PulseAudio 16.1

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 support for handling of complex features like events, channel mappings and volume control. It is, however, very simple to use and quite sufficient 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.
);
PA_STREAM_PLAYBACK
@ PA_STREAM_PLAYBACK
Playback stream.
Definition: def.h:160
PA_SAMPLE_S16NE
#define PA_SAMPLE_S16NE
Signed 16 Bit PCM, native endian.
Definition: sample.h:209
pa_simple_new
pa_simple * pa_simple_new(const char *server, const char *name, pa_stream_direction_t dir, const char *dev, const char *stream_name, const pa_sample_spec *ss, const pa_channel_map *map, const pa_buffer_attr *attr, int *error)
Create a new connection to the server.
pa_sample_spec
A sample format and attribute specification.
Definition: sample.h:252
pa_sample_spec::rate
uint32_t rate
The sample rate.
Definition: sample.h:256
pa_sample_spec::channels
uint8_t channels
Audio channels.
Definition: sample.h:259
pa_sample_spec::format
pa_sample_format_t format
The sample format.
Definition: sample.h:253
pa_simple
An opaque simple connection object.

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 called pa_simple_read() and pa_simple_write(). Note that these operations always block.

# Control

- pa_simple_get_latency() - Will return the total latency of the playback or record pipeline, respectively.
- pa_simple_flush() - Will throw away all data currently in buffers.

If a playback stream is used then the following operation is available:

- pa_simple_drain() - Will wait for all sent data to finish playing.

# Cleanup

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

pa_simple_free(s);
pa_simple_free
void pa_simple_free(pa_simple *s)
Close and free the connection to the server.