次の方法で共有

Together モード

  • [アーティクル]

この記事では、Azure Communication Services Calling SDK を使用して Microsoft Teams Together モードを実装する方法について説明します。 Together モードにより、仮想会議や通話が強化され、よりパーソナルな雰囲気になります。 全員を共有の背景に配置する統合ビューを作成すると、参加者がシームレスに接続し、効果的に共同作業を行うことができます。

重要

この記事で説明されている機能は、現在パブリック プレビュー段階にあります。 このプレビュー バージョンはサービス レベル アグリーメントなしで提供されており、運用環境のワークロードに使用することは推奨されません。 特定の機能はサポート対象ではなく、機能が制限されることがあります。 詳しくは、Microsoft Azure プレビューの追加使用条件に関するページをご覧ください。

サポート

次の表は、Azure Communication Services での Together モードのサポートを定義したものです。

ID と通話の種類

次の表は、サポートする通話と ID の種類を示しています。

ID Teams 会議 ルーム 1 対 1 の通話 グループ通話 1:1 Teams 相互運用機能通話 グループ チームの相互運用機能通話
Communication Services ユーザー ✔️ ✔️ ✔️
Microsoft 365 ユーザー ✔️ ✔️ ✔️

操作

次の表は、個々の ID の種類に対する Calling SDK における個々の API のサポートを示しています。

操作 Communication Services ユーザー Microsoft 365 ユーザー
Together モード ストリームを開始する ✔️ [1]
Together モード ストリームを取得する ✔️ ✔️
シーン サイズを取得する ✔️ ✔️
座席マップを取得する ✔️ ✔️
シーンを変更する
シートの割り当てを変更する

[1] Together モードの開始を呼び出せるのは、開催者、共同開催者、または発表者の役割を持つ Microsoft 365 ユーザーだけです。

SDK

次の表は、個々の Azure Communication Services SDK における Together モード機能のサポートを示しています。

プラットフォーム Web Web UI iOS iOS UI Android Android UI Windows
サポートの有無 ✔️

SDK のインストール

npm install コマンドを使用して、JavaScript 用の Azure Communication Services の Common SDK と Calling 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 には、次の 2 つの状態があります。

接続済み - 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);

Together モードを実装する

Together モードは、コア Call API の拡張機能です。 まず、Calling SDK から呼び出し機能をインポートする必要があります。

import { Features} from "@azure/communication-calling";

その後、呼び出しインスタンスから Together モード API オブジェクトを取得することができます。

const togetherModeFeature = call.feature(Features.TogetherMode);

Together モード ストリームの開始時または更新時にイベントを受信する

イベント togetherModeStreamsUpdated をサブスクライブすると、Together モードが開始または更新されたときに通知を受け取ることができます。 このイベントには、追加されたビデオ ストリームのレンダリングに関する情報が含まれています。

// event : { added: TogetherModeVideoStream[]; removed: TogetherModeVideoStream[] }
togetherModeFeature.on('togetherModeStreamsUpdated', (event) => {
    event.added.forEach(async stream => {
        // stream can be rendered as a remote video stream
    });
});

Together モード ストリームを取得する

プロパティ togetherModeStream を使用して、Together モード ストリームにアクセスできます。

const togetherModeStreams = togetherModeFeature.togetherModeStream;
Together モード ストリーム プロパティ 説明
id ストリームを識別するために使用される一意の番号。
mediaStreamType Together モード ストリームの種類を返します。 mediaStreamType の値は常に video です。
isReceiving ビデオ パケットが受信されたかどうかを示すブール値を返します。
size ストリームの幅と高さに関する情報 (ピクセル単位) を含む Together モード StreamSize を返します。

すべての参加者に対して Together モードを開始する

開催者、共同開催者、または発表者の役割を持つ Microsoft 365 ユーザーは、会議の参加者全員に対して Together モードを開始できます。 Together モードが開始されると、togetherModeStreamsUpdated イベントのすべてのサブスクライバーは、参加者が Together モードをレンダリングできるようにする通知を受け取ります。

togetherModeFeature.start();

Together モードを終了する

1 分間にどの参加者からもビデオ ストリームが検出されない場合、Together モードはすべての参加者に対して自動的に終了します。 Together モードを終了する API はありません。

Together モードで参加者の座標を取得する

プロパティ 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 )}`)

シーンまたは座席の更新時にイベントを受信する

Note

開催者、共同開催者、または発表者の役割を持つ Microsoft 365 ユーザーのみが、Together モードでシーンや参加者の割り当てを変更できます。 これらの変更は、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 start API を呼び出すために必要なアクセス許可がありません。 開催者、共同開催者、または発表者の役割を持つ Microsoft 365 ユーザーのみが、Together モードを開始できます。 ユーザーの役割は、Call クラスのインスタンスの role プロパティを使用して確認できます。
403 46304 ExpectedError サポートされていない通話シナリオで Together モードが開始されました。 グループ通話または会議のシナリオでのみ、Together モードが開始されることを確認します。
403 46306 ExpectedError Azure Communication Services ユーザーによって呼び出される Together モード start API。 開催者、共同開催者、または発表者の役割を持つ Microsoft 365 ユーザーのみが、Together モードを開始できます。

次のステップ