Virtual Background

Add virtual backgrounds in CometChat Calls SDK v5 for JavaScript calls with background effects and in-call video customization.

Apply virtual backgrounds to your video feed during calls. You can blur your background or replace it with a custom image.

​

Background Blur

Apply a blur effect to your background:

CometChatCalls.setVirtualBackgroundBlurLevel(10);

Parameter	Type	Description
blurLevel	Number	The blur intensity level (higher = more blur)

​

Custom Background Image

Set a custom image as your virtual background:

CometChatCalls.setVirtualBackgroundImage("https://example.com/background.jpg");

Parameter	Type	Description
imageUrl	String	URL of the background image

The image URL must be accessible from the user’s browser. Consider hosting images on a CDN for best performance.

​

Clear Virtual Background

Remove any applied virtual background:

CometChatCalls.clearVirtualBackground();

​

Virtual Background Dialog

​

Show Dialog

Open the built-in virtual background settings dialog:

CometChatCalls.showVirtualBackgroundDialog();

​

Hide Dialog

Close the virtual background dialog:

CometChatCalls.hideVirtualBackgroundDialog();

​

Configure the Virtual Background Picker

Use the virtualBackground session setting to control which images appear in the virtual background picker, whether users can upload their own images, and whether blur options are available. Pass it in the settings object to joinSession():

const callSettings = {
  virtualBackground: {
    images: [
      "https://cdn.example.com/backgrounds/office.jpg",
      { src: "https://cdn.example.com/backgrounds/beach.jpg", label: "Beach" },
    ],
    allowUserImages: false,
    allowBlur: true,
  },
  // ... other settings
};

await CometChatCalls.joinSession(callToken, callSettings, container);

Property	Type	Default	Description
images	Array	Built-in CometChat images	Images shown in the picker. Each entry is either an image URL or an object with a src URL and an optional label (used as the tile’s tooltip). Providing this replaces the built-in images. Pass [] to show no images.
allowUserImages	Boolean	true	Show the Add Background tile that lets users upload their own image. When false, any images the user uploaded earlier in the same page load are also removed from the picker.
allowBlur	Boolean	true	Show the Slightly Blur and Blur options.
enableV2	Boolean	false	Use the V2 virtual background engine. See Virtual Background V2 Engine.
assetsBaseUrl	String	CometChat CDN	Folder (with a trailing slash) the SDK downloads virtual background assets from. Only set this when self-hosting the assets.

Custom image URLs must be served with CORS enabled. If an image can’t be loaded cross-origin, the effect fails to apply and the user sees a “Virtual background could not be applied” message.

​

Default Images

When you don’t pass images, the picker shows these built-in images: Nature, Office, Library, Home, Night Sky, and Office Lounge.

To add your own images alongside the built-in ones instead of replacing them, spread DEFAULT_VIRTUAL_BACKGROUND_IMAGES into your list:

import {
  CometChatCalls,
  DEFAULT_VIRTUAL_BACKGROUND_IMAGES,
} from "@cometchat/calls-sdk-javascript";

const callSettings = {
  virtualBackground: {
    images: [
      ...DEFAULT_VIRTUAL_BACKGROUND_IMAGES,
      { src: "https://cdn.example.com/backgrounds/brand.jpg", label: "Brand" },
    ],
  },
};

​

TypeScript Types

The configuration types are exported from the SDK:

import type {
  VirtualBackgroundConfig,
  VirtualBackgroundImage,
} from "@cometchat/calls-sdk-javascript";

const virtualBackground: VirtualBackgroundConfig = {
  images: [{ src: "https://cdn.example.com/backgrounds/office.jpg", label: "Office" }],
  allowUserImages: true,
  allowBlur: true,
};

​

Virtual Background V2 Engine

The V2 engine runs background segmentation in a dedicated Web Worker and composites frames on the GPU. Compared to the default engine, it keeps the effect running smoothly when the tab is in the background, lowers main-thread CPU usage, and produces cleaner edges. The SDK picks the best backend for the device automatically: WebGPU or WebGL where a GPU is available, and a WebAssembly fallback otherwise.

Enable it with enableV2:

const callSettings = {
  virtualBackground: {
    enableV2: true,
  },
};

If V2 fails to initialize (for example, when the worker script is blocked), the SDK logs the error and automatically falls back to the default engine for the rest of the page lifetime.

​

Content Security Policy

If your page sets a Content Security Policy, the V2 engine requires the following directives, where <assets host> is the host serving the assets (https://cdn.cometchat.io by default, or the host of your assetsBaseUrl):

Directive	Value	Reason
worker-src	blob:	The inference worker is started from a blob: URL
script-src	<assets host>	The worker script is loaded from the assets host
connect-src	<assets host>	Segmentation models and WebAssembly files are downloaded from the assets host (also required by the default engine)

​

Self-Hosting Assets

By default, virtual background assets are downloaded on demand from the CometChat CDN. To serve them from your own infrastructure, host the files below in one folder and set assetsBaseUrl to that folder:

File	Used by
tflite.wasm, tflite-simd.wasm	Default engine and V2 (WebAssembly fallback)
selfie_segmentation_landscape.tflite	Default engine and V2 (WebAssembly fallback)
vb-inference-worker.<contentHash>.min.js	V2 only
selfie_segmentation_landscape_tfjs/model.json, selfie_segmentation_landscape_tfjs/group1-shard1of1.bin	V2 only (WebGPU and WebGL backends)

const callSettings = {
  virtualBackground: {
    enableV2: true,
    assetsBaseUrl: "https://assets.example.com/cometchat/vb/",
  },
};

The inference worker’s file name includes a hash of its contents, and each SDK version requests one exact file name (visible in the browser’s network tab, and in the console error when the file is missing). After upgrading the SDK, check whether the worker file name changed and copy the new file if needed. Keep the old file while pages may still load the previous SDK version.

​

Hide Virtual Background Button

To hide the virtual background button from the control panel:

const callSettings = {
  hideVirtualBackgroundButton: true,
  // ... other settings
};

​

Browser Requirements

Virtual backgrounds use machine learning for background segmentation. Performance may vary based on:

• Device processing power
• Browser version
• Camera resolution

​

Browser Compatibility

Platform	Browser	Supported
Desktop (Windows, macOS, Linux)	Chrome and other Chromium-based browsers (Microsoft Edge, Brave, Opera, etc.)	✅ Yes
Desktop (Windows, macOS, Linux)	Firefox and other Firefox-based browsers (Zen, etc.)	✅ Yes
Desktop (macOS)	Safari	❌ Not supported
Android	Chrome and other Chromium-based browsers (Microsoft Edge, Brave, etc.)	✅ Yes
Android	Firefox and other Firefox-based browsers	✅ Yes
iOS (iPhone, iPad)	Safari, Chrome, Edge, Brave, any browser	❌ Not supported

Virtual background is not supported on iOS. Every browser on iOS, including Chrome, Edge, and Brave, is required to use Apple’s WebKit engine (the same engine as Safari), which doesn’t provide the APIs needed for real-time background segmentation.

For best results, use a Chromium-based browser or Firefox on a device with adequate processing power.