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 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)
	Peeks into the 'audio in' buffer.
int	audio_in_drop (audio_in_h input)
	Drops the 'audio in' buffer that was peeked into.
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.
int	audio_in_get_volume (audio_in_h input, double *volume)
	Gets the volume of the audio input data stream.
int	audio_in_set_volume (audio_in_h input, double volume)
	Sets the volume of the audio input data stream.
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.1

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, otherwise `false` if the state is not changed by policy
[in]	user_data	The user data passed from the callback registration function

See also:: audio_in_set_state_changed_cb(); audio_in_unset_state_changed_cb()

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.1

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.1

Privilege Level:: public

Privilege:: http://tizen.org/privilege/recorder

Remarks:: input must be released using audio_in_destroy(). If the channel count of the requested channel is different from the system's supported channel count, then channel remapping will be processed internally.

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 Before 5.5: Mono or stereo Since 5.5: Mono, stereo or multi-channels
[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]	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.1

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 )

Drops the 'audio in' buffer that was peeked into.

This function works correctly only with read 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 the 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 :: 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 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.1

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.

Since :: 2.3.1

Parameters:

[in]	input	The handle to the audio input
[out]	channel	The audio channel type Before 5.5: Mono or stereo Since 5.5: Mono, stereo or multi-channels

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.1

Parameters:

[in]	input	The handle to the audio input
[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
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 of the audio input data stream.

Since :: 2.3.1

Parameters:

[in]	input	The handle to the audio input
[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
AUDIO_IO_ERROR_NOT_SUPPORTED	Not supported

int audio_in_get_volume	(	audio_in_h	input,
		double *	volume
	)

Gets the volume of the audio input data stream.

Since :: 6.0

Remarks:: The default volume of the audio input stream is 1.0.

Parameters:

[in]	input	The handle to the audio input
[out]	volume	The current volume value of the audio input stream

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_volume()

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
	)

Peeks into the 'audio in' buffer.

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

Since :: 2.3.1

Remarks:: Works only in asynchronous (event) mode. This function provides the pointer to the 'audio in' buffer. The pointed memory is owned by the platform, therefore the buffer should not be released by the application. When the data in the buffer is not needed anymore, use audio_in_drop() with the input for which audio_in_peek() was called.

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.1

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.1

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.

See also:: sound_manager_create_stream_information(); sound_manager_destroy_stream_information()

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.1

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_set_volume	(	audio_in_h	input,
		double	volume
	)

Sets the volume of the audio input data stream.

Since :: 6.0

Remarks:: The default volume of the audio input stream is 1.0. If the volume is less than 1.0, the loudness of recorded data will be decreased. If the volume is greater than 1.0, the loudness of recorded data will be increased, which can be useful when the loudness of original recorded data is too low in certain environments. Note that the volume can be clipped if the volume is greater than 1.0 and the loudness of original recorded data is high enough.

Parameters:

[in]	input	The handle to the audio input
[in]	volume	The volume value to be set (0.0 <= volume <= 2.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

See also:: audio_in_get_volume()

int audio_in_unprepare ( audio_in_h input )

Unprepares the audio input.

Since :: 2.3.1

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.1

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()

Required Header

Overview

Related Features

Functions

Typedefs

Typedef Documentation

Function Documentation