jason-mao/av_processor

readme (zh)

# AV Processor 组件（音视频处理）

`av_processor` 是一个面向应用层的音视频处理组件，用来把 ESP 平台上常见的音频与视频中间件能力整理成更统一、更容易集成的一组模块。

它构建在 GMF、`esp_audio_simple_player`、`esp_capture`、`esp_video_codec` 等基础能力之上，适合需要同时处理录音、播放、视频采集以及调试导出的项目。

## 文档导航

本 `README_CN.md` 只保留组件概览、能力说明和示例入口。

如果你要查看完整 API、配置结构体、生命周期、模式差异、使用流程和注意事项，请直接跳转到下面这些文档：

- 详细使用指南（含完整 API 索引）：[docs/COMPONENT_GUIDE_CN.md](av_processor/docs/COMPONENT_GUIDE_CN.md)
- 音频 API 头文件：[include/audio_processor.h](av_processor/include/audio_processor.h)
- 视频 API 头文件：[include/video_processor.h](av_processor/include/video_processor.h)
- 公共类型定义：[include/av_processor_type.h](av_processor/include/av_processor_type.h)

## 组件能力概览

### 音频能力

- 音频管理器初始化与板级输入输出抽象
- 音频录制，基于 `audio_recorder_handle_t` 管理实例
- 录音链路前端处理
- 录音输出编码，支持 PCM、G711、OPUS、AAC、MP3 等格式
- 统一音频播放接口，基于 `audio_play_handle_t` 管理实例，支持 URL 或本地文件
- Feeder 喂数播放，基于 `audio_feeder_handle_t` 管理实例，适合 RTC、网络流、私有协议接收后本地播放
- 提示音播放通过同一套 `audio_play_*` API 实现，适合短音频、阻塞式、高优先级场景
- 可选混音器，以及播放流和 feeder 流之间的焦点/渐变控制

### 前端与算法能力

- 内置 `ai_afe` 路径，可直接使用 `esp-sr` 中整套 AFE 能力
- custom frontend 路径，面向按模块组合 `esp-sr` 独立能力的接入方式
- 支持按需启用 AEC、NS、VAD、AGC、Wakeup、Voice Command Detection 等能力
- 当前 custom 路径已内置支持独立 WakeNet 场景

### 视频能力

- 视频采集
- 多 sink 输出
- 流模式回调处理
- fetch 模式获取/释放帧
- 视频解码
- 解码后的渲染回调

### 调试与问题分析能力

- Media Dump 调试导出
- 支持将录音链路中的音频原始数据导出到 SD 卡或通过 UDP 发送
- 支持抓取 AEC 前或 AEC 后的数据，便于分析回声、回授、削顶、底噪和处理效果

## 适合的典型场景

- 设备端录音并上传到云端或本地存储
- 网络音频接收后边解码边播放
- 播放主音频流时插入高优先级提示音
- 摄像头采集后做本地预览、编码输出或多路分发
- 同时输出压缩视频流和原始视频流
- 复现现场问题后导出原始音频做离线分析

## 音频模块实例模型

当前音频 API 已统一为 handle 风格：

- `audio_recorder_open(..., &handle)` 创建录音实例
- `audio_feeder_open(..., &handle)` 创建喂数实例
- `audio_play_open(..., &handle)` 创建播放实例
- 通过 `audio_play_config_t.type` 区分普通播放和提示音播放

后续的 `pause`、`resume`、`read`、`feed`、`play`、`stop`、`close` 都需要显式传入对应 handle。

这意味着同一应用中可以同时持有多个实例，例如同时创建两个 recorder，或者同时存在 playback 类型和 prompt 类型的 play 实例。

## 示例工程

仓库中已经提供了几组比较典型的示例，建议优先从示例入手理解组件的整体使用方式。

### 音频示例

- [examples/audio_afe](av_processor/examples/audio_afe)
  演示内置 `ai_afe` 路径，适合查看 AEC、NS、VAD、AGC 等前端处理能力的接入方式。

- [examples/audio_sr_vc_switch](av_processor/examples/audio_sr_vc_switch)
  演示在 `AFE_TYPE_SR` 和 `AFE_TYPE_VC` 两种录音前端之间切换，也适合参考多 recorder 实例和控制台切换流程。

- [examples/audio_wn](av_processor/examples/audio_wn)
  演示 custom frontend 路径和独立 WakeNet 的使用方式，也适合参考录音事件回调的处理流程。

- [examples/audio_echo](av_processor/examples/audio_echo)
  演示音频播放和 feeder 相关能力，适合做播放链路、混音器和接收后播放场景的参考。

- [examples/audio_play_test](av_processor/examples/audio_play_test)
  演示统一 `audio_play_*` API、普通播放与提示音播放、feeder 喂数、混音焦点切换以及控制台交互命令。

- [examples/audio_mem_leak](av_processor/examples/audio_mem_leak)
  用于循环验证 recorder、play、feeder 等模块的打开/关闭过程，适合做内存占用和泄漏排查。

### 视频示例

- [examples/video_preview](av_processor/examples/video_preview)
  演示视频采集与预览流程，适合快速理解 capture 的基本接法。

- [examples/video_test](av_processor/examples/video_test)
  用于验证和测试视频链路相关能力，适合排查 sink、格式和处理链路问题。

## Media Dump 说明

Media Dump 是一个面向调试的辅助能力，不是常规业务 API。

目前它主要用于录音链路音频数据导出，可用于：

- 排查“设备播放的声音再次被麦克风收回去”的回授问题
- 评估 AEC 处理前后的差异
- 检查音频是否存在削顶、饱和、底噪偏大、格式不匹配等问题

当前支持：

- AEC 前抓取
- AEC 后抓取
- SD 卡文件输出
- UDP 实时发送

详细配置方式和注意事项请查看：

- Media Dump 详细说明：[docs/COMPONENT_GUIDE_CN.md](av_processor/docs/COMPONENT_GUIDE_CN.md)

## 如何选择阅读路径

- 如果你只是想知道这个组件能做什么，以及应该从哪个示例开始，看本 README 就够了。
- 如果你已经准备接入代码，需要查看结构体、宏、API 调用顺序、完整 API 索引或模式差异，请直接看 [docs/COMPONENT_GUIDE_CN.md](av_processor/docs/COMPONENT_GUIDE_CN.md)。
- 如果你要确认函数签名、枚举值和配置字段，请直接查看公共头文件：
  [include/audio_processor.h](av_processor/include/audio_processor.h)
  [include/video_processor.h](av_processor/include/video_processor.h)
  [include/av_processor_type.h](av_processor/include/av_processor_type.h)

## 版本信息

当前版本：`v0.5.8`

## 许可证

本组件遵循 MIT 许可证，详见仓库中的 `LICENSE` 文件。

## 相关资源

- 问题反馈：https://github.com/espressif/esp-gmf/issues