# 虚拟背景 (/zh-CN/api-reference/rtc/electron/video/video-prenpro/virtualbackground)

> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).

<a id="toc_virtualbackground"></a>

<a id="api_irtcengine_enablevirtualbackground"></a>

<a id="ariaid-title2"></a>

## enableVirtualBackground [#enablevirtualbackground]

开启/关闭虚拟背景。

<a id="api_irtcengine_enablevirtualbackground__prototype"></a>

```ts
abstract enableVirtualBackground(
    enabled: boolean,
    backgroundSource: VirtualBackgroundSource,
    segproperty: SegmentationProperty,
    type?: MediaSourceType
  ): number;
```

<a id="api_irtcengine_enablevirtualbackground__detailed_desc"></a>

虚拟背景功能支持将本地用户原来的背景替换为静态图片、动态视频、将背景虚化，或者将人像与背景分割以实现人像画中画。成功开启虚拟背景功能后，频道内所有用户都能看到自定义的背景。
请在 [enableVideo](/zh-CN/api-reference/rtc/electron/video/video-basic#api_irtcengine_enablevideo) 或 [startPreview](/zh-CN/api-reference/rtc/electron/video/video-basic#api_irtcengine_startpreview2) 之后调用该方法。

:::note
注：

- 使用视频作为虚拟背景会导致内存占用持续增加，可能会导致 App 出现闪退等问题，因此在使用时请尽量降低视频的分辨率和帧率。
- 该功能对设备性能要求较高，调用该方法时 SDK 会自动对当前设备能力进行检查。建议你在搭载如下芯片的设备上使用：

  - CPU 为 i5 及更好的设备
- 建议你在满足如下条件的场景中使用该功能：

  - 使用高清摄像设备、摄像环境光照均匀。
  - 摄像画面中，物件较少，用户的人像为半身人像且基本无遮挡，背景色较单一且与用户着装颜色不同。
- 该方法依赖于虚拟背景动态库 `libagora_segmentation_extension.dll`，如果删除该动态库会导致无法正常开启该功能。
:::

<a id="api_irtcengine_enablevirtualbackground__parameters"></a>

### 参数 [#参数]

<ParameterList>
<a id="enabled"></a>
<Parameter name="enabled">

是否开启虚拟背景：

- true: 开启虚拟背景。
- false: 关闭虚拟背景。

</Parameter>
<a id="backgroundsource"></a>
<Parameter name="backgroundSource">

自定义的背景。详见 [VirtualBackgroundSource](/zh-CN/api-reference/rtc/electron/class-virtualbackgroundsource)。为将自定义背景图的分辨率与 SDK 的视频采集分辨率适配，SDK 会在保证自定义背景图不变形的前提下，对自定义背景图进行缩放和裁剪。

</Parameter>
<a id="segproperty"></a>
<Parameter name="segproperty">

背景图像的处理属性。详见 [SegmentationProperty](/zh-CN/api-reference/rtc/electron/class-segmentationproperty)。

</Parameter>
<a id="type"></a>
<Parameter name="type">

效果应用的媒体源类型。详见 [MediaSourceType](/zh-CN/api-reference/rtc/electron/enum-mediasourcetype)。

:::note
注： 在该方法中，该参数仅支持以下两种设置：

- 使用摄像头采集本地视频时，请保持默认值 `PrimaryCameraSource`。
- 如果要使用自定义采集的视频，将该参数设置为 `CustomVideoSource`。
:::

</Parameter>
</ParameterList>

<a id="api_irtcengine_enablevirtualbackground__return_values"></a>

### 返回值 [#返回值]

- 0: 方法调用成功。
- &lt; 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

  - -4：设备能力不满足虚拟背景的使用要求，建议更换性能更高的设备。

### 所属接口类 [#所属接口类]

- [IRtcEngine](/zh-CN/api-reference/rtc/electron/rtc-interface-class#class_irtcengine)