@100mslive/react-native-video-plugin

Integrate virtual backgrounds, blur backgrounds effects in your React Native app with the 100ms Video Plugin. 100ms video plugin enabled adding virtual backgrounds, blur backgrounds, and other video filters to your 100ms video conferencing app. The plugin is built on top of the 100ms React Native SDK.

📖 Read the Complete Documentation here: https://www.100ms.live/docs/react-native/v2/quickstart/quickstart

📲 Download the Example iOS app here: https://testflight.apple.com/join/v4bSIPad

🤖 Download the Example Android app here: https://appdistribution.firebase.dev/i/7b7ab3b30e627c35

virtual-background-ui-demo.mov

Virtual Background plugin helps in customising one's background that replacing the background with a static image or blurring the background. This guide provides an overview of usage of the Virtual Background plugin of 100ms.

Package	Version
@100mslive/react-native-room-kit
@100mslive/react-native-hms
@100mslive/react-native-video-plugin

Minimum Requirements

• Minimum @100mslive/react-native-hms SDK version is ^1.10.6

Limitations

Android

• Has poor FPS on older Android phones

iOS

• Minimum iOS version required to support Virtual Background plugin is iOS 15
• Virtual background plugin is in beta stage and may have performance issues on iPhone X, 8, 7, 6 and other older devices. We recommend that you use this feature on a high performance device for smooth experience.

Usage

Step 1: Add required dependency

Install @100mslive/react-native-video-plugin library

npm install @100mslive/react-native-video-plugin

Step 2: Create instance of HMSVirtualBackgroundPlugin

// Import from `@100mslive/react-native-video-plugin` library
import { HMSVirtualBackgroundPlugin } from '@100mslive/react-native-video-plugin';

...

const virtualBackgroundPlugin = new HMSVirtualBackgroundPlugin();

Step 3: Create instance of HMSVideoTrackSettings

let videoSettings = new HMSVideoTrackSettings({
    initialState: HMSTrackSettingsInitState.MUTED
    // The virtual background plugin to use for the video track. @type {HMSVirtualBackgroundPlugin}
    videoPlugin: virtualBackgroundPlugin,
});

let trackSettings = new HMSTrackSettings({
    video: videoSettings,
});

Step 4: Pass the Track Settings to the HMSSDK

const hmsInstance = await HMSSDK.build({
    trackSettings,
});

Step 5: How to enable and disable virtual background

Hold on to a reference to the instance of HMSVirtualBackgroundPlugin and use enable and disable methods on it to enable/disable the virtual background.

const virtualBackgroundPlugin = new HMSVirtualBackgroundPlugin();

...

let isVBEnabled = false;

// Enable VB
await virtualBackgroundPlugin.enable();
isVBEnabled = true;

// Disable VB
await virtualBackgroundPlugin.disable();
isVBEnabled = false;

Always call enable method after ON_JOIN and ON_PREVIEW event

Enabling Virtual Background and applying effect can take some time, you should add a loader in UI.

Step 6: How to apply Blur as virtual background

Enable the blur background using the setBlur method. You should pass blur percentage ranging from 0-100

const virtualBackgroundPlugin = new HMSVirtualBackgroundPlugin();

...
// state for tracking if VB is enabled
let isVBEnabled = false;

// If VB is disabled, first enable it before calling `setBlur` method
if (isVBEnabled === false) {
  await virtualBackgroundPlugin.enable();
  isVBEnabled = true;
}

await virtualBackgroundPlugin.setBlur(100);

You should only call setBlur method only after enabling the virtual background

Step 7: How to apply Image as virtual background

Enable the background image using the setBackground method. It accepts image source (either a object with height, width and uri properties or a static image file).

Here is how to use a static image file -

const virtualBackgroundPlugin = new HMSVirtualBackgroundPlugin();

...
// state for tracking if VB is enabled
let isVBEnabled = false;

// If VB is disabled, first enable it before calling `setBlur` method
if (isVBEnabled === false) {
  await virtualBackgroundPlugin.enable();
  isVBEnabled = true;
}

const image = require('<PATH_TO_IMAGE_HERE>'); // ex: require('../assets/VB-1.jpg')
await virtualBackgroundPlugin.setBackground(image);

Here is how to use remote image file, setBackground method accepts object of following type -

export interface ImageURISource {
  width: number;

  height: number;

  /**
   * `uri` is a string representing the resource identifier for the image, which
   * could be an http address, a local file path, or the name of a static image
   * resource (which should be wrapped in the `require('./path/to/image.png')`
   * function).
   */
  uri:
}

...

await virtualBackgroundPlugin.setBackground({
  width,
  height,
  uri: 'file://...', // path of image stored in device
});

Using library like react-native-image-picker -

import { launchImageLibrary } from 'react-native-image-picker';

...

// You can use result from library like `react-native-image-picker` to use images from photo library
const result = await launchImageLibrary({ mediaType: 'photo', selectionLimit: 1 });

// getting first image
const imageObject = response.assets?.[0];

// If image is selected, use it as background
if (imageObject) {
  await virtualBackgroundPlugin.setBackground(imageObject);
}

You should only call setBackground method only after enabling the virtual background