The Audio provides functions for audio devices.

Required Header

#include <hal-audio.h>

Overview

The Audio module in the HAL provides functions to manage audio playback and capture.

Key functionalities include:

Initializing and deinitializing the audio hardware.
Opening and configuring PCM audio streams.
Starting and stopping audio operations.
Recovering from audio errors.
Closing audio streams to free resources.

State Diagram

State Transitions

FUNCTION	PRE-STATE	POST-STATE	SYNC TYPE
hal_audio_init()	N/A	CLOSE	SYNC
hal_audio_deinit()	CLOSE	N/A	SYNC
hal_audio_pcm_open()	CLOSE	OPEN	SYNC
hal_audio_pcm_set_params()	OPEN	SETUP	SYNC
hal_audio_pcm_start()	SETUP	RUNNING	SYNC
hal_audio_pcm_stop()	RUNNING	STOP	SYNC
hal_audio_pcm_close()	STOP	CLOSE	SYNC
hal_audio_pcm_recover()	XRUN	RUNNING	SYNC

For more information on the Audio features and the macros, see HAL Audio programming guides and tutorials.

Typedefs
typedef enum audio_return	audio_return_e
	Enumeration for return codes.
typedef enum audio_direction	audio_direction_e
	Enumeration for audio direction.
typedef enum audio_state	audio_state_e
	Enumeration for audio state.
typedef struct device_info	device_info_s
	Device information including type, direction and id.
typedef struct audio_volume_info	audio_volume_info_s
	Volume information including type, gain and direction.
typedef struct audio_route_info	audio_route_info_s
	Route information including role and device.
typedef struct audio_route_option	audio_route_option_s
	Route option including role, name and value.
typedef struct audio_stream_info	audio_stream_info_s
	Stream information including role, direction and index.
typedef struct audio_ducking_info	audio_ducking_info_s
	Ducking information including target role, duration and ratio.
typedef void(*	message_cb )(const char name, int value, void user_data)
	Called when audio hal implementation needs to send a message.
typedef struct _hal_backend_media_audio_funcs	hal_backend_audio_funcs
	The structure type of the audio HAL functions.

Data Structure Documentation

struct device_info

Device information including type, direction and id.

Since:: HAL_MODULE_AUDIO 1.0

Data Fields
const char *	type
uint32_t	direction
uint32_t	id

Field Documentation

uint32_t device_info::direction

playback or capture

uint32_t device_info::id

device id

const char* device_info::type

device type

struct audio_volume_info

Volume information including type, gain and direction.

Since:: HAL_MODULE_AUDIO 1.0

Data Fields
const char *	type
const char *	gain
uint32_t	direction

Field Documentation

uint32_t audio_volume_info::direction

playback or capture

const char* audio_volume_info::gain

volume gain

const char* audio_volume_info::type

volume type

struct audio_route_info

Route information including role and device.

Since:: HAL_MODULE_AUDIO 1.0

Data Fields
const char *	role
device_info_s *	device_infos
uint32_t	num_of_devices

Field Documentation

device_info_s* audio_route_info::device_infos

device info

uint32_t audio_route_info::num_of_devices

number of devices

const char* audio_route_info::role

stream role

struct audio_route_option

Route option including role, name and value.

Since:: HAL_MODULE_AUDIO 1.0

Data Fields
const char *	role
const char *	name
int32_t	value

Field Documentation

const char* audio_route_option::name

key

const char* audio_route_option::role

stream role

int32_t audio_route_option::value

value

struct audio_stream_info

Stream information including role, direction and index.

Since:: HAL_MODULE_AUDIO 1.0

Data Fields
const char *	role
uint32_t	direction
uint32_t	idx

Field Documentation

uint32_t audio_stream_info::direction

playback or capture

uint32_t audio_stream_info::idx

stream index

const char* audio_stream_info::role

stream role

struct audio_ducking_info

Ducking information including target role, duration and ratio.

Since:: HAL_MODULE_AUDIO 1.0

Data Fields
const char *	target_role
uint32_t	duration
double	ratio

Field Documentation

uint32_t audio_ducking_info::duration

ducking duration

double audio_ducking_info::ratio

volume ratio

const char* audio_ducking_info::target_role

ducking target role

struct _hal_backend_media_audio_funcs

The structure type of the audio HAL functions.

Since:: HAL_MODULE_AUDIO 1.0

Data Fields
audio_return_e(*	init )(void **audio_handle)
audio_return_e(*	deinit )(void *audio_handle)
audio_return_e(*	get_volume_level_max )(void audio_handle, audio_volume_info_s info, uint32_t *level)
audio_return_e(*	get_volume_level )(void audio_handle, audio_volume_info_s info, uint32_t *level)
audio_return_e(*	set_volume_level )(void audio_handle, audio_volume_info_s info, uint32_t level)
audio_return_e(*	get_volume_value )(void audio_handle, audio_volume_info_s info, uint32_t level, double *value)
audio_return_e(*	get_volume_mute )(void audio_handle, audio_volume_info_s info, uint32_t *mute)
audio_return_e(*	set_volume_mute )(void audio_handle, audio_volume_info_s info, uint32_t mute)
audio_return_e(*	set_volume_ratio )(void audio_handle, audio_stream_info_s info, double ratio)
audio_return_e(*	notify_ducking_activation_changed )(void audio_handle, audio_ducking_info_s info, uint32_t is_activated)
audio_return_e(*	update_route )(void audio_handle, audio_route_info_s info)
audio_return_e(*	update_route_option )(void audio_handle, audio_route_option_s option)
audio_return_e(*	notify_stream_connection_changed )(void audio_handle, audio_stream_info_s info, uint32_t is_connected)
audio_return_e(*	pcm_open )(void audio_handle, const char card, const char device, uint32_t direction, void sample_spec, uint32_t period_size, uint32_t periods, void **pcm_handle)
audio_return_e(*	pcm_start )(void audio_handle, void pcm_handle)
audio_return_e(*	pcm_stop )(void audio_handle, void pcm_handle)
audio_return_e(*	pcm_close )(void audio_handle, void pcm_handle)
audio_return_e(*	pcm_avail )(void audio_handle, void pcm_handle, uint32_t *avail)
audio_return_e(*	pcm_write )(void audio_handle, void pcm_handle, const void *buffer, uint32_t frames)
audio_return_e(*	pcm_read )(void audio_handle, void pcm_handle, void *buffer, uint32_t frames)
audio_return_e(*	pcm_get_fd )(void audio_handle, void pcm_handle, int *fd)
audio_return_e(*	pcm_recover )(void audio_handle, void pcm_handle, int revents)
audio_return_e(*	pcm_get_params )(void audio_handle, void pcm_handle, uint32_t direction, void sample_spec, uint32_t period_size, uint32_t *periods)
audio_return_e(*	pcm_set_params )(void audio_handle, void pcm_handle, uint32_t direction, void *sample_spec, uint32_t period_size, uint32_t periods)
audio_return_e(*	pcm_avail_delay )(void audio_handle, void pcm_handle, int32_t avail, int32_t delay)
audio_return_e(*	pcm_mmap_begin )(void audio_handle, void pcm_handle, void *areas, uint32_t offset, uint32_t frames, void *ptr)
audio_return_e(*	pcm_mmap_commit )(void audio_handle, void pcm_handle, uint32_t offset, uint32_t frames)
audio_return_e(*	pcm_get_state )(void audio_handle, void pcm_handle, audio_state_e *state)
audio_return_e(*	add_message_cb )(void audio_handle, message_cb callback, void user_data)

Field Documentation

audio_return_e(* _hal_backend_media_audio_funcs::add_message_cb)(void *audio_handle, message_cb callback, void *user_data)

Remove message callback

audio_return_e(* _hal_backend_media_audio_funcs::deinit)(void *audio_handle)

Get volume max level

audio_return_e(* _hal_backend_media_audio_funcs::get_volume_level)(void *audio_handle, audio_volume_info_s *info, uint32_t *level)

Set volume level

audio_return_e(* _hal_backend_media_audio_funcs::get_volume_level_max)(void *audio_handle, audio_volume_info_s *info, uint32_t *level)

Get volume level

audio_return_e(* _hal_backend_media_audio_funcs::get_volume_mute)(void *audio_handle, audio_volume_info_s *info, uint32_t *mute)

Set volume mute

audio_return_e(* _hal_backend_media_audio_funcs::get_volume_value)(void *audio_handle, audio_volume_info_s *info, uint32_t level, double *value)

Get volume mute

audio_return_e(* _hal_backend_media_audio_funcs::init)(void **audio_handle)

< Initialize HAL backend Deinitialize HAL backend

audio_return_e(* _hal_backend_media_audio_funcs::notify_ducking_activation_changed)(void *audio_handle, audio_ducking_info_s *info, uint32_t is_activated)

Update route

audio_return_e(* _hal_backend_media_audio_funcs::notify_stream_connection_changed)(void *audio_handle, audio_stream_info_s *info, uint32_t is_connected)

Open device

audio_return_e(* _hal_backend_media_audio_funcs::pcm_avail)(void *audio_handle, void *pcm_handle, uint32_t *avail)

Write data

audio_return_e(* _hal_backend_media_audio_funcs::pcm_avail_delay)(void *audio_handle, void *pcm_handle, int32_t *avail, int32_t *delay)

Start mmap

audio_return_e(* _hal_backend_media_audio_funcs::pcm_close)(void *audio_handle, void *pcm_handle)

Get available size

audio_return_e(* _hal_backend_media_audio_funcs::pcm_get_fd)(void *audio_handle, void *pcm_handle, int *fd)

Try recovering device

audio_return_e(* _hal_backend_media_audio_funcs::pcm_get_params)(void *audio_handle, void *pcm_handle, uint32_t direction, void *sample_spec, uint32_t *period_size, uint32_t *periods)

Set device params

audio_return_e(* _hal_backend_media_audio_funcs::pcm_get_state)(void *audio_handle, void *pcm_handle, audio_state_e *state)

Add message callback

audio_return_e(* _hal_backend_media_audio_funcs::pcm_mmap_begin)(void *audio_handle, void *pcm_handle, void **areas, uint32_t *offset, uint32_t *frames, void **ptr)

Commit mmap

audio_return_e(* _hal_backend_media_audio_funcs::pcm_mmap_commit)(void *audio_handle, void *pcm_handle, uint32_t offset, uint32_t frames)

Get state

audio_return_e(* _hal_backend_media_audio_funcs::pcm_open)(void *audio_handle, const char *card, const char *device, uint32_t direction, void *sample_spec, uint32_t period_size, uint32_t periods, void **pcm_handle)

Start device

audio_return_e(* _hal_backend_media_audio_funcs::pcm_read)(void *audio_handle, void *pcm_handle, void *buffer, uint32_t frames)

Get file descriptor

audio_return_e(* _hal_backend_media_audio_funcs::pcm_recover)(void *audio_handle, void *pcm_handle, int revents)

Get device params

audio_return_e(* _hal_backend_media_audio_funcs::pcm_set_params)(void *audio_handle, void *pcm_handle, uint32_t direction, void *sample_spec, uint32_t period_size, uint32_t periods)

Get delay and latency both

audio_return_e(* _hal_backend_media_audio_funcs::pcm_start)(void *audio_handle, void *pcm_handle)

Stop device

audio_return_e(* _hal_backend_media_audio_funcs::pcm_stop)(void *audio_handle, void *pcm_handle)

Close device

audio_return_e(* _hal_backend_media_audio_funcs::pcm_write)(void *audio_handle, void *pcm_handle, const void *buffer, uint32_t frames)

Read data

audio_return_e(* _hal_backend_media_audio_funcs::set_volume_level)(void *audio_handle, audio_volume_info_s *info, uint32_t level)

Set volume value

audio_return_e(* _hal_backend_media_audio_funcs::set_volume_mute)(void *audio_handle, audio_volume_info_s *info, uint32_t mute)

Set volume ratio

audio_return_e(* _hal_backend_media_audio_funcs::set_volume_ratio)(void *audio_handle, audio_stream_info_s *info, double ratio)

Notify ducking activation

audio_return_e(* _hal_backend_media_audio_funcs::update_route)(void *audio_handle, audio_route_info_s *info)

Update route with option

audio_return_e(* _hal_backend_media_audio_funcs::update_route_option)(void *audio_handle, audio_route_option_s *option)

Notify stream connection

Typedef Documentation

typedef enum audio_direction audio_direction_e

Enumeration for audio direction.

Since:: HAL_MODULE_AUDIO 1.0

typedef struct audio_ducking_info audio_ducking_info_s

Ducking information including target role, duration and ratio.

Since:: HAL_MODULE_AUDIO 1.0

typedef enum audio_return audio_return_e

Enumeration for return codes.

Since:: HAL_MODULE_AUDIO 1.0

typedef struct audio_route_info audio_route_info_s

Route information including role and device.

Since:: HAL_MODULE_AUDIO 1.0

typedef struct audio_route_option audio_route_option_s

Route option including role, name and value.

Since:: HAL_MODULE_AUDIO 1.0

typedef enum audio_state audio_state_e

Enumeration for audio state.

Since:: HAL_MODULE_AUDIO 1.0

typedef struct audio_stream_info audio_stream_info_s

Stream information including role, direction and index.

Since:: HAL_MODULE_AUDIO 1.0

typedef struct audio_volume_info audio_volume_info_s

Volume information including type, gain and direction.

Since:: HAL_MODULE_AUDIO 1.0

typedef struct device_info device_info_s

Device information including type, direction and id.

Since:: HAL_MODULE_AUDIO 1.0

typedef struct _hal_backend_media_audio_funcs hal_backend_audio_funcs

The structure type of the audio HAL functions.

Since:: HAL_MODULE_AUDIO 1.0

typedef void(* message_cb)(const char *name, int value, void *user_data)

Called when audio hal implementation needs to send a message.

Since:: HAL_MODULE_AUDIO 1.0

Parameters:

[in]	name	The message name
[in]	value	The message value
[in]	user_data	The user data passed from the callback registration function

See also:: add_message_cb(); remove_message_cb()

Enumeration Type Documentation

enum audio_direction

Enumeration for audio direction.

Since:: HAL_MODULE_AUDIO 1.0

Enumerator:

AUDIO_DIRECTION_IN	Capture
AUDIO_DIRECTION_OUT	Playback

enum audio_return

Enumeration for return codes.

Since:: HAL_MODULE_AUDIO 1.0

Enumerator:

AUDIO_RET_OK	Error none
AUDIO_ERR_UNDEFINED	Undefined error
AUDIO_ERR_RESOURCE	Resource error
AUDIO_ERR_PARAMETER	Invalid parameters
AUDIO_ERR_IOCTL	ioctl error
AUDIO_ERR_INVALID_STATE	Invalid state
AUDIO_ERR_INTERNAL	Internal error
AUDIO_ERR_NOT_IMPLEMENTED	Not Implemented

enum audio_state

Enumeration for audio state.

Since:: HAL_MODULE_AUDIO 1.0

Enumerator:

AUDIO_STATE_OPEN	Open state
AUDIO_STATE_SETUP	Setup state
AUDIO_STATE_PREPARED	Prepared state
AUDIO_STATE_RUNNING	Running state
AUDIO_STATE_XRUN	Playback:underrun, Capture:overrun
AUDIO_STATE_DRAINING	Drain state
AUDIO_STATE_PAUSED	Pause state
AUDIO_STATE_SUSPENDED	Suspend state
AUDIO_STATE_DISCONNECTED	Disconnected state
AUDIO_STATE_UNKNOWN	Unknown state

Required Header

Overview

State Diagram

State Transitions

Typedefs

Data Structure Documentation

Data Fields

Field Documentation

Data Fields

Field Documentation

Data Fields

Field Documentation

Data Fields

Field Documentation

Data Fields

Field Documentation

Data Fields

Field Documentation

Data Fields

Field Documentation

Typedef Documentation

Enumeration Type Documentation