Tutorial: Enable Virtual Background

Function Description

This document will describe how to implement the virtual background feature during a call.

Original Camera	Background Blur	Background Image

Prerequisites

• Pricing see RTC-Engine Packages.
• TRTC SDK version must be >= 5.5.0
• System and configuration requirements for various platforms are as follows:

Implementation Steps

Deploying Static Resources

This plugin relies on certain static resource files. To ensure that the browser can load and run these files properly, follow these steps:

1. Publish the node_modules/trtc-sdk-v5/assets directory to a CDN or a static resource server.
2. Pass your CDN URL to the assets parameter when creating the trtc instance, for example: TRTC.create({ assets: 'https://xxxx/assets' }). The SDK will load the required resource files as needed.

• If your version is below v5.10.0, you need to download and extract assets.zip, then publish it to a CDN or a static resource server.
• If the Host URL of the files in the directory is different from the Host URL of the web application, you need to enable the CORS policy for the file domain.
• Do not place the directory files under an HTTP service, as loading HTTP resources from an HTTPS domain will be blocked by browser security policies.

Checking Browser Support (v5.8.1+)

import { VirtualBackground } from 'trtc-sdk-v5/plugins/video-effect/virtual-background';
if (!VirtualBackground.isSupported()) {
    // Virtual background is not supported
}

Registering the Plugin

import { VirtualBackground } from 'trtc-sdk-v5/plugins/video-effect/virtual-background';
const trtc = TRTC.create({ plugins: [VirtualBackground], assets: 'https://xxxx/assets' });

Starting the Local Camera

await trtc.startLocalVideo();

Enabling the Virtual Background Plugin

await trtc.startPlugin('VirtualBackground', {
  sdkAppId: 123123,
  userId: 'userId_123',
  userSig: 'your_userSig'
});

Note: The first time you enable this feature, it requires loading computing resources, which has been automatically processed for you. For a more ultimate startup experience, please refer to the end of the document: FAQ > How to speed up startup?

Updating Parameters as Needed

// Changing to an image background
await trtc.updatePlugin('VirtualBackground', {
  type: 'image',
  src: 'https://picsum.photos/seed/picsum/200/300'
});

Disabling Virtual Background

await trtc.stopPlugin('VirtualBackground');

API Documentation

trtc.startPlugin('VirtualBackground', options)

Used to enable the virtual background.

options

Example:

await trtc.startPlugin('VirtualBackground', {
  sdkAppId: 123123,
  userId: 'userId_123',
  userSig: 'your_userSig',
  type: 'image',
  src: 'https://picsum.photos/seed/picsum/200/300'
});

trtc.updatePlugin('VirtualBackground', options)

Allows modification of virtual background parameters.

options

Example:

await trtc.updatePlugin('VirtualBackground', {
  type: 'blur',
  blurLevel: 6
});

trtc.stopPlugin('VirtualBackground')

Disables the virtual background.

FAQs

1. When running the demo in Chrome, the video appears upside down and laggy

This plugin uses GPU acceleration, and you need to enable hardware acceleration mode in your browser settings. You can copy and paste chrome://settings/system into your browser's address bar and enable hardware acceleration mode.

2. When device performance is insufficient, causing high latency and rendering issues

You can reduce video resolution or frame rate by listening to events.

async function onError(error) {
  const { code } = error;
  if (code === 10000003 || code === 10000006) {
    // Reduce resolution and frame rate
    await trtc.updateLocalVideo({
      option: {
        profile: '480p_2'
      },
    });
    // await trtc.stopPlugin('VirtualBackground'); // Or disable the plugin
  }
}
await trtc.startPlugin('VirtualBackground', {
  ...// Other parameters
  onError,
});

2. When device performance is insufficient and causes high latency with long rendering times

You can reduce video resolution or frame rate by listening to events.

async function onError(error) {
  const { code } = error;
  if (code === 10000003 || code === 10000006) {
    // Reduce resolution and frame rate
    await trtc.updateLocalVideo({
      option: {
        profile: '480p_2'
      },
    });
    // await trtc.stopPlugin('VirtualBackground'); // Or disable the plugin
  }
}
await trtc.startPlugin('VirtualBackground', {
  ...// Other parameters
  onError,
});