2024/10/15 16:07:20

使用虚拟背景插件

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

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

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

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

实现原理

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

前提条件

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

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

示例代码

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

完整示例代码

TypeScript
import AgoraRTC from "agora-rtc-sdk-ng";
import VirtualBackgroundExtension from "agora-extension-virtual-background";

// 创建 Client
var client = AgoraRTC.createClient({mode: "rtc", codec: "vp8"});
// 创建 VirtualBackgroundExtension 实例
const extension = new VirtualBackgroundExtension();
// 注册插件
AgoraRTC.registerExtensions([extension]);

let processor = null;
var localTracks = {
  videoTrack: null,
  audioTrack: null
};

// 初始化
async function getProcessorInstance() {
  if (!processor && localTracks.videoTrack) {
    // 创建 VirtualBackgroundProcessor 实例
    processor = extension.createProcessor();

    try {
    // 初始化插件
    await processor.init();
    } catch(e) {
      console.log("Fail to load WASM resource!");
      return null;
    }

    // 将插件注入 SDK 内的视频处理管道
    localTracks.videoTrack.pipe(processor).pipe(localTracks.videoTrack.processorDestination);
  }
  return processor;
}

// 加入频道
async function join() {
  // 添加事件监听
  client.on("user-published", handleUserPublished);
  client.on("user-unpublished", handleUserUnpublished);

  [options.uid, localTracks.audioTrack, localTracks.videoTrack] = await Promise.all([
    // 加入频道
    client.join(options.appid, options.channel, options.token || null),
    // 创建本地麦克风轨道和摄像头轨道
    localTracks.audioTrack || AgoraRTC.createMicrophoneAudioTrack(),
    localTracks.videoTrack || AgoraRTC.createCameraVideoTrack({encoderConfig: '720p_4'})
  ]);

  // 播放本地轨道
  localTracks.videoTrack.play("local-player");
}

// 设置纯色背景
async function setBackgroundColor() {
  if (localTracks.videoTrack) {
    document.getElementById("loading").style.display = "block";

    let processor = await getProcessorInstance();

    try {
      processor.setOptions({type: 'color', color: '#00ff00'});
      await processor.enable();
    } finally {
      document.getElementById("loading").style.display = "none";
    }

    virtualBackgroundEnabled = true;
  }
}

// 将用户的实际背景虚化
async function setBackgroundBlurring() {
  if (localTracks.videoTrack) {
    document.getElementById("loading").style.display = "block";

    let processor = await getProcessorInstance();

    try {
      processor.setOptions({type: 'blur', blurDegree: 2});
      await processor.enable();
    } finally {
      document.getElementById("loading").style.display = "none";
    }

    virtualBackgroundEnabled = true;
  }
}

// 设置图片背景
async function setBackgroundImage() {
    const imgElement = document.createElement('img');

    imgElement.onload = async() => {
      document.getElementById("loading").style.display = "block";

      let processor = await getProcessorInstance();

      try {
        processor.setOptions({type: 'img', source: imgElement});
        await processor.enable();
      } finally {
        document.getElementById("loading").style.display = "none";
      }

      virtualBackgroundEnabled = true;
    }
    imgElement.src = '/images/background.png';
}

实现步骤

注意

本节介绍如何使用最新版本虚拟背景插件。历史版本的实现步骤可能会有所不同，具体差异详见插件发版说明。

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

1. 集成插件

通过 npm 将虚拟背景插件集成到你的项目中。

运行以下命令安装虚拟背景插件：
Bash
```
npm install agora-extension-virtual-background
```
通过以下任意一种方式引入虚拟背景插件。
- 方式一：在 JavaScript 文件中加入以下代码引入。
  TypeScript
  import VirtualBackgroundExtension from "agora-extension-virtual-background";
- 方式二：在 HTML 文件中通过 Script 标签引入。引入后即可在 JavaScript 文件中直接使用 VirtualBackgroundExtension 对象。
  html
  <script src="./agora-extension-virtual-background.js"></script>

2. 注册插件

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

TypeScript
// 创建 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. 初始化插件

调用 extension.createProcessor 创建 VirtualBackgroundProcessor 实例。
TypeScript
```
processor = extension.createProcessor();
```
调用 processor.init 初始化插件。当资源加载或插件初始化失败时，该方法将抛出异常，应用可捕获该异常并进行相应处理。
TypeScript
```
await processor.init();
```
在创建本地摄像头视频轨道后，调用 videoTrack.pipe 并指定 videoTrack.processorDestination 属性，将插件注入到 SDK 的媒体处理管道中。
注意
- 出于计算性能考虑，声网推荐在单个视频轨道上使用虚拟背景插件。
- 如果需要两个视频轨道用于预览，创建两个 VirtualBackgroundProcessor 实例即可。
TypeScript
```
localTracks.videoTrack.pipe(processor).pipe(localTracks.videoTrack.processorDestination);
```

4. 设置虚拟背景

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

设置纯色背景：将 type 参数设为 "color"，然后设置 color 参数指定颜色。
TypeScript
```
processor.setOptions({type: 'color', color: '#00ff00'});
```
设置图片背景：将 type 参数设为 "img"，然后设置 source 参数指定图片对象。
TypeScript
```
processor.setOptions({type: 'img', source: HTMLImageElement});
```
将用户的实际背景虚化：将 type 参数设为 "blur"，然后设置 blurDegree 参数指定虚化程度为低 (1)、中 (2)、高 (3)。
TypeScript
```
processor.setOptions({type: 'blur', blurDegree: 2});
```
设置动态背景：将 type 参数设为 "video"，然后设置 source 参数指定视频对象。
TypeScript
```
processor.setOptions({type: 'video', source: HTMLVideoElement});
```

5. 开启插件

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

TypeScript
await processor.enable();

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

6. 关闭插件

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

TypeScript
await processor.disable();

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

TypeScript
localTracks.videoTrack.unpipe();

信息

如果需要再次开启虚拟背景，复用已有的 VirtualBackgroundProcessor 实例即可，不需要重新创建。如果创建了多个 VirtualBackgroundProcessor，建议调用 processor.release 方法释放不再需要的插件资源。

开发注意事项

声网背景分割算法对一个摄像头画面里出现单人的分割效果最佳。
虚拟背景插件的浏览器支持如下：
- 支持桌面端 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 参考

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

IVirtualBackgroundExtension

createProcessor

TypeScript
createProcessor(): IVirtualBackgroundProcessor;

创建 IVirtualBackgroundProcessor 实例。

checkCompatibility

TypeScript
checkCompatibility(): boolean;

自从 v1.1.1。

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

IVirtualBackgroundProcessor

init

TypeScript
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";

setOptions

TypeScript
setOptions(options: VirtualBackgroundEffectOptions): void;

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

参数：

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

enable

TypeScript
enable(): void | Promise<void>;

开启虚拟背景功能。

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

disable

TypeScript
disable(): void | Promise<void>;

停止虚拟背景功能。

release

TypeScript
release(): Promise<void>;

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

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

onoverload

TypeScript
onoverload?: () => void;

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

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

信息

如果同时使用了 2 个 IVirtualBackgroundProcessor 实例，可以忽略该事件。

类型定义

VirtualBackgroundEffectOptions

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

TypeScript
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 属性开启循环播放。

实现原理​

前提条件​

示例代码​

实现步骤​

1. 集成插件​

2. 注册插件​

3. 初始化插件​

4. 设置虚拟背景​

5. 开启插件​

6. 关闭插件​

开发注意事项​

API 参考​

IVirtualBackgroundExtension​

createProcessor​

checkCompatibility​

IVirtualBackgroundProcessor​

init​

setOptions​

enable​

disable​

release​

onoverload​

类型定义​

VirtualBackgroundEffectOptions​