ESP32语音采集失败后别让旧音频继续过关
语音设备最难排查的故障，有时不是“完全没声音”，而是流程看起来一直正常。采集回调照常返回，算法继续收数据，网络也能发包。可这次送进去的音频，真的读成功了吗？
如果程序先把一块缓冲标成有效，再去问驱动读取是否成功，失败就可能被包装成一次正常采集。缓冲里留下的旧内容，甚至一次失败读取已经改写的局部内容，都有机会跟着“有效长度”一起过关。
下面从一块 ESP32-S3 语音核心板出发，把这个边界拆开。电路负责把声音送到正确入口，软件则必须证明这次拿到的数据可以交给后级。两件事缺一件，后面的降噪和识别都不好定位问题。
先认准声音进来的那条线
这里核对的是 CoreBoard V1.0。它把采集和播放分给不同器件，麦克风通路进入 ES7210，播放走 ES8311，再送到 NS4150B 功放。不能因为看见一颗“音频 Codec”，就把所有录音问题都归到 ES8311。
图1 由真实 MCU 图页重新导出的 I2S 局部，版本为 V1.0。
这几个信号要按主控的方向读。MCLK 是 GPIO42，BCLK 是 GPIO40，WS 是 GPIO39；GPIO41 把播放数据送往 ES8311，GPIO15 接收 ES7210 的采集数据，GPIO4 控制功放。控制总线使用 SCL GPIO1、SDA GPIO2。
同一套 BSP 也支持 V1.2，但那一版把采集输入和功放控制分别改成了 GPIO3、GPIO15。板子是 V1.0，配置却选了 V1.2，GPIO15 就会承担完全不同的角色。排查前应先对照板号和 CONFIG_BSP_PCB_VERSION_V1_0，而不是盯着软件里的 DIN 名字猜接法。
图2 U5 的数字接口局部。SDOUT1/TDMOUT 接到 I2S_DI，这里的 DI 是主控的数据输入。
还有一个容易误解的地方。电路中的 OUTP/OUTN 从 ES8311 输出，一路送到功放输入，另一路经阻容网络回到 ES7210 的 ADC_MIC3_P/N，作为回声消除的参考通路。它取自功放之前，不是把扬声器端的 VOP/VON 直接接回 ADC。参考通道也不等于又多了一只环境麦克风。
在 PCB 上先确认板面和接口位置，再去找软件入口。下面两图来自同一个 V1.0 工程，只用于板面定位和版本核对；本次没有修改走线或元件。
图3 PCB 顶面。下载、导出与软件核验使用同一 CoreBoard V1.0。
图4 底面图层仍按从顶面向下看的方向显示，因此底层丝印反向，不能据此倒推焊接方向。
报错为什么没有挡住这块数据
在固定版本的 audio_processor.c 中，录音入口回调先写 load->valid_size = wanted_size，随后调用 esp_codec_dev_read()，最后返回 wanted_size。中间的驱动返回值没有参与判断。
这相当于在货物到齐之前，先签了“全数收到”。假设这次想要128字节，缓冲原本保留着上一轮内容；驱动这次失败，回调依旧告诉后级128字节有效。若失败发生在部分缓冲已被改写之后，这块数据还可能是新旧内容的混合。
这里要分清三个量。
buf_length是缓冲容量，回答“最多装多少”。valid_size是这一次可交付的数据长度，回答“本次确认拿到多少”。esp_codec_dev_read()的返回值是状态码，回答“调用是否成功”。成功值是ESP_CODEC_DEV_OK，不能把某个正的错误码理解成读取字节数。
GMF 端口又有自己的约定。核对的 v0.6 实现以非负返回判断 acquire 成功，载荷长度放在 payload 里。因此原回调返回128，也会落进成功分支。修订后可以返回 ESP_GMF_IO_OK，同时通过 valid_size 明确交付长度。
问题不在于128这个数特殊，而在于驱动成功与数据交付之间缺了一道判断。
把有效长度留到最后再提交
改法很小，顺序却很关键。先撤销上一轮的有效状态，检查句柄、缓冲和容量，再读取；只有驱动明确成功，才写入本轮有效长度。
下面是完整的检查函数。放到已有 esp_codec_dev.h、esp_gmf_payload.h 等声明之后即可。函数指针是为了在主机测试中注入错误，实际板端仍调用原来的 Codec API。
/* SPDX-License-Identifier: MIT */
/* Include after esp_codec_dev.h and esp_gmf_payload.h. */
typedef int (*codec_read_fn)(esp_codec_dev_handle_t, void *, int);
static int checked_record_read(esp_codec_dev_handle_t dev,
esp_gmf_payload_t *load,
int wanted_size, codec_read_fn read_fn)
{
if (load == NULL) {
return ESP_GMF_IO_FAIL;
}
load->valid_size = 0;
load->is_done = false;
if (dev == NULL || load->buf == NULL || read_fn == NULL ||
wanted_size <= 0 || (size_t)wanted_size > load->buf_length) {
return ESP_GMF_IO_FAIL;
}
int status = read_fn(dev, load->buf, wanted_size);
if (status != ESP_CODEC_DEV_OK) {
return ESP_GMF_IO_FAIL;
}
load->valid_size = (size_t)wanted_size;
return ESP_GMF_IO_OK;
}
然后在 audio_processor.c 中替换原有同名回调，不能把新旧两份定义一起留下。
static int recorder_inport_acquire_read(
void *handle, esp_gmf_payload_t *load,
int wanted_size, int block_ticks)
{
(void)handle;
(void)block_ticks;
return checked_record_read(
audio_manager.rec_dev, load,
wanted_size, esp_codec_dev_read);
}
valid_size = 0 要在参数检查和驱动调用之前执行。否则上轮成功的128字节，还可能残留在这次失败的 payload 上。实时录音中的 is_done 也先清为 false，读取失败不能被解释成正常流结束。
容量检查同样不能省。先拒绝零和负的 wanted_size，再转为 size_t 比较，避免负数转换后变成巨大无符号数。容量不够就返回错误，不应在这个边界悄悄截短读请求，因为下游可能按完整音频块解释数据。
失败时不需要靠清空整个缓冲来“修好音频”。缓冲仍可能含有旧字节，但它不再被声明为有效。真正的约束是后级必须遵守错误返回和有效长度。若其他任务绕过接口直接读这片内存，这个函数也不能替它建立并发安全。
另外，block_ticks 在这个回调中没有传给 Codec API。本次修改没有增加超时能力，也没有决定设备关闭后的重启策略。把错误归一化为 ESP_GMF_IO_FAIL 能挡住假成功；定位具体驱动错误时，可在失败分支增加限频日志，记录原始 status，不应把它直接当成 GMF 字节数返回。
让失败主动发生一次
只跑成功路径，看不出这处修改有没有用。验证时，先把128字节全部填成 0xA5，再用一个假驱动只改写前8字节为 0x3C，随后返回错误。这个输入故意模拟“缓冲已经被碰过，但本次操作失败”的情况。
测试驱动的核心如下，和上面的函数使用同一份真实 GMF payload 声明。
#include <assert.h>
#include <string.h>
static int fail_after_prefix(
esp_codec_dev_handle_t dev, void *dst, int size)
{
(void)dev;
(void)size;
memset(dst, 0x3c, 8);
return -1; /* 注入非零失败状态 */
}
/* 在主机测试或专门的测试入口中执行 */
static void test_failed_read(esp_codec_dev_handle_t dev)
{
uint8_t buf[128];
memset(buf, 0xa5, sizeof(buf));
esp_gmf_payload_t p = {
.buf = buf,
.buf_length = sizeof(buf),
.valid_size = sizeof(buf),
.is_done = true,
};
int rc = checked_record_read(
dev, &p, sizeof(buf), fail_after_prefix);
assert(rc == ESP_GMF_IO_FAIL);
assert(p.valid_size == 0 && !p.is_done);
assert(buf[0] == 0x3c && buf[127] == 0xa5);
}
这里传入的 dev 必须是非空测试句柄。假驱动不访问设备，所以不需要真的发起 I2S 读取；在主机测试里可用局部对象地址充当句柄。不能把这个假驱动留在正式录音链路中。
图5 故障注入结果与缓冲示意。图中的字节来自合成输入，不是麦克风波形或板端实测。
同样的错误输入，原回调得到 ret=128, valid=128；检查函数得到 ret=-1, valid=0。前8字节依旧被改过，后120字节依旧保留 A5，但整块数据不会再以“本次有效音频”的身份交付。
主机验证还覆盖了成功读取、请求超过容量、零长度、负长度、空指针和空句柄；对成功及多种错误状态做了10000次交替，检查上一轮的有效长度不会泄漏到下一轮。特意加入正数128作为错误状态，确认它不会因为“看起来像长度”就被当成成功。
这些测试证明的是回调的提交规则，不是识别率提升，也不是整机故障已经消失。真实驱动未必会按这里的方式部分改写缓冲；故障注入用于检验接口面对这种失败时仍能守住边界。
上板时还要验收什么
集成位置是 core/brookesia_core/ai_framework/agent/audio_processor.c。固定源码中，这个回调注册到包含 ai_afe 的录音流水线；启用按键对话等其他录音路径时，必须另外确认是否经过同一入口，不能只替换函数就宣称所有模式都覆盖了。
获取下方固定提交的完整仓库，在原有 products/speaker 工程中修改，使用工程要求的 ESP-IDF 5.5或兼容环境，选择实际板卡版本后重新构建。这里没有提供可直接烧录的固件，也没有完成整套目标工程构建，不能用主机测试通过代替 idf.py build。
板端验收可分三步。先确认成功路径持续给出正确长度，再在专门测试配置中注入一次错误，观察 GMF 任务的错误状态和后级是否停止消费该块数据；最后恢复真实驱动，核对停止、关闭、重开设备的生命周期。出现错误后是重建流水线还是提示用户重试，应由业务层统一处理，别在采集回调里无限重试拖住音频线程。
测量电路时也沿着信号方向走。控制总线能访问，不代表采集时钟和数据一定正确；有 MCLK/BCLK/WS，也不代表本次读缓冲成功。先把板号、数字接口和软件返回值逐层对齐，排错才不会在“换一颗麦克风试试”之间打转。
资料与验证范围
硬件图来自 Espressif 的 ESP-VoCat 喵伴 CoreBoard V1.0，项目及 EDA 标注 GPL-3.0。本文重新从对应 EDA 工程导出原理图与 PCB，做局部裁剪、缩放及 PCB 亮度调整，未改变连线、元件或数值。工程入口及许可见 https://oshwhub.com/esp-college/echoear 。
软件核对版本为 esp-brookesia 提交 b22c488f50bafe53342c8e171081bd736396ef58，回调所在文件版权为2025 Espressif Systems (Shanghai) CO LTD，Apache-2.0。完整源码入口 https://github.com/espressif/esp-brookesia/tree/b22c488f50bafe53342c8e171081bd736396ef58 ，查看 products/speaker 及上述回调路径。
GMF 端口和 payload 参照 v0.6提交 ce2390f30bd12e8cdc2684a01b9ac5deb61e3c21，https://github.com/espressif/esp-gmf/tree/ce2390f30bd12e8cdc2684a01b9ac5deb61e3c21 。相关代码受 Espressif Modified MIT 约束，仅用于乐鑫产品，复用时须保留其版权及完整许可。Codec API声明见 https://github.com/espressif/esp-adf/blob/master/components/esp_codec_dev/include/esp_codec_dev.h 。
本文新增检查函数及故障注入示例按 MIT 许可提供；第三方文件仍遵循各自许可。已完成使用真实 GMF 结构声明的 C11 主机编译和故障注入验证，未完成目标整机编译、烧录和声学实测。
技术交流，欢迎关注微信公众号：美男子玩编程。
