ESP32的ADF详解：6. Audio Processing的API

一、Downmix

1. 核心功能

将基础音频流和新加入音频流混合为单一输出流，支持动态增益控制和状态转换。输出声道数与基础音频一致，新加入音频自动转换声道匹配。

2. 关键特性

1. 声道处理

   • 输出声道数 = 基础音频声道数
   • 新加入音频自动转换声道（如立体声→单声道取平均，单声道→立体声复制）
   • 采样率必须一致，否则报错

2. 三态工作流程

   状态	行为	增益变化
   Bypass Downmixing	仅处理基础音频流	基础音频增益恒定
   Switch on Downmixing	1. 过渡期：两路增益渐变到目标值 2. 稳定期：共享相同目标增益	基础增益: 原值→目标值 新加入增益: 0→目标值
   Switch off Downmixing	1. 过渡期：增益回退到原始值 2. 稳定期：恢复独立增益后进入Bypass	基础增益: 目标值→原值 新加入增益: 目标值→0

3. 增益控制

   • 独立控制两路音频增益
   • 过渡期支持线性/非线性渐变
   • 稳定期两路共享相同增益值

3. 典型应用场景

1. 智能音箱：语音提示混入背景音乐
2. 车载系统：导航提示与娱乐音频混合
3. 直播系统：麦克风人声与背景音混合
4. 多语言播报：基础音轨+实时语言叠加

关键约束：输入音频必须采样率一致，否则API返回错误码 ESP_ERR_INVALID_ARG

4. API

1. 核心配置与初始化

2. 输入输出控制

3. 工作模式与状态控制

4. 音频流参数配置

5. 增益控制

6. 数据结构与宏定义

/**
 * @brief 下混配置结构体，用于配置下混处理的各种参数。
 */
struct downmix_cfg_t {
    esp_downmix_info_t downmix_info; ///< 下混信息
    int max_sample; ///< 每次下混处理的样本数
    int out_rb_size; ///< 环形缓冲区大小
    int task_stack; ///< 任务栈大小
    int task_core; ///< 任务运行的核心（0 或 1）
    int task_prio; ///< 任务优先级（基于 FreeRTOS 的优先级）
    bool stack_in_ext; ///< 是否尝试在外部内存中分配栈
};

7. 关键约束与注意事项

1. 采样率一致性：所有输入流必须相同，否则返回ESP_ERR_INVALID_ARG。
2. 声道支持：仅支持单声道(MONO)和双声道(DUAL)，其他声道数需预处理。
3. 增益范围：-100dB至100dB，超出范围可能导致 clipping。
4. 实时性：过渡时间(transit_time)影响状态切换平滑度，需根据应用场景调整。

8. 典型调用流程

// 1. 初始化配置
downmix_cfg_t cfg = DEFAULT_DOWNMIX_CONFIG();
cfg.downmix_info.work_mode = ESP_DM_BYPASS;
cfg.downmix_info.output_type = ESP_DM_DUAL_OUTPUT;

// 2. 创建句柄
audio_element_handle_t downmixer = downmix_init(&cfg);

// 3. 设置输入流参数
downmix_set_source_stream_info(downmixer, 44100, 2, 0); // 基础流
downmix_set_source_stream_info(downmixer, 44100, 1, 1); // 新加入流(自动转立体声)

// 4. 配置增益
float gains[2] = {0.0f, -6.0f}; // [基础增益, 目标增益]
downmix_set_gain_info(downmixer, gains, 0);

// 5. 启动混音
downmix_set_work_mode(downmixer, ESP_DM_ON);
downmix_set_transit_time_info(downmixer, 500, 0); // 500ms过渡

二、Equalizer

1. 功能概述

• Equalizer 是 ESP ADF 提供的一个强大的音频均衡器模块，支持 10 个频段和多种采样率，适用于音频增强、音效定制等场景。通过 equalizer_cfg 和 equalizer_set_gain_info() 函数，开发者可以灵活调整音频信号的频率响应，满足不同的音频处理需求。

• Equalizer 支持：

  • 固定频段数量：10 个频段。
  • 支持的采样率：11025 Hz、22050 Hz、44100 Hz 和 48000 Hz。
  • 默认增益：每个频段的默认增益为 -13 dB。

2. 频段中心频率

Equalizer 的 10 个频段的中心频率如下表所示：

3. 使用场景

Equalizer 适用于需要调整音频信号频率响应的场景，例如：

• 音频增强：提升低频或高频部分的音量。
• 音效定制：根据不同需求调整音频特性，如增强低音或高音。
• 噪声消除：通过调整特定频段的增益来减少噪声。

4. 示例代码

以下是一个简单的示例，展示如何使用 Equalizer：

#include "esp_adf.h"
// 初始化 Equalizer
equalizer_cfg_t eq_cfg = {
    .bands = {
        { .gain = -10 },  // 31 Hz 频段增益为 -10 dB
        { .gain = -5 },   // 62 Hz 频段增益为 -5 dB
        // 其他频段可以按需设置
    },
    .band_count = 10
};
// 创建 Equalizer 实例
equalizer_handle_t eq_handle = equalizer_create(&eq_cfg);
// 设置单个频段的增益
equalizer_set_gain_info(eq_handle, 3, -8);  // 设置 250 Hz 频段增益为 -8 dB
// 应用 Equalizer
audio_element_handle_t audio_src = ...;  // 音频源
audio_element_handle_t audio_dest = ...; // 音频目标
audio_element_link(audio_src, eq_handle);
audio_element_link(eq_handle, audio_dest);

5. API

1. 核心配置与初始化

2. 参数设置

3. 数据结构与宏定义

4. 关键特性详解

频段分布（不同采样率下）

增益控制规则

• 单声道（MONO）

  • 10个可调频段（索引0~9）
  • 示例：equalizer_set_gain_info(self, 3, 5, true) → 设置第4个频段(250Hz)增益为5dB

• 双声道（DUAL）

  • 独立控制（is_channels_gain_equal=false）：20个频段（左声道0_{9，右声道10}19）

    // 设置左声道第2频段(62Hz)增益为3dB
    equalizer_set_gain_info(self, 1, 3, false);
    // 设置右声道第5频段(1kHz)增益为-2dB
    equalizer_set_gain_info(self, 14, -2, false);
    

  • 同步控制（is_channels_gain_equal=true）：10个频段（左右声道联动）

    // 同时设置左右声道的第7频段(4kHz)增益为6dB
    equalizer_set_gain_info(self, 6, 6, true);
    

5. 典型调用流程

// 1. 初始化配置
equalizer_cfg_t cfg = DEFAULT_EQUALIZER_CONFIG();
cfg.samplerate = 44100;
cfg.channel = 2;  // 立体声
int gains[20] = {0};  // 默认所有频段增益为0dB
cfg.set_gain = gains;

// 2. 创建均衡器实例
audio_element_handle_t eq = equalizer_init(&cfg);

// 3. 设置个性化增益
// 提升低频（左声道125Hz +5dB）
equalizer_set_gain_info(eq, 2, 5, false); 
// 衰减高频（右声道8kHz -3dB）
equalizer_set_gain_info(eq, 17, -3, false);
// 同步调整中频（左右声道1kHz +2dB）
equalizer_set_gain_info(eq, 5, 2, true);

6. 约束与注意事项

1. 采样率限制：仅支持11025/22050/44100/48000Hz，其他值返回ESP_ERR_INVALID_ARG。
2. 频段索引范围：
   • 单声道：0~9
   • 双声道独立控制：0_19（左09，右10~19）
3. 增益范围：未明确限制，但建议在[-12dB, +12dB]内避免失真。
4. 实时性：修改增益会立即生效，可能导致音频瞬态变化，建议在静音时调整。

三、Resample Filter

• 重采样滤波器是一种音频元素，旨在对输入的数据流进行降采样或升采样，同时还可以在立体声和单声道之间转换数据。

1. API

1. 核心配置与初始化

2. 参数动态设置

3. 工作模式与特性

重采样模式（esp_resample_mode_t）

重采样类型（esp_resample_type_t）

复杂度控制（complexity）

4. 声道处理规则

5. 数据结构与宏定义

/**
 * @brief 重采样滤波器配置结构体。
 *        此结构体用于配置重采样滤波器的参数。
 */
struct rsp_filter_cfg_t {
    int src_rate;                     /**< 源 PCM 文件的采样率（单位：Hz） */
    int src_ch;                       /**< 源 PCM 文道的通道数（单声道=1，立体声=2） */
    int dest_rate;                    /**< 目标 PCM 文件的采样率（单位：Hz） */
    int dest_bits;                    /**< 目标 PCM 数据样本的位宽。当前支持：16 位。 */
    int dest_ch;                      /**< 目标 PCM 文件的通道数（单声道=1，立体声=2） */
    int src_bits;                     /**< 源 PCM 数据样本的位宽。支持的位宽：8 位、16 位、24 位、32 位。 */
    esp_resample_mode_t mode;        /**< 重采样模式（编码或解码）。解码模式具有恒定的输入 PCM 长度；编码模式具有恒定的输出 PCM 长度。 */
    int max_indata_bytes;             /**< 输入 PCM 的最大缓冲区大小（单位：字节） */
    int out_len_bytes;                /**< 输出流数据的缓冲区长度。此参数必须在编码模式下配置。 */
    esp_resample_type_t type;        /**< 重采样类型（自动、升采样、降采样） */
    int complexity;                   /**< 指示重采样的复杂度。在使用 FIR 滤波器时有效。范围：[1, 5]；1 表示最低复杂度（最低精度，最快速度）；5 表示最高复杂度（最高精度，最慢速度）。小于 1 的值会被设置为 1，大于 5 的值会被设置为 5。 */
    int down_ch_idx;                  /**< 指示所选的通道（右或左）。仅当复杂度设置为 0 且输入文件的通道从立体声变为单声道时有效。 */
    esp_rsp_prefer_type_t prefer_flag;/**< 选择标志，用于选择较低的 CPU 使用率或较低的 INRAM 使用率。请参阅 esp_resample.h 获取详情。 */
    int out_rb_size;                  /**< 输出环形缓冲区大小 */
    int task_stack;                   /**< 任务栈大小 */
    int task_core;                    /**< 任务运行的核心 */
    int task_prio;                    /**< 任务优先级 */
    bool stack_in_ext;                /**< 尝试在外部内存中分配栈的标志 */
};

6. 典型调用流程

// 1. 初始化配置（48kHz立体声→16kHz单声道）
rsp_filter_cfg_t cfg = DEFAULT_RESAMPLE_FILTER_CONFIG();
cfg.src_rate = 48000;
cfg.src_ch = 2;
cfg.dest_rate = 16000;
cfg.dest_ch = 1;
cfg.mode = RESAMPLE_ENCODE_MODE;
cfg.complexity = 3;  // 平衡模式

// 2. 创建重采样实例
audio_element_handle_t resampler = rsp_filter_init(&cfg);

// 3. 动态修改输入参数（切换为24bit输入）
rsp_filter_change_src_info(resampler, 44100, 1, 24);  // 44.1kHz单声道24bit

7. 约束与注意事项

1. 位宽支持：
   • 输入：8/16/24/32bit
   • 输出：仅16bit
2. 采样率限制：输入/输出采样率需在ESP-ADF支持的范围内（通常8kHz-48kHz）
3. 实时性要求：高复杂度(complexity=5)可能增加处理延迟，需测试实际性能
4. 内存占用：选择ESP_RSP_PREFER_MEM可减少INRAM使用，但会增加CPU负载

8. 应用场景示例

四、Sonic

1. Sonic组件核心功能

1. 三维音频处理

   • 变速不变调：调整播放速度（speed）
   • 变调不变速：调整音高（pitch）
   • 插值算法：平衡处理速度与音质

2. 参数调节范围

   参数	类型	示例值	说明
   speed	float	0.5(半速)~2.0(倍速)	1.0为原始速度
   pitch	float	0.5(低八度)~2.0(高八度)	1.0为原始音高
   interpolation	enum	LINEAR/FIR	线性插值(快) vs FIR插值(准)

3. 典型应用场景

   • 音频书籍变速播放
   • 音乐音高修正
   • 实时语音速度调整

4. 特性对比

   插值类型	处理速度	音质精度	适用场景
   线性(Linear)	⚡️ 快	中等	实时处理/低功耗设备
   FIR	⏳ 慢	高	后期制作/高保真需求

2. 调用示例

// 初始化
sonic_cfg_t cfg = DEFAULT_SONIC_CONFIG();
audio_element_handle_t sonic_processor = sonic_init(&cfg);

// 设置为2倍速播放(保持原音高)
sonic_set_pitch_and_speed_info(sonic_processor, 1.0, 2.0);

// 启用高精度FIR插值
sonic_set_interpolation_type(sonic_processor, SONIC_INTERPOLATION_FIR);

3. 注意事项

1. 速度/音高参数建议范围：0.5~2.0，极端值可能导致失真
2. FIR插值会增加20-30%的CPU负载
3. 处理立体声音频时两个声道会同步调整

4. API

1. 核心配置与初始化

2. 参数动态设置

3. 处理模式控制

4. 结构体

/**
 * @brief 结构体用于存储音频文件的信息和Sonic处理所需的配置参数。
 */
struct sonic_info_t {
    int samplerate; /**< 音频文件的采样率（单位：Hz） */
    int channel; /**< 音频文件的通道数（单声道=1，立体声=2） */
    int resample_linear_interpolate; /**< 是否使用简单的线性插值。1表示使用，0表示不使用 */
    float pitch; /**< 音频文件的音高缩放因子。例如，0.3表示降低音高，1.3表示提高30%的音高 */
    float speed; /**< 音频文件的速度缩放因子。例如，0.3表示降低70%的速度，1.3表示提高30%的速度 */
};

/**
 * @brief Sonic配置结构体，用于配置Sonic处理音频的参数。
 */
struct sonic_cfg_t {
    struct sonic_info_t sonic_info; /**< Sonic处理所需的音频信息 */
    int out_rb_size; /**< 输出环形缓冲区的大小 */
    int task_stack; /**< 任务栈大小 */
    int task_core; /**< 任务运行的核心 */
    int task_prio; /**< 任务优先级 */
    bool stack_in_ext; /**< 是否尝试在外部内存中分配栈 */
};

5. 典型调用流程

// 1. 初始化配置（44.1kHz立体声）
sonic_cfg_t cfg = DEFAULT_SONIC_CONFIG();
cfg.sonic_info.samplerate = 44100;
cfg.sonic_info.channel = 2;
cfg.sonic_info.resample_linear_interpolate = 0; // 启用FIR插值

// 2. 创建处理器实例
audio_element_handle_t sonic = sonic_init(&cfg);

// 3. 设置为1.5倍速播放并升调20%
sonic_set_pitch_and_speed_info(sonic, 1.2f, 1.5f);

// 4. 动态修改采样率（切换至16kHz单声道）
sonic_set_info(sonic, 16000, 1);

6. 实践

1. 参数安全范围：

   • 音高(pitch)：建议0.5~2.0（超出可能失真）
   • 速度(speed)：建议0.5~4.0（极端值影响流畅性）

2. 资源消耗：

   配置组合	CPU占用	适用场景
   线性插值 + 中等变速	低	实时语音处理
   FIR插值 + 高精度变调	高	音乐后期制作

3. 内存管理：

   • 启用stack_in_ext可减少内部RAM占用
   • 输出缓冲区(out_rb_size)建议≥4KB处理高码率音频

7. 应用场景示例