|
| 1 | +--- |
| 2 | +author: cnwankwo |
| 3 | +ms.service: azure-communication-services |
| 4 | +ms.topic: include |
| 5 | +ms.date: 07/17/2024 |
| 6 | +ms.author: cnwankwo |
| 7 | +--- |
| 8 | + |
| 9 | +[!INCLUDE [Install SDK](../install-sdk/install-sdk-web.md)] |
| 10 | + |
| 11 | + |
| 12 | + |
| 13 | +Together Mode is an extended feature of the core `Call` API. You first need to import calling Features from the Calling SDK: |
| 14 | + |
| 15 | +```js |
| 16 | +import { Features} from "@azure/communication-calling"; |
| 17 | +``` |
| 18 | + |
| 19 | +Then you can get the feature API object from the call instance: |
| 20 | + |
| 21 | +```js |
| 22 | +const togetherModeFeature = call.feature(Features.TogetherMode); |
| 23 | +``` |
| 24 | + |
| 25 | +### Receive events when Together Mode stream starts or updates |
| 26 | +You can subscribe to the event `togetherModeStreamsUpdated` to receive notifications when Together Mode starts or updates. The event contains information about rendering the added video stream. |
| 27 | + |
| 28 | +```js |
| 29 | +// event : { added: TogetherModeVideoStream[]; removed: TogetherModeVideoStream[] } |
| 30 | +togetherModeFeature.on('togetherModeStreamsUpdated', (event) => { |
| 31 | + event.added.forEach(async stream => { |
| 32 | + // stream can be rendered as a remote video stream |
| 33 | + }); |
| 34 | +}); |
| 35 | +``` |
| 36 | + |
| 37 | +### Get Together Mode stream |
| 38 | +You can access Together Mode streams through the property `togetherModeStream`. |
| 39 | + |
| 40 | +```js |
| 41 | +const togetherModeStreams = togetherModeFeature.togetherModeStream; |
| 42 | +``` |
| 43 | + |
| 44 | +| Together Mode Stream Properties | Description| |
| 45 | +|----------------------------------------------|--------| |
| 46 | +|`id` | Unique number used to identify the stream. | |
| 47 | +|`mediaStreamType` | Returns the Together Mode stream type. The value of `mediaStreamType` is always `video`. | |
| 48 | +|`isReceiving` | Returns a Boolean value indicating if video packets are received. | |
| 49 | +|`size` | Returns the Together Mode `StreamSize` with information about the width and height of the stream in pixels. | |
| 50 | + |
| 51 | +### Start Together Mode for all participants |
| 52 | +Microsoft 365 users with role organizer, co-organizer, or presenter can start Together Mode for everyone in the meeting. When Together Mode starts, all subscribers to the `togetherModeStreamsUpdated` event receive notification that enables participants to render together mode. |
| 53 | + |
| 54 | +```js |
| 55 | +togetherModeFeature.start(); |
| 56 | +``` |
| 57 | +### End Together Mode |
| 58 | +Together Mode will automatically terminate for all participants if no video stream is detected from any participant for a duration of one minute. There's no API to end Together Mode. |
| 59 | + |
| 60 | +### Get coordinates of participants in Together Mode |
| 61 | +The property `togetherModeSeatingMap` provides coordinates for individual participants in the stream. Developers can use these coordinates to overlay participant info such as display name or visual features like spotlight, hand raised, and reactions on the stream. |
| 62 | + |
| 63 | +```js |
| 64 | +// returns Map<string, TogetherModeSeatingPosition> |
| 65 | +// where the key is the participant ID |
| 66 | +// and value of type TogetherModeSeatingPosition is the position relative to the sceneSize |
| 67 | +// TogetherModeSeatingPosition { |
| 68 | +// top: number; |
| 69 | +// left: number; |
| 70 | +// width: number; |
| 71 | +// height: number; |
| 72 | +// } |
| 73 | +const seatingMap = togetherModeFeature.togetherModeSeatingMap; |
| 74 | +``` |
| 75 | + |
| 76 | +### Manage scene size |
| 77 | +The `sceneSize` property specifies the dimensions (width and height) of the HTML container that houses the `togetherMode` video stream. The seating positions of participants are calculated based on the dimensions of the scene size. If scene size isn't provided, the calculation defaults to a width of 1,280 pixels and a height of 720 pixels. |
| 78 | + |
| 79 | +```js |
| 80 | +const togetherModeContainerSize = { width: 500, height: 500 }; |
| 81 | + |
| 82 | +// To set the scene size |
| 83 | +togetherModeFeature.sceneSize = togetherModeContainerSize; |
| 84 | + |
| 85 | +// To get the scene size |
| 86 | +console.log(`Current scene has the following size: ${JSON.stringify(togetherModeFeature.sceneSize )}`) |
| 87 | +``` |
| 88 | + |
| 89 | +### Receive events when scene or seatings updates |
| 90 | +> [!NOTE] |
| 91 | +> Only Microsoft 365 users with role organizer, co-organizer and presenter can change scene or assignment of participants in Together Mode. These changes can only be made from the Teams Client. |
| 92 | +
|
| 93 | +If there's a scene change or seating, the `togetherModeSceneUpdated` or `togetherModeSeatingUpdated` events are raised respectively, providing an updated calculation of the participants’ seating positions. |
| 94 | + |
| 95 | +```js |
| 96 | +const seatUpdate = (participantSeatingMap) => { |
| 97 | + participantSeatingMap.forEach((participantID, seatingCoordinates) => { |
| 98 | + console.log(`User with ID: ${participantID} has new coordinates ${JSON.stringify(seatingCoordinates)} `) |
| 99 | + }) |
| 100 | +} |
| 101 | + |
| 102 | +togetherModeFeature.on('togetherModeSceneUpdated', seatUpdate); |
| 103 | +togetherModeFeature.on('togetherModeSeatingUpdated', seatUpdate); |
| 104 | +``` |
| 105 | + |
| 106 | +## Troubleshooting |
| 107 | +|code| Subcode | Result Category | Reason | Resolution | |
| 108 | +|----------------------------------------------|--------|--------|---------|----------| |
| 109 | +|403 | 46303 | ExpectedError | The participant’s role doesn’t have the necessary permissions to call the `togetherMode` start API. | Only Microsoft 365 users with role organizer, co-organizer and presenter can start Together Mode. You can check the role of a user via 'role' property on instance of `Call` class. | |
| 110 | +|403 | 46304 | ExpectedError | Together Mode started in an unsupported calling scenario. | Ensure Together Mode is started only in group call or meeting scenarios. | |
| 111 | +|403 | 46306 | ExpectedError | Together Mode `start` API called by an Azure Communication Services user. | Only Microsoft 365 users with role organizer, co-organizer and presenter can start together mode. | |
0 commit comments