Merge pull request #276137 from enricohuang/patch-27

Update ACS Web Calling troubleshooting guide

Author: Jill Grant

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

@@ -28,16 +28,35 @@ This value is derived from `audioLevel` in WebRTC Stats. [https://www.w3.org/TR/
 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.
+If the `audioOutputLevel` value is low, it's 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.
+The value of `audioOutputLevel` ranges from 0 - 65536. In practice, values lower than 60 can be considered quiet, and values lower than 150 are often considered low volume.
+
 Users can check their device's volume settings and speaker output to ensure that they're set to an appropriate level.
+If the `audioOutputLevel` value appears normal, the issue may be related to system volume settings or speaker issues on the receiver's side.
+
+For example, if the user uses Windows, they should check the volume mixer settings and apps volume settings.
+
+:::image type="content" source="./media/apps-volume-mixer.png" alt-text="Screenshot of volume mixer.":::
 
 ### 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.
 
+## References
+### Troubleshooting process
+Below is a flow diagram of the troubleshooting process for this issue.
+
+:::image type="content" source="./media/low-volume-troubleshooting.svg" alt-text="Diagram of troubleshooting the low volume issue.":::
+
+1. When a user reports experiencing low audio volume, the first thing to check is whether the volume of the incoming audio is low. The application can obtain this information by checking `audioOutputLevel` in the media stats.
+2. If the `audioOutputLevel` value is constantly low, it indicates that the volume of audio sent by the speaking participant is low. In this case, ask the user to verify if the speaking participant has issues with their microphone device or input volume settings.
+3. If the `audioOutputLevel` value isn't always low, the user may still experience low audio volume issue due to system volume settings. Ask the user to check their system volume settings. 
+4. If the user's system volume is set to a low value, the user should increase the volume in the settings.
+5. In some systems that support app-specific volume settings, the audio volume output from the app may be low even if system volume isn't low. In this case, the user should check their volume setting of the app within the system.
+6. If the volume setting of the app in the system is low, the user should increase it.
+7. If you still can't determine why the audio output volume is low, ask the user to check their speaker device or select another audio output device. The issue may be due to a device problem and not related to the software or operating system. Not all platforms support speaker enumeration in the browser. For example, you can't select an audio output device through the JavaScript API in the Safari browser or in Chrome on Android. In these cases, you should configure the audio output device in the system settings.

articles/communication-services/resources/troubleshooting/voice-video-calling/audio-issues/media/apps-volume-mixer.png

@@ -42,3 +42,25 @@ For example, a hardware mute button of some headset models can trigger this even
 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.
+
+## References
+### Troubleshooting process
+If a user can't hear sound during a call, one possibility is that the speaking participant has an issue with their microphone.
+If the speaking participant is using your application, you can follow this flow diagram to troubleshoot the issue.
+
+:::image type="content" source="./media/microphone-issue-troubleshooting.svg" alt-text="Diagram of troubleshooting the microphone issue.":::
+
+1. First, check if a microphone is available. The application can obtain this information by invoking `DeviceManager.getMicrophone` API or by detecting a `noMicrophoneDevicesEnumerated` UFD Bad event.
+2. If no microphone device is available, prompt the user to plug in a microphone.
+3. If a microphone is available but there's no outgoing audio, consider other possibilities such as permission issues, device issues, or network problems.
+4. If permission is denied, refer to [The speaking participant doesn't grant the microphone permission](./microphone-permission.md) for more information.
+5. If permission is granted, consider whether the issue is due to an external problem, such as `microphoneMuteUnexpectedly` UFD.
+6. The `microphoneMuteUnexpectedly` UFD Bad event is triggered when the browser mutes the audio input track. The application can monitor this UFD but isn't able to detect the reason at JavaScript layer. You can still provide instructions in the app and ask if the user is using hardware mute button on their headset.
+7. If the user releases the hardware mute and the `microphoneMuteUnexpectedly` UFD recovers, the issue is resolved.
+8. If the user isn't using the hardware mute, ask the user to unplug and replug the microphone, or to select another microphone. Ensure the user hasn't muted the microphone at the system level.
+9. No outgoing audio issue can also happen when there's a `microphoneNotFunctioning` UFD Bad event.
+10. If there's no `microphoneNotFunctioning` UFD Bad event, consider other possibilities, such as network issues.
+11. If there's a `networkReconnect` Bad UFD, outgoing audio may be temporarily lost due to a network disconnection. Refer to [There's a network issue in the call](./network-issue.md) for detailed information.
+12. If there are no microphone-related events and no network-related events, create a support ticket for ACS team to investigate the issue. Refer to [Reporting an issue](../general-troubleshooting-strategies/report-issue.md).
+13. If a `microphoneNotFunctioning` UFD Bad event occurs, and the user has no outgoing audio, they can try to recover the stream by using ACS [mute](/javascript/api/azure-communication-services/@azure/communication-calling/call?view=azure-communication-services-js&preserve-view=true#@azure-communication-calling-call-mute) and [unmute](/javascript/api/azure-communication-services/@azure/communication-calling/call?view=azure-communication-services-js&preserve-view=true#@azure-communication-calling-call-unmute).
+14. If the `microphoneNotFunctioning` UFD doesn't recover after the user performs ACS mute and unmute, there might be an issue with the microphone device. Ask the user to unplug and replug the microphone or select another microphone.

articles/communication-services/resources/troubleshooting/voice-video-calling/audio-issues/media/low-volume-troubleshooting.svg

@@ -26,9 +26,23 @@ The listener should check for events with the value of `microphonePermissionDeni
 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.
+Your application should always call the [askDevicePermission](/javascript/api/azure-communication-services/@azure/communication-calling/devicemanager?view=azure-communication-services-js&preserve-view=true#@azure-communication-calling-devicemanager-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`.
+The application can also show a warning message if the user denies the permission, so the user can fix it before joining a call.
 
-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.
+It's also important to listen for the [microphonePermissionDenied](../references/ufd/microphone-permission-denied.md) UFD 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.
 
+## References
+### Troubleshooting process
+If a user can't hear sound during a call, one possibility is that the speaking participant hasn't granted microphone permission.
+If the speaking participant is using your application, you can follow this flow diagram to troubleshoot the issue.
 
+:::image type="content" source="./media/permission-issue-troubleshooting.svg" alt-text="Diagram of troubleshooting the permission issue.":::
+
+1. Check if there's a `microphonePermissionDenied` Bad UFD event for the speaking participant. This usually indicates that the user has denied the permission or that the permission isn't requested.
+2. If a `microphonePermissionDenied` Bad UFD event occurs, verify whether the app has called `askDevicePermission` API.
+3. The app must call `askDevicePermission` if this API hasn't been invoked before the user joins the call. The app can offer a smoother user experience by determining the current state of permissions. For instance, it can display a message instructing the user to adjust their permissions if necessary.
+4. If the app has called `askDevicePermission` API, but the user still gets a `microphonePermissionDenied` Bad UFD event. The user has to reset or grant the microphone permission in the browser. If they have confirmed that the permission is granted in the browser, they should check if the OS is blocking mic access to the browser.
+5. If there's no `microphonePermissionDenied` Bad UFD, we need to consider other possibilities. For the speaking participant, there might be other potential reasons for issues with outgoing audio, such as network reconnection, or device issues.
+6. If there's a `networkReconnect` Bad UFD, the outgoing audio may be temporarily lost due to a network disconnection. See [There's a network issue in the call](./network-issue.md) for detailed information.
+7. If no `networkReconnect` Bad UFD occurs, there might be a problem on the speaking participant's microphone. See [The speaking participant's microphone has a problem](./microphone-issue.md) for detailed information.