Virtual Background

enableVirtualBackground [1/2]

Enables or disables the virtual background feature.

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

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 picture-in-picture effects. 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 following processors:
    • Snapdragon 700 series 750G or above.
    • Snapdragon 800 series 835 or above.
    • Dimensity 700 series 720 or above.
    • Kirin 800 series 810 or above.
    • Kirin 900 series 980 or above.
  • Agora recommends using this feature in the following scenarios:
    • When using high-definition camera devices with even lighting.
    • When there are few objects in the frame, and the portrait is a half-body shot with no obstructions.
    • When the background is a solid color and clearly different from the user's clothing.
  • This method depends on the virtual background dynamic library libagora_segmentation_extension.so. If the library is deleted, the feature cannot be enabled.

Parameters

enabled
Whether to enable the virtual background:
  • true: Enable virtual background.
  • false: Disable virtual background.
backgroundSource
The custom background. To adapt the resolution of the custom background image to the video resolution captured by the SDK, the SDK scales and crops the image to ensure no distortion. See VirtualBackgroundSource.
segproperty
The processing properties of the background image. See SegmentationProperty.

Return Values

  • 0: Success.
  • < 0: Failure.
    • -4: The device does not meet the performance requirements for the virtual background feature. Agora recommends using a higher-performance device.

enableVirtualBackground [2/2]

Enables virtual background and specifies the media source, or disables the virtual background.

public abstract int enableVirtualBackground(boolean enabled, VirtualBackgroundSource backgroundSource, SegmentationProperty segproperty, Constants.MediaSourceType sourceType);

This method enables or disables the virtual background feature. You can 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. This method provides the same functionality as enableVirtualBackground [1/2], but allows you to specify the media source type for applying the virtual background. Call this method after calling enableVideo or startPreview.

Note:
  • Using video as a virtual background may cause continuous memory growth, potentially leading to application crashes. It is recommended to reduce the resolution and frame rate of the video.
  • This feature requires high device performance. When calling this method, the SDK automatically checks the device's capability. Agora recommends using this 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.
  • Agora recommends using this feature in the following scenarios:
    • Using a high-definition camera device with even lighting.
    • Few objects in the frame, with a half-body portrait unobstructed.
    • A solid color background that contrasts with the user’s clothing.
  • This method depends on the virtual background dynamic library libagora_segmentation_extension.so. If the library is deleted, the feature cannot be enabled properly.

Parameters

enabled
Whether to enable the virtual background:
  • true: Enable the virtual background.
  • false: Disable the virtual background.
backgroundSource
The custom background. The SDK scales and crops the custom background image to fit the captured video resolution and ensures the image content is not distorted. See VirtualBackgroundSource.
segproperty
The processing properties of the background image. See SegmentationProperty.
sourceType
The media source type to apply the filter effect. See MediaSourceType.
Note: In this method, the parameter only supports the following two values:
  • Default is PRIMARY_CAMERA_SOURCE.
  • If using a custom video source, set this parameter to CUSTOM_VIDEO_SOURCE.

Return Values

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