Virtual Background

CometChat Calling SDK v4 - Stable Release - Virtual Background for JavaScript

Quick Reference

• Settings class: CometChat.VirtualBackground
• Apply via: CallSettingsBuilder.setVirtualBackground(virtualBackground)
• Toggle UI: CallSettingsBuilder.showVirtualBackgroundSetting(true|false)
• Runtime control: CometChat.CallController.getInstance() → setBackgroundBlur(), setBackgroundImage(), openVirtualBackground()
• Requires: Ringing or Call Session setup

This section will guide you to implement virtual background feature in video calls.

Browser Compatibility: Virtual background is supported on desktop Chrome only. It is not supported on iOS device browsers (Safari, Chrome for iOS, or any browser) because all iOS browsers use WKWebView, which does not provide the APIs required for real-time background segmentation.

Implementation

Once you have decided to implement Ringing or Call Session calling and followed the steps to implement them. Just few additional methods will help you quickly implement virtual background.

Please make sure your callSettings is configured accordingly for Ringing or Call Session.

Settings

The CallSettingsclass allows you to customise the overall calling experience. The properties for the call/conference can be set using the CallSettingsBuilder class. This will eventually give you and object of the CallSettings class which you can pass to the startCall() method to start the call.

The mandatory parameters that are required to be present for any call/conference to work are:

1. sessionId - The unique session Id for the call/conference session.

The options available for virtual background are:

Setting	Description
showVirtualBackgroundSetting(showVBSettings: boolean)	This method shows/hides the virtual background settings in the menu bar. Default value = true
setVirtualBackground(virtualBackground: CometChat.VirtualBackground)	This method will set the virtual background setting. This methods takes an Object of Virtual Background Class.

For the use case where you wish to align your own custom buttons and not use the default layout provided by CometChat, you can embed the buttons in your layout and use the below methods to perform the corresponding operations:

Open Virtual Background Setting

You can use the openVirtualBackground() method to open the virtual background settings pop-up.

JavaScript

let callController = CometChat.CallController.getInstance();
callController.openVirtualBackground();

TypeScript

let callController: CometChat.CallController = CometChat.CallController.getInstance();
callController.openVirtualBackground();

Set Background Blur

You can use the setBackgroundBlur() method to apply background blur on the video stream. This method accepts a number which decides the level of blur to be applied.

JavaScript

let callController = CometChat.CallController.getInstance();
let blurLevel = 1;
callController.setBackgroundBlur(blurLevel);

TypeScript

let callController: CometChat.CallController = CometChat.CallController.getInstance();
let blurLevel: number = 1;
callController.setBackgroundBlur(blurLevel);

Set Background Image

You can use the setBackgroundImage()method to set the background image. This method takes either a URL or file Object & sets that image as the background.

JavaScript

let callController = CometChat.CallController.getInstance();
let imageURL = "URL_OF_BACKGROUND_IMAGE";
callController.setBackgroundImage(imageURL);

TypeScript

let callController: CometChat.CallController = CometChat.CallController.getInstance();
let imageURL: string = "URL_OF_BACKGROUND_IMAGE";
callController.setBackgroundImage(imageURL);

Virtual Background Settings

The VirtualBackground Class is the required in case you want to change how the end user can use virtual background features in a video call. You need to pass the Object of the VirtualBackground Class in the setVirtualBackground() method of the CallSettingsBuilder.

Setting	Description
allowBackgroundBlur(allowBackgroundBlur: boolean)	This method shows/hides the ability to allow end user to blur background. Default = true
allowUserImages(allowUserImages: boolean)	This method shows/hides the ability to allow end user to add their own custom background image. Default = true
showDefaultImages(showDefaultImages: boolean)	This method shows/hides the ability to allow end user to choose from default background images. Default = true
setImages(images: Array<String>)	This method allows developer to add their custom background image which the end user can choose.
enforceBackgroundBlur(enforceBackgroundBlur: number)	This method starts the call with background blurred. To blur the background you need to pass an integer value between 1-99 which decides the blur level. Default = 0
enforceBackgroundImage(enforceBackgroundImage: string)	This methods starts the call with the provided background image.

Best Practices

Practice	Details
Blur level range	Use values between 1-99 for enforceBackgroundBlur(). Higher values produce stronger blur. A value of 0 disables blur
Image hosting	Host background images on a CDN for fast loading. Large images may cause lag when applied
Enforce vs allow	Use enforceBackgroundBlur() or enforceBackgroundImage() when you want a mandatory background (e.g., for privacy). Use allowBackgroundBlur() and allowUserImages() to let users choose
Custom buttons	Use CallController methods (setBackgroundBlur, setBackgroundImage, openVirtualBackground) when building a custom UI instead of the default CometChat menu

Troubleshooting

Symptom	Cause	Fix
Virtual background option not visible	showVirtualBackgroundSetting(false) was set	Set showVirtualBackgroundSetting(true) in CallSettingsBuilder
Background blur not applied on call start	enforceBackgroundBlur() not set or set to 0	Pass a value between 1-99 to enforceBackgroundBlur()
Custom images not appearing	setImages() not called or empty array passed	Pass a non-empty array of valid image URLs to setImages()
CallController.getInstance() returns null	Called before the call has started	Only use CallController methods after startCall() has been invoked
User can’t upload their own images	allowUserImages(false) was set	Set allowUserImages(true) in the VirtualBackground configuration

Next Steps

Video View Customisation

Customize the main video container layout.

Recording

Record calls for playback.

Presenter Mode

Enable screen sharing and presenter mode.

Custom CSS

Customize the calling UI appearance.