Skip to content

Commit 3508b66

Browse files
American-DipperAmerican-Dipper
authored
Merge pull request #270508 from enricohuang/patch-21
Add troubleshooting guide for Azure Communication Services Web Calling SDK - video issues
2 parents 232daae + 5cf123d commit 3508b66

11 files changed

+410
-0
lines changed

‎articles/communication-services/resources/troubleshooting/voice-video-calling/video-issues/application-disposes-video-renderer.md

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
---
2+
title: Video issues - The application disposes the video renderer while subscribing the video
3+
titleSuffix: Azure Communication Services - Troubleshooting Guide
4+
description: Learn how to handle the error when the application disposes the video renderer while subscribing the video.
5+
author: enricohuang
6+
ms.author: enricohuang
7+
8+
services: azure-communication-services
9+
ms.date: 04/05/2024
10+
ms.topic: troubleshooting
11+
ms.service: azure-communication-services
12+
ms.subservice: calling
13+
---
14+
# Your application disposes the video renderer while subscribing to a video
15+
The [`createView`](/javascript/api/%40azure/communication-react/statefulcallclient?view=azure-node-latest&preserve-view=true#@azure-communication-react-statefulcallclient-createview) API doesn't resolve immediately, as there are multiple underlying asynchronous operations involved in the video subscription process and thus this API response is an asynchronous response.
16+
17+
If your application disposes of the render object while the video subscription is in progress, the [`createView`](/javascript/api/%40azure/communication-react/statefulcallclient?view=azure-node-latest&preserve-view=true#@azure-communication-react-statefulcallclient-createview) API throws an error.
18+
19+
## How to detect using the SDK
20+
21+
22+
| Error | Details |
23+
|------------------|-------------------------------------------------------|
24+
| code | 405(Method Not Allowed) |
25+
| subcode | 43209 |
26+
| message | Failed to start stream, disposing stream |
27+
| resultCategories | Expected |
28+
29+
## How to mitigate or resolve
30+
Your application should verify whether it intends to dispose the renderer or if it's due to an unexpected renderer disposal.
31+
The unexpected renderer disposal can be triggered when certain user interface resources are released in the application layer.
32+
If your application indeed needs to dispose of the renderer video during video subscription, it should gracefully handle this error thrown by the SDK.

‎articles/communication-services/resources/troubleshooting/voice-video-calling/video-issues/create-view-timeout.md

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
---
2+
title: Video issues - CreateView timeout
3+
titleSuffix: Azure Communication Services - Troubleshooting Guide
4+
description: Learn how to troubleshoot CreateView timeout error.
5+
author: enricohuang
6+
ms.author: enricohuang
7+
8+
services: azure-communication-services
9+
ms.date: 04/05/2024
10+
ms.topic: troubleshooting
11+
ms.service: azure-communication-services
12+
ms.subservice: calling
13+
---
14+
15+
# CreateView timeout
16+
When the calling SDK expects to receive video frames but there are no incoming video frames,
17+
the SDK detects this issue and throws an createView timeout error.
18+
19+
This error is unexpected from SDK's perspective. This error indicates a discrepancy between signaling and media transport.
20+
## How to detect using SDK
21+
When there's a `create view timeout` issue, the [`createView`](/javascript/api/%40azure/communication-react/statefulcallclient?view=azure-node-latest&preserve-view=true#@azure-communication-react-statefulcallclient-createview) API throws an error.
22+
23+
| Error | Details |
24+
|------------------|-------------------------------------------------------|
25+
| code | 408(Request Timeout) |
26+
| subcode | 43203 |
27+
| message | Failed to render stream, timeout |
28+
| resultCategories | Unexpected |
29+
30+
## Reasons behind createView timeout failures and how to mitigate the issue
31+
### The video sender's browser is in the background
32+
Some mobile devices don't send any video frames when the browser is in the background or a user locks the screen.
33+
The [`createView`](/javascript/api/%40azure/communication-react/statefulcallclient?view=azure-node-latest&preserve-view=true#@azure-communication-react-statefulcallclient-createview) API detects no incoming video frames and considers this situation a subscription failure, therefore, it throws a createView timeout error.
34+
No further detailed information is available because currently the SDK doesn't support notifying receivers that the sender's browser is in the background.
35+
36+
Your application can implement its own detection mechanism and notify the participants in a call when the sender's browser goes back to foreground.
37+
The participants can subscribe the video again.
38+
A feasible but less elegant approach for handling this createView timeout error is to continuously retry invoking the [`createView`](/javascript/api/%40azure/communication-react/statefulcallclient?view=azure-node-latest&preserve-view=true#@azure-communication-react-statefulcallclient-createview) API until it succeeds.
39+
40+
### The video sender dropped from the call unexpectedly
41+
Some users might end the call by terminating the browser process instead of by hanging up.
42+
The server is unaware that the user dropped the call until the timeout of 40 seconds ended.
43+
The participant remains on roster list until the server removes it at the end of the timeout (40 seconds).
44+
If other participants try to subscribe to a video from the user who dropped from the call unexpectedly, they get an error as no incoming video frames are received.
45+
No further detailed information is available. The server maintains the participants in the roster list even if no answer is received from them, until the timeout period ends.
46+
47+
48+
### The video sender has network issues
49+
If the video sender has network issues during the time other participants are subscribing to their video the video, subscription may fail.
50+
This error is unexpected on the video receiver's side.
51+
For example, if the sender experiences a temporary network disconnection, other participants are unable to receive video frames from the sender.
52+
53+
A workaround approach for handling this createView timeout error is to continuously retry invoking [`createView`](/javascript/api/%40azure/communication-react/statefulcallclient?view=azure-node-latest&preserve-view=true#@azure-communication-react-statefulcallclient-createview) API until it succeeds when this network event is happening.
54+
55+
### The video receiver has network issues
56+
Similar to the sender's network issues, if a video receiver has network issues the video subscription may fail.
57+
This issue could be due to high packet loss rate or temporary network connection errors.
58+
The SDK can detect network disconnection and fires a [`networkReconnect`](../../../../concepts/voice-video-calling/user-facing-diagnostics.md?pivots=platform-web#network-values) UFD event.
59+
However, in a WebRTC call, the default `STUN connectivity check` triggers a disconnection event if there's no response from the other party after around 10-15 seconds.
60+
61+
62+
63+
64+
This means if there's a [`networkReconnect`](../../../../concepts/voice-video-calling/user-facing-diagnostics.md?pivots=platform-web#network-values) UFD, the receiver side might not have received packets for already 15 seconds.
65+
66+
If there are network issues from the connection on the receiver's side, your application should subscribe to the video after [`networkReconnect`](../../../../concepts/voice-video-calling/user-facing-diagnostics.md?pivots=platform-web#network-values) UFD is recovered.
67+
You'll likely have limited control over network issues. Thus, we advise monitoring the network information and presenting the information on the user interface. You should also consider monitoring your client [media quality and network status](../../../../concepts/voice-video-calling/media-quality-sdk.md?pivots=platform-web) and make necessary changes to your client as needed. For instance, you might consider automatically turning off incoming video streams when you notice that the client is experience degraded network performance.
68+

‎articles/communication-services/resources/troubleshooting/voice-video-calling/video-issues/media/video-stream-flow.png

45.9 KB
Loading

‎articles/communication-services/resources/troubleshooting/voice-video-calling/video-issues/network-poor.md

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
---
2+
title: Video issues - The network is poor during the call
3+
titleSuffix: Azure Communication Services - Troubleshooting Guide
4+
description: Learn how to troubleshoot poor video quality when the network is poor during the call.
5+
author: enricohuang
6+
ms.author: enricohuang
7+
8+
services: azure-communication-services
9+
ms.date: 04/05/2024
10+
ms.topic: troubleshooting
11+
ms.service: azure-communication-services
12+
ms.subservice: calling
13+
---
14+
15+
# The network is poor during the call
16+
The quality of the network affects video quality on the sender and receiver's side.
17+
If the sender's network bandwidth becomes poor, the sender's SDK may adjust the video's encoding resolution and frame rate. In doing so, the SDK ensures that it doesn't send more data than the current network can support.
18+
19+
Similarly, when the receiver's bandwidth becomes poor in a group call and the [simulcast](../../../../concepts/voice-video-calling/simulcast.md) is enabled on the sender's side, the server may forward a lower resolution stream.
20+
This mechanism can reduce the impact of the network on the receiver's side.
21+
22+
Other network characteristics, such as packet loss, round trip time, and jitter, also affect the video quality.
23+
24+
## How to detect using the SDK
25+
26+
The [User Facing Diagnostics API](../../../../concepts/voice-video-calling/user-facing-diagnostics.md) gives feedback to your application about the occurrence of real time network impacting events.
27+
28+
For the network quality of the video sending end, you can check events with the values of `networkReconnect` and `networkSendQuality`.
29+
30+
For the network quality of the receiving end, you can check events with the values of `networkReconnect` and `networkReceiveQuality`.
31+
32+
In addition, the [media quality stats API](../../../../concepts/voice-video-calling/media-quality-sdk.md) also provides a way to monitor the network and video quality.
33+
34+
For the quality of the video sending end, you can check the metrics `packetsLost`, `rttInMs`, `frameRateSent`, `frameWidthSent`, `frameHeightSent`, and `availableOutgoingBitrate`.
35+
36+
For the quality of the receiving end, you can check the metrics `packetsLost`, `frameRateDecoded`, `frameWidthReceived`, `frameHeightReceived`, and `framesDropped`.
37+
38+
## How to mitigate or resolve
39+
From the perspective of the ACS Calling SDK, network issues are considered external problems.
40+
To solve network issues, it's often necessary to understand the network topology and the nodes causing the problem.
41+
42+
The ACS Calling SDK and browser adaptively adjust the video quality according to the networks condition.
43+
It's important for the application to handle events from the User Facing Diagnostics Feature and notify the users accordingly.
44+
In this way, users can be aware of any network quality issues and aren't surprised if they experience low-quality video during a call.
45+
46+
You should also consider monitoring your client [media quality and network status](../../../../concepts/voice-video-calling/media-quality-sdk.md?pivots=platform-web) and taking action when low quality or poor network is reported. For instance, you might consider automatically turning off incoming video streams when you notice that the client is experience degraded network performance. In other instances, you might give feedback to a user that they should turn off their camera because they have a poor internet connection.
47+
48+
If you have a hypothesis that the user's network environment is poor or unstable, you can also use the [Video Constraint API](../../../../concepts/voice-video-calling/video-constraints.md) to limit the maximum resolution, maximum frames per second (fps), and\or maximum bitrate sent or received to reduce the bandwidth required for video transmission.
49+

‎articles/communication-services/resources/troubleshooting/voice-video-calling/video-issues/overview.md

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
---
2+
title: Video issues - Overview of how to understand and mitigate quality issues
3+
titleSuffix: Azure Communication Services - Troubleshooting Guide
4+
description: Overview of video issues
5+
author: enricohuang
6+
ms.author: enricohuang
7+
8+
services: azure-communication-services
9+
ms.date: 04/05/2024
10+
ms.topic: troubleshooting
11+
ms.service: azure-communication-services
12+
ms.subservice: calling
13+
---
14+
15+
# Overview of video issues
16+
17+
Establishing a video call involves many components and processes. Steps include the video stream acquisition from a camera device, browser encoding, browser decoding, video rendering, and so on.
18+
If there's a problem in any of these stages, users may experience video-related issues.
19+
For example, users may complain about being unable to see the video or the poor quality of the video.
20+
Therefore, understanding how video content flow from the sender to the receiver is crucial for debugging and mitigating video issues.
21+
22+
## How a video call works from an end-to-end perspective
23+
24+
:::image type="content" source="./media/video-stream-flow.png" alt-text="Diagram of the end-to-end flow of video stream data":::
25+
26+
Here we use an Azure Communication Services group call as an example.
27+
28+
When the sender starts video in a call, the SDK internally retrieves the camera video stream via a browser API.
29+
After the SDK completes the handshake at the signaling layer with the server, it begins sending the video stream to the server.
30+
The browser performs video encoding and packetization at the RTP(Real-time Transport Protocol) layer for transmission.
31+
The other participants in the call receive notifications from the server, indicating the availability of a video stream from the sender.
32+
Your application can decide whether to subscribe to the video stream or not.
33+
If your application subscribes to the video stream from the server (for example, using [`createView`](/javascript/api/%40azure/communication-react/statefulcallclient?view=azure-node-latest&preserve-view=true#@azure-communication-react-statefulcallclient-createview) API), the server forwards the sender's video packets to the receiver.
34+
The receiver's browser decodes and renders the incoming video.
35+
36+
When you use ACS Web Calling SDK for video calls, the SDK and browser may adjust the video quality of the sender based on the available bandwidth.
37+
The adjustment may include changes in resolution, frames per second, and target bitrate.
38+
Additionally, CPU overload on the sender side can also influence the browser's decision on the target resolution for encoding.
39+
40+
## Common issues in video calls
41+
42+
We can see that the whole process involves factors such as the sender's camera device.
43+
The network conditions at the sender and receiver end also play an important role.
44+
Bandwidth and packets lost can impact the video quality perceived by the users.
45+
46+
Here we list several common video issues, along with potential causes for each issue:
47+
48+
### The user can't see video from the remote participant
49+
50+
* The sender's video isn't available when the user subscribes to it
51+
* The remote video becomes unavailable while subscribing the video
52+
* The application disposes the video renderer while subscribing the video
53+
* The maximum number of active video subscriptions was reached
54+
* The video sender's browser is in the background
55+
* The video sender dropped the call unexpectedly
56+
* The video sender experiences network issues
57+
* The receiver experiences network issues
58+
* The frames are received but not decoded
59+
60+
### The user only sees black video from the remote participant
61+
* The video sender's browser is in the background
62+
63+
### The user experiences poor video quality
64+
* The video sender has poor network
65+
* The receiver has poor network
66+
* Heavy load on the environment of the video sender or receiver
67+
* The receiver subscribes multiple incoming video streams

‎articles/communication-services/resources/troubleshooting/voice-video-calling/video-issues/reaching-max-number-of-active-video-subscriptions.md

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
---
2+
title: Video issues - The maximum number of active incoming video subscriptions is exceeded
3+
titleSuffix: Azure Communication Services - Troubleshooting Guide
4+
description: Learn how to handle errors when the maximum number of active incoming video subscriptions was reached
5+
author: enricohuang
6+
ms.author: enricohuang
7+
8+
services: azure-communication-services
9+
ms.date: 04/05/2024
10+
ms.topic: troubleshooting
11+
ms.service: azure-communication-services
12+
ms.subservice: calling
13+
---
14+
# The maximum number of active incoming video streams is reached the limit or been exceeded
15+
Azure Communication Service currently imposes a maximum limit on the number of active incoming video subscriptions that are rendered at a time. The current limit is 10 videos on desktop browsers and 6 videos on mobile browsers. Review the [supported browser list](../../../../concepts/voice-video-calling/calling-sdk-features.md#javascript-calling-sdk-support-by-os-and-browser) to see what browsers currently work with Azure Communication Services WebJS SDK.
16+
17+
## How to detect using the SDK
18+
If the number of active video subscriptions exceeds the limit, the [`createView`](/javascript/api/%40azure/communication-react/statefulcallclient?view=azure-node-latest&preserve-view=true#@azure-communication-react-statefulcallclient-createview) API throws an error.
19+
20+
21+
| Error details | Details |
22+
|------------------|-------------------------------------------------------|
23+
| code | 400(Bad Request) |
24+
| subcode | 43220 |
25+
| message | Failed to create view, maximum number of 10 active RemoteVideoStream has been reached. (*maximum number of 6* for mobile browsers) |
26+
| resultCategories | Expected |
27+
28+
## How to ensure that your client subscribes to the correct number of video streams
29+
Your applications should catch and handle this error gracefully. To understand how many incoming videos should be rendered, use the [Optimal Video Count (OVC)](../../../../how-tos/calling-sdk/manage-video.md?pivots=platform-web#remote-video-quality) API. Only display the correct number of incoming videos that can be rendered at a given time.

‎articles/communication-services/resources/troubleshooting/voice-video-calling/video-issues/remote-video-becomes-unavailable.md

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
---
2+
title: Video issues - The remote video becomes unavailable while subscribing the video
3+
titleSuffix: Azure Communication Services - Troubleshooting Guide
4+
description: Learn how to handle the error when the remote video becomes unavailable while subscribing the video.
5+
author: enricohuang
6+
ms.author: enricohuang
7+
8+
services: azure-communication-services
9+
ms.date: 04/05/2024
10+
ms.topic: troubleshooting
11+
ms.service: azure-communication-services
12+
ms.subservice: calling
13+
---
14+
# The remote video becomes unavailable while subscribing the video
15+
The remote video is initially available, but during the video subscription process, it becomes unavailable.
16+
17+
The SDK detects this change and throws an error.
18+
19+
This error is expected from SDK's perspective as the remote endpoint stops sending the video.
20+
## How to detect using the SDK
21+
If the video becomes unavailable before the [`createView`](/javascript/api/%40azure/communication-react/statefulcallclient?view=azure-node-latest&preserve-view=true#@azure-communication-react-statefulcallclient-createview) API finishes, the [`createView`](/javascript/api/%40azure/communication-react/statefulcallclient?view=azure-node-latest&preserve-view=true#@azure-communication-react-statefulcallclient-createview) API throws an error.
22+
23+
| error | Details |
24+
|------------------|-------------------------------------------------------|
25+
| code | 404(Not Found) |
26+
| subcode | 43202 |
27+
| message | Failed to start stream, stream became unavailable |
28+
| resultCategories | Expected |
29+
30+
## How to mitigate or resolve
31+
Your applications should catch and handle this error thrown by the SDK gracefully, so end users know the failure is because the remote participant stops sending video.

0 commit comments

Comments
 (0)