由gemini 2.5pro整理。

ADF仓库结构

espressif/esp-adf: Espressif Advanced Development Framework

1
2
3
4
5
6
7
8
9
esp-adf/
├── components      # 核心组件和第三方库
├── docs            # 文档
├── examples        # 示例代码
├── tools           # 实用工具
├── CMakeLists.txt  # 顶层构建脚本
├── esp-idf         # idf 作为submodoule
├── README.md       # 项目根 README
└── ...             # 其他配置文件

核心框架组件

esp-adf/omponents

  • audio_pipeline: 提供了音频管道 (Audio Pipeline) 的核心实现，负责将音频元素（如输入、解码、输出）连接起来，管理数据流和状态。
  • audio_stream: 提供了音频管道中“音频元素”的具体实现，包括：
    • Source: http_stream, fatfs_stream, i2s_stream, spiffs_stream, raw_stream 等，负责产生音频数据。
    • **Filter: 如各种解码器和编码器。
    • Sink: i2s_stream, raw_stream, pwm_stream 等，负责消费最终的音频数据。
  • audio_sal (Audio System Abstraction Layer): 音频系统抽象层，封装 FreeRTOS 的任务、队列、互斥锁、内存管理等功能，为上层应用提供统一接口。
  • adf_utils: 提供常用工具函数，如 aws_sig_v4_signing (AWS 签名)、baidu_access_token (百度令牌获取)、json_utils (JSON 解析工具)。
  • esp_dispatcher: 事件分发器，基于事件源和优先级执行动作，将服务与具体动作解耦，提高灵活性。

硬件抽象层 (HAL)

  • audio_hal: 音频硬件抽象层，定义标准接口控制音频编解码芯片 (Codec)，如初始化、配置音量、设置采样率，与硬件解耦。
  • esp_codec_dev: 新一代 Codec 设备抽象层，提供通用可扩展接口，支持控制接口（I2C, SPI）和数据接口（I2S）的灵活组合。
  • audio_board: 针对乐鑫官方开发板（如 ESP32-LyraT, ESP32-S3-Korvo-2）的板级支持，初始化引脚、外设和 audio_hal 接口。

服务 (Services)

服务是一些封装了特定功能的后台任务，可通过事件与应用层交互。

  • esp_peripherals: 外设管理服务，统一管理按键、Wi-Fi、SD 卡、触摸板等外设，通过 audio_event_iface 传递事件。
  • input_key_service: 统一按键事件处理服务，支持单击、双击、长按等事件，可自定义按键功能。
  • wifi_service: 专用 Wi-Fi 服务，封装连接、断线重连、获取 IP 等功能，支持 SmartConfig、AirKiss 等配网方式。
  • bluetooth_service: 蓝牙服务，封装 A2DP（音频流传输）、AVRCP（远程控制）、HFP（免提通话）等协议，简化蓝牙音频开发。
  • ota_service: 提供 OTA (Over-the-Air) 固件升级服务，支持通过 HTTP/HTTPS 下载并升级固件。
  • display_service: 显示服务，用于在带屏幕设备上显示信息，如通过 LED 灯条（WS2812）或 LED 点阵展示 Wi-Fi、播放状态。
  • battery_service: 电池服务，监控电池电压，估算剩余电量。
  • coredump_upload_service: 将设备崩溃时的 Core Dump 信息上传至服务器，便于远程调试和分析。

音频处理与高级功能

  • audio_mixer: 提供音频混音功能，将多个音频流（如背景音乐和提示音）混合成单声道或双声道音频流。
  • audio_recorder: 提供高级录音功能，支持编码存储，集成语音唤醒 (WakeNet) 和语音活动检测 (VAD)，在检测到有效语音时开始录音。
  • playlist: 提供播放列表管理功能，支持从 SD 卡或 Flash 扫描音频文件，管理播放顺序（如上一首、下一首、随机播放）。
  • tone_partition: 管理存储在 Flash 分区中的提示音，应用可通过 URI (tone://…) 访问和播放预置音频。

第三方服务与action

  • dueros_service: 专为百度 DuerOS 平台提供的组件，封装与 DuerOS 交互的逻辑。
  • esp_coze: 与 Coze (扣子) AI Agent 平台集成，允许设备与基于 Coze 平台的 AI 机器人进行语音交互。
  • esp_actions: 定义与服务相关的actions，如 wifi_action（连接、断开 Wi-Fi）、player_action（播放、暂停）等，可被 esp_dispatcher 调用。
  • esp_event_cast: 事件转换库，将一种事件类型转换为另一种，增强组件间事件交互的灵活性。

好复杂好丰富啊……

Examples

目录分类 主要功能
get-started 入门指南：提供最基础的音频播放、控制和连接示例，适合初学者快速上手。
player 播放器应用：专注于各种音源（HTTP, HLS, SD卡, Flash, 蓝牙等）的播放功能。
recorder 录音机应用：展示如何从麦克风录制音频，并编码存储为不同格式。
speech_recognition 语音识别：包含语音唤醒 (Wake Word Engine) 和语音活动检测 (VAD) 的示例。
protocols 网络协议：演示了基于特定网络协议的音视频应用，如 RTMP, RTSP, VoIP。
system 系统功能：提供系统级功能的示例，如低功耗管理、CoreDump 上传、电池管理等。
display 显示与交互：展示如何结合显示屏或 LED 灯带，为音频应用提供可视化交互。
cloud_services 云服务集成：演示如何对接到云服务平台，实现语音合成 (TTS) 和翻译等功能。
audio_processing 音频处理：包含了各种音频后处理算法的示例，如均衡器、变声、重采样等。
advanced_examples 高级应用：提供更复杂的综合性应用示例，如多房间同步、DLNA、灵活管道构建等。
ai_agent AI 代理：展示如何与 AI 代理平台（如 Coze）进行集成，实现智能对话机器人。
cli 命令行：提供一个基于命令行的交互式示例，用于测试和控制 ADF 功能。
checks 硬件检查：用于快速验证开发板上外设（如按键、LED）功能是否正常。
korvo_du1906 特定项目：一个完整的智能音箱解决方案，集成了百度 DUEROS 服务。

1. get-started (入门指南)

  • play_mp3_control
    • 简介: 最基础的 MP3 播放示例。它从代码中嵌入的 MP3 文件数据中读取并解码播放，同时展示了如何通过 audio_event_iface 监听按键事件来控制播放、暂停和音量。
    • Pipeline: i2s_stream_writer (作为 Sink) <— mp3_decoder <— i2s_stream_reader (作为 Source，但数据实际来自内存)。
  • pipeline_a2dp_sink_and_hfp （你管这叫get-started？？）
    • 简介: 演示了蓝牙音频 (A2DP Sink) 和蓝牙通话 (HFP) 功能的结合。设备既可以作为蓝牙音箱播放手机音乐，也可以接听和拨打电话。
    • Pipelines:
      • A2DP 播放: i2s_stream_writer <— bluetooth_service (内部处理 A2DP 数据流)
      • HFP 通话: i2s_stream_writer <–> hfp_stream <–> bluetooth_service (双向数据流)
  • pipeline_tcp_client
    • 简介: 演示了如何创建一个 TCP 客户端流，从一个 TCP 服务器接收音频数据并播放。
    • Pipeline: i2s_stream_writer <— mp3_decoder <— tcp_client_stream

2. player (播放器应用)

  • pipeline_a2dp_sink_stream / pipeline_bt_sink

    • 简介: 功能类似的蓝牙音箱 (A2DP Sink) 示例。手机连接开发板后，可以将手机上的音乐通过蓝牙传输给开发板播放。
    • Pipeline: i2s_stream_writer <— a2dp_stream

  • pipeline_a2dp_source_stream / pipeline_bt_source

    • 简介: 蓝牙音频发射 (A2DP Source) 示例。开发板主动连接到蓝牙耳机或音箱，并将本地的音频文件通过蓝牙发送出去播放。
    • Pipeline: a2dp_stream <— mp3_decoder <— fatfs_stream

  • pipeline_embed_flash_tone

    • 简介: 播放嵌入在代码中的提示音。音频数据作为 C 数组直接编译到固件中。
    • Pipeline: i2s_stream_writer <— mp3_decoder <— embed_flash_stream

  • pipeline_flash_tone

    • 简介: 播放存储在 Flash 特定分区 (tone) 中的提示音，通过 tone:// URI 进行访问。
    • Pipeline: i2s_stream_writer <— mp3_decoder <— tone_stream

  • pipeline_hfp_stream

    • 简介: 蓝牙免提通话 (HFP) 的独立示例，实现了完整的双向通话链路。
    • Pipeline: i2s_stream_writer (扬声器输出) <— hfp_stream <— i2s_stream_reader (麦克风输入)

  • pipeline_http_mp3

    • 简介: 播放一个网络上的 MP3 文件。
    • Pipeline: i2s_stream_writer <— mp3_decoder <— http_stream

  • pipeline_http_select_decoder

    • 简介: 演示如何根据网络流的内容类型 (Content-Type) 动态选择合适的解码器 (MP3/AAC) 进行播放。
    • Pipeline: i2s_stream_writer <— [mp3_decoder/aac_decoder] <— http_stream (动态链接)

  • pipeline_living_stream

    • 简介: 播放 HLS (HTTP Live Streaming) 直播流。
    • Pipeline: i2s_stream_writer <— mp3_decoder <— hls_stream (http_stream 的一种变体)

  • pipeline_loop_playback_without_gap

    • 简介: 演示如何实现两路 pipeline 的无缝循环播放，消除切换间隙。

    • Pipeline

      : 两个并行的 Pipeline，交替播放。

      • Pipeline 1: i2s_stream_writer <— mp3_decoder <— fatfs_stream
      • Pipeline 2: i2s_stream_writer <— mp3_decoder <— fatfs_stream

  • pipeline_play_mp3_with_dac_or_pwm

    • 简介: 展示如何使用内部 DAC 或 PWM 作为音频输出，适用于不外接 Codec 芯片的场景。
    • Pipeline: [pwm_stream_writer/dac_stream_writer] <— mp3_decoder <— i2s_stream_reader (数据来自内存)

  • pipeline_play_sdcard_music

    • 简介: 自动扫描 SD 卡中的所有音乐文件，并使用 playlist 组件进行列表播放。
    • Pipeline: i2s_stream_writer <— [decoder] <— fatfs_stream

  • pipeline_sdcard_mp3_control

    • 简介: 播放 SD 卡上的单个 MP3 文件，并支持按键控制。
    • Pipeline: i2s_stream_writer <— mp3_decoder <— fatfs_stream

  • pipeline_spiffs_mp3

    • 简介: 播放存储在 SPIFFS 文件系统中的 MP3 文件。
    • Pipeline: i2s_stream_writer <— mp3_decoder <— spiffs_stream

  • pipeline_tts_stream

    • 简介: 演示了文本转语音 (TTS) 流的使用。TTS 数据可以来自云端或本地。
    • Pipeline: i2s_stream_writer <— mp3_decoder <— tts_stream

3. recorder (录音机应用)

  • pipeline_recording_to_sdcard
    • 简介: 基础录音示例，将麦克风采集的原始 PCM 数据直接写入 SD 卡的 WAV 文件中。
    • Pipeline: fatfs_stream_writer <— i2s_stream_reader
  • pipeline_raw_http
    • 简介: 将麦克风采集的原始音频数据通过 HTTP POST 请求实时上传到服务器。
    • Pipeline: http_stream_writer <— raw_stream_reader <— i2s_stream_reader
  • pipeline_wav_amr_sdcard
    • 简介: 演示了录音并进行 AMR 编码。首先录制 WAV 文件，然后另起一个 pipeline 读取 WAV 文件，编码为 AMR 格式并存入 SD 卡。
    • Pipeline 1 (录制WAV): fatfs_stream_writer <— i2s_stream_reader
    • Pipeline 2 (转码AMR): fatfs_stream_writer <— amr_encoder <— wav_decoder <— fatfs_stream_reader

4. speech_recognition (语音识别)

  • vad (Voice Activity Detection)
    • 简介: 语音活动检测。使用 VAD 算法来检测环境中的语音片段，当检测到语音时，通过 esp_peripherals 发出事件。
    • Pipeline: vad_stream <— i2s_stream_reader (VAD 作为 Sink，但不输出数据，只产生事件)
  • wwe (Wake Word Engine)
    • 简介: 语音唤醒示例。使用乐鑫的 WakeNet 模型来识别特定的唤醒词（如“嗨，乐鑫”）。
    • Pipeline: i2s_stream_writer (用于回采) <— raw_stream_reader … esp_wn_iface (唤醒引擎) <— i2s_stream_reader (麦克风输入)。(唤醒部分不完全是标准的 pipeline，更多是算法组件的直接调用)

5. protocols (网络协议)

  • voip
    • 简介: 一个完整的 VoIP (网络电话) 客户端示例。使用 SIP 协议进行信令交互，RTP 协议传输 G.711 编码的音频数据，实现了网络通话功能。
    • Pipeline: i2s_stream_writer <— raw_stream_reader (接收) 和 raw_stream_writer <— i2s_stream_reader (发送)。数据在 sip_service 中通过 RTP 协议收发。
  • esp-rtsp / esp-rtc
    • 简介: 分别演示了 RTSP (实时流协议) 和 ESP-RTC (乐鑫自定义的实时通信协议) 的音视频传输。
    • Pipeline: 类似于 VoIP，通过 rtsp_stream 或自定义的服务处理音视频数据的收发和 pipeline 的构建。
  • rtmp
    • 简介: 演示了 RTMP (实时消息传输协议) 的推流和拉流。可以将本地音视频数据推送到 RTMP 服务器，或从服务器拉取音视频流播放。
    • Pipeline: i2s_stream_writer <— [decoder] <— rtmp_stream (拉流) 或 rtmp_stream <— [encoder] <— i2s_stream_reader (推流)。

6. system (系统功能)

  • battery
    • 简介: 使用 battery_service 通过 ADC 采样来监控电池电压，并上报事件。
    • Pipeline: 无音频 Pipeline，仅使用服务。
  • coredump
    • 简介: 演示了 CoreDump 功能。当系统崩溃时，可以将核心转储信息存储到 Flash 或通过网络上传，以便后续分析。
    • Pipeline: 无音频 Pipeline。
  • power_save
    • 简介: 展示了 ESP-ADF 的低功耗管理。在不播放音频时，系统可以进入 Light-sleep 模式以降低功耗，并通过 GPIO 或定时器唤醒。
    • Pipeline: 无音频 Pipeline。
  • wpa2_enterprise
    • 简介: 演示如何连接到需要 WPA2-Enterprise 认证的 Wi-Fi 网络。
    • Pipeline: 无音频 Pipeline。

7. advanced_examples (高级应用)

  • aec (Acoustic Echo Cancellation)
    • 简介: 回声消除示例。在需要双工通话的场景（如免提通话），此算法可以消除扬声器播放的声音被麦克风重新采集而产生的回声。
    • Pipeline: aec_stream <— i2s_stream_reader (AEC 元素需要两路输入：麦克风信号和参考信号，参考信号由 aec_stream_set_playback 写入)。
  • audio_mixer_tone
    • 简介: 音频混音示例。演示了如何使用 audio_mixer 将一个正在播放的音乐流和一个提示音流混合后输出。
    • Pipeline: i2s_stream_writer <— audio_mixer。audio_mixer 有两个输入环形缓冲区，分别接收来自音乐播放 Pipeline 和提示音播放 Pipeline 的数据。
  • dlna
    • 简介: 实现 DLNA 的数字媒体渲染器 (DMR) 功能。允许局域网内的 DLNA 控制点（如手机 App）发现设备，并将音乐推送到设备上播放。
    • Pipeline: i2s_stream_writer <— [decoder] <— http_stream。其中 http_stream 的 URL 由 DLNA 服务动态设置。
  • flexible_pipeline
    • 简介: 展示如何动态地构建和修改音频管道，例如在播放过程中切换音源（HTTP 和 SD 卡）。
    • Pipeline: 动态变化。[http_stream/fatfs_stream] <-> audio_element_switch —> i2s_stream_writer。
  • http_play_and_save_to_file
    • 简介: 演示如何一边通过 HTTP 播放在线音乐，一边将下载的数据保存到 SD 卡中，实现边听边缓存。
    • Pipeline: i2s_stream_writer <— mp3_decoder <— fatfs_stream_writer <— http_stream_reader。
  • multi-room
    • 简介: 多房间音频同步示例。允许多个设备在局域网内同步播放相同的音乐。通过 ESP-NOW 进行设备间的时间同步和控制。
    • Pipeline: 主设备: i2s_stream_writer <— [decoder] <— fatfs_stream，并向从设备广播数据。从设备: i2s_stream_writer <— [decoder] <— raw_stream (接收主设备的数据)。
  • nvs_dispatcher
    • 简介: 演示了如何使用 esp_dispatcher 框架，并结合 NVS (非易失性存储) 来实现持久化的配置和动作分发。
    • Pipeline: 这是一个框架使用示例，不一定包含完整的音频 Pipeline。
  • wifi_bt_ble_coex
    • 简介: Wi-Fi, 经典蓝牙 (BT), 低功耗蓝牙 (BLE) 共存的综合示例。展示了设备在播放 Wi-Fi 音乐的同时，还能响应 BLE 的控制命令。
    • Pipeline: i2s_stream_writer <— mp3_decoder <— http_stream，同时 BLE 服务在后台运行。