使用虚拟背景插件

功能简介

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

效果展示

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

注意事项

• 声网背景分割算法对一个摄像头画面里出现单人的分割效果最佳。

• 虚拟背景插件的浏览器支持如下：

  • 支持桌面端 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 可能会出现音视频卡顿。

技术原理

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

实现步骤

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

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

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

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

      npm install agora-extension-virtual-background

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

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

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

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

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

3. 动态加载 Wasm 文件依赖：虚拟背景插件依赖 Wasm 文件。Wasm 文件位于 node_modules/agora-extension-virtual-background/wasms 目录下。你需要将 Wasm 文件发布至 CDN 或者静态资源服务器中。后续调用 processor.init 初始化插件时，需要传入 Wasm 文件的 URL，插件会动态加载 Wasm 文件。

   • 如果 Wasm 文件的 Host URL 与网页应用的 Host URL 不一致，则需要开启访问文件域名的 CORS 策略。
   • 不能把 Wasm 文件放在 HTTP 服务下，因为在 HTTPS 域名下加载 HTTP 资源会被浏览器安全策略禁止。

4. 注册虚拟背景插件：调用 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]);

5. 初始化虚拟背景插件：

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

      processor = extension.createProcessor();

   2. 调用 processor.init 初始化插件。在该方法你需要传入虚拟背景 Wasm 模块所在的 URL 路径。当资源加载或插件初始化失败时，该方法将抛出异常，应用可捕获该异常并进行相应处理。

      await processor.init("./assets/wasms");

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

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

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

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

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

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

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

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

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

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

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

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

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

   await processor.enable();

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

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

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

   localTracks.videoTrack.unpipe();

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

示例代码

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 {
    // 初始化插件，传入 Wasm 文件路径
    await processor.init("./assets/wasms");
    } 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';
}

API 参考

IVirtualBackgroundExtension

createProcessor

createProcessor(): IVirtualBackgroundProcessor;

创建 IVirtualBackgroundProcessor 实例。

checkCompatibility

checkCompatibility(): boolean;

自从 v1.1.1。

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

IVirtualBackgroundProcessor

init

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

初始化插件。

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

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

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

参数：

• wasmDir: 虚拟背景 wasm 模块所在的 URL 路径（不包含 .wasm 文件名）。

setOptions

setOptions(options: VirtualBackgroundEffectOptions): void;

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

参数：

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

enable

enable(): void | Promise<void>;

开启虚拟背景功能。

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

disable

disable(): void | Promise<void>;

停止虚拟背景功能。

release

release(): Promise<void>;

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

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

onoverload

onoverload?: () => void;

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

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

类型定义

VirtualBackgroundEffectOptions

虚拟背景类型和参数。用于 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" 时，可通过此参数设置自定义背景图片或视频。

• blurDegree: Number 型。当你将 type 设为 "blur" 时，可通过此参数设置背景虚化程度。可设为：
  • 1: 低
  • 2: 中
  • 3: 高
• fit: String 型。虚拟背景的填充方式。可设为：
  • "contain": 按比例填充并保证背景能完整显示，不足部分用黑色填充。
  • "cover": 按比例填充并保证背景能充满所在区域，超出部分会被裁剪。
  • "fill": 拉伸以填满所在区域。