# Bluetooth® A2DP API

## Application Example

Check bluetooth/bluedroid/classic_bt folder in ESP-IDF examples, which contains the following application:

- This is a A2DP sink client demo. This demo can be discovered and connected by A2DP source device and receive the audio stream from remote device - bluetooth/bluedroid/classic_bt/a2dp_sink

## 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_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_data_callback(esp_a2d_sink_data_cb_t callback)

  Register A2DP sink data output function; For now the output is PCM data stream decoded from SBC format. This function should be called only after esp_bluedroid_enable() completes successfully, used only by A2DP sink. The callback is invoked in the context of A2DP sink task whose stack size is configurable through menuconfig.

  Parameters:

    callback -- [in] A2DP sink data 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_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_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_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_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_register_data_callback(esp_a2d_source_data_cb_t callback)

  Register A2DP source data input function. For now, the input shoule be PCM data stream. This function should be called only after esp_bluedroid_enable() completes successfully. The callback is invoked in the context of A2DP source task whose stack size is configurable through menuconfig.

  Parameters:

    callback -- [in] A2DP source data 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_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_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_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

  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_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_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_mcc_t

  A2DP media codec capabilities union.

  Public Members

  esp_a2d_mct_t type

    A2DP media codec type

  uint8_t sbc[ESP_A2D_CIE_LEN_SBC]

    SBC codec capabilities

  uint8_t m12[ESP_A2D_CIE_LEN_M12]

    MPEG-1,2 audio codec capabilities

  uint8_t m24[ESP_A2D_CIE_LEN_M24]

    MPEG-2, 4 AAC audio codec capabilities

  uint8_t atrac[ESP_A2D_CIE_LEN_ATRAC]

    ATRAC family codec capabilities

  union esp_a2d_mcc_t::[anonymous] cie

    A2DP codec information element

### Macros

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_CIE_LEN_SBC

ESP_A2D_CIE_LEN_M12

ESP_A2D_CIE_LEN_M24

ESP_A2D_CIE_LEN_ATRAC

### Type Definitions

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_data_cb_t)(const uint8_t *buf, uint32_t len)

  A2DP sink data callback function.

  Param buf:

    [in] : pointer to the data received from A2DP source device and is PCM format decoded from SBC decoder; buf references to a static memory block and can be overwritten by upcoming data

  Param len:

    [in] : size(in bytes) in buf

typedef int32_t (*esp_a2d_source_data_cb_t)(uint8_t *buf, int32_t len)

  A2DP source data read callback function.

  Param buf:

    [in] : buffer to be filled with PCM data stream from higher layer

  Param len:

    [in] : size(in bytes) of data block to be copied to buf. -1 is an indication to user that data buffer shall be flushed

  Return:

    size of bytes read successfully, if the argument len is -1, this value is ignored.

### 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

  enumerator ESP_A2D_AUDIO_STATE_STOPPED

    Note

    Deprecated

  enumerator ESP_A2D_AUDIO_STATE_REMOTE_SUSPEND

    Note

    Deprecated

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

  enumerator ESP_A2D_MEDIA_CTRL_STOP

    Note

    Deprecated, Please use ESP_A2D_MEDIA_CTRL_SUSPEND

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_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, only used for A2DP SINK

  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_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

Provide feedback about this document