Virtual Background

enableVirtualBackground

Enables or disables the virtual background feature.

virtual int enableVirtualBackground(bool enabled, VirtualBackgroundSource backgroundSource, SegmentationProperty segproperty, agora::media::MEDIA_SOURCE_TYPE type = agora::media::PRIMARY_CAMERA_SOURCE) = 0;
Since
Available since v3.7.200.

The virtual background feature allows the local user to replace the original background with a static image, dynamic video, blurred background, or portrait segmentation to achieve a picture-in-picture effect. Once enabled, all users in the channel can see the customized background. Call this method after enableVideo or startPreview.

Note:
  • Using a video as a virtual background may cause continuous memory growth, potentially leading to app crashes. It is recommended to reduce the resolution and frame rate of the video.
  • This feature requires high device performance. When this method is called, the SDK automatically detects the device's performance. Agora recommends using the virtual background feature on the following processors:
    • Snapdragon 700 series 750G and above.
    • Snapdragon 800 series 835 and above.
    • Dimensity 700 series 720 and above.
    • Kirin 800 series 810 and above.
    • Kirin 900 series 980 and above.
    • Devices equipped with i5 CPUs and above.
    • Devices equipped with A9 chips and above, including:
      • iPhone 6S and above.
      • iPad Air 3rd generation and above.
      • iPad 5th generation and above.
      • iPad Pro 1st generation and above.
      • iPad mini 5th generation and above.
  • Agora recommends using this feature in the following scenarios:
    • Using a high-definition camera in evenly lit environments.
    • Few objects in the frame, with unobstructed upper-body portraits.
    • A solid color background that contrasts with the user's clothing.
  • This method depends on the virtual background dynamic library libagora_segmentation_extension.dll. If this dynamic library is deleted, the feature cannot be enabled properly.

Parameters

enabled
Whether to enable the virtual background:
  • true: Enable virtual background.
  • false: Disable virtual background.
backgroundSource
Custom background. The SDK scales and crops the custom background image to fit the captured video resolution while ensuring the image content is not distorted. See VirtualBackgroundSource.
segproperty
Processing properties of the background image. See SegmentationProperty.
type
The media source type to apply the filter effect to. See MEDIA_SOURCE_TYPE.
  • When using the camera to capture local video, use the default value PRIMARY_CAMERA_SOURCE.
  • When using a custom video source, set to CUSTOM_VIDEO_SOURCE.

Return Values

  • 0: Success.
  • < 0: Failure.
    • -4: The device performance does not meet the requirements for the virtual background feature. Try this feature on a higher-performance device.