网站导航
> 技术文档 > ESP32的ADF详解：5. Streams的API

ESP32的ADF详解：5. Streams的API

网友: 技术文档 2025-07-26 20:29:22

一、算法流 (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 组合启用算法：

// 示例：同时启用AEC和NSconfig.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. 典型调用流程

  1. 初始化算法流

    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);

  2. 集成到流水线

    audio_pipeline_register(pipeline, algo_stream, \"algo\");audio_pipeline_link(pipeline, (const char*[]){\"i2s_reader\", \"algo\", \"vad\"}, 3);

  3. 调试延迟（Type2模式）

    ringbuf_handle_t ref_rb = rb_create(2048);algo_stream_set_delay(algo_stream, ref_rb, 5); // 设置5ms延迟

6. 注意事项

  1. 内存占用

    • 启用AEC约消耗50KB RAM，建议使用ESP32-S3/WROVER等大内存芯片
    • 外部PSRAM可设置stack_in_ext=true

  2. 性能调优

    • 采样率推荐16kHz，更高采样率会增加计算负担
    • AGC目标电平（target_level_dbfs）通常设为-3dBFS

  3. 硬件连接

    • Type1模式：需硬件支持I2S双声道（左声道接扬声器参考信号）
    • Type2模式：需用户自行同步参考信号与麦克风信号

二、FatFS流

1. 初始化与配置

API 功能描述 关键参数 fatfs_stream_init() 初始化FatFS流（读/写文件） type: AUDIO_STREAM_READER/WRITER
write_header: 是否写入AMR头

2. 结构体

/** * @brief FATFS 流配置结构体，用于配置 FATFS 流的参数。 * 如果任何条目为零，则配置将设置为默认值。 */struct fatfs_stream_cfg_t { audio_stream_type_t type; ///< 流类型 int buf_sz; ///< 音频元素缓冲区大小 int out_rb_size;  ///< 输出环形缓冲区大小 int task_stack; ///< 任务栈大小 int task_core; ///< 任务运行的核心（0 或 1） int task_prio; ///< 任务优先级（基于 FreeRTOS 优先级） bool ext_stack; ///< 是否在外部 RAM 中分配栈 bool write_header; ///< 是否在 FATFS 中写入 AMRNB/AMRWB 头（true 或 false，true 表示选择写入 AMRNB 头）};

三、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. 关键配置参数

结构体

/** * @brief HTTP 流事件消息结构体，用于传递 HTTP 流相关的事件信息。 */struct http_stream_event_msg_t { http_stream_event_id_t event_id; ///< 事件 ID，标识具体的事件类型 void *http_client; ///< 指向使用此 HTTP 流的 HTTP 客户端的引用 void *buffer; ///< 指向音频元素使用的缓冲区的引用 int buffer_len; ///< 缓冲区的长度 void *user_data; ///< 用户数据上下文，来自 http_stream_cfg_t audio_element_handle_t el; ///< 音频元素上下文};/** * @brief HTTP 流配置结构体，用于配置 HTTP 流的各种参数。 * 如果任何条目为零，则使用默认值。 */struct http_stream_cfg_t { audio_stream_type_t type; ///< 流类型 int out_rb_size; ///< 输出环形缓冲区的大小 int task_stack; ///< 任务栈大小 int task_core; ///< 任务运行的核心（0 或 1） int task_prio; ///< 任务优先级（基于 FreeRTOS 优先级） bool stack_in_ext; ///< 尝试在外部内存中分配栈 http_stream_event_handle_t event_handle; ///< HTTP 流事件的钩子函数 void *user_data; ///< 用户数据上下文 bool auto_connect_next_track; ///< 是否自动连接下一首曲目，无需打开/关闭 bool enable_playlist_parser; ///< 是否启用播放列表解析器 int multi_out_num; ///< 多输出数量 const char *cert_pem; ///< SSL 服务器证书，PEM 格式的字符串，如果客户端需要验证服务器 esp_err_t (*crt_bundle_attach)(void *conf); ///< 指向 esp_crt_bundle_attach 的函数指针，启用证书捆绑以进行服务器验证，必须在 menuconfig 中启用 int request_size; ///< 每次从 HTTP 客户端请求的数据大小，默认使用 DEFAULT_ELEMENT_BUFFER_LENGTH 如果设置为 0，如果音频帧大小较小且需要低延迟播放，需要小心此设置 int request_range_size; ///< 头部范围大小设置，范围：字节=起始-结束，如果设置为 0，请求资源的完整范围，建议范围大小大于请求大小 const char *user_agent; ///< 发送 HTTP 请求时使用的 User Agent 字符串};

宏定义

#define HTTP_STREAM_CFG_DEFAULT() // 默认配置（8KB环形缓冲区）#define HTTP_STREAM_RINGBUFFER_SIZE // 可覆盖默认缓冲区大小

6. 典型调用流程

HLS直播流播放

// 1. 初始化配置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;// 2. 创建实例audio_element_handle_t http_stream = http_stream_init(&cfg);// 3. 事件处理回调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音频流播放

// 设置SSL证书http_stream_set_server_cert(http_stream, \"-----BEGIN CERTIFICATE-----\\n\" \"MIIDx...\\n\" // 证书内容 \"-----END CERTIFICATE-----\");

注意事项

  1. 内存管理
    • 每个HTTP流实例默认占用~6KB任务栈，建议启用stack_in_ext使用外部RAM
  2. 直播流优化
    • 设置request_range_size > request_size避免频繁请求
  3. 错误处理
    • 监听HTTP_STREAM_FINISH_PLAYLIST事件处理播放列表结束
  4. 多输出支持
    • 通过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

/** * @brief I2S 流配置结构体，用于配置 I2S 流的各种参数。 * 如果任何条目为零，则使用默认值。 */struct i2s_stream_cfg_t { audio_stream_type_t type; ///< 流类型 i2s_comm_mode_t transmit_mode; ///< I2S 传输模式 i2s_chan_config_t chan_cfg; ///< I2S 控制器通道配置 i2s_std_config_t std_cfg; ///< I2S 标准模式主要配置，包括时钟/槽位/GPIO 配置 bool use_alc; ///< ALC 标志。如果使用 ALC，值为 true，否则为 false int volume; ///< 音频输入数据的音量设置 int out_rb_size; ///< 输出环形缓冲区大小 int task_stack; ///< 任务栈大小 int task_core; ///< 任务运行的核心（0 或 1） int task_prio; ///< 任务优先级（基于 FreeRTOS 优先级） bool stack_in_ext; ///< 尝试在外部内存中分配栈 int multi_out_num; ///< 多输出数量 bool uninstall_drv; ///< 是否在流销毁时卸载 I2S 驱动 bool need_expand; ///< 是否扩展 I2S 数据 i2s_data_bit_width_t expand_src_bits; ///< 扩展时的源每样本位数 int buffer_len; ///< 用于元素的缓冲区长度。注意：当 \'bits_per_sample\' 为 24 位时，缓冲区长度必须是 3 的倍数。推荐值为 3600};

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. 结构体

/** * @brief TCP 流事件消息结构体，用于传递 TCP 流相关的事件信息。 */struct tcp_stream_event_msg { void *source;  ///< 元素句柄 void *data;  ///< 输入/输出的数据 int data_len;  ///< 输入/输出的数据长度 esp_transport_handle_t sock_fd; ///< 套接字句柄};/** * @brief TCP 流配置结构体，用于配置 TCP 流的各种参数。 * 如果任何条目为零，则使用默认值。 */struct tcp_stream_cfg_t { audio_stream_type_t type; ///< 流类型 int timeout_ms; ///< 读写超时时间（毫秒） int port;///< TCP 端口号 char *host;  ///< TCP 主机地址 int task_stack; ///< 任务栈大小 int task_core;  ///< 任务运行的核心（0 或 1） int task_prio;  ///< 任务优先级（基于 FreeRTOS 优先级） bool ext_stack; ///< 是否在外部 RAM 中分配栈空间 tcp_stream_event_handle_cb event_handler; ///< TCP 流事件回调函数 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. 注意事项

  1. 连接管理：需通过回调函数 event_handler 监控连接状态（如断开重连）。
  2. 超时设置：timeout_ms 影响网络操作的阻塞时间。
  3. 资源分配：若启用 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

/** * @brief TONE 流配置结构体，用于配置 TONE 流的各种参数。 * 如果任何条目为零，则使用默认值。 */struct tone_stream_cfg_t { audio_stream_type_t type; ///< 流类型 int buf_sz; ///< 音频元素缓冲区大小 int out_rb_size; ///< 输出环形缓冲区大小 int task_stack; ///< 任务栈大小 int task_core; ///< 任务运行的核心（0 或 1） int task_prio; ///< 任务优先级（基于 FreeRTOS 优先级） const char *label; ///< 存储在闪存中的音调标签。默认值为 flash_tone bool extern_stack; ///< 任务栈是否在外部 RAM 中分配 bool use_delegate; ///< 是否使用 esp_delegate 读取音调分区。如果任务栈在外部 RAM 中，则必须为 TRUE};

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. 注意事项

  1. Flash 数据格式：提示音数据需通过 mk_audio_tone.py 工具生成，确保格式兼容。
  2. 资源分配：若使用外部堆栈（extern_stack=true），必须同时启用 use_delegate。
  3. 实时性：提示音流适用于短时音频播放（如系统提示音），不适用于长时间流媒体。

八、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

/** * @brief TTS 流配置结构体，用于配置 TTS 流的各种参数。 * 如果任何条目为零，则使用默认值。 */struct tts_stream_cfg_t { audio_stream_type_t type; ///< 流类型 int buf_sz; ///< 音频元素缓冲区大小 int out_rb_size; ///< 输出环形缓冲区大小 int task_stack; ///< 任务栈大小 int task_core; ///< 任务运行的核心（0 或 1） int task_prio; ///< 任务优先级（基于 FreeRTOS 优先级） bool ext_stack; ///< 是否在外部 RAM 中分配任务栈};

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）]
网络标签：

相关问题