Merge pull request #221409 from sloanster/patch-8

Create video-effects.md

Author: JamesJBarnett

articles/communication-services/concepts/voice-video-calling/video-effects.md

@@ -0,0 +1,152 @@
+---
+ms.author: micahvivion
+title: Azure Communication Services Calling video WebJS video effects
+titleSuffix: An Azure Communication Services document
+description: In this document, you'll learn how to create video effects on an Azure Communication Services call.
+author: sloanster
+services: azure-communication-services
+
+ms.date: 1/9/2023
+ms.topic: conceptual
+ms.service: azure-communication-services
+ms.subservice: calling
+---
+
+# Adding visual effects to a video call
+
+[!INCLUDE [Public Preview](../../includes/public-preview-include-document.md)]
+
+>[!IMPORTANT]
+> The Calling Video effects are available starting on the public preview version [1.9.1-beta.1](https://www.npmjs.com/package/@azure/communication-calling/v/1.9.1-beta.1) of the Calling SDK. Please ensure that you use this or a newer SDK when using video effects.
+
+> [!NOTE]
+> This API is provided as a preview ('beta') for developers and may change based on feedback that we receive.
+
+> [!NOTE]
+> This library cannot be used standalone and can only work when used with the Azure Communication Calling client library for WebJS (https://www.npmjs.com/package/@azure/communication-calling). 
+
+The Azure Communication Calling SDK allows you to create video effects that other users on a call will be able to see. For example, for a user doing ACS calling using the WebJS SDK you can now enable that the user can turn on background blur. When background blur enabled a user can feel more comfortable in doing a video call that the output video will just show a user and all other content will be blurred.
+
+## Prerequisites
+### Install the Azure Communication Services Calling SDK
+- An Azure account with an active subscription is required. See [Create an account for free](https://azure.microsoft.com/free/?WT.mc_id=A261C142F) on how to create an Azure account.
+- [Node.js](https://nodejs.org/) active Long Term Support(LTS) versions are recommended.
+- An active Communication Services resource. [Create a Communication Services resource](../../quickstarts/create-communication-resource.md).
+- A User Access Token to instantiate a call client. Learn how to [create and manage user access tokens](../../quickstarts/access-tokens.md). You can also use the Azure CLI and run the command below with your connection string to create a user and an access token. (Need to grab 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 
+```azurecli-interactive
+az communication identity token issue --scope voip --connection-string "yourConnectionString"
+```
+For details on using the CLI, see [Use Azure CLI to Create and Manage Access Tokens](../../quickstarts/access-tokens.md?pivots=platform-azcli).
+
+## Install the Calling effects SDK 
+Use ‘npm install’ command to install the Azure Communication Calling Effects SDK for JavaScript. 
+
+'npm install @azure/communication-calling-effects –save'
+
+## Supported video effects:
+Currently the video effects support the following ability:
+- Background blur 
+- Replace the background with a custom image 
+
+## Browser support: 
+
+Currently creating video effects is only supported on Chrome Desktop Browser and Mac Safari Desktop.
+
+## Class model:
+
+| Name  | Description  |
+|---|---|
+| BackgroundBlurEffect  | The background blur effect class.  |
+| BackgroundReplacementEffect  | The background replacement with image effect class.  |
+
+To use video effects with the Azure Communication Calling client library, once you've created a LocalVideoStream, you need to get the VideoEffects feature API of from the LocalVideoStream. 
+
+### Code examples
+```js
+import * as AzureCommunicationCallingSDK from '@azure/communication-calling'; 
+import { BackgroundBlur, BackgroundReplacement } from '@azure/communication-calling-effects'; 
+
+/** Assuming you have initialized the Azure Communication Calling client library and have created a LocalVideoStream 
+(reference <link to main SDK npm>) 
+*/ 
+
+// Get the video effects feature api on the LocalVideoStream 
+const videoEffectsFeatureApi = localVideoStream.features(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 BackgroundBlur(); 
+
+// 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 BackgroundReplacement({ 
+
+    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();
+
+```