Stream

PCM playback for music and video audio. More...

Functions
int	audio_stream_start (const audio_stream_format_t *format)
int	audio_stream_end (void)
int	audio_stream_queue_pcm (const void *pcm, int32_t byte_count)
int	audio_stream_wait_until_writable (int32_t byte_count, int32_t timeout_ms)
int	audio_stream_get_queued_bytes (void)
int	audio_stream_get_free_bytes (void)
int	audio_stream_stop_and_clear (void)
int	audio_stream_pause (void)
int	audio_stream_resume (void)
int	audio_stream_set_volume (int volume_percent)
int	audio_stream_set_low_data_callback (int32_t threshold_bytes, audio_low_data_fn callback, void *user)

Detailed Description

PCM playback for music and video audio.

One stream per context. Data is queued in the format given to audio_stream_start() and the library converts it to the 48 kHz stereo 16-bit layout the SPU2 plays. All byte counts are in the source format. A stream that runs out of data plays silence and continues when more arrives; that is not an error.

Function Documentation

audio_stream_end()

int audio_stream_end

(

void

)

Ends the stream and discards queued data. Threads waiting for space return -AUDIO_ERR_INTERRUPTED.

Returns

AUDIO_OK, also when no stream was started.

audio_stream_get_free_bytes()

int audio_stream_get_free_bytes

(

void

)

Bytes audio_stream_queue_pcm() accepts right now, rounded down.

Returns

The count, or -AUDIO_ERR_STREAM_NOT_STARTED.

audio_stream_get_queued_bytes()

int audio_stream_get_queued_bytes

(

void

)

Bytes queued and not yet played, rounded up.

Returns

The count, or -AUDIO_ERR_STREAM_NOT_STARTED.

audio_stream_pause()

int audio_stream_pause

(

void

)

Silences the output and keeps the queued data. Queuing continues until the stream is full.

Returns

AUDIO_OK, or -AUDIO_ERR_STREAM_NOT_STARTED.

audio_stream_queue_pcm()

int audio_stream_queue_pcm	(	const void *	pcm,
		int32_t	byte_count )

Adds PCM data to the stream. Copies the data before returning and never waits for space.

Parameters

pcm	Data in the stream format. No alignment needed.
byte_count	Bytes to queue. A trailing partial frame is not accepted.

Returns

Bytes accepted, from 0 up to byte_count (less than byte_count when the stream is full), or -AUDIO_ERR_STREAM_NOT_STARTED, -AUDIO_ERR_INVALID_ARGUMENT, -AUDIO_ERR_NOT_INITIALIZED.

Note

After audio_stream_wait_until_writable() returned AUDIO_OK for n bytes, queuing up to n bytes from the same thread is accepted in full.

audio_stream_resume()

int audio_stream_resume

(

void

)

Continues from where audio_stream_pause() stopped.

Returns

AUDIO_OK, or -AUDIO_ERR_STREAM_NOT_STARTED.

audio_stream_set_low_data_callback()

int audio_stream_set_low_data_callback	(	int32_t	threshold_bytes,
		audio_low_data_fn	callback,
		void *	user )

Registers a function called when the queued data falls to a threshold.

The callback runs on a thread owned by the library, once each time the queue drains to the threshold. It runs again only after the level has risen above the threshold. Registering does not call it for a level that is already low. The callback may queue data; it must not end or restart the stream. The threshold is kept when the stream is restarted.

Parameters

threshold_bytes	0 up to the capacity of the stream, in source bytes; 0 calls back only when empty.
callback	The function, or NULL to unregister.
user	Passed to the callback unchanged.

Returns

AUDIO_OK, -AUDIO_ERR_STREAM_NOT_STARTED, -AUDIO_ERR_INVALID_ARGUMENT or -AUDIO_ERR_NOT_INITIALIZED.

audio_stream_set_volume()

int audio_stream_set_volume

(

int

volume_percent

)

Volume of the stream alone. It persists across restarts and works before the stream is started.

Parameters

volume_percent

0 to 100.

Returns

AUDIO_OK, -AUDIO_ERR_INVALID_ARGUMENT or -AUDIO_ERR_NOT_INITIALIZED.

audio_stream_start()

int audio_stream_start

(

const audio_stream_format_t *

format

)

Starts a stream, or restarts it with a new format and discards queued data.

Parameters

format

Sample rate 8000-48000 Hz, 8 or 16 bits, 1 or 2 channels.

Returns

AUDIO_OK, -AUDIO_ERR_FORMAT_NOT_SUPPORTED, -AUDIO_ERR_INVALID_ARGUMENT or -AUDIO_ERR_NOT_INITIALIZED.

Note

Keeps the stream volume. The stream starts in the playing state.

audio_stream_stop_and_clear()

int audio_stream_stop_and_clear

(

void

)

Stops playback and discards queued data. The stream stays started with its format, in the playing state.

Returns

AUDIO_OK, also when no stream was started.

audio_stream_wait_until_writable()

int audio_stream_wait_until_writable	(	int32_t	byte_count,
		int32_t	timeout_ms )

Blocks until at least byte_count bytes can be queued.

Parameters

byte_count	1 up to the capacity of the stream in source bytes.
timeout_ms	Milliseconds to wait: 0 polls once, -1 waits forever.

Returns

AUDIO_OK, -AUDIO_ERR_TIMEOUT, -AUDIO_ERR_STREAM_PAUSED (space is short and the stream is paused), -AUDIO_ERR_INTERRUPTED (the stream ended or the audio system shut down while waiting), -AUDIO_ERR_INVALID_ARGUMENT (byte_count larger than the stream holds), -AUDIO_ERR_STREAM_NOT_STARTED.

Note

Other threads can keep using the library while one waits here.