文档中心

实时音视频

虚拟背景

Native 端虚拟背景

Native 端虚拟背景

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

前提条件

你已经集成了 3.50 及以上版本的 RTC SDK，并实现音视频通话功能。

调用背景分割接口前，你需要联系智能美化特效（CV）商务人员，获取 CV 许可证和背景分割模型和素材。背景分割依赖智能美化特效实现，因此你需要集成特效 SDK，集成方式参看智能美化特效（付费版）。

对于移动端，需要确保 CV 许可证和 CV 资源被拷贝至 App 内，安卓端需要将 CV 资源拷贝至外部存储后方可使用。

操作步骤

以 Android 平台为例：

检查 CV 许可证，并设置算法模型。证书路径为 *.licbag 文件的绝对路径，算法模型路径为 ModelResource.bundle 的绝对路径。

IVideoEffect mVideoEffect = mRTCVideo.getVideoEffectInterface();
mVideoEffect.initCVResource("## 授权证书绝对路径 ##", "## 算法模型文件夹路径 ##")

此步骤可能返回的错误码及应对方式如下：

initCVResource 返回的错误码	错误码含义	排查措施
0	集成特效 SDK 成功，可进行下一步操作	无
–1000	特效 SDK 集成失败	参照智能美化特效（付费版）检查集成方式
–121	授权证书路径不存在	检查授权证书是否拷贝到该参数指定的路径
–119	授权证书和包名不匹配	检查授权证书绑定的包名是否和当前 app 包名一致
–117	授权证书已过期	更新授权证书
其他错误码	参看错误码表

initCVResource 调用成功后，你可以开启虚拟背景，虚拟背景支持纯色背景和图片背景。

a. 开启纯色背景

VirtualBackgroundSource source = new VirtualBackgroundSource();
// 选择纯色背景
source.sourceType = VirtualBackgroundSourceType.COLOR;
// 设置背景颜色，背景颜色格式为 0xAARRGGBB，例如绿色
source.sourceColor = 0XFF00FF00;
// 开启纯色背景
IVideoEffect mVideoEffect = mRTCVideo.getVideoEffectInterface();
mVideoEffect.enableVirtualBackground("## 背景贴纸素材绝对路径 ##", source);

b. 开启图片背景

VirtualBackgroundSource source = new VirtualBackgroundSource();
// 选择图片背景
source.sourceType = VirtualBackgroundSourceType.IMAGE;
// 设置背景图片绝对路径
source.sourcePath = "/storage/emulated/0/Download/test.png";
// 开启图片背景
IVideoEffect mVideoEffect = mRTCVideo.getVideoEffectInterface();
mVideoEffect.enableVirtualBackground("## 背景贴纸素材绝对路径 ##", source);

c. 关闭虚拟背景

// 关闭虚拟背景
IVideoEffect mVideoEffect = mRTCVideo.getVideoEffectInterface();
mVideoEffect.disableVirtualBackground();

d. 切换虚拟背景

VirtualBackgroundSource source = new VirtualBackgroundSource();
// 选择图片背景
source.sourceType = VirtualBackgroundSourceType.IMAGE;
// 设置背景图片绝对路径
source.sourcePath = "/storage/emulated/0/Download/test.png";
// 设置背景颜色，例如绿色
source.sourceColor = 0XFF00FF00;
// 开启图片背景
IVideoEffect mVideoEffect = mRTCVideo.getVideoEffectInterface();
mVideoEffect.enableVirtualBackground("## 背景贴纸素材绝对路径 ##", source);
// 切换到绿色背景
source.sourceType = VirtualBackgroundSourceType.COLOR;
mVideoEffect.enableVirtualBackground("## 背景贴纸素材绝对路径 ##", source);

此步骤可能返回的错误码及应对方式如下：

enableVirtualBackground 返回的错误码	错误码含义	排查措施
0	虚拟背景成功开启	无
–2	背景素材路径不存在	检查虚拟背景素材路径是否正确
–4	背景图片打开失败	检查背景图片路径是否有效
–38	背景图片格式不支持	检查背景图片后缀是否为 jpg、png
–37	背景图片数据损坏	检查背景图片的内容
其他错误码	参看错误码表

API 参考

Android

initCVResource

enableVirtualBackground

disableVirtualBackground

iOS

initCVResource:withAlgoModelDir:

enableVirtualBackground:withSource:

disableVirtualBackground

Windows

initCVResource

enableVirtualBackground

disableVirtualBackground

最近更新时间：2026.08.04 14:36:36

这个页面对您有帮助吗？

有用

有用

无用

无用