ESP32-A2DP蓝牙音频库全面指南

2026-02-06 04:14:51作者：卓艾滢Kingsley

ESP32-A2DP是一个简单易用的ESP32蓝牙A2DP库，支持音乐接收器和发送器功能，兼容Arduino、PlatformIO和Espressif IDF平台。该库基于ESP-IDF开发，无需其他依赖，为ESP32开发者提供了便捷的蓝牙音频解决方案。

项目概述

ESP32-A2DP库允许ESP32设备通过蓝牙A2DP协议接收和发送音频数据。作为接收器时，可以将手机等设备的音频流传输到ESP32；作为发送器时，可以将ESP32生成的音频发送到蓝牙音箱等设备。

支持的蓝牙协议

该库专门支持A2DP（高级音频分发配置文件）协议，用于高质量音频流传输，同时支持AVRCP（音频/视频远程控制配置文件）。不支持HFP（免提配置文件）、HSP（耳机配置文件）或独立的AVRCP。

快速入门

安装依赖

首先确保已安装Arduino IDE和ESP32开发板支持包。然后通过以下方式安装库：

cd ~/Documents/Arduino/libraries
git clone https://gitcode.com/gh_mirrors/es/ESP32-A2DP.git
git clone https://github.com/pschatzmann/arduino-audio-tools.git

基础示例：音乐接收器

以下是一个简单的音乐接收器示例，使用默认I2S引脚输出到外部DAC：

#include "AudioTools.h"
#include "BluetoothA2DPSink.h"

I2SStream out;
BluetoothA2DPSink a2dp_sink(out);

void setup() {
  a2dp_sink.start("MyMusic");
}

void loop() {
  delay(1000);
}

默认I2S引脚配置：

BCK (位时钟)：GPIO14
WS (左右时钟)：GPIO15
DATA (数据输出)：GPIO22

自定义引脚配置

如需使用自定义引脚，可在setup()中配置：

void setup() {
  auto cfg = out.defaultConfig();
  cfg.pin_bck = 14;
  cfg.pin_ws = 15;
  cfg.pin_data = 22;
  out.begin(cfg);
  
  a2dp_sink.start("MyMusic");
}

核心功能详解

A2DP接收器功能

使用内部DAC输出

可直接使用ESP32的内部DAC输出音频：

#include "AudioTools.h"
#include "BluetoothA2DPSink.h"

AnalogAudioStream out;
BluetoothA2DPSink a2dp_sink(out);

void setup() {
  a2dp_sink.start("MyMusic");
}

void loop() {
}

内部DAC输出到GPIO25（通道1）和GPIO26（通道2）。

数据回调功能

可以监听数据包接收事件或直接访问音频数据：

// 数据包接收回调
a2dp_sink.set_on_data_received(data_received_callback);

void data_received_callback() {
  Serial.println("数据包已接收");
}

// 流数据读取回调  
a2dp_sink.set_stream_reader(read_data_stream);

void read_data_stream(const uint8_t *data, uint32_t length) {
  int16_t *samples = (int16_t*) data;
  uint32_t sample_count = length/2;
  // 处理音频数据
}

元数据支持

可以获取播放曲目的元数据信息：

void avrc_metadata_callback(uint8_t data1, const uint8_t *data2) {
  Serial.printf("AVRC元数据: 属性ID 0x%x, %s\n", data1, data2);
}

a2dp_sink.set_avrc_metadata_callback(avrc_metadata_callback);
a2dp_sink.start("BT");

A2DP发送器功能

音频数据发送

作为发送器时，需要提供音频生成回调函数：

#include "BluetoothA2DPSource.h"
#include <math.h> 

BluetoothA2DPSource a2dp_source;

int32_t get_data_frames(Frame *frame, int32_t frame_count) {
    static float m_time = 0.0;
    float m_amplitude = 10000.0;
    float m_deltaTime = 1.0 / 44100.0;
    
    for (int sample = 0; sample < frame_count; ++sample) {
        float angle = PI * 2.0 * 130.81 * m_time;
        frame[sample].channel1 = m_amplitude * sin(angle);
        frame[sample].channel2 = frame[sample].channel1;
        m_time += m_deltaTime;
    }
    
    delay(1); // 防止看门狗超时
    return frame_count;
}

void setup() {
  a2dp_source.set_data_callback_in_frames(get_data_frames);
  a2dp_source.start("MySpeaker");  
}

void loop() {
  delay(1000);
}

多设备连接支持

可以指定多个备选设备名称，系统会连接第一个可用的设备：

void setup() {
  static std::vector<char*> bt_names = {"MyMusic","RadioPlayer","MusicPlayer"};
  a2dp_source.set_data_callback(get_sound_data);
  a2dp_source.start(bt_names); 
}

高级功能

远程控制命令

支持AVRCP远程控制命令，可以控制连接的音频源设备：

a2dp_sink.play();      // 播放
a2dp_sink.pause();     // 暂停  
a2dp_sink.stop();      // 停止
a2dp_sink.next();      // 下一曲
a2dp_sink.previous();  // 上一曲
a2dp_sink.fast_forward(); // 快进
a2dp_sink.rewind();    // 后退

状态通知回调

支持播放状态、播放位置和曲目变化的通知回调：

a2dp_sink.set_avrc_rn_playstatus_callback(playstatus_callback);
a2dp_sink.set_avrc_rn_play_pos_callback(playpos_callback);
a2dp_sink.set_avrc_rn_track_change_callback(trackchange_callback);

配置选项

通过修改src/config.h文件可以调整库的各种参数：

#define AUTOCONNECT_TRY_NUM 1000      // 自动连接尝试次数
#define A2DP_I2S_MAX_WRITE_SIZE 5120  // 最大写入大小(字节)
#define A2DP_DISCONNECT_LIMIT 20      // 断开连接超时限制