Skip to main content
Version: 5.3

Virtual background

In video calls, you can use the virtual background feature to either blur the background or replace it with an image. This page describes how to use the virtual background feature.

Supported call typeMinimum SDK version
1-to-1 call, group call (conference)WebPlanetKit 5.3
Note
  • Currently, the virtual background feature is not supported in the Safari browser.
  • The virtual background feature cannot be used when the custom media stream is set.
Warning

Applying the virtual background effect increases CPU and memory usage.

Install the virtual background plugin SDK​​

WebPlanetKit provides an API to enable virtual background functionality through a separate plugin SDK. To use the virtual background API, first install the virtual background plugin SDK by referring to the README in the plugin SDK repository.

Prepare to use the virtual background feature​

Import the installed virtual background plugin SDK, create a PlanetKitVirtualBackground instance, and register the created instance with the WebPlanetKit instance. The PlanetKitVirtualBackground instance can also be registered with a MediaStreamManager instance, which is provided by WebPlanetKit to let you easily create and manage MediaStream.

// Import SDK
import { Conference } from "@line/planet-kit";
import PlanetKitVirtualBackground from "@line/planet-kit-virtual-background";

// Create a planet-kit instance (This example is for group call).
const planetKit = new Conference();

// Create a planet-kit-virtual-background instance.
const virtualBackground = new PlanetKitVirtualBackground();

// Register the planet-kit-virtual-background with the planet-kit.
const conferenceParams = {
    ...,
    mediaHtmlElement: {
        myVideo: myVideoElement // Used as the default video source of virtual background.
    }
};
planetKit.joinConference(conferenceParams).then(() => {
    planetKit.registerVirtualBackground(virtualBackground);
});

How the virtual background feature work​

WebPlanetKit's virtual background feature works by taking the video element set as the local user's video element in MakeCallParams, VerifyCallParams, or ConferenceParams as the source, applying the virtual background effect to this source, and rendering the result on a separate canvas element like the following.

<html>
    <div>
        <canvas id="virtual-background-canvas" autoplay></canvas>
    </div>
</html>

Set a blurred background​​

To apply a blur effect to the background, call startVirtualBackgroundBlur() with a canvas element and a value to determine the degree of blur (blurRadius). blurRadius is a value that determines the radius of the Gaussian blur applied to the virtual background. The larger the value, the blurrier the result. Typically, values between 5 and 20 are used, and the default value is 15 if not set.

const virtualBackgroundCanvasElement = document.getElementById('virtual-background-canvas');
const blurRadius = 15;

planetKit.startVirtualBackgroundBlur(virtualBackgroundCanvasElement, blurRadius)
    .then(() => {
        // Successfully started blurred virtual background
    })
    .catch((error) => {
        // Failed to start blurred virtual background
    });

Set an image background​​

To replace the background with an image, call startVirtualBackgroundImage() with a canvas element and the image you want to set as the background. For the image, you can use either the HTMLImageElement or ImageBitmap type.

const virtualBackgroundCanvasElement = document.getElementById('virtual-background-canvas');
const image = new Image();
image.src = '/image_file';

planetKit.startVirtualBackgroundImage(virtualBackgroundCanvasElement, image)
    .then(() => {
        // Successfully started image virtual background
    })
    .catch((error) => {
        // Failed to start image virtual background
    });

Change the source video element of the virtual background​

To change the video element used as the source for the virtual background feature, call changeVirtualBackgroundVideoElement() with the video element you want to use as the new source.

<html>
    <div>
        <video id="new-my-video" muted autoplay playsinline></video>
    </div>
</html>
const newMyVideoElement = document.getElementById('new-my-video');

planetKit.changeVirtualBackgroundVideoElement(newMyVideoElement)
    .then(() => {
        // Successfully changed source video element for virtual background
    })
    .catch((error) => {
        // Failed to change source video element for virtual background
    });

Change the canvas element where the virtual background is applied​

To change the canvas element where the virtual background is applied, call changeVirtualBackgroundCanvasElement() with a new canvas element as an argument.

<html>
    <div>
        <canvas id="new-virtual-background-canvas" autoplay></canvas>
    </div>
</html>
const newVirtualBackgroundCanvasElement = document.getElementById('new-virtual-background-canvas');

planetKit.changeVirtualBackgroundCanvasElement(newVirtualBackgroundCanvasElement)
    .then(() => {
        // Successfully changed canvas element for virtual background
    })
    .catch((error) => {
        // Failed to change canvas element for virtual background
    });

Check whether a virtual background is used​​

To check whether a virtual background is currently being used, call isVirtualBackgroundActive().

if (planetKit.isVirtualBackgroundActive()) {
    // Currently virtual background is active
}

Clear the virtual background​​

To clear the virtual background, call stopVirtualBackground().

planetKit.stopVirtualBackground()