多媒体技术 Wiki：Component Description

[English]

ESP-New-JPEG 组件

备注

有关 JPEG 的基础知识，可参考 JPEG

概述：

ESP-New-JPEG 是乐鑫科技推出的轻量级 JPEG 编解码库。为提高效率，JPEG 编解码器经过深度优化，减少了内存消耗并提升了处理性能。对于支持 SIMD 指令的 ESP32-S3 芯片，利用这些指令进一步提升了处理速度。此外，还扩展了旋转、裁剪和缩放功能，能够在编解码过程中同时进行，从而简化用户操作。针对内存较小的芯片，引入了 block 模式，支持多次处理部分图像内容，有效减少内存压力。

ESP-New-JPEG 支持 Baseline Profile 的 JPEG 编解码，旋转、裁剪、缩放和 block 模式等功能仅在特定配置下能生效。

JPEG 编码器功能：

编码器支持的 基本功能 如下：

• 支持任意宽度和高度解码

• 支持以下像素格式：RGB888、RGBA、YCbYCr、YCbY2YCrY2、GRAY

  • 当采用 YCbY2YCrY2 格式时，仅支持 YUV420 和 Gray 子采样

• 支持 YUV444、YUV422、YUV420、Gray 子采样

• 支持质量设置范围：1-100

扩展功能 如下：

• 支持 0°、90°、180°、270° 顺时针旋转

• 支持双任务（dual-task）编码

• 支持分块模式（block mode）编码

双任务编码可在双核芯片上使用，充分发挥双核并行编码的优势。其原理是一个核心处理主要编码任务，另一个核心负责熵编码部分的工作。在大多数情况下，启用双核编码能带来约 1.5 倍的性能提升。可以通过 menuconfig 配置选择是否启用双核解码，并调整熵编码任务的核心和优先级。

分块编码是指每次仅编码一个图像块的数据，经过多次处理后编码完整的图像。在 YUV420 子采样时，每个块的高度为 16 行，宽度为图像宽度；其他子采样格式下，每个块的高度为 8 行，宽度为图像宽度。由于分块编码每次处理的数据量较小，图像缓冲区可放入 DRAM，从而提高编码速度。分块编码的工作流程如下图所示：

扩展功能的配置要求如下所示：

JPEG 解码器功能：

解码器支持的 基本功能 如下：

• 支持任意宽度和高度解码

• 支持单通道和三通道解码

• 支持以下像素格式输出：RGB888、RGB565（大端）、RGB565（小端）、CbYCrY

扩展功能 如下：

• 支持缩放（最大缩小倍率为 1/8）

• 支持裁剪（以左上角为原点进行裁剪）

• 支持 0°、90°、180°、270° 顺时针旋转

• 支持分块模式（block mode）解码

使用缩放和裁剪功能时，需要配置对应的参数 jpeg_resolution_t。组件支持仅对宽度或高度进行单独处理，例如，仅裁剪宽度而保持高度不变时，可以设置 clipper.height = 0，此时图像的高度将保持为原始 JPEG 图像的高度。

缩放、裁剪和旋转的处理流程是顺序进行的，示意图如下。解码后的 JPEG 数据流首先进行缩放，然后进行裁剪，最后进行旋转和输出。

分块解码是指每次仅解码一个图像块的数据，经过多次处理后完成整个图像的解码。在 YUV420 子采样时，每个块的高度为 16 行，宽度为图像宽度；对于其他子采样格式，每个块的高度为 8 行，宽度为图像宽度。由于分块解码每次处理的数据量较小，因此对于没有 PSRAM 的芯片更加友好，同时将输出图像缓冲区放入 DRAM 也能提高解码速度。分块解码的操作可以看成是分块编码的反过程。

扩展功能的配置要求如下所示：

• 启用分块解码时，无法使用其他扩展功能

• 缩放、裁剪和旋转的配置参数中的宽度和高度均要求是 8 的整数倍

• 当同时启用缩放和裁剪时，要求裁剪的大小小于缩放后的大小

使用方法：

ESP-New-JPEG 组件托管在 Github。可以通过在工程中输入以下命令将该组件添加到你的工程中。

idf.py add-dependency “espressif/esp_new_jpeg”

esp_new_jpeg 文件夹下的 test_app 文件夹中包含一个可运行的测试工程，里面展示了相关 API 调用流程。在使用 ESP-New-JPEG 组件前，建议先参考和调试该测试工程，以熟悉 API 的使用方法。

性能：

ESP-New-JPEG 对 JPEG 编解码架构进行了深度优化：

• 优化数据处理流程，提高中间数据的复用效率，减少内存拷贝开销。

• 针对 Xtensa 架构芯片进行汇编级优化；在支持 SIMD 指令的 ESP32-S3 芯片上，显著提升计算性能。

• 将裁剪、旋转等多种图像操作整合进编解码器，提升整体系统效率

编解码性能测试数据请参考 Performance。

FAQ：

Q: ESP-New-JPEG 支持解码渐进式 JPEG 吗？

A: 不支持，ESP-New-JPEG 仅支持解码基线 JPEG。可以使用以下代码检查图像是否为渐进式 JPEG。输出 1 表示渐进式 JPEG，输出 0 表示基线 JPEG。

python
>>> from PIL import Image
>>> Image.open("file_name.jpg").info.get('progressive', 0)

Q: 为什么输出图像看起来错位？

A：此问题通常发生在图像的左侧或右侧出现一些列，且这些列出现在图像的另一侧。如果您使用的是 ESP32-S3，可能的原因是解码器的输出缓冲区或编码器的输入缓冲区没有进行 16 字节对齐。请使用 jpeg_calloc_align() 函数来分配缓冲区。

Q: 如何预览图像原始数据，如查看 RGB888 数据？

A：可以使用 yuvplayer。支持查看灰度、RGB888、RGB565（小端）、UYVY、YUYV，YUV420P 等数据。

相关链接：

• 组件注册表: esp_new_jpeg component

GMF-AI-Audio 组件

概述：

GMF-AI-Audio 是基于 GMF 框架开发的语音交互组件，通过封装 ESP-SR，提供从语音唤醒到指令识别的完整交互逻辑。组件集成了唤醒词检测（Wake Word）、语音活动检测（VAD）、语音指令识别以及回声消除（AEC）等功能，能够在智能音箱、智能家居等设备中实现高效、自然的语音交互体验。

支持场景：

方式	对应场景
唤醒后立即上传语音数据，在 Wakeup End 阶段停止上传	在云端实现 VAD 功能、RTC 场景
唤醒后等待 VAD 触发后开始上传，VAD 结束后停止上传	以往智能硬件的交互方式
无唤醒，等待 VAD 触发后开始上传，VAD 结束后停止上传	新式云端处理逻辑
按键后立即上传语音数据，松手后停止	算力有限的设备通过与云端交互实现语音功能
按键后等待 VAD 触发后开始上传，VAD 结束后停止上传	解决仅依赖 VAD 造成的数据量过大的问题
唤醒后检测命令词	默认使用逻辑
无唤醒，等待 VAD 触发后检测命令词	可应用于部分车辆系统
按键后检测命令词	玩具
连续命令词识别	家居控制

相关链接：

• 详细文档：GMF AI Audio 组件

• 演示工程：GMF AI Audio 示例

ESP-H264 组件

概述：

ESP-H264 是乐鑫科技开发的轻量级 H.264 编码器和解码器组件，提供硬件和软件两种实现方式。硬件编码器专为 ESP32-P4 芯片设计，可实现 1080P@30fps。软件编码器基于 openh264，解码器基于 tinyH264，两者都针对内存和 CPU 使用进行了优化，确保在乐鑫芯片上的最佳性能。

功能：

• 编码器功能

  • 硬件编码器 (ESP32-P4)：

    • 支持 Baseline Profile (最大帧大小 36864 宏块)

    • 支持宽度范围 [80, 1088] 像素，高度范围 [80, 2048] 像素

    • 支持质量优先的码率控制

    • 支持 YUV420 原始数据格式

    • 支持动态调整码率、帧率、GOP、QP 等参数

    • 支持单流和双流编码器

    • 支持去块滤波器、ROI、运动矢量功能

    • 支持 SPS 和 PPS 编码

  • 软件编码器：

    • 支持 Baseline Profile (最大帧大小 36864 宏块)

    • 支持宽度和高度大于 16 像素的任意分辨率

    • 支持质量优先的码率控制

    • 支持 YUYV 和 IYUV 原始数据格式

    • 支持动态调整码率、帧率

    • 支持 SPS 和 PPS 编码

• 解码器功能

  • 支持 Baseline Profile (最大帧大小 36864 宏块)

  • 支持各种宽度和高度

  • 支持长期参考 (LTR) 帧

  • 支持内存管理控制操作 (MMCO)

  • 支持参考图像列表修改

  • 支持序列参数集 (SPS) 中指定的多参考帧

  • 支持 IYUV 输出格式

性能：

• 编码性能：ESP32-P4 推荐使用硬件编码器，ESP32-S3 及其他板子使用软件编码器

  • 硬件编码器（仅 ESP32-P4）：

    • 性能功耗更佳，最大支持 1080P@30fps

    • 支持单流/双流编码

    • 支持动态调整码率、帧率、GOP、QP 等参数

    • 支持去块滤波器、ROI、运动矢量等高级功能

  • 软件编码器（全平台）：

    • 性能功耗有限，但无分辨率限制

    • 支持 YUYV 和 IYUV 格式，颜色格式更丰富

    • 支持所有乐鑫芯片平台，板子选择更多

    • 基于 OpenH264 开源项目

编码性能对比

平台	类型	最大分辨率	最大性能	备注
ESP32-S3	软件编码器	任意	320×240@11fps
ESP32-P4	硬件编码器	≤1080P	1920×1080@30fps	硬件加速

• 解码性能：所有板子均推荐使用软件解码器

  • 软件解码器（全平台）：

    • 性能功耗有限，但无分辨率限制

    • 支持 IYUV 输出格式

    • 支持长期参考帧、内存管理控制等高级功能

    • 基于 TinyH264 开源项目

解码性能对比

平台	类型	最大分辨率	最大性能
ESP32-S3	软件解码器	任意	320×192@27fps
ESP32-P4	软件解码器	任意	1280×720@10fps

警告

内存消耗强烈依赖于 H.264 流的分辨率和编码数据。建议根据实际应用场景调整内存分配。

小技巧

使用双任务解码器可以显著提升解码性能，特别是在高分辨率视频处理时。

组件链接：

• 组件注册表: esp_h264 component

• 示例项目: ESP H.264 Sample Projects

• 使用技巧: ESP-H264 使用技巧文档

相关资源：

• H.264 标准文档

• OpenH264 项目

• TinyH264 项目

ESP-Image-Effects 组件

概述：

ESP-Image-Effects 是乐鑫科技开发的图像处理引擎，集成了旋转、色彩空间转换、缩放、裁剪等基础功能。作为乐鑫音视频开发平台的核心组件之一，ESP-Image-Effects 模块对底层算法进行了深度重构，结合高效的内存管理和硬件加速，实现了高性能、低功耗、低内存占用的三重特性。此外，每个图像处理功能都采用一致的 API 架构设计，降低了用户的学习成本，便于快速开发。该引擎广泛应用于物联网、智能摄像头、工业视觉等多个领域。

功能：

• 图像颜色转换

  • 支持任意输入分辨率

  • 支持相同输入/输出格式的旁路模式

  • 支持 BT.601/BT.709/BT.2020 色彩空间标准

  • 支持针对格式和分辨率的快速颜色转换算法

  • 全面的格式支持矩阵：

  颜色转换格式支持

  输入格式	支持的输出格式
  RGB/BGR565_LE/BE RGB/BGR888	RGB565_LE/BGR/RGB565_LE/BE RGB/BGR888 YUV_PLANAR/PACKET YUYV/UYVY O_UYY_E_VYY/I420
  ARGB/BGR888	RGB565_LE/BGR/RGB565_LE/BE RGB/BGR888 YUV_PLANAR O_UYY_E_VYY/I420
  YUV_PACKET/UYVY/YUYV	RGB565_LE/BGR/RGB565_LE/BE RGB/BGR888 O_UYY_E_VYY/I420
  O_UYY_E_VYY/I420	RGB565_LE/BGR/RGB565_LE/BE RGB/BGR888 O_UYY_E_VYY

• 图像旋转

  • 支持旁路模式

  • 支持任意输入分辨率

  • 支持任意角度的顺时针旋转

  • 支持 ESP_IMG_PIXEL_FMT_Y/RGB565/BGR565/RGB888/BGR888/YUV_PACKET 格式

  • 支持针对特定角度、格式和分辨率的快速顺时针旋转算法

• 图像缩放

  • 支持旁路模式

  • 支持任意输入分辨率

  • 支持上采样和下采样操作

  • 支持 ESP_IMG_PIXEL_FMT_RGB565/BGR565/RGB888/BGR888/YUV_PACKET 格式

  • 支持多种滤波算法：优化的下采样和双线性插值

• 图像裁剪

  • 支持旁路模式

  • 支持任意输入分辨率

  • 支持上采样和下采样操作

  • 支持灵活的区域选择

  • 支持 ESP_IMG_PIXEL_FMT_Y/RGB565/BGR565/RGB888/BGR888/YUV_PACKET 格式

性能：

ESP-Image-Effects 组件已完成 1080P 下的性能测试，具体性能数据请参考 ESP32-P4 性能文档。该组件采用高效的内存管理和硬件加速技术，实现了高性能、低功耗、低内存占用的三重特性。

相关链接：

• 组件注册表: esp_image_effects component

• 示例项目: ESP-Image-Effects 示例项目

• 组件发布文档: 图像处理发布文档

• 常见问题：ESP-Image-Effects 官方文档

ESP-Audio-Effects 组件

概述：

ESP-Audio-Effects 是一个功能强大且灵活的音频处理库，旨在为开发者提供高效的音频效果处理能力。该组件广泛应用于各类智能音频设备，包括智能音箱、耳机、音频播放设备，以及语音交互系统。

功能：

• 自动电平控制：自动调节输入增益以稳定音频音量。渐进式调整确保平滑过渡。动态校正过度放大以避免削波失真。

• 均衡器：提供对滤波器类型、频率、增益和 Q 因子的精细控制。适用于音频调谐和专业信号塑形。

• 淡入淡出：实现淡入和淡出效果，确保音轨之间的平滑过渡。

• 音速音调处理：支持实时速度和音调修改，实现更动态的播放效果。

• 混音器：将多个输入流合并为一个输出，可为每个输入配置起始/目标权重和过渡时间。

• 数据编织器：处理音频数据缓冲区的交织和解交织。

• 采样率转换：在 4000 和 11025 的倍数之间进行采样率转换。

• 通道转换：使用权重数组重新映射音频通道布局。

• 位深转换：支持 U8、S16、S24 和 S32 位深度之间的转换。

下表列出了每个模块所支持的采样率、声道数和采样位深。如果用户想了解每个模块的详细介绍、性能、示例以及其他信息，可以点击 模块 列中的 README 链接。

颜色转换格式支持

模块	采样率	声道数	采样位深	数据布局
自动电平控制	全范围	全范围	s16, s24, s32	交错与去交错
均衡器	全范围	全范围	s16, s24, s32	交错与去交错
淡入淡出	全范围	全范围	s16, s24, s32	交错与去交错
音速音调处理	4 至 192 kHz，以及 4000 或 11025 的整数倍	全范围	s16, s24, s32	交错
混音器	全范围	全范围	s16, s24, s32	交错与去交错
数据编织器	全范围	全范围	s16, s24, s32	交错与去交错
采样率转换	4 至 192 kHz，以及 4000 或 11025 的整数倍	全范围	s16, s24, s32	交错与去交错
通道转换	全范围	全范围	s16, s24, s32	交错与去交错
位深转换	全范围	全范围	u8, s16, s24, s32	交错与去交错

数据布局：

ESP-Audio-Effects 支持交织和解交织两种音频格式：

1. 交织格式：使用 esp_ae_xxx_process() API 处理此布局。例如：

L0 R0 L1 R1 L2 R2 ...

其中 L 和 R 分别代表左右声道样本。

2. 解交织格式：使用 esp_ae_xxx_deintlv_process() API。每个通道存储在单独的缓冲区中：

L1, L2, L3, ...  // 左声道
R1, R2, R3, ...  // 右声道

API 风格:

ESP-Audio-Effects 提供一致且开发者友好的 API：

颜色转换格式支持

类别	函数	描述
初始化	esp_ae_xxx_open()	创建音频效果句柄。
交织处理	esp_ae_xxx_process()	处理交织音频数据。
解交织处理	esp_ae_xxx_deintlv_process()	处理解交织音频数据。
设置参数	esp_ae_xxx_set_xxx()	设置组件特定参数。
获取参数	esp_ae_xxx_get_xxx()	获取当前参数。
释放	esp_ae_xxx_close()	释放资源并销毁句柄。

相关链接：

• 组件注册表: esp_audio_effects component

ESP-Audio-Codec 组件

概述：

ESP-Audio-Codec 是乐鑫官方为 SoC 平台开发的音频编解码处理模块，提供标准化的编码与解码接口框架，便于用户在不同音频格式间进行灵活扩展与组合使用。该模块主要包括 ESP Audio Encoder（音频编码器）、ESP Audio Decoder（音频解码器） 和 Simple Decoder（简易解码器） 三个部分。

• ESP Audio Encoder 提供了统一的编码器接口，支持注册多种编码器（如 AAC、AMR-NB、AMR-WB、ADPCM、G711A、G711U、PCM、OPUS、ALAC 等）。用户可基于接口创建一个或多个编码器实例，实现多路同时编码。也可直接调用指定编码器的 API，以减少调用层级。

• ESP Audio Decoder 提供了统一的解码器接口，支持注册多种解码器（如 AAC、MP3、AMR-NB、AMR-WB、ADPCM、G711A、G711U、VORBIS、OPUS、ALAC 等）。用户可通过接口创建一个或多个解码器实例，实现多路同时解码。也可直接调用指定解码器的 API，以减少调用层级。ESP Audio Decoder 仅支持处理音频帧数据（即输入数据需为帧边界）。

• Simple Decoder 通过解析器聚合和组织音频帧，再调用 ESP Audio Decoder 进行解码，以简化音频帧的解析与定位。用户可输入任意长度的数据。该解码器支持的音频容器包括 AAC、MP3、WAV、FLAC、AMRNB、AMRWB、M4A 等。

主要特性：

• 易用接口：提供友好的用户接口，便于开发和集成。

• 高性能与轻量级：模块经过优化，兼具高性能和低内存占用。

• 双层解码器 API：输入数据为帧边界时可用 ESP Audio Decoder；任意长度数据可用 Simple Decoder。两者 API 类似，便于切换。

• 高度可定制：通过注册接口，用户可轻松添加自定义解码器、编码器或简易解码器，也可覆盖默认实现，无需修改应用代码。

功能特性：

• ESP Audio Encoder：提供统一的编码器接口，所有编码器均可通过统一 API 操作（详见 esp_audio_enc.h）。模块支持通过 esp_audio_enc_register() 注册自定义编码器或覆盖默认实现，也可使用 esp_audio_enc_register_default() 一键注册全部受支持的编码器，并可通过 menuconfig 统一管理。模块支持的编码器及其详细参数如下：

  • AAC:

    • 支持 AAC-LC（低复杂度）编码

    • 采样率（Hz）：96000, 88200, 64000, 48000, 44100, 32000, 24000, 22050, 16000, 12000, 11025, 8000

    • 声道数：单声道、双声道

    • 位深：16 位

    • 固定码率：12 Kbps ~ 160 Kbps

    • 可选择是否写入 ADTS 头

  • AMR:

    • 支持窄带（NB）和宽带（WB）编码

    • AMRNB 采样率：8 kHz

    • AMRWB 采样率：16 kHz

    • 声道数：单声道

    • 位深：16 位

    • AMRNB 码率（Kbps）：4.75, 5.15, 5.9, 6.7, 7.4, 7.95, 10.2, 12.2

    • AMRWB 码率（Kbps）：6.6, 8.85, 12.65, 14.25, 15.85, 18.25, 19.85, 23.05, 23.85

    • 支持 DTX（不连续传输）

  • ADPCM:

    • 支持所有采样率

    • 声道数：单声道、双声道

    • 位深：16 位

  • G711:

    • 支持 A-LAW 和 U-LAW

    • 支持所有采样率

    • 支持所有声道数

    • 位深：16 位

  • OPUS:

    • 采样率（Hz）：8000, 12000, 16000, 24000, 48000

    • 声道数：单声道、双声道

    • 位深：16 位

    • 固定码率：20 Kbps ~ 510 Kbps

    • 帧时长（ms）：2.5, 5, 10, 20, 40, 60, 80, 100, 120

    • 支持 VoIP 和音乐模式

    • 编码复杂度可调（0~10）

    • 支持 FEC（前向纠错）、DTX（不连续传输）、VBR（可变码率）

  • ALAC:

    • 采样率（Hz）：[1000, 384000]

    • 声道数：[1, 8]

    • 位深：16, 24, 32位

  • SBC:

    • 采样率（Hz）：16000, 32000, 44100, 48000

    • 声道模式：单声道、双声道、立体声、联合立体声

    • 位深：16 位

    • SBC 模式：标准、mSBC

    • 块长度：4, 8, 12, 16

    • 子带数：4, 8

    • 分配方式：响度、SNR

    • bitpool 范围：2~250

  • LC3:

    • 采样率（Hz）：8000, 16000, 24000, 32000, 44100, 48000

    • 支持全声道

    • 位深：16、24、32 位

    • 帧时长（dms）：7.5、10

    • nbyte 范围：20~400

    • 支持每帧前加 2 字节长度前缀

  • PCM

• ESP Audio Decoder：提供统一的解码器接口，所有解码器均可通过统一 API 操作（详见 esp_audio_dec.h）。模块支持通过 esp_audio_dec_register() 注册自定义解码器或覆盖默认实现，也可使用 esp_audio_dec_register_default() 一键注册全部受支持的解码器，并可通过 menuconfig 统一管理。模块支持的解码器及其详细参数如下：

  • AAC:

    • 支持 AAC-LC、AAC-Plus 编码

    • 可配置是否启用 AAC-Plus 解码，以降低 CPU 和内存占用

    • 采样率（Hz）：96000, 88200, 64000, 48000, 44100, 32000, 24000, 22050, 16000, 12000, 11025, 8000

    • 声道数：单声道、双声道

    • 位深：16 位

    • 支持解码包含或不包含 ADTS 头的音频数据

  • AMR:

    • 支持窄带（NB）和宽带（WB）解码

    • AMRNB 采样率：8 kHz

    • AMRWB 采样率：16 kHz

    • 声道数：单声道

    • 位深：16 位

  • ADPCM:

    • 支持所有采样率

    • 声道数：单声道、双声道

    • 位深：16 位

    • 仅支持 IMA-ADPCM

  • G711:

    • 支持 A-LAW 和 U-LAW

    • 支持所有采样率

    • 支持所有声道数

    • 位深：16 位

  • OPUS:

    • 采样率（Hz）：8000, 12000, 16000, 24000, 48000

    • 声道数：单声道、双声道

    • 位深：16 位

    • 支持自分隔包解码

  • ALAC:

    • 采样率（Hz）：8000, 12000, 16000, 24000, 48000

    • 声道数：单声道、双声道

    • 位深：16 位

  • FLAC:

    • 采样率（Hz）：96000, 48000, 44100, 32000, 24000, 22050, 16000, 12000, 11025, 8000

    • 声道数：[1, 8]

    • 位深：16、24、32 位

  • VORBIS:

    • 采样率（Hz）：48000, 44100, 32000, 24000, 22050, 16000, 12000, 11025, 8000

    • 声道数：单声道、双声道

    • 位深：16 位

    • 仅支持 VORBIS 帧解码，需去除 OGG 头

    • 用户需先提供通用头信息

  • SBC:

    • 采样率（Hz）：16000, 32000, 44100, 48000

    • 声道单声道、双声道

    • 位深：16 位

    • SBC 模式：标准、mSBC

    • 支持丢包隐藏（PLC）

  • LC3:

    • 采样率（Hz）：8000, 16000, 24000, 32000, 44100, 48000

    • 支持全声道

    • 位深：16、24、32 位

    • 帧时长（dms）：7.5、10

    • nbyte 范围：20~400

    • 支持 2 字节长度前缀帧数据解码

    • 支持丢包隐藏（PLC）

  • MP3

• Simple Decoder

  • 简易解码器可通过 API 操作，详见 esp_audio_simple_dec.h

  • 支持部分音频容器的音频帧查找与解码

  • 支持通用解析器，用户可根据规则添加自定义解析器

  • 支持自定义简易解码器以适配新文件格式

  • 支持自定义解析器与解码器配对：可用默认解析器配合自定义解码器

  • 仅支持流式解码，不支持 seek

  • 支持的音频容器及说明如下：

音频容器	说明
AAC	支持 AAC-Plus（可配置），带解析器可输入任意大小的数据
MP3	支持 Layer 1、2、3，带解析器可输入任意大小的数据
AMRNB	仅支持带 AMRNB 文件头的文件，带解析器可输入任意大小的数据
AMRWB	仅支持带 AMRWB 文件头的文件，带解析器可输入任意大小的数据
FLAC	仅支持带 FLAC 文件头的文件，带解析器可输入任意大小的数据
WAV	支持 G711A、G711U、PCM、ADPCM，带解析器可输入任意大小的数据
M4A	支持 MP3、AAC、ALAC，且仅支持 MOOV 后的 MDAT，带解析器可输入任意大小的数据
TS	支持 MP3、AAC，带解析器可输入任意大小的数据
G711	支持 G711A、G711U，可输入任意大小的数据
ADPCM	仅支持 IMA-ADPCM，不带解析器输入帧必须是完整音频帧
SBC	支持 SBC 和 MSBC，不带解析器输入帧必须是完整音频帧
LC3	支持 LC3，不带解析器输入帧必须是完整音频帧
OPUS	支持 OPUS，不带解析器输入帧必须是完整音频帧

性能表现：

• 编码器性能

  编码器	采样率（Hz）	声道	内存（KB）	CPU 占用（%）
  AAC	48000	2	51.4	12.9
  G711-A	8000	1	0.06	0.32
  G711-U	8000	1	0.06	0.33
  AMR-NB	8000	1	3.3	17.81
  AMR-WB	16000	1	5.6	37.69
  ADPCM	48000	2	0.01	2.69
  OPUS	48000	2	29.4	24.9
  SBC	48000	2	1.85	9.55
  LC3	48000	2	3.67	46.57

  • 编码器 CPU 占用高度依赖于编码参数（如码率、复杂度等）

  • AAC 编码器测试码率为 90 kbps

  • AMR-NB/AMR-WB 编码器测试码率分别为 12.2 kbps/8.85 kbps

  • OPUS 编码器测试码率为 90 kbps，复杂度为 0

  • 内存仅统计堆使用，不含栈。支持所有编码器时，建议任务栈大小约 40 K

• 解码器性能

  解码器	采样率（Hz）	声道	内存（KB）	CPU 占用（%）
  AAC	48000	2	51.2	6.75
  G711-A	8000	1	0.04	0.14
  G711-U	8000	1	0.04	0.13
  AMR-NB	8000	1	1.8	4.23
  AMR-WB	16000	1	5.4	9.5
  ADPCM	48000	2	0.11	2.43
  OPUS	48000	2	26.6	5.86
  MP3	44100	2	28	8.17
  FLAC	44100	2	89.4	8.0
  SBC	48000	2	0.21	8.14
  LC3	48000	2	1.36	17.5

  • MP3 和 FLAC 解码器为真实音频数据测试，其余为正弦波 PCM 编码数据

  • AAC 解码器测试文件为 AAC-LC；AAC-Plus 解码时内存和 CPU 占用更高

  • 内存仅统计堆使用。支持所有解码器时，建议任务栈大小约 20 K

Codec 对比:

下表为 ESP-Audio-Codec 支持的 Codec 特性对比：

常见音频 Codec 特性对比

Codec	特点	典型码率范围（kbps）	适用场景
AAC (Advanced Audio Coding)	有损压缩，音质优于 MP3，同码率下更高效；广泛支持。	96 – 320（立体声常用 128–256）	在线音乐、视频流媒体（YouTube、Apple Music、广播）。
MP3	最普及的有损压缩格式，兼容性极佳，但压缩效率比 AAC/Opus 略低。	128 – 320（低至 64 也可用）	音乐下载、传统播放器、车载音响。
AMR-NB / AMR-WB	专为语音优化，低比特率下语音清晰；NB（8kHz）、WB（16kHz）。	AMR-NB: 4.75 – 12.2；AMR-WB: 6.6 – 23.85	移动通信（2G/3G 电话通话）、VoIP、语音消息。
ADPCM	简单压缩，延迟低，音质有限；压缩效率不高。	常见 16 – 64	早期语音存储、嵌入式设备、对延迟敏感的简单音频传输。
G.711 (A-law / μ-law)	波形编码，固定 64 kbps，音质接近电话级；延迟极低。	固定为 64	固定电话、VoIP（如 SIP）、呼叫中心。
OPUS	低延迟、高音质，支持窄带到全频带，适应性强；开源免费。	6 – 510（常见语音 16–32，音乐 64–128）	实时语音（VoIP、会议）、音乐流、游戏语音、WebRTC。
Vorbis	开源有损压缩，音质好，压缩率比 MP3 优；逐渐被 Opus 取代。	64 – 320（常用 128–192）	开源流媒体（OGG 容器）、部分游戏和应用。
FLAC	无损压缩，保留原始音质，压缩率约 40–60%。	700 – 1100（CD 质量，取决于内容）	高保真音乐存储、音乐下载（Hi-Res 音乐）。
ALAC	苹果无损压缩，与 FLAC 类似，生态受限。	700 – 1100（与 FLAC 类似）	Apple Music 无损音频、iTunes、iOS/macOS 生态。
SBC	简单、低功耗，蓝牙 A2DP 默认编码，音质一般。	192 – 320（常用 256）	蓝牙耳机、蓝牙音箱。
LC3	继承 SBC，用于蓝牙 LE Audio；低功耗，音质比 SBC 好，延迟低。	16 – 160（常用 96–128）	蓝牙 LE Audio（TWS 耳机、助听器）、物联网音频。

SoC 兼容性:

下表为 ESP-Audio-Codec 在乐鑫各芯片上的支持情况。“✔” 表示支持，“✘” 表示不支持。

芯片	v2.0.0
ESP32	✔
ESP32-S2	✔
ESP32-C3	✔
ESP32-C6	✔
ESP32-S3	✔
ESP32-P4	✔
ESP32-C2	✔
ESP32-C5	✔
ESP32-H4	✔
ESP32-H2	✘

使用方法：

• 编码器使用示例

  • 详细用法请参考：audio_encoder_test.c

  • 若需要使用自定义编码器，请按照如下步骤进行：

    1. 实现自定义编码器接口，接口形式详见：结构体 esp_audio_enc_ops_t

    2. 在枚举 esp_audio_type_t 里自定义音频编码器类型，定义范围在 ESP_AUDIO_TYPE_CUSTOMIZED 到 ESP_AUDIO_TYPE_CUSTOMIZED_MAX 之间，详见：枚举 esp_audio_type_t

    3. 如果想要覆盖默认编码器，无需自定义音频编码器类型，可直接使用已有的编码器类型

    4. 注册自定义编码器，详见：esp_audio_enc_register()

• 解码器使用示例

  • 详细用法请参考：audio_decoder_test.c

  • 若需要使用自定义解码器，请按照如下步骤进行：

    1. 实现自定义解码器接口，接口形式详见：结构体 esp_audio_dec_ops_t

    2. 在枚举 esp_audio_type_t 里自定义音频解码器类型，定义范围在 ESP_AUDIO_TYPE_CUSTOMIZED 到 ESP_AUDIO_TYPE_CUSTOMIZED_MAX 之间，详见：枚举 esp_audio_type_t

    3. 如果想要覆盖默认解码器，无需自定义音频解码器类型，可直接使用已有的解码器类型

    4. 注册自定义解码器，详见：esp_audio_dec_register()

• 简易解码器使用示例

  • 详细用法请参考：simple_decoder_test.c

  • 若需要使用自定义简易解码器，请按照如下步骤进行：

    1. 实现自定义简易解码器接口，接口形式详见：结构体 esp_audio_simple_dec_reg_info_t

    2. 在枚举 esp_audio_simple_dec_type_t 里自定义音频简易解码器类型，定义范围在 ESP_AUDIO_SIMPLE_DEC_TYPE_CUSTOM 到 ESP_AUDIO_SIMPLE_DEC_TYPE_CUSTOM_MAX 之间，详见：枚举 esp_audio_simple_dec_type_t

    3. 如果想要覆盖默认解码器，无需自定义音频解码器类型，可直接使用已有的解码器类型

    4. 注册自定义简易解码器，详见：esp_audio_simple_dec_register()

相关链接：

• 组件注册表: esp_audio_codec component

ESP-Media-Protocols 组件

概述：

多媒体协议是多种通信协议的集合，广泛应用于流媒体传输、设备控制以及设备互联通信等场景。ESP-Media-Protocols 是乐鑫科技推出的多媒体协议库，提供对基础及主流多媒体协议的支持。

协议	层级	功能
RTP/RTCP	传输层	实时传输音视频流，提供质量信息
RTSP	应用层	作为服务器支持被拉流，作为客户端支持拉流和推流
SIP	应用层	会话终端，支持注册到 SIP 服务器，支持发起会话和接收会话
RTMP	应用层	作为服务器支持被拉流和接收推流，作为客户端支持拉流和推流
MRM	/	多设备主从同步播放音乐
UPnP	/	设备互联，媒体和服务共享

使用方法：

ESP-Media-Protocols 组件托管在 Github。可以通过在工程中输入以下命令将该组件添加到你的工程中。

idf.py add-dependency “jimforr/esp_media_protocols”

在使用 ESP-Media-Protocols 组件前，建议先参考和调试以下示例工程，以熟悉 API 的使用方法以及协议栈的具体应用。

• SIP audio

• SIP audio/video

• RTSP

• RTMP

• Multi-Room Music

• UPnP

性能：

各协议性能对比

协议	实时性	数据流	控制流	设备发现	TLS 加密	复杂度
RTSP	高	是	是	手动	否	中
SIP	高	是	是	手动	是	中
RTMP	中	是	基础	手动	是	中
MRM	高	是	是	自动	否	低
UPnP	低	是	是	自动	否	中

• 实时性

  • 低延迟：用于控制或命令传输的数据，延迟约 20 ms。

  • 低延迟：音视频或其他媒体流传输，延迟约为 300 ms。

  • 中延迟：基于 RTMP 的直播流，延迟约为 2 秒。

• 安全性

  • TLS（可选）

  • MD5 摘要鉴权（SIP 强制）

• 扩展性

  • 可定制协议头和协议体

  • 支持订阅和通知，可注册服务

• 并发性

  • 支持多客户端连接（RTMP）

• 兼容性

  • SIP 支持 linphone、Asterisk FreePBX、Freeswitch、Kamailio

  • RTSP 支持 ffmpeg、vlc、live555、mediamtx

  • RTMP 支持 ffmpeg、vlc

  • UPnP 支持网易云音乐

• 媒体支持

  • 请参考 README

• 内存消耗数据

  • 请参考 README

FAQ：

Q: ESP-Media-Protocols 支持的协议和功能全吗？

A: ESP-Media-Protocols 目前支持在嵌入式领域使用较广泛的基础协议和功能。还有一些未支持的协议如 SRTP、HLS 等，可以在其他组件或仓库下找到和使用。已支持的协议规范会不断迭代以及扩展功能，我们也会同步更新以及根据客户需求考虑扩展，后续对一些强功能的新协议也会计划实现支持。

Q: 有些协议功能重叠，在使用的时候如何选择？

A: 根据应用场景，具体分析功能要求、延迟要求和网络环境。如实时性要求较高，且需要支持实时控制（暂停、快进、快退、定位）的应用，通常使用 RTSP；如实时性要求较高，且需要支持实时互动的应用，则可以使用 SIP 创建会话；如在浏览器中播放的大规模直播，对稳定性和兼容性要求较高，对实时性没有高要求，则可以考虑使用 RTMP。

更多相关问题请参考以下协议目录中的 Issues 板块：

• SIP Issues

• RTSP Issues

• RTMP Issues

• MRM Issues

• UPnP Issues