Merge pull request #231658 from akania/patch-26

Update manage-video-web.md

Author: prmerger-automator[bot]

articles/communication-services/how-tos/calling-sdk/includes/manage-video/manage-video-web.md

@@ -8,7 +8,7 @@ ms.author: rifox
 [!INCLUDE [Install SDK](../install-sdk/install-sdk-web.md)]
 
 ## Device management
-To begin using video with Calling, you will need to know how to manage devices. Devices allow you to control what transmits Audio and Video to the call.
+To begin using video with Calling, you need to know how to manage devices. Devices allow you to control what transmits Audio and Video to the call.
 
 In `deviceManager`, you can enumerate local devices that can transmit your audio and video streams in a call. You can also use it to request permission to access the local device's microphones and cameras.
 
@@ -35,7 +35,7 @@ const localSpeakers = await deviceManager.getSpeakers(); // [AudioDeviceInfo, Au
 
 ### Set the default microphone and speaker
 
-In `deviceManager`, you can set a default device that you'll use to start a call. If client defaults aren't set, Communication Services uses operating system defaults.
+In `deviceManager`, you can set a default device that you use to start a call. If client defaults aren't set, Communication Services uses operating system defaults.
 
 ```js
 // Get the microphone device that is being used.
@@ -72,7 +72,7 @@ Prompt a user to grant camera and/or microphone permissions:
 const result = await deviceManager.askDevicePermission({audio: true, video: true});
 ```
 
-This resolves with an object that indicates whether `audio` and `video` permissions were granted:
+The output returns with an object that indicates whether `audio` and `video` permissions were granted:
 
 ```js
 console.log(result.audio);
@@ -81,8 +81,8 @@ console.log(result.video);
 #### Notes
 - The 'videoDevicesUpdated' event fires when video devices are plugging-in/unplugged.
 - The 'audioDevicesUpdated' event fires when audio devices are plugged
-- When the DeviceManager is created, at first it does not know about any devices if permissions have not been granted yet, and so initially its device list is empty. If we then call the DeviceManager.askPermission() API, the user is prompted for device access and if the user clicks on 'allow' to grant the access, then the device manager will learn about the devices on the system, update it's device lists and emit the 'audioDevicesUpdated' and 'videoDevicesUpdated' events. Lets say we then refresh the page and create device manager, the device manager will be able to learn about devices because user has already previously granted access, and so it will initially it will have it's device lists filled and it will not emit 'audioDevicesUpdated' nor 'videoDevicesUpdated' events.
-- Speaker enumeration/selection is not supported on Android Chrome, iOS Safari, nor macOS Safari.
+- When the DeviceManager is created, at first it doesn't know about any devices if permissions haven't been granted yet so initially its device list will be empty. If we then call the DeviceManager.askPermission() API, the user is prompted for device access. When the user clicks on 'allow' to grant the access the device manager learns about the devices on the system, update it's device lists and emit the 'audioDevicesUpdated' and 'videoDevicesUpdated' events. If a user refreshes the page and creates a device manager, the device manager will be able to learn about devices because user has already previously granted access, and so it will initially it will have its device lists filled and it will not emit 'audioDevicesUpdated' nor 'videoDevicesUpdated' events.
+- Speaker enumeration/selection isn't supported on Android Chrome, iOS Safari, nor macOS Safari.
 
 ## Place a call with video camera
 
@@ -139,12 +139,12 @@ const camera = cameras[1];
 localVideoStream.switchSource(camera);
 ```
 
-If the specified video device is being used by another process, or if it is disabled in the system:
-- While in a call, if your video is off and you start video using `call.startVideo()`, this method will throw with a `SourceUnavailableError` and `cameraStartFiled` will be set to true.
-- A call to the `localVideoStream.switchSource()` method will cause `cameraStartFailed` to be set to true.
+If the specified video device is being used by another process, or if it's disabled in the system:
+- While in a call, if your video is off and you start video using `call.startVideo()`, this method throws a `SourceUnavailableError` and `cameraStartFiled` will be set to true.
+- A call to the `localVideoStream.switchSource()` method causes `cameraStartFailed` to be set to true.
 Our Call Diagnostics guide provides additional information on how to diagnose call related issues.
 
-To check or verify if the local video is on or off, you can use isLocalVideoStarted API, which returns true or false:
+To verify if the local video is on or off you can use isLocalVideoStarted API, which returns true or false:
 ```js
 // Check if local video is on or off
 call.isLocalVideoStarted;
@@ -175,7 +175,7 @@ await call.startScreenSharing();
 await call.stopScreenSharing();
 ```
 
-To check or verify if screen sharing is on or off, you can use isScreenSharingOn API which returns true or false:
+To verify if screen sharing is on or off, you can use isScreenSharingOn API, which returns true or false:
 ```js
 // Check if screen sharing is on or off
 call.isScreenSharingOn;
@@ -202,10 +202,9 @@ const remoteVideoStream: RemoteVideoStream = call.remoteParticipants[0].videoStr
 const streamType: MediaStreamType = remoteVideoStream.mediaStreamType;
 ```
 
-To render `RemoteVideoStream`, you have to subscribe to it's `isAvailableChanged` event. If the `isAvailable` property changes to `true`, a remote participant is sending a stream. After that happens, create a new instance of `VideoStreamRenderer`, and then create a new `VideoStreamRendererView` instance by using the asynchronous `createView` method.  You can then attach `view.target` to any UI element.
+To render `RemoteVideoStream`, you have to subscribe to its `isAvailableChanged` event. If the `isAvailable` property changes to `true`, a remote participant is sending a stream. After that happens, create a new instance of `VideoStreamRenderer`, and then create a new `VideoStreamRendererView` instance by using the asynchronous `createView` method.  You can then attach `view.target` to any UI element.
 
-Whenever availability of a remote stream changes, you can choose to destroy the whole `VideoStreamRenderer`, a specific `VideoStreamRendererView`
-or keep them, but this will result in displaying blank video frame.
+Whenever availability of a remote stream changes, you can destroy the whole `VideoStreamRenderer` or a specific `VideoStreamRendererView`. If you do decided to keep them will result in displaying blank video frame.
 
 ```js
 // Reference to the html's div where we would display a grid of all remote video stream from all participants.
@@ -310,6 +309,29 @@ CSS for styling the loading spinner over the remote video stream.
 }
 ```
 
+### Remote video quality
+
+Starting from 1.12(beta) version, the ACS WebJS SDK provides a new feature called OptimalVideoCount (OVC). This feature can be used to inform applications at run-time how many videos from different participants can be optimally rendered at a given moment in a group call (2+ participants). This feature exposes a property `optimalVideoCount` that is dynamically changing during the call based on the network and hardware capabilities of a local endpoint. The value of `optimalVideoCount` details how many videos from different participants application should render at a given moment. Application should handle these changes and update number of rendered videoes accordingly to the recommendation. There's a cooldown period (around 10s), between updates that to avoid too frequent of changes.
+
+**Usage**
+The `optimalVideoCount` feature is a call feature
+```typescript
+interface OptimalVideoCountCallFeature extends CallFeature {
+    off(event: 'optimalVideoCountChanged', listener: PropertyChangedEvent): void;
+    on(event: 'optimalVideoCountChanged', listener: PropertyChangedEvent): void;
+    readonly optimalVideoCount: number;
+}
+
+const optimalVideoCountFeature = call.feature(Features.OptimalVideoCount);
+optimalVideoCountFeature.on('optimalVideoCountChanged', () => {
+    const localOptimalVideoCountVariable = optimalVideoCountFeature.optimalVideoCount;
+})
+```
+
+Example usage: Application should subscribe to changes of OVC and handle it in group calls by either creating new renderer (`createView` method) or dispose views (`dispose`)
+and update layout accordingly either by removing participants from the main call screen area (often called stage or roster ) or replacing their video elements with an avatar and a name of the user.
+
+
 ### Remote video stream properties
 
 Remote video streams have the following properties:
@@ -326,7 +348,7 @@ const id: number = remoteVideoStream.id;
 const type: MediaStreamType = remoteVideoStream.mediaStreamType;
 ```
 
-- `isAvailable`: Whether a remote participant endpoint is actively sending a stream.
+- `isAvailable`: Defines whether a remote participant endpoint is actively sending a stream.
 
 ```js
 const isAvailable: boolean = remoteVideoStream.isAvailable;
@@ -337,12 +359,12 @@ const isAvailable: boolean = remoteVideoStream.isAvailable;
     > [!NOTE]
     > This API is provided as a preview for developers and may change based on feedback that we receive. To use this api please use 1.5.4-beta.1+ release of Azure Communication Services Calling Web SDK
     - Will inform the application if remote video stream data is being received or not. Such scenarios are:
-        - I am viewing the video of a remote participant who is on mobile browser. The remote participant brings the mobile browser app to the background. I now see the RemoteVideoStream.isReceiving flag goes to false and I see his video with black frames / frozen. When the remote participant brings the mobile browser back to the foreground, I now see the RemoteVideoStream.isReceiving flag to back to true, and I see his video playing normally.
-        - I am viewing the video of a remote participant who is on whatever platforms. There are network issues from either side, his video start to look pretty laggy, bad quality, probbaly because of network issues, so I see the RemoteVideoStream.isReceiving flag goes to false.
-        - I am viewing the video of a Remote participant who is On MacOS/iOS Safari, and from their address bar, they click on "Pause" / "Resume" camera. I'll see a black/frozen video since they paused their camera and I'll see the RemoteVideoStream.isReceiving flag goes to false. Once they resume playing the camera, then I'll see the RemoteVideoStream.isReceiving flag goes to true.
-        - I am viewing the video of a remote participant who in on whatever platform. And for whatever reason their network disconnects. This will actually leave the remote participant in the call for a little while and I'll see his video frozen/black frame, and ill see RemoteVideoStream.isReceiving flag goes to false. The remote participant can get network back and reconnect and his audio/video should start flowing normally and I'll see the RemoteVideoStream.isReceiving flag to true.
-        - I am viewing the video of a remote participant who is on mobile browser. The remote participant terminates/kills the mobile browser. Since that remote participant was on mobile, this will actually leave the participant in the call for a little while and I will still see him in the call and his video will be frozen, and so I'll see the RemoteVideoStream.isReceiving flag goes to false. At some point, service will kick participant out of the call and I would just see that the participant disconnected from the call.
-        - I am viewing the video of a remote participant who is on mobile browser and they locks device. I'll see the RemoteVideoStream.isReceiving flag goes to false and. Once the remote participant unlocks the device and navigates to the acs call, then ill see the flag go back to true. Same behavior when remote participant is on desktop and the desktop locks/sleeps
+        - I am viewing the video of a remote participant who is on mobile browser. The remote participant brings the mobile browser app to the background. I now see the RemoteVideoStream.isReceiving flag goes to false and I see their video with black frames / frozen. When the remote participant brings the mobile browser back to the foreground, I now see the RemoteVideoStream.isReceiving flag to back to true, and I see their video playing normally.
+        - I am viewing the video of a remote participant who is on whatever platforms. There are network issues from either side, their video start to have bad quality, probably because of network issues, so I see the RemoteVideoStream.isReceiving flag goes to false.
+        - I am viewing the video of a Remote participant who is On MacOS/iOS Safari, and from their address bar, they click on "Pause" / "Resume" camera. I see a black/frozen video since they paused their camera and I see the RemoteVideoStream.isReceiving flag goes to false. Once they resume playing the camera, then I see the RemoteVideoStream.isReceiving flag goes to true.
+        - I am viewing the video of a remote participant who in on whatever platform. And for whatever reason their network disconnects. This will actually leave the remote participant in the call for a little while and I see their video frozen/black frame, and see RemoteVideoStream.isReceiving flag goes to false. The remote participant can get network back and reconnect and their audio/video should start flowing normally and I see the RemoteVideoStream.isReceiving flag to true.
+        - I am viewing the video of a remote participant who is on mobile browser. The remote participant terminates/kills the mobile browser. Since that remote participant was on mobile, this will actually leave the participant in the call for a little while and I will still see them on the call and their video will be frozen, and so I  see the RemoteVideoStream.isReceiving flag goes to false. At some point, service will kick participant out of the call and I would just see that the participant disconnected from the call.
+        - I am viewing the video of a remote participant who is on mobile browser and they lock the device. I see the RemoteVideoStream.isReceiving flag goes to false. Once the remote participant unlocks the device and navigates to the acs call, then ill see the flag go back to true. Same behavior when remote participant is on desktop and the desktop locks/sleeps
     - This feature improves the user experience for rendering remote video streams.
     - You can display a loading spinner over the remote video stream when isReceiving flag changes to false. You don't have to do a loading spinner, you can do anything you desire, but a loading spinner is the most common usage for better user experience.
 ```js