Tizen Native API

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:

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_create_loopback (int sample_rate, audio_channel_e channel, audio_sample_type_e type, audio_in_h *input)
 Creates an audio loopback 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_prepare (audio_in_h input)
 Prepares reading audio input by starting buffering of audio data from the device.
int audio_in_unprepare (audio_in_h input)
 Unprepares reading audio input by stopping buffering the audio data from the device.
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_interrupted_cb (audio_in_h input, audio_io_interrupted_cb callback, void *user_data)
 Registers a callback function to be invoked when the audio input handle is interrupted or the interrupt is completed.
int audio_in_unset_interrupted_cb (audio_in_h input)
 Unregisters the callback function.
int audio_in_ignore_session (audio_in_h input)
 Ignores session for input.
int audio_in_set_stream_cb (audio_in_h input, audio_in_stream_cb callback, void *userdata)
 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.

Typedefs

typedef struct audio_in_s * audio_in_h
 The audio input handle.
typedef void(* audio_in_stream_cb )(audio_in_h handle, size_t nbytes, void *userdata)
 Called when audio input data is available in asynchronous(event) mode.

Typedef Documentation

typedef struct audio_in_s* audio_in_h

The audio input handle.

Since :
2.3.1
typedef void(* audio_in_stream_cb)(audio_in_h handle, size_t nbytes, void *userdata)

Called when audio input data is available in asynchronous(event) mode.

Since :
2.3.1
Remarks:
use audio_in_peek() to get audio in data inside callback, use audio_in_drop() after use of peeked data.
Parameters:
[in]handleThe handle to the audio input
[in]nbytesThe amount of available audio in data which can be peeked.
[in]userdataThe 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.

Since :
2.3.1
Privilege Level:
public
Privilege:
http://tizen.org/privilege/recorder

This function is used for audio input initialization.

Remarks:
input must be released using audio_in_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)
[out]inputAn audio input 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_PERMISSION_DENIEDPermission denied
AUDIO_IO_ERROR_OUT_OF_MEMORYOut of memory
AUDIO_IO_ERROR_DEVICE_NOT_OPENEDDevice not opened
AUDIO_IO_ERROR_SOUND_POLICYSound policy error
AUDIO_IO_ERROR_NOT_SUPPORTEDNot supported
See also:
audio_in_destroy()
int audio_in_create_loopback ( int  sample_rate,
audio_channel_e  channel,
audio_sample_type_e  type,
audio_in_h input 
)

Creates an audio loopback device instance and returns an input handle to record PCM (pulse-code modulation) data.

Since :
2.3.1
Privilege Level:
public
Privilege:
http://tizen.org/privilege/recorder

This function is used for audio loopback input initialization.

Remarks:
input must be released using audio_in_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)
[out]inputAn audio input handle will be created, if successful
Returns:
0 on success, otherwise a negative error value
Return values:
AUDIO_IO_ERROR_NONESuccessful
AUDIO_IO_ERROR_INVALID_PARAMETERInvalid parameter
AUDIO_IO_ERROR_PERMISSION_DENIEDPermission denied
AUDIO_IO_ERROR_OUT_OF_MEMORYOut of memory
AUDIO_IO_ERROR_DEVICE_NOT_OPENEDDevice not opened
AUDIO_IO_ERROR_SOUND_POLICYSound policy error
AUDIO_IO_ERROR_NOT_SUPPORTEDNot supported
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.1
Parameters:
[in]inputThe handle to the audio input 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_DEVICE_NOT_CLOSEDDevice not closed
AUDIO_IO_ERROR_NOT_SUPPORTEDNot 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.1
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]inputThe handle to the audio input
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
AUDIO_IO_ERROR_NOT_SUPPORTEDNot supported
See also:
audio_in_peek()
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.1
Parameters:
[in]inputThe handle to the audio input
[out]sizeThe 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
AUDIO_IO_ERROR_NOT_SUPPORTEDNot 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.

Since :
2.3.1

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

Parameters:
[in]inputThe handle to the audio input
[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
AUDIO_IO_ERROR_NOT_SUPPORTEDNot 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.1
Parameters:
[in]inputThe handle to the audio input
[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
AUDIO_IO_ERROR_NOT_SUPPORTEDNot supported

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

Since :
2.3.1
Parameters:
[in]inputThe handle to the audio input
[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
AUDIO_IO_ERROR_NOT_SUPPORTEDNot supported

Ignores session for input.

Since :
2.3.1
Parameters:
[in]inputThe handle to the audio input
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
AUDIO_IO_ERROR_NOT_SUPPORTEDNot supported
int audio_in_peek ( audio_in_h  input,
const void **  buffer,
unsigned int *  length 
)

peek from audio in buffer

Since :
2.3.1

This function works correctly only with read, write callback. Otherwise it won't operate as intended.

Remarks:
Works only in asynchronous(event) mode. This will just retrieve buffer pointer from audio in buffer. Drop after use.
Parameters:
[in]inputThe handle to the audio input
[out]bufferstart buffer pointer of peeked audio in data
[in,out]lengthamount of audio in data to be peeked
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
AUDIO_IO_ERROR_NOT_SUPPORTEDNot supported
See also:
audio_in_drop()
int audio_in_prepare ( audio_in_h  input)

Prepares reading audio input by starting buffering of audio data from the device.

Since :
2.3.1
Parameters:
[in]inputThe handle to the audio input
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
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.1
Parameters:
[in]inputThe handle to the audio input
[out]bufferThe PCM buffer address
[in]lengthThe 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_PARAMETERInvalid parameter
AUDIO_IO_ERROR_INVALID_BUFFERInvalid buffer pointer
AUDIO_IO_ERROR_SOUND_POLICYSound policy error
AUDIO_IO_ERROR_INVALID_OPERATIONInvalid operation
AUDIO_IO_ERROR_NOT_SUPPORTEDNot supported
Precondition:
audio_in_start_recording().
int audio_in_set_interrupted_cb ( audio_in_h  input,
audio_io_interrupted_cb  callback,
void *  user_data 
)

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

Since :
2.3.1
Parameters:
[in]inputThe handle to the audio input
[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
AUDIO_IO_ERROR_NOT_SUPPORTEDNot supported
Postcondition:
audio_io_interrupted_cb() will be invoked.
See also:
audio_in_unset_interrupted_cb()
audio_io_interrupted_cb()
int audio_in_set_stream_cb ( audio_in_h  input,
audio_in_stream_cb  callback,
void *  userdata 
)

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

Since :
2.3.1

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)

Remarks:
input must be created using audio_in_create().
Parameters:
[in]inputAn audio input handle
[in]callbacknotify stream callback when user can read data (audio_in_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
AUDIO_IO_ERROR_NOT_SUPPORTEDNot supported
See also:
audio_out_set_stream_cb()

Unprepares reading audio input by stopping buffering the audio data from the device.

Since :
2.3.1
Parameters:
[in]inputThe handle to the audio input
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
See also:
audio_in_prepare()

Unregisters the callback function.

Since :
2.3.1
Parameters:
[in]inputThe handle to the audio input
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
AUDIO_IO_ERROR_NOT_SUPPORTEDNot supported
See also:
audio_in_set_interrupted_cb()

Unregisters the callback function.

Since :
2.3.1
Parameters:
[in]inputThe handle to the audio input
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
AUDIO_IO_ERROR_NOT_SUPPORTEDNot supported
See also:
audio_in_set_interrupted_cb()