Tizen Native API  5.0
Audio Output

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 (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_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]handleThe handle of the audio output
[in]previousThe previous state of the audio output
[in]currentThe current state of the audio output
[in]by_policytrue if the state is changed by policy, otherwise false if the state is not changed by policy
[in]user_dataThe 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]handleThe handle to the audio output
[in]nbytesThe amount of audio in data which can be written.
[in]user_dataThe 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.
Parameters:
[in]sample_rateThe audio sample rate in 8000[Hz] ~ 48000[Hz] (Before 5.0), 8000[Hz] ~ 192000[Hz] (Since 5.0)
[in]channelThe audio channel type (mono or stereo)
[in]typeThe type of audio sample (8-bit or 16-bit)
[out]outputAn audio output handle is created on success
Returns:
0 on success, otherwise a negative error value
Return values:
AUDIO_IO_ERROR_NONESuccessful
AUDIO_IO_ERROR_INVALID_PARAMETERInvalid parameter
AUDIO_IO_ERROR_OUT_OF_MEMORYOut of memory
AUDIO_IO_ERROR_DEVICE_NOT_OPENEDDevice not opened
AUDIO_IO_ERROR_SOUND_POLICYSound 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]outputThe handle to the audio output to destroy
Returns:
0 on success, otherwise a negative error value
Return values:
AUDIO_IO_ERROR_NONESuccessful
AUDIO_IO_ERROR_INVALID_PARAMETERInvalid parameter
AUDIO_IO_ERROR_OUT_OF_MEMORYOut of memory
AUDIO_IO_ERROR_DEVICE_NOT_CLOSEDDevice 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]outputThe handle to the audio output
Returns:
0 on success, otherwise a negative error value
Return values:
AUDIO_IO_ERROR_NONESuccessful
AUDIO_IO_ERROR_INVALID_PARAMETERInvalid parameter
AUDIO_IO_ERROR_INVALID_STATEInvalid 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]outputThe handle to the audio output
Returns:
0 on success, otherwise a negative error value
Return values:
AUDIO_IO_ERROR_NONESuccessful
AUDIO_IO_ERROR_INVALID_PARAMETERInvalid parameter
AUDIO_IO_ERROR_INVALID_STATEInvalid 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]outputThe handle to the audio output
[out]sizeThe 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_NONESuccessful
AUDIO_IO_ERROR_INVALID_PARAMETERInvalid 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
Parameters:
[in]outputThe handle to the audio output
[out]channelThe audio channel type
Returns:
0 on success, otherwise a negative error value
Return values:
AUDIO_IO_ERROR_NONESuccessful
AUDIO_IO_ERROR_INVALID_PARAMETERInvalid 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]outputThe handle to the audio output
[out]sample_rateThe audio sample rate in Hertz (8000 ~ 48000) (Before 5.0), (8000 ~ 192000) (Since 5.0)
Returns:
0 on success, otherwise a negative error value
Return values:
AUDIO_IO_ERROR_NONESuccessful
AUDIO_IO_ERROR_INVALID_PARAMETERInvalid parameter

Gets the sample audio format (8-bit or 16-bit) of the audio output data stream.

Since :
2.3
Parameters:
[in]outputThe handle to the audio output
[out]typeThe audio sample type
Returns:
0 on success, otherwise a negative error value
Return values:
AUDIO_IO_ERROR_NONESuccessful
AUDIO_IO_ERROR_INVALID_PARAMETERInvalid 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]outputThe handle to the audio output
[out]typeThe sound type
Returns:
0 on success, otherwise a negative error value
Return values:
AUDIO_IO_ERROR_NONESuccessful
AUDIO_IO_ERROR_INVALID_PARAMETERInvalid parameter
int audio_out_pause ( audio_out_h  output)

Pauses feeding of audio data to the device.

Since :
3.0
Parameters:
[in]outputThe handle to the audio output
Returns:
0 on success, otherwise a negative error value
Return values:
AUDIO_IO_ERROR_NONESuccessful
AUDIO_IO_ERROR_INVALID_PARAMETERInvalid parameter
AUDIO_IO_ERROR_INVALID_STATEInvalid 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]outputThe handle to the audio output
Returns:
0 on success, otherwise a negative error value
Return values:
AUDIO_IO_ERROR_NONESuccessful
AUDIO_IO_ERROR_INVALID_PARAMETERInvalid parameter
AUDIO_IO_ERROR_INVALID_STATEInvalid 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]outputThe handle to the audio output
Returns:
0 on success, otherwise a negative error value
Return values:
AUDIO_IO_ERROR_NONESuccessful
AUDIO_IO_ERROR_INVALID_PARAMETERInvalid parameter
AUDIO_IO_ERROR_INVALID_STATEInvalid state
Precondition:
The state should be AUDIO_IO_STATE_PAUSED.
Postcondition:
The state will be AUDIO_IO_STATE_RUNNING.
See also:
audio_out_pause()

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]outputThe handle to the audio output
[in]stream_infoThe handle of stream information
Returns:
0 on success, otherwise a negative error value
Return values:
AUDIO_IO_ERROR_NONESuccessful
AUDIO_IO_ERROR_INVALID_PARAMETERInvalid parameter
AUDIO_IO_ERROR_NOT_SUPPORTEDNot supported
AUDIO_IO_ERROR_INVALID_STATEInvalid state
AUDIO_IO_ERROR_NOT_SUPPORTED_TYPENot 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]outputThe audio output handle
[in]callbackthe state changed callback called when the state of the handle is changed (audio_out_state_changed_cb)
[in]user_datauser data to be retrieved when callback is called
Returns:
0 on success, otherwise a negative error value
Return values:
AUDIO_IO_ERROR_NONESuccessful
AUDIO_IO_ERROR_INVALID_PARAMETERInvalid 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]outputAn audio output handle
[in]callbacknotify stream callback when user can write data (audio_out_stream_cb)
[in]user_datauser data to be retrieved when callback is called
Returns:
0 on success, otherwise a negative error value
Return values:
AUDIO_IO_ERROR_NONESuccessful
AUDIO_IO_ERROR_INVALID_PARAMETERInvalid parameter
AUDIO_IO_ERROR_OUT_OF_MEMORYOut of memory
AUDIO_IO_ERROR_DEVICE_NOT_OPENEDDevice not opened
AUDIO_IO_ERROR_SOUND_POLICYSound policy error
See also:
audio_out_unset_stream_cb()

Unprepares the audio output.

Since :
2.3
Parameters:
[in]outputThe handle to the audio output
Returns:
0 on success, otherwise a negative error value
Return values:
AUDIO_IO_ERROR_NONESuccessful
AUDIO_IO_ERROR_INVALID_PARAMETERInvalid parameter
AUDIO_IO_ERROR_INVALID_STATEInvalid state
Postcondition:
The state will be AUDIO_IO_STATE_IDLE.
See also:
audio_out_prepare()

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

Since :
3.0
Parameters:
[in]outputThe handle to the audio output
Returns:
0 on success, otherwise a negative error value
Return values:
AUDIO_IO_ERROR_NONESuccessful
AUDIO_IO_ERROR_INVALID_PARAMETERInvalid parameter
See also:
audio_out_set_state_changed_cb()

Unregisters the callback function.

Since :
2.3
Parameters:
[in]outputThe handle to the audio output
Returns:
0 on success, otherwise a negative error value
Return values:
AUDIO_IO_ERROR_NONESuccessful
AUDIO_IO_ERROR_INVALID_PARAMETERInvalid parameter
AUDIO_IO_ERROR_INVALID_OPERATIONInvalid 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]outputThe handle to the audio output
[in,out]bufferThe PCM buffer address
[in]lengthThe 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_PARAMETERInvalid parameter
AUDIO_IO_ERROR_INVALID_BUFFERInvalid buffer pointer
AUDIO_IO_ERROR_SOUND_POLICYSound policy error
AUDIO_IO_ERROR_INVALID_STATEInvalid state
Precondition:
The state should be AUDIO_IO_STATE_RUNNING.