简介面向实时音视频开发者的WebRTC音频3A可编译代码参考包聚焦自动增益控制AGC、自动噪声抑制ANS与回声消除AEC三大核心算法。这三项技术是保证实时通话音质的关键AGC动态调整麦克风增益以保持音量平稳ANS过滤背景噪声以提升语音清晰度AEC则消除扬声器回授避免通话回声。资源共249个文件压缩包整体约7.49MB包含ANS、AGC等模块的C/C源文件、头文件、CMake构建脚本以及用于验证效果的WAV测试音频同时保留编译中间文件与产物便于对照检查构建流程。已有342人学习浏览。直接提供可编译的AGC、ANS、AEC模块实现配合标准构建配置与测试音频读者可在本地编译运行直观观察算法对不同音频输入的实时处理效果。WebRTC上游代码库更新频繁整理好的可编译版本能够省去自行拉取、适配的繁琐步骤适合学习研究核心算法或在此基础上做二次优化。1. 为什么要让 webrtc audio 3a 代码真正能编译先得把它当工程对待很多人拿到 webrtc audio 3a 代码的第一反应是把modules/audio_processing目录直接拖进自己的工程然后祈祷编译一次通过。结果通常是几百个编译错误从缺少 absl 头文件到rtc_base/logging.h找不到最后只能放弃。标题里真正关键的不是“3A”这三个字母而是“可编译”三个字。较新的音频处理模块已经不是一个孤立算法它带着日志、线程、SIMD 指令选择、10ms 帧对齐和基础库依赖直接 Copy-Paste 必然翻车。这篇文章会从模块边界讲起给你一条能编译、能运行的落地路径再给出三套参数模板和五个现场级排查经验。适合想把 AEC、AGC、ANS 集成进自己采集链路的工程师也适合拿这块代码当算法参考的开发者。2. WebRTC 音频 3A 的调用关系AEC、AGC、ANS 各自管哪一段2.1 三个字母背后的信号链路先别急着敲编译命令把信号链路摆清楚更重要。AEC 解决的是声学回声扬声器播放出来的声音被麦克风收回变成一个延迟且被房间反射扭曲的副本。AGC 解决的是响度漂移说话人离麦克风忽远忽近音量也跟着忽大忽小。ANS 解决的是稳态噪声风扇、空调、交通噪音这些背景声在语音间隙里显得尤其刺耳。这三件事在 WebRTC 里被打包成一个叫 AudioProcessing 的模块顺序固定地串在采集端。这条链路的常见排序是 AEC 在最前AGC 和 NS 在后。如果先做 AGC回声和近端信号一起被放大AEC 的误差信号里会混入更多非线性成分自适应滤波器收敛更难。如果先做 NS降噪会把参考信号里的细节也抹掉一部分AEC 对回声路径的估计一样会受影响。所以你在参考代码里会看到ProcessStream入口先处理 AEC 相关逻辑再把输出交给增益控制和降噪。这个顺序是多年工程调试的结果不是拍脑袋定的。WebRTC 里现在主推的 AEC3和教科书里的 NLMS 差别很大。它内部有延迟估计、双讲检测、多级自适应滤波器和一套抑制增益计算。换句话说它不是简单地把回声信号“减掉”而是在检测到双讲时会主动收住滤波器更新避免把对方说话的声音一起消掉。这也是为什么有人尝试用一段简化的 LMS 代码替换 WebRTC 的 3A 之后效果反而明显变差。AEC3 的复杂度主要就集中在这里而不是在某个单独的滤波公式上。整个处理过程以 10ms 为一帧对齐。48kHz 采样率下一帧是 480 个采样点16kHz 下是 160 个。AudioFrame里要同时设置sample_rate_hz()、num_channels()、samples_per_channel()这三个字段只要和 APM 配置不一致运行时就会直接 CHECK 失败。这个约束后面会反复遇到在线调试时几乎一半的崩溃都跟它有关。2.2 为什么独立项目也敢选 WebRTC 的 3A做自研音频链路的人大多数最后还是选择把 WebRTC 的 3A 抠出来而不是自己从零实现。第一个原因是工作量单说 AEC3 的双讲检测和延迟估计没有半年以上音频信号处理功底很难做到生产可用。第二个原因是维护性上游持续在修边界问题比如蓝牙设备的延迟抖动、外接声卡的时钟漂移自己实现这些经验积累太慢。第三个原因是许可WebRTC 代码对商用集成友好很多会议终端、直播软件、耳机产品的底层都有它的影子。很多人以为“最新参考代码”是去网上找一个别人打包好的 3A 编译包我建议反过来直接面对上游源码主线。打包好的旧代码往往停留在一两年前的版本那时候 AEC3 还没有后来加进去的延迟鲁棒性补丁AGC 也还是老式的模拟增益风格。旧代码或许能顺利编过但遇到现在常见的蓝牙卡顿、USB 音频延迟抖动很多问题是旧代码里根本没有修复过的。所以后面所有的编译步骤都按较新的主线源码来写。2.3 模块最小依赖先认清要拿哪几块WebRTC 的音频 3A 不是一个孤立目录。modules/audio_processing只是核心它的头文件会引用到common_audio、api/audio、rtc_base和system_wrappers。真要动手先对下面这张表心里有数。目录 / 模块作用能不能砍modules/audio_processingAPM 核心实现AEC3、AGC、NS 都在这里不能common_audio重采样、音频 buffer、滤波工具不能但可以裁剪到具体 .ccapi/audioAudioFrame、ProcessingConfig 等公共接口不能rtc_base日志、线程、智能指针工具大部分要留但不用全量system_wrappersCPU 特性检测、时间戳通常需要音频设备层、视频模块采集播放设备、视频编解码能砍编译时直接关掉看到这张表你应该能理解为什么网上总有人说 WebRTC 的 3A 没有“轻量版”。就算只处理 10ms 帧AudioProcessing 内部也依赖 rtc_base 的日志、absl 的参数解析、system_wrappers 的 CPU 指令集检测。想做到单文件集成只有两种可靠办法一是用上游的 GN 构建让构建系统把依赖关系算清楚二是先编出静态库再给自己的应用封装一层 C 接口。第二种在集成阶段更省事但前提是你能先把目标编出来。我一般会先用第一条路线把代码跑通确认 API 行为和参数效果再考虑第二条路线做产品集成。提示GN 生成工程时如果网络环境不好第三方依赖下载可能失败。先确认依赖缓存完整再开始编译避免卡在中间步骤。3. 搭一个能编译的最小工程从上游源码到 10ms 音频帧跑通3.1 上游构建路线GN Ninja 是最稳的起点GN 是 WebRTC 源码自带的构建系统生成器Ninja 负责实际编译。不要因为没听过 GN 就绕开它在大型 C 工程里很成熟。拿到源码后先别急着敲命令打开源码根目录下的 BUILD.gn找到音频处理模块对应的构建目标。不同版本里这个目标可能叫audio_processing或webrtc_audio_processing以文件里实际写的为准。# 在 WebRTC 源码根目录执行 gn gen out/audio \ --argstarget_oslinux is_component_buildfalse \ rtc_include_internal_audio_devicefalse \ rtc_enable_protobuffalse # 编译音频处理模块 ninja -C out/audio audio_processing这里几个参数按实际需要调。target_os决定目标系统做交叉编译时改成android或iosis_component_buildfalse表示编译成静态库产物方便带走rtc_include_internal_audio_devicefalse会砍掉桌面端的音频设备采集实现因为我们要的是信号处理模块不是录音放音的底层驱动rtc_enable_protobuffalse能去掉调试转储用的 protobuf 依赖省掉一大块第三方代码。如果在移动端交叉编译通常还要加rtc_build_with_neontrue让 AEC3 的 FFT 走 NEON 加速。第一次编这个目标即使只编译音频模块也会连带把 common_audio、rtc_base、absl 这些编一遍。耗时从几分钟到十几分钟不等取决于机器性能。这段时间不要以为命令卡住了只要 ninja 还在打印进度就让它跑完。成功后你会得到一个静态库这就是后续集成到业务工程的基础。3.2 CMake 手写路线的边界骨架能看别指望一次编过第二种路线的风险在于源文件列表不可能一次写全。AEC3 的实现分散在modules/audio_processing/aec3/下的几十个文件里而且不少文件会 include 到 common_audio 和 rtc_base 的内部头文件。手写一个 CMakeLists 把依赖列清楚是能做到的但前提是你已经知道完整依赖是什么。下面这段代码只展示结构不是拿来就能编的完整版本。cmake_minimum_required(VERSION 3.16) project(audio_3a_standalone CXX) set(CMAKE_CXX_STANDARD 17) set(CMAKE_CXX_STANDARD_REQUIRED ON) # 假设 WebRTC 源码放在 third_party/webrtc 下 set(WSRC ${CMAKE_CURRENT_SOURCE_DIR}/third_party/webrtc) include_directories( ${WSRC} ${WSRC}/api ${WSRC}/modules/audio_processing/include ${WSRC}/common_audio ${WSRC}/rtc_base ) # 只供演示源文件列表必须按 BUILD.gn 的 deps 补全 set(APM_SOURCES ${WSRC}/api/audio/audio_frame.cc ${WSRC}/modules/audio_processing/audio_processing.cc # ... 这里至少有几十个 .cc ) add_executable(audio_3a_demo demo/main.cc ${APM_SOURCES}) target_link_libraries(audio_3a_demo PRIVATE absl::strings)注意代码里把源码根目录也加入了 include 路径这是为了让#include modules/audio_processing/include/audio_processing.h能按 WebRTC 自己的头文件习惯找到路径。target_link_libraries 里的 absl还需要你的 CMake 环境额外提供如果环境里没有就得把 absl 源码也引入工程依赖会进一步膨胀。所以我更建议第一次编的时候别自己写 CMake。等 GN 编过之后用 ninja 的-t commands导出每个目标文件的实际编译命令或者生成 compile_commands.json再反过来填 CMake 的源文件列表。一个反常识的排查经验是源文件列表漏了报错往往不是漏文件本身而是在链接阶段冒出一个奇怪的 undefined reference比如重采样函数找不到。你会误以为是算法库的问题其实只是 common_audio 没有编进来。3.3 最小编译后的调用代码AudioProcessingBuilder 与 10ms 帧拿到能链接的库之后上面这段代码是最小的调用骨架不是完整的生产代码。它把 APM 生命周期讲清楚了Create 返回一个带默认配置的实例ApplyConfig 要在开始处理之前调用ProcessStream 处理采集端近端数据ProcessReverseStream 喂播放端参考数据。AEC 只有在两边数据都持续喂入时才会收敛。#include memory #include modules/audio_processing/include/audio_processing.h #include api/audio/audio_frame.h std::unique_ptrwebrtc::AudioProcessing CreateApm( bool enable_aec, bool enable_agc, bool enable_ns) { webrtc::AudioProcessingBuilder builder; auto apm builder.Create(); webrtc::AudioProcessing::Config config; config.echo_canceller.enabled enable_aec; config.gain_controller1.enabled enable_agc; config.noise_control.enabled enable_ns; apm-ApplyConfig(config); return apm; } void ProcessOneFrame(webrtc::AudioFrame* capture_frame, webrtc::AudioFrame* render_frame, webrtc::AudioProcessing* apm) { // 播放端参考信号要先喂 if (render_frame ! nullptr) { apm-ProcessReverseStream(render_frame); } // 采集端近端信号从麦克风来 apm-ProcessStream(capture_frame); }代码里的config.gain_controller1是较新代码里的常见字段名不同版本可能被改写成gain_controller2或别的结构。拿到源码后先打开audio_processing.h看一眼Config里实际有哪些字段不要照抄老博客。字段名变化是版本升级里最折腾人的地方但核心链路是稳定的。AudioFrame的构造和使用是编译后最容易崩的地方。在 48kHz 双声道下一条 10ms 帧的samples_per_channel必须是 480num_channels必须是 2。如果采集设备给的是 16kHz 单声道就要先做重采样或者把 APM 的格式配置改成 16kHz。APM 会按格式参数去校验内部 buffer任何一边不匹配Debug 版本直接 CHECK 失败Release 版本可能产生不可预测的噪声。另外真实工程里AudioFrame的数据指针最好做到 16 字节对齐尤其是在开了 SIMD 的情况下某些崩溃就来自未对齐访问。3.4 编译参数与宏SIMD、C 标准和调试开关编译参数直接影响 3A 的实时性和可调试性。AEC3 在纯 C 模式下也能跑但 48kHz 双声道下一个不带 SIMD 的 ARM 核心可能会被吃满开启 NEON 后帧均耗时可能降到原来的三分之一。所以编译阶段就把指令集选对比后面在代码层面做优化要省力得多。开关 / 宏作用建议WEBRTC_APM_DEBUG_DUMP打开 APM 调试转储记录每帧中间结果调试时开发布前关-marchnative 或 -msse4.2让 AEC3 的 FFT 走桌面端 SIMD目标机支持就开rtc_build_with_neon移动端 NEON 加速交叉编译移动端时开-DNDEBUG关闭 CHECK 断言发布时开但保留关键日志第一次跑测试时建议把WEBRTC_APM_DEBUG_DUMP打开。它能把每帧的回声估计、滤波器系数、AGC 增益曲线写进一个转储文件后面用脚本解析就能看到参数调整对内部状态的影响。没有这个开关3A 的调试基本全靠听感定位问题会慢很多。4. 三套可抄的参数模板通话、直播采集、离线 WAV 批处理4.1 全双工通话场景AEC 优先参考信号必须从播放器拿全双工通话是 3A 最经典的场景。我的常见模板是AEC 开NS 低档AGC 用自适应数字增益。参考信号必须从播放器缓冲里取原始 PCM如果播放之后再用麦克风在空气中录一遍等于把整个声学路径又绕回输入端AEC 永远收敛不了。webrtc::AudioProcessing::Config config; config.echo_canceller.enabled true; config.noise_control.enabled true; config.noise_control.level webrtc::AudioProcessing::Config::NoiseControl::Level::kLow; config.gain_controller1.enabled true; apm-ApplyConfig(config);这里 echo_canceller 用默认模式适合大多数桌面和嵌入式通话。移动端有时要把 mobile_mode 置为 true它会限制滤波器阶数用一点回声抑制性能换取 CPU 占用下降。如果遇到蓝牙设备的声音延迟抖动重点查 AEC3 的延迟估计相关配置较新代码里这块默认行为有调整但效果和具体设备强相关需要实测。4.2 直播和演唱采集没有参考信号就别开 AEC直播场景和通话最大的区别是很多主播只开麦克风不放伴奏也不开监听播放端根本没有参考信号。这种情况下 AEC 开着反而是负优化双讲检测会来回误判所以我习惯直接把echo_canceller.enabled置为 false只保留 AGC 和 NS。NS 档位可以提到中高但要注意高灵敏度麦克风会把呼吸声也当噪声降噪太强时人声高频泛音会受损。如果直播里有伴奏和监听回放播放器就要把伴奏 PCM 同步喂给 ProcessReverseStreamAEC 才能消掉伴奏窜入麦克风的部分。这种场景下 AGC 别用太激进的压缩compression_gain_db从默认 9dB 往下调到 6dB 左右保留人声动态同时打开 limiter防止主播突然贴近麦克风导致爆音。4.3 离线 WAV 批处理帧连续是关键声道不能搞反离线批处理常用于回归测试和参数调优。我一般录一个双通道 WAV左声道是麦克风原始近端信号右声道是参考信号然后逐 10ms 帧送给 APM输出写回单声道 WAV。最典型的错误是声道搞反AEC 的参考必须是播放端的数据近端必须是麦克风的数据一旦交换滤波器会试图把整个近端信号都抵消掉。离线处理同样要保持状态连续不能每帧重建 APM。有人写测试脚本时图省事对每个 10ms 块都创建一个新实例结果 AEC 永远不收敛ERLE 是负数。正确做法是一个 APM 实例从头处理到尾中途不要改配置。4.4 三套模板对照与关键参数表场景AECAGCNS最容易踩的坑全双工通话开自适应数字增益低档参考信号没从播放器取直播 / 演唱有伴奏才开compression_gain_db 6dB 左右中高档无参考时还强行开 AEC离线 WAV 批处理按场景按场景按场景每帧重建 APM、声道接反这张表可以当抄作业的起点但不能当终点。同一个产品在不同麦克风、不同设备上的表现差异很大。关键不在于抄到哪个参数而在于你有没有把 debug dump 开起来。WebRTC 的 APM 会把每帧的回声估计、增益曲线和降噪后频谱写进文件解析出来就能看到参数变化对内部状态的影响。否则参数调整基本就是盲调只能靠耳朵来回试。5. 避坑编译与效果现场的五个案例从 ASSERT 崩溃到 AGC 忽大忽小5.1 现象编译错误刷了几百行头文件缺失刚拿到较新代码那天最容易看到的就是编译错误刷屏。从缺 absl 头文件到rtc_base/logging.h找不到有人甚至怀疑源码包是不是损坏了。原因新版 APM 的头文件里大量使用 absl 类型和 rtc_base 工具直接把手写的工程和源码目录拼在一起依赖链必然会断。解决先用 GN 生成 ninja 工程让构建系统把 absl 和 rtc_base 的路径自动导出。如果坚持手写 CMake就先给 absl 建一个能用的 CMake 导入再从头文件里逐个确认用了哪些子库。不要靠猜每猜一次就会多花半小时。5.2 现象依赖列表像雪球一样越滚越大编完 audio_processing发现还要编 common_audio编完 common_audio又发现 rtc_base 里引了线程模块线程模块又依赖更多系统 API。看起来像死循环。原因WebRTC 的模块边界是按 BUILD.gn 的 target 划分的不是按源码目录划分。你用了核心模块它列在 deps 里的所有依赖都得编。解决打开 BUILD.gn看 audio_processing 这个 target 的 deps 列表照着这个列表去组织自己的构建工程。同时关掉rtc_include_internal_audio_device和rtc_enable_protobuf这类与信号处理无关的开关能少掉一大半第三方依赖。5.3 现象编译过了一运行就 CHECK failed编译顺利通过但程序一启动就报Check failed: samples_per_channel 480之类的错误。原因APM 使用 48kHz 处理而测试代码给了一个 16kHz 的 AudioFrame一帧只有 160 个采样。采集设备确实是 16kHz但这里缺了重采样环节。解决把 APM 的 ProcessingConfig 设成和输入一致或者在送进 APM 之前用 common_audio 里的重采样器把 16k 升到 48k。还要检查声道数单声道帧不能喂给双声道配置这个错误通常在 iOS 和 Android 的采集回调里特别常见。5.4 现象回声消掉了伴奏和人声一起被挖掉一块在某音乐播放场景下AEC 开了之后回声被压住了但歌曲里的歌声和伴奏也被削弱听感像被人挖掉一块。原因参考信号和实际播放信号没有对齐或者 AEC 在双讲段仍然更新滤波器导致它把近端伴奏也当成回声来抵消。抑制增益开得过猛也会加重这个问题。解决先看延迟估计日志确认参考与近端的延迟在合理范围把双讲检测的灵敏度调高仍然误消的话就降低抑制增益或者把 NS 降一档。音乐场景下3A 不是越强越好过度抑制比不消回声更难听。5.5 现象AGC 让人声忽大忽小打击乐一段声音就被压下去AGC 开启后人声前后音量不稳鼓点一来整段音量被瞬时压低。原因AGC 在波形能量高的地方会快速调小增益音乐里打击乐节奏强、峰值突出会反复触发增益调整。另外如果 AGC 放在 AEC 前面回声能量也会参与计算增益变化会更夸张。解决调低 compression_gain_db限制最大增益变化步长开启 limiter 防止过冲。把增益变化时间常数调慢一些让人耳的感知更自然。如果产品里还有另一层自动响度控制建议关掉一重避免双 AGC 互相打架。6. 把双通道 WAV 变成 3A 效果的量化证明用 ERLE 判断回声压得干不干净验证 3A 效果不能只靠耳朵我常用的第一道量化指标是 ERLE回声返回损耗增强。它衡量 AEC 把线性回声压掉了多少 dB定义是近端输入功率和误差输出功率之比。注意 ERLE 只对 AEC 有效AGC 和 NS 的效果要另外看响度曲线和残留噪声。import wave import numpy as np def read_wav(path): with wave.open(path, rb) as w: sr w.getframerate() data np.frombuffer(w.readframes(w.getnframes()), dtypenp.int16) ch w.getnchannels() return sr, data.reshape(-1, ch) # mic_raw.wav 是原始近端apm_out.wav 是 3A 处理后输出 sr, rec read_wav(mic_raw.wav) sr, out read_wav(apm_out.wav) n min(len(rec), len(out), sr // 10) # 只看前 1 秒 frame_len sr // 100 # 10ms 一帧 erle_list [] for i in range(0, n - frame_len, frame_len): ref_p np.mean(rec[i:i frame_len].astype(np.float64) ** 2) out_p np.mean(out[i:i frame_len].astype(np.float64) ** 2) if ref_p 1e-6 and out_p 1e-6: erle_list.append(10 * np.log10(ref_p / out_p)) print(median ERLE: %.2f dB % np.median(erle_list))脚本里我只看前 1 秒避免长时间统计把单讲段和双讲段糊在一起。一般的经验线是单讲时 ERLE 中位数能到 20dB 以上双讲段掉到 5 到 10dB 也算正常。如果看到中位数不到 10dB先检查参考信号有没有对齐查了一圈还是低就把 debug dump 打开看 AEC 滤波器是否真正收敛。我现在每调一组参数都会把左右声道 WAV 和这个脚本放在同一个目录里先出数字再去听避免又回到盲调的状态。希望帮到你。本文还有配套的精品资源点击获取