Audio HAL

Abstraction layer for audio board hardware, serves as an interface between the user application and the hardware driver for specific audio board like ESP32 LyraT.

The API provides data structures to configure sampling rates of ADC and DAC signal conversion, data bit widths, I2C stream parameters, and selection of signal channels connected to ADC and DAC. It also contains several specific functions to e.g. initialize the audio board, audio_hal_init(), control the volume, audio_hal_get_volume() and audio_hal_set_volume().

API Reference

Header File

components/audio_hal/include/audio_hal.h

Functions

audio_hal_handle_t audio_hal_init(audio_hal_codec_config_t *audio_hal_conf, audio_hal_func_t *audio_hal_func)

Initialize media codec driver.

Note

If selected codec has already been installed, it’ll return the audio_hal handle.

Parameters

audio_hal_conf – Configure structure audio_hal_config_t
audio_hal_func – Structure containing functions used to operate audio the codec chip

Returns

int, 0—success, others—fail

esp_err_t audio_hal_deinit(audio_hal_handle_t audio_hal)

Uninitialize media codec driver.

Parameters: audio_hal – reference function pointer for selected audio codec
Returns: int, 0—success, others—fail

esp_err_t audio_hal_ctrl_codec(audio_hal_handle_t audio_hal, audio_hal_codec_mode_t mode, audio_hal_ctrl_t audio_hal_ctrl)

Start/stop codec driver.

Parameters

audio_hal – reference function pointer for selected audio codec
mode – select media hal codec mode either encode/decode/or both to start from audio_hal_codec_mode_t
audio_hal_ctrl – select start stop state for specific mode

Returns

int, 0—success, others—fail

esp_err_t audio_hal_codec_iface_config(audio_hal_handle_t audio_hal, audio_hal_codec_mode_t mode, audio_hal_codec_i2s_iface_t *iface)

Set codec I2S interface samples rate & bit width and format either I2S or PCM/DSP.

Parameters

audio_hal – reference function pointer for selected audio codec
mode – select media hal codec mode either encode/decode/or both to start from audio_hal_codec_mode_t
iface – I2S sample rate (ex: 16000, 44100), I2S bit width (16, 24, 32),I2s format (I2S, PCM, DSP).

Returns

0 Success
-1 Error

esp_err_t audio_hal_set_mute(audio_hal_handle_t audio_hal, bool mute)

Set voice mute. Enables or disables DAC mute of a codec.

Note

audio_hal_get_volume will still give a non-zero number in mute state. It will be set to that number when speaker is unmuted.

Parameters

audio_hal – reference function pointer for selected audio codec
mute – true/false. If true speaker will be muted and if false speaker will be unmuted.

Returns

int, 0—success, others—fail

esp_err_t audio_hal_set_volume(audio_hal_handle_t audio_hal, int volume)

Set voice volume.

Note

if volume is 0, mute is enabled,range is 0-100.

Parameters

audio_hal – reference function pointer for selected audio codec
volume – value of volume in percent(%)

Returns

int, 0—success, others—fail

esp_err_t audio_hal_get_volume(audio_hal_handle_t audio_hal, int *volume)

get voice volume.

Note

if volume is 0, mute is enabled, range is 0-100.

Parameters

audio_hal – reference function pointer for selected audio codec
volume – value of volume in percent returned(%)

Returns

int, 0—success, others—fail

esp_err_t audio_hal_enable_pa(audio_hal_handle_t audio_hal, bool enable)

Enables or disables PA.

Parameters

audio_hal – reference function pointer for selected audio codec
enable – true/false.

Returns

int, 0—success, others—fail

Structures

struct audio_hal_codec_i2s_iface_t

I2s interface configuration for audio codec chip.

Public Members

audio_hal_iface_mode_t mode: audio codec chip mode

audio_hal_iface_format_t fmt: I2S interface format

audio_hal_iface_samples_t samples: I2S interface samples per second

audio_hal_iface_bits_t bits: i2s interface number of bits per sample

struct audio_hal_codec_config_t

Configure media hal for initialization of audio codec chip.

Public Members

audio_hal_adc_input_t adc_input: set adc channel

audio_hal_dac_output_t dac_output: set dac channel

audio_hal_codec_mode_t codec_mode: select codec mode: adc, dac or both

audio_hal_codec_i2s_iface_t i2s_iface: set I2S interface configuration

struct audio_hal

Configuration of functions and variables used to operate audio codec chip.

Public Members

esp_err_t (*audio_codec_initialize)(audio_hal_codec_config_t *codec_cfg): initialize codec

esp_err_t (*audio_codec_deinitialize)(void): deinitialize codec

esp_err_t (*audio_codec_ctrl)(audio_hal_codec_mode_t mode, audio_hal_ctrl_t ctrl_state): control codec mode and state

esp_err_t (*audio_codec_config_iface)(audio_hal_codec_mode_t mode, audio_hal_codec_i2s_iface_t *iface): configure i2s interface

esp_err_t (*audio_codec_set_mute)(bool mute): set codec mute

esp_err_t (*audio_codec_set_volume)(int volume): set codec volume

esp_err_t (*audio_codec_get_volume)(int *volume): get codec volume

esp_err_t (*audio_codec_enable_pa)(bool enable): enable pa

xSemaphoreHandle audio_hal_lock: semaphore of codec

void *handle: handle of audio codec

Macros

AUDIO_HAL_VOL_DEFAULT

Type Definitions

typedef struct audio_hal *audio_hal_handle_t

typedef struct audio_hal audio_hal_func_t: Configuration of functions and variables used to operate audio codec chip.

Enumerations

enum audio_hal_codec_mode_t

Select media hal codec mode.

Values:

enumerator AUDIO_HAL_CODEC_MODE_ENCODE: select adc

enumerator AUDIO_HAL_CODEC_MODE_DECODE: select dac

enumerator AUDIO_HAL_CODEC_MODE_BOTH: select both adc and dac

enumerator AUDIO_HAL_CODEC_MODE_LINE_IN: set adc channel

enum audio_hal_adc_input_t

Select adc channel for input mic signal.

Values:

enumerator AUDIO_HAL_ADC_INPUT_LINE1: mic input to adc channel 1

enumerator AUDIO_HAL_ADC_INPUT_LINE2: mic input to adc channel 2

enumerator AUDIO_HAL_ADC_INPUT_ALL: mic input to both channels of adc

enumerator AUDIO_HAL_ADC_INPUT_DIFFERENCE: mic input to adc difference channel

enum audio_hal_dac_output_t

Select channel for dac output.

Values:

enumerator AUDIO_HAL_DAC_OUTPUT_LINE1: dac output signal to channel 1

enumerator AUDIO_HAL_DAC_OUTPUT_LINE2: dac output signal to channel 2

enumerator AUDIO_HAL_DAC_OUTPUT_ALL: dac output signal to both channels

enum audio_hal_ctrl_t

Select operating mode i.e. start or stop for audio codec chip.

Values:

enumerator AUDIO_HAL_CTRL_STOP: set stop mode

enumerator AUDIO_HAL_CTRL_START: set start mode

enum audio_hal_iface_mode_t

Select I2S interface operating mode i.e. master or slave for audio codec chip.

Values:

enumerator AUDIO_HAL_MODE_SLAVE: set slave mode

enumerator AUDIO_HAL_MODE_MASTER: set master mode

enum audio_hal_iface_samples_t

Select I2S interface samples per second.

Values:

enumerator AUDIO_HAL_08K_SAMPLES: set to 8k samples per second

enumerator AUDIO_HAL_11K_SAMPLES: set to 11.025k samples per second

enumerator AUDIO_HAL_16K_SAMPLES: set to 16k samples in per second

enumerator AUDIO_HAL_22K_SAMPLES: set to 22.050k samples per second

enumerator AUDIO_HAL_24K_SAMPLES: set to 24k samples in per second

enumerator AUDIO_HAL_32K_SAMPLES: set to 32k samples in per second

enumerator AUDIO_HAL_44K_SAMPLES: set to 44.1k samples per second

enumerator AUDIO_HAL_48K_SAMPLES: set to 48k samples per second

enum audio_hal_iface_bits_t

Select I2S interface number of bits per sample.

Values:

enumerator AUDIO_HAL_BIT_LENGTH_16BITS: set 16 bits per sample

enumerator AUDIO_HAL_BIT_LENGTH_24BITS: set 24 bits per sample

enumerator AUDIO_HAL_BIT_LENGTH_32BITS: set 32 bits per sample

enum audio_hal_iface_format_t

Select I2S interface format for audio codec chip.

Values:

enumerator AUDIO_HAL_I2S_NORMAL: set normal I2S format

enumerator AUDIO_HAL_I2S_LEFT: set all left format

enumerator AUDIO_HAL_I2S_RIGHT: set all right format

enumerator AUDIO_HAL_I2S_DSP: set dsp/pcm format

Provide feedback about this document