Bluetooth® A2DP API

Application Examples

API Reference

Header File

  • components/bt/host/bluedroid/api/include/api/esp_a2dp_api.h

  • This header file can be included with:

    #include "esp_a2dp_api.h"

  • This header file is a part of the API provided by the bt component. To declare that your component depends on bt, add the following to your CMakeLists.txt:

    REQUIRES bt

    or

    PRIV_REQUIRES bt

Functions

esp_a2d_audio_buff_t *esp_a2d_audio_buff_alloc(uint16_t size)

Allocate a audio buffer to store and send audio data, can be used in both sink and source.

Parameters:

size -- [in] buffer size to allocate

Returns:

allocated audio buffer, if Bluedroid is not enabled, no memory, or size is zeros, will return NULL

void esp_a2d_audio_buff_free(esp_a2d_audio_buff_t *audio_buf)

Free a audio buffer allocated by esp_a2d_audio_buff_alloc.

Parameters:

audio_buf -- [in] audio buffer to free

esp_err_t esp_a2d_register_callback(esp_a2d_cb_t callback)

Register application callback function to A2DP module. This function should be called only after esp_bluedroid_enable() completes successfully, used by both A2DP source and sink.

Parameters:

callback -- [in] A2DP event callback function

Returns:

  • ESP_OK: success

  • ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled

  • ESP_FAIL: if callback is a NULL function pointer

esp_err_t esp_a2d_sink_register_audio_data_callback(esp_a2d_sink_audio_data_cb_t callback)

Register A2DP sink audio data output function, the output format is undecoded audio data frame in esp_a2d_audio_buff_t, user shall call esp_a2d_audio_buff_free to free the buff when the data is consumed.

Parameters:

callback -- [in] A2DP sink audio data callback function

Returns:

  • ESP_OK: success

  • ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled

  • ESP_FAIL: others

esp_err_t esp_a2d_sink_init(void)

Initialize the bluetooth A2DP sink module. This function should be called after esp_bluedroid_enable() completes successfully, and ESP_A2D_PROF_STATE_EVT with ESP_A2D_INIT_SUCCESS will reported to the APP layer. Note: A2DP can work independently. If you want to use AVRC together, you should initiate AVRC first. This function should be called after esp_bluedroid_enable() completes successfully.

Returns:

  • ESP_OK: if the initialization request is sent successfully

  • ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled

  • ESP_FAIL: others

esp_err_t esp_a2d_sink_register_stream_endpoint(uint8_t seid, const esp_a2d_mcc_t *mcc)

Register a a2dp sink Stream Endpoint (SEP) with specific codec capability, shall register SEP after a2dp sink initializing and before a2dp connection establishing. Register the same SEP index repeatedly will overwrite the old one.

Parameters:

  • seid -- [in] local SEP identifier, start from 0, less than ESP_A2D_MAX_SEPS

  • mcc -- [in] codec capability, currently only supports SBC

Returns:

  • ESP_OK: success

  • ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled

  • ESP_ERR_INVALID_ARG: invalid parameter

  • ESP_FAIL: others

esp_err_t esp_a2d_sink_deinit(void)

De-initialize for A2DP sink module. This function should be called only after esp_bluedroid_enable() completes successfully, and ESP_A2D_PROF_STATE_EVT with ESP_A2D_DEINIT_SUCCESS will reported to APP layer.

Returns:

  • ESP_OK: if the deinitialization request is sent successfully

  • ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled

  • ESP_FAIL: others

esp_err_t esp_a2d_sink_connect(esp_bd_addr_t remote_bda)

Connect to remote bluetooth A2DP source device. This API must be called after esp_a2d_sink_init() and before esp_a2d_sink_deinit().

Parameters:

remote_bda -- [in] remote bluetooth device address

Returns:

  • ESP_OK: connect request is sent to lower layer successfully

  • ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled

  • ESP_FAIL: others

esp_err_t esp_a2d_sink_disconnect(esp_bd_addr_t remote_bda)

Disconnect from the remote A2DP source device. This API must be called after esp_a2d_sink_init() and before esp_a2d_sink_deinit().

Parameters:

remote_bda -- [in] remote bluetooth device address

Returns:

  • ESP_OK: disconnect request is sent to lower layer successfully

  • ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled

  • ESP_FAIL: others

esp_err_t esp_a2d_sink_set_delay_value(uint16_t delay_value)

Set delay reporting value. The delay value of sink is caused by buffering (including protocol stack and application layer), decoding and rendering. The default delay value is 120ms, if the set value is less than 120ms, the setting will fail. This API must be called after esp_a2d_sink_init() and before esp_a2d_sink_deinit().

Parameters:

delay_value -- [in] reporting value is in 1/10 millisecond

Returns:

  • ESP_OK: delay value is sent to lower layer successfully

  • ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled

  • ESP_FAIL: others

esp_err_t esp_a2d_sink_get_delay_value(void)

Get delay reporting value. This API must be called after esp_a2d_sink_init() and before esp_a2d_sink_deinit().

Returns:

  • ESP_OK: if the request is sent successfully

  • ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled

  • ESP_FAIL: others

esp_err_t esp_a2d_media_ctrl(esp_a2d_media_ctrl_t ctrl)

Media control commands. This API can be used for both A2DP sink and source and must be called after esp_a2d_sink_init() and before esp_a2d_sink_deinit().

Parameters:

ctrl -- [in] control commands for A2DP data channel

Returns:

  • ESP_OK: control command is sent to lower layer successfully

  • ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled

  • ESP_FAIL: others

esp_err_t esp_a2d_get_profile_status(esp_a2d_profile_status_t *profile_status)

This function is used to get the status of A2DP.

Parameters:

profile_status -- [out] - A2DP status

Returns:

  • ESP_OK: success

  • other: failed

esp_err_t esp_a2d_source_init(void)

Initialize the bluetooth A2DP source module. A2DP can work independently. If you want to use AVRC together, you should initiate AVRC first. This function should be called after esp_bluedroid_enable() completes successfully, and ESP_A2D_PROF_STATE_EVT with ESP_A2D_INIT_SUCCESS will reported to the APP layer. Note: A2DP can work independently. If you want to use AVRC together, you should initiate AVRC first.

Returns:

  • ESP_OK: if the initialization request is sent to lower layer successfully

  • ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled

  • ESP_FAIL: others

esp_err_t esp_a2d_source_register_stream_endpoint(uint8_t seid, const esp_a2d_mcc_t *mcc)

Register a a2dp source Stream Endpoint (SEP) with specific codec capability, shall register SEP after a2dp source initializing and before a2dp connection establishing. Register the same SEP index repeatedly will overwrite the old one.

Parameters:

  • seid -- [in] local SEP identifier, start from 0, less than ESP_A2D_MAX_SEPS

  • mcc -- [in] codec capability, currently, only SBC supported

Returns:

  • ESP_OK: success

  • ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled

  • ESP_ERR_INVALID_ARG: invalid parameter

  • ESP_FAIL: others

esp_err_t esp_a2d_source_deinit(void)

De-initialize for A2DP source module. This function should be called only after esp_bluedroid_enable() completes successfully, and ESP_A2D_PROF_STATE_EVT with ESP_A2D_DEINIT_SUCCESS will reported to APP layer.

Returns:

  • ESP_OK: success

  • ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled

  • ESP_FAIL: others

esp_err_t esp_a2d_source_audio_data_send(esp_a2d_conn_hdl_t conn_hdl, esp_a2d_audio_buff_t *audio_buf)

Send a audio buff with encoded audio data to sink, the audio data len shall not bigger than audio connection mtu (retrieved from ESP_A2D_CONNECTION_STATE_EVT). if the return value is ESP_OK, then the audio buff is consumed, otherwise, audio buff can be reused by user.

Parameters:

  • conn_hdl -- [in] connection handle

  • audio_buf -- [in] encoded audio data

Returns:

  • ESP_OK: success

  • ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled

  • ESP_ERR_INVALID_ARG: invalid parameter

  • ESP_ERR_INVALID_SIZE: data len bigger than mtu

  • ESP_FAIL: buffer queue is full, try again later

esp_err_t esp_a2d_source_connect(esp_bd_addr_t remote_bda)

Connect to remote A2DP sink device. This API must be called after esp_a2d_source_init() and before esp_a2d_source_deinit().

Parameters:

remote_bda -- [in] remote bluetooth device address

Returns:

  • ESP_OK: connect request is sent to lower layer successfully

  • ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled

  • ESP_FAIL: others

esp_err_t esp_a2d_source_disconnect(esp_bd_addr_t remote_bda)

Disconnect from the remote A2DP sink device. This API must be called after esp_a2d_source_init() and before esp_a2d_source_deinit().

Parameters:

remote_bda -- [in] remote bluetooth device address

Returns:

  • ESP_OK: disconnect request is sent to lower layer

  • ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled

  • ESP_FAIL: others

Unions

union esp_a2d_cb_param_t
#include <esp_a2dp_api.h>

A2DP state callback parameters.

Public Members

struct esp_a2d_cb_param_t::a2d_conn_stat_param conn_stat

A2DP connection status

struct esp_a2d_cb_param_t::a2d_audio_stat_param audio_stat

audio stream playing state

struct esp_a2d_cb_param_t::a2d_audio_cfg_param audio_cfg

media codec configuration information

struct esp_a2d_cb_param_t::media_ctrl_stat_param media_ctrl_stat

status in acknowledgement to media control commands

struct esp_a2d_cb_param_t::a2d_prof_stat_param a2d_prof_stat

status to indicate a2d prof init or deinit

struct esp_a2d_cb_param_t::a2d_sep_reg_stat_param a2d_sep_reg_stat

status to indicate a2d sep register success or not

struct esp_a2d_cb_param_t::a2d_psc_cfg_param a2d_psc_cfg_stat

status to indicate protocol service capabilities configured

struct esp_a2d_cb_param_t::a2d_set_stat_param a2d_set_delay_value_stat

A2DP sink set delay report value status

struct esp_a2d_cb_param_t::a2d_get_stat_param a2d_get_delay_value_stat

A2DP sink get delay report value status

struct esp_a2d_cb_param_t::a2d_report_delay_stat_param a2d_report_delay_value_stat

A2DP source received sink report value status

struct a2d_audio_cfg_param
#include <esp_a2dp_api.h>

ESP_A2D_AUDIO_CFG_EVT.

Public Members

esp_bd_addr_t remote_bda

remote bluetooth device address

esp_a2d_conn_hdl_t conn_hdl

connection handle

esp_a2d_mcc_t mcc

A2DP media codec capability information

struct a2d_audio_stat_param
#include <esp_a2dp_api.h>

ESP_A2D_AUDIO_STATE_EVT.

Public Members

esp_a2d_audio_state_t state

one of the values from esp_a2d_audio_state_t

esp_bd_addr_t remote_bda

remote bluetooth device address

esp_a2d_conn_hdl_t conn_hdl

connection handle

struct a2d_conn_stat_param
#include <esp_a2dp_api.h>

ESP_A2D_CONNECTION_STATE_EVT.

Public Members

esp_a2d_connection_state_t state

one of values from esp_a2d_connection_state_t

esp_bd_addr_t remote_bda

remote bluetooth device address

esp_a2d_conn_hdl_t conn_hdl

connection handle

uint16_t audio_mtu

MTU of audio connection

esp_a2d_disc_rsn_t disc_rsn

reason of disconnection for "DISCONNECTED"

struct a2d_get_stat_param
#include <esp_a2dp_api.h>

ESP_A2D_SNK_GET_DELAY_VALUE_EVT.

Public Members

uint16_t delay_value

delay report value

struct a2d_prof_stat_param
#include <esp_a2dp_api.h>

ESP_A2D_PROF_STATE_EVT.

Public Members

esp_a2d_init_state_t init_state

a2dp profile state param

struct a2d_psc_cfg_param
#include <esp_a2dp_api.h>

ESP_A2D_SNK_PSC_CFG_EVT.

Public Members

esp_a2d_psc_t psc_mask

protocol service capabilities configured

struct a2d_report_delay_stat_param
#include <esp_a2dp_api.h>

ESP_A2D_REPORT_SNK_DELAY_VALUE_EVT.

Public Members

uint16_t delay_value

delay report value

struct a2d_sep_reg_stat_param
#include <esp_a2dp_api.h>

ESP_A2D_SEP_REG_STATE_EVT.

Public Members

uint8_t seid

the stream endpoint to register

esp_a2d_sep_reg_state_t reg_state

stream endpoint register state

struct a2d_set_stat_param
#include <esp_a2dp_api.h>

ESP_A2D_SNK_SET_DELAY_VALUE_EVT.

Public Members

esp_a2d_set_delay_value_state_t set_state

a2dp profile state param

uint16_t delay_value

delay report value

struct media_ctrl_stat_param
#include <esp_a2dp_api.h>

ESP_A2D_MEDIA_CTRL_ACK_EVT.

Public Members

esp_a2d_media_ctrl_t cmd

media control commands to acknowledge

esp_a2d_media_ctrl_ack_t status

acknowledgement to media control commands

Structures

struct esp_a2d_cie_sbc_t

A2DP SBC media codec capabilities information struct.

Public Members

uint8_t ch_mode

Channel mode

uint8_t samp_freq

Sampling frequency

uint8_t alloc_mthd

Allocation method

uint8_t num_subbands

Number of subbands

uint8_t block_len

Block length

uint8_t min_bitpool

Minimum bitpool

uint8_t max_bitpool

Maximum bitpool

struct esp_a2d_cie_m12_t

A2DP MPEG-1, 2 media codec capabilities information struct (Not supported yet)

Public Members

uint8_t ch_mode

Channel mode

uint8_t crc

CRC protection

uint8_t layer

Layers of MPEG-1,2 Audio

uint8_t samp_freq

Sampling frequency

uint8_t mpf

Media payload format

uint8_t rfu

Reserved

uint8_t bri1

Bit rate index part 1

uint8_t vbr

Support of VBR

uint8_t bri2

Bit rate index part 2

struct esp_a2d_cie_m24_t

A2DP MPEG-2, 4 media codec capabilities information struct (Not supported yet)

Public Members

uint8_t drc

Support of MPEG-D DRC

uint8_t obj_type

Object type

uint8_t samp_freq1

Sampling frequency part 1

uint8_t ch

Channels

uint8_t samp_freq2

Sampling frequency part 2

uint8_t br1

Bit rate part 1

uint8_t vbr

Support of VBR

uint8_t br2

Bit rate part 2

uint8_t br3

Bit rate part 3

struct esp_a2d_cie_atrac_t

A2DP ATRAC media codec capabilities information struct (Not supported yet)

Public Members

uint8_t rfu1

Reserved

uint8_t ch_mode

Channel mode

uint8_t version

Version

uint8_t bri1

Bit rate index part 1

uint8_t vbr

Support of VBR

uint8_t samp_freq

Sampling frequency

uint8_t rfu2

Reserved

uint8_t bri2

Bit rate index part 2

uint8_t bri3

Bit rate index part 3

uint16_t max_sul

Maximum SUL

uint8_t rfu3

Reserved

struct esp_a2d_mcc_t

A2DP media codec capabilities union.

Public Members

esp_a2d_mct_t type

A2DP media codec type

esp_a2d_cie_sbc_t sbc_info

SBC codec capabilities

esp_a2d_cie_m12_t m12_info

MPEG-1,2 audio codec capabilities

esp_a2d_cie_m24_t m24_info

MPEG-2, 4 AAC audio codec capabilities

esp_a2d_cie_atrac_t atrac_info

ATRAC family codec capabilities

union esp_a2d_mcc_t cie

A2DP codec information element

struct esp_a2d_profile_status_t

A2DP profile status parameters.

Public Members

bool a2d_snk_inited

A2DP sink initialization

bool a2d_src_inited

A2DP source initialization

uint8_t conn_num

Number of connections

struct esp_a2d_audio_buff_t

A2DP audio buffer.

Public Members

uint16_t buff_size

audio buff size

uint16_t number_frame

number of encoded frame in this buff

uint32_t timestamp

timestamp of the first frame

uint16_t data_len

audio data len

uint8_t *data

pointer to audio data start

Macros

ESP_A2D_MAX_SEPS

Maximum number of Stream Endpoint that supported

ESP_A2D_MCT_SBC

Media codec types supported by A2DP.

SBC

ESP_A2D_MCT_M12

MPEG-1, 2 Audio

ESP_A2D_MCT_M24

MPEG-2, 4 AAC

ESP_A2D_MCT_ATRAC

ATRAC family

ESP_A2D_MCT_NON_A2DP

NON-A2DP

ESP_A2D_PSC_DELAY_RPT

Protocol service capabilities. This value is a mask.

Delay Report

ESP_A2D_SBC_CIE_SF_16K

A2DP SBC sampling frequency bit mask in CIE.

SBC sampling frequency 16kHz

ESP_A2D_SBC_CIE_SF_32K

SBC sampling frequency 32kHz

ESP_A2D_SBC_CIE_SF_44K

SBC sampling frequency 44.1kHz

ESP_A2D_SBC_CIE_SF_48K

SBC sampling frequency 48kHz

ESP_A2D_SBC_CIE_CH_MODE_MONO

A2DP SBC channel mode bit mask in CIE.

SBC channel mode Mono

ESP_A2D_SBC_CIE_CH_MODE_DUAL_CHANNEL

SBC channel mode Dual Channel

ESP_A2D_SBC_CIE_CH_MODE_STEREO

SBC channel mode Stereo

ESP_A2D_SBC_CIE_CH_MODE_JOINT_STEREO

SBC channel mode Stereo

ESP_A2D_SBC_CIE_BLOCK_LEN_4

A2DP SBC block length bit mask in CIE.

SBC block length 4

ESP_A2D_SBC_CIE_BLOCK_LEN_8

SBC block length 8

ESP_A2D_SBC_CIE_BLOCK_LEN_12

SBC block length 12

ESP_A2D_SBC_CIE_BLOCK_LEN_16

SBC block length 16

ESP_A2D_SBC_CIE_NUM_SUBBANDS_4

A2DP SBC number of subbands bit mask in CIE.

SBC number of subbands 4

ESP_A2D_SBC_CIE_NUM_SUBBANDS_8

SBC number of subbands 8

ESP_A2D_SBC_CIE_ALLOC_MTHD_SRN

A2DP SBC allocation method bit mask in CIE.

SBC allocation method SNR

ESP_A2D_SBC_CIE_ALLOC_MTHD_LOUDNESS

SBC allocation method Loudness

ESP_A2D_CIE_LEN_SBC
ESP_A2D_CIE_LEN_M12
ESP_A2D_CIE_LEN_M24
ESP_A2D_CIE_LEN_ATRAC

Type Definitions

typedef uint16_t esp_a2d_conn_hdl_t

Connection handle, associate with specific device that connected

typedef uint8_t esp_a2d_mct_t
typedef uint16_t esp_a2d_psc_t
typedef void (*esp_a2d_cb_t)(esp_a2d_cb_event_t event, esp_a2d_cb_param_t *param)

A2DP profile callback function type.

Param event:

: Event type

Param param:

: Pointer to callback parameter

typedef void (*esp_a2d_sink_audio_data_cb_t)(esp_a2d_conn_hdl_t conn_hdl, esp_a2d_audio_buff_t *audio_buf)

A2DP sink data callback function.

Param conn_hdl:

[in] connection handle

Param audio_buf:

[in] pointer to the data received from A2DP source device, should be freed by calling esp_a2d_audio_buff_free

Enumerations

enum esp_a2d_connection_state_t

Bluetooth A2DP connection states.

Values:

enumerator ESP_A2D_CONNECTION_STATE_DISCONNECTED

connection released

enumerator ESP_A2D_CONNECTION_STATE_CONNECTING

connecting remote device

enumerator ESP_A2D_CONNECTION_STATE_CONNECTED

connection established

enumerator ESP_A2D_CONNECTION_STATE_DISCONNECTING

disconnecting remote device

enum esp_a2d_disc_rsn_t

Bluetooth A2DP disconnection reason.

Values:

enumerator ESP_A2D_DISC_RSN_NORMAL

Finished disconnection that is initiated by local or remote device

enumerator ESP_A2D_DISC_RSN_ABNORMAL

Abnormal disconnection caused by signal loss

enum esp_a2d_audio_state_t

Bluetooth A2DP datapath states.

Values:

enumerator ESP_A2D_AUDIO_STATE_SUSPEND

audio stream datapath suspended by remote device

enumerator ESP_A2D_AUDIO_STATE_STARTED

audio stream datapath started

enum esp_a2d_media_ctrl_ack_t

A2DP media control command acknowledgement code.

Values:

enumerator ESP_A2D_MEDIA_CTRL_ACK_SUCCESS

media control command is acknowledged with success

enumerator ESP_A2D_MEDIA_CTRL_ACK_FAILURE

media control command is acknowledged with failure

enumerator ESP_A2D_MEDIA_CTRL_ACK_BUSY

media control command is rejected, as previous command is not yet acknowledged

enum esp_a2d_media_ctrl_t

A2DP media control commands.

Values:

enumerator ESP_A2D_MEDIA_CTRL_NONE

Not for application use, use inside stack only.

enumerator ESP_A2D_MEDIA_CTRL_CHECK_SRC_RDY

check whether AVDTP is connected, only used in A2DP source

enumerator ESP_A2D_MEDIA_CTRL_START

command to set up media transmission channel

enumerator ESP_A2D_MEDIA_CTRL_SUSPEND

command to suspend media transmission

enum esp_a2d_init_state_t

Bluetooth A2DP Initiation states.

Values:

enumerator ESP_A2D_DEINIT_SUCCESS

A2DP profile deinit successful event

enumerator ESP_A2D_INIT_SUCCESS

A2DP profile deinit successful event

enum esp_a2d_sep_reg_state_t

Bluetooth A2DP SEP register states.

Values:

enumerator ESP_A2D_SEP_REG_SUCCESS

A2DP stream endpoint register success

enumerator ESP_A2D_SEP_REG_FAIL

A2DP stream endpoint register generic fail

enumerator ESP_A2D_SEP_REG_UNSUPPORTED

A2DP stream endpoint register fail, unsupported codec type or param

enumerator ESP_A2D_SEP_REG_INVALID_STATE

A2DP stream endpoint register fail, invalid state

enum esp_a2d_set_delay_value_state_t

Bluetooth A2DP set delay report value states.

Values:

enumerator ESP_A2D_SET_SUCCESS

A2DP profile set delay report value successful

enumerator ESP_A2D_SET_INVALID_PARAMS

A2DP profile set delay report value is invalid parameter

enum esp_a2d_cb_event_t

A2DP callback events.

Values:

enumerator ESP_A2D_CONNECTION_STATE_EVT

connection state changed event

enumerator ESP_A2D_AUDIO_STATE_EVT

audio stream transmission state changed event

enumerator ESP_A2D_AUDIO_CFG_EVT

audio codec is configured

enumerator ESP_A2D_MEDIA_CTRL_ACK_EVT

acknowledge event in response to media control commands

enumerator ESP_A2D_PROF_STATE_EVT

indicate a2dp init&deinit complete

enumerator ESP_A2D_SEP_REG_STATE_EVT

indicate a2dp steam endpoint register status

enumerator ESP_A2D_SNK_PSC_CFG_EVT

protocol service capabilities configured，only used for A2DP SINK

enumerator ESP_A2D_SNK_SET_DELAY_VALUE_EVT

indicate a2dp sink set delay report value complete, only used for A2DP SINK

enumerator ESP_A2D_SNK_GET_DELAY_VALUE_EVT

indicate a2dp sink get delay report value complete, only used for A2DP SINK

enumerator ESP_A2D_REPORT_SNK_DELAY_VALUE_EVT

report delay value, only used for A2DP SRC

Was this page helpful?