@seastart/srtc-plugin-deepfilternet

基于 DeepFilterNet（AudioWorklet + WASM）的 SRTC Web SDK 降噪处理器插件，实现 SDK 的 TrackProcessor 接口。

相比 RNNoise，DeepFilterNet 降噪质量更高，且支持运行时可调的降噪强度与旁路开关。底层封装了 deepfilternet3-noise-filter 的内核。

安装

npm i @seastart/srtc-web-sdk @seastart/srtc-plugin-deepfilternet

托管静态资源

插件依赖两个静态资源（wasm + 模型，合计约 18MB），需自托管：

• v2/pkg/df_bg.wasm
• v2/models/DeepFilterNet3_onnx.tar.gz

⚠️ v2/pkg、v2/models 这两层子目录由底层包写死，拷贝时必须保留该目录结构，且通过 assetBasePath 指向其根目录。

资源不随源码入库，安装后用包内脚本拉取，再拷到你的静态目录：

# 在本包目录下拉取资源到 assets/
npm run fetch-assets --prefix node_modules/@seastart/srtc-plugin-deepfilternet

# 拷贝到你的静态目录（保留 v2/ 结构）
cp -r node_modules/@seastart/srtc-plugin-deepfilternet/assets/v2 public/deepfilternet/v2

（npm 上的版本已内置 assets/v2，安装后即存在；上面的 fetch-assets 仅在缺失时作兜底。）

使用

import SRTC from "@seastart/srtc-web-sdk";
import { DeepFilterNetProcessor } from "@seastart/srtc-plugin-deepfilternet";

const srtc = new SRTC();

const mic = srtc.createLocalMicTrack();
await mic.startCapture({ deviceId });

// 开启降噪（assetBasePath 指向上一步托管资源的目录）
const processor = new DeepFilterNetProcessor({
  assetBasePath: "/deepfilternet/",
  suppressionLevel: 50,
});
await mic.setProcessor(processor);

await srtc.publishLocalTrack(mic);

// 运行时调整降噪强度（0–100），无需重建流
processor.setSuppressionLevel(80);

// 运行时旁路 / 恢复
processor.setEnabled(false);
processor.setEnabled(true);

// 关闭降噪，还原原始麦克风轨道
await mic.removeProcessor();

选项

| 选项 | 类型 | 默认 | 说明 | | --- | --- | --- | --- | | suppressionLevel | number | 50 | 降噪强度 0–100，映射 DeepFilterNet 衰减上限 atten_lim_db；可运行时调整 | | assetBasePath | string | "/" | 自托管资源根目录（其下需有 v2/pkg、v2/models） | | cdnUrl | string | — | 高级：直接覆盖资源根 URL，优先级高于 assetBasePath |

运行时方法

| 方法 | 说明 | | --- | --- | | setSuppressionLevel(level: number) | 调整降噪强度 0–100，无需重建音频流 | | setEnabled(enabled: boolean) | 旁路（false 输出原始音频）/ 恢复降噪（true） |

注意事项

• 仅支持音频轨道；用于视频轨道会抛错。
• 需在 HTTPS（或 localhost）环境下运行；AudioContext 可能需用户手势后才能 resume。
• 采样率固定 48kHz。
• DeepFilterNet 计算量高于 RNNoise，STFT 最小延迟约 20ms；请在目标设备实测 CPU 与延迟。
• 切换设备（changeDeviceId）或重新 startCapture 后，SDK 会自动重建处理器，无需再次 setProcessor。
• 许可：DeepFilterNet 本体为 Apache-2.0/MIT；模型权重的授权请在分发前自行核实。

关于模型 .tar.gz 与 Content-Encoding

模型文件本身是 gzip。部分服务器/代理会对 .gz 再加 Content-Encoding: gzip，浏览器据此自动解压一次，导致底层拿到的是未压缩的 .tar 而初始化崩溃（RuntimeError: unreachable）。

本插件已自动兜底：检测到模型被解压后会在浏览器内重新 gzip 还原，无需改服务器配置。该还原依赖 CompressionStream（Chrome 80+ / Edge 80+ / Safari 16.4+ / Firefox 113+）；若环境不支持，会抛出明确错误提示你关闭该响应头。此外，若资源路径错误返回了 HTML（如 SPA fallback），也会抛出清晰的内容无效错误，而非晦涩的 unreachable。