|
| 1 | +--- |
| 2 | +author: fuyan |
| 3 | +ms.service: azure-communication-services |
| 4 | +ms.topic: include |
| 5 | +ms.date: 10/24/2024 |
| 6 | +ms.author: fuyan |
| 7 | +--- |
| 8 | +[!INCLUDE [Install SDK](../install-sdk/install-sdk-web.md)] |
| 9 | + |
| 10 | +## Implement media access |
| 11 | + |
| 12 | +`MediaAccess` is a `feature` of the class `Call`. You first need to import package `Features` from the Calling SDK: |
| 13 | + |
| 14 | +```js |
| 15 | +import { Features} from "@azure/communication-calling"; |
| 16 | +``` |
| 17 | + |
| 18 | +Then you can get the instance of `MediaAccess` API from the `call` instance: |
| 19 | + |
| 20 | +```js |
| 21 | +const mediaAccessFeature = call.feature(Features.MediaAccess); |
| 22 | +``` |
| 23 | + |
| 24 | +### Control access to send audio or video of individual attendees |
| 25 | + |
| 26 | +Use the `permitAudio()` method to enable selected attendees to unmute. Use the `permitVideo()` method to enable selected attendees to turn on video. These actions don't automatically unmute or turn on video. They only enable attendees to perform these actions. |
| 27 | + |
| 28 | +Use the `forbidAudio()` method to enable organizers to mute selected attendees and deny them the ability to unmute. Use the `forbidVideo()` method to enable organizers to turn off video for selected attendees and deny them the ability to turn on video. |
| 29 | + |
| 30 | +```js |
| 31 | +// Define list of attendees |
| 32 | +const acsUser = new CommunicationUserIdentifier('<USER_ID>'); |
| 33 | +const teamsUser = new MicrosoftTeamsUserIdentifier('<USER_ID>'); |
| 34 | +const participants = [acsUser, teamsUser]; |
| 35 | + |
| 36 | +// Allow selected attendees to unmute |
| 37 | +mediaAccessFeature.permitAudio(participants); |
| 38 | + |
| 39 | +// Deny selected attendees to unmute |
| 40 | +mediaAccessFeature.forbidAudio(participants); |
| 41 | + |
| 42 | +// Allow selected attendees to turn on video |
| 43 | +mediaAccessFeature.permitVideo(participants); |
| 44 | + |
| 45 | +// Deny selected attendees to turn on video |
| 46 | +mediaAccessFeature.forbidVideo(participants); |
| 47 | +``` |
| 48 | + |
| 49 | +### List media access state for all remote participants |
| 50 | + |
| 51 | +Use the `getAllOthersMediaAccess` API to get information about all remote participant media access states for current call. |
| 52 | +An example of how to use the `getAllOthersMediaAccess` API: |
| 53 | +```js |
| 54 | +let remoteParticipantsMediaAccess = mediaAccessHandFeature.getAllOthersMediaAccess() |
| 55 | + |
| 56 | +remoteParticipantsMediaAccess.forEach((mediaAccess) => { |
| 57 | + console.log(`Identifier: ${mediaAccess.participant } can unmute: ${mediaAccess.isAudioPermitted } and can turn on video: ${mediaAccess.isVideoPermitted }`); |
| 58 | +}) |
| 59 | +``` |
| 60 | + |
| 61 | +### Get notification that media access changed |
| 62 | + |
| 63 | +Subscribe to the `mediaAccessChanged` events from `MediaAccess` API to receive array of `MediaAccess` instances. Use the array to see the media access state for all remote participants if they're currently enabled or denied the ability to send audio or video. By default, all participants other than the attendee role can send audio and video. The `mediaAccessChanged` events are triggered when a participant with an appropriate role changes media access for selected attendees or all attendees. |
| 64 | + |
| 65 | +```js |
| 66 | +const mediaAccessChangedHandler = (event) => { |
| 67 | + console.log(`Attendees that changed media access states:`); |
| 68 | + event.mediaAccesses.forEach( (mediaAccess) => { |
| 69 | + console.log(`Identifier: ${mediaAccess.participant } can unmute: ${mediaAccess.isAudioPermitted } and can turn on video: ${mediaAccess.isVideoPermitted }`); |
| 70 | + } |
| 71 | +} |
| 72 | +mediaAccessFeature.on('mediaAccessChanged', mediaAccessChangedHandler ) |
| 73 | +``` |
| 74 | +
|
| 75 | +### Stop receiving media access events |
| 76 | +Use the following code to stop receiving media access events. |
| 77 | +```js |
| 78 | +mediaAccessFeature.off('mediaAccessChanged', mediaAccessChangedHandler) |
| 79 | +``` |
| 80 | +
|
| 81 | +### Media Access properties |
| 82 | +Class `MediaAccess` has the following properties: |
| 83 | +
|
| 84 | +| Properties | Description | |
| 85 | +|--|--| |
| 86 | +| participant | Identifier of the participant whose media access changed. | |
| 87 | +| isAudioPermitted | Boolean value indicating whether ability to send audio is allowed for this participant. | |
| 88 | +| isVideoPermitted | Boolean value indicating whether ability to send video is allowed for this participant. | |
| 89 | +
|
| 90 | +### Control access to send audio or video for all attendees |
| 91 | +Microsoft Teams meetings support APIs that enable organizers, co-organizers, and presenters to change the meeting options **Allow mic for attendees** or **Allow camera for attendees**. You can use those APIs to change the value of the meeting options, which enable organizers to enable or denying all attendees sending audio or video. |
| 92 | +
|
| 93 | +You can use the `permitOthersAudio()` method to set meeting option **Allow mic for attendees** to `true` and enable all attendees to unmute. You can also use the `permitOthersVideo()` method to set meeting option **Allow camera for attendees** to `true` and enable all attendees to turn on video. These actions don't automatically unmute or turn on video. They only enable attendees to perform these actions. |
| 94 | +
|
| 95 | +Use the `forbidOthersAudio()` method to set meeting option **Allow mic for attendees** to `false`, which organizers can use to mute all attendees and deny them the ability to unmute. You can also use the `forbidOthersVideo()` method to set meeting option **Allow mic for attendees** to `false`, which organizers can use to turn of video for all attendees and deny them the ability to turn on video. |
| 96 | +
|
| 97 | +Participants with appropriate roles can override methods `permitOthersAudio` ,`permitOthersVideo`, `forbidOthersAudio` ,`forbidOthersVideo` with methods `forbidAudio` and `forbidVideo` or `permitAudio` and `permitVideo`. Change of media access for all attendees triggers `mediaAccessChanged` event for all participants that are impacted. |
| 98 | +
|
| 99 | +```js |
| 100 | +// Allow all attendees to unmute |
| 101 | +mediaAccessFeature.permitOthersAudio(); |
| 102 | + |
| 103 | +// Deny all attendees to unmute |
| 104 | +mediaAccessFeature.forbidOthersAudio(); |
| 105 | + |
| 106 | +// Allow all attendees to turn on video |
| 107 | +mediaAccessFeature.permitOthersVideo(); |
| 108 | + |
| 109 | +// Deny all attendees to turn on video |
| 110 | +mediaAccessFeature.forbidOthersVideo(); |
| 111 | +``` |
| 112 | +
|
| 113 | +### Get Teams meeting media access setting |
| 114 | +You can use the `getMeetingMediaAccess` API to get values of `Allow mic for attendees` or `Allow camera for attendees` Teams meeting options. The fact that meeting options are set to `true` or `false` don't guarantee that all attendees have permitted or forbid audio or video, because those calls can be overridden with methods `forbidAudio`, `forbidVideo`, `permitAudio` and `permitVideo`. |
| 115 | +Here's an example of how to use the `getMeetingMediaAccess` API: |
| 116 | +```js |
| 117 | +let meetingMediaAccess = mediaAccessHandFeature.getMeetingMediaAccess() |
| 118 | +console.log(`Teams meeting settings - Allow mic for attendees: ${meetingMediaAccess.isAudioPermitted}, Allow camera for attendees: ${meetingMediaAccess.isVideoPermitted}`); |
| 119 | +``` |
| 120 | +
|
| 121 | +### Get notification that meeting media access changed |
| 122 | +You can subscribe to the `meetingMediaAccessChanged` events from `MediaAccess` API to receive a `MeetingMediaAccess` instance when Teams meeting options `Allow mic for attendees` or `Allow camera for attendees` are changed. |
| 123 | +```js |
| 124 | +const meetingMediaAccessChangedHandler = (event) => { |
| 125 | + console.log(`Teams meeting settings - Allow mic for attendees: ${event.meetingMediaAccess.isAudioPermitted}, Allow camera for attendees: ${event.meetingMediaAccess.isVideoPermitted}`); |
| 126 | +} |
| 127 | +mediaAccessFeature.on('meetingMediaAccessChanged', meetingMediaAccessChangedHandler ) |
| 128 | +``` |
| 129 | +
|
| 130 | +### Stop receiving meeting media access events |
| 131 | +Use the following code to stop receiving meeting media access events. |
| 132 | +```js |
| 133 | +mediaAccessFeature.off('meetingMediaAccessChanged', meetingMediaAccessChangedHandler) |
| 134 | +``` |
| 135 | +
|
| 136 | +### Meeting media access properties |
| 137 | +Class `MeetingMediaAccess` has the following properties: |
| 138 | +
|
| 139 | +| Properties | Description | |
| 140 | +|--|--| |
| 141 | +| isAudioPermitted | Boolean value of Teams meeting option `Allow mic for attendees`. | |
| 142 | +| isVideoPermitted | Boolean value of Teams meeting option `Allow camera for attendees`. | |
| 143 | +
|
| 144 | +### Troubleshooting |
| 145 | +
|
| 146 | +|Error code| Subcode | Result Category | Reason | Resolution | |
| 147 | +|----------------------------------------------|--------|--------|---------|----------| |
| 148 | +|500 | 46500 | UnexpectedServerError | Internal error while updating the audio or video access. | Gather browser console logs and contact Azure Communication Services support. | |
| 149 | +|500 | 46501 | UnexpectedClientError | Couldn't initialize media access feature. | Gather browser console logs and contact Azure Communication Services support. | |
| 150 | +|403 | 46502 | ExpectedError | Change media access failed. User doesn't have an organizer, coorganizer, or presenter role. | Ensure that the user has one of mentioned roles and try again. If the issue persists, gather browser console logs and contact Azure Communication Services support. | |
| 151 | +|403| 46503 | UnexpectedServerError |Change media access failed. Change media access can only be done in meeting or group call scenarios. | Ensure that the feature is initialized only for Teams meeting or group call scenarios. You can check `Capability` feature to learn about the availability of the feature. If the issue persists, gather browser console logs and contact Azure Communication Services support. | |
| 152 | +|403 | 46504| ExpectedError | Change media access failed. Only able to change media access for attendees. | Ensure that the method is called only for participants with role attendees. You can check the property `role` of class `remoteParticipant` to understand the role of the participant.| |
| 153 | +|412 | 46505| ExpectedError | Failed to change media access. | Use media access APIs only when your instance of `Call` has property `state` set to `connected`. | |
| 154 | +|412| 46506 | UnexpectedClientError | Media access change failed as meeting capabilities are empty. | Gather browser console logs and contact Azure Communication Services support. | |
| 155 | +|412| 46507 | ExpectedError | Azure Communication Services currently disabled this feature. | Try the APIs in a couple of days. | |
| 156 | +
|
| 157 | +## SDK compatibility |
| 158 | +
|
| 159 | +The following table shows the minimum version of SDKs that support individual APIs. |
| 160 | +
|
| 161 | +| Operations | Web | Web UI | iOS | iOS UI | Android | Android UI | Windows | |
| 162 | +|-------------|-----|--------|-----|--------|---------|------------|---------| |
| 163 | +|Permit audio |1.31.2,<br>1.32.1-beta.1|❌|❌|❌|❌|❌|❌| |
| 164 | +|Forbid audio |1.31.2,<br>1.32.1-beta.1|❌|❌|❌|❌|❌|❌| |
| 165 | +|Permit others audio|1.31.2,<br>1.32.1-beta.1|❌|❌|❌|❌|❌|❌| |
| 166 | +|Forbid others audio|1.31.2,<br>1.32.1-beta.1|❌|❌|❌|❌|❌|❌| |
| 167 | +|Permit video |1.31.2,<br>1.32.1-beta.1|❌|❌|❌|❌|❌|❌| |
| 168 | +|Forbid video |1.31.2,<br>1.32.1-beta.1|❌|❌|❌|❌|❌|❌| |
| 169 | +|Permit others video|1.31.2,<br>1.32.1-beta.1|❌|❌|❌|❌|❌|❌| |
| 170 | +|Forbid others video|1.31.2,<br>1.32.1-beta.1|❌|❌|❌|❌|❌|❌| |
| 171 | +
|
0 commit comments