The Audio Output API provides a set of functions to directly manage the system audio output devices.

Required Header

#include <audio_io.h>

Overview

The Audio Output API provides a set of functions to play recorded audio data from Audio Input.

Functions
int	audio_out_create_new (int sample_rate, audio_channel_e channel, audio_sample_type_e type, audio_out_h *output)
	Creates an audio device instance and returns an output handle to play PCM (pulse-code modulation) data.
int	audio_out_destroy (audio_out_h output)
	Releases the audio output handle, along with all its resources.
int	audio_out_set_sound_stream_info (audio_out_h output, sound_stream_info_h stream_info)
	Sets the sound stream information to the audio output.
int	audio_out_prepare (audio_out_h output)
	Prepares the audio output for playback, this must be called before audio_out_write().
int	audio_out_unprepare (audio_out_h output)
	Unprepares the audio output.
int	audio_out_pause (audio_out_h output)
	Pauses feeding of audio data to the device.
int	audio_out_resume (audio_out_h output)
	Resumes feeding of audio data to the device.
int	audio_out_drain (audio_out_h output)
	Drains buffered audio data from the output stream.
int	audio_out_flush (audio_out_h output)
	Flushes and discards buffered audio data from the output stream.
int	audio_out_write (audio_out_h output, void *buffer, unsigned int length)
	Starts writing the audio data to the device.
int	audio_out_get_buffer_size (audio_out_h output, int *size)
	Gets the size to be allocated for the audio output buffer.
int	audio_out_get_sample_rate (audio_out_h output, int *sample_rate)
	Gets the sample rate of the audio output data stream.
int	audio_out_get_channel (audio_out_h output, audio_channel_e *channel)
	Gets the channel type of the audio output data stream.
int	audio_out_get_sample_type (audio_out_h output, audio_sample_type_e *type)
	Gets the sample audio format of the audio output data stream.
int	audio_out_get_sound_type (audio_out_h output, sound_type_e *type)
	Gets the sound type supported by the audio output device.
int	audio_out_set_stream_cb (audio_out_h output, audio_out_stream_cb callback, void *user_data)
	Sets an asynchronous (event) callback function to handle playing PCM (pulse-code modulation) data.
int	audio_out_unset_stream_cb (audio_out_h output)
	Unregisters the callback function.
int	audio_out_set_state_changed_cb (audio_out_h output, audio_out_state_changed_cb callback, void *user_data)
	Sets the state changed callback function to the audio output handle.
int	audio_out_unset_state_changed_cb (audio_out_h output)
	Unregisters the state changed callback function of the audio output handle.
Typedefs
typedef struct audio_io_s *	audio_out_h
	The audio output handle.
typedef void(*	audio_out_stream_cb )(audio_out_h handle, size_t nbytes, void *user_data)
	Called when 'audio out' data can be written in asynchronous (event) mode.
typedef void(*	audio_out_state_changed_cb )(audio_out_h handle, audio_io_state_e previous, audio_io_state_e current, bool by_policy, void *user_data)
	Called when the state of audio output is changed.

Typedef Documentation

typedef struct audio_io_s* audio_out_h

The audio output handle.

Since :: 2.3

typedef void(* audio_out_state_changed_cb)(audio_out_h handle, audio_io_state_e previous, audio_io_state_e current, bool by_policy, void *user_data)

Called when the state of audio output is changed.

Since :: 3.0

Parameters:

[in]	handle	The handle of the audio output
[in]	previous	The previous state of the audio output
[in]	current	The current state of the audio output
[in]	by_policy	`true` if the state is changed by policy, otherwise `false` if the state is not changed by policy
[in]	user_data	The user data passed from the callback registration function

See also:: audio_out_set_state_changed_cb(); audio_out_unset_state_changed_cb()

typedef void(* audio_out_stream_cb)(audio_out_h handle, size_t nbytes, void *user_data)

Called when 'audio out' data can be written in asynchronous (event) mode.

Since :: 2.3

Remarks:: Use audio_out_write() to write pcm data inside this callback.

Parameters:

[in]	handle	The handle to the audio output
[in]	nbytes	The amount of 'audio in' data which can be written.
[in]	user_data	The user data passed from the callback registration function

See also:: audio_out_set_stream_cb()

Function Documentation

int audio_out_create_new	(	int	sample_rate,
		audio_channel_e	channel,
		audio_sample_type_e	type,
		audio_out_h *	output
	)

Creates an audio device instance and returns an output handle to play PCM (pulse-code modulation) data.

This function is used for audio output initialization.

Since :: 3.0

Remarks:: output must be released by audio_out_destroy(). It is recommended to call audio_out_set_sound_stream_info() after this API. Multi-channel playback is not supported.

Parameters:

[in]	sample_rate	The audio sample rate Before 5.0: 8000[Hz] ~ 48000[Hz] Since 5.0: 8000[Hz] ~ 192000[Hz]
[in]	channel	The audio channel type (mono or stereo)
[in]	type	The type of audio sample Before 5.0: 8 or 16-bit Since 5.0: 8, 16 or 24-bit Since 5.5: 8, 16, 24 or 32-bit
[out]	output	An audio output handle is created on success

Returns:: 0 on success, otherwise a negative error value

Return values:

AUDIO_IO_ERROR_NONE	Successful
AUDIO_IO_ERROR_INVALID_PARAMETER	Invalid parameter
AUDIO_IO_ERROR_OUT_OF_MEMORY	Out of memory
AUDIO_IO_ERROR_DEVICE_NOT_OPENED	Device not opened
AUDIO_IO_ERROR_SOUND_POLICY	Sound policy error

Postcondition:: The state will be AUDIO_IO_STATE_IDLE.
audio_out_set_sound_stream_info() is recommended to be called after this API.

See also:: audio_out_destroy()

int audio_out_destroy ( audio_out_h output )

Releases the audio output handle, along with all its resources.

Since :: 2.3

Parameters:

[in] output The handle to the audio output to destroy

Returns:: 0 on success, otherwise a negative error value

Return values:

AUDIO_IO_ERROR_NONE	Successful
AUDIO_IO_ERROR_INVALID_PARAMETER	Invalid parameter
AUDIO_IO_ERROR_OUT_OF_MEMORY	Out of memory
AUDIO_IO_ERROR_DEVICE_NOT_CLOSED	Device not closed

See also:: audio_out_create_new()

int audio_out_drain ( audio_out_h output )

Drains buffered audio data from the output stream.

This function waits until drains stream buffer completely. (e.g end of playback)

Since :: 2.4

Parameters:

[in] output The handle to the audio output

Returns:: 0 on success, otherwise a negative error value

Return values:

AUDIO_IO_ERROR_NONE	Successful
AUDIO_IO_ERROR_INVALID_PARAMETER	Invalid parameter
AUDIO_IO_ERROR_INVALID_STATE	Invalid state

Precondition:: The state should be AUDIO_IO_STATE_RUNNING or AUDIO_IO_STATE_PAUSED.

See also:: audio_out_flush()

int audio_out_flush ( audio_out_h output )

Flushes and discards buffered audio data from the output stream.

Since :: 2.4

Parameters:

[in] output The handle to the audio output

Returns:: 0 on success, otherwise a negative error value

Return values:

AUDIO_IO_ERROR_NONE	Successful
AUDIO_IO_ERROR_INVALID_PARAMETER	Invalid parameter
AUDIO_IO_ERROR_INVALID_STATE	Invalid state

Precondition:: The state should be AUDIO_IO_STATE_RUNNING or AUDIO_IO_STATE_PAUSED.

See also:: audio_out_drain()

int audio_out_get_buffer_size	(	audio_out_h	output,
		int *	size
	)

Gets the size to be allocated for the audio output buffer.

Since :: 2.3

Parameters:

[in]	output	The handle to the audio output
[out]	size	The suggested buffer size (in bytes, the maximum size is 1 MB)

Returns:: 0 on success, otherwise a negative error value

Return values:

AUDIO_IO_ERROR_NONE	Successful
AUDIO_IO_ERROR_INVALID_PARAMETER	Invalid parameter

See also:: audio_out_write()

int audio_out_get_channel	(	audio_out_h	output,
		audio_channel_e *	channel
	)

Gets the channel type of the audio output data stream.

Since :: 2.3

Parameters:

[in]	output	The handle to the audio output
[out]	channel	The audio channel type (mono or stereo)

Returns:: 0 on success, otherwise a negative error value

Return values:

AUDIO_IO_ERROR_NONE	Successful
AUDIO_IO_ERROR_INVALID_PARAMETER	Invalid parameter

int audio_out_get_sample_rate	(	audio_out_h	output,
		int *	sample_rate
	)

Gets the sample rate of the audio output data stream.

Since :: 2.3

Parameters:

[in]	output	The handle to the audio output
[out]	sample_rate	The audio sample rate Before 5.0: 8000[Hz] ~ 48000[Hz] Since 5.0: 8000[Hz] ~ 192000[Hz]

Returns:: 0 on success, otherwise a negative error value

Return values:

AUDIO_IO_ERROR_NONE	Successful
AUDIO_IO_ERROR_INVALID_PARAMETER	Invalid parameter

int audio_out_get_sample_type	(	audio_out_h	output,
		audio_sample_type_e *	type
	)

Gets the sample audio format of the audio output data stream.

Since :: 2.3

Parameters:

[in]	output	The handle to the audio output
[out]	type	The type of audio sample Before 5.0: 8 or 16-bit Since 5.0: 8, 16 or 24-bit Since 5.5: 8, 16, 24 or 32-bit

Returns:: 0 on success, otherwise a negative error value

Return values:

AUDIO_IO_ERROR_NONE	Successful
AUDIO_IO_ERROR_INVALID_PARAMETER	Invalid parameter

int audio_out_get_sound_type	(	audio_out_h	output,
		sound_type_e *	type
	)

Gets the sound type supported by the audio output device.

Since :: 2.3

Parameters:

[in]	output	The handle to the audio output
[out]	type	The sound type

Returns:: 0 on success, otherwise a negative error value

Return values:

AUDIO_IO_ERROR_NONE	Successful
AUDIO_IO_ERROR_INVALID_PARAMETER	Invalid parameter

int audio_out_pause ( audio_out_h output )

Pauses feeding of audio data to the device.

Since :: 3.0

Parameters:

[in] output The handle to the audio output

Returns:: 0 on success, otherwise a negative error value

Return values:

AUDIO_IO_ERROR_NONE	Successful
AUDIO_IO_ERROR_INVALID_PARAMETER	Invalid parameter
AUDIO_IO_ERROR_INVALID_STATE	Invalid state

Precondition:: The state should be AUDIO_IO_STATE_RUNNING.

Postcondition:: The state will be AUDIO_IO_STATE_PAUSED.

See also:: audio_out_resume()

int audio_out_prepare ( audio_out_h output )

Prepares the audio output for playback, this must be called before audio_out_write().

Since :: 2.3

Parameters:

[in] output The handle to the audio output

Returns:: 0 on success, otherwise a negative error value

Return values:

AUDIO_IO_ERROR_NONE	Successful
AUDIO_IO_ERROR_INVALID_PARAMETER	Invalid parameter
AUDIO_IO_ERROR_INVALID_STATE	Invalid state

Postcondition:: The state will be AUDIO_IO_STATE_RUNNING.

See also:: audio_out_unprepare()

int audio_out_resume ( audio_out_h output )

Resumes feeding of audio data to the device.

Since :: 3.0

Parameters:

[in] output The handle to the audio output

Returns:: 0 on success, otherwise a negative error value

Return values:

AUDIO_IO_ERROR_NONE	Successful
AUDIO_IO_ERROR_INVALID_PARAMETER	Invalid parameter
AUDIO_IO_ERROR_INVALID_STATE	Invalid state

Precondition:: The state should be AUDIO_IO_STATE_PAUSED.

Postcondition:: The state will be AUDIO_IO_STATE_RUNNING.

See also:: audio_out_pause()

int audio_out_set_sound_stream_info	(	audio_out_h	output,
		sound_stream_info_h	stream_info
	)

Sets the sound stream information to the audio output.

Since :: 3.0

Remarks:: The sound stream information includes audio routing and volume type. For more details, you can refer to Sound Manager Voice Recognition and Loopback stream types are not supported in this API.

Parameters:

[in]	output	The handle to the audio output
[in]	stream_info	The handle of stream information

Returns:: 0 on success, otherwise a negative error value

Return values:

AUDIO_IO_ERROR_NONE	Successful
AUDIO_IO_ERROR_INVALID_PARAMETER	Invalid parameter
AUDIO_IO_ERROR_NOT_SUPPORTED	Not supported
AUDIO_IO_ERROR_INVALID_STATE	Invalid state
AUDIO_IO_ERROR_NOT_SUPPORTED_TYPE	Not supported stream type

Precondition:: The state should be AUDIO_IO_STATE_IDLE.
Call audio_out_create_new() before calling this function.

Postcondition:: Call audio_out_prepare() after calling this function.

See also:: sound_manager_create_stream_information(); sound_manager_destroy_stream_information()

int audio_out_set_state_changed_cb	(	audio_out_h	output,
		audio_out_state_changed_cb	callback,
		void *	user_data
	)

Sets the state changed callback function to the audio output handle.

Since :: 3.0

Remarks:: input must be created using audio_out_create_new().

Parameters:

[in]	output	The audio output handle
[in]	callback	the state changed callback called when the state of the handle is changed (audio_out_state_changed_cb)
[in]	user_data	user data to be retrieved when callback is called

Returns:: 0 on success, otherwise a negative error value

Return values:

AUDIO_IO_ERROR_NONE	Successful
AUDIO_IO_ERROR_INVALID_PARAMETER	Invalid parameter

See also:: audio_out_unset_state_changed_cb()

int audio_out_set_stream_cb	(	audio_out_h	output,
		audio_out_stream_cb	callback,
		void *	user_data
	)

Sets an asynchronous (event) callback function to handle playing PCM (pulse-code modulation) data.

callback will be called when you can write a PCM data. It might cause dead lock if change the state of audio handle in callback. (ex: audio_out_destroy(), audio_out_prepare(), audio_out_unprepare()) Recommend to use as a VOIP only. Recommend not to hold callback too long.(it affects latency)

Since :: 2.3

Remarks:: output must be created using audio_out_create_new().

Parameters:

[in]	output	An audio output handle
[in]	callback	notify stream callback when user can write data (audio_out_stream_cb)
[in]	user_data	user data to be retrieved when callback is called

Returns:: 0 on success, otherwise a negative error value

Return values:

AUDIO_IO_ERROR_NONE	Successful
AUDIO_IO_ERROR_INVALID_PARAMETER	Invalid parameter
AUDIO_IO_ERROR_OUT_OF_MEMORY	Out of memory
AUDIO_IO_ERROR_DEVICE_NOT_OPENED	Device not opened
AUDIO_IO_ERROR_SOUND_POLICY	Sound policy error

See also:: audio_out_unset_stream_cb()

int audio_out_unprepare ( audio_out_h output )

Unprepares the audio output.

Since :: 2.3

Parameters:

[in] output The handle to the audio output

Returns:: 0 on success, otherwise a negative error value

Return values:

AUDIO_IO_ERROR_NONE	Successful
AUDIO_IO_ERROR_INVALID_PARAMETER	Invalid parameter
AUDIO_IO_ERROR_INVALID_STATE	Invalid state

Postcondition:: The state will be AUDIO_IO_STATE_IDLE.

See also:: audio_out_prepare()

int audio_out_unset_state_changed_cb ( audio_out_h output )

Unregisters the state changed callback function of the audio output handle.

Since :: 3.0

Parameters:

[in] output The handle to the audio output

Returns:: 0 on success, otherwise a negative error value

Return values:

AUDIO_IO_ERROR_NONE	Successful
AUDIO_IO_ERROR_INVALID_PARAMETER	Invalid parameter

See also:: audio_out_set_state_changed_cb()

int audio_out_unset_stream_cb ( audio_out_h output )

Unregisters the callback function.

Since :: 2.3

Parameters:

[in] output The handle to the audio output

Returns:: 0 on success, otherwise a negative error value

Return values:

AUDIO_IO_ERROR_NONE	Successful
AUDIO_IO_ERROR_INVALID_PARAMETER	Invalid parameter
AUDIO_IO_ERROR_INVALID_OPERATION	Invalid operation

See also:: audio_out_set_stream_cb()

int audio_out_write	(	audio_out_h	output,
		void *	buffer,
		unsigned int	length
	)

Starts writing the audio data to the device.

Since :: 2.3

Parameters:

[in]	output	The handle to the audio output
[in,out]	buffer	The PCM buffer address
[in]	length	The length of the PCM buffer (in bytes)

Returns:: The written data size on success, otherwise a negative error value

Return values:

AUDIO_IO_ERROR_INVALID_PARAMETER	Invalid parameter
AUDIO_IO_ERROR_INVALID_BUFFER	Invalid buffer pointer
AUDIO_IO_ERROR_SOUND_POLICY	Sound policy error
AUDIO_IO_ERROR_INVALID_STATE	Invalid state

Precondition:: The state should be AUDIO_IO_STATE_RUNNING.

Required Header

Overview

Functions

Typedefs

Typedef Documentation

Function Documentation