Sounds, channels and the stream

The SPU2 plays two kinds of audio, and the library keeps them apart.

A sound is ADPCM data kept in SPU2 memory. audio_sound_load_adpcm() and audio_sound_load_apcm() upload it and return a handle. A sound is loaded once and can play on several channels at once.
A channel is a mixer strip, numbered 0 to 23. audio_channel_play_sound() starts a sound on a channel.
The stream is PCM data that an application feeds while it plays, such as music or video audio. There is one stream per context, and it plays alongside the channels.

Channel settings

A channel keeps its volume, pan and pitch until they are changed. They persist from one sound to the next, after a sound ends, and can be set before the first sound plays. A sound played with audio_channel_play_sound() uses the settings the channel has.

audio_play_sound() picks the first idle channel itself. It resets that channel to volume 100, centered, normal pitch first, so a one-shot sound does not inherit what an earlier sound left there. An application that keeps settings on channels should play on those channels with audio_channel_play_sound().

Playing on a channel that is busy replaces the sound there at once.

Commands and ordering

The calls that play, stop or change a channel return as soon as the command is sent. The driver runs them in the order they were sent, so a call that asks for a result, such as audio_channel_is_playing(), sees the effect of the commands before it. The library checks what can fail (channel range, value ranges, and that a sound handle is live) before sending.

The stream

audio_stream_start() sets the format: 8000 to 48000 Hz, 8 or 16 bits, mono or stereo. The library converts the data to the 48 kHz stereo 16-bit layout the SPU2 input plays. All byte counts in the stream functions are in the format the application gave.

audio_stream_queue_pcm() copies data and returns how much it accepted; it never waits. Two ways to feed it at the right pace:

Call audio_stream_wait_until_writable() for the size of the next chunk, then queue that chunk. The wait guarantees the space.
Register audio_stream_set_low_data_callback(). The library calls it on its own thread when the queue drains to a threshold; the callback queues the next data.

A stream that runs out of data plays silence until more is queued. Pausing keeps queued data.

Effects

The SPU2 has a reverb and delay unit. audio_effect_set_preset() selects one of ten presets, and nothing is heard until a source is sent to it with audio_channel_set_effect_send() or audio_stream_set_effect_send(). See Effects.

Threads

All functions can be called from any thread. A thread waiting in audio_stream_wait_until_writable() does not stop other threads from using the library. Stop the threads that use the library before calling audio_shutdown(); waiters return -AUDIO_ERR_INTERRUPTED.

Units

Quantity	Unit	Range
Volume	percent	0 to 100
Pan	balance	-100 (left), 0 (center), 100 (right)
Pitch	ratio of the sound's own rate	0.0625 to 4.0
Channel	number	0 to 23
Effect depth	percent	0 to 100
Effect delay, feedback	steps	0 to 255
Stream data	bytes in the stream format
Timeouts	milliseconds	0 polls once, -1 waits forever

Errors

A function returns a value of 0 or more on success, or the negated error code on failure. See Error codes. audio_get_error_message() gives text for a code.