Enables/Disables the virtual background.

public abstract int enableVirtualBackground(
      boolean enabled, VirtualBackgroundSource backgroundSource, SegmentationProperty segproperty);


The virtual background feature enables the local user to replace their original background with a static image, dynamic video, blurred background, or portrait-background segmentation to achieve picture-in-picture effect. Once the virtual background feature is enabled, all users in the channel can see the custom background.

Call this method before calling enableVideo or startPreview [2/2].

  • This feature has high requirements on device performance. When calling this method, the SDK automatically checks the capabilities of the current device. Agora recommends you use virtual background on devices with the following processors:
    • Snapdragon 700 series 750G and later
    • Snapdragon 800 series 835 and later
    • Dimensity 700 series 720 and later
    • Kirin 800 series 810 and later
    • Kirin 900 series 980 and later
  • Agora recommends that you use this feature in scenarios that meet the following conditions:
    • A high-definition camera device is used, and the environment is uniformly lit.
    • There are few objects in the captured video. Portraits are half-length and unobstructed. Ensure that the background is a solid color that is different from the color of the user's clothing.
  • This method relies on the virtual background dynamic library libagora_segmentation_extension.so. If the dynamic library is deleted, the function cannot be enabled normally.


Whether to enable virtual background:
  • true: Enable virtual background.
  • false: Disable virtual background.
The custom background. See VirtualBackgroundSource. To adapt the resolution of the custom background image to that of the video captured by the SDK, the SDK scales and crops the custom background image while ensuring that the content of the custom background image is not distorted.
Processing properties for background images. See SegmentationProperty.


  • 0: Success.
  • < 0: Failure.
    • -4: The device capabilities do not meet the requirements for the virtual background feature. Agora recommends you try it on devices with higher performance.