简介：本资源为可编译的WebRTC音频3A参考代码包，面向从事实时音视频开发的工程师与学习者，聚焦自动增益控制（AGC）、自动噪声抑制（ANS）与自动回声消除（AEC）三大核心算法的实现，可用于视频会议、在线教育、语音聊天等场景的音质优化与二次开发。压缩包共249个文件，约7.49MB，以sample示例、cmake构建脚本、h头文件、make编译文件、c与cc源码为主，另含wav音频样本、pcm数据及少量bin、txt说明，覆盖音频采集、处理与播放的完整链路，便于本地编译验证。目前已有342人学习下载。代码结构清晰，包含噪声抑制、增益控制等模块的参考实现，读者可据此理解3A算法在WebRTC中的工程落地方式，对照调试并移植到自有项目，适合希望深入掌握实时音频处理的中高级开发者。

1. WebRTC Audio 3A 代码到底在解决什么问题

如果你正在做实时语音通话、在线会议、互动课堂或者语音对讲，一定绕不开 WebRTC 的音频 3A——AEC（回声消除）、AGC（自动增益控制）、NS（噪声抑制）。很多人第一次接触它，是搜到一堆散落的源码片段，编译报错、链接缺符号、跑起来没效果，最后卡在“代码能跑但声音还是废的”这一步。这篇笔记要讲清楚的，就是一套可编译、可复现、贴近最新参考实现的 WebRTC audio 3A 代码该怎么落地：从模块拆分、编译依赖、参数配置，到实际接入音频流水线时最容易翻车的地方。适合两类人：一是想把 3A 从 WebRTC 大工程里单独抽出来用的嵌入式/客户端工程师，二是需要在自己的音频链路里验证 3A 效果、调参对比的算法同学。核心不是背 API，而是搞明白每一帧音频进来之后，AEC、NS、AGC 各自动了什么手脚，以及为什么你的编译环境和参数顺序会让效果天差地别。

2. WebRTC 3A 的模块边界与可编译拆分思路

2.1 为什么不能直接搬整个 WebRTC 工程

WebRTC 的音频处理模块（modules/audio_processing）在官方仓库里是和rtc_base、api、system_wrappers、common_audio等一大堆基础库耦合在一起的。你如果直接把整个src目录拖进自己的工程，会发现它依赖 GN 构建系统、abseil、protobuf、甚至部分平台相关的线程和日志封装。对于只想用 3A 的人来说，这是一场灾难——编译一次动辄几十分钟，链接报错几百行，最后还未必能跑在目标平台上。

常见做法是只抽取modules/audio_processing及其最小依赖集：common_audio（提供 FFT、环形缓冲区、滤波器）、rtc_base（只保留checks、criticalsection、logging等基础头文件）、system_wrappers（主要是include目录下的接口声明）。我一般会先建一个空工程，把audio_processing的include和source加进去，然后根据编译器的报错逐个补依赖，而不是一次性全搬。这样能最快定位到哪些文件是真正必需的，哪些只是历史包袱。

提示：不同版本的 WebRTC 目录结构有差异，较新的版本把common_audio挪到了modules/audio_processing同级，抽取前先确认你手上的代码快照结构。

2.2 最小可编译文件清单与目录组织

下面是我实际抽取后能编译通过的一个最小目录结构，基于常见的 WebRTC 音频处理模块组织方式。注意这不是官方发布包，而是从工程里裁剪出来的可编译子集，文件名和路径以你手上的代码为准，但依赖关系是通用的。

audio_3a/ ├── include/ │ ├── audio_processing.h │ ├── audio_processing_impl.h │ └── config.h ├── modules/ │ ├── aec/ │ │ ├── echo_cancellation.h │ │ ├── echo_cancellation_impl.cc │ │ └── echo_cancellation_impl.h │ ├── ns/ │ │ ├── noise_suppression.h │ │ └── noise_suppression_impl.cc │ └── agc/ │ ├── gain_control.h │ └── gain_control_impl.cc ├── common_audio/ │ ├── fft/ │ ├── ring_buffer/ │ └── signal_processing/ ├── rtc_base/ │ ├── checks.h │ ├── criticalsection.h │ └── logging.h └── system_wrappers/ └── include/ ├── cpu_features.h └── rw_lock.h

这个结构的关键在于：audio_processing_impl.cc是总入口，它内部会按配置创建 AEC、NS、AGC 三个子模块。你不需要单独去调每个子模块的Process，而是通过AudioProcessing::ProcessStream一次性完成。编译时最容易缺的是common_audio里的real_fourier和ring_buffer，因为 AEC 的频域处理和延迟估计强依赖它们。

2.3 编译脚本与关键宏开关

抽取完成后，用 CMake 或直接 g++ 编译都可以。下面是一个 CMake 片段，重点是把WEBRTC_USE_NEON、WEBRTC_ARCH_ARM这类平台宏关掉，避免引入不必要的手写汇编。

cmake_minimum_required(VERSION 3.10) project(audio_3a CXX) set(CMAKE_CXX_STANDARD 14) set(CMAKE_CXX_STANDARD_REQUIRED ON) # 关闭平台相关优化宏，先用纯 C++ 跑通 add_definitions(-DWEBRTC_USE_NEON=0) add_definitions(-DWEBRTC_ARCH_ARM=0) add_definitions(-DWEBRTC_ARCH_ARM64=0) add_definitions(-DWEBRTC_POSIX=1) include_directories( ${CMAKE_SOURCE_DIR}/include ${CMAKE_SOURCE_DIR} ${CMAKE_SOURCE_DIR}/system_wrappers/include ) file(GLOB_RECURSE AUDIO_3A_SRC ${CMAKE_SOURCE_DIR}/modules/*.cc ${CMAKE_SOURCE_DIR}/common_audio/*.cc ${CMAKE_SOURCE_DIR}/rtc_base/*.cc ) add_library(audio_3a STATIC ${AUDIO_3A_SRC}) target_link_libraries(audio_3a pthread m)

逻辑说明：file(GLOB_RECURSE)把三个核心目录的.cc全部纳入编译，避免手动列文件漏掉。add_definitions里关掉 NEON 和 ARM 宏，是因为很多抽取出来的代码里带有条件编译的汇编优化，在 x86 上会直接报错。pthread和m是rtc_base里锁和数学函数需要的。参数上，如果你确实要上 ARM 平台，再把对应宏打开，并补上WEBRTC_HAS_NEON的定义，但建议先在 x86 上跑通逻辑再交叉编译。

3. 把 3A 接进音频流水线：初始化与逐帧处理

3.1 AudioProcessing 的创建与配置参数

拿到可编译的库之后，下一步是把它接进你的音频采集和播放链路。WebRTC 3A 的处理对象是 10ms 一帧的 PCM 数据，采样率常见为 16kHz 或 48kHz，声道数可以是单声道或立体声。初始化时最关键的是Config结构体，它决定了 AEC、NS、AGC 是否开启以及各自的模式。

#include "audio_processing.h" #include "config.h" using namespace webrtc; AudioProcessing* apm = AudioProcessing::Create(); Config config; // 回声消除：开启，使用全频带模式 config.Set<EchoCancellation>(new EchoCancellation(true)); // 噪声抑制：开启，中等抑制水平 config.Set<NoiseSuppression>(new NoiseSuppression(true)); // 自动增益：开启，自适应数字模式 config.Set<GainControl>(new GainControl(true)); apm->ApplyConfig(config); // 设置处理格式：48kHz，单声道，10ms 帧长 apm->set_sample_rate_hz(48000); apm->set_num_channels(1, 1);

逻辑说明：AudioProcessing::Create()返回的是平台相关的实现指针，内部已经按默认配置创建了三个子模块。ApplyConfig必须在set_sample_rate_hz之前调用，否则部分版本的实现会用默认采样率初始化滤波器，导致后续切换采样率时状态错乱。set_num_channels(1, 1)的第一个参数是输入通道数，第二个是输出通道数，做单声道处理时都填 1。参数上，EchoCancellation(true)里的true表示启用，部分版本还支持传入EchoCancellation::SuppressionLevel来调整抑制强度，但接口名在不同快照里可能不同，以你代码里的头文件为准。

3.2 逐帧处理：ProcessStream 的调用顺序与缓冲区管理

3A 的处理是流式的，每一帧音频都要按固定顺序喂给ProcessStream。最常见的错误是把采集到的音频直接丢进去，却忘了 AEC 需要参考信号（也就是远端播放的声音）来做回声消除。如果你的场景是纯录音降噪，可以只开 NS 和 AGC；但只要是双向通话，就必须把远端信号通过ProcessReverseStream送进来。

const int kFrameSize = 480; // 48kHz, 10ms, 单声道 float near_frame[kFrameSize]; float far_frame[kFrameSize]; float out_frame[kFrameSize]; // 模拟：far_frame 是远端参考信号，near_frame 是近端采集 // 实际项目中这两块数据来自不同的音频回调 // 第一步：处理远端参考信号 apm->ProcessReverseStream(far_frame, kFrameSize); // 第二步：处理近端采集信号，输出到 out_frame apm->ProcessStream(near_frame, out_frame, kFrameSize); // out_frame 即为 3A 处理后的音频，可送去编码或播放

逻辑说明：ProcessReverseStream必须在ProcessStream之前调用，因为 AEC 需要利用远端信号建立回声路径模型。如果顺序反了，AEC 会拿不到参考，回声消除基本失效。kFrameSize必须是 10ms 对应的采样点数：48kHz 下是 480，16kHz 下是 160。参数上，ProcessStream的输入和输出可以是同一块缓冲区，但为了调试方便，建议分开，这样能对比处理前后的波形。如果你的音频是 16bit 定点 PCM，需要先转成 float，WebRTC 内部处理用的是 float 格式。

3.3 采样率与帧长的匹配规则

采样率和帧长不匹配是新手最容易踩的坑。WebRTC 3A 内部固定按 10ms 帧处理，如果你送进去的是 20ms 帧，它会直接返回错误或者只处理前一半。下面这张表列出了常见采样率对应的单帧样本数，直接照着填就行。

注意：如果你的采集回调是 20ms 一次，必须在送入 3A 之前拆成两个 10ms 帧，否则 AEC 的延迟估计会偏移，回声消除效果断崖式下降。

4. 参数调优与效果验证：AEC、NS、AGC 各自怎么调

4.1 AEC 延迟估计与尾长参数

AEC 的效果好坏，七成取决于延迟估计是否准确。WebRTC 的 AEC 内部有一个延迟估计器，会自动对齐远端和近端信号，但它能容忍的初始延迟范围有限。如果你的设备采集和播放之间存在固定延迟（比如蓝牙耳机），需要在配置里显式设置EchoCancellation::SetDelay或者调整AudioProcessing的delay_offset。

// 在 ApplyConfig 之后，显式设置 AEC 延迟偏移 EchoCancellation* aec = apm->echo_cancellation(); if (aec) { // 假设已知硬件延迟为 50ms，换算成样本数 int delay_samples = 50 * 48; // 48kHz 下 50ms 对应 2400 样本 aec->SetDelay(delay_samples); }

逻辑说明：SetDelay告诉 AEC 远端信号相对于近端信号提前了多少个样本。这个值如果设得不准，AEC 会一直在错误的位置找回声，导致要么消不干净，要么把近端人声也消掉。参数上，delay_samples需要根据实际硬件链路测量，常见做法是播放一个脉冲信号，录回来找峰值位置。尾长（tail length）一般不用手动设，WebRTC 默认按 200ms 左右处理，足够覆盖大多数室内环境。

4.2 NS 抑制水平与语音失真权衡

噪声抑制的强度不是越高越好。WebRTC 的 NS 模块提供多个抑制级别，从低到高分别是Low、Moderate、High、VeryHigh。级别越高，背景噪声压得越狠，但语音的细节和自然度也会损失，尤其是清辅音和尾音容易被吃掉。

// 设置 NS 抑制级别为 Moderate NoiseSuppression* ns = apm->noise_suppression(); if (ns) { ns->set_level(NoiseSuppression::kModerate); ns->Enable(true); }

逻辑说明：set_level需要在Enable(true)之前调用，否则部分实现会忽略级别设置。实际调参时，我一般先用Moderate跑一遍，如果背景噪声仍然明显，再升到High，但升完之后一定要用耳机听一遍语音是否发闷。参数上，kModerate适合大多数办公和室内场景，kHigh适合风扇、空调噪声较大的环境，kVeryHigh只在极端噪声下用，且要做好语音质量下降的心理准备。

4.3 AGC 目标电平与压缩曲线

AGC 负责把忽大忽小的音量拉到一个稳定的水平。WebRTC 的 AGC 有两种模式：自适应模拟增益和自适应数字增益。数字增益直接对 PCM 乘系数，实现简单但会放大底噪；模拟增益需要硬件支持，效果更自然。

// 设置 AGC 目标电平为 -3dBFS GainControl* agc = apm->gain_control(); if (agc) { agc->set_target_level_dbfs(3); // 注意：部分版本参数是负值，以头文件为准 agc->set_compression_gain_db(9); agc->Enable(true); }

逻辑说明：set_target_level_dbfs控制 AGC 把音频拉到多大的电平，值越小输出越响，但太接近 0 会削波。set_compression_gain_db是压缩增益，决定动态范围压缩的强度，9dB 是一个比较温和的起点。参数上，如果发现处理后声音忽大忽小，把压缩增益调低；如果整体音量偏小，把目标电平调小（更响）。不同版本的接口参数正负号可能不同，编译前先看头文件里的注释。

5. 避坑与排查：3A 代码编译和运行中的血泪经验

5.1 编译报错 “undefined reference to webrtc::…”

现象：链接阶段大量报错，提示找不到webrtc::AudioProcessing或webrtc::EchoCancellation的符号。原因通常是只编译了头文件所在的目录，没有把对应的.cc实现文件加入构建。WebRTC 的音频模块很多实现文件放在modules/audio_processing/aec/这类子目录里，file(GLOB_RECURSE)如果路径写错就会漏掉。解决：用find命令确认所有.cc文件都被包含，或者直接在 CMake 里打印AUDIO_3A_SRC变量，看文件列表是否完整。

5.2 处理后的音频全是静音或全是噪声

现象：调用ProcessStream之后，输出缓冲区要么全是 0，要么是一堆白噪声。原因有两个常见方向：一是输入帧长不对，比如送了 20ms 数据但按 10ms 处理，导致内部缓冲区错位；二是ProcessReverseStream和ProcessStream的调用顺序反了，AEC 把近端当成了远端。解决：先确认帧长和采样率匹配，再检查调用顺序，最后用一段纯人声测试，关掉 AEC 只开 NS，看输出是否正常。

5.3 AEC 消不干净，对方仍能听到自己的回声

现象：双向通话时，对方反馈能听到自己的声音，回声消除似乎没生效。原因可能是延迟估计不准，或者远端参考信号没有真正送进来。很多人在集成时，把远端信号直接跳过了ProcessReverseStream，只调了ProcessStream，AEC 没有参考自然消不掉。解决：在ProcessReverseStream入口打日志，确认远端数据确实在每帧调用；然后用SetDelay手动补偿硬件延迟，从 0 开始每次加 10ms 试，直到回声明显减弱。

5.4 开启 AGC 后底噪被放大

现象：安静环境下，处理后能听到明显的“嘶嘶”声。原因是 AGC 的数字增益在提升语音音量的同时，也把本底噪声一起放大了。解决：先开 NS 再开 AGC，让 NS 把底噪压下去之后再让 AGC 提音量；如果仍然明显，降低compression_gain_db，或者改用模拟增益模式（如果硬件支持）。另外，AGC 的目标电平不要设得太激进，留 3~6dB 的余量。

5.5 在 ARM 平台上编译报汇编错误

现象：x86 上编译通过，交叉编译到 ARM 时大量报错，提示 NEON 指令或内联汇编问题。原因是 WebRTC 的common_audio里有针对 ARM 的手写汇编优化，但你的交叉编译工具链或宏定义没配对。解决：先在 CMake 里关掉WEBRTC_USE_NEON和WEBRTC_HAS_NEON，用纯 C++ 跑通；确认逻辑无误后，再打开 NEON 并确保工具链支持。如果仍然报错，检查cpu_features.cc里的检测逻辑是否被正确编译。

6. 进阶：用双讲场景验证 3A 的真实效果

调完参数、跑通编译只是第一步，真正能说明问题的是双讲场景下的表现。所谓双讲，就是近端和远端同时说话，这时候 AEC 既要消掉远端回声，又不能把近端人声消掉，NS 要压噪声但不能压语音，AGC 要稳住音量但不能忽大忽小。我一般会准备三段测试音频：一段纯远端、一段纯近端、一段双方同时说话，然后用脚本把三段依次喂进 3A 流水线，对比处理前后的波形和频谱。

import numpy as np import soundfile as sf # 读取三段测试音频，统一为 48kHz 单声道 float far, sr = sf.read('far.wav', dtype='float32') near, _ = sf.read('near.wav', dtype='float32') double, _ = sf.read('double.wav', dtype='float32') # 分帧，每帧 480 样本（10ms） def frame_generator(data, frame_size=480): for i in range(0, len(data) - frame_size + 1, frame_size): yield data[i:i+frame_size] # 模拟双讲：远端和近端同时送入 for far_frame, near_frame in zip(frame_generator(far), frame_generator(double)): # 这里调用 C++ 侧的 ProcessReverseStream 和 ProcessStream # 实际项目中通过 pybind11 或 ctypes 封装 pass

逻辑说明：这段 Python 脚本负责准备测试数据和分帧，真正的 3A 处理在 C++ 侧完成。分帧大小必须和 C++ 侧一致，否则对不齐。参数上，dtype='float32'保证和 WebRTC 内部格式一致，避免额外的类型转换误差。验证时重点看三个指标：回声残留比（ERLE）、近端语音失真度、输出电平波动范围。ERLE 低于 20dB 说明 AEC 没调好，近端语音失真明显说明 NS 或 AGC 过头了。

我自己的习惯是，每次改完参数，先用双讲音频跑一遍，用耳机听三遍：第一遍只听远端，确认回声没了；第二遍只听近端，确认人声没被吃掉；第三遍一起听，确认双方都能听清。这个土办法比看任何指标都直接。希望帮到你。

本文还有配套的精品资源，点击获取