Adding visual effects to a video call

The Azure Communication Calling SDK enables you to create video effects that are visible to other users on a call. For example, for an attendee using the Azure Communication Services calling WebJS SDK, you can provide the user with the option to turn on background blur. With background blur enabled, a user can feel more comfortable on a video call knowing that the background is blurred.

Prerequisites

Install the Azure Communication Services Calling SDK

• An Azure account with an active subscription is required. See Create an account for free on how to create an Azure account.
• Node.js active Long Term Support(LTS) versions are recommended.
• An active Communication Services resource. Create a Communication Services resource.
• A User Access Token to instantiate a call client. Learn how to create and manage user access tokens. You can also use the Azure CLI and run the command with your connection string to create a user and an access token. Record the connection string from the resource through Azure portal.
• Azure Communication Calling client library is properly set up and configured (https://www.npmjs.com/package/@azure/communication-calling).

An example using the Azure CLI to create and manage access tokens:

az communication identity token issue --scope voip --connection-string "yourConnectionString"

For more information, see Use Azure CLI to Create and Manage Access Tokens.

Install the Calling effects SDK

Use the npm install command to install the Azure Communication Calling Effects SDK for JavaScript.

npm install @azure/communication-calling-effects --save

For more information about the calling communication effects, see npm package page.

Supported video effects

Currently, the video effects support the following ability:

• Background blur.
• Replace the background with a custom image.

Class model

To use video effects with the Azure Communication Calling client library, create a LocalVideoStream, then get the VideoEffects feature from the LocalVideoStream.

Code examples

import * as AzureCommunicationCallingSDK from '@azure/communication-calling'; 
import { BackgroundBlurEffect, BackgroundReplacementEffect } from '@azure/communication-calling-effects'; 

// Ensure you have initialized the Azure Communication Calling client library and have created a LocalVideoStream 

// Get the video effects feature api on the LocalVideoStream 
const videoEffectsFeatureApi = localVideoStream.feature(AzureCommunicationCallingSDK.Features.VideoEffects); 

// Subscribe to useful events 
videoEffectsFeatureApi.on(‘effectsStarted’, () => { 
    // Effects started 
});
 
videoEffectsFeatureApi.on(‘effectsStopped’, () => { 
    // Effects stopped
});

videoEffectsFeatureApi.on(‘effectsError’, (error) => { 
    // Effects error 
}); 

// Create the effect instance 
const backgroundBlurEffect = new BackgroundBlurEffect(); 

// Recommended: Check if backgroundBlur is supported
const backgroundBlurSupported = await backgroundBlurEffect.isSupported(); 

if (backgroundBlurSupported) { 
    // Use the video effects feature api we created to start/stop effects 
    await videoEffectsFeatureApi.startEffects(backgroundBlurEffect); 
} 
 
/** 
To create a background replacement with a custom image you need to provide the URL of the image you want as the background to this effect. The 'startEffects' method will fail if the URL is not of an image or is unreachable/unreadable. 

Supported image formats are – png, jpg, jpeg, tiff, bmp. 
*/ 

const backgroundImage = 'https://linkToImageFile'; 

// Create the effect instance 
const backgroundReplacementEffect = new BackgroundReplacementEffect({ 
    backgroundImageUrl: backgroundImage 
}); 

// Recommended: Check if background replacement is supported:
const backgroundReplacementSupported = await backgroundReplacementEffect.isSupported(); 

if (backgroundReplacementSupported) { 
    // Use the video effects feature api as before to start/stop effects 
    await videoEffectsFeatureApi.startEffects(backgroundReplacementEffect); 
} 

//You can change the image used for this effect by passing it in the a new configure method: 
const newBackgroundImage = 'https://linkToNewImageFile';
await backgroundReplacementEffect.configure({ 
    backgroundImageUrl: newBackgroundImage 
}); 

//You can switch the effects using the same method on the video effects feature api: 

// Switch to background blur 
await videoEffectsFeatureApi.startEffects(backgroundBlurEffect); 

// Switch to background replacement 
await videoEffectsFeatureApi.startEffects(backgroundReplacementEffect); 

//To stop effects: 
await videoEffectsFeatureApi.stopEffects();