Merge pull request #270510 from enricohuang/patch-20

Add troubleshooting guide for Azure Communication Services Web Calling SDK - audio issues

Author: JamesJBarnett

articles/communication-services/resources/troubleshooting/voice-video-calling/audio-issues/delay-issue.md

@@ -0,0 +1,51 @@
+---
+title: Audio issues - The user experiences delays during the call 
+titleSuffix: Azure Communication Services - Troubleshooting Guide
+description: Learn how to troubleshoot when the user experiences delays during the call.
+author: enricohuang
+ms.author: enricohuang
+
+services: azure-communication-services
+ms.date: 04/10/2024
+ms.topic: troubleshooting
+ms.service: azure-communication-services
+ms.subservice: calling
+---
+
+# The user experiences delays during the call
+High round trip time and high jitter buffer delay are the most common causes of audio delay.
+
+There are several reasons that can cause high round trip time.
+Besides the long distance or many hops between two endpoints, one common reason is network congestion, which occurs when the network is overloaded with traffic.
+If there's congestion, network packets wait in a queue for a longer time.
+Another possible reason is a high number of packets resend at the `TCP` layer if the client uses `TCP` or `TLS` relay.
+A high resend number can occur when packets are lost or delayed in transit.
+In addition, the physical medium used to transmit data can also affect the round trip time.
+For example, Wi-Fi usually has higher network latency than Ethernet, which can lead to higher round trip times.
+
+The jitter buffer is a mechanism used by the browser to compensate for packet jitter and reordering.
+Depending on network conditions, the length of the jitter buffer delay can vary.
+The jitter buffer delay refers to the amount of time that audio samples stay in the jitter buffer.
+A high jitter buffer delay can cause audio delays that are noticeable to the user.
+
+## How to detect using the SDK
+You can use the [User Facing Diagnostics API](../../../../concepts/voice-video-calling/user-facing-diagnostics.md) to detect the network condition changes.
+
+For the network quality of the audio sending end, you can check events with the values of `networkSendQuality`.
+
+For the network quality of the receiving end, you can check events with the values of `networkReceiveQuality`.
+
+In addition, you can use the  [Media Stats API](../../../../concepts/voice-video-calling/media-quality-sdk.md) as a method to monitor and track real time the network performance from the Web client.
+
+For the quality of the audio sending end, you can check the metrics `rttInMs`.
+
+For the quality of the receiving end, you can check the metrics `jitterInMs`, `jitterBufferDelayInMs`.
+
+## How to mitigate or resolve
+From the perspective of the ACS Calling SDK, network issues are considered external problems.
+To solve network issues, it's often necessary to understand the network topology and the nodes causing the problem.
+These parts involve network infrastructure, which is outside the scope of the ACS Calling SDK.
+
+However, the browser can adaptively adjust the audio sending quality according to the network condition.
+It's important for the application to handle events from the [User Facing Diagnostics API](../../../../concepts/voice-video-calling/user-facing-diagnostics.md) or to monitor the metrics provided by the MediaStats feature.
+In this way, users can be aware of any network quality issues and aren't surprised if they experience low-quality audio during a call.

articles/communication-services/resources/troubleshooting/voice-video-calling/audio-issues/echo-issue.md

@@ -0,0 +1,37 @@
+---
+title: Audio issues - The user experiences echo during the call
+titleSuffix: Azure Communication Services - Troubleshooting Guide
+description: Learn how to troubleshoot when the user experiences echo during the call.
+author: enricohuang
+ms.author: enricohuang
+
+services: azure-communication-services
+ms.date: 04/09/2024
+ms.topic: troubleshooting
+ms.service: azure-communication-services
+ms.subservice: calling
+---
+
+# The user experiences echo during the call
+Acoustic echo happens when the microphone picks up sound from speakers, creating a loop of sound that results in an echo.
+Modern browsers have built-in acoustic echo cancellation capabilities in their audio processing modules.
+These capabilities are designed to remove near-end echoes, which can improve the overall audio quality of web based Azure Communication Service calls.
+However, the browser isn't able to remove all echoes.
+For instance, if the delay between the echo and reference signals is beyond the range of the filter, the echoes may persist.
+This problem can occur when a user joins an ACS call using a remote desktop client and plays the audio through their speakers.
+Other scenarios, such as double talk, or two devices in the same room participating in the same call can also affect the result of echo cancellation.
+
+## How to detect
+Currently, if the browser fails to remove echoes, there is no simple way to detect this issue from the information reported by the browser.
+When the user reports this issue, it's described as the user hearing their own voice or other sounds repeated back to them, creating a distracting and unpleasant audio experience. 
+
+## How to mitigate or resolve
+There are many ways to help remove the potential of an echo being picked up. The fastest solution is to have people that are producing echo to use headphones.
+The echo exists because the microphone picks up the sound from the speaker.
+Since the sound played from headphone doesn't leak, the microphone doesn't pick up the far-end signal. 
+
+Adjusting the speaker's volume level and the microphone's sensitivity level is another way that may help.
+If the volume level is low enough, it can alleviate the echo issue.
+
+Other solutions are to point an external speaker away from the microphone so that the external sound isn't picked up.
+

articles/communication-services/resources/troubleshooting/voice-video-calling/audio-issues/incoming-audio-low-volume.md

@@ -0,0 +1,43 @@
+---
+title: Audio issues - The volume of the incoming audio is low
+titleSuffix: Azure Communication Services - Troubleshooting Guide
+description: Learn how to troubleshoot when the volume of the incoming audio is low.
+author: enricohuang
+ms.author: enricohuang
+
+services: azure-communication-services
+ms.date: 04/09/2024
+ms.topic: troubleshooting
+ms.service: azure-communication-services
+ms.subservice: calling
+---
+
+# The volume of the incoming audio is low
+If users report low incoming audio volume, there could be several possible causes.
+One possibility is that the volume sent by the sender is low.
+Another possibility is that the operating system volume is set too low.
+Finally, it's possible that the speaker output volume is set too low.
+
+If you use [raw audio](../../../../quickstarts/voice-video-calling/get-started-raw-media-access.md?pivots=platform-web) API, you may also need to check the output volume of the audio element.
+
+## How to detect using the SDK
+The [Media Stats API](../../../../concepts/voice-video-calling/media-quality-sdk.md) provides a way to monitor the incoming audio volume at receiving end.
+
+To check the audio output level, you can look at `audioOutputLevel` value, which ranges from 0 to 65536.
+This value is derived from `audioLevel` in WebRTC Stats. [https://www.w3.org/TR/webrtc-stats/#dom-rtcinboundrtpstreamstats-audiolevel](https://www.w3.org/TR/webrtc-stats/#dom-rtcinboundrtpstreamstats-audiolevel)
+A low `audioOutputLevel` value indicates that the volume sent by the sender is also low.
+
+## How to mitigate or resolve
+If the `audioOutputLevel` value is low, this is likely that the volume sent by the sender is also low.
+To troubleshoot this issue, users should investigate why the audio input volume is low on the sender's side.
+This problem could be due to various factors, such as microphone settings, or hardware issues.
+
+If the `audioOutputLevel` value appears normal, the issue may be related to system volume settings or speaker issues on the receiver's side.
+Users can check their device's volume settings and speaker output to ensure that they're set to an appropriate level.
+
+### Using Web Audio GainNode to increase the volume
+It may be possible to address this issue at the application layer using Web Audio GainNode.
+By using this feature with the raw audio stream, it's possible to increase the output volume of the stream.
+
+You can also look to display a [volume level indicator](../../../../quickstarts/voice-video-calling/get-started-volume-indicator.md?pivots=platform-web) in your client user interface to let your users know what the current volume level is.
+

articles/communication-services/resources/troubleshooting/voice-video-calling/audio-issues/microphone-issue.md

@@ -0,0 +1,44 @@
+---
+title: Audio issues - The speaking participant's microphone has a problem
+titleSuffix: Azure Communication Services - Troubleshooting Guide
+description: Learn how to troubleshoot one-way audio issue when the speaking participant's microphone has a problem.
+author: enricohuang
+ms.author: enricohuang
+
+services: azure-communication-services
+ms.date: 04/09/2024
+ms.topic: troubleshooting
+ms.service: azure-communication-services
+ms.subservice: calling
+---
+
+# The speaking participant's microphone has a problem
+When the speaking's participant's microphone has a problem, it might cause the outgoing audio to be silent, resulting in one-way audio issue in the call.
+
+## How to detect using the SDK
+Your application can use [User Facing Diagnostics API](../../../../concepts/voice-video-calling/user-facing-diagnostics.md) and register a listener callback to detect the device issue.
+
+There are several events related to the microphone issues, including:
+* `noMicrophoneDevicesEnumerated`: There's no microphone device available in the system.
+* `microphoneNotFunctioning`: The browser ends the audio input track.
+* `microphoneMuteUnexpectedly`: The browser mutes the audio input track.
+
+In addition, the [Media Stats API](../../../../concepts/voice-video-calling/media-quality-sdk.md) also provides a way to monitor the audio input or output level.
+
+To check the audio level at the sending end, look at `audioInputLevel` value, which ranges from 0 to 65536 and indicates the volume level of the audio captured by the audio input device.
+
+To check the audio level at the receiving end, look at `audioOutputLevel` value, which also ranges from 0 to 65536. This value indicates the volume level of the decoded audio samples.
+If the `audioOutputLevel` value is low, it indicates that the volume sent by the sender is also low.
+
+## How to mitigate or resolve
+Microphone issues are considered external problems from the perspective of the ACS Calling SDK.
+For example, the `noMicrophoneDevicesEnumerated` event indicates that no microphone device is available in the system.
+This problem usually happens when the user removes the microphone device and there's no other microphone device in the system.
+The `microphoneNotFunctioning` event fires when the browser ends the current audio input track,
+which can happen when the operating system or driver layer terminates the audio input session.
+The `microphoneMuteUnexpectedly` event can occur when the audio input track's source is temporarily unable to provide media data.
+For example, a hardware mute button of some headset models can trigger this event.
+
+The application should listen to the [User Facing Diagnostics API](../../../../concepts/voice-video-calling/user-facing-diagnostics.md) events.
+The application should display a warning message when receiving events.
+By doing so, the user is aware of the issue and can troubleshoot by switching to a different microphone device or by unplugging and plugging in their current microphone device.

articles/communication-services/resources/troubleshooting/voice-video-calling/audio-issues/microphone-permission.md

@@ -0,0 +1,34 @@
+---
+title: Audio issues - The speaking participant doesn't grant the microphone permission
+titleSuffix: Azure Communication Services - Troubleshooting Guide
+description: Learn how to troubleshoot one-way audio issue when the speaking doesn't grant the microphone permission.
+author: enricohuang
+ms.author: enricohuang
+
+services: azure-communication-services
+ms.date: 04/09/2024
+ms.topic: troubleshooting
+ms.service: azure-communication-services
+ms.subservice: calling
+---
+
+# The speaking participant doesn't grant the microphone permission
+When the speaking participant doesn't grant microphone permission, it can result in a one-way audio issue in the call.
+This issue occurs if the user denies permission at the browser level or doesn't grant access at the operating system level.
+
+## How to detect using the SDK
+When an application requests microphone permission but the permission is denied,
+the `DeviceManager.askDevicePermission` API returns `{ audio: false }`.
+
+To detect this permission issue, the application can register a listener callback through the [User Facing Diagnostics API](../../../../concepts/voice-video-calling/user-facing-diagnostics.md).
+The listener should check for events with the value of `microphonePermissionDenied`.
+
+It's important to note that if the user revokes access permission during the call, this `microphonePermissionDenied`  event also fires.
+
+## How to mitigate or resolve
+Your application should always call the `askDevicePermission` API after the `CallClient` is initialized.
+This way gives the user a chance to grant the device permission if they didn't do so before or if the permission state is `prompt`.
+
+It's also important to listen for the `microphonePermissionDenied` event. Display a warning message if the user revokes the permission during the call. By doing so, the user is aware of the issue and can adjust their browser or system settings accordingly.
+
+

articles/communication-services/resources/troubleshooting/voice-video-calling/audio-issues/network-issue.md

@@ -0,0 +1,34 @@
+---
+title: Audio issues - There's a network issue in the call
+titleSuffix: Azure Communication Services - Troubleshooting Guide
+description: Learn how to troubleshoot one-way audio issue when there's a network issue in the call.
+author: enricohuang
+ms.author: enricohuang
+
+services: azure-communication-services
+ms.date: 04/09/2024
+ms.topic: troubleshooting
+ms.service: azure-communication-services
+ms.subservice: calling
+---
+
+# There's a network issue in the call
+When there's a network reconnection in the call on the audio sending end or receiving end, the participant can experience one-way audio issue temporarily.
+It can cause an audio issue because shortly before and during the network is reconnecting, audio packets don't flow.
+
+## How to detect using the SDK
+Through [User Facing Diagnostics API](../../../../concepts/voice-video-calling/user-facing-diagnostics.md), your application can register a listener callback to detect the network condition changes.
+
+For the network reconnection, you can check events with the values of `networkReconnect`.
+
+## How to mitigate or resolve
+From the perspective of the ACS Calling SDK, network issues are considered external problems.
+To solve network issues, it's often necessary to understand the network topology and the nodes causing the problem.
+These parts involve network infrastructure, which is outside the scope of the ACS Calling SDK.
+
+The application should listen to the `networkReconnect` event and display a warning message when receiving them,
+so that the user is aware of the issue and understands that the audio loss is due to network reconnection.
+
+However, if the network reconnection occurs at the sender's side,
+users on the receiving end are unable to know about it because currently the SDK doesn't support notifying receivers that the sender has network issues.
+

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

@@ -0,0 +1,52 @@
+---
+title: Audio issues - Overview
+titleSuffix: Azure Communication Services - Troubleshooting Guide
+description: Overview of audio issues
+author: enricohuang
+ms.author: enricohuang
+
+services: azure-communication-services
+ms.date: 04/09/2024
+ms.topic: troubleshooting
+ms.service: azure-communication-services
+ms.subservice: calling
+---
+
+# Overview of audio issues
+Audio quality is important in conference calls. If any participants on a call can’t hear each other well enough, then the participants likely leave the call.
+To establish a voice call with good quality, several factors must be considered. These factors include:
+
+- The users granted the microphone permission
+- The users microphone is working properly
+- The network conditions are good enough on sending and receiving ends
+- The audio output level is functioning properly
+
+All of these factors are important from an end-to-end perspective.
+
+Device and network issues are considered external problems from the perspective of the ACS Calling SDK.
+Your application should integrate the [User Facing Diagnostics API](../../../../concepts/voice-video-calling/user-facing-diagnostics.md)
+to monitor device and network issues and display warning messages accordingly.
+In this way, users are aware of the issue and can troubleshoot on their own.
+
+## Common issues in audio calls
+Here we list several common audio issues, along with potential causes for each issue:
+
+### The user can't hear sound during the call
+* There's a problem on the microphone of the speaking participant.
+* There's a problem on the audio output device of the user.
+* There's a network issue in the call
+
+### The user experiences poor audio quality
+* The audio sender has poor network connectivity.
+* The receiver has poor network connectivity.
+
+### The user experiences delays during the call
+* The round trip time is large between the sender and the receiver.
+* Other network issues.
+
+### The user experiences echo during the call
+* The browser's acoustic echo canceler isn't able to remove the echo on the audio sender's side.
+
+### The volume of the incoming audio is low
+* There's a low volume of outgoing audio on the sender's side.
+* There's an issue with the speaker or audio volume settings on the receiver's side