# Virtual Background (/en/realtime-media/marketplace/build/add-video-and-ar-effects/virtual-background) > For AI agents: see the complete documentation index at [llms.txt](/llms.txt). Virtual Background enables users to blur their background, or replace it with a solid color or an image. This feature is applicable to use-cases such as online conferences, online classes, and live streaming. It helps protect personal privacy and reduces audience distraction. <_PlatformTabsGroup groupMode="structured" canonicalPlatform="web" platforms="["android","ios","web","windows","electron","flutter","react-native","unity"]" showTabs="true"> <_PlatformPanel platform="android"> <_PlatformProcessedMarker groupMode="structured" canonicalPlatform="web" platform="android" /> ## Understand the tech [#understand-the-tech] Virtual Background offers the following options: | Feature | Example | | --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Blurred background and image background | ![image](https://assets-docs.agora.io/images/extensions-marketplace/blurred-background.jpg) | | Video/Animated background |

| | Portrait-in-picture | ![portrait-in-picture](https://assets-docs.agora.io/images/extensions-marketplace/portrait-in-picture.jpg) Allows the presenter to use slides as the virtual background while superimposing their video. The effect is similar to a weather news cast on television, preventing interruptions during a layout toggle. | Want to test Virtual Background? Try the online demo. ## Prerequisites [#prerequisites] Ensure that you have implemented the [SDK quickstart](../../index.mdx) in your project. ## Implement virtual background [#implement-virtual-background] This section shows you how to add a virtual background to the local video. ### Check device compatibility [#check-device-compatibility] To avoid performance degradation or unavailable features when enabling Virtual Background on low-end devices, check whether the device supports the feature. Java Kotlin ```java boolean isFeatureAvailable() { return agoraEngine.isFeatureAvailableOnDevice( Constants.FEATURE_VIDEO_VIRTUAL_BACKGROUND ); } ``` ```kotlin fun isFeatureAvailable(): Boolean { return agoraEngine.isFeatureAvailableOnDevice( Constants.FEATURE_VIDEO_VIRTUAL_BACKGROUND ) } ``` ### Set a blurred background [#set-a-blurred-background] To blur the video background, use the following code: Java Kotlin ```java void setBlurBackground() { VirtualBackgroundSource virtualBackgroundSource = new VirtualBackgroundSource(); virtualBackgroundSource.setBackgroundSourceType(VirtualBackgroundSource.BACKGROUND_BLUR); virtualBackgroundSource.setBlurDegree(VirtualBackgroundSource.BLUR_DEGREE_MEDIUM); // Set processing properties for background SegmentationProperty segmentationProperty = new SegmentationProperty(); segmentationProperty.setModelType(SegmentationProperty.SEG_MODEL_AI); // Use SEG_MODEL_GREEN if you have a green background segmentationProperty.setGreenCapacity(0.5f); // Accuracy for identifying green colors (range 0-1) // Enable or disable virtual background agoraEngine.enableVirtualBackground(true, virtualBackgroundSource, segmentationProperty); } ``` ```kotlin fun setBlurBackground() { val virtualBackgroundSource = VirtualBackgroundSource() virtualBackgroundSource.setBackgroundSourceType(VirtualBackgroundSource.BACKGROUND_BLUR) virtualBackgroundSource.setBlurDegree(VirtualBackgroundSource.BLUR_DEGREE_MEDIUM) // Set processing properties for background val segmentationProperty = SegmentationProperty() segmentationProperty.setModelType(SegmentationProperty.SEG_MODEL_AI) // Use SEG_MODEL_GREEN if you have a green background segmentationProperty.setGreenCapacity(0.5f) // Accuracy for identifying green colors (range 0-1) // Enable or disable virtual background agoraEngine.enableVirtualBackground(true, virtualBackgroundSource, segmentationProperty) } ``` ### Set a color background [#set-a-color-background] To apply a solid color as the virtual background, use a hexadecimal color code. For example, `0x0000FF` for blue: Java Kotlin ```java void setSolidBackground() { VirtualBackgroundSource virtualBackgroundSource = new VirtualBackgroundSource(); virtualBackgroundSource.setBackgroundSourceType(VirtualBackgroundSource.BACKGROUND_COLOR); virtualBackgroundSource.setColor(0x0000FF); // Set processing properties for background SegmentationProperty segmentationProperty = new SegmentationProperty(); segmentationProperty.setModelType(SegmentationProperty.SEG_MODEL_AI); // Use SEG_MODEL_GREEN if you have a green background segmentationProperty.setGreenCapacity(0.5f); // Accuracy for identifying green colors (range 0-1) // Enable or disable virtual background agoraEngine.enableVirtualBackground(true, virtualBackgroundSource, segmentationProperty); } ``` ```kotlin fun setSolidBackground() { val virtualBackgroundSource = VirtualBackgroundSource() virtualBackgroundSource.setBackgroundSourceType(VirtualBackgroundSource.BACKGROUND_COLOR) virtualBackgroundSource.setColor(0x0000FF) // Set processing properties for background val segmentationProperty = SegmentationProperty() segmentationProperty.setModelType(SegmentationProperty.SEG_MODEL_AI) // Use SEG_MODEL_GREEN if you have a green background segmentationProperty.setGreenCapacity(0.5f) // Accuracy for identifying green colors (range 0-1) // Enable or disable virtual background agoraEngine.enableVirtualBackground(true, virtualBackgroundSource, segmentationProperty) } ``` ### Set an image background [#set-an-image-background] To set a custom image as the virtual background, specify the absolute path to the image file. Java Kotlin ```java void setImageBackground() { VirtualBackgroundSource virtualBackgroundSource = new VirtualBackgroundSource(); virtualBackgroundSource.setBackgroundSourceType(VirtualBackgroundSource.BACKGROUND_IMG); virtualBackgroundSource.setSource(""); // Set processing properties for background SegmentationProperty segmentationProperty = new SegmentationProperty(); segmentationProperty.setModelType(SegmentationProperty.SEG_MODEL_AI); // Use SEG_MODEL_GREEN if you have a green background segmentationProperty.setGreenCapacity(0.5f); // Accuracy for identifying green colors (range 0-1) // Enable or disable virtual background agoraEngine.enableVirtualBackground(true, virtualBackgroundSource, segmentationProperty); } ``` ```kotlin fun setImageBackground() { val virtualBackgroundSource = VirtualBackgroundSource() virtualBackgroundSource.setBackgroundSourceType(VirtualBackgroundSource.BACKGROUND_IMG) virtualBackgroundSource.setSource("") // Set processing properties for background val segmentationProperty = SegmentationProperty() segmentationProperty.setModelType(SegmentationProperty.SEG_MODEL_AI) // Use SEG_MODEL_GREEN if you have a green background segmentationProperty.setGreenCapacity(0.5f) // Accuracy for identifying green colors (range 0-1) // Enable or disable virtual background agoraEngine.enableVirtualBackground(true, virtualBackgroundSource, segmentationProperty) } ``` ### Reset the background [#reset-the-background] To disable the virtual background and revert to the original video state, use the following code: Java Kotlin ```java void removeBackground() { // Disable virtual background agoraEngine.enableVirtualBackground( false, new VirtualBackgroundSource(), new SegmentationProperty() ); } ``` ```kotlin fun removeBackground() { // Disable virtual background agoraEngine.enableVirtualBackground( false, VirtualBackgroundSource(), SegmentationProperty() ) } ``` ## Reference [#reference] This section contains content that completes the information in this page, or points you to documentation that explains other aspects to this product. ### API reference [#api-reference] * [`isFeatureAvailableOnDevice`](https://api-ref.agora.io/en/video-sdk/android/4.x/API/class_irtcengine.html#api_irtcengine_isfeatureavailableondevice) * [`enableVirtualBackground`](https://api-ref.agora.io/en/video-sdk/android/4.x/API/class_irtcengine.html#api_irtcengine_enablevirtualbackground) * [`VirtualBackgroundSource`](https://api-ref.agora.io/en/video-sdk/android/4.x/API/class_virtualbackgroundsource.html) * [`SegmentationProperty`](https://api-ref.agora.io/en/video-sdk/android/4.x/API/rtc_api_data_type.html#class_segmentationproperty) <_PlatformProcessedMarker close="true" /> <_PlatformPanel platform="ios"> <_PlatformProcessedMarker groupMode="structured" canonicalPlatform="web" platform="ios" /> ## Understand the tech [#understand-the-tech-1] Virtual Background offers the following options: | Feature | Example | | --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Blurred background and image background | ![image](https://assets-docs.agora.io/images/extensions-marketplace/blurred-background.jpg) | | Video/Animated background |

| | Portrait-in-picture | ![portrait-in-picture](https://assets-docs.agora.io/images/extensions-marketplace/portrait-in-picture.jpg) Allows the presenter to use slides as the virtual background while superimposing their video. The effect is similar to a weather news cast on television, preventing interruptions during a layout toggle. | Want to test Virtual Background? Try the online demo. A typical transmission pipeline in the Agora Web SDK consists of a chain of procedures, including capture, preprocessing, encoding, transmitting, decoding, post-processing, and playback. In the preprocessing stage, extensions can modify the audio and video data in the pipeline to implement features such as virtual background and noise cancellation. **Web SDK typical transmission** ![web extensions](https://assets-docs.agora.io/images/extensions-marketplace/virtual-background.svg) ## Prerequisites [#prerequisites-2] Ensure that you have implemented the [SDK quickstart](../../index.mdx) in your project. ## Implement virtual background [#implement-virtual-background-2] This section shows you how to add a virtual background to the local video. ### Complete sample code [#complete-sample-code] Copy the following code into your script file: **Complete sample code for virtual background** ```js // Create Client var client = AgoraRTC.createClient({mode: "rtc", codec: "vp8"}); // Create VirtualBackgroundExtension instance const extension = new VirtualBackgroundExtension(); // Register plugin AgoraRTC.registerExtensions([extension]); let processor = null; var localTracks = { videoTrack: null, audioTrack: null }; // Initialize async function getProcessorInstance() { if (!processor && localTracks.videoTrack) { // Create VirtualBackgroundProcessor instance processor = extension.createProcessor(); try { // Initialize plugin await processor.init(); } catch(e) { console.log("Fail to load WASM resource!"); return null; } // Inject plugin into SDK's video processing pipeline localTracks.videoTrack.pipe(processor).pipe(localTracks.videoTrack.processorDestination); } return processor; } // Join channel async function join() { // Add event listeners client.on("user-published", handleUserPublished); client.on("user-unpublished", handleUserUnpublished); [options.uid, localTracks.audioTrack, localTracks.videoTrack] = await Promise.all([ // Join channel client.join(options.appid, options.channel, options.token || null), // Create local microphone and camera tracks localTracks.audioTrack || AgoraRTC.createMicrophoneAudioTrack(), localTracks.videoTrack || AgoraRTC.createCameraVideoTrack({encoderConfig: '720p_4'}) ]); // Play local tracks localTracks.videoTrack.play("local-player"); } // Set solid color background async function setBackgroundColor() { if (localTracks.videoTrack) { document.getElementById("loading").style.display = "block"; let processor = await getProcessorInstance(); try { processor.setOptions({type: 'color', color: '#00ff00'}); await processor.enable(); } finally { document.getElementById("loading").style.display = "none"; } virtualBackgroundEnabled = true; } } // Blur user's actual background async function setBackgroundBlurring() { if (localTracks.videoTrack) { document.getElementById("loading").style.display = "block"; let processor = await getProcessorInstance(); try { processor.setOptions({type: 'blur', blurDegree: 2}); await processor.enable(); } finally { document.getElementById("loading").style.display = "none"; } virtualBackgroundEnabled = true; } } // Set image background async function setBackgroundImage() { const imgElement = document.createElement('img'); imgElement.onload = async() => { document.getElementById("loading").style.display = "block"; let processor = await getProcessorInstance(); try { processor.setOptions({type: 'img', source: imgElement}); await processor.enable(); } finally { document.getElementById("loading").style.display = "none"; } virtualBackgroundEnabled = true; } imgElement.src = '/images/background.png'; } ``` ### Integrate the virtual background extension [#integrate-the-virtual-background-extension] Run the following comment in the root directory of your project: ```bash npm install agora-extension-virtual-background ``` ### Import the virtual background extension [#import-the-virtual-background-extension] You can add the extension in your app in the following ways: 1. Add the following code to the script file: ```typescript import VirtualBackgroundExtension from "agora-extension-virtual-background"; ``` 2. Add the following code to the html file: ```html ``` ### Create and register the extension instance [#create-and-register-the-extension-instance] Register the extension instance with the Video SDK. To do this, add the following code to the script file: ```typescript // Create Client var client = AgoraRTC.createClient({mode: "rtc", codec: "vp8"}); // Create VirtualBackgroundExtension instance const extension = new VirtualBackgroundExtension(); // Check compatibility if (!extension.checkCompatibility()) { // The current browser does not support the virtual background plugin, you can stop executing the subsequent logic console.error("Does not support Virtual Background!"); } // Register plugin AgoraRTC.registerExtensions([extension]); ``` ### Inject a processor into the local video stream [#inject-a-processor-into-the-local-video-stream] 1. Call `extension.createProcessor` to create a `VirtualBackgroundProcessor` instance. ```javascript processor = extension.createProcessor(); ``` 2. Call `processor.init` to initialize the plugin. When resource loading or plug-in initialization fails, this method will throw an exception, and the application can catch the exception and handle it accordingly: ```javascript await processor.init(); ``` 3. After creating the local camera video track, call `videoTrack.pipe` and specify the `videoTrack.processorDestination` attribute to inject the plug-in into the SDK's media processing pipeline. For computing performance reasons, Agora recommends using the virtual background plug-in on a single video track. If you need two video tracks for preview, create multiple instances of `VirtualBackgroundProcessor`. ```javascript localTracks.videoTrack.pipe(processor).pipe(localTracks.videoTrack.processorDestination); ``` ### Set a virtual background [#set-a-virtual-background] Call `processor.setOptions` to set the virtual background type and corresponding parameters. The following examples show how you use different backgrounds: 1. Set a solid color background: Set the `type` parameter to `color`, then set the `color` parameter to a color value: ```javascript processor.setOptions({type: 'color', color: '#00ff00'}); ``` 2. Set the picture background: Set the `type` parameter to `img`, and then set the `source` parameter to `HTMLImageElement`: ```javascript processor.setOptions({type: 'img', source: HTMLImageElement}); ``` 3. Blur the user's actual background: Set the `type` parameter to `blur`, and then set the `blurDegree` parameter to low (`1`), medium (`2`), or high (`3`): ```javascript processor.setOptions({type: 'blur', blurDegree: 2}); ``` 4. Set a dynamic background: Set the `type` parameter to `video`, and then set the `source` parameter to a video object: ```javascript processor.setOptions({type: 'video', source: HTMLVideoElement}); ``` ### Enable the virtual background [#enable-the-virtual-background] To enable a virtual background, call `processor.enable`: ```javascript await processor.enable(); ``` If `enable` is not called before calling `setOptions`, the SDK will enable the background blur effect by default, with a blur level of `1`. After turning on the virtual background, if you need to switch the virtual background effect, just adjust `setOptions`. ### Disable the virtual background [#disable-the-virtual-background] To disable the virtual background, call `disable` and `unpipe`: ```javascript await processor.disable(); ``` To remove the processor from the local video track, call `videoTrack.unpipe`: ```javascript localTracks.videoTrack.unpipe(); ``` If you need to enable the virtual background again, you can reuse the existing `VirtualBackgroundProcessor` instance and do not need to recreate it. If multiple instances of `VirtualBackgroundProcessor` are created, it is recommended to call the `processor.release` method to release the plug-in resources that are no longer needed. ## Reference [#reference-2] This section contains content that completes the information in this page, or points you to documentation that explains other aspects to this product. * For a working example, check out the [Virtual background web demo](https://webdemo.agora.io/virtualBackground/index.html) and the associated [source code](https://github.com/AgoraIO/API-Examples-Web/tree/main/Demo/virtualBackground). ### Considerations [#considerations] * This extension works best when there is only one user in the video captured by the camera. * The browser support for the virtual background extension is as follows: * To get a better virtual background experience, Agora recommends using this feature on the latest version of Desktop Chrome. * Agora does not recommend enabling the virtual background feature on Firefox and Safari browsers. Backgrounding the web app on Firefox may cause the video to freeze, while the performance on Safari could be poor due to the browser's own performance issues. * Agora does not recommend enabling the virtual background feature on mobile browsers. * The virtual background feature has high performance requirements. Make sure your computer meets the following requirements: * CPU: Intel Core i5 4 cores or higher * 8G RAM or more * 64-bit operating system * If multiple extensions are enabled concurrently and other programs are occupying high system resources at the same time, your app may experience audio and video freezes. * When using this extension, Agora recommends selecting `Performance` mode or `Balanced` mode for your laptops. The computing requirements for this extension may not be met if the laptop is in a battery-saving mode. * This extension supports using a video as a dynamic virtual background since v1.0.0-beta-3. Videos must be in a format supported by `