Re: new PortAudio API overview documentation (DRAFT)
Bjorn Roche <bjorn <at> xowave.com>
2010-11-05 00:39:35 GMT
Ross! This looks terrific. The figure is a bit like something I tried
to make a while ago and forgot about. Your figure is awesomer than
what I was working on. I read it and have some minor corrections I am
sending off list. I think it might be useful to add an FAQ section
here even if there are FAQs elsewhere on the site just to cover the
really top questions that get asked when someone is a total noob.
Here's what came immediately to my mind.
What about reading and writing audio files? PortAudio doesn't do that.
If you want to read and write files, one popular option is
libSoundFile; however, there are many, many options for reading and
writing sound files depending on your OS, licensing and other
Is PortAudio thread-safe? No. It is up to you to figure out how to
ensure that PortAudio is used in a thread-safe manner. Above-
beyond this, you must ensure that you do not perform certain
operations such as mallocs, waiting on mutexs, or performing I/O while
processing audio, as this may result in both audio quality problems,
and, on some platforms, even more severe issues.
(this is mentioned in the callback section, but it's worth repeating.)
What about MIDI? PortAudio does not handle MIDI. For this, you may
want to consider the PortMIDI library.
What about volume/pan/EQ controls on my sound device? For controlling
the input and output volumes on your sound devices, you may want to
use the PortMixer library.
What about sound processing and effects? You are talking about DSP, or
Digital Signal Processing. That's cool, but PortAudio won't do it for
you. You might want to ask on the Music-DSP list.
I want the sound that's coming out of the computer to be an input into
my software! Unfortunately, this isn't part of most operating system's
Audio I/O System, so it's not something you can do with PortAudio.
On Nov 4, 2010, at 6:31 PM, Ross Bencina wrote:
> Hi Everyone
> A little while ago someone mentioned we needed an up-to-date
> overview document for the PortAudio API. I've always thought there
> should be some kind of architectural overview on the doxygen main
> page here:
> Since I've been slinging mud about poor documentation elsewhere
> lately I thought I'd better clean up my act a bit, so here's a draft
> of a new API overview for the PortAudio doxygen main page. It's a
> pdf at the moment because that was easiest for me to share but I
> intend to merge the final version into the doxygen documentation so
> it ends up with the rest of the API docs. As I note in the pdf, in
> the final version all function and type names will be hyperlinked to
> the appropriate entry in the doxygen reference.
> Here's the draft:
> It's a bit different from the ICMC paper and the Audio Anecdotes
> book chapter we've written before in that it doesn't include a
> tutorial or discussion of internal implementation details. This is
> intended as a top-down overview or map, with hyperlinks to all the
> relevant API functions and data types -- kind of a way in to the
> existing API documentation. There's probably a room for a PortAudio
> Internals document too, and of course we already have tutorials
> Please tell me what you think. All corrections/notes/omissions etc
> welcome. It's not as easy to read as the Audio Anecdotes chapter on
> the same topic -- if there's an experienced editor/tech writer out
> there who would be willing to help me smooth it out please get in
> I'm considering doing a UML diagram of the whole public API.. it's a
> lot of work and I'm not sure it's needed but I'd be interested to
> hear what people think.
> Portaudio mailing list
> Portaudio <at> music.columbia.edu