一、Downmix
1. 核心功能
將基礎音頻流和新加入音頻流混合為單一輸出流,支持動態增益控制和狀態轉換。輸出聲道數與基礎音頻一致,新加入音頻自動轉換聲道匹配。
2. 關鍵特性
-
聲道處理
- 輸出聲道數 = 基礎音頻聲道數
- 新加入音頻自動轉換聲道(如立體聲→單聲道取平均,單聲道→立體聲復制)
- 采樣率必須一致,否則報錯
-
三態工作流程
狀態 行為 增益變化 Bypass Downmixing 僅處理基礎音頻流 基礎音頻增益恒定 Switch on Downmixing 1. 過渡期:兩路增益漸變到目標值
2. 穩定期:共享相同目標增益基礎增益: 原值→目標值
新加入增益: 0→目標值
Switch off Downmixing 1. 過渡期:增益回退到原始值
2. 穩定期:恢復獨立增益后進入Bypass基礎增益: 目標值→原值
新加入增益: 目標值→0
-
增益控制
- 獨立控制兩路音頻增益
- 過渡期支持線性/非線性漸變
- 穩定期兩路共享相同增益值
3. 典型應用場景
- 智能音箱:語音提示混入背景音樂
- 車載系統:導航提示與娛樂音頻混合
- 直播系統:麥克風人聲與背景音混合
- 多語言播報:基礎音軌+實時語言疊加
關鍵約束:輸入音頻必須采樣率一致,否則API返回錯誤碼
ESP_ERR_INVALID_ARG
4. API
1. 核心配置與初始化
API/結構體 | 功能描述 | 關鍵參數/成員 |
---|---|---|
downmix_init(downmix_cfg_t *) | 初始化Downmix音頻元素 | downmix_info (工作模式/輸出類型)、max_sample (每幀采樣數)、out_rb_size 等 |
downmix_cfg_t | 配置結構體 | - esp_downmix_info_t downmix_info - 任務棧大小/核心/優先級 - 緩沖區大小 |
DEFAULT_DOWNMIX_CONFIG() | 生成默認配置宏 | 預定義任務棧(4KB)、優先級(5)、核心(1)、緩沖區大小(2KB) |
2. 輸入輸出控制
API | 功能描述 | 關鍵參數 |
---|---|---|
downmix_set_input_rb() | 設置輸入環形緩沖區 | rb (緩沖區句柄)、index (輸入流索引,0/1) |
downmix_set_input_rb_timeout() | 設置輸入緩沖區超時時間 | ticks_to_wait (RTOS tick數) |
downmix_set_output_type() | 設置輸出聲道類型 | output_type (僅支持MONO 或DUAL ) |
downmix_set_out_ctx_info() | 傳遞輸出流的上下文信息 | out_ctx (如各聲道獨立控制標志) |
3. 工作模式與狀態控制
API | 功能描述 | 關鍵參數 |
---|---|---|
downmix_set_work_mode() | 設置工作模式 | mode :- BYPASS (直通)- ON (開啟混音)- OFF (關閉混音) |
downmix_set_transit_time_info() | 設置狀態切換的過渡時間 | transit_time (毫秒)、index (輸入流索引) |
4. 音頻流參數配置
API | 功能描述 | 關鍵參數 |
---|---|---|
downmix_set_source_stream_info() | 設置輸入流的采樣率和聲道數 | rate (必須一致)、ch (僅支持1/2聲道)、index (輸入流索引) |
source_info_init() | 批量初始化多路輸入流信息 | source_info (結構體數組,含采樣率/聲道數/增益等) |
5. 增益控制
API | 功能描述 | 關鍵參數 |
---|---|---|
downmix_set_gain_info() | 設置輸入流的增益值 | gain (數組[原增益, 目標增益],范圍[-100dB,100dB]) |
6. 數據結構與宏定義
類型/宏定義 | 說明 |
---|---|
esp_downmix_info_t | 工作模式(work_mode ) + 輸出類型(output_type ) |
esp_downmix_input_info_t | 輸入流信息(采樣率/聲道數/增益/過渡時間) |
DOWNMIX_TASK_STACK | 默認任務棧大小(4KB) |
DM_BUF_SIZE | 內部緩沖區大小(默認1024樣本) |
/*** @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. 關鍵約束與注意事項
- 采樣率一致性:所有輸入流必須相同,否則返回
ESP_ERR_INVALID_ARG
。 - 聲道支持:僅支持單聲道(
MONO
)和雙聲道(DUAL
),其他聲道數需預處理。 - 增益范圍:
-100dB
至100dB
,超出范圍可能導致 clipping。 - 實時性:過渡時間(
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 個頻段的中心頻率如下表所示:
頻段索引 | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 |
---|---|---|---|---|---|---|---|---|---|---|
頻率 | 31 Hz | 62 Hz | 125 Hz | 250 Hz | 500 Hz | 1 kHz | 2 kHz | 4 kHz | 8 kHz | 16 kHz |
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. 核心配置與初始化
API/結構體 | 功能描述 | 關鍵參數/成員 |
---|---|---|
equalizer_init(equalizer_cfg_t *) | 初始化均衡器音頻元素 | samplerate (支持11025/22050/44100/48000Hz)、channel (單/雙聲道)、set_gain (增益數組) |
equalizer_cfg_t | 配置結構體 | - task_stack (默認4KB)- out_rb_size (輸出緩沖區大小)- stack_in_ext (外部內存分配) |
DEFAULT_EQUALIZER_CONFIG() | 生成默認配置宏 | 預定義任務棧、優先級(5)、核心(1)、緩沖區大小(2KB) |
2. 參數設置
API | 功能描述 | 關鍵參數 |
---|---|---|
equalizer_set_info() | 設置采樣率和聲道數 | rate (必須為特定值)、ch (1或2) |
equalizer_set_gain_info() | 設置指定頻段的增益 | index (頻段索引)、value_gain (增益值)、is_channels_gain_equal (雙聲道同步) |
3. 數據結構與宏定義
類型/宏定義 | 說明 |
---|---|
EQUALIZER_TASK_STACK | 默認任務棧大小(4KB) |
EQUALIZER_RINGBUFFER_SIZE | 環形緩沖區大小(默認2KB) |
equalizer_cfg_t | 包含采樣率、聲道數、增益數組等配置參數 |
4. 關鍵特性詳解
頻段分布(不同采樣率下)
采樣率 | 支持的10個頻段中心頻率(Hz) |
---|---|
11025Hz | 31, 62, 125, 250, 500, 1000, 2000, 3000, 4000, 5500 |
22050Hz | 31, 62, 125, 250, 500, 1000, 2000, 4000, 8000, 11000 |
44100Hz | 31, 62, 125, 250, 500, 1000, 2000, 4000, 8000, 16000 |
48000Hz | 同44100Hz |
增益控制規則
-
單聲道(MONO)
- 10個可調頻段(索引0~9)
- 示例:
equalizer_set_gain_info(self, 3, 5, true)
→ 設置第4個頻段(250Hz)增益為5dB
-
雙聲道(DUAL)
- 獨立控制(
is_channels_gain_equal=false
):20個頻段(左聲道09,右聲道1019)// 設置左聲道第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. 約束與注意事項
- 采樣率限制:僅支持11025/22050/44100/48000Hz,其他值返回
ESP_ERR_INVALID_ARG
。 - 頻段索引范圍:
- 單聲道:0~9
- 雙聲道獨立控制:019(左09,右10~19)
- 增益范圍:未明確限制,但建議在[-12dB, +12dB]內避免失真。
- 實時性:修改增益會立即生效,可能導致音頻瞬態變化,建議在靜音時調整。
三、Resample Filter
- 重采樣濾波器是一種音頻元素,旨在對輸入的數據流進行降采樣或升采樣,同時還可以在立體聲和單聲道之間轉換數據。
1. API
1. 核心配置與初始化
API/結構體 | 功能描述 | 關鍵參數/成員 |
---|---|---|
rsp_filter_init(rsp_filter_cfg_t *) | 初始化重采樣音頻元素 | src_rate /dest_rate (Hz)、src_ch /dest_ch (1/2)、mode (編碼/解碼模式) |
rsp_filter_cfg_t | 配置結構體 | - type (自動/上采樣/下采樣)- complexity (1-5級精度)- prefer_flag (CPU/RAM優化傾向) |
DEFAULT_RESAMPLE_FILTER_CONFIG() | 生成默認配置宏 | 預定義任務棧(4KB)、優先級(5)、核心(1)、緩沖區大小(2KB) |
2. 參數動態設置
API | 功能描述 | 關鍵參數 |
---|---|---|
rsp_filter_set_src_info() | 設置輸入流的采樣率和聲道數 | src_rate (Hz)、src_ch (1/2) |
rsp_filter_change_src_info() | 動態修改輸入流參數(含位寬) | src_bit (支持8/16/24/32bit) |
3. 工作模式與特性
重采樣模式(esp_resample_mode_t
)
模式 | 行為特性 |
---|---|
RESAMPLE_DECODE_MODE | 自動從audio_element_getinfo 獲取輸入參數,輸出長度可變 |
RESAMPLE_ENCODE_MODE | 需手動配置輸入/輸出參數,輸出長度固定(需設置out_len_bytes ) |
重采樣類型(esp_resample_type_t
)
類型 | 說明 |
---|---|
RESAMPLE_AUTO | 自動判斷上/下采樣 |
RESAMPLE_UP | 強制上采樣(如44.1kHz→48kHz) |
RESAMPLE_DOWN | 強制下采樣(如48kHz→16kHz) |
復雜度控制(complexity
)
等級 | 性能表現 | 適用場景 |
---|---|---|
1 | 最快速度,最低精度 | 低功耗實時處理 |
3 | 平衡速度與精度 | 通用場景(默認) |
5 | 最慢速度,最高精度 | 高保真音頻處理 |
4. 聲道處理規則
轉換場景 | 處理方式 |
---|---|
單聲道→立體聲 | 復制單聲道數據到雙聲道(可設置down_ch_idx 指定源聲道) |
立體聲→單聲道 | 默認混合左右聲道,或通過down_ch_idx 選擇左/右聲道(0:左, 1:右) |
5. 數據結構與宏定義
類型/宏定義 | 說明 |
---|---|
RSP_FILTER_TASK_STACK | 默認任務棧大小(4KB) |
RSP_FILTER_RINGBUFFER_SIZE | 環形緩沖區大小(默認2KB) |
esp_rsp_prefer_type_t | 資源偏好: - ESP_RSP_PREFER_CPU - ESP_RSP_PREFER_MEM |
/*** @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. 約束與注意事項
- 位寬支持:
- 輸入:8/16/24/32bit
- 輸出:僅16bit
- 采樣率限制:輸入/輸出采樣率需在ESP-ADF支持的范圍內(通常8kHz-48kHz)
- 實時性要求:高復雜度(
complexity=5
)可能增加處理延遲,需測試實際性能 - 內存占用:選擇
ESP_RSP_PREFER_MEM
可減少INRAM使用,但會增加CPU負載
8. 應用場景示例
場景 | 推薦配置 |
---|---|
語音通話降采樣 | dest_rate=8kHz 、complexity=1 、prefer_flag=ESP_RSP_PREFER_CPU |
高保真音樂格式轉換 | complexity=5 、prefer_flag=ESP_RSP_PREFER_MEM |
實時音頻流處理 | mode=RESAMPLE_DECODE_MODE 、type=RESAMPLE_AUTO |
四、Sonic
1. Sonic組件核心功能
-
三維音頻處理
- 變速不變調:調整播放速度(
speed
) - 變調不變速:調整音高(
pitch
) - 插值算法:平衡處理速度與音質
- 變速不變調:調整播放速度(
-
參數調節范圍
參數 類型 示例值 說明 speed
float 0.5(半速)~2.0(倍速) 1.0為原始速度 pitch
float 0.5(低八度)~2.0(高八度) 1.0為原始音高 interpolation
enum LINEAR/FIR 線性插值(快) vs FIR插值(準) -
典型應用場景
- 音頻書籍變速播放
- 音樂音高修正
- 實時語音速度調整
-
特性對比
插值類型 處理速度 音質精度 適用場景 線性(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. 注意事項
- 速度/音高參數建議范圍:
0.5~2.0
,極端值可能導致失真 - FIR插值會增加20-30%的CPU負載
- 處理立體聲音頻時兩個聲道會同步調整
4. API
1. 核心配置與初始化
API/結構體 | 功能說明 | 關鍵參數/成員 |
---|---|---|
sonic_init(sonic_cfg_t *) | 初始化Sonic音頻處理器 | sonic_info (采樣率/聲道數)、out_rb_size (輸出緩沖區大小) |
sonic_cfg_t | 配置結構體 | - task_stack (默認4KB)- task_prio (優先級5)- stack_in_ext (外部內存) |
DEFAULT_SONIC_CONFIG() | 生成默認配置宏 | 預定義環形緩沖區(2KB)、任務核心(1)、插值模式(線性) |
2. 參數動態設置
API | 功能描述 | 參數范圍/說明 |
---|---|---|
sonic_set_info() | 設置輸入流采樣率和聲道數 | rate (Hz)、ch (1/2) |
sonic_set_pitch_and_speed_info() | 設置音高和速度比例因子 | pitch [0.2,4.0]speed [0.1,8.0](0=保持原值) |
3. 處理模式控制
配置項 | 選項 | 性能影響 |
---|---|---|
插值算法 ( resample_linear_interpolate ) | 1 :線性插值 | ?? 處理速度快,適合實時場景 |
0 :FIR插值 | 🎵 音質更優,CPU負載增加約30% |
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. 實踐
-
參數安全范圍:
- 音高(
pitch
):建議0.5~2.0(超出可能失真) - 速度(
speed
):建議0.5~4.0(極端值影響流暢性)
- 音高(
-
資源消耗:
配置組合 CPU占用 適用場景 線性插值 + 中等變速 低 實時語音處理 FIR插值 + 高精度變調 高 音樂后期制作 -
內存管理:
- 啟用
stack_in_ext
可減少內部RAM占用 - 輸出緩沖區(
out_rb_size
)建議≥4KB處理高碼率音頻
- 啟用