Tizen Native API
5.5
|
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, otherwisefalse
if the state is not changed by policy[in] user_data The user data passed from the callback registration function
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.
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.