一、算法流 (algorithm stream)
1. 初始化與配置 API 功能描述 關鍵參數說明 algo_stream_init()
初始化算法流(AEC/AGC/NS/VAD) config->algo_mask
選擇算法組合config->sample_rate
設置采樣率(默認16kHz)config->partition_label
指定模型分區ALGORITHM_STREAM_CFG_DEFAULT()
獲取默認配置宏 包含默認任務棧大小(4KB)、環形緩沖區大小(8KB)等
2. 算法控制 API 功能描述 關鍵參數說明 algo_stream_set_delay()
設置播放/錄音信號延遲(Type2模式專用) delay_ms
推薦0-10msringbuf
需關聯參考信號緩沖區algorithm_mono_fix()
修復ESP32 I2S單聲道噪聲問題 需傳入16bit PCM數據緩沖區
3. 音頻處理配置
| 配置結構體 algorithm_stream_cfg_t
關鍵字段:
字段 功能描述 推薦值 input_type
輸入類型:TYPE1
:單I2S雙聲道輸入(左=參考,右=麥克風)TYPE2
:獨立信號輸入 根據硬件連接選擇 rec_linear_factor
錄音信號線性放大系數 1-10(原始信號較弱時增大) agc_mode
AGC模式:AFE_AGC_OFF
/AFE_AGC_FIXED
/AFE_AGC_ADAPTIVE
語音識別建議ADAPTIVE
debug_input
啟用調試輸出(生成左右聲道原始數據) true/false
4. 算法掩碼選項
通過 algo_mask
組合啟用算法:
config. algo_mask = ALGORITHM_STREAM_USE_AEC | ALGORITHM_STREAM_USE_NS;
掩碼值 對應算法 適用場景 ALGORITHM_STREAM_USE_AEC
聲學回聲消除 語音通話、免提設備 ALGORITHM_STREAM_USE_AGC
自動增益控制 動態麥克風輸入 ALGORITHM_STREAM_USE_NS
噪聲抑制 高噪聲環境 ALGORITHM_STREAM_USE_VAD
語音活動檢測 關鍵詞喚醒
5. 典型調用流程
初始化算法流
algorithm_stream_cfg_t algo_cfg = ALGORITHM_STREAM_CFG_DEFAULT ( ) ;
algo_cfg. algo_mask = ALGORITHM_STREAM_USE_AEC | ALGORITHM_STREAM_USE_NS;
algo_cfg. sample_rate = 16000 ;
audio_element_handle_t algo_stream = algo_stream_init ( & algo_cfg) ;
集成到流水線
audio_pipeline_register ( pipeline, algo_stream, "algo" ) ;
audio_pipeline_link ( pipeline, ( const char * [ ] ) { "i2s_reader" , "algo" , "vad" } , 3 ) ;
調試延遲(Type2模式)
ringbuf_handle_t ref_rb = rb_create ( 2048 ) ;
algo_stream_set_delay ( algo_stream, ref_rb, 5 ) ;
6. 注意事項
內存占用
啟用AEC約消耗50KB RAM,建議使用ESP32-S3/WROVER等大內存芯片 外部PSRAM可設置stack_in_ext=true
性能調優
采樣率推薦16kHz,更高采樣率會增加計算負擔 AGC目標電平(target_level_dbfs
)通常設為-3dBFS
硬件連接
Type1模式 :需硬件支持I2S雙聲道(左聲道接揚聲器參考信號)Type2模式 :需用戶自行同步參考信號與麥克風信號
二、FatFS流
1. 初始化與配置 API 功能描述 關鍵參數 fatfs_stream_init()
初始化FatFS流(讀/寫文件) type
: AUDIO_STREAM_READER
/WRITER
write_header
: 是否寫入AMR頭
2. 結構體
struct fatfs_stream_cfg_t { audio_stream_type_t type; int buf_sz; int out_rb_size; int task_stack; int task_core; int task_prio; bool ext_stack; bool write_header;
} ;
三、HTTP流
1. 初始化與基礎控制 API 功能描述 關鍵參數 返回值 http_stream_init()
初始化HTTP流實例 config->type
: 指定讀/寫模式config->enable_playlist_parser
: 啟用HLS播放列表解析返回元素句柄 http_stream_restart()
重啟HTTP流連接 el
: HTTP流句柄ESP_OK/ESP_FAIL http_stream_fetch_again()
重新獲取播放列表(直播流場景) el
: HTTP流句柄ESP_OK/ESP_ERR_NOT_SUPPORTED
2. 播放列表控制 API 功能描述 觸發條件 使用場景 http_stream_next_track()
切換到下一曲目 需在HTTP_STREAM_FINISH_TRACK
事件回調中調用 播放列表/HLS直播流 http_stream_event_msg_t
播放事件結構體 包含event_id
和http_client
指針 事件回調參數
3. 安全認證 API 功能描述 參數說明 注意事項 http_stream_set_server_cert()
設置SSL服務器證書 cert
: PEM格式證書字符串僅HTTPS需要 crt_bundle_attach
(配置項)啟用證書包驗證 需在menuconfig中啟用ESP_CERT_BUNDLE
減少內存占用
4. 事件回調類型 事件ID 觸發時機 典型處理邏輯 HTTP_STREAM_PRE_REQUEST
HTTP請求發起前 修改請求頭/URL HTTP_STREAM_FINISH_TRACK
單曲目播放完成 調用next_track()
切換 HTTP_STREAM_ON_RESPONSE
接收數據時 實時數據校驗/分析
5. 關鍵配置參數
結構體
struct http_stream_event_msg_t { http_stream_event_id_t event_id; void * http_client; void * buffer; int buffer_len; void * user_data; audio_element_handle_t el;
} ;
struct http_stream_cfg_t { audio_stream_type_t type; int out_rb_size; int task_stack; int task_core; int task_prio; bool stack_in_ext; http_stream_event_handle_t event_handle; void * user_data; bool auto_connect_next_track; bool enable_playlist_parser; int multi_out_num; const char * cert_pem; esp_err_t ( * crt_bundle_attach) ( void * conf) ; int request_size; int request_range_size; const char * user_agent;
} ;
宏定義
# define HTTP_STREAM_CFG_DEFAULT ( )
# define HTTP_STREAM_RINGBUFFER_SIZE
6. 典型調用流程
HLS直播流播放
http_stream_cfg_t cfg = HTTP_STREAM_CFG_DEFAULT ( ) ;
cfg. type = AUDIO_STREAM_READER;
cfg. enable_playlist_parser = true;
cfg. event_handle = _hls_event_handler;
audio_element_handle_t http_stream = http_stream_init ( & cfg) ;
static int _hls_event_handler ( http_stream_event_msg_t * msg) { if ( msg-> event_id == HTTP_STREAM_FINISH_TRACK) { http_stream_next_track ( msg-> el) ; } return 0 ;
}
HTTPS音頻流播放
http_stream_set_server_cert ( http_stream, "-----BEGIN CERTIFICATE-----\n" "MIIDx...\n" "-----END CERTIFICATE-----" ) ;
注意事項
內存管理
每個HTTP流實例默認占用~6KB任務棧,建議啟用stack_in_ext
使用外部RAM
直播流優化
設置request_range_size > request_size
避免頻繁請求
錯誤處理
監聽HTTP_STREAM_FINISH_PLAYLIST
事件處理播放列表結束
多輸出支持
通過multi_out_num
配置多路輸出環形緩沖區
四、I2S流
1. 初始化與配置函數/宏定義 描述 參數 返回值 i2s_stream_init()
創建I2S流音頻元素句柄 config
: 配置結構體音頻元素句柄 i2s_stream_set_channel_type()
設置I2S流通道格式類型 config
: 配置結構體type
: 通道格式類型ESP_OK
或ESP_ERR_INVALID_ARG
I2S_STREAM_CFG_DEFAULT()
默認I2S流配置宏 無 默認配置結構體 I2S_STREAM_CFG_DEFAULT_WITH_PARA()
帶參數的默認配置宏 port
: I2S端口rate
: 采樣率bits
: 位寬stream_type
: 流類型配置結構體 I2S_STREAM_CFG_DEFAULT_WITH_TYLE_AND_CH()
帶類型和通道的默認配置宏 port
: I2S端口rate
: 采樣率bits
: 位寬stream_type
: 流類型channel
: 通道類型配置結構體
2. 時鐘控制函數 描述 參數 返回值 i2s_stream_set_clk()
設置I2S流時鐘 i2s_stream
: 元素句柄rate
: 采樣率(Hz)bits
: 位寬(8/16/24/32)ch
: 通道數ESP_OK
或ESP_FAIL
3. 音量控制(ALC)函數 描述 參數 返回值 i2s_alc_volume_set()
設置ALC音量 i2s_stream
: 元素句柄volume
: 音量值(-64~63dB)ESP_OK
或ESP_FAIL
i2s_alc_volume_get()
獲取當前音量 i2s_stream
: 元素句柄volume
: 存儲音量值的指針ESP_OK
或ESP_FAIL
4. 同步控制函數 描述 參數 返回值 i2s_stream_sync_delay()
設置流同步延遲 i2s_stream
: 元素句柄delay_ms
: 延遲時間(ms)ESP_OK
或ESP_FAIL
5. 結構體
i2s_stream_cfg_t
struct i2s_stream_cfg_t { audio_stream_type_t type; i2s_comm_mode_t transmit_mode; i2s_chan_config_t chan_cfg; i2s_std_config_t std_cfg; bool use_alc; int volume; int out_rb_size; int task_stack; int task_core; int task_prio; bool stack_in_ext; int multi_out_num; bool uninstall_drv; bool need_expand; i2s_data_bit_width_t expand_src_bits; int buffer_len;
} ;
6. 枚舉類型
i2s_channel_type_t
枚舉值 描述 I2S_CHANNEL_TYPE_RIGHT_LEFT
分離的左右聲道 I2S_CHANNEL_TYPE_ALL_RIGHT
兩個聲道都加載右聲道數據 I2S_CHANNEL_TYPE_ALL_LEFT
兩個聲道都加載左聲道數據 I2S_CHANNEL_TYPE_ONLY_RIGHT
僅在右聲道加載數據(單聲道模式) I2S_CHANNEL_TYPE_ONLY_LEFT
僅在左聲道加載數據(單聲道模式)
五、RAW流
1. 初始化與配置函數/宏定義 描述 參數 返回值 raw_stream_init()
初始化RAW流 cfg
: 配置結構體音頻元素句柄 RAW_STREAM_CFG_DEFAULT()
默認RAW流配置宏 無 默認配置結構體
2. 數據讀寫操作函數 描述 參數 返回值 raw_stream_read()
從流中讀取數據 pipeline
: 管道句柄buffer
: 數據緩沖區buf_size
: 最大讀取字節數實際讀取的字節數 raw_stream_write()
向流中寫入數據 pipeline
: 管道句柄buffer
: 數據緩沖區buf_size
: 要寫入的字節數實際寫入的字節數
3. 結構體
raw_stream_cfg_t
成員 類型 描述 type
audio_stream_type_t
流類型(讀/寫) out_rb_size
int
輸出環形緩沖區大小
4. 宏定義宏 描述 RAW_STREAM_RINGBUFFER_SIZE
默認環形緩沖區大小
5. 應用模式說明模式 數據流向 示例 讀模式(AUDIO_STREAM_READER) 從前級元素獲取數據 [i2s] → [filter] → [raw] [i2s] → [codec-amr] → [raw] 寫模式(AUDIO_STREAM_WRITER) 向后級元素提供數據 [raw] → [codec-mp3] → [i2s]
六、TCP流
1. 初始化與配置 函數/宏定義 描述 參數 返回值 tcp_stream_init()
初始化 TCP 客戶端流 config
: 配置結構體 (tcp_stream_cfg_t
)音頻元素句柄 TCP_STREAM_CFG_DEFAULT()
默認 TCP 流配置宏 無 默認配置結構體
2. 結構體
struct tcp_stream_event_msg { void * source; void * data; int data_len; esp_transport_handle_t sock_fd;
} ;
struct tcp_stream_cfg_t { audio_stream_type_t type; int timeout_ms; int port; char * host; int task_stack; int task_core; int task_prio; bool ext_stack; tcp_stream_event_handle_cb event_handler; void * event_ctx;
} ;
3. 事件回調與狀態 類型/枚舉 描述 回調函數 tcp_stream_event_handle_cb
處理 TCP 流事件的回調函數,參數包括: - msg
: 事件消息 (tcp_stream_event_msg_t
) - state
: 連接狀態 (tcp_stream_status_t
) - event_ctx
: 用戶上下文 枚舉 tcp_stream_status_t
TCP 流狀態: - TCP_STREAM_STATE_NONE
(未連接) - TCP_STREAM_STATE_CONNECTED
(已連接)
4. 宏定義 宏 描述 TCP_STREAM_DEFAULT_PORT
默認 TCP 端口號 TCP_STREAM_TASK_STACK
默認任務堆棧大小 TCP_STREAM_BUF_SIZE
默認緩沖區大小 TCP_STREAM_TASK_PRIO
默認任務優先級 TCP_STREAM_TASK_CORE
默認任務運行核心 TCP_SERVER_DEFAULT_RESPONSE_LENGTH
默認服務器響應長度
5. 典型數據流向 模式 數據方向 示例 讀取模式 (AUDIO_STREAM_READER
)從服務器接收數據 [tcp_client] → [decoder] → [i2s]
寫入模式 (AUDIO_STREAM_WRITER
)向服務器發送數據 [i2s] → [encoder] → [tcp_client]
6. 注意事項
連接管理 :需通過回調函數 event_handler
監控連接狀態(如斷開重連)。超時設置 :timeout_ms
影響網絡操作的阻塞時間。資源分配 :若啟用 ext_stack
,需確保外部 RAM 可用。
七、TONE流
1. 初始化與配置 函數/宏定義 描述 參數 返回值 tone_stream_init()
初始化提示音流(僅支持 AUDIO_STREAM_READER
類型,從 Flash 讀取音頻數據) config
: 配置結構體 (tone_stream_cfg_t
)音頻元素句柄 TONE_STREAM_CFG_DEFAULT()
默認提示音流配置宏 無 默認配置結構體
2. 結構體
tone_stream_cfg_t
struct tone_stream_cfg_t { audio_stream_type_t type; int buf_sz; int out_rb_size; int task_stack; int task_core; int task_prio; const char * label; bool extern_stack; bool use_delegate;
} ;
3. 宏定義 宏 描述 TONE_STREAM_BUF_SIZE
默認緩沖區大小 TONE_STREAM_TASK_STACK
默認任務堆棧大小 TONE_STREAM_TASK_CORE
默認任務運行核心 TONE_STREAM_TASK_PRIO
默認任務優先級 TONE_STREAM_RINGBUFFER_SIZE
默認環形緩沖區大小 TONE_STREAM_EXT_STACK
是否默認啟用外部堆棧分配 TONE_STREAM_USE_DELEGATE
是否默認啟用 esp_delegate
讀取 Flash
4. 功能限制與說明 特性 描述 僅支持讀取模式 提示音流僅支持 AUDIO_STREAM_READER
類型,不可用于寫入。 數據來源 需通過 tools/audio_tone/mk_audio_tone.py
生成二進制數據并燒錄至 Flash 的指定分區(標簽通過 label
指定)。 外部堆棧依賴 若啟用 extern_stack
,需確保外部 RAM 可用且 use_delegate=true
。
5. 典型數據流向
[Flash 提示音數據] → [tone_stream] → [下游音頻元素(如 I2S)]
6. 注意事項
Flash 數據格式 :提示音數據需通過 mk_audio_tone.py
工具生成,確保格式兼容。資源分配 :若使用外部堆棧(extern_stack=true
),必須同時啟用 use_delegate
。實時性 :提示音流適用于短時音頻播放(如系統提示音),不適用于長時間流媒體。
八、TTS流
1. 初始化與配置 函數/宏定義 描述 參數 返回值 tts_stream_init()
初始化 TTS 流(僅支持 AUDIO_STREAM_READER
類型,從 esp_tts_voice
獲取數據) config
: 配置結構體 (tts_stream_cfg_t
)音頻元素句柄 TTS_STREAM_CFG_DEFAULT()
默認 TTS 流配置宏 無 默認配置結構體
2. 語音合成控制 函數 描述 參數 返回值 tts_stream_set_strings()
設置 TTS 合成的文本字符串 el
: 音頻元素句柄strings
: 待合成的文本字符串指針ESP_OK
或 ESP_FAIL
tts_stream_set_speed()
設置語音合成速度(0-5,0 最慢) el
: 音頻元素句柄speed
: 速度值(tts_voice_speed_t
枚舉類型)ESP_OK
或 ESP_FAIL
tts_stream_get_speed()
獲取當前語音合成速度 el
: 音頻元素句柄speed
: 返回速度值的指針ESP_OK
或 ESP_FAIL
3. 結構體
tts_stream_cfg_t
struct tts_stream_cfg_t { audio_stream_type_t type; int buf_sz; int out_rb_size; int task_stack; int task_core; int task_prio; bool ext_stack;
} ;
4. 宏定義 宏 描述 TTS_STREAM_BUF_SIZE
默認緩沖區大小 TTS_STREAM_TASK_STACK
默認任務堆棧大小 TTS_STREAM_TASK_CORE
默認任務運行核心 TTS_STREAM_TASK_PRIO
默認任務優先級 TTS_STREAM_RINGBUFFER_SIZE
默認環形緩沖區大小
5. 枚舉類型 (tts_voice_speed_t
) 枚舉值 描述 TTS_VOICE_SPEED_0
最慢語速(等級 0) TTS_VOICE_SPEED_1
語速等級 1 TTS_VOICE_SPEED_2
語速等級 2 TTS_VOICE_SPEED_3
默認語速(等級 3) TTS_VOICE_SPEED_4
語速等級 4 TTS_VOICE_SPEED_5
最快語速(等級 5) TTS_VOICE_SPEED_MAX
最大語速(同等級 5)
6. 功能限制與說明 特性 描述 僅支持讀取模式 TTS 流僅支持 AUDIO_STREAM_READER
類型,不可用于寫入。 依賴 esp-sr 需集成 esp-sr
組件以提供 esp_tts_voice
語音合成功能。 實時性要求 適用于實時語音合成場景(如語音助手響應),需合理設置緩沖區大小以避免卡頓。
7. 典型數據流向
[esp_tts_voice 合成數據] → [tts_stream] → [下游音頻元素(如 I2S)]