MT2523 API Reference  LinkIt SDK v4

This section introduces the Bluetooth codec APIs including terms and acronyms, supported features, details on how to use the codec, function groups, enums, structures and functions. More...

Overview

This section introduces the Bluetooth codec APIs including terms and acronyms, supported features, details on how to use the codec, function groups, enums, structures and functions.

The Bluetooth codec is used for A2DP and HFP profiles.

Terms and acronyms

Terms Details
A2DP The Advanced Audio Distribution Profile (A2DP) defines the protocols and procedures that implement distribution of audio content of high-quality in mono or stereo on ACL channels.
HFP The Hands-free Profile (HFP) defines the device acting as the audio gateway's remote audio input and output mechanism.
AAC Advanced Audio Coding (AAC) is an audio coding standard for lossy digital audio compression.
SBC The Low Complexity Subband Coding (SBC) is an audio subband codec specified by the Bluetooth Special Interest Group (SIG) for the Advanced Audio Distribution Profile (A2DP). SBC is a digital audio encoder and decoder used to transfer data to Bluetooth audio output devices like headphones or loudspeakers.
VBR Variable bitrate (VBR) is a term used in telecommunications and computing that relates to the bitrate used in sound or video encoding.

How to use this module

Functions

bt_media_handle_tbt_codec_a2dp_open (bt_codec_a2dp_callback_t callback, const bt_codec_a2dp_audio_t *param)
 This function opens the A2DP audio codec. More...
 
bt_codec_media_status_t bt_codec_a2dp_close (bt_media_handle_t *handle)
 This function closes the A2DP audio codec. More...
 
bt_codec_media_status_t bt_codec_hfp_mix_stream_out (bt_codec_media_hfp_mix_stream_out_method_t mix_method, void *buffer, uint32_t sample_count)
 Mix a tone to the stream out tone. More...
 
bt_codec_media_status_t bt_codec_hfp_get_mix_stream_out_sample_count (uint32_t *sample_count)
 Query the sample_count of mix stream out buffer. More...
 
bt_codec_media_status_t bt_codec_hfp_unregister_mix_stream_out_data_callback (void)
 Unregister the callback function for mix stream out data. More...
 
bt_codec_media_status_t bt_codec_hfp_register_mix_stream_out_data_callback (bt_codec_hfp_mix_stream_out_data_callback_t callback, void *user_data)
 Register the callback function for mixing stream out data. More...
 
bt_codec_media_status_t bt_codec_hfp_read_stream_in (void *buffer, uint32_t sample_count)
 Recieve data from stream in. More...
 
bt_codec_media_status_t bt_codec_hfp_get_stream_in_sample_count (uint32_t *sample_count)
 Query the sample_count of stream in buffer. More...
 
bt_codec_media_status_t bt_codec_hfp_unregister_get_stream_in_data_callback (void)
 Unregister the callback function for getting stream in data. More...
 
bt_codec_media_status_t bt_codec_hfp_register_get_stream_in_data_callback (bt_codec_hfp_get_stream_in_data_callback_t callback, void *user_data)
 Register the callback function for get stream in data. More...
 
bt_codec_media_status_t bt_codec_hfp_set_device_path (bt_codec_hfp_device_path_t device_path)
 This function sets the HFP device path. More...
 
bt_media_handle_tbt_codec_hfp_open (bt_codec_hfp_callback_t callback, const bt_codec_hfp_audio_t *param)
 This function opens the HFP audio codec. More...
 
bt_codec_media_status_t bt_codec_hfp_close (bt_media_handle_t *handle)
 This function closes the HFP codec. More...
 
bt_codec_media_status_t bt_codec_a2dp_aws_set_flag (bt_media_handle_t *handle, bool flag)
 This function sets the advanced wireless stereo flag. More...
 
bt_codec_media_status_t bt_codec_a2dp_aws_set_initial_sync (bt_media_handle_t *handle)
 This function sets the advanced wireless stereo initial synchronization. More...
 
bt_codec_media_status_t bt_codec_a2dp_aws_get_consumed_data_count (bt_media_handle_t *handle, bt_codec_a2dp_data_count_t *information)
 This function gets the advanced wireless stereo consumed data count. More...
 
bt_codec_media_status_t bt_codec_a2dp_aws_get_silence_frame_information (bt_media_handle_t *handle, bt_codec_a2dp_bitstream_t *information)
 This function gets the advanced wireless stereo silence frame information for one silence frame. More...
 
bt_codec_media_status_t bt_codec_a2dp_aws_fill_silence_frame (bt_media_handle_t *handle, bt_codec_a2dp_buffer_t *data, uint32_t frame_count)
 This function fills the advanced wireless stereo silence frames to target data buffer. More...
 
bt_codec_media_status_t bt_codec_a2dp_aws_parse_data_information (bt_media_handle_t *handle, bt_codec_a2dp_buffer_t *data, bt_codec_a2dp_bitstream_t *information)
 This function parses the advanced wireless stereo packet data information. More...
 
bt_codec_media_status_t bt_codec_a2dp_aws_get_clock_skew_status (bt_media_handle_t *handle, bt_codec_aws_clock_skew_status_t *status)
 This function gets the advanced wireless stereo clock skew status. More...
 
bt_codec_media_status_t bt_codec_a2dp_aws_set_clock_skew_compensation_value (bt_media_handle_t *handle, int32_t sample_count)
 This function sets the advanced wireless stereo clock skew compensation value. More...
 
bt_codec_media_status_t bt_codec_a2dp_aws_get_audio_latency (bt_media_handle_t *handle, uint32_t sampling_rate, uint32_t *latency_us)
 This function gets the advanced wireless stereo audio latency. More...
 

Modules

 Define
 
 Enum
 
 Struct
 

Function Documentation

bt_codec_media_status_t bt_codec_a2dp_aws_fill_silence_frame ( bt_media_handle_t handle,
bt_codec_a2dp_buffer_t data,
uint32_t  frame_count 
)

This function fills the advanced wireless stereo silence frames to target data buffer.

Parameters
[in]handleis the A2DP codec handle.
[out]datapoints to the target data buffer structure.
[in]frame_countis the silence frame count.
Returns
If the operation completed successfully, the return value is BT_CODEC_MEDIA_STATUS_OK, otherwise the return value is BT_CODEC_MEDIA_STATUS_ERROR.
bt_codec_media_status_t bt_codec_a2dp_aws_get_audio_latency ( bt_media_handle_t handle,
uint32_t  sampling_rate,
uint32_t *  latency_us 
)

This function gets the advanced wireless stereo audio latency.

Parameters
[in]handleis the A2DP codec handle.
[in]sampling_rateis the audio sampling rate in Hz.
[out]latency_uspoints to the audio latency in microsecond.
Returns
If the operation completed successfully, the return value is BT_CODEC_MEDIA_STATUS_OK, otherwise the return value is BT_CODEC_MEDIA_STATUS_ERROR.
bt_codec_media_status_t bt_codec_a2dp_aws_get_clock_skew_status ( bt_media_handle_t handle,
bt_codec_aws_clock_skew_status_t status 
)

This function gets the advanced wireless stereo clock skew status.

Parameters
[in]handleis the A2DP codec handle.
[out]statuspoints to the clock skew status.
Returns
If the operation completed successfully, the return value is BT_CODEC_MEDIA_STATUS_OK, otherwise the return value is BT_CODEC_MEDIA_STATUS_ERROR.
bt_codec_media_status_t bt_codec_a2dp_aws_get_consumed_data_count ( bt_media_handle_t handle,
bt_codec_a2dp_data_count_t information 
)

This function gets the advanced wireless stereo consumed data count.

Parameters
[in]handleis the A2DP codec handle.
[out]informationpoints to the consumed data count information.
Returns
If the operation completed successfully, the return value is BT_CODEC_MEDIA_STATUS_OK, otherwise the return value is BT_CODEC_MEDIA_STATUS_ERROR.
bt_codec_media_status_t bt_codec_a2dp_aws_get_silence_frame_information ( bt_media_handle_t handle,
bt_codec_a2dp_bitstream_t information 
)

This function gets the advanced wireless stereo silence frame information for one silence frame.

Parameters
[in]handleis the A2DP codec handle.
[out]informationpoints to the silence frame information for one silence frame.
Returns
If the operation completed successfully, the return value is BT_CODEC_MEDIA_STATUS_OK, otherwise the return value is BT_CODEC_MEDIA_STATUS_ERROR.
bt_codec_media_status_t bt_codec_a2dp_aws_parse_data_information ( bt_media_handle_t handle,
bt_codec_a2dp_buffer_t data,
bt_codec_a2dp_bitstream_t information 
)

This function parses the advanced wireless stereo packet data information.

Parameters
[in]handleis the A2DP codec handle.
[in]datapoints to the packet data buffer structure.
[out]informationpoints to the packet data buffer information.
Returns
If the operation completed successfully, the return value is BT_CODEC_MEDIA_STATUS_OK, otherwise the return value is BT_CODEC_MEDIA_STATUS_ERROR.
bt_codec_media_status_t bt_codec_a2dp_aws_set_clock_skew_compensation_value ( bt_media_handle_t handle,
int32_t  sample_count 
)

This function sets the advanced wireless stereo clock skew compensation value.

Parameters
[in]handleis the A2DP codec handle.
[in]sample_countis the audio sample count to be compensated. One pair of L / R counts as one audio sample.
Returns
If the operation completed successfully, the return value is BT_CODEC_MEDIA_STATUS_OK, otherwise the return value is BT_CODEC_MEDIA_STATUS_ERROR.
bt_codec_media_status_t bt_codec_a2dp_aws_set_flag ( bt_media_handle_t handle,
bool  flag 
)

This function sets the advanced wireless stereo flag.

Parameters
[in]handleis the A2DP codec handle.
[in]flagis used to determine to turn on or turn off AWS mechanism. 1: turn on AWS, 0: turn off AWS.
Returns
If the operation completed successfully, the return value is BT_CODEC_MEDIA_STATUS_OK, otherwise the return value is BT_CODEC_MEDIA_STATUS_ERROR.
bt_codec_media_status_t bt_codec_a2dp_aws_set_initial_sync ( bt_media_handle_t handle)

This function sets the advanced wireless stereo initial synchronization.

Parameters
[in]handleis the A2DP codec handle.
Returns
If the operation completed successfully, the return value is BT_CODEC_MEDIA_STATUS_OK, otherwise the return value is BT_CODEC_MEDIA_STATUS_ERROR.
bt_codec_media_status_t bt_codec_a2dp_close ( bt_media_handle_t handle)

This function closes the A2DP audio codec.

Parameters
[in]handleis the A2DP codec handle.
Returns
If the operation completed successfully, the return value is BT_CODEC_MEDIA_STATUS_OK, otherwise the return value is BT_CODEC_MEDIA_STATUS_ERROR.
bt_media_handle_t* bt_codec_a2dp_open ( bt_codec_a2dp_callback_t  callback,
const bt_codec_a2dp_audio_t param 
)

This function opens the A2DP audio codec.

Parameters
[in]callbackis a pointer to the callback function for the A2DP data control.
[in]paramis the settings of the A2DP codec.
Returns
Media handle of the A2DP. Please refer to bt_media_handle_t.
bt_codec_media_status_t bt_codec_hfp_close ( bt_media_handle_t handle)

This function closes the HFP codec.

Parameters
[in]handleis the HFP codec handle.
Returns
BT_CODEC_MEDIA_STATUS_OK, if the operation completed successfully, BT_CODEC_MEDIA_STATUS_ERROR, if an error occurred.
bt_codec_media_status_t bt_codec_hfp_get_mix_stream_out_sample_count ( uint32_t *  sample_count)

Query the sample_count of mix stream out buffer.

Parameters
[out]sample_countis the size of the mix stream out buffer (in bytes).
Returns
#BT_CODEC_MEDIA_STATUS_MEDIA_OK, if OK.
Note
Call this function before bt_codec_hfp_mix_stream_out() to known the maximum mix stream stream out buffer.
See also
bt_codec_hfp_mix_stream_out()
bt_codec_media_status_t bt_codec_hfp_get_stream_in_sample_count ( uint32_t *  sample_count)

Query the sample_count of stream in buffer.

Parameters
[out]sample_countis the size of stream in buffer (in bytes).
Returns
#BT_CODEC_MEDIA_STATUS_MEDIA_OK, if OK.
Note
Call this function before bt_codec_hfp_read_stream_in() to know the maximum stream in buffer.
See also
bt_codec_hfp_read_stream_in()
bt_codec_media_status_t bt_codec_hfp_mix_stream_out ( bt_codec_media_hfp_mix_stream_out_method_t  mix_method,
void *  buffer,
uint32_t  sample_count 
)

Mix a tone to the stream out tone.

Parameters
[in]mix_methodis to indicate which mix method will be used.
[in]*bufferis the tone buffer that will mix with stream out tone.
[in]sample_countis the size of *buffer that will mix with stream out tone (in bytes). It will equal or less than the sample_count that get from bt_codec_hfp_get_mix_stream_out_sample_count().
Returns
#BT_CODEC_MEDIA_STATUS_MEDIA_OK, if OK.
See also
bt_codec_hfp_get_mix_stream_out_sample_count()
bt_media_handle_t* bt_codec_hfp_open ( bt_codec_hfp_callback_t  callback,
const bt_codec_hfp_audio_t param 
)

This function opens the HFP audio codec.

Parameters
[in]callbackis a pointer to the callback function for HFP error handling.
[in]paramis the HFP codec settings.
Returns
Media handle of the HFP.
bt_codec_media_status_t bt_codec_hfp_read_stream_in ( void *  buffer,
uint32_t  sample_count 
)

Recieve data from stream in.

Parameters
[in]bufferis a pointer to a user defined buffer.
[in]sample_countis the amount of data received (in bytes).
Returns
#BT_CODEC_MEDIA_STATUS_MEDIA_OK, if OK.
See also
bt_codec_hfp_get_stream_in_sample_count()
bt_codec_media_status_t bt_codec_hfp_register_get_stream_in_data_callback ( bt_codec_hfp_get_stream_in_data_callback_t  callback,
void *  user_data 
)

Register the callback function for get stream in data.

Parameters
[in]callbackis the function pointer of callback for getting stream int data.
[in]user_datais extended parameter for user.
Returns
#BT_CODEC_MEDIA_STATUS_MEDIA_OK, if OK.
bt_codec_media_status_t bt_codec_hfp_register_mix_stream_out_data_callback ( bt_codec_hfp_mix_stream_out_data_callback_t  callback,
void *  user_data 
)

Register the callback function for mixing stream out data.

Parameters
[in]callbackis the function pointer of callback for mix stream out data control.
[in]user_datais extended parameter for user.
Returns
#BT_CODEC_MEDIA_STATUS_MEDIA_OK, if OK.
bt_codec_media_status_t bt_codec_hfp_set_device_path ( bt_codec_hfp_device_path_t  device_path)

This function sets the HFP device path.

Parameters
[in]piter.
Returns
If the operation completed successfully, the return value is #BT_CODEC_MEDIA_STATUS_MEDIA_OK, otherwise the return value is #BT_CODEC_MEDIA_STATUS_MEDIA_ERROR.
bt_codec_media_status_t bt_codec_hfp_unregister_get_stream_in_data_callback ( void  )

Unregister the callback function for getting stream in data.

Returns
#BT_CODEC_MEDIA_STATUS_MEDIA_OK, if OK.
bt_codec_media_status_t bt_codec_hfp_unregister_mix_stream_out_data_callback ( void  )

Unregister the callback function for mix stream out data.

Returns
#BT_CODEC_MEDIA_STATUS_MEDIA_OK, if OK.