启用聚焦

本文介绍如何使用 Azure 通信服务通话 SDK 实现聚焦功能。 聚焦使通话或会议中的用户能够向其他参与者发出信号，即所选用户应 处于聚光灯下。 聚焦还允许用户在通话中标记其他用户，并通知所有参与者有人成为了焦点，其他客户端需要更改针对该用户的用户界面布局。

概述

聚焦将用作信号功能，而不是媒体功能。 当某个参与者被聚光灯照射时，应用程序可以确定如何管理或调整被聚光的参与者的用户界面。 聚光灯通常会导致突出显示参与者，并将其置于 UI 布局的中心。 聚焦还会放大其视频呈现器大小，同时使其他参与者的视频更小。 通话中聚焦参与者的最大限制为 7，这意味着在单个通话中，聚焦的非重复用户总数为 7（7）。

可以在 Azure 通信服务通话和 Teams 会议中聚焦参与者。 在 Teams 会议中，组织者、共同组织者或演示者可以选择多达七位用户（包括他们自己）被放入聚光灯下。 请记住，在 Teams 会议应用场景中，当通话设置为“大型画廊模式”或“同框场景模式”时，参与者无法更改 UI 布局。

若要为焦点用户的视频启用更高的分辨率，应用程序必须确保其视频呈现器比屏幕上显示的其他用户更大。 较大的渲染尺寸使 Azure 通信服务 SDK 能够请求和订阅分辨率更高的流，只要硬件和网络条件允许，该流就会与渲染器的大小相匹配。 如果并非最佳状态，SDK 会调整分辨率，以便顺畅播放。 还可以通过 视频约束控制分辨率，从而替代默认的 Azure 通信服务 SDK 行为。

先决条件

• 具有活动订阅的 Azure 帐户。 免费创建帐户。
• 已部署的通信服务资源。 创建通信服务资源。
• 用于启用通话客户端的用户访问令牌。 有关详细信息，请参阅创建和管理访问令牌。
• 可选：完成快速入门向应用程序添加语音呼叫

支持

下表定义了对 Azure 通信服务中的聚焦功能的支持。

标识和通话类型

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

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

操作

Azure 通信服务或 Microsoft 365 用户可以基于角色类型和对话类型调用聚焦操作。

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

在一对一通话、群组通话和会议场景中，通信服务和 Microsoft 365 用户都支持以下操作

操作	通信服务用户	Microsoft 365 用户
startSpotlight	✔️ [1]	✔️ [1]
stopSpotlight	✔️	✔️
stopAllSpotlight	✔️ [1]	✔️ [1]
getSpotlightedParticipants	✔️	✔️
StartSpotlightAsync	✔️ [1]	✔️ [1]
StopSpotlightAsync	✔️ [1]	✔️ [1]
StopAllSpotlightAsync	✔️ [1]	✔️ [1]
SpotlightedParticipants	✔️ [1]	✔️ [1]
MaxSupported	✔️ [1]	✔️ [1]

[1] 在 Teams 会议场景中，这些操作仅适用于具有组织者、共同组织者或演示者角色的用户。

SDK

下表显示了各个 Azure 通信服务 SDK 对聚焦功能的支持。

平台	Web	网页用户界面	iOS	iOS 用户界面	Android	安卓用户界面	Windows操作系统
是否支持	✔️	✔️	✔️		✔️		✔️

安装 SDK

使用 npm install 命令安装适用于 JavaScript 的 Azure 通信服务通用 SDK 和通话 SDK：

npm install @azure/communication-common --save
npm install @azure/communication-calling --save

初始化所需的对象

大多数通话操作需要 CallClient 实例。 创建新的 CallClient 实例时，可以使用自定义选项（如 Logger 实例）对其进行配置。

有了 CallClient 实例后，可以通过调用 CallAgent 创建 createCallAgent 实例。 此方法将异步返回 CallAgent 实例对象。

createCallAgent 方法使用 CommunicationTokenCredential 作为参数。 它接受用户访问令牌。

可在 getDeviceManager 实例上使用 CallClient 方法来访问 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 有两种可能的状态：

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

已断开连接 - Call Agent connectionStatue 值为 Disconnected 表示存在阻止 SDK 正确连接的问题。 应重新创建 Call Agent。

• invalidToken：如果令牌已过期或无效，Call Agent 实例会断开连接并出现此错误。
• connectionIssue：如果客户端在连接到 Microsoft 基础结构时出现问题，则在多次重试后，Call Agent 会显示 connectionIssue 错误。

可以通过检查 Call Agent 属性的当前值来检查本地 connectionState 是否已连接到 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 spotLightFeature = call.feature(Features.Spotlight);

为当前参与者启用聚焦

若要固定当前/本地参与者的视频，请使用以下代码。 此操作是幂等的，尝试为已固定的参与者启用聚焦不会产生任何影响。

spotLightFeature.startSpotlight();

聚焦特定参与者

通话或会议中的任何参与者都可以固定。 只有具有组织者、共同组织者或演示者角色的 Microsoft 365 用户才能为其他参与者启动聚焦。 此操作是幂等的，尝试为已固定的参与者启用聚焦不会产生任何影响。

// Specify list of participants to be spotlighted
CommunicationUserIdentifier acsUser = new CommunicationUserIdentifier(<USER_ID>);
MicrosoftTeamsUserIdentifier teamsUser = new MicrosoftTeamsUserIdentifier(<USER_ID>)
spotLightFeature.startSpotlight([acsUser, teamsUser]);

为当前参与者停止聚焦

若要取消固定当前/本地参与者的视频，请使用以下代码。 此操作是幂等的，尝试为已取消固定的参与者停止聚焦不会产生任何影响。

spotLightFeature.stopSpotlight();

删除参与者的聚焦

通话或会议中任何已固定的参与者都可以取消固定。 只有具有组织者、共同组织者或演示者角色的 Microsoft 365 用户才能取消固定其他参与者。 此操作是幂等的，尝试为已取消固定的参与者停止聚焦不会产生任何影响。

若要使用此功能，需要提供参与者标识符列表。

// Specify list of participants to be spotlighted
CommunicationUserIdentifier acsUser = new CommunicationUserIdentifier(<USER_ID>);
MicrosoftTeamsUserIdentifier teamsUser = new MicrosoftTeamsUserIdentifier(<USER_ID>)
spotLightFeature.stopSpotlight([acsUser, teamsUser]);

删除所有聚焦

可以通过此操作取消固定所有已固定的参与者。 只有具有组织者、共同组织者或演示者角色的 MicrosoftTeamsUserIdentifier 用户才能取消固定所有参与者。

spotLightFeature.stopAllSpotLight();

处理已更改状态

聚焦模式使你能够订阅 SpotlightChanged 事件。 SpotlightChanged 事件来自通话实例，其中包含有关新聚焦的参与者和已停止聚焦的参与者的信息。 返回的数组 SpotlightedParticipant 按参与者聚焦的顺序进行排序。

若要获取当前通话中所有参与者聚焦状态变化的相关信息，请使用以下代码。

// event : { added: SpotlightedParticipant[]; removed: SpotlightedParticipant[] }
// SpotlightedParticipant = { identifier: CommunicationIdentifier, order?: number }
// where: 
//  identifier: ID of participant whose spotlight state is changed
//  order: sequence of the event

const spotlightChangedHandler = (event) => {
    console.log(`Newly added spotlight state ${JSON.stringify(event.added)}`);
    console.log(`Newly removed spotlight state ${JSON.stringify(event.removed)}`);
};
spotLightFeature.on('spotlightChanged', spotlightChangedHandler);

使用以下命令停止接收 spotlightUpdated 事件

spotLightFeature.off('spotlightChanged', spotlightChangedHandler);

获取当前聚焦的所有参与者的列表

若要获取当前通话中具有聚焦状态的所有参与者的相关信息，可以使用以下操作。 返回的数组 SpotlightedParticipant 按参与者聚焦的顺序进行排序。

let spotlightedParticipants = spotLightFeature.getSpotlightedParticipants();

获取支持的最大聚焦参与者数

以下操作可用于获取可以使用通话 SDK 聚焦的最大参与者数。

spotLightFeature.maxParticipantsToSpotlight;

安装 SDK

找到项目级 build.gradle 文件，并将 mavenCentral() 添加到 buildscript 和 allprojects 下的存储库列表中：

buildscript {
    repositories {
    ...
        mavenCentral()
    ...
    }
}

allprojects {
    repositories {
    ...
        mavenCentral()
    ...
    }
}

然后，在模块级 build.gradle 文件中，将以下行添加到 dependencies 部分：

dependencies {
    ...
    implementation 'com.azure.android:azure-communication-calling:1.0.0'
    ...
}

初始化所需的对象

若要创建 CallAgent 实例，必须对 createCallAgent 实例调用 CallClient 方法。 此调用将异步返回 CallAgent 实例对象。

createCallAgent 方法采用 CommunicationUserCredential 作为参数来封装访问令牌。

若要访问 DeviceManager，必须先创建 callAgent 实例。 然后，可以使用 CallClient.getDeviceManager 方法获取 DeviceManager。

String userToken = '<user token>';
CallClient callClient = new CallClient();
CommunicationTokenCredential tokenCredential = new CommunicationTokenCredential(userToken);
android.content.Context appContext = this.getApplicationContext(); // From within an activity, for instance
CallAgent callAgent = callClient.createCallAgent(appContext, tokenCredential).get();
DeviceManager deviceManager = callClient.getDeviceManager(appContext).get();

若要为主叫方设置显示名称，请使用以下替代方法：

String userToken = '<user token>';
CallClient callClient = new CallClient();
CommunicationTokenCredential tokenCredential = new CommunicationTokenCredential(userToken);
android.content.Context appContext = this.getApplicationContext(); // From within an activity, for instance
CallAgentOptions callAgentOptions = new CallAgentOptions();
callAgentOptions.setDisplayName("Alice Bob");
DeviceManager deviceManager = callClient.getDeviceManager(appContext).get();
CallAgent callAgent = callClient.createCallAgent(appContext, tokenCredential, callAgentOptions).get();

实现聚焦

聚焦是核心 Call API 的扩展功能。 首先，需要从通话 SDK 导入通话功能。

import com.azure.android.communication.calling.SpotlightFeature;

然后，可从通话实例获取功能 API 对象。

SpotlightCallFeature spotlightCallFeature;
spotlightCallFeature = call.feature(Features.SPOTLIGHT);

为参与者启动聚焦

通话或会议中的任何参与者都可以固定。 只有具有组织者、共同组织者或演示者角色的 Microsoft 365 用户才能为其他参与者启动聚焦。 此操作是幂等的，尝试在已固定的参与者上启动聚焦不会产生任何影响

若要使用此功能，需要提供参与者标识符列表。

List<CommunicationIdentifier> spotlightIdentifiers = new ArrayList<>();
CommunicationUserIdentifier acsUser = new CommunicationUserIdentifier(<USER_ID>);
MicrosoftTeamsUserIdentifier teamsUser = new MicrosoftTeamsUserIdentifier(<USER_ID>);
spotlightIdentifiers.add(new CommunicationUserIdentifier("<USER_ID>"));
spotlightIdentifiers.add(new MicrosoftTeamsUserIdentifier("<USER_ID>"));
spotlightCallFeature.StartSpotlight(spotlightIdentifiers);

还可以使用以下代码启动参与者聚焦。

CommunicationUserIdentifier acsUser = new CommunicationUserIdentifier(<USER_ID>);
MicrosoftTeamsUserIdentifier teamsUser = new MicrosoftTeamsUserIdentifier(<USER_ID>);
spotlightCallFeature.StartSpotlight(acsUser, teamsUser);

删除参与者的聚焦

通话或会议中任何已固定的参与者都可以取消固定。 只有具有组织者、共同组织者或演示者角色的 Microsoft 365 用户才能取消固定其他参与者。 此操作是幂等的，尝试为已取消固定的参与者停止聚焦不会产生任何影响。

若要使用此功能，需要提供参与者标识符列表。

List<CommunicationIdentifier> spotlightIdentifiers = new ArrayList<>();
CommunicationUserIdentifier acsUser = new CommunicationUserIdentifier(<USER_ID>);
MicrosoftTeamsUserIdentifier teamsUser = new MicrosoftTeamsUserIdentifier(<USER_ID>);
spotlightIdentifiers.add(new CommunicationUserIdentifier("<USER_ID>"));
spotlightIdentifiers.add(new MicrosoftTeamsUserIdentifier("<USER_ID>"));
spotlightCallFeature.StopSpotlight(spotlightIdentifiers);

还可以使用以下代码移除参与者聚焦。

CommunicationUserIdentifier acsUser = new CommunicationUserIdentifier(<USER_ID>);
MicrosoftTeamsUserIdentifier teamsUser = new MicrosoftTeamsUserIdentifier(<USER_ID>);
spotlightCallFeature.StopSpotlight(acsUser, teamsUser);

删除所有聚焦

可以通过此操作取消固定所有已固定的参与者。 只有具有组织者、共同组织者或演示者角色的 MicrosoftTeamsUserIdentifier 用户才能取消固定所有参与者。

spotlightCallFeature.stopAllSpotlight();

处理已更改状态

聚焦模式使你能够订阅 SpotlightChanged 事件。 SpotlightChanged 事件来自通话实例，其中包含有关新聚焦的参与者和已停止聚焦的参与者的信息。 返回的数组 SpotlightedParticipant 按参与者聚焦的顺序进行排序。

若要获取当前通话中所有参与者聚焦状态变化的相关信息，请使用以下代码。

import com.azure.android.communication.calling.SpotlightedParticipant;

// event : { added: SpotlightedParticipant[]; removed: SpotlightedParticipant[] }
// SpotlightedParticipant = { identifier: CommunicationIdentifier }
// where: 
//  identifier: ID of participant whose spotlight state is changed
void onSpotlightChanged(SpotlightChangedEvent args) {
    Log.i(ACTIVITY_TAG, String.format("Spotlight Changed Event"));
    for(SpotlightedParticipant participant: args.getadded()) {
        Log.i(ACTIVITY_TAG, String.format("Added ==>: %s %d", Utilities.toMRI(participant.getIdentifier())));
    }

    for(SpotlightedParticipant participant: args.getremoved()) {
        Log.i(ACTIVITY_TAG, String.format("Removed ==>: %s %d", Utilities.toMRI(participant.getIdentifier())));
    }
}
spotlightCallFeature.addOnSpotlightChangedListener(onSpotlightChanged);

获取所有已聚焦的参与者

若要获取当前通话中具有聚焦状态的所有参与者的相关信息，可以使用以下操作。 返回的数组按参与者聚焦的顺序进行排序。

List<SpotlightedParticipant> currentSpotlightedParticipants = spotlightCallFeature.getSpotlightedParticipants();
foreach (SpotlightedParticipant participant in currentSpotlightedParticipants)
{
    Trace.WriteLine("Participant " + participant.Identifier.RawId + " has spotlight");
}

获取支持的最大聚焦参与者数

以下操作可用于获取可以使用通话 SDK 聚焦的最大参与者数。

spotlightCallFeature.maxSupported();

设置系统

若要设置系统，请按照以下步骤操作。

创建 Xcode 项目

在 Xcode 中，创建新的 iOS 项目，并选择“单视图应用”模板。 本文使用 SwiftUI 框架，因此应将“语言”设置为“Swift”，并将“界面”设置为“SwiftUI”。

在本文中，无需创建测试。 请随意清除“包括测试”复选框。

使用 CocoaPods 安装包和依赖项

1. 为应用程序创建 Podfile，如此示例所示：

   platform :ios, '13.0'
   use_frameworks!
   target 'AzureCommunicationCallingSample' do
       pod 'AzureCommunicationCalling', '~> 1.0.0'
   end
   

2. 运行 pod install。

3. 使用 Xcode 打开 .xcworkspace。

请求访问麦克风

若要访问设备的麦克风，需要使用 NSMicrophoneUsageDescription 更新应用的信息属性列表。 将关联的值设置为一个字符串，该字符串将包含在系统用于向用户请求访问权限的对话框中。

右键单击项目树的 Info.plist 条目，然后选择“打开为...”“源代码”>。 将以下代码行添加到顶层 <dict> 部分，然后保存文件。

<key>NSMicrophoneUsageDescription</key>
<string>Need microphone access for VOIP calling.</string>

设置应用框架

打开项目的 ContentView.swift 文件。 将 import 声明添加到文件顶部以导入 AzureCommunicationCalling 库。 此外，导入 AVFoundation。 你需要使用它来处理代码中的音频权限请求。

import AzureCommunicationCalling
import AVFoundation

初始化 CallAgent

若要从 CallAgent 创建 CallClient 实例，必须使用 callClient.createCallAgent 方法，该方法在初始化后异步返回 CallAgent 对象。

若要创建通话客户端，请传递 CommunicationTokenCredential 对象：

import AzureCommunication

let tokenString = "token_string"
var userCredential: CommunicationTokenCredential?
do {
    let options = CommunicationTokenRefreshOptions(initialToken: token, refreshProactively: true, tokenRefresher: self.fetchTokenSync)
    userCredential = try CommunicationTokenCredential(withOptions: options)
} catch {
    updates("Couldn't created Credential object", false)
    initializationDispatchGroup!.leave()
    return
}

// tokenProvider needs to be implemented by Contoso, which fetches a new token
public func fetchTokenSync(then onCompletion: TokenRefreshOnCompletion) {
    let newToken = self.tokenProvider!.fetchNewToken()
    onCompletion(newToken, nil)
}

将创建的 CommunicationTokenCredential 对象传递给 CallClient 并设置显示名称：

self.callClient = CallClient()
let callAgentOptions = CallAgentOptions()
options.displayName = " iOS Azure Communication Services User"

self.callClient!.createCallAgent(userCredential: userCredential!,
    options: callAgentOptions) { (callAgent, error) in
        if error == nil {
            print("Create agent succeeded")
            self.callAgent = callAgent
        } else {
            print("Create agent failed")
        }
})

实现聚焦

聚焦是核心 Call API 的扩展功能。 首先，需要从通话 SDK 导入通话功能。

import AzureCommunicationCalling

然后，可从通话实例获取功能 API 对象：

@State var spotlightFeature: SpotlightCallFeature?

spotlightFeature = self.call!.feature(Features.spotlight)

为参与者启动聚焦

通话或会议中的任何参与者都可以固定。 只有具有组织者、共同组织者或演示者角色的 Microsoft 365 用户才能为其他参与者启动聚焦。 此操作是幂等的，尝试在已固定的参与者上启动聚焦不会产生任何影响

若要使用此功能，需要提供参与者标识符列表。

var identifiers : [CommunicationIdentifier] = []
identifiers.append(CommunicationUserIdentifier("<USER_ID>"))
identifiers.append(MicrosoftTeamsUserIdentifier("<USER_ID>"))
spotlightFeature.startSpotlight(participants: identifiers, completionHandler: { (error) in
    if let error = error {
        print ("startSpotlight failed %@", error as Error)
    }
})

删除参与者的聚焦

通话或会议中任何已固定的参与者都可以取消固定。 只有具有组织者、共同组织者或演示者角色的 Microsoft 365 用户才能取消固定其他参与者。 此操作是幂等的，尝试为已取消固定的参与者停止聚焦不会产生任何影响。

若要使用此功能，需要提供参与者标识符列表。

var identifiers : [CommunicationIdentifier] = []
identifiers.append(CommunicationUserIdentifier("<USER_ID>"))
identifiers.append(MicrosoftTeamsUserIdentifier("<USER_ID>"))
spotlightFeature.stopSpotlight(participants: identifiers, completionHandler: { (error) in
    if let error = error {
        print ("stopSpotlight failed %@", error as Error)
    }
})

删除所有聚焦

可以通过此操作取消固定所有已固定的参与者。 只有具有组织者、共同组织者或演示者角色的 MicrosoftTeamsUserIdentifier 用户才能取消固定所有参与者。

spotlightFeature.stopAllSpotlight(completionHandler: { (error) in
    if let error = error {
        print ("stopAllSpotlight failed %@", error as Error)
    }
})

处理已更改状态

聚焦模式使你能够订阅 SpotlightChanged 事件。 SpotlightChanged 事件来自通话实例，其中包含有关新聚焦的参与者和已停止聚焦的参与者的信息。 返回的数组 SpotlightedParticipant 按参与者聚焦的顺序进行排序。

若要获取当前通话中所有参与者聚焦状态变化的相关信息，请使用以下代码。

// event : { added: SpotlightedParticipant[]; removed: SpotlightedParticipant[] }
// SpotlightedParticipant = { identifier: CommunicationIdentifier }
// where: 
//  identifier: ID of participant whose spotlight state is changed

spotlightFeature = self.call!.feature(Features.spotlight)
spotlightFeature!.delegate = self.SpotlightDelegate

public class SpotlightDelegate: SpotlightCallFeatureDelegate {
    public func SpotlightCallFeature(_ spotlightCallFeature: SpotlightCallFeature, didChangeSpotlight args: SpotlightChangedEventArgs) {
        args.added.forEach { participant in
            print("Spotlight participant " + Utilities.toMri(participant.identifier) +  "is ON")
        }
        args.removed.forEach { participant in
            print("Spotlight participant " + Utilities.toMri(participant.identifier) +  "is OFF")
        }
    }
}

获取所有已聚焦的参与者

若要获取当前通话中具有聚焦状态的所有参与者的相关信息，可以使用以下操作。 返回的数组按参与者聚焦的顺序进行排序。

spotlightCallFeature.spotlightedParticipants.forEach { participant in
    print("Spotlight active for participant: " + Utilities.toMri(participant.identifier))
}

获取支持的最大聚焦参与者数

以下操作可用于获取可以使用通话 SDK 聚焦的最大参与者数。

spotlightCallFeature.maxSupported();

设置系统

若要设置系统，请按照以下步骤操作。

创建 Visual Studio 项目

对于通用 Windows 平台应用，请在 Visual Studio 2022 中创建新的“空白应用(通用 Windows)”项目。 输入项目名称后，可随意选择任何版本高于 10.0.17763.0 的 Windows SDK。

对于 WinUI 3 应用，请使用“已打包空白应用(桌面中的 WinUI 3)”模板创建新项目，以设置单页 WinUI 3 应用。 需要 Windows App SDK 版本 1.3 或更高版本。

使用 NuGet 包管理器安装包和依赖项

可通过 NuGet 包公开提供通话 SDK API 和库。

要查找、下载和安装通话 SDK NuGet 包，请执行以下操作：

1. 选择“工具”“NuGet 包管理器”>“管理解决方案的 NuGet 包”，以打开 NuGet 包管理器。>
2. 选择“浏览”，然后在搜索框中输入 Azure.Communication.Calling.WindowsClient。
3. 确保已选中“包括预发行版”复选框。
4. 选择 Azure.Communication.Calling.WindowsClient 包，然后选择 Azure.Communication.Calling.WindowsClient1.4.0-beta.1 或更新版本。
5. 在右侧窗格中选中与 Azure 通信服务项目对应的复选框。
6. 选择“安装”。

实现聚焦

聚焦是核心 Call API 的扩展功能。 首先，需要从通话 SDK 导入通话功能。

using Azure.Communication.Calling.WindowsClient;

然后，可从通话实例获取功能 API 对象。

private SpotlightCallFeature spotlightCallFeature;
spotlightCallFeature = call.Features.Spotlight;

为参与者启动聚焦

通话或会议中的任何参与者都可以固定。 只有具有组织者、共同组织者或演示者角色的 Microsoft 365 用户才能为其他参与者启动聚焦。 此操作是幂等的，尝试在已固定的参与者上启动聚焦不会产生任何影响

若要使用此功能，需要提供参与者标识符列表

List<CallIdentifier> spotlightIdentifiers= new List<CallIdentifier>();
spotlightIdentifiers.Add("USER_ID");
spotlightIdentifiers.Add("USER_ID");
spotlightCallFeature.StartSpotlightAsync(spotlightIdentifiers);

删除参与者的聚焦

通话或会议中任何已固定的参与者都可以取消固定。 只有具有组织者、共同组织者或演示者角色的 Microsoft 365 用户才能取消固定其他参与者。 此操作是幂等的，尝试为已取消固定的参与者停止聚焦不会产生任何影响。

若要使用此功能，需要提供参与者标识符列表。

List<CallIdentifier> spotlightIdentifiers= new List<CallIdentifier>();
spotlightIdentifiers.Add("USER_ID");
spotlightIdentifiers.Add("USER_ID");
spotlightCallFeature.StopSpotlightAsync(spotlightIdentifiers);

删除所有聚焦

可以通过此操作取消固定所有已固定的参与者。 只有具有组织者、共同组织者或演示者角色的 MicrosoftTeamsUserIdentifier 用户才能取消固定所有参与者。

spotlightCallFeature.StopAllSpotlightAsync();

处理已更改状态

聚焦模式使你能够订阅 SpotlightChanged 事件。 SpotlightChanged 事件来自通话实例，其中包含有关新聚焦的参与者和已停止聚焦的参与者的信息。 返回的数组 SpotlightedParticipant 按参与者聚焦的顺序进行排序。

若要获取当前通话中所有参与者聚焦状态变化的相关信息，请使用以下代码。

// event : { added: SpotlightedParticipant[]; removed: SpotlightedParticipant[] }
// SpotlightedParticipant = { identifier: CommunicationIdentifier }
// where: 
//  identifier: ID of participant whose spotlight state is changed
private void OnSpotlightChange(object sender, SpotlightChangedEventArgs args)
{
    foreach (SpotlightedParticipant rh in args.added)
    {
        Trace.WriteLine("Added ===========> " + rh.Identifier.RawId);
    }
    foreach (SpotlightedParticipant rh in args.removed)
    {
        Trace.WriteLine("Removed =========> " + rh.Identifier.RawId);
    }
}
spotlightCallFeature.SpotlightChanged += OnSpotlightChange;

获取所有已聚焦的参与者

若要获取当前通话中具有聚焦状态的所有参与者的相关信息，可以使用以下操作。 返回的数组按参与者聚焦的顺序进行排序。

List<SpotlightedParticipant> currentSpotlightedParticipants = spotlightCallFeature.SpotlightedParticipants();
foreach (SpotlightedParticipant participant in currentSpotlightedParticipants)
{
    Trace.WriteLine("Participant " + participant.Identifier.RawId + " has spotlight");
}

获取支持的最大聚焦参与者数

以下操作可用于获取可以使用通话 SDK 聚焦的最大参与者数。

spotlightCallFeature.MaxSupported();

疑难解答

Code	子代码	结果类别	原因	解决方法
400	45900	ExpectedError	已聚焦所有给定的参与者 ID。	仅可聚焦当前未被聚焦的参与者。
400	45902	ExpectedError	已聚焦的最大参与者数。	无论何时，都只能有 7 个参与者处于聚焦状态。
403	45903	ExpectedError	只有具有组织者、共同组织者或演示者角色的参与者才能启动聚焦功能。	确保调用 startSpotlight 操作的参与者具有组织者、共同组织者或演示者角色。

后续步骤

• 了解如何管理通话
• 了解如何管理视频
• 了解如何记录通话
• 了解如何转录通话