Rewamp the isReceiving section

Author: Kevin Le Goff

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

@@ -165,7 +165,8 @@ console.log(result.video);
 
 To place a video call, you have to  enumerate local cameras by using the `getCameras()` method in `deviceManager`.
 
-After you select a camera, use it to construct a `LocalVideoStream` instance. Pass it within `videoOptions` as an item within the `localVideoStream` array to the `startCall` method.
+After you select a camera, use it to construct a `LocalVideoStream` instance. 
+Pass it within `videoOptions` as an item within the `localVideoStream` array to the `CallAgent` `startCall` method.
 
 ```js
 const deviceManager = await callClient.getDeviceManager();
@@ -181,7 +182,11 @@ const call = callAgent.startCall([userCallee], placeCallOptions);
 
 ## Start and stop sending local video while on a call
 
-To start a video while on a call, you have to enumerate cameras using the `getCameras` method on the `deviceManager` object. Then create a new instance of `LocalVideoStream` with the desired camera and then pass the `LocalVideoStream` object into the `startVideo` method of an existing call object:
+
+### Start video
+To start a video while on a call, you have to enumerate cameras using the `getCameras` method on the `deviceManager` object. 
+Then create a new instance of `LocalVideoStream` with the desired camera and then pass the `LocalVideoStream` 
+object into the `startVideo` method of an existing call object:
 
 ```js
 const deviceManager = await callClient.getDeviceManager();
@@ -191,19 +196,25 @@ const localVideoStream = new LocalVideoStream(camera);
 await call.startVideo(localVideoStream);
 ```
 
-After you successfully start sending video, a `LocalVideoStream` instance of type `Video` is added to the `localVideoStreams` collection on a call instance.
 
+### Stop Video
+
+After you successfully start sending video, a `LocalVideoStream` instance of type `Video` is added to the `localVideoStreams` 
+collection on a call instance.
+
+**Find the video stream in the Call object**
 ```js
 const localVideoStream = call.localVideoStreams.find( (stream) => { return stream.mediaStreamType === 'Video'} );
 ```
 
-To stop local video while on a call, pass the `localVideoStream` instance that's being used for video:
+**Stop the local video**
+To stop local video while on a call, pass the `localVideoStream` instance that's being used for video to the stopVideo method of the `Call`:
 
 ```js
 await call.stopVideo(localVideoStream);
 ```
 
-You can switch to a different camera device while a video is sending by invoking `switchSource` on a `localVideoStream` instance:
+You can switch to a different camera device while having an active LocalVideoStream by invoking `switchSource` on that `LocalVideoStream` instance:
 
 ```js
 const cameras = await callClient.getDeviceManager().getCameras();
@@ -212,11 +223,11 @@ localVideoStream.switchSource(camera);
 ```
 
 If the specified video device is being used by another process, or if it is not enabled 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` user facing diagnostic is set to true.
+- While in a call, if your video is off and you start video using `call.startVideo()`, this method throws a `SourceUnavailableError` and `cameraStartFailed` user facing diagnostic is 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 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  the `Call` method `isLocalVideoStarted`, which returns true or false:
 ```js
 // Check if local video is on or off
 call.isLocalVideoStarted;
@@ -234,26 +245,29 @@ call.off('isLocalVideoStartedChanged', () => {
 });
 ```
 
-
-
 ## Start and stop screen sharing while on a call
-To start screen sharing while on a call, you can use asynchronous API startScreenSharing:
+To start screen sharing while on a call, you can use the asynchronous method `startScreenSharing()` on a `Call` object:
+
+### Start screen sharing
 ```js
 // Start screen sharing
 await call.startScreenSharing();
 ```
 
+### Find the screen sharing in the collection of LocalVideoStream
 After you successfully start sending screen sharing, a `LocalVideoStream` instance of type `ScreenSharing`, is added to the `localVideoStreams` collection on the call instance.
 ```js
 const localVideoStream = call.localVideoStreams.find( (stream) => { return stream.mediaStreamType === 'ScreenSharing'} );
 ```
 
+### Stop screen sharing
 To stop screen sharing while on a call, you can use asynchronous API stoptScreenSharing:
 ```js
 // Stop screen sharing
 await call.stopScreenSharing();
 ```
 
+### Check the screen sharing status
 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
@@ -274,8 +288,11 @@ call.off('isScreenSharingOnChanged', () => {
 
 [!INCLUDE [Public Preview Disclaimer](../../../../includes/public-preview-include.md)]
 Local screen share preview is in public preview and available as part of version 1.15.1-beta.1+.
+
 ### Local screen share preview
-You can use `VideoStreamRenderer` to begin rendering streams from your local screen share so you can see what you are sending as a screen sharing stream.
+
+You can use a `VideoStreamRenderer` to begin rendering streams from your local screen share so you can see 
+what you are sending as a screen sharing stream.
 ```js
 // To start viewing local screen share preview
 await call.startScreenSharing();
@@ -303,23 +320,32 @@ call.on('isScreenSharingOnChanged', () => {
 
 ## Render remote participant video/screensharing streams
 
-To list the video streams and screen sharing streams of remote participants, inspect the `videoStreams` collections:
+<!-- To list the video streams and screen sharing streams of remote participants, inspect the `videoStreams` collections:
+ -->
+The to render a remote participant video or screensharing, the first step is to get a reference on the RemoteVideoStream you want to render.
+This can be done by going through the array or video stream (`videoStreams`) of the `RemoteParticipant`. The remote particpant collection 
+is accessed via the `Call` object.
 
 ```js
 const remoteVideoStream: RemoteVideoStream = call.remoteParticipants[0].videoStreams[0];
 const streamType: MediaStreamType = remoteVideoStream.mediaStreamType;
 ```
 
-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.
+To render `RemoteVideoStream`, you have to subscribe to its `isAvailableChanged` event. If the `isAvailable` property changes to `true`,
+a remote participant is sending a video 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 destroy the whole `VideoStreamRenderer` or a specific `VideoStreamRendererView`. If you do decided to keep them, then the view displays a blank video frame.
+Whenever the availability of a remote stream changes, you can destroy the whole `VideoStreamRenderer` or 
+a specific `VideoStreamRendererView`. If you do decided to keep them, then the view displays a blank video frame.
 
 ```js
 // Reference to the html's div where we would display a grid of all remote video stream from all participants.
 let remoteVideosGallery = document.getElementById('remoteVideosGallery');
 
 subscribeToRemoteVideoStream = async (remoteVideoStream) => {
-   let renderer = new VideoStreamRenderer(remoteVideoStream);
+    let renderer = new VideoStreamRenderer(remoteVideoStream);
     let view;
     let remoteVideoContainer = document.createElement('div');
     remoteVideoContainer.className = 'remote-video-container';
@@ -415,10 +441,17 @@ CSS for styling the loading spinner over the remote video stream.
 
 ### Remote video quality
 
-The Azure Communication Services WebJS SDK, starting in version [1.15.1](https://github.com/Azure/Communication/blob/master/releasenotes/acs-javascript-calling-library-release-notes.md#1153-stable-2023-08-18), provides a feature called Optimal Video Count (OVC). This feature can be used to inform applications at run-time how many incoming 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. Applications should handle these changes and update number of rendered videoes accordingly to the recommendation. There's a cooldown period (around 10 s), between updates that to avoid too frequent of changes.
+The Azure Communication Services WebJS SDK, provides a feature called Optimal Video Count (OVC), starting in version [1.15.1](https://github.com/Azure/Communication/blob/master/releasenotes/acs-javascript-calling-library-release-notes.md#1153-stable-2023-08-18). 
+This feature can be used to inform applications at run-time about how many incoming 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 participant
+application should render at a given moment. Applications should handle these changes and update number of rendered videos
+accordingly to the recommendation. There's a debounce period (around 10 s) between each update.
 
 **Usage**
 The `optimalVideoCount` feature is a call feature
+
+<!-- TODO KLG convert this to Javascript -->
 ```typescript
 interface OptimalVideoCountCallFeature extends CallFeature {
     off(event: 'optimalVideoCountChanged', listener: PropertyChangedEvent): void;
@@ -432,9 +465,8 @@ optimalVideoCountFeature.on('optimalVideoCountChanged', () => {
 })
 ```
 
-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.
-
+Example usage: Application should subscribe to changes of Optimal Video Count in group calls. A change in the optimal video count can be handled
+by either creating new renderer (`createView` method) or dispose views (`dispose`) and update the application layout accordingly.
 
 ### Remote video stream properties
 
@@ -459,13 +491,23 @@ const isAvailable: boolean = remoteVideoStream.isAvailable;
 ```
 
 - `isReceiving`:
-    - Informs the application if remote video stream data is being received or not. Such scenarios are:
-        - I'm 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'm 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'm 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'm viewing the video of a remote participant who is on any platform and their network disconnects. The remote participant will stay in the call for about two minutes and I see their video frozen/black frame. The 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'm 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 about two minutes. I will still see them on the call and their video will be frozen. 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'm 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 Azure Communication Services call, then I'll see the flag go back to true. Same behavior when remote participant is on desktop and the desktop locks/sleeps
+  - Informs the application if remote video stream data is being received or not. All scenarios listed assumes the remote partipant is 
+sharing its video
+  
+    - The flag moves to `false` in the following scenarios:
+      - A remote participant who is on mobile browser brings the browser app to the background. 
+      - A remote participant or the user receiving the video has network issue that affects video quality drastically.
+      - A remote participant who is On macOS/iOS Safari clicks on "Pause" from their address bar.
+      - A remote participant has a network disconnection. 
+      - A remote particpant on mobile kills or terminate the browser. 
+      - A remote particpant on mobile or desktop locks his device. This scenario applies also if the remote particpant is on a desktop computer and it goes to sleep.
+ 
+    - The flag moves to `true` in the following scenarios:
+      - A remote participant whos is on mobile browser and has his browser backgrounded brings it back to foreground.
+      - A remote participant who is On macOS/iOS Safari clicks on "Resume" from their address bar after having paused its video.
+      - A remote participant has a reconnects to the network after a temporary disconnection.
+      - A remote participant on mobile unlock his device and return to the call on his mobile browser.
+        
     - 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