虚拟背景
更新时间: 2024/08/05 15:02:55
在音视频会议或教育场景中,为了突出人像或者保护隐私,用户往往不希望将视窗的背景呈现出来。为了帮助用户隐藏周围的真实场景,NERTC SDK 支持开启背景分割,帮助开发者轻松实现虚拟背景功能,包括背景替换、背景虚化等。
功能介绍
网易云信提供虚拟背景插件 VirtualBackground
,可以与核心 SDK 搭配使用。支持通过开启虚拟背景功能,将用户人像和背景分割开来,虚化用户周围的真实环境,或者以自定义背景色或背景图像替换真实背景。
仅 v4.6.20 及之后版本的 NERTC Web SDK 支持此功能,请前往网易云信 SDK 下载中心获取最新版本 SDK。
前提条件
在实现虚拟背景功能前,请确保已在您的项目中实现基本的实时音视频功能。
注意事项
- 该插件与核心 SDK 独立,在注册时需配置插件地址。
- 虚拟背景功能暂时仅支持桌面端 Chrome 浏览器和 Safari 浏览器(建议 15.4+),暂不兼容 Firefox 浏览器。
- 若您的开发环境中使用了 babel 插件,您需要在
babel.config.js
文件中增加exclude: /NIM_Web_NERTC/
。 - 背景分割的计算和渲染处理属于实时计算密集型操作,此操作过程中存在较大的 GPU 和 CPU 开销,因此建议在配有 i5-8500 及以上高性能处理器的设备上使用此功能,且建议使用的分辨率为 640 * 480,帧率为 15 fps。若用户的设备使用了更高性能的 GPU,可以适当提高分辨率或帧率;但若用户的设备性能不足以支撑运算,可能会导致帧率下降等问题。
- 若同时启用屏幕共享与虚拟背景功能,会影响虚拟背景帧率,因此建议不要在较低性能的设备上同时开启。
- 若用户需要立即开启虚拟背景,建议在虚拟背景插件加载后,即在收到
on('plugin-load')
事件回调后,在回调事件中调用enableBodySegment
方法。 - 该功能支持预设背景参数。配置方法为插件加载后先调用
setBackGround
方法设置背景参数,再调用enableBodySegment
方法启用背景分割,即开启虚拟背景功能。用户也可以在音视频通话过程中,实时调整相关参数。
配置步骤
-
调用
createStream
方法创建并返回一个本地音视频流对象。调用
createStream
创建媒体流之前,需要通过getDevices
方法获取麦克风和摄像头设备的 deviceId。详细说明请参考音视频设备检测。 -
调用
registerPlugin
方法并配置pluginOptions
参数注册虚拟背景插件,其中pluginOptions = {key: 'VirtualBackground', pluginUrl: string, pluginObj: Object, wasmUrl: string}
,相关字段的具体说明如下:key
:VirtualBackground
,必填,表示虚拟背景插件。pluginUrl
:可选,插件的 CDN 地址。支持自定义 URL,也可使用默认地址https://yx-web-nosdn.netease.im/sdk-release/NIM_Web_VirtualBackground_v4.6.20.js
。pluginObj
:可选,插件对象。请通过 npm 方式安装,具体安装方式请参考下方说明。wasmUrl
:必填,插件依赖的 wasm 文件地址。官网的 SDK 包以及 npm 包均提供原文件,可以部署到您自己本地的服务器中;也可以使用https://yx-web-nosdn.netease.im/sdk-release/NIM_Web_VirtualBackground_simd_v4.6.20.wasm
或https://yx-web-nosdn.netease.im/sdk-release/NIM_Web_VirtualBackground_nosimd_v4.6.20.wasm
。
- 虚拟背景插件提供 simd 版本和非 simd 版本,建议使用 simd 版本以体验更佳的性能。关于您的浏览器是否支持 simd 版本的插件,请参考
wasm-feature-detect
。 - 必须传入
pluginUrl
和pluginObj
的其中一项。 - 安装
pluginObj
的代码如下://第一步 npm install nertc-web-sdk //第二步 import VirtualBackground from 'nertc-web-sdk/NERTC_Web_SDK_VirtualBackground'
- 若您选择通过 npm 安装插件,您在安装后可在
nertc-web-sdk/wasm
路径下的文件夹中找到NERTC_Web_SDK_VirtualBackground_simd.wasm
和NERTC_Web_SDK_VirtualBackground_nosimd.wasm
文件,该文件可部署到您自己本地的服务器中,并将部署后的文件地址通过wasmUrl
参数传递给 SDK。
-
在本端监听
on('plugin-load')
和on('plugin-load-error')
事件,以判断虚拟背景插件是否加载成功。若因插件注册失败触发了
on('plugin-load-error')
回调,请关注返回的event
结构里的msg
详细字段:Load {wasmUrl} error
:wasm 加载失败,需要检查 URL 地址。unsupport plugin {key}
:不支持该插件,需要检查key
参数和pluginUrl/pluginObj
是否匹配。Load plugin ${pluginUrl} error
:pluginUrl 加载失败。
-
在触发
onPluginLoaded
回调后,调用enableBodySegment
方法启用虚拟背景功能,并调用setBackGround
方法通过backGround
参数设置虚拟背景属性,相关字段的具体说明如下:-
设置背景图片为纯色图像(默认):您需要设置
type
字段为color
;并设置color
字段自定义图像颜色,该参数的取值范围为 #000000 ~ #FFFFFF,默认值为 #E7AD3C。 -
设置背景图片为自定义图片:您需要设置
type
字段为image
;并设置source
字段为自定义背景图片的对象。
source
字段支持 image 对象、url 和 base64 编码。- 设置背景虚化:您需要设置
type
字段为blur
;并通过level
字段设置虚化等级,该数值越高代表虚化程度越高,建议取值范围为 1 ~ 10。
-
-
若您需要取消虚拟背景效果,请调用
disableBodySegment
方法关闭背景分割进程。 -
若您需要销毁虚拟背景插件,请调用
unregisterPlugin(key)
方法销毁插件。
示例代码
使用虚拟背景的基础流程对应的示例代码如下:
// 创建本端stream实例
rtc.localStream = NERTC.createStream({
uid: uid, // 本端的uid
audio: true, // 是否从麦克风采集音频
microphoneId: microphoneId, // 麦克风设备 deviceId,通过 getMicrophones() 获取
video: true, // 是否从摄像头采集视频
cameraId: cameraId // 摄像头设备 deviceId,通过 getCameras() 获取
});
//注册虚拟背景插件
rtc.localStream.registerPlugin(pluginOptions)
const pluginOptions = {
key: 'VirtualBackground', //插件名
pluginUrl: 'https://yx-web-nosdn.netease.im/sdk-release/NIM_Web_VirtualBackground_v4.6.20.js', //插件NIM_Web_VirtualBackground.js地址
wasmUrl: 'https://yx-web-nosdn.netease.im/sdk-release/NIM_Web_VirtualBackground_nosimd_v4.6.20.wasm', //插件依赖的NIM_Web_VirtualBackground.wasm文件地址
}
//注册plugin-load事件,当插件初始化完成后回调onPluginLoaded
rtc.localStream.on('plugin-load', onPluginLoaded);
//插件注册失败时触发,event结构:{key: 插件名,msg: 详细信息}
rtc.localStream.on('plugin-load-error', event);//具体参考信息见上文配置步骤
function onPluginLoaded(name: String) {
if (name == 'VirtualBackground') {
//在此处可立即调用enableBodySegment
}
}
//打开虚拟背景
rtc.localStream.enableBodySegment()
//设置虚拟背景参数
let options = {type: 'color', color: '#ff0000'}
rtc.localStream.setBackGround(options)
//关闭虚拟背景
rtc.localStream.disableBodySegment()
//销毁插件,销毁之后如果需要使用插件则需再次注册
rtc.localStream.unregisterPlugin(pluginKey)
API 参考
方法 | 功能描述 |
---|---|
registerPlugin |
注册虚拟背景插件。 |
createStream |
创建并返回音视频流对象。 |
enableBodySegment |
初始化背景分割进程。 |
setBackGround |
设置虚拟背景属性。 |
disableBodySegment |
关闭背景分割进程。 |
unregisterPlugin(key) |
销毁虚拟背景插件。 |