你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

同框场景模式

项目
10/04/2024

本文介绍如何使用 Azure 通信服务通话 SDK 实现 Microsoft Teams 同框场景模式。同框场景模式可增强虚拟会议和通话体验，提升虚拟会议和通话的个性化程度。通过创建将每个人都置于共享背景中的统一视图，参与者可以无缝连接并有效协作。

重要

本文中所述的功能目前以公共预览版提供。此预览版在提供时没有附带服务级别协议，我们不建议将其用于生产工作负荷。某些功能可能不受支持或者受限。有关详细信息，请参阅 Microsoft Azure 预览版补充使用条款。

支持

下表定义了对 Azure 通信服务中的同框场景模式的支持。

标识和通话类型

下表显示了支持的通话类型和身份类型。

标识	Teams 会议	房间	1 对 1 通话	组呼叫	1:1 Teams 互操作通话	小组 Teams 互操作通话
通信服务用户	✔️			✔️		✔️
Microsoft 365 用户	✔️			✔️		✔️

Operations

下表显示了通话 SDK 中各个 API 对各个身份类型的支持。

Operations	通信服务用户	Microsoft 365 用户
启动同框场景模式流		✔️ [1]
获取同框场景模式流	✔️	✔️
获取场景大小	✔️	✔️
获取座位图	✔️	✔️
更改场景
更改座位分配

[1] 只有具有组织者、共同组织者或演示者角色的 Microsoft 365 用户才能调用“启动同框场景模式”。

SDK

下表显示了各个 Azure 通信服务 SDK 对同框场景模式功能的支持。

平台	Web	Web UI	iOS	iOS UI	Android	Android UI	Windows
支持	✔️

安装 SDK

使用 npm install 命令安装适用于 JavaScript 的 Azure 通信服务通用 SDK 和通话 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()

如何最好地管理 SDK 与 Microsoft 基础结构的连接性

Call Agent 实例可帮助你管理通话（以加入或启动通话）。通话 SDK 需要连接到 Microsoft 基础结构以获取传入通话通知并协调其他通话详细信息，否则无法工作。你的 Call Agent 有两种可能的状态：

已连接 - Call Agent connectionStatue 值为 Connected 表示客户端 SDK 已连接，能够接收来自 Microsoft 基础结构的通知。

已断开连接 - Call Agent connectionStatue 值为 Disconnected 表示存在阻止 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);

故障排除

代码	子代码	结果类别	Reason	解决方法
403	46303	ExpectedError	参与者的角色没有调用 `togetherMode` 启动 API 所需的权限。	只有具有组织者、共同组织者或演示者角色的 Microsoft 365 用户才能启动同框场景模式。可以通过 `role` 类实例上的 `Call` 属性检查用户的角色。
403	46304	ExpectedError	同框场景模式在未受支持的通话场景中启动。	确保仅在群组通话或会议场景中启动同框场景模式。
403	46306	ExpectedError	同框场景模式 `start` API 由 Azure 通信服务用户调用。	只有具有组织者、共同组织者或演示者角色的 Microsoft 365 用户才能启动同框场景模式。

通过