Virtual Background

Apply blur or custom image backgrounds during video calls

Quick Reference for AI Agents & Developers

// Configure virtual background
const virtualBackground = new CometChatCalls.VirtualBackground();
virtualBackground.allowBackgroundBlur(true);
virtualBackground.allowUserImages(true);
virtualBackground.setImages(["https://example.com/bg1.jpg"]);
virtualBackground.enforceBackgroundBlur(50);  // Start with blur (1-99)

// Apply to call settings
const callSettings = new CometChatCalls.CallSettingsBuilder()
  .showVirtualBackgroundSetting(true)
  .setVirtualBackground(virtualBackground)
  .build();

// Programmatic control during call
const controller = CometChatCalls.CallController.getInstance();
controller.setBackgroundBlur(50);
controller.setBackgroundImage("https://example.com/bg.jpg");

Available via: SDK | UI Kits

Enhance video calls with virtual backgrounds, allowing users to blur their surroundings or display custom images behind them.

Prerequisites

Before implementing virtual backgrounds, ensure you have:

1. Completed the Calls SDK Setup
2. Implemented either Ringing or Call Session calling

Quick Start

Enable virtual background settings in your call configuration:

JavaScript

const callSettings = new CometChatCalls.CallSettingsBuilder()
  .enableDefaultLayout(true)
  .showVirtualBackgroundSetting(true)  // Show VB button in UI
  .setCallListener(callListener)
  .build();

TypeScript

const callSettings = new CometChatCalls.CallSettingsBuilder()
  .enableDefaultLayout(true)
  .showVirtualBackgroundSetting(true)
  .setCallListener(callListener)
  .build();

Call Settings Options

Method	Description	Default
showVirtualBackgroundSetting(boolean)	Show/hide virtual background button in menu	true
setVirtualBackground(VirtualBackground)	Configure virtual background options	-

Virtual Background Configuration

Use the VirtualBackground class to customize available options:

JavaScript

const virtualBackground = new CometChatCalls.VirtualBackground();

// Allow background blur
virtualBackground.allowBackgroundBlur(true);

// Allow users to upload custom images
virtualBackground.allowUserImages(true);

// Show default background images
virtualBackground.showDefaultImages(true);

// Add custom background images
virtualBackground.setImages([
  "https://example.com/bg1.jpg",
  "https://example.com/bg2.jpg",
  "https://example.com/bg3.jpg"
]);

// Apply to call settings
const callSettings = new CometChatCalls.CallSettingsBuilder()
  .enableDefaultLayout(true)
  .setVirtualBackground(virtualBackground)
  .setCallListener(callListener)
  .build();

TypeScript

const virtualBackground = new CometChatCalls.VirtualBackground();

virtualBackground.allowBackgroundBlur(true);
virtualBackground.allowUserImages(true);
virtualBackground.showDefaultImages(true);
virtualBackground.setImages([
  "https://example.com/bg1.jpg",
  "https://example.com/bg2.jpg",
  "https://example.com/bg3.jpg"
]);

const callSettings = new CometChatCalls.CallSettingsBuilder()
  .enableDefaultLayout(true)
  .setVirtualBackground(virtualBackground)
  .setCallListener(callListener)
  .build();

Configuration Options

Method	Description	Default
allowBackgroundBlur(boolean)	Allow users to blur their background	true
allowUserImages(boolean)	Allow users to upload custom images	true
showDefaultImages(boolean)	Show CometChat’s default background images	true
setImages(string[])	Add custom background images (URLs)	[]
enforceBackgroundBlur(number)	Start call with blur enabled (1-99 intensity)	0 (disabled)
enforceBackgroundImage(string)	Start call with specific background image	-

Enforce Settings

Force specific virtual background settings when the call starts:

Enforce Blur

const virtualBackground = new CometChatCalls.VirtualBackground();

// Start call with medium blur (1-99)
virtualBackground.enforceBackgroundBlur(50);

const callSettings = new CometChatCalls.CallSettingsBuilder()
  .enableDefaultLayout(true)
  .setVirtualBackground(virtualBackground)
  .build();

Enforce Image

const virtualBackground = new CometChatCalls.VirtualBackground();

// Start call with specific background
virtualBackground.enforceBackgroundImage("https://example.com/office-bg.jpg");

const callSettings = new CometChatCalls.CallSettingsBuilder()
  .enableDefaultLayout(true)
  .setVirtualBackground(virtualBackground)
  .build();

Programmatic Control

For custom UI implementations, control virtual backgrounds programmatically:

Open Settings Dialog

JavaScript

const callController = CometChatCalls.CallController.getInstance();
callController.openVirtualBackground();

TypeScript

const callController = CometChatCalls.CallController.getInstance();
callController.openVirtualBackground();

Set Background Blur

Apply blur with intensity from 1 (light) to 99 (heavy):

JavaScript

const callController = CometChatCalls.CallController.getInstance();

// Light blur
callController.setBackgroundBlur(20);

// Medium blur
callController.setBackgroundBlur(50);

// Heavy blur
callController.setBackgroundBlur(80);

TypeScript

const callController = CometChatCalls.CallController.getInstance();
callController.setBackgroundBlur(50);

Set Background Image

Apply a custom background image:

From URL

const callController = CometChatCalls.CallController.getInstance();
callController.setBackgroundImage("https://example.com/background.jpg");

From File

const callController = CometChatCalls.CallController.getInstance();

// From file input
const fileInput = document.getElementById("bg-file-input");
fileInput.addEventListener("change", (event) => {
  const file = event.target.files[0];
  callController.setBackgroundImage(file);
});

Complete Example

JavaScript

// Configure virtual background options
const virtualBackground = new CometChatCalls.VirtualBackground();
virtualBackground.allowBackgroundBlur(true);
virtualBackground.allowUserImages(true);
virtualBackground.showDefaultImages(true);
virtualBackground.setImages([
  "https://example.com/office.jpg",
  "https://example.com/nature.jpg",
  "https://example.com/abstract.jpg"
]);

// Optional: Start with blur enabled
virtualBackground.enforceBackgroundBlur(30);

// Build call settings
const callSettings = new CometChatCalls.CallSettingsBuilder()
  .enableDefaultLayout(true)
  .showVirtualBackgroundSetting(true)
  .setVirtualBackground(virtualBackground)
  .setCallListener(callListener)
  .build();

// Start the call
const htmlElement = document.getElementById("call-container");
CometChatCalls.startSession(callToken, callSettings, htmlElement);

TypeScript

const virtualBackground = new CometChatCalls.VirtualBackground();
virtualBackground.allowBackgroundBlur(true);
virtualBackground.allowUserImages(true);
virtualBackground.showDefaultImages(true);
virtualBackground.setImages([
  "https://example.com/office.jpg",
  "https://example.com/nature.jpg",
  "https://example.com/abstract.jpg"
]);
virtualBackground.enforceBackgroundBlur(30);

const callSettings = new CometChatCalls.CallSettingsBuilder()
  .enableDefaultLayout(true)
  .showVirtualBackgroundSetting(true)
  .setVirtualBackground(virtualBackground)
  .setCallListener(callListener)
  .build();

const htmlElement = document.getElementById("call-container") as HTMLElement;
CometChatCalls.startSession(callToken, callSettings, htmlElement);

Next Steps

Video Customization

Customize video container appearance

Custom CSS

Style the call UI with CSS