aec3-rs：把 WebRTC 的 AEC3 回声消除器搬进 Rust 生态

aec3（RubyBit/aec3-rs）是 WebRTC AEC3 声学回声消除器的 Rust 移植版本，但它不只是”翻译一遍 C++”——它把 AEC3 与 NS、AGC2、HPF、重采样等模块统一到一个带类型检查的有向图运行时里，让端侧语音链路的搭建从”函数按顺序调用”变成”声明式接线”。截至 v0.4.0，它已经补齐了多声道检测、前置回声检测、全带后置滤波，并给出了 SIMD 加速后的实测数据，许可证为 MIT OR BSD-3-Clause，可直接商用。

GitHub 链接：https://github.com/RubyBit/aec3-rs

一、AEC3 解决什么

免提通话、视频会议、智能音箱都有一个绕不开的物理事实：远端的声音从本地扬声器放出来，会被本地麦克风再收一遍，然后传回远端。远端听到的这个人声延迟版本，就是回声。音量越大、房间越空旷、设备越廉价，回声越难听。

WebRTC 里的这个模块叫 AEC3（第三代声学回声消除器），它跑在 APM（Audio Processing Module）内部，处理 10 ms 一帧的音频，内部再切成 64 样本的块（16 kHz 下即 4 ms 一块）推进流水线。整条链路大致是五个环节：

延迟估计（delay estimation）：先把参考信号（远端播出的音频）和采集信号在时间上对齐。这个延迟不是固定值，它包含播放缓冲、DAC、空气路径、ADC、采集缓冲，手机上可能浮动在 20～200 ms 之间。
线性自适应滤波：用频域分块自适应滤波器建模”扬声器→房间→麦克风”这条回声路径，算出回声估计并从麦克风信号里减掉。
双讲检测（double-talk detection）：双方同时说话时必须冻结滤波器更新，否则会把近端人声当成回声学进去，模型就废了。
残余回声抑制（residual echo suppression）：廉价扬声器在大音量下的非线性失真，线性滤波器消不掉，靠抑制增益按子带处理。
舒适噪声（comfort noise）：抑制过狠会把通话变成”洞穴感”，需要补一点点合成底噪。

调试这套东西时最常用的指标是 ERLE（Echo Return Loss Enhancement），即回声被压低了多少 dB。ERLE 长期低于 10 dB，基本可以判定滤波器没收敛，而根因往往是延迟没对齐或参考信号接错了线，而不是”算法不够聪明”。

理解了这五步，才能看懂 aec3-rs 为什么要把架构设计成现在这样。

二、aec3-rs 是什么

aec3 是一个 WebRTC AEC3 的 Rust 移植，外加一组持续扩充的可复用 DSP 构建块。当前版本 0.4.0（2026-09-16），edition 2024，作者 Angelos-Ermis Mangos。

它把代码分成四个顶层模块，职责非常清楚：

模块	定位	内容
`aec3::graph`	运行时层	图构建器、类型化端口/packet、队列与调度、背压、序列号与对齐规则
`aec3::nodes`	节点层	`aec3`、`ns`、`agc2`、`hpf`、`post_filter`、`resample`、`tap`、`audio`
`aec3::pipelines`	便利层	`linear`，封装最常见的语音链路
`aec3::audio_processing`	底层算法层	从 WebRTC 直接移植的处理模块（`echo_canceller3`、`gain_controller2`、`noise_suppressor` 等）

依赖也相当克制：num-complex、rustfft、crossbeam-channel、log 为必选；serde、postcard、hound 挂在可选的 diagnostics feature 下，用于导出/解析诊断数据。

关键设计意图是：内置 DSP 节点全部以 10 ms 音频帧为单位，统一承载在 AudioChunk 里，因此采集链路、双工回声消除链路、旁路分析链路、多输出图和自定义节点，共用同一套执行模型。

三、图运行时：这才是这个库真正的差异点

绝大多数 AEC 移植项目的 API 长这样：process(render, capture) -> output。简单，但一旦你想在 AEC 之后接噪声抑制、在 AGC2 之前拿一路旁路信号做分析、或者把 linear 输出喂给 NS 的 analysis 输入，就得自己手写调度和缓存。

aec3-rs 从 v0.2 开始换成了 DAG 执行模型，几个能力值得单独说：

泛型类型化端口：Source<T>、Sink<T>、InPort<T>、OutPort<T>，接线错误在编译期就暴露，运行期还有一层图不变量与格式校验兜底。
异步到达：render、capture、control 三类 packet 可以各自独立到达，不必锁步推进。对真实设备来说这很关键——播放和采集本来就不是同一个时钟。
零拷贝倾向：packet 是共享句柄，音频缓冲走 copy-on-write，fan-out 到多路下游时不会强制复制。
两种调度风格：SchedulePlan::OnArrival（触发端口收到 packet 就跑）用于 AEC3 这类 render 独立更新内部状态的节点；SchedulePlan::AlignOn（触发 packet 与依赖 packet 按策略配对后才跑）用于旁路分析输入。
严格的对齐语义：MatchPolicy::BySequence 要求依赖 packet 的 sequence 与触发 packet 一致，未打戳的包会直接报 MissingSequenceForAlignment 错误，而不是悄悄退化成 FIFO 匹配——这类静默降级正是语音链路里最难查的 bug 来源。
节点生命周期控制：Active / Bypassed / Suspended 三种运行状态，加上 Runtime::reset_node(...) 的重置能力，Bypassed 支持主音频路径直通，Suspended 则冻结工作但不动拓扑。

对语音智能体、会议客户端这类需要动态开关处理链的场景，这套控制面比”重新构造一个 processor”要优雅得多。

四、用法

如果你只需要标准语音链路，直接上 aec3::pipelines::linear，它封装的是 render + capture -> HPF -> AEC3 -> NS -> AGC2：

use aec3::nodes::audio::AudioFormat;
use aec3::pipelines::linear;

let format = AudioFormat::ten_ms(48_000, 1);
let mut pipeline = linear::builder(format, format)
    .initial_delay_ms(116)
    .export_metrics(true)
    .build()?;

let render = vec![0.0f32; format.sample_count()];
let capture = vec![0.0f32; format.sample_count()];
let mut output = vec![0.0f32; format.sample_count()];

pipeline.handle_render_frame(&render)?;
let produced = pipeline.process_capture_frame(&capture, &mut output)?;
assert!(produced);

注意 initial_delay_ms 这个参数——它对应前面说的那条”延迟估计”环节的起始假设值，填 116 ms 是 WebRTC 侧常见的经验值。这个 wrapper 会自动给 packet 打序列号，所以下游任何用 BySequence 对齐的节点都能直接工作。

如果你需要自己接线，就上 GraphBuilder：注册 mic / render 两个 source、一个 output sink，然后依次 add_to(&mut graph) 加入 AGC2、AEC3、NS 三个节点，再手工 connect。典型拓扑包括：

仅采集处理：source -> agc2 / hpf / ns -> sink
双工回声消除：capture + render -> aec3 -> sink
旁路分析：aec3.linear_out -> ns.analysis_in
扇出：接 nodes::tap，或把一个输出连到多个下游端口

自定义节点则是实现 NodeSpec（声明端口）、NodeFactory（构建运行期状态）、NodeRunner（在 ProcessCtx 里消费输入、产出输出）三个 trait，图核心保持泛型不侵入。

五、AEC3 节点本身的能力

作为图中的一个普通节点，AEC3 提供了几个可选端口：线性输出（linear-output，用于旁路分析）、指标（metrics）、诊断（diagnostics，配合 diagnostics feature 与 parse-diagnostics 工具）、延迟控制，以及 0.4 新增的 capture_output_used_in。

最后这个端口解决的是一个很实际的算力问题：如果这一帧的采集输出根本没人用（典型场景是纯监测、或者当前处于静音段），通过 EchoCanceller3::set_capture_output_usage 可以跳过残余回声估计、抑制增益计算和抑制滤波，采集块原样透传——而线性滤波器继续自适应，不会因为省算力而丢掉收敛进度。

六、许可与专利：能不能商用

可以。Cargo.toml 里写的是 MIT OR BSD-3-Clause，双许可任选，商用没有任何障碍。

需要留意的是仓库根目录里那个 PATENT 文件，内容沿用 Google 对 WebRTC 代码包的 Additional IP Rights Grant：Google 授予你永久、全球、非独占、免费、不可撤销的专利许可，用来制造、使用、销售、修改和分发本实现——但许可范围仅限”本实现必然侵权”的权利要求，不包括因为进一步修改才侵权的部分。此外有一条终止条款：如果你对任何实体发起主张本实现构成专利侵权的诉讼，该许可自起诉之日起终止。

对做商业语音产品的团队来说，结论是：直接用、按原样用，专利风险由 Google 的授权覆盖；一旦做了大幅改动，就落回这个授权的边界之外了。仓库 README 的措辞也很直白——请依据自身需求与原始项目政策来采用和授权。

七、适合谁，边界在哪

适合：

在 Rust 生态里做端侧 RTC、会议客户端、语音智能体、对讲设备的团队：不想拖一个 C++ libwebrtc 进来，又需要工业级的回声消除质量。
需要在 AEC 前后插入自定义 DSP、或者要动态开关处理节点的产品（图运行时的控制面正好对上这个需求）。
想在 Rust 里复用 NS / AGC2 / 重采样 / 三带滤波器组等 WebRTC 音频组件，而不只是 AEC 的项目。

要留意：

项目自我定位是 WIP，图 API 从 v0.2 起才存在且”预期会继续演进”，作者也明确表示仍在内部验证这套设计是否有用，特别欢迎关于易用性、使用场景与性能的反馈。生产使用建议锁版本。
如果不需要图模型，可以直接用 aec3::audio_processing 里的底层模块，不必被这套运行时绑架。
结构对应的是 WebRTC 参考实现，src/audio_processing/aec3/ 下从 matched_filter、erl_estimator、reverb_model 到 transparent_mode、clockdrift_detector、saturation_detector 一应俱全，agc2 里连 RNN VAD 的权重与测试数据都一并移植了——这让逐模块对照上游、校验行为一致性成为可能，也意味着这个库的野心不止于”AEC 能用就行”。