你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。
在通话中获取活动说话人
在活动通话期间，可能需要获取活动说话人列表，以便以不同方式呈现或显示这些说话人。 操作方法如下。
先决条件
- 具有活动订阅的 Azure 帐户。 免费创建帐户。
- 已部署的通信服务资源。 创建通信服务资源。
- 用于启用通话客户端的用户访问令牌。 有关详细信息，请参阅创建和管理访问令牌。
- 可选：完成快速入门向应用程序添加语音呼叫
安装 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 的扩展功能，可用于获取通话中的活跃说话人列表。
这是一个排名列表，列表中的第一个元素表示通话中的最后一个活跃说话人，依次类推。
为获取通话中的主导说话人，首先需获取通话主导说话人功能 API 对象：
const callDominantSpeakersApi = call.feature(Features.CallDominantSpeakers);
然后，通过调用 dominantSpeakers 获取主导说话人列表。 其类型为 DominantSpeakersInfo，具有以下成员：
speakersList包含通话中已排名的主导说话人列表。 这些由其参与者 ID 表示。timestamp是通话中的主导发言人的最新更新时间。
let dominantSpeakers: DominantSpeakersInfo = callDominantSpeakersApi.dominantSpeakers;
此外，可以订阅 dominantSpeakersChanged 事件，了解主导说话人列表何时发生变化
const dominantSpeakersChangedHandler = () => {
// Get the most up to date list of dominant speakers
let dominantSpeakers = callDominantSpeakersApi.dominantSpeakers;
};
callDominantSpeakersApi.on('dominantSpeakersChanged', dominantSpeakersChangedHandler);
处理主导说话人的视频流
应用程序可以使用 DominantSpeakers 功能呈现一个或多个主导说话人的视频流，并在主导说话人列表更新时不断更新 UI。 这可以通过以下代码示例来实现。
// RemoteParticipant obj representation of the dominant speaker
let dominantRemoteParticipant: RemoteParticipant;
// It is recommended to use a map to keep track of a stream's associated renderer
let streamRenderersMap: new Map<RemoteVideoStream, VideoStreamRenderer>();
function getRemoteParticipantForDominantSpeaker(dominantSpeakerIdentifier) {
let dominantRemoteParticipant: RemoteParticipant;
switch(dominantSpeakerIdentifier.kind) {
case 'communicationUser': {
dominantRemoteParticipant = currentCall.remoteParticipants.find(rm => {
return (rm.identifier as CommunicationUserIdentifier).communicationUserId === dominantSpeakerIdentifier.communicationUserId
});
break;
}
case 'microsoftTeamsUser': {
dominantRemoteParticipant = currentCall.remoteParticipants.find(rm => {
return (rm.identifier as MicrosoftTeamsUserIdentifier).microsoftTeamsUserId === dominantSpeakerIdentifier.microsoftTeamsUserId
});
break;
}
case 'unknown': {
dominantRemoteParticipant = currentCall.remoteParticipants.find(rm => {
return (rm.identifier as UnknownIdentifier).id === dominantSpeakerIdentifier.id
});
break;
}
}
return dominantRemoteParticipant;
}
// Handler function for when the dominant speaker changes
const dominantSpeakersChangedHandler = async () => {
// Get the new dominant speaker's identifier
const newDominantSpeakerIdentifier = currentCall.feature(Features.DominantSpeakers).dominantSpeakers.speakersList[0];
if (newDominantSpeakerIdentifier) {
// Get the remote participant object that matches newDominantSpeakerIdentifier
const newDominantRemoteParticipant = getRemoteParticipantForDominantSpeaker(newDominantSpeakerIdentifier);
// Create the new dominant speaker's stream renderers
const streamViews = [];
for (const stream of newDominantRemoteParticipant.videoStreams) {
if (stream.isAvailable && !streamRenderersMap.get(stream)) {
const renderer = new VideoStreamRenderer(stream);
streamRenderersMap.set(stream, renderer);
const view = await videoStreamRenderer.createView();
streamViews.push(view);
}
}
// Remove the old dominant speaker's video streams by disposing of their associated renderers
if (dominantRemoteParticipant) {
for (const stream of dominantRemoteParticipant.videoStreams) {
const renderer = streamRenderersMap.get(stream);
if (renderer) {
streamRenderersMap.delete(stream);
renderer.dispose();
}
}
}
// Set the new dominant remote participant obj
dominantRemoteParticipant = newDominantRemoteParticipant
// Render the new dominant remote participant's streams
for (const view of streamViewsToRender) {
htmlElement.appendChild(view.target);
}
}
};
// When call is disconnected, set the dominant speaker to undefined
currentCall.on('stateChanged', () => {
if (currentCall === 'Disconnected') {
dominantRemoteParticipant = undefined;
}
});
const dominantSpeakerIdentifier = currentCall.feature(Features.DominantSpeakers).dominantSpeakers.speakersList[0];
dominantRemoteParticipant = getRemoteParticipantForDominantSpeaker(dominantSpeakerIdentifier);
currentCall.feature(Features.DominantSpeakers).on('dominantSpeakersChanged', dominantSpeakersChangedHandler);
subscribeToRemoteVideoStream = async (stream: RemoteVideoStream, participant: RemoteParticipant) {
let renderer: VideoStreamRenderer;
const displayVideo = async () => {
renderer = new VideoStreamRenderer(stream);
streamRenderersMap.set(stream, renderer);
const view = await renderer.createView();
htmlElement.appendChild(view.target);
}
stream.on('isAvailableChanged', async () => {
if (dominantRemoteParticipant !== participant) {
return;
}
renderer = streamRenderersMap.get(stream);
if (stream.isAvailable && !renderer) {
await displayVideo();
} else {
streamRenderersMap.delete(stream);
renderer.dispose();
}
});
if (dominantRemoteParticipant !== participant) {
return;
}
renderer = streamRenderersMap.get(stream);
if (stream.isAvailable && !renderer) {
await displayVideo();
}
}
安装 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 实例，必须对 CallClient 实例调用 createCallAgent 方法。 此调用将异步返回 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 对象的扩展功能，它允许用户监视当前通话中最主要的说话人。 参与者可以根据其在通话中的行为方式加入和离开列表。
当加入由多个参与者组成的群组通话时，通话 SDK 会识别当前正在说话的会议参与者。 活跃说话人用于标识在每个收到的音频帧中正在被倾听的参与者。 主导说话人用于标识群组对话中当前最活跃或处于主导地位的参与者，虽然他们的声音不一定在每个音频帧中都被听到。 由于不同的参与者轮流说话，主导说话人组可能会改变。可以实施基于主导说话人逻辑的视频订阅请求。
主要思路是，当参与者加入、离开此参与者列表以及在此列表中的位置上下变动时，客户端应用程序可以获取此信息并相应地自定义通话体验。 例如，客户端应用程序可以在另一 UI 的通话中显示最主要的说话人，使其独立于未积极参与通话的说话人。
开发人员可以接收更新内容并获取有关通话中最主要说话人的信息。 此信息将表示为：
- 远程参与者的已排序列表，表示通话中的主导说话人。
- 一个时间戳，标记上次修改此列表的日期。
若要使用适用于 Android 的主导说话人通话功能，第一步是获取主导说话人功能 API 对象：
DominantSpeakersFeature dominantSpeakersFeature = call.feature(Features.DOMINANT_SPEAKERS);
主导说话人功能对象具有以下 API 结构：
OnDominantSpeakersChanged：用于侦听主导说话人列表中的更改的事件。getDominantSpeakersInfo()：获取DominantSpeakersInfo对象。 此对象有：getSpeakers()：一个参与者标识符列表，表示主导说话人列表。getLastUpdatedAt()：主导说话人列表的更新日期。
订阅主导说话人列表中的更改：
// Obtain the extended feature object from the call object.
DominantSpeakersFeature dominantSpeakersFeature = call.feature(Features.DOMINANT_SPEAKERS);
// Subscribe to the OnDominantSpeakersChanged event.
dominantSpeakersFeature.addOnDominantSpeakersChangedListener(handleDominantSpeakersChangedlistener);
private void handleCallOnDominantSpeakersChanged(PropertyChangedEvent args) {
// When the list changes, get the timestamp of the last change and the current list of Dominant Speakers
DominantSpeakersInfo dominantSpeakersInfo = dominantSpeakersFeature.getDominantSpeakersInfo();
Date timestamp = dominantSpeakersInfo.getLastUpdatedAt();
List<CommunicationIdentifier> dominantSpeakers = dominantSpeakersInfo.getSpeakers();
}
设置系统
创建 Visual Studio 项目
对于 UWP 应用，请在 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 包：
- 选择“工具”>“NuGet 包管理器”>“管理解决方案的 NuGet 包”，以打开 NuGet 包管理器。
- 选择“浏览”，然后在搜索框中输入
Azure.Communication.Calling.WindowsClient。 - 确保已选中“包括预发行版”复选框。
- 选择
Azure.Communication.Calling.WindowsClient包，然后选择Azure.Communication.Calling.WindowsClient1.4.0-beta.1 或更高版本。 - 在右侧选项卡上选中与 Azure 通信服务项目对应的复选框。
- 选择“安装”按钮。
主导说话人是核心 Call 对象的扩展功能，它允许用户监视当前通话中最主要的说话人。 参与者可以根据其在通话中的行为方式加入和离开列表。
当加入由多个参与者组成的群组通话时，通话 SDK 会识别当前正在说话的会议参与者。 活跃说话人用于标识在每个收到的音频帧中正在被倾听的参与者。 主导说话人用于标识群组对话中当前最活跃或处于主导地位的参与者，虽然他们的声音不一定在每个音频帧中都被听到。 由于不同的参与者轮流说话，主导说话人组可能会改变。可以实施基于主导说话人逻辑的视频订阅请求。
主要思路是，当参与者加入、离开此参与者列表以及在此列表中的位置上下变动时，客户端应用程序可以获取此信息并相应地自定义通话体验。 例如，客户端应用程序可以在另一 UI 的通话中显示最主要的说话人，使其独立于未积极参与通话的说话人。
开发人员可以接收更新内容并获取有关通话中最主要说话人的信息。 此信息将表示为：
- 远程参与者的已排序列表，表示通话中的主导说话人。
- 一个时间戳，标记上次修改此列表的日期。
若要使用适用于 Windows 的主导说话人通话功能，第一步是获取主导说话人功能 API 对象：
DominantSpeakersCallFeature dominantSpeakersFeature = call.Features.DominantSpeakers;
主导说话人功能对象具有以下 API 结构：
OnDominantSpeakersChanged：用于侦听主导说话人列表中的更改的事件。DominantSpeakersInfo：获取DominantSpeakersInfo对象。 此对象有：Speakers：一个参与者标识符列表，表示主导说话人列表。LastUpdatedAt：主导说话人列表的更新日期。
订阅主导说话人列表中的更改：
// Obtain the extended feature object from the call object.
DominantSpeakersFeature dominantSpeakersFeature = call.Features.DominantSpeakers;
// Subscribe to the OnDominantSpeakersChanged event.
dominantSpeakersFeature.OnDominantSpeakersChanged += DominantSpeakersFeature__OnDominantSpeakersChanged;
private void DominantSpeakersFeature__OnDominantSpeakersChanged(object sender, PropertyChangedEventArgs args) {
// When the list changes, get the timestamp of the last change and the current list of Dominant Speakers
DominantSpeakersInfo dominantSpeakersInfo = dominantSpeakersFeature.DominantSpeakersInfo;
DateTimeOffset date = dominantSpeakersInfo.LastUpdatedAt;
IReadOnlyList<ICommunicationIdentifier> speakersList = dominantSpeakersInfo.Speakers;
}
设置系统
创建 Xcode 项目
在 Xcode 中，创建新的 iOS 项目，并选择“单视图应用”模板。 本快速入门使用 SwiftUI 框架，因此应将“语言”设置为“Swift”，并将“接口”设置为“SwiftUI”。
在此快速入门过程中，无需创建测试。 请随意清除“包括测试”复选框。
使用 CocoaPods 安装包和依赖项
为应用程序创建 Podfile，如此示例所示：
platform :ios, '13.0' use_frameworks! target 'AzureCommunicationCallingSample' do pod 'AzureCommunicationCalling', '~> 1.0.0' end运行
pod install。使用 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
若要从 CallClient 创建 CallAgent 实例，必须使用 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 对象的扩展功能，它允许用户监视当前通话中最主要的说话人。 参与者可以根据其在通话中的行为方式加入和离开列表。
当加入由多个参与者组成的群组通话时，通话 SDK 会识别当前正在说话的会议参与者。 活跃说话人用于标识在每个收到的音频帧中正在被倾听的参与者。 主导说话人用于标识群组对话中当前最活跃或处于主导地位的参与者，虽然他们的声音不一定在每个音频帧中都被听到。 由于不同的参与者轮流说话，主导说话人组可能会改变。可以实施基于主导说话人逻辑的视频订阅请求。
主要思路是，当参与者加入、离开此参与者列表以及在此列表中的位置上下变动时，客户端应用程序可以获取此信息并相应地自定义通话体验。 例如，客户端应用程序可以在另一 UI 的通话中显示最主要的说话人，使其独立于未积极参与通话的说话人。
开发人员可以接收更新内容并获取有关通话中最主要说话人的信息。 此信息将表示为：
- 远程参与者的已排序列表，表示通话中的主导说话人。
- 一个时间戳，标记上次修改此列表的日期。
若要使用适用于 iOS 的主导说话人通话功能，第一步是获取主导说话人功能 API 对象：
let dominantSpeakersFeature = call.feature(Features.dominantSpeakers)
主导说话人功能对象具有以下 API 结构：
didChangeDominantSpeakers：用于侦听主导说话人列表中的更改的事件。dominantSpeakersInfo：用于获取DominantSpeakersInfo对象。 此对象有：speakers：一个参与者标识符列表，表示主导说话人列表。lastUpdatedAt：主导说话人列表的更新日期。
订阅主导说话人列表中的更改：
// Obtain the extended feature object from the call object.
let dominantSpeakersFeature = call.feature(Features.dominantSpeakers)
// Set the delegate object to obtain the event callback.
dominantSpeakersFeature.delegate = DominantSpeakersDelegate()
public class DominantSpeakersDelegate : DominantSpeakersCallFeatureDelegate
{
public func dominantSpeakersCallFeature(_ dominantSpeakersCallFeature: DominantSpeakersCallFeature, didChangeDominantSpeakers args: PropertyChangedEventArgs) {
// When the list changes, get the timestamp of the last change and the current list of Dominant Speakers
let dominantSpeakersInfo = dominantSpeakersCallFeature.dominantSpeakersInfo
let timestamp = dominantSpeakersInfo.lastUpdatedAt
let dominantSpeakersList = dominantSpeakersInfo.speakers
}
}
后续步骤
反馈
即将发布：在整个 2024 年，我们将逐步淘汰作为内容反馈机制的“GitHub 问题”，并将其取代为新的反馈系统。 有关详细信息，请参阅：https://aka.ms/ContentUserFeedback。
提交和查看相关反馈