多媒体技术 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、RGB565（大端）、RGB565（小端）、RGBA、YCbYCr、CbYCrY、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 数据流首先进行缩放，然后进行裁剪，最后进行旋转和输出。

使用缩放和裁剪功能时，需要配置 jpeg_resolution_t 结构体中的对应参数。组件支持仅对宽度或高度进行单独处理，例如，仅裁剪宽度而保持高度不变时，可以设置 clipper.height = 0，此时图像的高度将保持为原始 JPEG 图像的高度。处理流程可通过下述详细或简化配置完成。

// Detailed configuration
jpeg_dec_config_t config = DEFAULT_JPEG_DEC_CONFIG();
config.output_type = JPEG_PIXEL_FORMAT_RGB565_LE;
config.scale.width = 320;
config.scale.height = 120;
config.clipper.width = 192;
config.clipper.height = 120;
config.rotate = JPEG_ROTATE_90D;

// Simplified configuration
jpeg_dec_config_t config = DEFAULT_JPEG_DEC_CONFIG();
config.output_type = JPEG_PIXEL_FORMAT_RGB565_LE;
config.scale.width = 0;  // keep width unchanged by setting to 0
config.scale.height = 120;
config.clipper.width = 192;
config.clipper.height = 0;  // keep height unchanged by setting to 0
config.rotate = JPEG_ROTATE_90D;

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

分块解码的典型使用方法如下：

jpeg_dec_config_t config = DEFAULT_JPEG_DEC_CONFIG();
config.block_enable = true;

jpeg_dec_open();
jpeg_dec_parse_header();

int output_len = 0;
int process_count = 0;
jpeg_dec_get_outbuf_len(hd, &output_len);
jpeg_dec_get_process_count(hd, &process_count);

for (int block_cnt = 0; block_cnt < process_count; block_cnt++) {
  jpeg_dec_process();
}

jpeg_dec_close();

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

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

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

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

性能

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

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

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

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

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

使用方法

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

idf.py add-dependency “espressif/esp_new_jpeg”

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

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 等数据。

Q: 为什么 ESP_NEW_JPEG 在 ESP32-P4 上解码速度较慢？

A：ESP_NEW_JPEG 尚未针对 ESP32-P4 进行优化。但 ESP32-P4 配备了硬件 JPEG 编解码模块，硬件解码性能优于软件解码。建议在 ESP32-P4 上使用硬件 JPEG 模块以获得更优的解码性能。可以参考 JPEG 图像编解码器 - ESP32-P4 获取更多信息。

Q: ESP_NEW_JPEG 是否会与硬件编解码器整合到一个组件，类似 H264 的组件？

A：暂无计划。

Q: 如何估算解码速度？

A：特定分辨率图像的解码速度可以通过已测试的基准数据进行估算。如待测的图像分辨率为 480x512, 已知 640x480 的解码速度为 13.24 fps, 则可以估算出 480x512 的解码速度约为 13.24 * (480/640) * (512/480) = 10.59 fps。

已测试数据请参考 Performance。

Q: ESP_NEW_JPEG 的内存消耗如何？

A：目前仅统计了 decoder 的内存消耗情况。

• 当不开启 scale 时，内存消耗恒定，约 10 KB。open() 时分配大部分固定内存，close() 时释放全部内存。

• 当开启 scale 时，内存消耗随图像宽度增加而增加。

Q: 如何理解 ESP_NEW_JPEG 里的流式处理的概念？

A：ESP_NEW_JPEG 解码接口基础使用方式：open() > parse_header() > process() > close()

如果每张图像参数都一样，每次都 open 和 close 会浪费资源，因此设计了流式处理的示例：open 一次，循环 parse_header > process，结束后 close。

相关链接：

• 组件注册表: 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] 像素

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

  • 支持 RGB888、BGR565_BE、VUY、UYVY、YUV420(O_UYY_E_VYY) 原始数据格式

  • 支持动态调整码率、帧率、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。

数据布局

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 组件的介绍及性能说明可参考 ESP-Audio-Codec。

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 耳机、助听器）、物联网音频。

使用方法

编码器使用示例

• 详细用法请参考：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 组件

概述

多媒体协议是多种通信协议的集合，广泛应用于流媒体传输、设备控制以及设备互联通信等场景，典型应用方式如下：

• 安防系统大多数网络摄像头都内置 RTSP 服务器，将采集的视频压缩后使用 RTP 协议对外提供视频流，允许监控平台、NVR、VLC 播放器等进行访问拉流；

• GB28181（全称：GB/T 28181-2016），中国公安部发布的国家标准，定义了公共安全视频监控联网系统的信息传输、交换和控制技术要求，基于 SIP 协议完成设备注册、心跳、呼叫等信令控制，使用 SDP 描述媒体会话信息，使用 RTP 和 RTCP 实时传输和控制媒体数据；

• VoIP、视频会议、可视对讲系统，基于 SIP 协议完成呼叫和语音、视频通信功能；

• 广播系统、直播平台，设备采集媒体流后基于 RTMP 协议向服务器推流，多客户端设备基于 RTMP 协议从服务器拉流并播放。

ESP-Media-Protocols 是乐鑫科技推出的多媒体协议库，提供对基础及主流多媒体协议的支持。

协议	层级	功能	常见应用场景
RTP/RTCP	传输层	实时传输音视频流，提供质量信息	网络摄像头、实时通话/会议的媒体数据的低延时传输，RTCP 提供传输质量统计
RTSP	应用层	作为服务器支持被拉流，作为客户端支持拉流和推流	网络摄像头的媒体数据的低延时单向传输、播放控制
SIP	应用层	会话终端，支持注册到 SIP 服务器，支持发起会话和接收会话	对讲机、电话终端之间媒体数据的低延时双向传输，通过会话管理实现对讲、会议
RTMP	应用层	作为服务器支持被拉流和接收推流，作为客户端支持拉流和推流	直播推流与后端分发（设备向直播服务器/平台推流），直播接入
MRM	/	多设备主从同步播放音乐	多房间音频同步播放（智能音箱、家庭影院多设备同步）
UPnP	/	设备互联，媒体和服务共享	家庭内设备发现与媒体共享（手机/PC 发现电视/NAS 并投屏或播放）

性能数据

各协议性能对比

协议	实时性	数据流	控制流	设备发现	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

可通过以下图流轻松初步辨别要使用的协议：

使用方法

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

idf.py add-dependency "espressif/esp_media_protocols^0.5.1"

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

• SIP audio

• SIP audio/video

• RTSP

• RTMP

• Multi-Room Music

• UPnP

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

ESP-MIDI 组件

概述

ESP-MIDI 是乐鑫科技推出的 MIDI（乐器数字接口）软件库，提供高效的 MIDI 文件解析与实时音频合成功能。ESP-MIDI 支持 SoundFont 音色库和自定义音频库，可输出高保真、无失真的音频效果。结合 MIDI 文件体积小和音色库资源丰富的特点，ESP-MIDI 实现了卓越音质与高效性能的平衡，为开发者提供完善的 MIDI 处理方案。

相关资料如下：

• 组件注册表: esp-midi component

• 示例项目: ESP-MIDI 示例项目

FAQ

Q: 如何加载 SoundFont 文件？

A: ESP-MIDI 支持完整的 SoundFont 2（SF2）文件解析和播放。您可以通过音色库加载接口加载 SF2 文件，也可以使用用户自定义的声音库。

Q: ESP-MIDI 支持实时 MIDI 输入吗？

A: 是的，ESP-MIDI 支持实时 MIDI 事件编码和解码，包括音符开关、音色切换、控制变化、弯音、通道压力等多种 MIDI 事件类型。

Q: 如何控制播放速度？

A: ESP-MIDI 支持 BPM（每分钟节拍数）设置和速度变化，支持动态调整。您可以通过 API 设置和修改播放速度。

Q: 音频输出如何集成？

A: ESP-MIDI 提供基于回调的音频输出接口，可以与不同的音频后端灵活集成，如 ESP-ADF、ESP-Audio-Codec 等。