使用 AI 降噪插件

功能简介

AI 降噪插件使用声网人工智能噪声消除算法，可以与 Web SDK（v4.15.0 或以上）搭配使用，降低上百种噪声，减少多人同时说话时的人声失真。对于在线会议、语聊房、远程问诊、游戏语音等场景，AI 降噪插件能够让远程交流和面对面交谈一样实时。

噪声类型

AI 降噪插件可以有效压制以下类型的噪声：

• 电视噪声
• 厨房噪声
• 街道噪声，如鸟叫声、汽车噪声、地铁噪声
• 机器噪声，如风扇、空调、吸尘器、复印机等噪声
• 办公室噪声，如敲键盘、鼠标点击
• 家庭噪声，如开关门声、吱吱响椅子声、婴儿哭叫声、装修噪声
• 连续敲击声
• 提示音、鼓掌声
• 音乐

降噪策略

AI 降噪插件支持如下降噪策略：

• 默认策略：在保护人声的前提下，将噪声降低到人耳舒适的状态。
• 定制策略：如果你需要增强降噪效果或根据业务场景定制降噪策略，请联系 sales@agora.io。

注意事项

AI 降噪插件目前有以下限制：

• 如果输入信号的采样率不是 16KHz，AI 降噪插件会将信号下采至 16KHz 处理，然后重采回原采样率。因此，输出信号中 8KHz 以上的音频内容将丢失。
• 在一些未知场景下，降噪可能会损伤一定程度的语音质量 。
• 多人同时说话时，明显较小的人声可能有一定程度的语音损伤。
• 如果当前页面只有部分音频轨道开启了 AI 降噪，由于开启 AI 降噪会打开浏览器自带的 AEC 和 AGC、关闭浏览器自带的 NS，未开启 AI 降噪的音频轨道可能会受影响。
• 仅支持 Safari 14.1 以上版本，但由于 Safari 自身性能原因，声网不建议在 Safari 上使用。
• 暂不支持在移动端使用。

• 如需同时使用多个媒体处理插件，声网建议你使用 Intel Core i5 4 核或以上的处理器。同时开启多个插件后，如果其它正在运行的程序占用了较高的系统资源，你的 app 可能会出现音视频卡顿。

技术原理

声网 Web SDK 的媒体传输管道包含采集、前处理、编码、传输、解码、后处理和播放等环节。 在前处理阶段，插件可以对管道中的音视频数据进行处理，从而实现虚拟背景、降噪、美颜等功能。

前提条件

使用 AI 降噪插件需要满足以下前提条件：

• 噪声类型符合你的业务场景。 例如：当前版本会将麦克风采集的背景音乐当作噪声，因此不适用于使用麦克风同时采集人声和背景音乐的场景。
• 最新版本的桌面端 Chrome（推荐）、Edge、Firefox 浏览器。

实现步骤

按照以下步骤集成 AI 降噪插件并实现 AI 降噪功能：

1. 参考快速开始文档，将 Web SDK（v4.15.0 或以上）集成到你的项目中并实现基本的实时音视频功能。

2. 通过 npm 将 AI 降噪插件（agora-extension-ai-denoiser）集成到你的项目中。

   1. 运行以下命令安装 AI 降噪插件：
      npm install agora-extension-ai-denoiser
   2. 在你的 .js 文件中加入以下代码导入 AI 降噪模块：

      import {AIDenoiserExtension} from "agora-extension-ai-denoiser";

3. 动态加载 Wasm 文件依赖：AI 降噪插件依赖一些 Wasm 文件。为保证浏览器可以正常加载和运行这些文件，你需要完成以下步骤：

   1. 将 node_modules/agora-extension-ai-denoiser/external 目录下的 Wasm 文件发布至 CDN 或者静态资源服务器中，并且处于同一个公共路径下。后续创建 AIDenoiserExtension 对象时，需要传入上述公共路径的 URL，插件会动态加载这些依赖文件。
      • 如果 Wasm 文件的 Host URL 与网页应用的 Host URL 不一致，则需要开启访问文件域名的 CORS 策略。
      • 不能把 Wasm 文件放在 HTTP 服务下，因为在 HTTPS 域名下加载 HTTP 资源会被浏览器安全策略禁止。
   2. 如果启用了 CSP（Content Security Policy），由于 Chrome 和 Edge 默认禁止加载和运行 Wasm 文件、默认禁止加载 Blob 对象，你需要根据浏览器版本配置 CSP：
      • 高于 Chrome 97 和 Edge 97 的版本（含 Chrome 97 和 Edge 97）：在 script-src 选项中添加 'wasm-unsafe-eval' 和 blob:。 例如：

        <meta http-equiv="Content-Security-Policy" content="script-src 'self' 'wasm-unsafe-eval' blob:">

      • 低于 Chrome 97 和 Edge 97 的版本：在 script-src 选项中添加 'unsafe-eval' 和 blob:。

4. 注册 AI 降噪插件：调用 AgoraRTC.registerExtensions 方法并传入创建的 AIDenoiserExtension 实例。 你还可以监听 Wasm 文件加载失败的事件。

   声网推荐你只创建一个 AIDenoiserExtension 实例。

   // 传入 Wasm 文件所在的公共路径以创建 AIDenoiserExtension 实例，路径结尾不带 “/”
   const denoiser = new AIDenoiserExtension({assetsPath:'./external'});
   // 检查兼容性
   if (!denoiser.checkCompatibility()) {
     // 当前浏览器可能不支持 AI 降噪插件，你可以停止执行之后的逻辑
     console.error("Does not support AI Denoiser!");
   }
   // 注册插件
   AgoraRTC.registerExtensions([denoiser]);
   // 监听 Wasm 文件加载失败的事件，可能原因包括 Wasm 文件路径有误等
   denoiser.onloaderror = (e) => {
     // 如果 Wasm 文件加载失败，你可以关闭插件，例如：
     // openDenoiserButton.enabled = false;
     console.log(e);
   }

5. 创建 IAIDenoiserProcessor 实例：调用 createProcessor 方法创建一个 processor，并设置插件为默认开启或关闭。如果不设置，插件将沿用上一次的状态。

   // 创建 processor
   const processor = denoiser.createProcessor();
   // 设置插件为默认开启
   processor.enable();
   // 设置插件为默认关闭
   // processor.disable();

6. 将插件注入音频处理管道：调用 pipe 方法并指定 processorDestination 属性。

   // 创建音频轨道
   const audioTrack = await AgoraRTC.createMicrophoneAudioTrack();
   // 将插件注入音频处理管道
   audioTrack.pipe(processor).pipe(audioTrack.processorDestination);
   await processor.enable();

7. 控制插件的开启或关闭：调用 enable 方法和 disable 方法。

   () => {
    if (processor.enabled) {
      await processor.disable();
    } else {
      await processor.enable();
    }
   }

8. 根据需要调整降噪模式或降噪等级：

   // 监听降噪处理耗时过长的事件
   processor.onoverload = async (elapsedTime) => {
     console.log("overload!!!");
     // 调整为稳态降噪模式，临时关闭 AI 降噪
     await processor.setMode("STATIONARY_NS");
     // 完全关闭 AI 降噪，使用浏览器自带的降噪
     // await processor.disable()
   }

9. 转储降噪处理过程中的音频数据：调用 dump 方法，并监听 ondump 和 ondumpend 回调。

   声网强烈推荐你对音频数据进行转储。在降噪处理发生问题的情况下，转储可以提高定位和分析问题的效率。

   processor.ondump = (blob, name) => {
     // 将降噪处理过程中的音频数据文件以 .pcm 格式转储到本地
     const objectURL = URL.createObjectURL(blob);
     const tag = document.createElement("a");
     tag.download = name;
     tag.href = objectURL;
     tag.click();
     setTimeout(() => {URL.revokeObjectURL(objectURL);}, 0);
   }
   
   processor.ondumpend = () => {
     console.log("dump ended!!");
   }
   
   processor.dump();

API 参考

IAIDenoiserExtension

checkCompatibility

checkCompatibility(): boolean;

自从 v1.1.0。

检查当前浏览器是否支持 AI 降噪插件。该方法返回的结果仅供参考。

createProcessor

createProcessor(): IAIDenoiserProcessor;

创建 IAIDenoiserProcessor 实例。

onloaderror

onloaderror?: (error: Error) => void;

Wasm 依赖文件加载失败回调。

IAIDenoiserProcessor

kind

get kind(): 'video' | 'audio';

Processor 的类型，分为视频和音频两种。

enabled

get enabled(): boolean;

插件是否启用：

• true：已启用。
• false：未启用。

enable

enable(): void | Promise<void>;

开启 AI 降噪功能。

disable

disable(): void | Promise<void>;

关闭 AI 降噪功能。

setMode

setMode(mode: AIDenoiserProcessorMode): Promise<void>;

自从 v1.1.0。

设置降噪模式。

你可以在 onoverload 回调中调用该方法切换至稳态降噪，降低开销。详见 AIDenoiserProcessorMode。

该方法必须在 pipe 之后调用。

setLevel

setLevel(level: AIDenoiserProcessorLevel): Promise<void>;

自从 v1.1.0。

设置降噪强度，详见 AIDenoiserProcessorLevel。

该方法必须在 pipe 之后调用。

dump

dump(): void;

转储降噪处理过程中的音频数据，方便定位和分析降噪处理的问题。

该方法必须在 pipe 之后调用。

调用该方法会触发 9 次 ondump 回调，返回插件在该方法调用前 30 秒和后 60 秒处理的音频数据，一共 9 个音频文件（详见音频文件说明）。然后触发 ondumpend 回调，表示已结束音频数据的转储。

音频文件说明

每个音频文件的编码格式为 PCM，长度为 30 秒。文件名包含以下信息：

• 音频数据所处的阶段，有以下三种：
  • input：待降噪的音频数据。
  • ns_out：经过降噪处理的音频数据。
  • agc_out：经过人声增强处理的音频数据。
• 音频采样率。
• 通道数。
• 转储时间：假设转储时间为 T（单位为秒），则文件包含 [T-30,T] 范围内的音频数据。

音频文件名示例：input_16000hz_1ch_0.pcm

注意

• 如果你在 ondump 回调触发不到 9 次时关闭了 AI 降噪，转储过程会立即终止，并触发ondumpend 回调，此时返回的音频数据文件不足 9 个。
• 如果插件实际处理的音频长度不足 30 秒，则对应的音频文件长度也不足 30 秒。

ondump

ondump?: (blob: Blob, name: string) => void;

转储音频数据回调。

该回调返回以下参数：

• blob：音频数据文件。
• name：音频数据文件的名称。

ondumpend

ondumpend?: () => void;

转储音频数据已结束回调。

onoverload

onoverload?: (elapsedTime: number) => void;

降噪处理耗时过长回调。

回调参数：

• elapsedTime：插件处理一帧音频的时间（毫秒）。该值仅作参考，精度取决于浏览器计时的精度，比如 Firefox 上的时间精度较低。

类型定义

AIDenoiserExtensionOptions

export interface AIDenoiserExtensionOptions {
  assetsPath: string
}

AI 降噪插件初始化参数：

• assetsPath ： AI 降噪插件依赖的 Wasm 文件的 URL 路径。路径结尾不要带“/”，例如 ./external。

插件会根据 assetsPath 拼接出 Wasm 文件的完整路径。如果路径错误导致 Wasm 文件加载失败，你会收到 onloaderror 回调。

AIDenoiserProcessorMode

export enum AIDenoiserProcessorMode {
  NSNG = "NSNG",
  STATIONARY_NS = "STATIONARY_NS",
}

降噪模式：

• NSNG：AI 降噪。该模式可以压制噪声类型中的稳态与非稳态噪声。
• STATIONARY_NS：稳态降噪。该模式仅压制稳态噪声，建议仅在 AI 降噪处理耗时过长时使用。

AIDenoiserProcessorLevel

export enum AIDenoiserProcessorLevel {
  SOFT = "SOFT",
  AGGRESSIVE = "AGGRESSIVE",
}

降噪强度：

• SOFT：（推荐）舒缓降噪。
• AGGRESSIVE：激进降噪。将降噪强度提高到激进降噪会增大损伤人声的概率。