使用虚拟背景插件

使用虚拟背景插件Copy Anchor Link

声网提供虚拟背景插件 agora-extension-virtual-background，可以与 Web SDK（v4.15.0 或以上）搭配使用，能够将用户人像和背景分割开来，虚化用户周围的真实环境，或者以自定义颜色、图片、视频替代真实背景。虚拟背景插件适用于在线会议、在线教育、直播等场景，有助于保护个人隐私，也能避免杂乱背景对观众造成干扰。

点击在线链接立即体验虚拟背景功能。

虚拟背景插件的效果如下：

功能	效果
虚化背景和图片背景
视频/动态背景

表格内容超出当前宽度，可横向滚动查看更多列。

实现原理Copy Anchor Link

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

前提条件Copy Anchor Link

使用虚拟背景插件需要满足以下前提条件：

• 使用最新版本的桌面端 Chrome 浏览器。
• 已集成 v4.15.0 或以上版本的 Web SDK，实现基础的实时音视频互动功能，具体参考快速开始文档。

示例代码Copy Anchor Link

以下是一段使用 AI 画质插件的完整代码，供开发者参考。

实现步骤Copy Anchor Link

按照以下步骤集成虚拟背景插件并实现虚拟背景功能。

1. 集成插件Copy Anchor Link

通过 npm 将虚拟背景插件 agora-extension-virtual-background 集成到你的项目中。

1. 运行以下命令安装虚拟背景插件：

   Copy Text

   npm install agora-extension-virtual-background

2. 通过以下任意一种方式引入虚拟背景插件。

   • 方式一：在 JavaScript 文件中加入以下代码引入。

     Copy Text

     import VirtualBackgroundExtension from "agora-extension-virtual-background";

   • 方式二：在 HTML 文件中通过 Script 标签引入。引入后即可在 JavaScript 文件中直接使用 VirtualBackgroundExtension 对象。

     Copy Text

     <script src="./agora-extension-virtual-background.js"></script>

2. 注册插件Copy Anchor Link

调用 AgoraRTC.createClient 创建 Client 对象后，新建一个 VirtualBackgroundExtension 对象，然后调用 AgoraRTC.registerExtensions 并传入创建的 VirtualBackgroundExtension 对象，注册虚拟背景插件。

// 创建 Client
var client = AgoraRTC.createClient({mode: "rtc", codec: "vp8"});
// 创建 VirtualBackgroundExtension 实例
const extension = new VirtualBackgroundExtension();
// 检查兼容性
if (!extension.checkCompatibility()) {
  // 当前浏览器不支持虚拟背景插件，你可以停止执行之后的逻辑
  console.error("Does not support Virtual Background!");
}
// 注册插件
AgoraRTC.registerExtensions([extension]);

3. 初始化插件Copy Anchor Link

1. 调用 extension.createProcessor 创建 VirtualBackgroundProcessor 实例。

   Copy Text

   processor = extension.createProcessor();

2. 调用 processor.init 初始化插件。当资源加载或插件初始化失败时，该方法将抛出异常，应用可捕获该异常并进行相应处理。

   Copy Text

   await processor.init();

3. 在创建本地摄像头视频轨道后，调用 videoTrack.pipe 并指定 videoTrack.processorDestination 属性，将插件注入到 SDK 的媒体处理管道中。

   注意

   • 出于计算性能考虑，声网推荐在单个视频轨道上使用虚拟背景插件。
   • 如果需要两个视频轨道用于预览，创建两个 VirtualBackgroundProcessor 实例即可。

   Copy Text

   localTracks.videoTrack.pipe(processor).pipe(localTracks.videoTrack.processorDestination);

4. 设置虚拟背景Copy Anchor Link

调用 processor.setOptions 设置虚拟背景类型和相应参数。支持以下设置：

• 设置纯色背景：将 type 参数设为 "color"，然后设置 color 参数指定颜色。

  Copy Text

  processor.setOptions({type: 'color', color: '#00ff00'});

• 设置图片背景：将 type 参数设为 "img"，然后设置 source 参数指定图片对象。

  Copy Text

  processor.setOptions({type: 'img', source: HTMLImageElement});

• 将用户的实际背景虚化：将 type 参数设为 "blur"，然后设置 blurDegree 参数指定虚化程度为低 (1)、中 (2)、高 (3)。

  Copy Text

  processor.setOptions({type: 'blur', blurDegree: 2});

• 设置动态背景：将 type 参数设为 "video"，然后设置 source 参数指定视频对象。

  Copy Text

  processor.setOptions({type: 'video', source: HTMLVideoElement});

5. 开启插件Copy Anchor Link

调用 processor.enable 开启虚拟背景功能：

await processor.enable();

如果调用此方法前未调用 setOptions，SDK 默认开启背景虚化效果，虚化程度为 1。开启虚拟背景后，如需切换虚拟背景效果，直接调 setOptions 即可。

6. 关闭插件Copy Anchor Link

需要暂时关闭虚拟背景时，调用 processor.disable 方法。

await processor.disable();

确定不再使用虚拟背景时，调用 videoTrack.unpipe，将插件从当前视频轨道上移除。

localTracks.videoTrack.unpipe();

开发注意事项Copy Anchor Link

• 声网背景分割算法对一个摄像头画面里出现单人的分割效果最佳。
• 虚拟背景插件的浏览器支持如下：
  • 支持桌面端 Chrome 91 以上版本。为了获得更好的虚拟背景体验，声网推荐使用桌面端 Chrome 最新版。
  • 不建议在 Firefox 和 Safari 上开启虚拟背景。Firefox 切后台可能导致画面冻结；Safari 上由于浏览器自身性能问题，效果不佳。
  • 不建议在移动端上开启虚拟背景。
• 虚拟背景插件对设备性能要求较高，声网建议满足以下要求（通过 navigator.hardwareConcurrency 和 navigator.deviceMemory 可以分别获取设备的 CPU 逻辑内核数和系统 RAM 大小）：
  • Intel Core i5 4 核或以上的处理器
  • RAM 8GB 或以上
  • 64 位操作系统
• 使用虚拟背景插件时，建议为笔记本电脑选择性能模式或平衡模式，在电源管理节能模式下的性能可能无法满足计算要求。
• 虚拟背景插件自 v1.0.0-beta-3 起支持使用视频作为动态虚拟背景。视频必须为 HTML <video> 元素支持的格式。声网还建议满足以下要求：
  • 视频采用与人像接近的分辨率，不建议使用码率太高的视频。
  • 视频内容适合循环播放，实现更自然的动态虚拟背景效果。
  • 适当降低视频帧率，如 15 fps 或以下。不建议使用 30 fps 以上的视频。
• 如需同时使用多个媒体处理插件，声网建议你使用 Intel Core i5 4 核或以上的处理器。同时开启多个插件后，如果其它正在运行的程序占用了较高的系统资源，你的 App 可能会出现音视频卡顿。

API 参考Copy Anchor Link

本节提供虚拟背景插件的 API 参考。

IVirtualBackgroundExtensionCopy Anchor Link

createProcessorCopy Anchor Link

createProcessor(): IVirtualBackgroundProcessor;

创建 IVirtualBackgroundProcessor 实例。

checkCompatibilityCopy Anchor Link

checkCompatibility(): boolean;

自从 v1.1.1。

检查当前浏览器是否支持虚拟背景插件。

IVirtualBackgroundProcessorCopy Anchor Link

initCopy Anchor Link

init(wasmDir: string): Promise<void>;

初始化插件。

参数：

• wasmDir: 虚拟背景 Wasm 模块所在的 URL 路径（不包含 .wasm 文件名）。自 v1.2.0 起，该参数改为可选参数。

如果因为无法访问 Wasm 文件，插件初始化失败，此方法会抛出异常，建议你在捕获异常时停止虚拟背景功能。

如果 Wasm 文件使用跨域方式部署在 CDN、OSS 等第三方服务上，你需要在服务管理中开启服务的跨域访问权限。在 Nginx 服务器进行跨域部署时，可增加以下配置开启跨域访问：

add_header 'Access-Control-Allow-Origin' "$http_origin";
add_header 'Access-Control-Allow-Credentials' "true";

setOptionsCopy Anchor Link

setOptions(options: VirtualBackgroundEffectOptions): void;

设置虚拟背景类型和参数。

参数：

• options: 虚拟背景选项，详见 VirtualBackgroundEffectOptions。

enableCopy Anchor Link

enable(): void | Promise<void>;

开启虚拟背景功能。

如果调用此方法前未调用 setOptions 方法，SDK 默认开启背景虚化效果，虚化程度为 1。

disableCopy Anchor Link

disable(): void | Promise<void>;

停止虚拟背景功能。

releaseCopy Anchor Link

release(): Promise<void>;

释放插件占用的所有资源，包括创建的 Web Worker。

如果反复创建插件对象 IVirtualBackgroundProcessor 但不释放插件占用资源，可能会导致内存耗尽。

onoverloadCopy Anchor Link

onoverload?: () => void;

当系统运算性能无法满足处理要求（前 100 帧的平均处理时间超过 100 ms）时，SDK 会触发 onoverload。

声网建议你统计该事件的触发频率。当触发频率不高时，可以忽略该事件；当触发频率较高时，如 1 分钟内超过 5 次，可以在该事件的回调函数中调用 disable 关闭虚拟背景，或添加 UI 提示引导用户关闭虚拟背景。

类型定义Copy Anchor Link

VirtualBackgroundEffectOptionsCopy Anchor Link

虚拟背景类型和参数。用于 setOptions 方法。

export type VirtualBackgroundEffectOptions = {
  type: string,
  color?: string;
  source?: HTMLImageElement | HTMLVideoElement;
  blurDegree?: Number;
  fit?: 'contain' | 'cover' | 'fill';
};

属性：

• type: String 型。设置虚拟背景类型。可设为：

  • "color": 纯色背景。
  • "img": 图片背景。
  • "blur": 虚化背景。
  • "video": 视频，即动态背景。
  • "none": 无背景，即人像抠图的效果。

• color: String 型。当你将 type 设为 "color" 时，可通过此参数设置背景颜色。值必须为有效的 CSS 颜色，如 "white"、"#00ff00"、"RGB(255, 0, 0)"。

• source: HTMLImageElement 或 HTMLVideoElement 对象。当你将 type 设为 "img" 或 "video" 时，可通过此参数设置自定义背景图片或视频。

  注意

  • 如果出现 "texture bound to texture unit 2 is not renderable. It might be non-power-of-2 or have incompatible texture filtering (maybe)?" 报错，请检查图片的分辨率相乘后是否是 2 的倍数。
  • 受浏览器安全策略限制，当背景图片或视频资源进行跨域部署时，你需要确保开启服务器的跨域访问权限，且将 HTMLImageElement 对象的 crossOrigin 属性设置为 "anonymous"。
  • 由于 HTMLImageElement 对象的图片加载需要时间，声网建议在 HTMLImageElement 对象的 onload 事件回调中调用 setOptions 方法，否则背景会变成黑色。
  • 如果使用视频作为背景，你需要为 video 元素设置 mute 属性开启静音、设置 loop 属性开启循环播放。

• blurDegree: Number 型。当你将 type 设为 "blur" 时，可通过此参数设置背景虚化程度。可设为：

  • 1: 低
  • 2: 中
  • 3: 高

• fit: String 型。虚拟背景的填充方式。可设为：

  • "contain": 按比例填充并保证背景能完整显示，不足部分用黑色填充。
  • "cover": 按比例填充并保证背景能充满所在区域，超出部分会被裁剪。
  • "fill": 拉伸以填满所在区域。