Documentation Request

Documentation Request

[Carl Canuck]

Hello,

I've recently begun the work of porting a Windows application to
LInux/ALSA.  I think ALSA and it's drivers are quite good, but the
documentation and example code are terribly lacking, especially for one of
the most important use-cases of all:  the full on digital audio workstation.

I humbly request that a full_duplex_audio_with_midi.c file be added to the
example code with the following parameters:

1.  Full duplex audio, just simply memcpy'ing the input to the output would
suffice
2.  Accepts MIDI input;  it doesn't have to do anything useful with the
data, just printing the event parameters to stdout would suffice.
3.  At run time, the application lists all available audio devices and
allows the user to select the device, then make settings such as buffer
size, sample rate, bit depth and whether to use mmap based on the
capabilities of the chosen device
4.  At run time, allows optionally selecting a MIDI device.
5.  Copious code comments that makes no assumption that the person reading
knows anything about the ALSA API or it's constructs, invocations and
methodologies.

This could either be an interactive CLI application written in C, or even a
full GUI application using Qt or GTK.  This could then be used as a shell
for writing more complex applications, instead of each developer having to
reinvent the wheel by trying to figure out how to combine about 4 or so of
the other example applications into a single app.

/Carl

Re: Documentation Request

[Eliot Blennerhassett]

On 04/09/13 12:32, Carl Canuck wrote:
> especially for one of
> the most important use-cases of all:  the full on digital audio workstation.

The stock answer for this use case is
"Don't use ALSA directly; use JACK" http://jackaudio.org/

Re: Documentation Request

[Carl Canuck]

Hi Eliot,

Thanks for your response, but I think that is a very poor solution.  Jack
is problematic on many configurations, and I have no intention of modifying
this app to rely on Jack Transport or any Jack session manager in order to
play nicely with the rest of the Jack ecosystem, nor do Jack's features add
value to my application.  Therefore, it makes little sense to use Jack or
accept it's additional bugs and CPU overhead, no more than it makes sense
to use Pulseaudio for high performance, low latency audio applications,
adding another layer over ALSA can only result in more bugs and more
overhead, not less.

Surely an experienced core ALSA developer could create such a demo of how
the API is meant to be used in less than an hour.  This would save numerous
ALSA-curious developers like myself countless hours of reverse engineering
other applications and scouring alsa-devel mailing list posts attempting to
understand how ALSA is meant to be used.  I understand that writing
documentation isn't fun, but after my first 2 weeks of trying I have to
believe that countless developers have probably given up on ALSA (and Linux
by extension) due to the cryptic documentation and lack of simplest-case
example code.  With the example I proposed, I could've been productive from
day one.

Thanks,
Carl


On Tue, Sep 3, 2013 at 8:58 PM, Eliot Blennerhassett <
eliot@blennerhassett.gen.nz> wrote:

> On 04/09/13 12:32, Carl Canuck wrote:
> > especially for one of
> > the most important use-cases of all:  the full on digital audio
> workstation.
>
> The stock answer for this use case is
> "Don't use ALSA directly; use JACK" http://jackaudio.org/
>
>
>
>

Re: Documentation Request

[Carl Canuck]

Sorry, I only sent that last reply to Grant, the
reply-to-anybody-but-sender options are a little counter-intuitive in Gmail.


On Tue, Sep 3, 2013 at 11:10 PM, Carl Canuck <carl.canuck.official@gmail.com
> wrote:

> Hi Grant,
>
> I have in fact spent a little time with Jack and even conjured up a
> working prototype using Jack audio with ALSA MIDI (that will never see the
> light of day).  However, you're ignoring the fact that:
>
> 1.  Some people don't like having 20 separate audio applications running
> and having to save all of their states individually
> 2.  If you believe that any existing Jack session manager is a stable,
> reliable application that adequately solves problem #1, then it's obvious
> that you've not spent much time with Jack session managers
> 3.  Jack is something like 15 years old now, and they still haven't even
> managed to solve #1 and #2 yet, among other long-standing issues?
> 4.  With points #1, #2 and #3 all being common knowledge, why should I put
> my faith in Jack competently wrapping ALSA for me instead of taking matters
> into my own hands and going straight to ALSA?
> 5.  If you visit Windows/Mac audio forums, there are legions of people who
> will tell you they tried Linux once, found Jack to be buggy and terrible in
> general, never intend to try Linux again.  In fact, you can register a user
> name on any non-Linux music forum, and ask "i'm thinking of trying Linux
> for audio, thoughts?", and people will say exactly the things I described
> to you, not because they have any unfounded bias against Linux or Jack, but
> because that was truly their experience.
> 6.  Jack's configuration settings and error logging are atrocious, it is
> far too often excessively difficult to understand why Jack won't start and
> how to fix it.
> 7.  Is it really so unreasonable to ask for a basic example of a common
> use-case for ALSA without being told that I should just abandon the quest
> for that knowledge and put my faith in the Jack developers?  Should
> deciphering the intended use of any API be an exercise left to the would-be
> developer?
>
> If you like Jack, then by all means use it, but it's not ideal for my
> use-case, and I won't be spending any more time evaluating it until the
> Jack developers address these long-standing issues.
>
> Carl
>
> <http://users.suse.com/~mana/alsa090_howto.html>


Also, I have in fact seen the link you provided Grant, but that once again
is only bits and pieces of the use-case.  I'd like to know that I'm using
ALSA as it's creators intended, rather than stringing together bits and
pieces and hoping that I'm doing it right.

Regards,
Carl

Re: Documentation Request

[Felix Homann]

Am 04.09.2013 05:16 schrieb "Carl Canuck" <carl.canuck.official@gmail.com>:
>
> > 7.  Is it really so unreasonable to ask for a basic example of a common
> > use-case for ALSA without being told that I should just abandon the
quest
> > for that knowledge and put my faith in the Jack developers?

It is unreasonable to think of *your* use case as a *common* use case for
ALSA. It is a common use-case for Jack. I don't know of any program doing
all of this on plain ALSA grounds (maybe except for Pd which ironically
doesn't work for me with the ALSA driver but only with Jack.)
Moreover, using Jack is (almost) the only reliable way to get full duplex
audio on some implicit feedback USB interfaces because it implicitly works
around a current (still?) limitation of the ALSA driver.

Regards, Felix

Re: Documentation Request

[Clemens Ladisch]

Carl Canuck wrote:
> Surely

:-/

> an experienced core ALSA developer

Do you know how many there are?  And how much time they have?

> could create such a demo in less than an hour.

So if I'd set a stopwatch for one hour, and stopped typing then, you
would be willing to accept the result?  ;-)


Regards,
Clemens

Re: Documentation Request

[Florian Faber]

Carl,

> Thanks for your response, but I think that is a very poor solution. [ignorant blah]
>
> Surely an experienced core ALSA developer could create such a demo [more blah]

How about: You write the documentation, given your 'fresh' experience
with ALSA to help others in your situation.

Or even better: Accept recommendations from other developers and use
jack. You would have finished after half an hour and your application
would cooperate with all other audio applications.

All you have now is two wasted weeks of your life span and a
non-cooperative application. And other new ALSA users are still in the
same situation as you were.


Flo
-- 
Machines can do the work, so people have time to think.
public key 8D073185          x-hkp://subkeys.pgp.net

Re: Documentation Request

[Carl Canuck]

> Thanks for your response, but I think that is a very poor solution.
> [ignorant blah]
>
>
Ignorant?  You do realize that Jack has captured the hearts and minds of
exactly zero world renowned audio professionals, despite being
"professional grade" according to it's developers?  Do you think that could
possibly be a problem with Jack, or did everybody just not give it enough
of a chance?



> How about: You write the documentation, given your 'fresh' experience
> with ALSA to help others in your situation.
>
>
Why the hell should somebody with no experience programming with ALSA
attempt to reverse-engineer, document and create example code when the only
references available are some horribly inadequate API docs and a few
kernels of wisdom scattered over years of mailing lists?  I think instead
I'll just abandon my attempts to port anything to Linux if the attitude of
the ALSA community is that the combined use of ALSA audio and MIDI with
proper device configuration options is supposed to be a big secret that you
all are too busy to share.

Now get back to writing drivers for the latest ARM SOC, sorry to have
bothered you.

Re: Documentation Request

[Felix Homann]

2013/9/4 Carl Canuck <carl.canuck.official@gmail.com>

>
> Ignorant?  You do realize that Jack has captured the hearts and minds of
> exactly zero world renowned audio professionals, despite being
> "professional grade" according to it's developers?  Do you think that could
> possibly be a problem with Jack, or did everybody just not give it enough
> of a chance?
>


If you insist on using pure ALSA: Read the docs that Grant pointed you to.
Everything you need is there, IMO. Otherwise, using portaudio/portmidi can
help you in porting your Windows application to Linux. The tool of choice
though is: Err, you just don't want to hear that again...



> Why the hell should somebody with no experience programming with ALSA
> attempt to reverse-engineer, document and create example code when the only
> references available are some horribly inadequate API docs and a few
> kernels of wisdom scattered over years of mailing lists?


Ever so often, once you figured something out you can't see your initial
problems in understanding anymore. That's why it is a good idea to write
about such things as long as you still see your problems.

BTW, I can't see anything missing in the example code that would be
relevant to you. So what's wrong with it? What's wrong with the API docs?
It's a bit rough, sure. But it's your decision to go the hard way and not
use the adequate tool for your problem.



> I think instead
> I'll just abandon my attempts to port anything to Linux if the attitude of
> the ALSA community is that the combined use of ALSA audio and MIDI with
> proper device configuration options is supposed to be a big secret that you
> all are too busy to share.


You asked for advice. You got advice. You don't like the advice. You
complain. Hmmm. Doesn't sound right to me.

Re: Documentation Request

[Clemens Ladisch]

Carl Canuck wrote:
> if the attitude of the ALSA community is

There is no individual that has the power to speak for the community.


Regards,
Clemens

Re: Documentation Request

[Carl Canuck]

Continue the conversation if you choose, but I am searching for the
unsubscribe button as we speak.

I have no incentive to port anything to Linux other than some general
feelings of goodwill towards the open source community.  If you truly feel
that writing a kludgy API with poor documentation and example code that's
only meant to be wrapped into other APIs developed by those brave souls
willing to take the time to reverse engineer it all is good business, then
by all means keep on doing what you're doing.   It is my personal
conviction that I would much rather retain full control of my application
by communicating directly with ALSA rather than delegating control to Jack
just to ease the pain of deciphering your poor documentation.

I am truly sorry for taking time away from your driver development, please
continue with your work and let this conversation die in peace, I will not
be participating in this conversation or your mailing list any further.


On Wed, Sep 4, 2013 at 10:05 AM, Clemens Ladisch <clemens@ladisch.de> wrote:

> Carl Canuck wrote:
> > if the attitude of the ALSA community is
>
> There is no individual that has the power to speak for the community.
>
>
> Regards,
> Clemens
> _______________________________________________
> Alsa-devel mailing list
> Alsa-devel@alsa-project.org
> http://mailman.alsa-project.org/mailman/listinfo/alsa-devel
>

Re: Documentation Request

[Joël Krähemann]

Hi

Assumed it's really an open source project why not looking at code from
other projects. There are many applications that do midi e.g. lmms,
rosegarden and probably many more.

http://code.ohloh.net and http://www.codase.com is providing good code
search engines.

So let me help you. Pick a function you're interested in and just copy
it to the search field.

And don't get being disappointed of frustrated open source developers.

have a nice day
Joël

On Wed, 2013-09-04 at 10:30 -0400, Carl Canuck wrote:
> Continue the conversation if you choose, but I am searching for the
> unsubscribe button as we speak.
> 
> I have no incentive to port anything to Linux other than some general
> feelings of goodwill towards the open source community.  If you truly feel
> that writing a kludgy API with poor documentation and example code that's
> only meant to be wrapped into other APIs developed by those brave souls
> willing to take the time to reverse engineer it all is good business, then
> by all means keep on doing what you're doing.   It is my personal
> conviction that I would much rather retain full control of my application
> by communicating directly with ALSA rather than delegating control to Jack
> just to ease the pain of deciphering your poor documentation.
> 
> I am truly sorry for taking time away from your driver development, please
> continue with your work and let this conversation die in peace, I will not
> be participating in this conversation or your mailing list any further.
> 
> 
> On Wed, Sep 4, 2013 at 10:05 AM, Clemens Ladisch <clemens@ladisch.de> wrote:
> 
> > Carl Canuck wrote:
> > > if the attitude of the ALSA community is
> >
> > There is no individual that has the power to speak for the community.
> >
> >
> > Regards,
> > Clemens
> > _______________________________________________
> > Alsa-devel mailing list
> > Alsa-devel@alsa-project.org
> > http://mailman.alsa-project.org/mailman/listinfo/alsa-devel
> >
> _______________________________________________
> Alsa-devel mailing list
> Alsa-devel@alsa-project.org
> http://mailman.alsa-project.org/mailman/listinfo/alsa-devel

Re: Documentation Request

[Keith A. Milner]

On Wednesday 04 Sep 2013 09:20:23 Carl Canuck wrote:
> > Thanks for your response, but I think that is a very poor solution.
> > [ignorant blah]
> 
> Ignorant?  You do realize that Jack has captured the hearts and minds of
> exactly zero world renowned audio professionals, despite being
> "professional grade" according to it's developers? 
>

You do realise that native ALSA music production apps have captured an even 
smaller number of those hearts and minds...

And of the many people who do use Linux for music production (professional or 
otherwise), native ALSA apps have captured very close to zero percent of their 
hearts and minds.

Amongst the Linux audio production market Jack is, far and away, the most 
popular approach both amongst app developers and users. It is the de-facto 
standard. Part of this is because Jack enables your app to work well with 
others, whereas ALSA on it's own does not.

If you want people in this market to use your app, then you shouldn't even be 
considering not using Jack.

Unless, of course, you are trying to  consign your app to obscurity to give 
you another reason to denigrate Linux and it's users.

> Do you think that could
> possibly be a problem with Jack, or did everybody just not give it enough
> of a chance?

Have you considered that it could be other factors, such as Linux only having 
a few percent of the desktop market (where audio production sits) or that none 
of the "brand name" software vendors produce software for it, or that people 
in that industry are not generally very computer-literate and may not have 
even heard of Linux, yet alone know you could produce music on it or are 
willing to take the risk on using a new, unknown platform.

All of the above are good reasons. I have worked with ALSA and Jack for 
several years and you are the only person in this time I have heard suggest 
the root cause for lack of Linux penetration in the audio production market is 
due to Jack. It's a crazy suggestion and, unless you have some firm evidence 
backing this up, ignorance really is the only explanation for such a 
suggestion.

In looking to write a native ALSA music production app you were on completely 
the wrong path. This community has, generously, offered you advice to steer you 
onto the correct path. I recommend you swallow your pride, and follow this 
sage advice.

Cheers,

Keith