Virtual Background 🔗


This feature is part of OpenVidu PRO and ENTERPRISE editions.
WARNING: OpenVidu Virtual Background is considered an experimental feature. This means that there is a possibility that unexpected bugs may arise, and that the API may change in the near future.

OpenVidu Virtual Background allows you to apply a filter to a video stream, such as a blurring effect or a background image. In this way you may cut out the person from the background, giving a more professional look to your video calls. Take a look to the video below to get an idea of what is possible with OpenVidu Virtual Background:

You can check out openvidu-virtual-background tutorial to see this feature in action.

How does Virtual Background work 🔗

You can apply a Virtual Background to a Stream object using the same openvidu-browser API used for applying server-side voice and video filters.

To apply a blur effect:

var OV = new OpenVidu();
var publisher = OV.initPublisherAsync(targetElement);
var virtualBackgroundFilter = await publisher.stream.applyFilter("VB:blur");

To apply a background image:

var OV = new OpenVidu();
var publisher = OV.initPublisherAsync(targetElement);
var virtualBackgroundFilter = await publisher.stream.applyFilter("VB:image", {
    url: "https://raw.githubusercontent.com/OpenVidu/openvidu.io/master/img/vb/office.jpeg",
});

To modify the background image of an active Virtual Background filter:

await virtualBackgroundFilter.execMethod("update", {
    url: "https://raw.githubusercontent.com/OpenVidu/openvidu.io/master/img/vb/beach.jpeg"
});

To remove a Virtual Background filter:

await publisher.stream.removeFilter();

Applying a Virtual Background before connecting to the Session 🔗

It is a very common use case for any videoconferencing application to have a configuration panel prior to joining the video session. In this configuration panel, the user sets up its nickname, camera, microphone and other settings. It is therefore necessary to be able to configure a Virtual Background before connecting to the Session, so that users have a preview of their appearance before others start receiving their streams.

If you try applying a Virtual Background before connecting to a Session, an OpenViduError will be triggered by default:

{
    "name": "VIRTUAL_BACKGROUND_ERROR",
    "message": "Virtual Background requires the client to be connected to a Session or to have a 'token' property available in 'options' parameter with a valid OpenVidu token"
}

To avoid this, pass a token parameter to the method, providing a valid token generated for any Session in the OpenVidu deployment:

var myToken; // A valid token from the OpenVidu deployment

var OV = new OpenVidu();
var publisher = OV.initPublisherAsync(targetElement);
publisher.stream.applyFilter("VB:image", {
    url: "https://raw.githubusercontent.com/OpenVidu/openvidu.io/master/img/vb/office.jpeg",
    token: myToken
});

Virtual Background limitations 🔗

Keep the following points in mind when implementing Virtual Background in your application:

  • Virtual Background is compatible with most platforms, but not all. It has been successfully tested in desktop browsers (Chrome, Firefox, Edge, Opera, Safari), mobile browsers (Chrome, Firefox, Edge, Opera, Safari, Samsung Internet Browser), Electron and Ionic for Android. Right now it is not supported in React Native, Ionic for iOS and native Android/iOS apps.
  • HD resolutions may reduce performance. It is recommended to apply Virtual Background only on SD resolutions and below (max 640x480).
  • On mobile devices, a change in screen orientation after applying a Virtual Background (because of mobile rotation) can distort the filtered video. Mobile applications that allow screen rotation should not use Virtual Background.
  • Applying more than one Virtual Background in the same device can reduce performance to the point of making it unusable. Make sure to apply only one Virtual Background to a single Stream per device.
  • Virtual Backgrounds can only by applied to Publisher's streams.
  • It is not possible to apply both a Virtual Background filter and a server-side filter at the same time on the same Stream.
  • In Ionic when applying a background image, high resolution images may fail to be applied. The exact height and width in pixels from which the problem occurs has not been determined.
  • The behavior of Virtual Backgrounds may vary and its performance be affected when the focus of the application is lost. For example, in recent versions of Google Chrome, the Publisher's stream will freeze if a Virtual Background is being applied to it and the user changes the application's tab. In recent versions of Firefox, the image will not freeze, but the framerate will significantly drop.