Skip to main content
虚拟背景在摄像头采集链路上做人像分割,把人像之外的区域替换成虚化或指定图片。它是自研组件,装载不需要授权密钥
接口挂在 SMeetingEngine 上,但状态是设备级的:虚拟背景作用于进程内唯一的共享摄像头采集链路,设置会同时作用于全部会议与频道。同时加入多个房间时,不存在「只给某一个房间开虚拟背景」的用法。会中切换摄像头、关掉摄像头再打开、断线重连后都不需要自己补——效果由采集链路每帧现取,轨道重建不会把它丢掉。
1.3.0 起最低系统要求抬到 iOS 16.0 / macOS 14.0(此前为 iOS 13 / macOS 10.15)。低于此下限的工程解析不到 1.3.0 及以后的版本,详见 集成方式推理运行时 onnxruntime 已静态链入音视频层的 SRTC.xcframework,你不需要额外声明任何依赖。

step 1:装载虚拟背景组件

建议在需要用到虚拟背景前装载,例如进入会议页面时。modelPathnil 使用 SDK 内置的人像分割模型。
抛出的错误(来自音视频层的 SRTCError):

step 2:设置背景效果

背景虚化与背景替换互斥,后调用的生效。两个接口在装载前调用也会被记住,装载完成后自动生效,因此不必关心与 installVirtualBackground() 的先后顺序。
SRTCNativeImage 是平台原生图片类型的别名(iOS 上是 UIImage、macOS 上是 NSImage)。

step 3:开启或关闭虚拟背景

装载后默认不开启,需要显式打开。关闭后是零开销直通,不再跑推理。
组件未装载时调用开关会抛 virtualBackgroundNotInstalled。关闭时会清掉帧间状态,下次开启从首帧重新收敛,不会闪出过期蒙版。
虚拟背景是本地预处理,与会议状态无关:入会前、入会后都能设,也不受主持人静音/关摄像头等权限动作影响。摄像头没开时设置同样会被记住,开了摄像头就能看到效果。

step 4:低端机保帧率(可选)

默认每帧都跑一次人像分割。低端机上可以调大推理间隔,用蒙版复用换帧率;此时再按需打开蒙版对齐消除拖影。
inferenceInterval1 时,setVirtualBackgroundMaskSync(_:) 开与不开没有任何区别——它只在调大推理间隔后才起作用。

step 5:卸载虚拟背景组件

不再使用时卸载,释放推理会话与相关缓冲。已设置的效果参数不会被清掉,下次装载后仍然生效。

出错时丢帧,不会闪出真实背景

分割失败或输出缓冲池被耗尽时,SDK 丢掉这一帧,而不是把未处理的摄像头原始画面送出去——那会把真实背景闪给其它成员。代价是对端看到画面短暂卡顿。 丢帧计数与只读状态都在 meeting.virtualBackground 上(droppedFrameCountisInstalledisEnabledeffectblurLevel),可用于把面板控件回填成 SDK 的真实状态:

本地预览与推流的一致性

虚拟背景开启时,本地预览显示的就是处理后的画面,与其它成员看到的是同一份数据;关闭后本地预览回到摄像头原始画面。 更底层的用法(把虚拟背景挂到自定义视频轨道、自己接管采集时清帧间状态)见音视频层的 虚拟背景

相关页面