一、算法流 (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)]