majingjing123/esp_asrc

readme

# ESP-ASRC

- [中文](./README_CN.md)

The ASRC module is a high-performance audio format converter that supports sample rate, bit depth, and channel count conversion. It is designed for scenarios requiring unified audio formats across various applications. Featuring a hybrid hardware-software architecture, the module automatically leverages hardware resources on chips with ASRC peripherals to achieve low-latency, high-efficiency real-time conversion. In environments without hardware support, it falls back to an optimized software path to maintain performance. With a clean interface and flexible configuration, the module is easy to integrate into embedded audio frameworks, middleware, or high-level applications for seamless audio format adaptation.

# Features

- 🎚️ **Sample Rate Conversion**: Supports arbitrary integer multiple sample rates based on 4000 Hz or 11025 Hz, with maximum support up to 192000 Hz, covering all mainstream frequency configurations from narrowband voice to high-resolution audio.
- 🧮 **Bit Width Conversion**: Supports bit conversion between various data formats, including u8 (unsigned 8-bit), s16, s24, s32 (signed integers).
- 🔊 **Channel Conversion**: Supports expansion, mixing, and remapping between arbitrary channel numbers, with weight matrix configuration capability, suitable for scenarios such as mono to stereo conversion and multi-channel mixing.
- ⚙️ **Configurable Strategy**: Supports flexible processing strategy selection, including automatic scheduling, software priority (speed or memory), and forced use of hardware acceleration to adapt to different system resources and performance requirements.

# Performance

Test uses the following system configuration:
|      Chip      | IDF Version  | CPU Frequency | SPI Ram Frequency | Flash SPI mode|
|       --       |     --       |  --           |     --            |      --       |
|   ESP32-H4     |    master    | 32MHz         |   40MHz           |     DIO       |

ASRC module hardware and software conversion performance table for different input and output formats:
| Input Format    | Output Format   | Mode   | Memory Usage (KB) | CPU Usage (%) |
| ----------------| ----------------|--------| ------------------| ------------- |
| 16kHz/1ch/16bit | 48kHz/2ch/16bit | Use HW | 0.7              |    4.3        |
|                 |                 | Only SW| 0.6              |    21.8       |
| 48kHz/2ch/16bit | 16kHz/1ch/16bit | Use HW | 0.6              |    8.2        |
|                 |                 | Only SW| 0.5              |    20.5       |
| 44kHz/2ch/16bit | 48kHz/2ch/16bit | Use HW | 0.6              |    10.8       |
|                 |                 | Only SW| 6.1              |    79.2       |
| 32kHz/2ch/16bit | 48kHz/2ch/16bit | Use HW | 0.6              |    8.6        |
|                 |                 | Only SW| 0.6              |    78.2       |

**Performance Notes:**
- **Use HW Mode**: Utilizes hardware acceleration for sample rate conversion, resulting in lower CPU usage and relatively less memory consumption
- **Only SW Mode**: Pure software implementation with higher CPU usage but better compatibility
- **CPU Usage**: Average CPU time percentage based on 10 seconds of audio processing
- **Test Conditions**: Using 1kHz sine wave as test signal, processed with 512 sample block size

# ASRC Release and SOC Compatibility

The following table shows ESP_ASRC support for Espressif SoCs.

| Chip Model     |   v1.0.0    |   Notes     |
|----------------|-------------|-------------|
|ESP32           |      ✅    |Software only|
|ESP32-S2        |      ✅    |Software only|
|ESP32-S3        |      ✅    |Software only|
|ESP32-C2        |      ✅    |Software only|
|ESP32-C3        |      ✅    |Software only|
|ESP32-C5        |      ✅    |Software only|
|ESP32-C6        |      ✅    |Software only|
|ESP32-P4        |      ✅    |Software only|
|ESP32-H4        |      ✅    |Hardware & Software|

# Example Code

Please refer to the following usage example [ASRC_TEST](./test_app/main/asrc_test_h4.c)

# FAQ

1) Does the ASRC module have requirements for input/output memory?

   >Yes, the ASRC module has the following requirements for input/output memory:
   ><p align="center">
   - **In hardware acceleration mode**, if the output buffer is allocated in **PSRAM**, it must meet the memory size and address **cacheline alignment** requirements.
   - **In software mode**, alignment requirements are more relaxed, and memory allocated by ordinary `malloc` can be used, but performance may be slightly lower than the hardware path.
   - It is recommended to use the interface `esp_asrc_alloc_mem()` to ensure automatic allocation of compatible buffers for different modes.
   ></p>

2) Does ASRC support to dynamically change sample rate, bit depth, or channel during processing?

   >The current version does not support **runtime dynamic parameter modification**. If you need to change the input or output sample rate, bit depth, or channel count, it is recommended to follow this process:
   ><p align="center">
   1. Call `esp_asrc_close()` to close the existing ASRC instance;
   2. Update parameters;
   3. Call `esp_asrc_open()` to recreate a new ASRC instance.
   ></p>

3) How to choose ASRC mode?

   >ASRC supports multiple operating modes, which can be flexibly selected through configuration parameters:
   ><p align="center">
   |             Mode Name              |                Description                                                             |
   |-----------------------------------|----------------------------------------------------------------------------------------|
   | `ESP_ASRC_PERF_TYPE_AUTO`         | Automatically schedules hardware or software paths. Some conversions (like sample rate) can be completed by hardware, while others are handled by software, achieving software-hardware collaboration. |
   | `ESP_ASRC_PERF_TYPE_SW_SPEED`     | Pure software path, internal buffer allocated in IRAM, can speed up execution        |
   | `ESP_ASRC_PERF_TYPE_SW_MEMORY`    | Pure software path, internal buffer allocated in PSRAM, reduces internal RAM overhead but slows down execution |
   | `ESP_ASRC_PERF_TYPE_HW_ONLY`      | Forces use of hardware path only, initialization fails if hardware is not supported  |
   ></p>
   > ✅ It is recommended to use `ESP_ASRC_PERF_TYPE_AUTO` by default, which can achieve optimal compatibility and performance on different chips and platforms.