@seastart/srtc-plugin-deepfilternet 0.1.0

package/README.md

@@ -0,0 +1,95 @@
+# @seastart/srtc-plugin-deepfilternet
+
+基于 [DeepFilterNet](https://github.com/Rikorose/DeepFilterNet)（AudioWorklet + WASM）的 SRTC Web SDK 降噪处理器插件，实现 SDK 的 `TrackProcessor` 接口。
+
+相比 RNNoise，DeepFilterNet 降噪质量更高，且支持**运行时可调的降噪强度**与**旁路开关**。底层封装了 [`deepfilternet3-noise-filter`](https://github.com/mezonai/mezon-noise-suppression) 的内核。
+
+## 安装
+
+```bash
+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` 指向其根目录。
+
+资源不随源码入库，安装后用包内脚本拉取，再拷到你的静态目录：
+
+```bash
+# 在本包目录下拉取资源到 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` 仅作兜底。）
+
+## 发布
+
+在仓库根目录执行（会先构建 web SDK 产出类型、再拉取资源、编译并发布）：
+
+```bash
+npm run publishdeepfilternet
+```
+
+## 使用
+
+```typescript
+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；模型权重的授权请在分发前自行核实。

package/dist/deepfilternet-processor.d.ts

@@ -0,0 +1,25 @@
+import type { ProcessorOptions, TrackProcessor } from "@seastart/srtc-web-sdk";
+export interface DeepFilterNetProcessorOptions {
+    suppressionLevel?: number;
+    assetBasePath?: string;
+    cdnUrl?: string;
+}
+export declare class DeepFilterNetProcessor implements TrackProcessor {
+    readonly name = "deepfilternet";
+    processedTrack?: MediaStreamTrack;
+    private suppressionLevel;
+    private assetBasePath;
+    private cdnUrl?;
+    private audioContext?;
+    private ownContext;
+    private core?;
+    private sourceNode?;
+    private workletNode?;
+    private destinationNode?;
+    constructor(options?: DeepFilterNetProcessorOptions);
+    private resolveAssetBase;
+    init(options: ProcessorOptions): Promise<void>;
+    setSuppressionLevel(level: number): void;
+    setEnabled(enabled: boolean): void;
+    destroy(): Promise<void>;
+}

package/dist/deepfilternet-processor.js

@@ -0,0 +1,67 @@
+import { TrackKind } from "@seastart/srtc-web-sdk";
+import { DeepFilterNet3Core } from "deepfilternet3-noise-filter";
+export class DeepFilterNetProcessor {
+    constructor(options = {}) {
+        this.name = "deepfilternet";
+        this.ownContext = false;
+        this.suppressionLevel = options.suppressionLevel ?? 50;
+        this.assetBasePath = options.assetBasePath ?? "/";
+        this.cdnUrl = options.cdnUrl;
+    }
+    resolveAssetBase() {
+        return (this.cdnUrl ?? this.assetBasePath).replace(/\/+$/, "");
+    }
+    async init(options) {
+        if (options.kind !== TrackKind.Audio) {
+            throw new Error("DeepFilterNetProcessor 仅支持音频轨道");
+        }
+        if (options.audioContext) {
+            this.audioContext = options.audioContext;
+            this.ownContext = false;
+        }
+        else {
+            this.audioContext = new (window.AudioContext || window.webkitAudioContext)({
+                sampleRate: 48000,
+                latencyHint: "interactive",
+            });
+            this.ownContext = true;
+        }
+        this.core = new DeepFilterNet3Core({
+            sampleRate: 48000,
+            noiseReductionLevel: this.suppressionLevel,
+            assetConfig: { cdnUrl: this.resolveAssetBase() },
+        });
+        await this.core.initialize();
+        this.workletNode = await this.core.createAudioWorkletNode(this.audioContext);
+        this.sourceNode = this.audioContext.createMediaStreamSource(new MediaStream([options.track]));
+        this.destinationNode = this.audioContext.createMediaStreamDestination();
+        this.sourceNode.connect(this.workletNode);
+        this.workletNode.connect(this.destinationNode);
+        const tracks = this.destinationNode.stream.getAudioTracks();
+        if (!tracks.length) {
+            throw new Error("DeepFilterNetProcessor 未产出音频轨道");
+        }
+        this.processedTrack = tracks[0];
+    }
+    setSuppressionLevel(level) {
+        this.suppressionLevel = Math.max(0, Math.min(100, Math.floor(level)));
+        this.core?.setSuppressionLevel(this.suppressionLevel);
+    }
+    setEnabled(enabled) {
+        this.core?.setNoiseSuppressionEnabled(enabled);
+    }
+    async destroy() {
+        this.core?.destroy();
+        this.sourceNode?.disconnect();
+        this.destinationNode?.disconnect();
+        if (this.ownContext && this.audioContext && this.audioContext.state !== "closed") {
+            await this.audioContext.close();
+        }
+        this.core = undefined;
+        this.sourceNode = undefined;
+        this.workletNode = undefined;
+        this.destinationNode = undefined;
+        this.audioContext = undefined;
+        this.processedTrack = undefined;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { DeepFilterNetProcessor } from "./deepfilternet-processor.js";
+export type { DeepFilterNetProcessorOptions } from "./deepfilternet-processor.js";

package/dist/index.js

@@ -0,0 +1 @@
+export { DeepFilterNetProcessor } from "./deepfilternet-processor.js";

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@seastart/srtc-plugin-deepfilternet",
+  "version": "0.1.0",
+  "description": "SRTC Web SDK DeepFilterNet 降噪处理器插件",
+  "type": "module",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "assets"
+  ],
+  "scripts": {
+    "fetch-assets": "node scripts/fetch-assets.mjs",
+    "build": "tsc -p tsconfig.json"
+  },
+  "dependencies": {
+    "deepfilternet3-noise-filter": "^1.2.1"
+  },
+  "peerDependencies": {
+    "@seastart/srtc-web-sdk": ">=0.5.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "srtc",
+    "deepfilternet",
+    "denoise",
+    "noise-suppression",
+    "webrtc"
+  ],
+  "author": "dev@seastart.cn",
+  "license": "ISC"
+}