ESP-BT-AUDIO Component

[中文]

Note

This document is automatically translated using AI. Please excuse any detailed errors. The official English version is still in progress.

Component Overview

esp_bt_audio is an advanced Bluetooth audio component provided by Espressif, used for unified management of Classic Bluetooth and LE Audio capabilities. The component interfaces downwards with the BT host, controller, and various audio profiles, and provides a unified initialization interface, role configuration, event callbacks, stream abstraction, and packet I/O upwards, reducing the complexity of Bluetooth audio application development.

The component automatically completes the initialization and management of the corresponding protocol based on the Classic and LE role configured by the application, and reports the connection status, device discovery, stream lifecycle, playback control, volume change, call status, phone status, address book, and call record information uniformly through esp_bt_audio_event_cb_t.

Classic Bluetooth audio uses the Bluedroid host; LE Audio can use either NimBLE or Bluedroid host depending on the chip and project configuration, and requires the activation of ESP-IDF Bluetooth Audio and ISO support.

This component is suitable for the following typical scenarios:

  • Bluetooth Speaker and Bluetooth Headset

  • A2DP Audio Source Device

  • Call devices in vehicles, headphones, or voice terminals

  • TMAP Unicast and Broadcast Audio Devices

  • Auracast or other BIS broadcast transmission/reception devices

  • Bluetooth audio applications that need to access the ESP-GMF pipeline

Main Features

  • Unified Bluetooth Audio Interface Provides a unified API, role configuration, and event callbacks for applications, eliminating the need to handle the underlying differences between each profile and host separately.

  • Classic Bluetooth Audio Supports A2DP Source/Sink, HFP Hands-Free (HF), HFP Audio Gateway (AG), AVRCP Controller/Target, and PBAP Client Equipment. A2DP supports external codec paths, with the current implementation including SBC and AAC.

  • LE Audio Unicast Capability Supports BAP Unicast Server, which can expose sink/source ASE for LE unicast media or call audio.

  • LE Audio Broadcasting Capability Supports BAP Broadcast Source, BAP Broadcast Sink, and Scan Delegator, which can send or receive LC3 broadcast audio streams.

  • LE Audio Control and Collaboration Capabilities Supports capabilities such as TMAP roles, VCP Renderer, MCP, MICP, CCP Client, and CSIP Set Member for volume, media, microphone, call control, and collaborative group.

  • Unified Event Callback Model Reports events such as connection, discovery, stream lifecycle, playback control, metadata, volume, call and phone status, phonebook, call history, and BIG/PA synchronization loss through esp_bt_audio_event_cb_t.

  • Stream Abstraction and Packet I/O The esp_bt_audio_stream_handle_t is used to represent the Bluetooth audio stream, which allows for querying codec information, direction, context, and LE ISO intervals, and for reading or writing encoded frames through the acquire/release API.

  • Optional GMF I/O Provides esp_gmf_io_bt, which adapts the Bluetooth audio stream as a reader or writer for the ESP-GMF pipeline.

Functional Features

ESP_BT_AUDIO supports the following functions:

Function

Description

Typical Application

A2DP Sink

Receive SBC/AAC encoded audio from remote sources such as mobile phones, PCs, etc., and play it locally.

Bluetooth speakers, headphones

A2DP Source

Sends local audio to remote Bluetooth speakers or headphones

Players, voice devices

HFP HF/AG

Supports Hands-Free and Audio Gateway voice call scenarios

Car-mounted, headphones, voice terminals

AVRCP Controller/Target

Supports playback control, playback status, metadata, and notifications

Playback control panel, audio player

PBAP Client Equipment

Retrieve mobile phone contacts and call records

Terminal devices with phone book capabilities

BAP Unicast Server

Expose LE Audio sink/source ASE for media or call audio

LE Speaker, LE Headphones

BAP Broadcast Source/Sink

Send or receive LC3 broadcast audio streams

Auracast transmitter and receiver

Scan Delegator

Receive broadcast discovery and synchronization requests from the Broadcast Assistant

Remote broadcast control device

TMAP

Configure CT, UMR, BMR, BMS, etc. phone and media role combinations

TMAP Audio Device

VCP/MCP/MICP/CCP/CSIP

Supports volume, media control, microphone control, call control, and collaborative group capabilities

LE Audio Control and Collaborative Devices

GMF I/O

Connects Bluetooth audio stream to ESP-GMF pipeline

Complex audio processing chain

Architecture Overview

ESP_BT_AUDIO is located between the application layer and the Bluetooth protocol stack, serving as an adaptation layer that provides a unified interface upwards and interfaces with the BT host, controller, Classic profile, and LE Audio profile downwards. The underlying profile and host callbacks are converted into unified events by the component; Classic and LE streams use the same lifecycle and packet I/O model.

You didn't provide any text to translate. Please provide the text in Chinese that you want to translate into English.
 |-- Initialization / role provision / control command
 |-- Unified Event Callback
 v
esp_bt_audio
 |-- Classic profiles：A2DP / HFP / AVRCP / PBAP
 |-- LE Audio profiles：BAP / TMAP / VCP / MCP / MICP / CCP / CSIP
 |-- stream abstraction and packet queue
 v
BT host（Bluedroid / NimBLE）--> BT controller
                      |
                      +--> Optional GMF I/O --> ESP-GMF pipeline

The typical processing flow is as follows:

  1. Initialize the NVS and BT controller applications.

  2. Application Preparation: Configure Bluedroid or NimBLE host, and set Classic and/or LE role, event callbacks.

  3. Initialize the component by calling esp_bt_audio_init().

  4. Components initialize corresponding protocols based on the role.

  5. Connection, discovery, stream status, and control events are reported through a unified callback.

  6. The application selects reading, writing, or binding the GMF pipeline based on the stream direction.

API Overview

The main header files for ESP_BT_AUDIO are as follows:

Header file

Description

esp_bt_audio.h

Module initialization, de-initialization, and overall configuration

esp_bt_audio_event.h

Event ID and event data structure definition

esp_bt_audio_defs.h

Classic/LE role, codec and basic definitions

esp_bt_audio_host.h

Bluedroid / NimBLE host provision configuration structure

esp_bt_audio_classic.h

Classic device discovery, connection, disconnection, and scanning mode interfaces

esp_bt_audio_le.h

LE scanning, broadcast switch, ACL connection and broadcast synchronization interface

esp_bt_audio_stream.h

stream abstraction, property query, and packet acquire/release API

esp_bt_audio_media.h

Local media sends transmission control

esp_bt_audio_playback.h

Interfaces related to playback control, metadata, and notifications

esp_bt_audio_vol.h

Absolute volume, relative volume control and notification

esp_bt_audio_tel.h

Call status, phone status, and call control

esp_bt_audio_pb.h

Contacts and call history

esp_bt_audio_le_playback_sync.h

Optional LE playback start and clock synchronization auxiliary interface, dependent on CONFIG_SOC_MODEM_SUPPORT_ETM

io/esp_gmf_io_bt.h

Optional GMF I/O adapter interface

Stream Model

stream direction

  • ESP_BT_AUDIO_STREAM_DIR_SINK: Downstream receiving direction. The stream outputs encoded frames to the application, which uses esp_bt_audio_stream_acquire_read() and esp_bt_audio_stream_release_read().

  • ESP_BT_AUDIO_STREAM_DIR_SOURCE: Upstream transmission direction. The application writes encoded frames into the stream, using esp_bt_audio_stream_acquire_write() and esp_bt_audio_stream_release_write().

Applications can query stream attributes through the following interface:

  • esp_bt_audio_stream_get_codec_info(): codec type, sampling rate, channel, bit width, frame size, etc.

  • esp_bt_audio_stream_get_dir(): Data direction.

  • esp_bt_audio_stream_get_profile(): Profiles such as A2DP, HFP, LE unicast, or LE broadcast.

  • esp_bt_audio_stream_get_context(): Context for media, calls, and other services.

  • esp_bt_audio_stream_get_local_data(): Additional data within the component.

  • esp_bt_audio_stream_get_iso_interval(): LE ISO interval, in microseconds.

stream lifecycle

The lifecycle of the stream is maintained internally by the component and reported through the ESP_BT_AUDIO_EVENT_STREAM_STATE_CHG event. Common states are as follows:

  • ALLOCATED: The stream has been created, the application can query the codec, direction, context and allocate resources.

  • STARTED: The audio stream has started, the application begins to read or write encoded frames.

  • STOPPED：The audio stream has stopped, the application has stopped the data processing flow.

  • RELEASED: The stream has been released, the application cleans up related resources.

Typical Data Flow

In the classic sink scenario, a mobile phone or PC acts as an audio source, sending SBC, AAC, and other encoded frames. The ESP device obtains the encoded data through ESP_BT_AUDIO, which is then processed through decoding, sample rate conversion, channel conversion, etc., and output to I2S, DAC, or codec device.

In the Classic source scenario, the ESP device obtains local audio data from files, microphones, or pipelines. After necessary conversion and encoding, it sends the data to remote Bluetooth speakers or headphones via ESP_BT_AUDIO.

In the LE Audio sink scenario, the remote unicast or broadcast audio source sends LC3 frames, and the ESP device reads the encoded frames and feeds them into the local decoding and playback link after the stream starts. In the LE Audio source scenario, LC3 frames can be generated from local audio input and sent via the negotiated LE Audio stream.

LE Playback Synchronization Capability

On chips that support CONFIG_SOC_MODEM_SUPPORT_ETM, esp_bt_audio_le_playback_sync.h provides auxiliary interfaces for LE playback start synchronization and I2S FIFO clock synchronization. Applications can align BLE timing events with I2S output to reduce LE Audio playback start and clock deviation.

GMF I/O Integration

When CONFIG_ESP_BT_AUDIO_GMF_IO_SUPPORT is enabled, the component provides esp_gmf_io_bt, adapting the Bluetooth audio stream to an ESP-GMF I/O node.

The logic is used as follows:

  1. Register the io_bt reader and/or writer in the GMF Pool according to the direction. During initialization, the stream can be set to null.

  2. Upon receiving a stream in the ALLOCATED state, call esp_gmf_io_bt_set_stream() to bind based on the direction.

  3. The Bluetooth sink stream serves as the pipeline input, using the io_bt reader; the Bluetooth source stream serves as the pipeline output, using the io_bt writer.

  4. Run or stop the corresponding pipeline when the STARTED / STOPPED status changes.

The typical pipeline combination is as follows:

  • Classic / LE sink：io_bt reader → aud_dec → aud_rate_cvt / aud_ch_cvt → io_codec_dev writer

  • Classic / LE source: io_file or io_codec_dev reader → aud_dec → aud_enc → io_bt writer

  • LE broadcast source: Local audio input → Decode/Convert/Encode → io_bt writer → BIS

Usage Method

Integrated Component

The current component version is 1.1.x, requiring ESP-IDF 5.5 or higher. When using the ESP-IDF Component Manager, you can add the following dependencies to the project:

dependencies:
  espressif/esp_bt_audio:
    version: "~1.1"

The component depends on the bt component and esp_audio_codec of ESP-IDF. When CONFIG_ESP_BT_AUDIO_GMF_IO_SUPPORT=y, it also introduces gmf_core and gmf_io.

Dependencies can also be added through commands:

idf.py add-dependency "espressif/esp_bt_audio~1.1"

Configuring Classic Bluetooth

The source code related to the Classic profile will only be compiled when the corresponding ESP-IDF provision is enabled:

  • CONFIG_BT_CLASSIC_ENABLED

  • CONFIG_BT_BLUEDROID_ENABLED

  • CONFIG_BT_A2DP_ENABLE

  • CONFIG_BT_A2DP_USE_EXTERNAL_CODEC

  • CONFIG_BT_HFP_ENABLE

  • CONFIG_BT_HFP_CLIENT_ENABLE or CONFIG_BT_HFP_AG_ENABLE

  • CONFIG_BT_HFP_AUDIO_DATA_PATH_HCI

  • CONFIG_BT_HFP_USE_EXTERNAL_CODEC

  • CONFIG_BT_AVRCP_ENABLED

  • CONFIG_BT_PBAC_ENABLED

Configure LE Audio

LE Audio requires enabling Bluetooth Audio and ISO support, and choosing either NimBLE or Bluedroid host based on the target chip and project:

  • CONFIG_BT_AUDIO

  • CONFIG_BT_ISO

  • CONFIG_BT_NIMBLE_ENABLED or CONFIG_BT_BLUEDROID_ENABLED

The optional LE profile switch comes from the ESP-IDF Bluetooth Audio provision, for example:

  • CONFIG_BT_BAP_UNICAST_SERVER

  • CONFIG_BT_BAP_BROADCAST_SOURCE

  • CONFIG_BT_BAP_BROADCAST_SINK

  • CONFIG_BT_BAP_SCAN_DELEGATOR

  • CONFIG_BT_VCP_VOL_REND

  • CONFIG_BT_MCC

  • CONFIG_BT_MICP_MIC_DEV

  • CONFIG_BT_TBS_CLIENT

  • CONFIG_BT_CSIP_SET_MEMBER

  • CONFIG_BT_TMAP

The LE Broadcast Source is configured with the broadcast code, broadcast name, and stream_num through esp_bt_audio_le_bsrc_cfg_t.

Component Self-Configuration

In the ESP Bluetooth Audio menu of menuconfig, you can configure:

  • CONFIG_ESP_BT_AUDIO_GMF_IO_SUPPORT: Compile esp_gmf_io_bt.

  • CONFIG_ESP_BT_AUDIO_MONITOR and its sub-options: Play synchronization, clock synchronization, or stream monitoring GPIO.

Initialization Example

Classic A2DP Sink Example:

#include "esp_bt_audio.h"
#include "esp_bt_audio_host.h"

static void bt_audio_event_cb(esp_bt_audio_event_t event,
                               void *event_data, void *user_data);

void init_classic_bt_audio(void)
{
    esp_bt_audio_host_bluedroid_cfg_t host_cfg =
        ESP_BT_AUDIO_HOST_BLUEDROID_CFG_DEFAULT();

    esp_bt_audio_config_t cfg = {
        .host_config = &host_cfg,
        .event_cb = bt_audio_event_cb,
        .event_user_ctx = NULL,
        .classic.roles = ESP_BT_AUDIO_CLASSIC_ROLE_A2DP_SNK |
                         ESP_BT_AUDIO_CLASSIC_ROLE_AVRC_TG,
    };

    ESP_ERROR_CHECK(esp_bt_audio_init(&cfg));
}

LE Audio Unicast Server and Broadcast Sink Example:

#include "esp_bt_audio.h"
#include "esp_bt_audio_host.h"

static void bt_audio_event_cb(esp_bt_audio_event_t event,
                               void *event_data, void *user_data);

void init_le_audio(void)
{
    esp_bt_audio_host_nimble_cfg_t host_cfg =
        ESP_BT_AUDIO_HOST_NIMBLE_CFG_DEFAULT();

    esp_bt_audio_config_t cfg = {
        .host_config = &host_cfg,
        .event_cb = bt_audio_event_cb,
        .event_user_ctx = NULL,
        .le.user_case = ESP_BT_AUDIO_LE_USER_CASE_TMAP,
        .le.roles = ESP_BT_AUDIO_LE_ROLE_UNICAST_SERVER |
                    ESP_BT_AUDIO_LE_ROLE_BROADCAST_SINK,
        .le.snk_cnt = 1,
        .le.src_cnt = 0,
    };

    ESP_ERROR_CHECK(esp_bt_audio_init(&cfg));
}

Actual projects need to fully configure NVS, BT controller, PACS, CSIP, VCP or broadcast source parameters according to the target chip and the host used.

Auxiliary Interface

Classic Auxiliary Interface

After enabling Classic and Bluedroid, esp_bt_audio_classic.h provides interfaces for starting/stopping device discovery, connecting/disconnecting by role and address, setting connectable/discoverable scan modes, and so on.

LE Audio Auxiliary Interface

After enabling LE Audio, esp_bt_audio_le.h provides the following common operations:

  • LE scan start and stop, and scan by target address: esp_bt_audio_le_scan_start(), esp_bt_audio_le_scan_start_ext(), esp_bt_audio_le_scan_stop().

  • Broadcast switch: esp_bt_audio_le_set_advertising().

  • LE ACL Connection and Disconnection: esp_bt_audio_le_connect(), esp_bt_audio_le_disconnect(), esp_bt_audio_le_disconnect_peer().

  • Broadcast source start/stop: esp_bt_audio_le_broadcast_source_start() / stop().

  • Broadcast synchronization and desynchronization: esp_bt_audio_le_broadcast_sync() and esp_bt_audio_le_pa_sync_terminate().

Example Project

The bt_audio example project can be created with the following command:

idf.py create-project-from-example "espressif/esp_bt_audio~1.1:bt_audio"

The examples cover Classic audio playback/sending, call and phonebook, LE Audio unicast and broadcast, as well as GMF pipeline. For detailed compilation and board-level configuration, please refer to the examples/bt_audio directory in the component.