# 使用 VAD 插件 (Beta) (/zh-CN/realtime-media/rtc/build/extensions/web/voice-activity-detection) > For AI agents: see the complete documentation index at [llms.txt](/llms.txt). ## 使用 VAD 插件(Beta 版) [#使用-vad-插件beta-版] VAD (Voice Activity Detection,语音活动检测) 插件可以与 Web SDK (v4.15.0 或以上) 搭配使用,用于检测音频中包含人声和背景音乐的概率。 ## 实现原理 [#实现原理] 声网 Web SDK 的媒体传输管道包含采集、前处理、编码、传输、解码、后处理和播放等环节。在前处理阶段,插件可以对管道中的音视频数据进行处理,从而实现虚拟背景、降噪、美颜、语音活动检测等功能。 ## 前提条件 [#前提条件] 使用 VAD 插件需要满足以下前提条件: - 使用最新版本的桌面端 Chrome(推荐)、Edge、Firefox 浏览器。 :::warning[注意] VAD 插件仅支持 Safari 14.1 以上版本,但由于 Safari 自身性能原因,声网不建议在 Safari 上使用。 ::: - 如需同时使用多个媒体处理插件,声网建议你使用 Intel Core i5 4 核或以上的处理器。同时开启多个插件后,如果其它正在运行的程序占用了较高的系统资源,你的 App 可能会出现音视频卡顿。 - 已集成 v4.15.0 或以上版本的 Web SDK,实现基础的实时音视频互动功能,具体参考[快速开始](../../../get-started/quick-start?platform=web)文档。 ## 实现步骤 [#实现步骤] 按照以下步骤集成 VAD 插件并实现 VAD 功能。 ### 1. 集成插件 [#1-集成插件] 通过 npm 将 VAD 插件 [agora-extension-vad](https://www.npmjs.com/package/agora-extension-vad) 集成到你的项目中。 1. 运行以下命令安装 VAD 插件: ```shell npm install agora-extension-vad ``` 2. 在你的 `.js` 文件中加入以下代码导入 VAD 模块: ```typescript import { VADExtension } from "agora-extension-vad"; ``` ### 2. 加载 Wasm 依赖 [#2-加载-wasm-依赖] VAD 插件依赖一些 [Wasm 文件](https://webassembly.org/)。为保证浏览器可以正常加载和运行这些文件,你需要完成以下步骤: 1. 将 `node_modules/agora-extension-vad/wasm` 目录下的 Wasm 文件发布至 CDN 或者静态资源服务器中,并且处于同一个公共路径下。后续创建 `VADExtension` 对象时,需要传入上述公共路径的 URL,插件会动态加载这些依赖文件。 :::warning[注意] - 如果 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`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/script-src) 选项中添加 `'wasm-unsafe-eval'` 和 `blob:`。 例如: ```text ``` - 低于 Chrome 97 和 Edge 97 的版本:在 `script-src` 选项中添加 `'unsafe-eval'` 和 `blob:`。 ### 3. 注册插件 [#3-注册插件] 调用 [`AgoraRTC.registerExtensions`](/zh-CN/api-reference/rtc/web/interfaces/iagorartc#registerextensions) 方法并传入创建的 `VADExtension` 实例注册 VAD 插件。你还可以监听 Wasm 文件加载失败的事件。 :::warning[注意] 声网推荐你只创建一个 `VADExtension` 实例。 ::: ```typescript import AgoraRTC from "agora-rtc-sdk-ng"; import { VADExtension } from "agora-extension-vad"; // 传入 Wasm 文件所在的公共路径以创建 VADExtension 实例,路径结尾不带 “/” const extension = new VADExtension({ assetsPath: "./wasm" }); // 检查兼容性 if (!extension.checkCompatibility()) { return console.warn("vad plugin is not support!"); } // 监听 Wasm 文件加载失败的事件 extension.onloaderror = (error) => { // 如果加载 VAD 失败,在此处理错误 console.error(error); }; // 注册插件 AgoraRTC.registerExtensions([extension]); ``` ### 4. 开启插件 [#4-开启插件] 按照以下步骤开启 VAD 插件: 1. 调用 `createProcessor` 方法创建一个 `IVADProcessor` 实例。你可以设置插件为默认开启或关闭。如果不设置,插件将沿用上一次的状态。 ```typescript // 创建 IVADProcessor 实例 const processor = extension.createProcessor(); // 设置插件为默认开启 // await processor.enable(); // 设置插件为默认关闭 // await processor.disable(); //(可选)监听处理器的过载事件以捕获过载信息 processor.on("overload", async () => { console.log("overload!!!"); // 你可以选择关闭插件 // await processor.disable(); // 或者忽略过载状况,继续处理音频 }); ``` 2. 调用 SDK 的 [`pipe`](/zh-CN/api-reference/rtc/web/interfaces/imicrophoneaudiotrack#pipe) 方法并指定 [`processorDestination`](/zh-CN/api-reference/rtc/web/interfaces/imicrophoneaudiotrack#processordestination) 属性,将插件注入音频处理管道。 ```typescript // 创建音频轨道 const audioTrack = await AgoraRTC.createMicrophoneAudioTrack(); // 将插件注入音频处理管道 audioTrack.pipe(processor).pipe(audioTrack.processorDestination); await processor.enable(); ``` 3. 如果没有设置插件为默认开启,还需要调用 `enable` 方法开启插件。 ```typescript await processor.enable(); ``` ### 5. 获取检测结果 [#5-获取检测结果] 在成功开启插件后,你可以通过监听 `result` 事件获取检测结果,并根据需要进行处理。 ```typescript // 监听 VAD 插件的检测结果,并进行相关处理 processor.on("result", handleResult) function handleResult(result) { //输出 `voiceProb`,表示某人正在说话的概率 console.info("voiceProb: ", result.voiceProb); //输出 `musicProb`,表示当前在播放音乐的概率 console.info("musicProb: ", result.musicProb); } ``` :::info[信息] `voiceProb` 和 `musicProb` 是一个从 0 到 1 的浮点数,表示某人正在说话和当前在播放音乐的概率。 ::: ### 6. 关闭插件 [#6-关闭插件] 需要停止使用 VAD 插件时,调用 `disable` 方法关闭插件。 ```typescript await processor.disable(); ``` ## API 参考 [#api-参考] 本节提供 VAD 插件的 API 参考。 ### IVADExtension [#ivadextension] #### checkCompatibility [#checkcompatibility] ```typescript checkCompatibility(): boolean; ``` 检查当前浏览器是否支持 VAD 插件。该方法返回的结果仅供参考。 #### createProcessor [#createprocessor] ```typescript createProcessor(): IVADProcessor; ``` 创建 `IVADProcessor` 实例。 #### onloaderror [#onloaderror] ```typescript onloaderror?: (error: Error) => void; ``` Wasm 依赖文件加载失败回调。 ### IVADProcessor [#ivadprocessor] #### kind [#kind] ```typescript get kind(): 'video' | 'audio'; ``` Processor 的类型,分为视频和音频两种。 #### enabled [#enabled] ```typescript get enabled(): boolean; ``` 插件是否启用: - true:已启用。 - false:未启用。 #### enable [#enable] ```typescript enable(): void | Promise; ``` 开启 VAD 功能。 #### disable [#disable] ```typescript disable(): void | Promise; ``` 关闭 VAD 功能。 #### onoverload [#onoverload] ```typescript on("overload", () => void); ``` ### 类型定义 [#类型定义] #### VADExtensionOptions [#vadextensionoptions] ```typescript export interface VADExtensionOptions { assetsPath: string } ``` VAD 插件初始化参数: - `assetsPath` : VAD 插件依赖的 Wasm 文件的 URL 路径。路径结尾不要带“/”,例如 `./external`。 插件会根据 `assetsPath` 拼接出 Wasm 文件的完整路径。如果路径错误导致 Wasm 文件加载失败,你会收到 [onloaderror](#onloaderror) 回调。