一、算法流 (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-10ms
ringbuf 需关联参考信号缓冲区 |
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)]