Tizen Native API
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 (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]handleThe handle to the audio output
[in]nbytesThe amount of audio in data which can be written.
[in]userdataThe 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_rateThe audio sample rate in 8000[Hz] ~ 48000[Hz]
[in]channelThe audio channel type (mono or stereo)
[in]typeThe type of audio sample (8- or 16-bit)
[in]sound_typeThe type of sound (sound_type_e)
[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
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]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()
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]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.1
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.1
Parameters:
[in]outputThe handle to the audio output
[out]sample_rateThe audio sample rate in Hertz (8000 ~ 48000)
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.1
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.1
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

Ignores session for output.

Since :
2.3.1
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
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]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_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]outputThe handle to the audio output
[in]callbackThe callback function to register
[in]user_dataThe user data to be passed to the callback function
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
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]outputAn audio output handle
[in]callbacknotify stream callback when user can write data (audio_out_stream_cb)
[in]userdatauser 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_in_set_stream_cb()

Unprepares playing audio output.

Since :
2.3.1
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_prepare()

Unregisters the callback function.

Since :
2.3.1
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_interrupted_cb()

Unregisters the callback function.

Since :
2.3.1
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.1
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