Web RTC SDK 提供虚拟背景插件，在互动直播、视频会议、在线授课等场景下，可将用户人像和背景分离，采用模糊背景或自定义图片作为虚拟背景，从而避免杂乱背景对观众的影响，保护用户隐私，呈现较高的视频效果。你可以参考本文，实现这一功能。

1. 自 Web SDK v4.52 起，本功能可用。

2. 自 v4.53 版本起，支持在初始化时选择使用 GPU 模式。

3. Web SDK v4.60.2 对本功能做了如下修改：

   • 浏览器兼容性变动，变更后的浏览器最低版本要求如下表。

     设备类型	浏览器	浏览器最低版本要求
     桌面端	Chrome	78
     	Safari	15
     	Firefox	80
     	Edge	83
     移动端	Chrome	78
     	Safari	15.4
     	微信内嵌浏览器	8.0.32

   • 修改了部分枚举类型中的字面量值：

     • 在 BackgroundMode 枚举中，BACKGROUND_IMAGE 的取值从 'image' 改为 'image-url'。
     • 在 BackgroundAIModelType 枚举中，PERFORMANCE 的取值从 0 改为 'fast'；QUALITY 的取值从 1 改为 'accurate'。
     • 在 BackgroundAIBackend 枚举中，CPU 的取值从 -1 改为 'cpu'；GPU 的取值从 1 改为 'gpu'。

• 新增了视频和纯色背景。
• 设置为模糊背景时支持自定义模糊半径。

1. 本功能需付费使用，请联系技术支持团队获取符合业务功能需求的鉴权文件。

2. RTC SDK v4.52+ 你需要集成 RTC SDK，并实现音视频通话功能。

3. 不建议在移动端使用本功能。这是由于本功能依赖一些 WASM 文件，对移动端设备的性能要求较高。

4. 为了更好的使用体验，建议设备满足以下要求：

   1. 双核 Intel Core i5+

   2. RAM 8 GB+

   3. 64 位操作系统

5. 如果你使用了云代理功能，你需要在防火墙白名单中添加虚拟背景域名，参看在防火墙限制下进行通话。

1. 在你的项目中引入虚拟背景插件，可直接引入或通过 UMD 方式引入。

   1. 直接引入

   import RTCBeautyExtension from '@volcengine/rtc/extension-beauty';
   

   2. 通过 UMD 方式引入

   const {BackgroundMode, RTCBeautyExtension} = window.VERTCExtensions;
   

2. 注册虚拟背景插件。

import VERTC from '@volcengine/rtc';
import RTCBeautyExtension, { BackgroundAIBackend } from '@volcengine/rtc/extension-beauty';

// 创建引擎实例
const engine = VERTC.createEngine('appid');

// 创建虚拟背景插件实例，需传入鉴权文件
const extension = new RTCBeautyExtension({ 
  authFileUrl: 'https://xxxx.auth',
  // 自 v4.53 版本起，可设置使用 GPU 模式
  aiBackend: BackgroundAIBackend.GPU
});
// 注册插件
try {
  await engine.registerExtension(extension);
} catch (error) {
  // 注册失败，详细信息：error.message
}

3. 开始视频采集，并设置渲染视图及模式。 示例代码以内部采集为例，如需使用外部采集，参看 setVideoSourceType。

// 开启内部视频采集
engine.startVideoCapture();
// 设置本地视频渲染时使用的视图，并设置渲染模式。
engine.setLocalVideoPlayer(StreamIndex.STREAM_INDEX_MAIN, {
  renderDom: 'yourDomId'
});

4. 设置虚拟背景参数。

import { BackgroundMode } from '@volcengine/rtc/extension-beauty';

// ① 设置虚拟背景模式为背景模糊（默认）
extension.setBackgroundMode(BackgroundMode.BACKGROUND_BLUR);
// ② 或设置背景模式为背景图片
extension.setBackgroundMode(BackgroundMode.BACKGROUND_IMAGE);
extension.loadBackgroundImage('https://image_url');

5. 开启虚拟背景。

extension.enableVirtualBackground();

6. 关闭虚拟背景。

extension.disableVirtualBackground();

IRTCBeautyExtension

类型: interface

• API

方法	描述
checkCompatibility	测试当前浏览器兼容性情况。
enableVirtualBackground	开启虚拟背景。
disableVirtualBackground	关闭虚拟背景。
setBackgroundMode	设置虚拟背景模式。
getBackgroundImage	获取当前虚拟背景图片。背景模式为 BACKGROUND_IMAGE 时有效。
loadBackgroundImage	设置虚拟背景图片。背景模式为 BACKGROUND_IMAGE 时有效。
setAIModelType	设置虚拟背景使用的人像识别 AI 算法效果。
setBackgroundBlurRadius	设置模糊效果半径。背景模式为 BACKGROUND_BLUR 时有效。
setBackgroundColor	设置虚拟背景颜色，背景模式为 BACKGROUND_COLOR 时有效。
loadBackgroundVideo	设置背景视频。背景模式为 BACKGROUND_VIDEO 时有效。
getBackgroundVideo	获取背景视频的点播地址。背景模式为 BACKGROUND_VIDEO 时有效。

checkCompatibility

测试当前浏览器兼容性情况。

• 类型

  () => Promise<CompatibilityCheckResult>
  

• 返回值

  类型: Promise<CompatibilityCheckResult>

  兼容性测试结果。

enableVirtualBackground

开启虚拟背景。

• 类型

  () => void
  

• 注意

  • 调用 setBackgroundMode 设置虚拟背景模式。若在调用本方法前没有设置虚拟背景模式，则默认开启背景模糊。
  • 调用 disableVirtualBackground 关闭虚拟背景。
  • 本方法仅适用于视频源，不适用于屏幕源。

disableVirtualBackground

关闭虚拟背景。

• 类型

  () => void
  

setBackgroundMode

设置虚拟背景模式。

• 类型

  (mode: BackgroundMode) => void
  

• 注意

  开启虚拟背景后，可调用本方法动态切换使用的虚拟背景模式。

• 参数

  • mode

    类型: BackgroundMode

    虚拟背景模式。

getBackgroundImage

获取当前虚拟背景图片。背景模式为 BACKGROUND_IMAGE 时有效。

• 类型

  () => string
  

• 返回值

  类型: string

  当前虚拟背景图片 URL。

loadBackgroundImage

设置虚拟背景图片。背景模式为 BACKGROUND_IMAGE 时有效。

• 类型

  (url: string) => Promise<void>
  

• 注意

  • 支持的图片格式为 jpg、jpeg、png。
  • 图片和视频长宽比不一致时，为保证图片内容不变形，图片按短边缩放至与视频帧一致，使图片填满视频帧，对多出的高或宽进行剪裁。
  • 自定义图片带有局部透明效果时，透明部分由黑色代替。
  • 设置在插件的生命周期内有效。

• 参数

  • url

    类型: string

    虚拟背景图片 URL。

• 返回值

  类型: Promise<void>

setAIModelType

设置虚拟背景使用的人像识别 AI 算法效果。

• 类型

  (type: BackgroundAIModelType) => void
  

• 参数

  • type

    类型: BackgroundAIModelType

    人像识别 AI 算法效果。

setBackgroundBlurRadius

设置模糊效果半径。背景模式为 BACKGROUND_BLUR 时有效。

• 类型

  (radius: number) => void
  

• 注意

  设置在插件的生命周期内有效。

• 参数

  • radius

    类型: number

    模糊效果半径。单位为 px。默认模糊半径为 20 px。
    [0, ∞)，没有上限，当值超过视频长边一半时模糊效果将不再变化。比如，在 640*480 下，当设置超过 320 时效果不再变化。

setBackgroundColor

设置虚拟背景颜色，背景模式为 BACKGROUND_COLOR 时有效。

• 类型

  (color: string) => boolean
  

• 注意

  设置在插件的生命周期内有效。

• 参数

  • color

    类型: string

    RGBA(red, green, blue, alpha) 或 #RRGGBBAA
    比如，rgba(255, 255, 255, 1)。alpha 取值范围为 0（透明）到 1（不透明）。其余字段为0～255。
    比如，#FFFFFFFF。alpha 取值范围为 0（透明）到 1（不透明）。其余字段为 0～0xFF。

• 返回值

  类型: boolean

  • true：设置成功。
  • false：设置失败。

loadBackgroundVideo

设置背景视频。背景模式为 BACKGROUND_VIDEO 时有效。

• 类型

  (url: string) => Promise<void>
  

• 注意

  设置在插件的生命周期内有效。

• 参数

  • url

    类型: string

    虚拟背景视频 URL。

• 返回值

  类型: Promise<void>

  视频资源加载异常会通过 promise.reject() 抛出

getBackgroundVideo

获取背景视频的点播地址。背景模式为 BACKGROUND_VIDEO 时有效。

• 类型

  () => string
  

• 返回值

  类型: string

  虚拟背景视频 URL。

CompatibilityCheckResult

类型: interface

兼容性测试结果。

isCompatible

类型: boolean

是否兼容。

true：符合兼容性最低要求，可正常运行。
false：不兼容，无法正常运行。

reasons

类型: number[]

不兼容的原因。

• 0：其他未知原因。
• 1：系统不支持 getUserMedia API。
• 2：系统不支持 WebAssembly。
• 3：系统获取不到 video input 设备。
• 100：WebAR SDK 加载失败。

IRTCBeautyExtensionConfig

类型: interface

美颜和虚拟背景插件参数。

authFileUrl

类型: string

鉴权文件地址。

aiBackend

类型: BackgroundAIBackend

初始化时选择使用 CPU/GPU 模式，默认使用 CPU 模式。

aiModelType

类型: BackgroundAIModelType

人像识别 AI 算法效果。

BackgroundMode

类型: enum

虚拟背景模式。

• 成员

  属性	值	描述
  BACKGROUND_BLUR	'blur'	背景模糊。
  BACKGROUND_IMAGE	'image-url'	背景图片。
  BACKGROUND_COLOR	'color'	背景颜色。
  BACKGROUND_VIDEO	'video-url'	背景视频。

BackgroundAIModelType

类型: enum

人像识别 AI 算法效果。

• 成员

  属性	值	描述
  PERFORMANCE	'fast'	性能优先。
  QUALITY	'accurate'	效果优先。

BackgroundAIBackend

类型: enum

初始化时选择使用 CPU/GPU 模式，默认使用 CPU 模式。

• 成员

  属性	值	描述
  CPU	'cpu'	CPU 模式。
  GPU	'gpu'	GPU 模式。SDK 内部会自动判断当前环境是否支持开启 GPU 模式，对于不支持的环境会自动回退为 CPU 模式。