音视频通话

虚拟背景

功能介绍

SDK 内置虚拟背景，可在音视频通话或互动直播中对本端摄像头画面的人像与背景进行分割与替换，支持纯色背景、图片背景及背景模糊等效果。

通过 CRVideo_SetVirtualBackground 统一完成开启、更新与关闭；接口返回 Promise，errCode 为 0 表示成功。

type 效果
0 关闭虚拟背景
1 纯色背景（color）
2 图片背景（image）
3 保留原画面，可配合 blurIntensity 做背景模糊

配置字段详见 CRVideo_VirtualBgCfg。

注意：

须在成功进入房间后，方可设置虚拟背景。

须事先通过 CRVideo_SetSDKParams 配置 virtualBackgroundAssets（人像分割模型资源目录，不是背景图片 URL）；首次开启时 SDK 自动加载模型。

须联系商务为账号开通虚拟背景权限；未开通或房间未下发人像分割权限时，接口可能返回 errCode 806。

仅对默认摄像头生效（stream / canvas 摄像头不支持），可通过 CRVideo_SetDefaultVideo 切换默认设备，详见 视频设备管理。

人像分割依赖浏览器 WebGL；开启后 CPU 开销较大，采集分辨率越高开销越大。

1. 开通虚拟背景功能授权

联系商务经理，为所用账号开通虚拟背景功能授权。

2. 加载人像分割模型资源

启动虚拟背景前，需部署 SDK 包内 VirtualBackgroundSource 目录（人像分割模型及相关脚本），并设置加载路径：

  1. 基础方案：将 VirtualBackgroundSource 拷贝到项目静态资源目录，使用相对路径；
  2. 推荐方案：部署至 CDN，使用绝对 URL（便于版本更新与跨域部署）。

在 SDK 初始化阶段（或首次调用虚拟背景之前）调用 CRVideo_SetSDKParams：

CRVideo_SetSDKParams({
  virtualBackgroundAssets: "../SDK/VirtualBackgroundSource",
  // ...
});

也可使用公共 CDN 路径（需保证资源可访问），例如 @mediapipe/selfie_segmentation 对应目录。

相关 API 请参考：

3. 开启虚拟背景

调用 CRVideo_SetVirtualBackground，传入 CRVideo_VirtualBgCfg 配置对象。

纯色背景（type = 1）示例：

const sdkErr = await CRVideo_SetVirtualBackground({
  type: 1,
  color: "#17dc06",
  blurIntensity: 0,
});
if (sdkErr == 0) {
  // 开启成功
} else if (sdkErr == 806) {
  // 未开通权限或未下发人像分割权限
}

图片背景（type = 2）示例：

image 须为已加载完成的 Image 实例或页面中的 <img> 元素，不能直接传图片 URL 字符串。

var image = new Image();
image.src = "picture.jpg";
image.onload = async () => {
  const sdkErr = await CRVideo_SetVirtualBackground({
    type: 2,
    image,
    blurIntensity: 0,
  });
};

背景模糊（type = 3）示例：

await CRVideo_SetVirtualBackground({
  type: 3,
  blurIntensity: 50, // 0～100，0 表示不模糊
});

blurIntensity 在 type 为 1、2、3 时均可使用，用于控制背景模糊强度。

相关 API 请参考：

4. 更新虚拟背景参数

再次调用 CRVideo_SetVirtualBackground，传入新的配置即可切换背景类型、颜色、图片或模糊程度，无需先关闭再开启。

await CRVideo_SetVirtualBackground({
  type: 1,
  color: "#3333bb",
  blurIntensity: 30,
});

相关 API 请参考：

5. 关闭虚拟背景

将 type 设为 0 即可关闭：

await CRVideo_SetVirtualBackground({ type: 0 });

可选参数 destroy（默认 true）：为 true 时释放人像分割相关资源；为 false 时保留资源，下次开启速度更快，但占用更多内存。仅当 type 为 0 时有效。

await CRVideo_SetVirtualBackground({ type: 0, destroy: false });

相关 API 请参考：

相关文档