Author: Phil Burk
Description: Tutorial for PortAudio, a cross platform, open-source, audio I/O library.It provides a very simple API for recording and/or playing sound using a simple callback function.
Keywords: audio, tutorial, library, portable, open-source, DirectSound,sound, music, JSyn, synthesis,

# PortAudio Tutorial

## Blocking Read/Write Functions

> [Note: These functions are not part of the official PortAudio API. They are simply built on top of PortAudio as an extra utility. Also note that they are under evaluation and their definition may change.]

> There are two fundamentally different ways to design an audio API. One is to use callback functions the way we have already shown. The callback function operates under an interrupt or background thread This leaves the foreground application free to do other things while the audio just runs in the background. But this can sometimes be awkward.

> So we have provided an alternative technique that lets a program generate audio in the foreground and then just write it to the audio stream as if it was a file. If there is not enough room in the audio buffer for more data, then the write function will just block until more room is available. This can make it very easy to write an audio example. To use this tool, you must add the files "pablio/pablio.c" and "pablio/ringbuffer.c" to your project. You must also:

> >     #include "pablio.h"

> Here is a short excerpt of a program that opens a stream for input and output. It then read a pair of samples at a time from input, and writes them to output, in a loop. The complete example can be found in "pablio/test_rw.c".

> >         SAMPLE          samples[2];
> >         PaError         err;
> >         PABLIO_Stream  *aStream;

> >     /* Open simplified blocking I/O layer on top of PortAudio. */
> >         err = OpenAudioStream( &rwbl, SAMPLE_RATE, paFloat32,
> >                              (PABLIO_READ_WRITE | PABLIO_STEREO) );
> >         if( err != paNoError ) goto error;

> >     /* Process samples in the foreground. */
> >         for( i=0; i<(NUM_SECONDS * SAMPLE_RATE); i++ )
> >         {
> >         /* Read one frame of data into sample array from audio input. */
> >             ReadAudioStream( aStream, samples, 1 );
> >         /*
> >         ** At this point you could process the data in samples[0] and samples[1],
> >         ** and write the result back to the same samples array.
> >         */
> >         /* Write that same frame of data to output. */
> >             WriteAudioStream( aStream, samples, 1 );
> >         }

> >         CloseAudioStream( aStream );

home | contents | previous | next