Skip to content

Commit 0361d1b

Browse files
JamesJBarnettJamesJBarnett
authored
Merge pull request #270502 from enricohuang/patch-19
Add troubleshooting guide for Azure Communication Services Web Calling SDK - device and permission issues
2 parents c41c156 + 1f453f7 commit 0361d1b

File tree

6 files changed

+224
-1
lines changed

6 files changed

+224
-1
lines changed

‎articles/communication-services/resources/troubleshooting/voice-video-calling/device-issues/ask-device-permission-api-takes-too-long.md

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
---
2+
title: Device and permission issues - askDevicePermission API takes too long
3+
titleSuffix: Azure Communication Services - Troubleshooting Guide
4+
description: Learn how to troubleshoot when askDevicePermission API takes too long.
5+
author: enricohuang
6+
ms.author: enricohuang
7+
8+
services: azure-communication-services
9+
ms.date: 03/29/2024
10+
ms.topic: troubleshooting
11+
ms.service: azure-communication-services
12+
ms.subservice: calling
13+
---
14+
15+
# The askDevicePermission API takes too long
16+
The [`askDevicePermission`](/javascript/api/%40azure/communication-react/calladapterdevicemanagement?view=azure-node-latest&preserve-view=true#@azure-communication-react-calladapterdevicemanagement-askdevicepermission) API prompts the end user via the browser asking if they allow permission to use camera or microphone.
17+
If the end user approves camera or microphone usage, then those devices are available to be used in a call. The devices availability is reflected in available device list.
18+
19+
User taking a long time to approve the permission can cause delay in the API response.
20+
21+
Occasionally, the device list update step can take a long time.
22+
A delay in the driver layer is usually the cause of the issue. The issue can happen with some virtual audio devices in particular. [Chromium Issue 1402866](https://bugs.chromium.org/p/chromium/issues/detail?id=1402866&no_tracker_redirect=1)
23+
24+
## How to detect using the SDK
25+
To detect this issue, you can measure the time difference between when you call the [`askDevicePermission`](/javascript/api/%40azure/communication-react/calladapterdevicemanagement?view=azure-node-latest&preserve-view=true#@azure-communication-react-calladapterdevicemanagement-askdevicepermission) API and when the promise resolves or rejects.
26+
27+
## How to mitigate or resolve
28+
If the [`askDevicePermission`](/javascript/api/%40azure/communication-react/calladapterdevicemanagement?view=azure-node-latest&preserve-view=true#@azure-communication-react-calladapterdevicemanagement-askdevicepermission) API fails due to the user not responding to the UI permission prompt,
29+
the application can retry the API again and the user should see the UI permission prompt.
30+
31+
As for other reasons, such as the device list updating taking too long to complete, the user should check their devices and see if there's any device that could potentially be causing this issue.
32+
They may need to update or remove the problematic device to resolve the issue.

‎articles/communication-services/resources/troubleshooting/voice-video-calling/device-issues/no-enumerated-microphone-list.md

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
---
2+
title: Device and permission issues - getMicrophones API doesn't return detailed microphone list
3+
titleSuffix: Azure Communication Services - Troubleshooting Guide
4+
description: Learn how to troubleshoot when getMicrophones API doesn't return detailed microphone list.
5+
author: enricohuang
6+
ms.author: enricohuang
7+
8+
services: azure-communication-services
9+
ms.date: 03/29/2024
10+
ms.topic: troubleshooting
11+
ms.service: azure-communication-services
12+
ms.subservice: calling
13+
---
14+
15+
# The getMicrophones API doesn't return detailed microphone list
16+
If a user reports they can't see the detailed microphone list,
17+
it's likely because the user didn't grant permission to access the microphone.
18+
When the permission state is `prompt` or `denied`, the browser doesn't provide detailed information about the microphone devices.
19+
In this scenario, the [`DeviceManager.getMicrophones`](/javascript/api/azure-communication-services/@azure/communication-calling/devicemanager?view=azure-communication-services-js&preserve-view=true#@azure-communication-calling-devicemanager-getmicrophones) API returns an array with one object, where the `id` is set to `microphone:` and the name is set to an empty string.
20+
21+
It's important to note that this scenario differs from the scenario where a user doesn't have any microphone on their device. If a device doesn't have any microphones the [`DeviceManager.getMicrophones`](/javascript/api/azure-communication-services/@azure/communication-calling/devicemanager?view=azure-communication-services-js&preserve-view=true#@azure-communication-calling-devicemanager-getmicrophones) API returns an empty array, indicating that there's no available microphone devices on the user's system.
22+
23+
## How to detect using the SDK
24+
[`DeviceManager.getMicrophones`](/javascript/api/azure-communication-services/@azure/communication-calling/devicemanager?view=azure-communication-services-js&preserve-view=true#@azure-communication-calling-devicemanager-getmicrophones) API returns an empty array or an array with an object, where the `id` is set to `microphone:` and the name is set to an empty string.
25+
26+
Additionally, to detect the scenario where the user removes the microphone during the call and there are no available microphones in the system,
27+
the application can listen to the [`noMicrophoneDevicesEnumerated`](/javascript/api/azure-communication-services/@azure/communication-calling/latestmediadiagnostics?view=azure-communication-services-js&preserve-view=true#@azure-communication-calling-latestmediadiagnostics-nomicrophonedevicesenumerated) event being raised to true in the [User Facing Diagnostics Feature](../../../../concepts/voice-video-calling/user-facing-diagnostics.md).
28+
This event can help the application understand the current situation, so it can show a warning message on its UI accordingly.
29+
30+
## How to mitigate or resolve
31+
Your application should always call the [`DeviceManager.askDevicePermission`](/javascript/api/azure-communication-services/@azure/communication-calling/devicemanager?view=azure-communication-services-js&preserve-view=true#@azure-communication-calling-devicemanager-askdevicepermission) API to ensure that the required permissions are granted.
32+
If the user doesn't grant the microphone permission, your application should display a warning message on its user interface.
33+
34+
Additionally, your application should listen to the [`noMicrophoneDevicesEnumerated`](/javascript/api/azure-communication-services/@azure/communication-calling/latestmediadiagnostics?view=azure-communication-services-js&preserve-view=true#@azure-communication-calling-latestmediadiagnostics-nomicrophonedevicesenumerated) event and show a message when there are no available microphone devices.
35+
If the application provides a device selection page before the call,
36+
it can also check whether the microphone list is empty and shows a warning accordingly indicating no mic devices available.

‎articles/communication-services/resources/troubleshooting/voice-video-calling/device-issues/no-enumerated-speaker-list.md

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
---
2+
title: Device and permission issues - getSpeakers API doesn't return detailed speaker list
3+
titleSuffix: Azure Communication Services - Troubleshooting Guide
4+
description: Learn how to troubleshoot when getSpeakers API doesn't return detailed speaker list.
5+
author: enricohuang
6+
ms.author: enricohuang
7+
8+
services: azure-communication-services
9+
ms.date: 03/28/2024
10+
ms.topic: troubleshooting
11+
ms.service: azure-communication-services
12+
ms.subservice: calling
13+
---
14+
15+
# The getSpeakers API doesn't return detailed speaker list
16+
If a user reports that they can't see the detailed speaker list, it could be because the application doesn't have permission to access the microphone.
17+
Alternatively, the platform may not support speaker enumeration.
18+
19+
The way browsers currently work may seem counterintuitive, as the permission to access the microphone can interfere with the enumeration of speakers.
20+
The speaker and microphone enumeration shares the same permission information.
21+
22+
When the microphone permission state is `prompt` or `denied`, the browser doesn't provide detailed information about the microphone devices and speaker devices.
23+
In this scenario, [`DeviceManager.getSpeakers`](/javascript/api/azure-communication-services/@azure/communication-calling/devicemanager?view=azure-communication-services-js&preserve-view=true#@azure-communication-calling-devicemanager-getspeakers) API returns an array with one object, where the `id` is set to `speaker:` and the name is set to an empty string.
24+
25+
Some platforms, such as iOS Safari, macOS Safari, or earlier versions of Firefox don't support speaker enumeration.
26+
27+
It's important to note that this scenario is different from the scenario where a user doesn't have any audio output device.
28+
In the latter case, the [`DeviceManager.getSpeakers`](/javascript/api/azure-communication-services/@azure/communication-calling/devicemanager?view=azure-communication-services-js&preserve-view=true#@azure-communication-calling-devicemanager-getspeakers) API only returns an empty array, indicating that there's no available audio output device in the user's system.
29+
30+
## How to detect using the SDK
31+
[`DeviceManager.getSpeakers`](/javascript/api/azure-communication-services/@azure/communication-calling/devicemanager?view=azure-communication-services-js&preserve-view=true#@azure-communication-calling-devicemanager-getspeakers) API returns an empty array or an array with an object, where the `id` is set to `speaker:` and the name is set to an empty string.
32+
33+
Additionally, to detect the scenario where the user removes the speaker during the call and there are no available audio output devices in the system, the application can listen to the `noSpeakerDevicesEnumerated` event being raised to true in the [User Facing Diagnostics Feature](../../../../concepts/voice-video-calling/user-facing-diagnostics.md). This event can help the application understand the current situation, and show the warning message on its UI accordingly.
34+
35+
For the platform that doesn't support speaker enumeration, you get an error when calling [`DeviceManager.getSpeakers`](/javascript/api/azure-communication-services/@azure/communication-calling/devicemanager?view=azure-communication-services-js&preserve-view=true#@azure-communication-calling-devicemanager-getspeakers) API.
36+
37+
The error code/subcode is
38+
39+
| error | Details |
40+
|------------------|-------------------------------------------------------|
41+
| code | 405 (Method Not Allowed) |
42+
| subcode | 40606 |
43+
| message | This device doesn't support speaker enumeration. |
44+
| resultCategories | Expected |
45+
46+
## How to mitigate or resolve
47+
The application should always call the `DeviceManager.askDevicePermission` API to ensure that the required permissions are granted.
48+
If the user doesn't grant the microphone permission, the application should show a warning on its user interface, so the user knows that they aren't able to see the speaker device list.
49+
50+
The application should also check whether the speaker list is empty or handle the error when calling [`DeviceManager.getSpeakers`](/javascript/api/azure-communication-services/@azure/communication-calling/devicemanager?view=azure-communication-services-js&preserve-view=true#@azure-communication-calling-devicemanager-getspeakers) API, and show a warning accordingly.
51+
Additionally, the application should listen to the `noSpeakerDevicesEnumerated` event and show a message when there are no available speaker devices.

‎articles/communication-services/resources/troubleshooting/voice-video-calling/device-issues/no-permission-prompt.md

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
---
2+
title: Device and permission issues - no permission prompt after calling askDevicePermission
3+
titleSuffix: Azure Communication Services - Troubleshooting Guide
4+
description: Learn why there's no permission prompt after calling askDevicePermission.
5+
author: enricohuang
6+
ms.author: enricohuang
7+
8+
services: azure-communication-services
9+
ms.date: 03/29/2024
10+
ms.topic: troubleshooting
11+
ms.service: azure-communication-services
12+
ms.subservice: calling
13+
---
14+
15+
# No permission prompt shows when calling askDevicePermission
16+
If a user reports that they don't see any permission prompts, it may be because they previously granted or denied permission and the browser caches the result.
17+
18+
Not showing the permission prompt isn't a problem if the browser has the required permission.
19+
However, if the user can't see the device list, it could be because they denied permission before.
20+
21+
Another possible reason for the lack of a permission prompt is that the user's system doesn't have any microphone or camera devices available,
22+
causing the browser to skip the prompt even if the permission state is set to `prompt`.
23+
24+
## How to detect using the SDK
25+
We can't detect whether the permission prompt actually shows or not, as this browser behavior can't be detected at JavaScript layer.
26+
27+
## How to mitigate or resolve
28+
The application should check the result of [`DeviceManager.askDevicePermission`](/javascript/api/%40azure/communication-react/calladapterdevicemanagement?view=azure-node-latest&preserve-view=true#@azure-communication-react-calladapterdevicemanagement-askdevicepermission) API.
29+
If the result is false, it may indicate that user denied the permission now or previously.
30+
31+
The application should show a warning message and ask the user to check their browser settings to ensure that correct permissions were granted.
32+
They also need to verify that their system has the necessary devices installed and configured properly.

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

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
---
2+
title: Device and permission issues - Overview
3+
titleSuffix: Azure Communication Services - Troubleshooting Guide
4+
description: Overview of device and permission issues
5+
author: enricohuang
6+
ms.author: enricohuang
7+
8+
services: azure-communication-services
9+
ms.date: 03/29/2024
10+
ms.topic: troubleshooting
11+
ms.service: azure-communication-services
12+
ms.subservice: calling
13+
---
14+
15+
# Overview of device and permission issues
16+
In the WebJS calling SDK, there are two types of permissions: browser permissions and system permissions.
17+
When an application needs to access a user's audio or video input device, it requires permissions granted at both the browser and system level.
18+
19+
If an application doesn't have the required permission, it can't access the device,
20+
which means that other participants in the call are unable to see or hear the user.
21+
22+
To avoid these issues, it's important for users to grant the necessary permissions when prompted by the browser.
23+
If a user accidentally denies permission or needs to change their permissions later, they can usually do so through the browser settings.
24+
25+
The permission is also necessary for the application to retrieve detailed device list information.
26+
The application can call [`DeviceManager.askDevicePermission`](/javascript/api/%40azure/communication-react/calladapterdevicemanagement?view=azure-node-latest&preserve-view=true#@azure-communication-react-calladapterdevicemanagement-askdevicepermission) to trigger the permission prompt UI.
27+
However, the browser may cache the permission result and return it without showing the permission prompt UI.
28+
If the permission result is `denied`, the user needs to update the permission through the browser settings.
29+
30+
## Common issues related to the device and permission
31+
Here are some common issues related to devices and permissions, along with their potential causes:
32+
33+
### The getMicrophones API returns an empty array or doesn't return detailed microphone list
34+
* The microphone device isn't available in the system.
35+
* The microphone permission isn't granted.
36+
37+
### The getSpeakers API returns an empty array or doesn't return detailed speaker list
38+
* The speaker device isn't available in the system.
39+
* The browser doesn't support speaker enumeration.
40+
* The microphone permission isn't granted.
41+
42+
### No permission prompt shows when calling askDevicePermission
43+
* The browser caches the permission result granted or denied previously and returns it without prompting the user.
44+
* The microphone device isn't available when requesting microphone permission.
45+
* The camera device isn't available when requesting camera permission.
46+
47+
### The askDevicePermission API takes too long
48+
* The user doesn't grant or deny the permission prompt.
49+
* The device driver layer responds slowly.
50+
51+
## Next steps
52+
53+
This overview article provides basic information on device and permission issues you may encounter when using the WebJS calling SDK.
54+
For more detailed guidance, follow the links to the pages listed within the `Device and permission issues` section of this troubleshooting guide.

‎articles/communication-services/toc.yml

Lines changed: 19 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1023,12 +1023,30 @@ items:
10231023
href: concepts/advanced-messaging/whatsapp/template-messages.md
10241024
- name: Azure Advisor
10251025
href: concepts/advisor-overview.md
1026-
- name: Resources
1026+
- name: Resources
10271027
items:
10281028
- name: Release notes
10291029
href: https://github.com/Azure/Communication/blob/master/releasenotes
10301030
- name: Learn modules
10311031
href: resources/learn-modules.md
1032+
- name: Troubleshooting Guides
1033+
items:
1034+
- name: Voice and Video
1035+
items:
1036+
- name: Calling (JavaScript)
1037+
items:
1038+
- name: Device and permission issues
1039+
items:
1040+
- name: Overview
1041+
href: resources/troubleshooting/voice-video-calling/device-issues/overview.md
1042+
- name: The getMicrophones API doesn't return detailed microphone list
1043+
href: resources/troubleshooting/voice-video-calling/device-issues/no-enumerated-microphone-list.md
1044+
- name: The getSpeakers API doesn't return detailed speaker list
1045+
href: resources/troubleshooting/voice-video-calling/device-issues/no-enumerated-speaker-list.md
1046+
- name: No permission prompt shows when calling askDevicePermission
1047+
href: resources/troubleshooting/voice-video-calling/device-issues/no-permission-prompt.md
1048+
- name: The askDevicePermission API takes too long
1049+
href: resources/troubleshooting/voice-video-calling/device-issues/ask-device-permission-api-takes-too-long.md
10321050
- name: References
10331051
items:
10341052
- name: Reference documentation overview

0 commit comments

Comments
 (0)