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 (int sample_rate, audio_channel_e channel, audio_sample_type_e type, sound_type_e sound_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_prepare (audio_out_h output)
	Prepares playing audio output, this must be called before audio_out_write().
int	audio_out_unprepare (audio_out_h output)
	Unprepares playing audio output.
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 (8-bit or 16-bit) 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_interrupted_cb (audio_out_h output, audio_io_interrupted_cb callback, void *user_data)
	Registers a callback function to be invoked when the audio output handle is interrupted or the interrupt is completed.
int	audio_out_unset_interrupted_cb (audio_out_h output)
	Unregisters the callback function.
int	audio_out_ignore_session (audio_out_h output)
	Ignores session for output.
int	audio_out_set_stream_cb (audio_out_h output, audio_out_stream_cb callback, void *userdata)
	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.
Typedefs
typedef struct audio_out_s *	audio_out_h
	The audio output handle.
typedef void(*	audio_out_stream_cb )(audio_out_h handle, size_t nbytes, void *userdata)
	Called when audio out data can be written in asynchronous(event) mode.

Typedef Documentation

typedef struct audio_out_s* audio_out_h

The audio output handle.

Since :: 2.3.1

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

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

Since :: 2.3.1

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]	userdata	The user data passed from the callback registration function

See also:: audio_out_set_stream_cb()

Function Documentation

int audio_out_create	(	int	sample_rate,
		audio_channel_e	channel,
		audio_sample_type_e	type,
		sound_type_e	sound_type,
		audio_out_h *	output
	)

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

Since :: 2.3.1

This function is used for audio output initialization.

Remarks:: output must be released by audio_out_destroy().

Parameters:

[in]	sample_rate	The audio sample rate in 8000[Hz] ~ 48000[Hz]
[in]	channel	The audio channel type (mono or stereo)
[in]	type	The type of audio sample (8- or 16-bit)
[in]	sound_type	The type of sound (sound_type_e)
[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

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.1

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()

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.1

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.

The audio channel type defines whether the audio is mono or stereo.

Since :: 2.3.1

Parameters:

[in]	output	The handle to the audio output
[out]	channel	The audio channel 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_get_sample_rate	(	audio_out_h	output,
		int *	sample_rate
	)

Gets the sample rate of the audio output data stream.

Since :: 2.3.1

Parameters:

[in]	output	The handle to the audio output
[out]	sample_rate	The audio sample rate in Hertz (8000 ~ 48000)

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 (8-bit or 16-bit) of the audio output data stream.

Since :: 2.3.1

Parameters:

[in]	output	The handle to the audio output
[out]	type	The audio sample 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_get_sound_type	(	audio_out_h	output,
		sound_type_e *	type
	)

Gets the sound type supported by the audio output device.

Since :: 2.3.1

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_ignore_session ( audio_out_h output )

Ignores session for output.

Since :: 2.3.1

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

int audio_out_prepare ( audio_out_h output )

Prepares playing audio output, this must be called before audio_out_write().

Since :: 2.3.1

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_unprepare()

int audio_out_set_interrupted_cb	(	audio_out_h	output,
		audio_io_interrupted_cb	callback,
		void *	user_data
	)

Registers a callback function to be invoked when the audio output handle is interrupted or the interrupt is completed.

Since :: 2.3.1

Parameters:

[in]	output	The handle to the audio output
[in]	callback	The callback function to register
[in]	user_data	The user data to be passed to the callback function

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

Postcondition:: audio_io_interrupted_cb() will be invoked.

See also:: audio_out_unset_interrupted_cb(); audio_io_interrupted_cb()

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

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

Since :: 2.3.1

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_in_destroy, audio_in_prepare, audio_in_unprepare) Recommend to use as a VOIP only. Recommend not to hold callback too long.(it affects latency)

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

Parameters:

[in]	output	An audio output handle
[in]	callback	notify stream callback when user can write data (audio_out_stream_cb)
[in]	userdata	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_in_set_stream_cb()

int audio_out_unprepare ( audio_out_h output )

Unprepares playing audio output.

Since :: 2.3.1

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_prepare()

int audio_out_unset_interrupted_cb ( audio_out_h output )

Unregisters the callback function.

Since :: 2.3.1

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_interrupted_cb()

int audio_out_unset_stream_cb ( audio_out_h output )

Unregisters the callback function.

Since :: 2.3.1

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.1

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

Required Header

Overview

Functions

Typedefs

Typedef Documentation

Function Documentation