MT2523 API Reference  LinkIt SDK v4
AUDIO

This section introduces the Audio APIs including terms and acronyms, supported features, software architecture, details on how to use this driver, Audio function groups, enums, structures and functions. More...

Overview

This section introduces the Audio APIs including terms and acronyms, supported features, software architecture, details on how to use this driver, Audio function groups, enums, structures and functions.

How to use this driver

The APIs are grouped based on their functionality for more convenient usage. For more information about each function, please click on the function name.

Functions

hal_audio_status_t hal_audio_init (void)
 Initializes basic settings of the audio hardware. More...
 
hal_audio_status_t hal_audio_deinit (void)
 Deinitialize audio settings. More...
 
hal_audio_status_t hal_audio_set_stream_out_sampling_rate (hal_audio_sampling_rate_t sample_rate)
 Set the sampling rate of the audio output stream. More...
 
hal_audio_status_t hal_audio_set_stream_out_channel_number (hal_audio_channel_number_t channel_number)
 Set the audio output channel number. More...
 
hal_audio_status_t hal_audio_start_stream_out (hal_audio_active_type_t active_type)
 Power on the audio out. More...
 
void hal_audio_stop_stream_out (void)
 Power off the stream out path. More...
 
hal_audio_status_t hal_audio_set_stream_out_volume (uint32_t digital_volume_index, uint32_t analog_volume_index)
 Set audio output the volume. More...
 
void hal_audio_mute_stream_out (bool mute)
 Mute the audio output stream. More...
 
hal_audio_status_t hal_audio_set_stream_out_device (hal_audio_device_t device)
 Set the audio output device. More...
 
hal_audio_status_t hal_audio_write_stream_out (const void *buffer, uint32_t size)
 Write data to audio output. More...
 
hal_audio_status_t hal_audio_get_stream_out_sample_count (uint32_t *sample_count)
 Query available free space for the output. More...
 
hal_audio_status_t hal_audio_register_stream_out_callback (hal_audio_stream_out_callback_t callback, void *user_data)
 Register the callback function for output data. More...
 
hal_audio_status_t hal_audio_set_stream_in_sampling_rate (hal_audio_sampling_rate_t sample_rate)
 Set audio input stream sampling rate. More...
 
hal_audio_status_t hal_audio_set_stream_in_channel_number (hal_audio_channel_number_t channel_number)
 Set audio input channel number. More...
 
hal_audio_status_t hal_audio_start_stream_in (hal_audio_active_type_t active_type)
 Power on the audio in. More...
 
void hal_audio_stop_stream_in (void)
 Power off the stream in path. More...
 
hal_audio_status_t hal_audio_set_stream_in_volume (uint32_t digital_volume_index, uint32_t analog_volume_index)
 Set audio input volume. More...
 
void hal_audio_mute_stream_in (bool mute)
 Mute the audio input stream. More...
 
hal_audio_status_t hal_audio_set_stream_in_device (hal_audio_device_t device)
 Set audio input device. More...
 
hal_audio_status_t hal_audio_read_stream_in (void *buffer, uint32_t sample_count)
 Recieve data from the audio input. More...
 
hal_audio_status_t hal_audio_get_stream_in_sample_count (uint32_t *sample_count)
 Query the available input data sample count. More...
 
hal_audio_status_t hal_audio_register_stream_in_callback (hal_audio_stream_in_callback_t callback, void *user_data)
 Register the callback function for input data. More...
 
hal_audio_status_t hal_audio_get_memory_size (uint32_t *memory_size)
 Query the size of needed memory to be allocated for internal use in audio driver. More...
 
hal_audio_status_t hal_audio_set_memory (void *memory)
 Hand over allocated memory to audio driver. More...
 
hal_audio_status_t hal_audio_get_audio_clock (uint32_t *sample_count)
 Get audio clock. More...
 

Modules

 Enum
 
 Struct
 
 Typedef
 

Function Documentation

hal_audio_status_t hal_audio_deinit ( void  )

Deinitialize audio settings.

Returns
HAL_AUDIO_STATUS_OK, if OK.
See also
hal_audio_init()
hal_audio_status_t hal_audio_get_audio_clock ( uint32_t *  sample_count)

Get audio clock.

Parameters
[out]sample_countis a pointer to the accumulated audio sample count.
Returns
HAL_AUDIO_STATUS_OK, if OK.
Note
The function is called to get the accumulated audio sample count written to audio hardware. One pair of L / R counts as one audio sample.
hal_audio_status_t hal_audio_get_memory_size ( uint32_t *  memory_size)

Query the size of needed memory to be allocated for internal use in audio driver.

Parameters
[out]memory_sizeis the amount of memory required by the audio driver for an internal use (in bytes).
Returns
HAL_AUDIO_STATUS_OK, if OK.
Note
The function should be called at least before hal_audio_start_stream_in() or hal_audio_start_stream_out() to ensure enough memory can be used internally.
See also
hal_audio_set_memory()
hal_audio_status_t hal_audio_get_stream_in_sample_count ( uint32_t *  sample_count)

Query the available input data sample count.

Parameters
[out]sample_countthe available amount of received data (in bytes).
Returns
HAL_AUDIO_STATUS_OK, if OK.
Note
Call this function before hal_audio_read_stream_in() to check the content availability in an input buffer.
See also
hal_audio_read_stream_in()
hal_audio_status_t hal_audio_get_stream_out_sample_count ( uint32_t *  sample_count)

Query available free space for the output.

Parameters
[out]sample_countis the available output sample count (in bytes).
Returns
HAL_AUDIO_STATUS_OK, if OK.
Note
Call this function before hal_audio_write_stream_out() to make sure there is enough free space to write the output.
See also
hal_audio_write_stream_out()
hal_audio_status_t hal_audio_init ( void  )

Initializes basic settings of the audio hardware.

Returns
HAL_AUDIO_STATUS_OK, if OK.
Note
This function should at least be called once after system restarts and before using any audio functionality.
See also
hal_audio_deinit()
void hal_audio_mute_stream_in ( bool  mute)

Mute the audio input stream.

Parameters
[in]muteis a flag to set the audio on/off silent.
Example
1 hal_audio_mute_stream_in(true);
void hal_audio_mute_stream_out ( bool  mute)

Mute the audio output stream.

Parameters
[in]muteis a flag to set the audio on/off silent.
example
1 hal_audio_mute_stream_out(true);
hal_audio_status_t hal_audio_read_stream_in ( void *  buffer,
uint32_t  sample_count 
)

Recieve data from the audio input.

Parameters
[in]bufferis a pointer to a user defined buffer.
[in]sample_countis the amount of data received (in bytes).
Returns
HAL_AUDIO_STATUS_OK, if OK.
See also
hal_audio_get_stream_in_sample_count()
hal_audio_status_t hal_audio_register_stream_in_callback ( hal_audio_stream_in_callback_t  callback,
void *  user_data 
)

Register the callback function for input data.

Parameters
[in]callbackis the function pointer of callback for input data control.
[in]user_datais extended parameter for user.
Returns
HAL_AUDIO_STATUS_OK, if OK.
Example
1 hal_audio_register_stream_in_callback(stream_in_callback, user_data);
hal_audio_status_t hal_audio_register_stream_out_callback ( hal_audio_stream_out_callback_t  callback,
void *  user_data 
)

Register the callback function for output data.

Parameters
[in]callbackis the function pointer of callback for output data control
[in]user_datais a user defined extended parameter.
Returns
HAL_AUDIO_STATUS_OK, if OK.
hal_audio_status_t hal_audio_set_memory ( void *  memory)

Hand over allocated memory to audio driver.

Parameters
[in]memoryis a pointer to an allocated memory. It should be 4 bytes aligned.
Returns
HAL_AUDIO_STATUS_OK, if OK.
Note
The function should be called after user allocates enough memory that is at least greater than the size queried from hal_audio_get_memory_size().
See also
hal_audio_get_memory_size()
hal_audio_status_t hal_audio_set_stream_in_channel_number ( hal_audio_channel_number_t  channel_number)

Set audio input channel number.

Parameters
[in]channel_numberis to set input channel number. For more details, please refer to hal_audio_channel_number_t.
Returns
HAL_AUDIO_STATUS_OK, if channel number is valid.
Example
1 hal_audio_set_stream_in_channel_number(HAL_AUDIO_MONO);
hal_audio_status_t hal_audio_set_stream_in_device ( hal_audio_device_t  device)

Set audio input device.

Parameters
[in]deviceis the input component. For more details, please refer to hal_audio_device_t.
Returns
HAL_AUDIO_STATUS_OK, if input device is valid.
Example
1 hal_audio_set_stream_in_device(HAL_AUDIO_DEVICE_MAIN_MIC);
hal_audio_status_t hal_audio_set_stream_in_sampling_rate ( hal_audio_sampling_rate_t  sample_rate)

Set audio input stream sampling rate.

Parameters
[in]sample_rateis to set input sampling rate. Please refers to hal_audio_sampling_rate_t.
Returns
HAL_AUDIO_STATUS_OK, if sampling rate is valid
Note
Only 8kHz and 16kHz is supported.
Example
1 hal_audio_set_stream_in_sampling_rate(HAL_AUDIO_SAMPLING_RATE_8KHZ);
hal_audio_status_t hal_audio_set_stream_in_volume ( uint32_t  digital_volume_index,
uint32_t  analog_volume_index 
)

Set audio input volume.

Parameters
[in]digital_volume_indexis to set a digital gain in centi-db in hex (FFFFFE0C equal to -5db). Gain range: depend on the gain map.
[in]analog_volume_indexis to set digital gain in centi-db in hex (FFFFFE0C equal to -5db). Gain range: depends on the hardware design and gain map.
Returns
HAL_AUDIO_STATUS_OK, if input volume range is valid.
hal_audio_status_t hal_audio_set_stream_out_channel_number ( hal_audio_channel_number_t  channel_number)

Set the audio output channel number.

Parameters
[in]channel_numberis to set the output channel number. For more details, please refer to hal_audio_channel_number_t.
Returns
HAL_AUDIO_STATUS_OK, if channel number is valid.
hal_audio_status_t hal_audio_set_stream_out_device ( hal_audio_device_t  device)

Set the audio output device.

Parameters
[in]deviceis the ouput component. For more details, please refer to hal_audio_device_t.
Returns
HAL_AUDIO_STATUS_OK, if output device is valid.
hal_audio_status_t hal_audio_set_stream_out_sampling_rate ( hal_audio_sampling_rate_t  sample_rate)

Set the sampling rate of the audio output stream.

Parameters
[in]sample_rateis to set the output sampling rate. For more details, please refer to hal_audio_sampling_rate_t.
Returns
HAL_AUDIO_STATUS_OK, if sampling rate is valid.
Note
If the audio function is for speech, such as HAL_AUDIO_PLAYBACK_VOICE/ HAL_AUDIO_RECORD_VOICE/ HAL_AUDIO_BLUETOOTH_CALL, only 8kHz or 16kHz is available.
hal_audio_status_t hal_audio_set_stream_out_volume ( uint32_t  digital_volume_index,
uint32_t  analog_volume_index 
)

Set audio output the volume.

Parameters
[in]digital_volume_indexis to set digital gain in centi-db in hex (FFFFFE0C equal to -5db). Gain range: depends on the gain map.
[in]analog_volume_indexis to set digital gain in centi-db in hex (FFFFFE0C equal to -5db). Gain range: depends on the hardware design and gain map.
Returns
HAL_AUDIO_STATUS_OK, if output volume range is valid.
hal_audio_status_t hal_audio_start_stream_in ( hal_audio_active_type_t  active_type)

Power on the audio in.

Parameters
[in]active_typeis to set input function type. For more details, please refer to hal_audio_active_type_t.
Returns
HAL_AUDIO_STATUS_OK, if input path type is valid.
See also
hal_audio_stop_stream_in()
Example
1 hal_audio_start_stream_in(HAL_AUDIO_RECORD_VOICE);
hal_audio_status_t hal_audio_start_stream_out ( hal_audio_active_type_t  active_type)

Power on the audio out.

Parameters
[in]active_typeis to set the audio output function type. For more details, please refer to hal_audio_active_type_t.
Returns
HAL_AUDIO_STATUS_OK, if the output path type is valid
See also
hal_audio_stop_stream_out()
void hal_audio_stop_stream_in ( void  )

Power off the stream in path.

See also
hal_audio_start_stream_in()
Example
1 hal_audio_stop_stream_in();
void hal_audio_stop_stream_out ( void  )

Power off the stream out path.

See also
hal_audio_start_stream_out()
hal_audio_status_t hal_audio_write_stream_out ( const void *  buffer,
uint32_t  size 
)

Write data to audio output.

Parameters
[in]bufferis the pointer to output data.
[in]sizeis the available free space of the output buffer (in bytes).
Returns
HAL_AUDIO_STATUS_OK, if OK.
See also
hal_audio_get_stream_out_sample_count()