ESP32的ADF详解：5. Streams的API

一、算法流 (algorithm stream)

1. 初始化与配置

2. 算法控制

3. 音频处理配置

| 配置结构体 algorithm_stream_cfg_t 关键字段：

4. 算法掩码选项

通过 algo_mask 组合启用算法：

// 示例：同时启用AEC和NS
config.algo_mask = ALGORITHM_STREAM_USE_AEC | ALGORITHM_STREAM_USE_NS;

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. 初始化与配置

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. 初始化与基础控制

2. 播放列表控制

3. 安全认证

4. 事件回调类型

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. 初始化与配置

2. 时钟控制

3. 音量控制(ALC)

4. 同步控制

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

五、RAW流

1. 初始化与配置

2. 数据读写操作

3. 结构体

raw_stream_cfg_t

4. 宏定义

5. 应用模式说明

六、TCP流

1. 初始化与配置

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. 事件回调与状态

4. 宏定义

5. 典型数据流向

6. 注意事项

1. 连接管理：需通过回调函数 event_handler 监控连接状态（如断开重连）。
2. 超时设置：timeout_ms 影响网络操作的阻塞时间。
3. 资源分配：若启用 ext_stack，需确保外部 RAM 可用。

七、TONE流

1. 初始化与配置

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. 宏定义

4. 功能限制与说明

5. 典型数据流向

[Flash 提示音数据] → [tone_stream] → [下游音频元素（如 I2S）]

6. 注意事项

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

八、TTS流

1. 初始化与配置

2. 语音合成控制

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. 宏定义

5. 枚举类型 (tts_voice_speed_t)

6. 功能限制与说明

7. 典型数据流向

[esp_tts_voice 合成数据] → [tts_stream] → [下游音频元素（如 I2S）]