简介基于ESP32的语音唤醒与离线/在线识别完整工程源码包面向电子信息、计算机等专业学生和嵌入式开发者适合课程设计、毕业设计或实战入门。包内共有616个文件压缩包大小为42.27MB以C/C源文件、汇编文件、语音模型数据及测试音频为主另含Markdown文档、Python脚本与配置文件覆盖源码、模型、文档和工具链便于理解工程结构并进行二次开发目前已有185人学习浏览。资源完整集成了语音唤醒、离线识别与百度在线识别三种模式可直接编译运行配套模型文件和音频样例通过阅读源码可以学习ESP32音频采集、唤醒词模型部署、离线识别引擎集成以及云端API调用等关键环节清晰的目录结构和readme说明也为初学者提供了良好的上手路径方便在此基础上扩展功能并完成毕业设计或项目展示。1. 从离线唤醒到百度在线的双级语音链路做智能家居面板或毕设语音终端时最尴尬的不是模型效果差而是功耗和延迟互相打架。常驻在线识别设备发热、云端费用高断网就瘫只做本地识别词表一扩ESP32 的内存直接告急。ESP32 语音唤醒离线识别百度在线识别这套方案把语音链路拆成两段本地用 ESP-SR 跑小模型做唤醒词检测和低延迟命令词识别识别置信度不够或词表外的话再走百度的 REST 接口做大词汇量识别。这部分源码把 I2S 采集、唤醒循环、HTTP 鉴权上传都串好了适合做课程设计、毕业设计也适合想把离线在线混合识别落进智能家居设备里的工程师。下面按音频采集、离线识别、在线接入、切换策略四个层面拆开讲最后补一个射频干扰导致识别率骤降的排查技巧。2. I2S 数字音频采集麦克风选型与采样配置2.1 麦克风选型与接口选择ESP32 本身没有模拟音频输入必须外接数字麦克风或 Codec。数字麦克风有两类接口IIS 和 PDM。IIS 接口的典型代表是 INMP441PDM 接口的代表是 MSM261S4030H0 和软排线封装的 S21。PDM 麦克风输出的是 1bit 的高频脉冲密度流需要 ESP32 内部的 I2S 外设做抽取滤波把 2.4MHz 或 3.2MHz 的 PDM 流降到 16kHz/16bit 的 PCM 数据。INMP441 这类 IIS 麦克风则直接输出 16/24bit PCM配置更直观但占用的 GPIO 和时钟要求更严格。给这套源码配硬件时优先选 INMP441因为 ESP-SR 官方例程和第三方移植大多按 IIS 模式初始化踩坑成本低。型号接口类型信噪比需要的 GPIO典型场景INMP441IIS/PCM61dBSCK/WS/SD 三线固定面板、桌面设备MSM261S4030H0PDM63dBCLK/DATA 两线低引脚占用的小板S21PDM59dBCLK/DATA 两线低成本唤醒板PDM 麦克风虽然省一根 IO但 PDM 时钟抖动对识别率影响明显PCB 走线不好时容易出现周期性爆音。如果选 PDM建议把 CLK 和 DATA 分别走地线包边并缩短到芯片的距离。2.2 I2S 外设初始化与 16kHz 采样配置无论用 Arduino 还是 ESP-IDFI2S 驱动接口的参数模型都一样需要明确采样率、位宽、通道数和主从模式。以下是在 ESP-IDF 中初始化 IIS 模式采集的常见写法#include driver/i2s.h #include driver/i2s_common.h #define I2S_PORT I2S_NUM_0 #define I2S_SCK 5 #define I2S_WS 25 #define I2S_SD 26 void audio_i2s_init(void) { i2s_config_t i2s_cfg { .mode I2S_MODE_MASTER | I2S_MODE_RX, // 主机接收模式 .sample_rate 16000, // 16kHz 采样率 .bits_per_sample I2S_BITS_PER_SAMPLE_16BIT, // 16bit 采样位宽 .channel_format I2S_CHANNEL_FMT_ONLY_LEFT, // 单声道取左声道 .communication_format I2S_COMM_FORMAT_STAND_I2S, .intr_alloc_flags ESP_INTR_FLAG_LEVEL1, .dma_buf_count 8, // DMA 缓冲区个数 .dma_buf_len 256, // 每个 DMA 缓冲区的帧数 .use_apll false, .tx_desc_auto_clear false, }; i2s_driver_install(I2S_PORT, i2s_cfg, 0, NULL); i2s_pin_config_t pin_cfg { .bck_io_num I2S_SCK, .ws_io_num I2S_WS, .data_out_num I2S_PIN_NO_CHANGE, .data_in_num I2S_SD, }; i2s_set_pin(I2S_PORT, pin_cfg); }这段配置里有两个参数直接决定 ESP-SR 能不能正常工作。sample_rate必须设成 16000ESP-SR 的唤醒词模型和命令词模型都按 16kHz 训练的喂 8kHz 或 44.1kHz 数据进去识别率会断崖式下降。channel_format设为单声道是因为语音识别算法只需要一路信号双声道数据会让 DMA 缓冲区占用翻倍而且 INMP441 的右声道在 ONLY_LEFT 模式下是静音数据浪费内存。dma_buf_len设为 256配合 16kHz 采样率每帧 DMA 数据约 16ms唤醒检测循环的调度粒度也按这个量级走。缓冲区太小容易在 CPU 被 WiFi 任务抢占时丢数据太大会增加识别延迟。2.3 音频帧读取与环形缓冲区存放ESP-SR 的唤醒接口是按帧读取数据的每次传入 16ms 的音频块。实际工程中不直接读一次处理一次而是先放环形缓冲区由识别任务按自己的节奏取。这样 WiFi 栈的高优先级任务抢 CPU 时不会造成音频帧断裂。#include freertos/ringbuf.h RingbufHandle_t audio_ringbuf; #define FRAME_SIZE 512 // 16kHz * 16bit * 16ms 512 字节 static void audio_capture_task(void *arg) { int16_t sample_buf[FRAME_SIZE / 2]; size_t bytes_read 0; while (1) { esp_err_t err i2s_read(I2S_PORT, sample_buf, FRAME_SIZE, bytes_read, portMAX_DELAY); if (err ESP_OK bytes_read FRAME_SIZE) { xRingbufferSend(audio_ringbuf, sample_buf, bytes_read, pdMS_TO_TICKS(10)); } } }这段代码从 I2S 外设读取固定大小的音频块然后投递到 FreeRTOS RingBuffer。RingBuffer 在 ESP32 上比队列更适合音频场景因为它是直接内存拷贝不涉及队列项复制时的二次分配。读取返回后必须检查bytes_read是否等于请求长度DMA 在 WiFi 共存期间偶尔会返回短帧这种帧直接丢弃不要往识别引擎里送。3. 基于 ESP-SR 的离线唤醒与命令词识别3.1 WakeNet 与 MultiNet 的分工ESP-SR 里两个模型各司其职。WakeNet 负责低功耗唤醒词检测例如“你好小智”它运行在连续监听模式下不断从 I2S 数据流里找唤醒词特征。唤醒触发后MultiNet 开始工作负责离线命令词识别例如“打开空调”“温度调到二十六度”。两个模型叠加内存占用约 800KB 左右ESP32 传统型号跑起来吃力ESP32-S3 比较从容。工程上我会把整个识别链路跑在 S3 上片外 PSRAM 可不开因为 MultiNet 的模型和 feature cache 都放内部 RAM 才能保证实时性。把 WakeNet 和 MultiNet 都放在 PSRAM 里虽然能跑但唤醒延迟会从 200ms 涨到 350ms 以上功耗也更高。3.2 语音识别引擎初始化流程初始化顺序有讲究先开 I2S再加载 WakeNet最后加载 MultiNet。反过来初始化时模型加载期间的音频数据会丢失可能导致启动后第一次唤醒失败。#include esp_sr.h static model_data_t *wakenet_model; static model_data_t *multinet_model; static srec_handle_t *srec_engine; static int wake_word_id -1; static esp_err_t voice_recognition_init(void) { // 初始化 ESP-SR 模型资源 srmodel_list_t *model_list esp_srmodel_init(model); if (model_list NULL) { return ESP_ERR_INVALID_STATE; } // 加载 WakeNet 中文唤醒词模型 char *wn_name esp_srmodel_filter(model_list, ESP_WN_PREFIX, EN_WN_ZH); wakenet_model esp_srmodel_get(model_list, wn_name); // 加载 MultiNet 中文命令词模型 char *mn_name esp_srmodel_filter(model_list, ESP_MN_PREFIX, EN_MN_ZH); multinet_model esp_srmodel_get(model_list, mn_name); // 创建唤醒识别句柄 srec_engine esp_sr_create_srec(wakenet_model, SREC_MODE_WAKENET, 16000, 2); if (srec_engine NULL) { return ESP_ERR_NO_MEM; } esp_sr_set_detection_threshold(srec_engine, 0.5f); return ESP_OK; }esp_sr_create_srec第二参数的SREC_MODE_WAKENET指定引擎以唤醒模式运行。模型里的EN_WN_ZH表示中文唤醒词EN_MN_ZH表示中文命令词工程里默认的唤醒词是“你好小智”你可以在 ESP-SR 的模型配置里替换成“小度小度”“你好小智”等但词条必须和训练集一致否则检测不到。3.3 唤醒检测循环与命令词置信度判定唤醒检测不是等触发才开始而是持续对音频帧打分。每一帧都会返回一个置信度超过阈值才认为唤醒。static void recognition_task(void *arg) { int16_t audio[512 * 2]; size_t read_len 0; while (1) { // 从环形缓冲区取一帧音频 size_t item_size 0; int16_t *item xRingbufferReceive(audio_ringbuf, item_size, pdMS_TO_TICKS(100)); if (item NULL || item_size ! sizeof(audio)) { vTaskDelay(pdMS_TO_TICKS(10)); continue; } memcpy(audio, item, item_size); vRingbufferReturnItem(audio_ringbuf, item); // 将音频喂给 srec返回值是置信度 int det_result esp_sr_feed_srec(srec_engine, audio); if (det_result 0) { // 唤醒成功切换到命令词识别模式 srec_engine esp_sr_create_srec(multinet_model, SREC_MODE_MULTINET, 16000, 2); if (srec_engine ! NULL) { esp_sr_set_detection_threshold(srec_engine, 0.6f); int cmd_id esp_sr_feed_srec(srec_engine, audio); if (cmd_id 0) { process_command(cmd_id); } } // 识别完成后重新进入唤醒模式 srec_engine esp_sr_create_srec(wakenet_model, SREC_MODE_WAKENET, 16000, 2); } } }代码里把唤醒模式和多轮对话模式串成了状态机。esp_sr_feed_srec返回-1表示当前帧没检测到目标返回0表示命中命中的整数值就是命令词的 ID。不同命令词对应不同 ID应用层根据process_command(cmd_id)分发动作。命令词文本对应 ID推荐阈值误触发表现打开空调00.6无串到其他命令概率低关闭空调10.6无温度调到二十六度20.65偶尔和“二十五度”混淆查询电量30.7无阈值调高会降低误唤醒但真实环境里说话人距离超过 3 米时命中率会明显下降。先用默认值跑一周再统计误唤醒次数来微调。4. 百度在线识别接入鉴权、音频上传与结果解析4.1 REST API 鉴权与 access_token 缓存机制百度在线识别的接口基于 REST API调用前需要先获取access_token。token 有效期为 30 天获取一次后缓存下来避免每次识别前都重新请求导致延迟增加。#include esp_http_client.h #include cJSON.h static char auth_token[128] {0}; esp_err_t get_bd_access_token(const char *api_key, const char *secret_key) { char url[512]; snprintf(url, sizeof(url), https://aip.baidubce.com/oauth/2.0/token?grant_typeclient_credentials client_id%sclient_secret%s, api_key, secret_key); esp_http_client_config_t config { .url url, .timeout_ms 5000, }; esp_http_client_handle_t client esp_http_client_init(config); esp_http_client_set_method(client, HTTP_METHOD_POST); char *response NULL; int content_length 0; esp_err_t err esp_http_client_open(client, 0); if (err ESP_OK) { content_length esp_http_client_fetch_headers(client); int total esp_http_client_read_response(client, response, 512); if (total 0) { cJSON *json cJSON_Parse(response); cJSON *token_item cJSON_GetObjectItem(json, access_token); if (cJSON_IsString(token_item)) { strncpy(auth_token, token_item-valuestring, sizeof(auth_token) - 1); } cJSON_Delete(json); } } esp_http_client_cleanup(client); return err; }代码里 URL 拼接了grant_typeclient_credentials这是百度 AI 开放平台的标准 OAuth 方式。client_id对应控制台里的 API Keyclient_secret对应 Secret Key。timeout_ms尽量不小于 5000token 请求偶尔会慢到 2 秒。4.2 音频格式处理与 Base64 编码上传百度在线识别接口接收的音频格式为原始 PCM常见要求是 16kHz 采样率、16bit 位宽、单声道。I2S 里直接拿到的数据不能直接 POST 上去必须按固定长度分帧并做 Base64 编码。#include mbedtls/base64.h static char *pcm_to_base64(int16_t *pcm_data, size_t pcm_len) { size_t b64_len 0; // 新接口 raw 格式只传原始 PCM 即可 mbedtls_base64_encode(NULL, 0, b64_len, (unsigned char *)pcm_data, pcm_len); char *b64 calloc(b64_len 1, 1); mbedtls_base64_encode((unsigned char *)b64, b64_len 1, b64_len, (unsigned char *)pcm_data, pcm_len); return b64; } void upload_to_baidu(int16_t *pcm, size_t len) { char *b64_data pcm_to_base64(pcm, len); cJSON *payload cJSON_CreateObject(); cJSON_AddStringToObject(payload, format, pcm); cJSON_AddNumberToObject(payload, rate, 16000); cJSON_AddNumberToObject(payload, channel, 1); cJSON_AddStringToObject(payload, token, auth_token); cJSON_AddStringToObject(payload, speech, b64_data); char *json_str cJSON_PrintUnformatted(payload); cJSON_Delete(payload); free(b64_data); // 把 json_str 通过 HTTP POST 发送到识别接口 }建议每次上传 3~5 秒的音频也就是 48KB 到 80KB 的 PCM 数据。太短识别不完整太长 HTTP 响应时间超限。Base64 会把数据放大 1.37 倍ESP32 堆内一次性分配 100KB 以上容易失败建议用heap_caps_malloc分配 PSRAM 内存来做 Base64 转换。4.3 返回 JSON 解析与错误码处理识别结果通过标准的 JSON 结构返回核心字段是result数组和err_no错误码。解析时不只取第一项结果因为百度会按置信度排序多个候选实际工程里可以取前两条做本地纠错。void parse_baidu_response(const char *resp) { cJSON *root cJSON_Parse(resp); int err_no cJSON_GetObjectItem(root, err_no)-valueint; if (err_no 0) { cJSON *result cJSON_GetObjectItem(root, result); if (cJSON_IsArray(result) cJSON_GetArraySize(result) 0) { char *top_result cJSON_GetArrayItem(result, 0)-valuestring; handle_voice_command(top_result); } } else { handle_baidu_error(err_no); } cJSON_Delete(root); }错误码含义处理策略3300输入参数不正确检查 format/rate/channel 字段3301音频质量过差检查麦克风增益或环境噪声3302音频过长缩短上传时长到 5 秒内3304token 失效重新调用 token 接口刷新handle_baidu_error里对 3304 做特殊处理先把本地缓存的 token 清空再异步重新获取避免每次错误重试都失败。5. 离线与在线识别的切换策略和参数调优5.1 双链路协调先本地判定未达标再走云端离线识别和在线识别不应该由唤醒词简单切分而是用置信度做两级裁决。第一级离线识别如果置信度高于某个高阈值直接执行如果低于高阈值但高于低阈值则把同一段音频转发云端做二次识别低于低阈值则丢弃不触发网络请求。void process_command(int cmd_id, int16_t *audio_buf, size_t audio_len) { float confidence get_last_confidence(); if (confidence 0.75f) { // 离线高置信度直接执行 execute_local(cmd_id); } else if (confidence 0.35f) { // 低置信度走百度在线二次确认 upload_to_baidu(audio_buf, audio_len); } else { // 置信度太低大概率是误唤醒忽略 } }get_last_confidence在esp_sr_feed_srec返回命令词 ID 时同步记录内部的certainty值。在线二次确认后云端结果覆盖本地结果但也应该把云端的文本和本地的命令词做一次 Levenshtein 距离比对距离超过 2 就采信云端。5.2 唤醒词阈值与误唤醒的平衡唤醒阈值是最难调的参数低于 0.3 时电视声、敲门声都可能触发高于 0.7 时人站在两米外就唤不醒。动态门限是一种实用的折中方案在环境静音时提阈值检测到持续噪声时降阈值。void adjust_wake_threshold(float no_energy_db) { float threshold 0.5f; if (no_energy_db 30.0f) { // 安静环境提高阈值减少误唤醒 threshold 0.7f; } else if (no_energy_db 55.0f) { // 噪声环境降低阈值保证远场唤醒率 threshold 0.4f; } esp_sr_set_detection_threshold(srec_engine, threshold); }这里的no_energy_db是上一个音频分帧的平均能量单位是 dBFS。能量计算在音频采集任务里做每 32 帧更新一次不会额外消耗太多 CPU。注意阈值调整不要过于频繁每次调整至少间隔 2 秒否则会引入明显的抖动。5.3 端到端延迟预算与超时兜底本地唤醒到离线识别完成理想情况下在 250ms 内。走百度在线识别则要加上网络往返和云端处理时间通常在 2 秒内可接受。为了让整个链路稳定每个环节都要有超时保护。环节正常耗时超时值兜底动作唤醒检测50~150ms500ms重置状态机离线命令词识别100~200ms800ms转云端识别HTTP 上传 识别800~1500ms5000ms返回超时提示结果解析与执行10ms50ms丢弃结果超时器用一个单调时钟esp_timer_get_time实现不依赖 RTOS tick。网络识别里最容易忽略的是 DNS 解析超时可以在esp_http_client_config里设置skip_cert_common_name_check和具体的timeout_ms并把 DNS 服务器固定为路由器网关减少公网 DNS 的波动。6. 识别率骤降问题排查WiFi 射频耦合噪声的处理开启 WiFi 后识别率突然下降是 ESP32 语音项目里最容易误判为算法问题的情况。ESP32 的 2.4GHz 射频电路在发射时会通过 PCB 走线耦合到麦克风的时钟线或数据线。典型现象是识别率在 WiFi 关闭时接近 95%打开 WiFi 后掉到 60%而且唤醒词反复漏检。先做诊断把 I2S 读到的原始音频通过串口导出用 Audacity 看波形。射频耦合通常会表现为在音频波形顶部叠加一条高频毛刺带幅度约 20~50mV对应到数字域就是最高位附近持续跳动。这时先检查麦克风供电给 INMP441 的 VDD 加一颗 10uF 0.1uF 去耦电容并让 I2S SCK 走线避开天线区域。另一个手段是数据有效性检查。射频干扰严重时DMA 读到的数据可能直接变成全 0x00 或全 0xFF这类帧不能喂给识别引擎要在采集任务里过滤。bool is_invalid_audio_frame(int16_t *buf, size_t len) { int zero_count 0; int clip_count 0; for (size_t i 0; i len; i) { if (buf[i] 0) zero_count; if (buf[i] 32767 || buf[i] -32767) clip_count; } if (zero_count len * 0.9) return true; // 几乎全是静音 if (clip_count len * 0.5) return true; // 削顶失真 return false; }把过滤后的数据再送入识别引擎坏帧直接丢弃能恢复一部分识别率。前提是坏帧占比不超过 20%否则丢帧太多会导致音频断流反而影响唤醒。如果去耦和滤波都没解决考虑时序错峰。WiFi 的 beacon 每隔 100ms 左右会触发一次射频活动让 I2S 采样任务在 beacon 期间暂停采集等射频槽位结束再恢复。static volatile bool wifi_active false; void wifi_event_handler(void *arg, esp_event_base_t base, int32_t event_id, void *event_data) { if (event_id WIFI_EVENT_STA_START || event_id WIFI_EVENT_STA_CONNECTED) { wifi_active true; } } // 在 audio_capture_task 的 while 循环里 while (wifi_active) { vTaskDelay(pdMS_TO_TICKS(2)); }错峰会导致音频出现约 10ms 的间隙对唤醒检测的影响相对较小因为 ESP-SR 对连续 20ms 的音频丢失有一定的容错。这个方案适合对识别率要求高于实时性的场景比如语音遥控器、控制面板不太适合近场实时通话。射频耦合问题排查完之后把去耦电容和过滤逻辑固化到硬件设计里后续换麦克风型号时就不会再被同样的问题绊住。本文还有配套的精品资源点击获取