Simple API

Overview

The simple API is designed for applications with very basic sound playback or capture needs. It can only support a single stream per connection and has no handling of complex features like events, channel mappings and volume control. It is, however, very simple to use and quite sufficent for many programs.

Connecting

The first step before using the sound system is to connect to the server. This is normally done this way:

 pa_simple *s;
 pa_sample_spec ss;

 ss.format = PA_SAMPLE_S16NE;
 ss.channels = 2;
 ss.rate = 44100;

 s = pa_simple_new(NULL,               // Use the default server.
                   "Fooapp",           // Our application's name.
                   PA_STREAM_PLAYBACK,
                   NULL,               // Use the default device.
                   "Music",            // Description of our stream.
                   &ss,                // Our sample format.
                   NULL,               // Use default channel map
                   NULL,               // Use default buffering attributes.
                   NULL,               // Ignore error code.
                   );

At this point a connected object is returned, or NULL if there was a problem connecting.

Transferring Data

Once the connection is established to the server, data can start flowing. Using the connection is very similar to the normal read() and write() system calls. The main difference is that they're call pa_simple_read() and pa_simple_write(). Note that these operations always block.

Control

If a playback stream is used then a few other operations are available:

• pa_simple_drain() - Will wait for all sent data to finish playing.
• pa_simple_flush() - Will throw away all data currently in buffers.
• pa_simple_get_playback_latency() - Will return the total latency of the playback pipeline.

Cleanup

Once playback or capture is complete, the connection should be closed and resources freed. This is done through:

 pa_simple_free(s);