实时音视频
实时音视频
- 文档首页
实时音视频实时音视频开发指南视频管理虚拟背景Web 端虚拟背景
文档反馈
问问助手Web RTC SDK 提供虚拟背景插件，在互动直播、视频会议、在线授课等场景下，可将用户人像和背景分离，采用模糊背景或自定义图片作为虚拟背景，从而避免杂乱背景对观众的影响，保护用户隐私，呈现较高的视频效果。你可以参考本文，实现这一功能。
自 Web SDK v4.52 起，本功能可用。
自 v4.53 版本起，支持在初始化时选择使用 GPU 模式。
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'。
- 在
- 新增了视频和纯色背景。
- 设置为模糊背景时支持自定义模糊半径。
本功能需付费使用，请联系技术支持团队获取符合业务功能需求的鉴权文件。
RTC SDK v4.52+ 你需要集成 RTC SDK，并实现音视频通话功能。
不建议在移动端使用本功能。这是由于本功能依赖一些 WASM 文件，对移动端设备的性能要求较高。
为了更好的使用体验，建议设备满足以下要求：
双核 Intel Core i5+
RAM 8 GB+
64 位操作系统
如果你使用了云代理功能，你需要在防火墙白名单中添加虚拟背景域名，参看在防火墙限制下进行通话。
在你的项目中引入虚拟背景插件，可直接引入或通过 UMD 方式引入。
- 直接引入
import RTCBeautyExtension from '@volcengine/rtc/extension-beauty';- 通过 UMD 方式引入
const {BackgroundMode, RTCBeautyExtension} = window.VERTCExtensions;注册虚拟背景插件。
注意
注册插件后，无法动态修改视频流帧率。你可以在注册插件前调用 setVideoEncoderConfig 修改帧率。
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 }
- 开始视频采集，并设置渲染视图及模式。 示例代码以内部采集为例，如需使用外部采集，参看 setVideoSourceType。
注意
虚拟背景仅对主流、本地流生效，不支持屏幕流、远端流。即 StreamIndex 必须为 STREAM_INDEX_MAIN。
// 开启内部视频采集 engine.startVideoCapture(); // 设置本地视频渲染时使用的视图，并设置渲染模式。 engine.setLocalVideoPlayer(StreamIndex.STREAM_INDEX_MAIN, { renderDom: 'yourDomId' });
- 设置虚拟背景参数。
import { BackgroundMode } from '@volcengine/rtc/extension-beauty'; // ① 设置虚拟背景模式为背景模糊（默认） extension.setBackgroundMode(BackgroundMode.BACKGROUND_BLUR); // ② 或设置背景模式为背景图片 extension.setBackgroundMode(BackgroundMode.BACKGROUND_IMAGE); extension.loadBackgroundImage('https://image_url');
- 开启虚拟背景。
extension.enableVirtualBackground();
- 关闭虚拟背景。
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
人像识别 AI 算法效果。
setBackgroundBlurRadius
设置模糊效果半径。背景模式为 BACKGROUND_BLUR 时有效。
类型
(radius: number) => void注意
设置在插件的生命周期内有效。
参数
radius
类型:
number模糊效果半径。单位为 px。默认模糊半径为 20 px。
[0, ∞)，没有上限，当值超过视频长边一半时模糊效果将不再变化。比如，在 640*480 下，当设置超过 320 时效果不再变化。
setBackgroundColor
设置虚拟背景颜色，背景模式为 BACKGROUND_COLOR 时有效。
类型
(color: string) => boolean注意
设置在插件的生命周期内有效。
参数
color
类型:
stringRGBA(red, green, blue, alpha) 或 #RRGGBBAA
比如，rgba(255, 255, 255, 1)。alpha 取值范围为0（透明）到1（不透明）。其余字段为0～255。
比如，#FFFFFFFF。alpha 取值范围为0（透明）到1（不透明）。其余字段为 0～0xFF。
返回值
类型:
booleantrue：设置成功。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
初始化时选择使用 CPU/GPU 模式，默认使用 CPU 模式。
aiModelType
人像识别 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 模式。