majingjing123/esp_asrc

readme (zh)

# ESP-ASRC

- [English](./README.md)

ASRC 模块是一个高性能音频格式转换单元，支持采样率、位深和通道数转换，适用于需要音频格式统一的多种应用场景。该模块采用软硬件协同架构：在具备 ASRC 外设的芯片上，模块可根据配置自动调度硬件资源，实现低延迟、高效率的实时转换；在无硬件支持时，则使用优化的软件路径保障性能。模块接口设计清晰，配置灵活，易于集成，适合用于嵌入式音频框架、音频中间件、或高层应用程序中的音频格式适配场景。

# 特点

- 🎚️ **采样率转换**：支持任意以 4000 Hz 或 11025 Hz 为基准的整数倍采样率，最高支持至 192000 Hz，覆盖从窄带语音到高分辨率音频的全部主流频率配置。
- 🧮 **位宽转换**：支持多种数据格式之间的比特位转换，包括 u8（无符号 8 位）、s16、s24、s32（有符号整数）。
- 🔊 **通道数转换**：支持任意通道数之间的扩展、混合与重映射，具备权重矩阵配置能力，适用于如单声道转立体声、多声道混音等场景。
- ⚙️ **可配置策略**：支持灵活的处理策略选择，包括自动调度、软件优先（速度或内存）、以及强制使用硬件加速，以适应不同系统资源与性能需求

# 性能

测试使用如下系统配置：
|      Chip      | IDF Version  | CPU Frequency | SPI Ram Frequency | Flash SPI mode|
|       --       |     --       |  --           |     --            |      --       |
|   ESP32-H4     |    master    | 32MHz         |   40MHz           |     DIO       |

不同输入输出格式下 ASRC 模块软硬件转换性能表：
| 输入格式         | 输出格式        | 模式   | 内存消耗 (KB)  | CPU 占用率 (%) |
| ----------------| ----------------|-------| --------------| -------------- |
| 16kHz/1ch/16bit | 48kHz/2ch/16bit | HW    | 0.7           |    4.3         |
|                 |                 | SW    | 0.6           |    21.8        |
| 48kHz/2ch/16bit | 16kHz/1ch/16bit | HW    | 0.6           |    8.2         |
|                 |                 | SW    | 0.5           |    20.5        |
| 44kHz/2ch/16bit | 48kHz/2ch/16bit | HW    | 0.6           |    10.8        |
|                 |                 | SW    | 6.1           |    79.2        |
| 32kHz/2ch/16bit | 48kHz/2ch/16bit | HW    | 0.6           |    8.6         |
|                 |                 | SW    | 0.6           |    78.2        |

**性能说明:** 
- **HW 模式**: 利用硬件加速进行采样率转换，CPU占用率较低，内存消耗相对较少
- **SW 模式**: 纯软件实现，CPU占用率较高，但兼容性更好
- **CPU占用率**: 基于10秒音频处理的平均CPU时间占比
- **测试条件**: 使用1kHz正弦波作为测试信号，512样本块大小进行处理

# ASRC 发布和SOC兼容性

下表显示了 ESP_ASRC 对 Espressif SoC 的支持。

| 芯片型号        |   v1.0.0    |   备注  |
|----------------|-------------|---------|
|ESP32           |      ✅    |只支持软件|
|ESP32-S2        |      ✅    |只支持软件|
|ESP32-S3        |      ✅    |只支持软件|
|ESP32-C2        |      ✅    |只支持软件|
|ESP32-C3        |      ✅    |只支持软件|
|ESP32-C5        |      ✅    |只支持软件|
|ESP32-C6        |      ✅    |只支持软件|
|ESP32-P4        |      ✅    |只支持软件|
|ESP32-H4        |      ✅    |支持软硬件|

# 示例代码

请参考以下使用示例[ASRC_TEST](./test_app/main/asrc_test_h4.c)

# FAQ

1) ASRC 模块的输入输出内存是否有要求？

   >是的，ASRC 模块对输入输出内存有如下要求：
   ><p align="center"> 
   - **硬件加速模式下**，输出缓冲区如果分配在**PSRAM**，则必须满足内存大小和地址为 **cacheline 对齐** 要求。
   - **软件模式下**，对齐要求较为宽松，普通 `malloc` 分配的内存即可，但性能可能略低于硬件路径。
   - 建议使用接口 `esp_asrc_alloc_mem()` 可确保自动为不同模式分配兼容的缓冲区。
   ></p>

2) ASRC 模块能否动态修改采样率，比特位或声道数？

   >当前版本暂不支持 **运行时动态修改参数**。若需更改输入或输出的采样率、位深或声道数，建议按照如下流程处理：
   ><p align="center">
   1. 调用 `esp_asrc_close()` 关闭现有 ASRC 实例；
   2. 更新参数；
   3. 调用 `esp_asrc_open()` 重新创建新的 ASRC 实例。
   ></p>

3) ASRC的模式如何选择？

   >ASRC 支持多种运行模式，可通过配置参数灵活选择：
   ><p align="center">
   |             模式名              |                描述                                                                |
   |--------------------------------|------------------------------------------------------------------------------------|
   | `ESP_ASRC_PERF_TYPE_AUTO`      | 自动调度硬件或软件路径。部分转换（如采样率）可由硬件完成，其余由软件处理，实现软硬件协同。 |
   | `ESP_ASRC_PERF_TYPE_SW_SPEED`  | 纯软件路径，内部buffer申请在inram，可以加快运行速度                                    |
   | `ESP_ASRC_PERF_TYPE_SW_MEMORY` | 纯软件路径，内部buffer申请在psram，减少内部ram的开销，但是运行速度会减慢                 |
   | `ESP_ASRC_PERF_TYPE_HW_ONLY`   | 强制仅使用硬件路径，若硬件不支持则初始化失败。                                          |
   ></p>
   > ✅ 建议默认使用 `ESP_ASRC_PERF_TYPE_AUTO`，可在不同芯片和平台上获得最佳兼容性与性能。