Docs Overview/
RTC Engine/
SDK/
Web/
高级功能/
启用虚拟背景/

启用虚拟背景

功能描述

本文将介绍如何在通话过程中实现虚拟背景的功能。
原始摄像头
背景虚化
背景图片










前提条件

需要使用虚拟背景功能的 SdkAppId 已开通 RTC Engine 包月套餐包 Pro版（1499美元/月）。
TRTC Web SDK 版本 ≥ 5.5.0
各平台系统及配置要求如下表：
平台
操作系统
浏览器版本
fps
推荐配置
备注
Web
Windows
Chrome 90+Firefox 90+Edge 97+
30
内存：16GBCPU：i5-10500GPU：独显 2GB
建议使用最新版 Chrome 浏览器 （开启浏览器硬件加速）
15
内存：8GBCPU：i3-8300GPU：intel 核显 1GB
Mac
Chrome 98+Firefox 96+Safari 14+
30
2019年 MacBook内存：16GB(2667MHz)CPU：i7(6核 2.60GHz)GPU：AMD Radeon 5300M
Android
ChromeFirefox Browser
30
High-end devices (e.g., Qualcomm Snapdragon 8 Gen1)
建议使用Chrome、火狐浏览器等主流浏览器
20
Mid-range devices (e.g., MediaTek Dimensity 8000-MAX)
10
Low-end devices (e.g., Qualcomm Snapdragon 660)
iOS
ChromeSafariFirefox
30
iPhone 13
- 需要 iOS 14.4 或以上版本 - 建议使用 Chrome 或 Safari 浏览器
20
iPhone XR

实现流程

引入并注册插件

import { VirtualBackground } from 'trtc-sdk-v5/plugins/video-effect/virtual-background';

let trtc = TRTC.create({ plugins: [VirtualBackground] });

开启本地摄像头

await trtc.startLocalVideo();

开启虚拟背景插件

await trtc.startPlugin('VirtualBackground', {
  sdkAppId: 123123,
  userId: 'userId_123',
  userSig: 'your_userSig'
});
注意：
第一次开启本功能需要加载计算资源，已经帮您自动处理。如需获得更极致的启动体验，请参见文末：常见问题 > 如何加快启动速度？

按需更新参数

// 改为图片背景
await trtc.updatePlugin('VirtualBackground', {
  type: 'image',
  src: 'https://picsum.photos/seed/picsum/200/300'
});

关闭虚拟背景

await trtc.stopPlugin('VirtualBackground');

API 说明

trtc.startPlugin('VirtualBackground', options)

用于开启虚拟背景。

options

Name
Type
Attributes
Description
sdkAppId
number
必填
当前应用 ID
userId
string
必填
当前用户 ID
userSig
string
必填
用户 ID 对应的 UserSig
type
string
选填
image 图片背景
blur 虚化背景（默认）
src
string
type 为 image 时必填
图片地址，如 https://picsum.photos/seed/picsum/200/300
onError
(error) => {}
选填
运行过程中发生错误的回调
error.code=10000003 渲染耗时长
error.code=10000006 浏览器特性支持不足，可能会出现卡顿情况
推荐处理方法可参考文末常见问题
Example:
await trtc.startPlugin('VirtualBackground', {
  sdkAppId: 123123,
  userId: 'userId_123',
  userSig: 'your_userSig',
  type: 'image',
  src: 'https://picsum.photos/seed/picsum/200/300'
});

trtc.updatePlugin('VirtualBackground', options)

可修改虚拟背景参数

options

Name
Type
Attributes
Description
type
string
必填
image 图片背景
blur 虚化背景
src
string
type 为 image 时必填
图片地址，如 https://picsum.photos/seed/picsum/200/300
Example:
await trtc.updatePlugin('VirtualBackground', {
  type: 'blur'
});

trtc.stopPlugin('VirtualBackground')

关闭虚拟背景

常见问题

在 Chrome 中运行 Demo 发现画面颠倒且卡顿？

本插件使用 GPU 进行加速，您需要在浏览器设置中找到使用硬件加速模式并启用。可以将 chrome://settings/system 复制到浏览器地址栏，并且打开硬件加速模式。

当设备性能不足造成延迟高，提示渲染耗时长？

可通过监听事件，降低视频分辨率或者帧率。
async function onError(error) {
  const { code } = error;
  if (code === 10000003 || code === 10000006) {
    // 降低分辨率帧率
    await trtc.updateLocalVideo({
      option: {
        profile: '480p_2'
      },
    });
    // await trtc.stopPlugin('VirtualBackground'); // 或者关闭插件
  }
}

await trtc.startPlugin('VirtualBackground', {
  ...// 其他参数
  onError,
});

如何加快启动速度？（手动部署虚拟背景模型文件）

本插件的原理为：采集到摄像头后，在本地通过机器学习模型进行人像分割，然后将结果上行到后台传输。
第一次启用时，会自动从腾讯云 CDN 下载机器学习模型，但腾讯云 CDN 与您网页的静态文件地址是非同源的，会降低部分加载速度。最佳方案是将模型文件部署在您自己的静态资源服务器上，比如跟网页服务部署在一起。
加速方法很简单，将 assets.zip 解压到您的项目中，如 ./src/assets/，并且在创建 TRTC 实例时，指定这个地址：
const trtc = TRTC.create({ plugins: [VirtualBackground], assetsPath: './src/assets/' });