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.

Overview

ESP_BT_AUDIO is an advanced Bluetooth audio component launched by Espressif, used to uniformly manage the audio capabilities of Classic Bluetooth and LE Audio. This component integrates the underlying Bluetooth protocol, audio data stream, and event notification process, providing a unified initialization, data access, and status management interface for the application layer, thereby reducing the complexity of Bluetooth audio application development.

ESP_BT_AUDIO will automatically complete the initialization and management of the corresponding protocol according to the user-configured role, and report connection status, device discovery, audio stream status, playback control, volume changes, call status, address book, and call records to the application layer through a unified event mechanism.

This component is suitable for the following typical scenarios:

  • Bluetooth speakers

  • Bluetooth headphones

  • Smart audio devices

  • Voice terminals with call capabilities

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

Main Features

  • Unified Bluetooth audio interface Provides a unified API and event callback to the upper layer, and the application does not need to handle the underlying differences of different Bluetooth profiles separately.

  • Supports Classic Bluetooth audio protocol Supports functions such as A2DP Sink, A2DP Source, HFP Hands-Free, AVRCP Controller/Target, and PBAP Client Equipment.

  • Unified event callback model Reports connection, discovery, stream lifecycle, playback control, metadata, volume, call status, phone status, address book, and call records events through esp_bt_audio_event_cb_t.

  • Stream abstraction Uses esp_bt_audio_stream_handle_t to represent Bluetooth audio streams, supports querying codec information, data direction, business context, and reading and writing encoded frames through packet API.

  • Flexible data access methods Supports Packet I/O to directly read and write Bluetooth audio data packets, and also supports access to the ESP-GMF pipeline through esp_gmf_io_bt.

  • Reduces application development complexity Converges protocol initialization, profile management, status changes, and data stream processing into a unified component, improving code reusability and scalability.

Functional Features

ESP_BT_AUDIO supports the following functions:

Function

Description

Typical Application

A2DP Sink

Receives audio from remote sources such as mobile phones, PCs, etc., and plays it locally

Bluetooth speakers, headphones

A2DP Source

Sends local audio to remote Bluetooth speakers or headphones

Players, voice devices

HFP Hands-Free

Supports call-type voice scenarios

Car-mounted, headphones, voice terminals

AVRCP Controller/Target

Supports playback control, metadata, and playback status notifications

Playback control panel, audio player

PBAP Client Equipment

Pulls mobile phone address book and call records

Terminal devices with phone book capabilities

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, providing a unified interface upwards as an adaptation layer, and docking with the BT host, Bluetooth controller, and various Classic Bluetooth profiles downwards. The callbacks of the underlying profile and host will be uniformly converted into events by the component and then notified to the application layer for processing.

The typical processing flow is as follows:

  1. The application initializes NVS and BT controller.

  2. Configure host, role, and event callbacks.

  3. Initialize the component by calling esp_bt_audio_init().

  4. The component initializes the corresponding Bluetooth protocol 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.

Stream Lifecycle

The stream lifecycle of ESP_BT_AUDIO is maintained internally by the component and is reported through the ESP_BT_AUDIO_EVENT_STREAM_STATE_CHG event. The application can complete codec initialization, pipeline binding, data processing start/stop, and resource release based on the status.

Common statuses are as follows:

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

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

  • STOPPED: The audio stream has stopped, the application stops the corresponding processing flow.

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

Typical Data Flow

In the A2DP Sink scenario, the mobile phone or PC acts as an audio source to send SBC and other encoded frames. The ESP device obtains the encoded data through ESP_BT_AUDIO, and after decoding, sample rate conversion, channel conversion, etc., it outputs to I2S, DAC, or codec device.

In the A2DP Source scenario, the ESP device obtains local audio data from files, microphones, or pipelines, and after necessary conversion and encoding, it sends it to the remote Bluetooth speaker or earphone through ESP_BT_AUDIO.

Example Project

You can create the bt_audio example project with the following command:

idf.py create-project-from-example "espressif/esp_bt_audio=0.8.1:bt_audio"

For more example code, please refer to the examples directory in the component.