直接使用 WebRTC 的 webrtc::EchoCanceller3 是最现实的选择，因其是唯一经 Zoom、Teams 等大规模验证、开源且持续维护的工业级 AEC 实现，支持多采样率、纯 CPU 运行，并已集成 AGC 与降噪协同逻辑。
为什么直接用 WebRTC 的 webrtc::EchoCanceller3 是最现实的选择
自己从零写 AEC 在 C++ 里几乎不可行：它需要精确的延迟估计、非线性失真建模、双讲检测（DT）、近端语音保护，还要应对不同采样率、缓冲区抖动和硬件回声路径变化。WebRTC 的 EchoCanceller3 是目前唯一经过大规模真实场景（如 Zoom、Teams 底层）验证、开源且持续维护的工业级实现。它不依赖 GPU，纯 CPU 运行，支持 16kHz/48kHz，帧长可配（默认 10ms），且已内建 AGC 和噪声抑制协同逻辑。
实操建议：
- 不要尝试复现 NLMS 或传统子带 LMS —— 它们在现代设备（尤其是蓝牙耳机、USB 麦克风）上基本失效
- 直接拉取
webrtc/src/modules/audio_processing子模块（推荐用 Git Submodule，别 copy-paste） - 编译时务必启用
WEBRTC_ENABLE_WEBRTC_APM，否则EchoCanceller3被自动剔除 - 注意其输入要求：
capture（麦克风）和render（扬声器播放）必须严格时间对齐，误差 >5ms 就会导致回声残留
EchoCanceller3 初始化时最关键的三个参数
它不像普通滤波器那样“设个系数就行”，核心控制点就三个，设错一个，整条链路就哑火：
-
config.delay.default_delay_ms：初始延迟估计值。桌面端通常填50，移动端（尤其 Android OpenSL ES）建议100–200；填太小会误判双讲，填太大导致收敛慢 -
config.use_linear_aec：设为false（默认）。开启线性 AEC 仅用于调试，实际会削弱非线性残余抑制能力 -
config.multi_channel_render和multi_channel_capture：若你处理立体声渲染+单麦采集，必须显式设为true和false，否则内部通道混叠导致爆音
错误现象示例：Render audio buffer size mismatch: expected 480, got 960 —— 八成是通道数配置与实际输入不一致。
立即学习“C++免费学习笔记（深入）”；
如何把 EchoCanceller3 接进你的音频流水线（非 WebRTC 环境）
它设计上不绑定 WebRTC 网络栈，但依赖 AudioBuffer 数据结构和严格的生命周期管理。关键不是“怎么调用”，而是“怎么喂数据”：
- 每帧必须同时提供
render（播放侧 PCM，int16_t，interleaved）和capture（录音侧 PCM，int16_t，interleaved），长度相同（如 480 samples @ 48kHz = 10ms） - 调用顺序不能乱：
ProcessCaptureAudio()→ProcessRenderAudio()→ 再ProcessCaptureAudio()。漏掉一次ProcessRenderAudio，后续所有capture都会累积回声 - 不要跨线程共享
EchoCanceller3实例 —— 它内部状态非线程安全；如需多路，每个流独立 new 一个 - 如果用 PortAudio 或 RtAudio，确保回调周期严格等于 AEC 帧长（例如 10ms），否则需自行做重采样或丢帧补偿
简单初始化片段：
auto aec = webrtc::EchoCanceller3::Create(config, sample_rate_hz, num_render_channels, num_capture_channels); auto audio_buffer = std::make_unique<webrtc::AudioBuffer>(sample_rate_hz, num_render_channels, sample_rate_hz, num_capture_channels, sample_rate_hz); // … 每次回调中： audio_buffer->CopyFromRender(render_data, num_render_channels, sample_rate_hz); aec->ProcessRenderAudio(audio_buffer.get()); audio_buffer->CopyFromCapture(capture_data, num_capture_channels, sample_rate_hz); aec->ProcessCaptureAudio(audio_buffer.get()); // 输出结果在 audio_buffer->split_bands_f(0)
常见崩溃和静音问题排查路径
出问题基本就三类地方，按优先级检查：
- 内存越界：
EchoCanceller3对AudioBuffer内存布局极其敏感。用 ASan 编译，重点看AudioBuffer::CopyFrom*是否越界写入 —— 特别是当num_channels传错时 - 采样率不匹配：
ProcessRenderAudio和ProcessCaptureAudio输入的 buffer 必须与构造时sample_rate_hz一致，哪怕只差 1Hz（如 47999Hz）也会触发断言失败 - 静音输出：大概率是
ProcessCaptureAudio返回前，audio_buffer->split_bands_f(0)没被正确读取；或者你误用了audio_buffer->channels_f(0)（那是未处理原始数据） - Windows 上
__declspec(dllimport)符号缺失：若静态链接 WebRTC，确保所有webrtc::apm相关 .lib 全部加入链接器输入，缺一个就会 unresolved external
最易被忽略的一点：AEC 必须在首次收到 render 数据后，再等至少 200ms 才能稳定。冷启动阶段看到回声不是 bug，是正常收敛过程 —— 别急着改参数。
