Tizen Native API
5.0
|
The Audio Input API provides a set of functions to directly manage the system audio input devices.
Required Header
#include <audio_io.h>
Overview
The Audio Input API provides a set of functions to record audio data (PCM format) from audio devices.
Related Features
This API is related with the following features:
- http://tizen.org/feature/microphone
It is recommended to design feature related codes in your application for reliability.
You can check if a device supports the related features for this API by using System Information, thereby controlling the procedure of your application.
To ensure your application is only running on the device with specific features, please define the features in your manifest file using the manifest editor in the SDK.
More details on featuring your application can be found from Feature Element.
Functions | |
int | audio_in_create (int sample_rate, audio_channel_e channel, audio_sample_type_e type, audio_in_h *input) |
Creates an audio device instance and returns an input handle to record PCM (pulse-code modulation) data. | |
int | audio_in_destroy (audio_in_h input) |
Releases the audio input handle and all its resources associated with an audio stream. | |
int | audio_in_set_sound_stream_info (audio_in_h input, sound_stream_info_h stream_info) |
Sets the sound stream information to the audio input. | |
int | audio_in_prepare (audio_in_h input) |
Prepares the audio input for reading audio data by starting buffering of audio data from the device. | |
int | audio_in_unprepare (audio_in_h input) |
Unprepares the audio input. | |
int | audio_in_pause (audio_in_h input) |
Pauses buffering of audio data from the device. | |
int | audio_in_resume (audio_in_h input) |
Resumes buffering audio data from the device. | |
int | audio_in_flush (audio_in_h input) |
Flushes and discards buffered audio data from the input stream. | |
int | audio_in_read (audio_in_h input, void *buffer, unsigned int length) |
Reads audio data from the audio input buffer. | |
int | audio_in_get_buffer_size (audio_in_h input, int *size) |
Gets the size to be allocated for the audio input buffer. | |
int | audio_in_get_sample_rate (audio_in_h input, int *sample_rate) |
Gets the sample rate of the audio input data stream. | |
int | audio_in_get_channel (audio_in_h input, audio_channel_e *channel) |
Gets the channel type of the audio input data stream. | |
int | audio_in_get_sample_type (audio_in_h input, audio_sample_type_e *type) |
Gets the sample audio format (8-bit or 16-bit) of the audio input data stream. | |
int | audio_in_set_stream_cb (audio_in_h input, audio_in_stream_cb callback, void *user_data) |
Sets an asynchronous(event) callback function to handle recording PCM (pulse-code modulation) data. | |
int | audio_in_unset_stream_cb (audio_in_h input) |
Unregisters the callback function. | |
int | audio_in_peek (audio_in_h input, const void **buffer, unsigned int *length) |
peek from audio in buffer | |
int | audio_in_drop (audio_in_h input) |
drop peeked audio buffer. | |
int | audio_in_set_state_changed_cb (audio_in_h input, audio_in_state_changed_cb callback, void *user_data) |
Sets the state changed callback function to the audio input handle. | |
int | audio_in_unset_state_changed_cb (audio_in_h input) |
Unregisters the state changed callback function of the audio input handle. | |
Typedefs | |
typedef struct audio_io_s * | audio_in_h |
The audio input handle. | |
typedef void(* | audio_in_stream_cb )(audio_in_h handle, size_t nbytes, void *user_data) |
Called when audio input data is available in asynchronous(event) mode. | |
typedef void(* | audio_in_state_changed_cb )(audio_in_h handle, audio_io_state_e previous, audio_io_state_e current, bool by_policy, void *user_data) |
Called when the state of audio input is changed. |
Typedef Documentation
typedef struct audio_io_s* audio_in_h |
The audio input handle.
- Since :
- 2.3
typedef void(* audio_in_state_changed_cb)(audio_in_h handle, audio_io_state_e previous, audio_io_state_e current, bool by_policy, void *user_data) |
Called when the state of audio input is changed.
- Since :
- 3.0
- Parameters:
-
[in] handle The handle of the audio input [in] previous The previous state of the audio input [in] current The current state of the audio input [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_in_stream_cb)(audio_in_h handle, size_t nbytes, void *user_data) |
Called when audio input data is available in asynchronous(event) mode.
- Since :
- 2.3
- Remarks:
- use audio_in_peek() to get audio in data inside callback, use audio_in_drop() after use of peeked data.
- Parameters:
-
[in] handle The handle to the audio input [in] nbytes The amount of available audio in data which can be peeked. [in] user_data The user data passed from the callback registration function
- See also:
- audio_in_set_stream_cb()
Function Documentation
int audio_in_create | ( | int | sample_rate, |
audio_channel_e | channel, | ||
audio_sample_type_e | type, | ||
audio_in_h * | input | ||
) |
Creates an audio device instance and returns an input handle to record PCM (pulse-code modulation) data.
This function is used for audio input initialization.
- Since :
- 2.3
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/recorder
- Remarks:
- input must be released using audio_in_destroy().
- Parameters:
-
[in] sample_rate The audio sample rate in 8000[Hz] ~ 48000[Hz] (Before 5.0), 8000[Hz] ~ 192000[Hz] (Since 5.0) [in] channel The audio channel type (mono or stereo) [in] type The type of audio sample (8- or 16-bit) [out] input An audio input 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_PERMISSION_DENIED Permission denied 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 AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
- Postcondition:
- The state will be AUDIO_IO_STATE_IDLE.
audio_in_set_sound_stream_info() is recommended to be called after this API.
- See also:
- audio_in_destroy()
int audio_in_destroy | ( | audio_in_h | input | ) |
Releases the audio input handle and all its resources associated with an audio stream.
- Since :
- 2.3
- Parameters:
-
[in] input The handle to the audio input 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_DEVICE_NOT_CLOSED Device not closed AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
- See also:
- audio_in_create()
int audio_in_drop | ( | audio_in_h | input | ) |
drop peeked audio buffer.
This function works correctly only with read, write callback. Otherwise it won't operate as intended.
- Since :
- 2.3
- Remarks:
- Works only in asynchronous(event) mode. This will remove audio in data from actual stream buffer. Use this if peeked data is not needed anymore.
- Parameters:
-
[in] input The handle to the audio input
- 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 AUDIO_IO_ERROR_NOT_SUPPORTED Not supported AUDIO_IO_ERROR_INVALID_STATE Invalid state
- Precondition:
- The state should be AUDIO_IO_STATE_RUNNING.
- See also:
- audio_in_peek()
int audio_in_flush | ( | audio_in_h | input | ) |
Flushes and discards buffered audio data from the input stream.
- Since :
- 2.4
- Parameters:
-
[in] input The handle to the audio input
- 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
- Precondition:
- The state should be AUDIO_IO_STATE_RUNNING or AUDIO_IO_STATE_PAUSED.
int audio_in_get_buffer_size | ( | audio_in_h | input, |
int * | size | ||
) |
Gets the size to be allocated for the audio input buffer.
- Since :
- 2.3
- Parameters:
-
[in] input The handle to the audio input [out] size The 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 AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
- See also:
- audio_in_read()
int audio_in_get_channel | ( | audio_in_h | input, |
audio_channel_e * | channel | ||
) |
Gets the channel type of the audio input data stream.
The audio channel type defines whether the audio is mono or stereo.
- Since :
- 2.3
- Parameters:
-
[in] input The handle to the audio input [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 AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
int audio_in_get_sample_rate | ( | audio_in_h | input, |
int * | sample_rate | ||
) |
Gets the sample rate of the audio input data stream.
- Since :
- 2.3
- Parameters:
-
[in] input The handle to the audio input [out] sample_rate The 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_NONE Successful AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
int audio_in_get_sample_type | ( | audio_in_h | input, |
audio_sample_type_e * | type | ||
) |
Gets the sample audio format (8-bit or 16-bit) of the audio input data stream.
- Since :
- 2.3
- Parameters:
-
[in] input The handle to the audio input [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 AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
int audio_in_pause | ( | audio_in_h | input | ) |
Pauses buffering of audio data from the device.
- Since :
- 3.0
- Parameters:
-
[in] input The handle to the audio input
- 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
- Precondition:
- The state should be AUDIO_IO_STATE_RUNNING.
- Postcondition:
- The state will be AUDIO_IO_STATE_PAUSED.
- See also:
- audio_in_resume()
int audio_in_peek | ( | audio_in_h | input, |
const void ** | buffer, | ||
unsigned int * | length | ||
) |
peek from audio in buffer
This function works correctly only with read, write callback. Otherwise it won't operate as intended.
- Since :
- 2.3
- Remarks:
- Works only in asynchronous(event) mode. This will just retrieve buffer pointer from audio in buffer. Drop after use.
- Parameters:
-
[in] input The handle to the audio input [out] buffer start buffer pointer of peeked audio in data [out] length amount of audio in data to be peeked
- 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 AUDIO_IO_ERROR_NOT_SUPPORTED Not supported AUDIO_IO_ERROR_INVALID_STATE Invalid state
- Precondition:
- The state should be AUDIO_IO_STATE_RUNNING.
- See also:
- audio_in_drop()
int audio_in_prepare | ( | audio_in_h | input | ) |
Prepares the audio input for reading audio data by starting buffering of audio data from the device.
- Since :
- 2.3
- Parameters:
-
[in] input The handle to the audio input
- 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_DEVICE_POLICY_RESTRICTION Device policy restriction AUDIO_IO_ERROR_INVALID_STATE Invalid state
- Postcondition:
- The state will be AUDIO_IO_STATE_RUNNING.
- See also:
- audio_in_unprepare()
int audio_in_read | ( | audio_in_h | input, |
void * | buffer, | ||
unsigned int | length | ||
) |
Reads audio data from the audio input buffer.
- Since :
- 2.3
- Parameters:
-
[in] input The handle to the audio input [out] buffer The PCM buffer address [in] length The length of the PCM data buffer (in bytes)
- Returns:
- The number of read bytes 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_OPERATION Invalid operation AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
- Precondition:
- The state should be AUDIO_IO_STATE_RUNNING.
int audio_in_resume | ( | audio_in_h | input | ) |
Resumes buffering audio data from the device.
- Since :
- 3.0
- Parameters:
-
[in] input The handle to the audio input
- 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
- Precondition:
- The state should be AUDIO_IO_STATE_PAUSED.
- Postcondition:
- The state will be AUDIO_IO_STATE_RUNNING.
- See also:
- audio_in_pause()
int audio_in_set_sound_stream_info | ( | audio_in_h | input, |
sound_stream_info_h | stream_info | ||
) |
Sets the sound stream information to the audio input.
- Since :
- 3.0
- Remarks:
- the sound stream information includes audio routing and volume type. For more details, you can refer to Sound Manager System, Alarm, Notification, Emergency, Voice Information, Ringtone VOIP and Ringtone Call stream types are not supported in this API.
- Parameters:
-
[in] input The handle to the audio input [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_in_create() before calling this function.
- Postcondition:
- Call audio_in_prepare() after calling this function.
int audio_in_set_state_changed_cb | ( | audio_in_h | input, |
audio_in_state_changed_cb | callback, | ||
void * | user_data | ||
) |
Sets the state changed callback function to the audio input handle.
- Since :
- 3.0
- Remarks:
- input must be created using audio_in_create().
- Parameters:
-
[in] input The audio input handle [in] callback the state changed callback called when the state of the handle is changed (audio_in_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 AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
- See also:
- audio_in_unset_state_changed_cb()
int audio_in_set_stream_cb | ( | audio_in_h | input, |
audio_in_stream_cb | callback, | ||
void * | user_data | ||
) |
Sets an asynchronous(event) callback function to handle recording PCM (pulse-code modulation) data.
callback will be called when you can read 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)
- Since :
- 2.3
- Remarks:
- input must be created using audio_in_create().
- Parameters:
-
[in] input An audio input handle [in] callback notify stream callback when user can read data (audio_in_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 AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
- See also:
- audio_in_unset_stream_cb()
int audio_in_unprepare | ( | audio_in_h | input | ) |
Unprepares the audio input.
- Since :
- 2.3
- Parameters:
-
[in] input The handle to the audio input
- 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
- Postcondition:
- The state will be AUDIO_IO_STATE_IDLE.
- See also:
- audio_in_prepare()
int audio_in_unset_state_changed_cb | ( | audio_in_h | input | ) |
Unregisters the state changed callback function of the audio input handle.
- Since :
- 3.0
- Parameters:
-
[in] input The handle to the audio input
- 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
- See also:
- audio_in_set_state_changed_cb()
int audio_in_unset_stream_cb | ( | audio_in_h | input | ) |
Unregisters the callback function.
- Since :
- 2.3
- Parameters:
-
[in] input The handle to the audio input
- 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 AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
- See also:
- audio_in_set_stream_cb()