当前位置: 首页 > news >正文

ESP32的ADF详解:5. Streams的API

一、算法流 (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_modeAGC模式:
AFE_AGC_OFF/AFE_AGC_FIXED/AFE_AGC_ADAPTIVE
语音识别建议ADAPTIVE
debug_input启用调试输出(生成左右声道原始数据)true/false

4. 算法掩码选项

通过 algo_mask 组合启用算法:

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

  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_idhttp_client指针事件回调参数

3. 安全认证

API功能描述参数说明注意事项
http_stream_set_server_cert()设置SSL服务器证书cert: PEM格式证书字符串仅HTTPS需要
crt_bundle_attach (配置项)启用证书包验证需在menuconfig中启用ESP_CERT_BUNDLE减少内存占用

4. 事件回调类型

事件ID触发时机典型处理逻辑
HTTP_STREAM_PRE_REQUESTHTTP请求发起前修改请求头/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_taudio_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_OKESP_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_OKESP_FAIL

3. 音量控制(ALC)

函数描述参数返回值
i2s_alc_volume_set()设置ALC音量i2s_stream: 元素句柄
volume: 音量值(-64~63dB)
ESP_OKESP_FAIL
i2s_alc_volume_get()获取当前音量i2s_stream: 元素句柄
volume: 存储音量值的指针
ESP_OKESP_FAIL

4. 同步控制

函数描述参数返回值
i2s_stream_sync_delay()设置流同步延迟i2s_stream: 元素句柄
delay_ms: 延迟时间(ms)
ESP_OKESP_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,否则为 falseint 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

成员类型描述
typeaudio_stream_type_t流类型(读/写)
out_rb_sizeint输出环形缓冲区大小

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_tTCP 流状态:
- 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_tonebool 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_OKESP_FAIL
tts_stream_set_speed()设置语音合成速度(0-5,0 最慢)el: 音频元素句柄
speed: 速度值(tts_voice_speed_t 枚举类型)
ESP_OKESP_FAIL
tts_stream_get_speed()获取当前语音合成速度el: 音频元素句柄
speed: 返回速度值的指针
ESP_OKESP_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)]
http://www.lryc.cn/news/596937.html

相关文章:

  • 聊聊 Flutter 在 iOS 真机 Debug 运行出现 Timed out *** to update 的问题
  • 在AI深度嵌入企业业务的当下——AI时代的融合数据库
  • Qt 菜单与工具栏设计:提升用户体验
  • AI产品经理面试宝典第48天:产品设计与用户体验优化策略
  • 【数学建模 | Matlab】二维绘图 和 三维绘图
  • 国产数据库转向 “融合” 赛道:电科金仓的下一代形态定义之路
  • Leetcode力扣解题记录--第240题(矩阵搜索)
  • 大规模金融数据相关性并行计算系统设计与实现
  • Linux内存映射原理
  • 第十讲:stack、queue、priority_queue以及deque
  • Python-初学openCV——图像预处理(一)
  • 如何在 npm 上发布 Element Plus 二次封装组件
  • Parasoft为金融服务打造统一测试平台,提升安全、合规与交付效率
  • C++ Primer(第5版)- Chapter 7. Classes -005
  • ESP32的ADF详解:6. Audio Processing的API
  • Android 测试全指南:单元测试与UI测试框架详解
  • ESP-NOW实战:ESP32一对多无线通信方案(支持ESP8266兼容)
  • 【Spring Cloud Gateway 实战系列】进阶篇:过滤器高级用法、动态路由配置与性能优化
  • Android Studio中调用USB摄像头
  • CRMEB 单商户PRO多商户通用去版权教程
  • win11安装erlang和rabbitmq
  • SpringBoot 使用Rabbitmq
  • RabbitMQ--@RabbitListener及@RabbitHandle
  • OceanBase数据库
  • RabbitMQ有多少种Exchange?
  • LLM 幻觉一般是由于什么产生的,在模型什么部位产生
  • Java学习第六十九部分——RabbitMQ
  • iOS WebView 远程调试实战 解决表单输入被键盘遮挡和焦点丢失问题
  • 期权遇到股票分红会调整价格吗?
  • 【机器学习深度学习】比较 LLaMA-Factory、vLLM 和 LMDeploy 的量化导出:为何 LLaMA-Factory 不是首选?