在一起模式
本文內容
支援
安裝 SDK
初始化必要的物件
實作在一起模式
疑難排解
下一步
顯示其他 2 個
本文說明如何使用 Azure 通訊服務 通話 SDK 來實作 Microsoft Teams 共同模式。 一起模式可增強虛擬會議和通話,讓他們感覺更個人化。 藉由建立統一的檢視,讓所有人置於共用背景,參與者就可以順暢地連線並有效地共同作業。
下表定義在 Azure 通訊服務 中共同模式的支援。
下表顯示呼叫和身分識別類型的支援。
展開資料表
身分識別
Teams 會議
會議室
1:1 通話
群組通話
一對一 Teams Interop 通話
群組 Teams Interop 通話
通訊服務使用者
✔️
✔️
✔️
Microsoft 365 使用者
✔️
✔️
✔️
下表顯示呼叫SDK中個別 API 對個別身分識別類型的支援。
展開資料表
Operations
通訊服務使用者
Microsoft 365 使用者
啟動一起模式數據流
✔️ [1]
結合模式串流
✔️
✔️
取得場景大小
✔️
✔️
取得座位地圖
✔️
✔️
變更場景
變更座位指派
[1] 只有具有召集人、共同召集人或演示者角色的Microsoft 365 使用者才能呼叫 [一起啟動模式]。
下表顯示個別 Azure 通訊服務 SDK 中「共同模式」功能的支援。
展開資料表
平台
Web
Web UI
iOS
iOS UI
Android
Android UI
Windows
受到支援
✔️
使用 npm install
命令,安裝適用於 JavaScript 的 Azure 通訊服務通用和通話 SDK:
npm install @azure/communication-common --save
npm install @azure/communication-calling --save
大部分通話作業都需要 CallClient
執行個體。 當您建立新的 CallClient
執行個體時,您可以使用自訂選項加以設定,如同 Logger
執行個體一樣。
使用 CallClient
執行個體,您可以藉由呼叫 createCallAgent
來建立 CallAgent
執行個體。 此方法會以非同步的方式傳回 CallAgent
執行個體物件。
createCallAgent
方法會使用 CommunicationTokenCredential
作為引數。 其接受使用者存取權杖 。
您可以使用 CallClient
執行個體上的 getDeviceManager
方法來存取 deviceManager
。
const { CallClient } = require('@azure/communication-calling');
const { AzureCommunicationTokenCredential} = require('@azure/communication-common');
const { AzureLogger, setLogLevel } = require("@azure/logger");
// Set the logger's log level
setLogLevel('verbose');
// Redirect log output to console, file, buffer, REST API, or whatever location you want
AzureLogger.log = (...args) => {
console.log(...args); // Redirect log output to console
};
const userToken = '<USER_TOKEN>';
callClient = new CallClient(options);
const tokenCredential = new AzureCommunicationTokenCredential(userToken);
const callAgent = await callClient.createCallAgent(tokenCredential, {displayName: 'optional Azure Communication Services user name'});
const deviceManager = await callClient.getDeviceManager()
如何最好地管理與 Microsoft 基礎結構的 SDK 連線
Call Agent
執行個體可協助您管理通話 (加入或啟動通話)。 若要運作,您的通話 SDK 必須連線到 Microsoft 基礎結構以取得來電通知,並協調其他通話詳細資料。 您的 Call Agent
有兩種可能的狀態:
已連線 - Connected
的 Call Agent
connectionStatue 值表示用戶端 SDK 已連線且能夠接收來自 Microsoft 基礎結構的通知。
已中斷連線 - Disconnected
狀態的 Call Agent
connectionStatue 值指出有問題導致 SDK 無法正確連線。
Call Agent
應該重新建立。
invalidToken
:如果權杖已過期或無效,Call Agent
執行個體會中斷連線,並出現此錯誤。
connectionIssue
:如果用戶端連線到 Microsoft 基礎結構時發生問題,在多次重試之後,Call Agent
會公開 connectionIssue
錯誤。
您可以藉由檢查 connectionState
屬性的目前值,檢查本機 Call Agent
是否已連線到 Microsoft 基礎結構。 在作用中通話期間,您可以接聽 connectionStateChanged
事件,以判斷 Call Agent
是否從已連線 變更為已中斷連線 狀態。
const connectionState = callAgentInstance.connectionState;
console.log(connectionState); // it may return either of 'Connected' | 'Disconnected'
const connectionStateCallback = (args) => {
console.log(args); // it will return an object with oldState and newState, each of having a value of either of 'Connected' | 'Disconnected'
// it will also return reason, either of 'invalidToken' | 'connectionIssue'
}
callAgentInstance.on('connectionStateChanged', connectionStateCallback);
「一起模式」是核心 Call
API 的擴充功能。 您必須先從呼叫 SDK 匯入呼叫功能:
import { Features} from "@azure/communication-calling";
然後,您可以從呼叫實例取得共同模式 API 物件:
const togetherModeFeature = call.feature(Features.TogetherMode);
您可以訂閱事件 togetherModeStreamsUpdated
,以在 [一起模式] 啟動或更新時接收通知。 事件包含轉譯已新增視訊串流的相關信息。
// event : { added: TogetherModeVideoStream[]; removed: TogetherModeVideoStream[] }
togetherModeFeature.on('togetherModeStreamsUpdated', (event) => {
event.added.forEach(async stream => {
// stream can be rendered as a remote video stream
});
});
您可以透過 屬性 togetherModeStream
來存取 [一起模式] 資料流。
const togetherModeStreams = togetherModeFeature.togetherModeStream;
展開資料表
一起模式數據流屬性
描述
id
用來識別數據流的唯一數位。
mediaStreamType
傳回 [一起模式] 數據流類型。 的值 mediaStreamType
一律 video
為 。
isReceiving
傳回布爾值,指出是否收到視訊封包。
size
傳回 [一起模式 StreamSize
],其中包含以像素為單位之數據流寬度和高度的相關信息。
Microsoft 365 位具有角色召集人、共同召集人或演示者的用戶可以在會議中為每個人啟動共同模式。 當 [一起模式] 啟動時,事件接收通知的所有訂閱者 togetherModeStreamsUpdated
都會讓參與者轉譯在一起模式。
togetherModeFeature.start();
如果任何參與者在一分鐘內未偵測到任何參與者的視訊串流,[一起模式] 會自動終止。 沒有 API 可結束在一起模式。
屬性 togetherModeSeatingMap
會為數據流中的個別參與者提供座標。 開發人員可以使用這些座標來重迭參與者資訊,例如顯示名稱或視覺功能,例如焦點、手舉和串流上的反應。
// returns Map<string, TogetherModeSeatingPosition>
// where the key is the participant ID
// and value of type TogetherModeSeatingPosition is the position relative to the sceneSize
// TogetherModeSeatingPosition {
// top: number;
// left: number;
// width: number;
// height: number;
// }
const seatingMap = togetherModeFeature.togetherModeSeatingMap;
屬性 sceneSize
會指定裝載 togetherMode
視訊串流之 HTML 容器的維度(寬度和高度)。 參與者的座位位置是根據場景大小的維度來計算。 如果未提供場景大小,計算預設為寬度為 1,280 像素,高度為 720 圖元。
const togetherModeContainerSize = { width: 500, height: 500 };
// To set the scene size
togetherModeFeature.sceneSize = togetherModeContainerSize;
// To get the scene size
console.log(`Current scene has the following size: ${JSON.stringify(togetherModeFeature.sceneSize )}`)
注意
只有Microsoft 365 位具有角色召集人、共同召集人或演示者的使用者,才能變更一起模式中參與者的場景或指派。 這些變更只能從Teams客戶端進行。
如果有場景變更或座位變更,則會 togetherModeSceneUpdated
分別引發 或 togetherModeSeatingUpdated
事件,並提供參與者座位位置的更新計算。
const seatUpdate = (participantSeatingMap) => {
participantSeatingMap.forEach((participantID, seatingCoordinates) => {
console.log(`User with ID: ${participantID} has new coordinates ${JSON.stringify(seatingCoordinates)} `)
})
}
togetherModeFeature.on('togetherModeSceneUpdated', seatUpdate);
togetherModeFeature.on('togetherModeSeatingUpdated', seatUpdate);
展開資料表
代碼
子代碼
結果類別
原因
解決方法
403
46303
ExpectedError
參與者的角色沒有呼叫 togetherMode
啟動 API 的必要許可權。
只有具有角色召集人、共同召集人或演示者的 365 位使用者Microsoft才能啟動 [共同模式]。 您可以透過 role
類別實例 Call
上的 屬性來檢查使用者的角色。
403
46304
ExpectedError
在不支援的呼叫案例中啟動一起模式。
請確定只有在群組通話或會議案例中才啟動 [共同模式]。
403
46306
ExpectedError
Azure 通訊服務 使用者一起呼叫的模式 start
API。
只有具有角色召集人、共同召集人或演示者的 365 位使用者Microsoft才能啟動 [共同模式]。