在用戶端上顯示通話謄寫狀態
您必須先徵得通話中所有參與者的同意,才能謄寫他們的通話內容。 Microsoft Teams 允許使用者在會議或通話中開始謄寫。 如果謄寫在您加入通話或會議之前開始,您會在謄寫開始時收到事件,並可檢查謄寫狀態。
必要條件
- 具有有效訂用帳戶的 Azure 帳戶。 免費建立帳戶。
- 已部署通訊服務資源。 建立通訊服務資源。
- 用來啟用呼叫用戶端的使用者存取權杖。 如需詳細資訊,請參閱建立和管理存取權杖。
- 選擇性:完成快速入門以將語音通話新增至您的應用程式
支援
下表定義 Azure 通訊服務中通話謄寫的支援。
身分識別和通話類型
下表顯示特定通話類型和身分識別的謄寫支援。
身分識別 | Teams 會議 | 會議室 | 1:1 通話 | 群組通話 | 一對一 Teams Interop 通話 | 群組 Teams Interop 通話 |
---|---|---|---|---|---|---|
通訊服務使用者 | ✔️ | ✔️ | ✔️ | |||
Microsoft 365 使用者 | ✔️ | ✔️ | ✔️ |
Operations
下表顯示通話 SDK 中對個別身分識別類型支援的個別 API。
Operations | 通訊服務使用者 | Microsoft 365 使用者 |
---|---|---|
取得已開始謄寫的事件 | ✔️ | ✔️ |
取得謄寫狀態 | ✔️ | ✔️ |
開始或停止謄寫 |
SDK
下表顯示個別 Azure 通訊服務 SDK 中的謄寫支援。
平台 | Web | Web UI | iOS | iOS UI | Android | Android UI | Windows |
---|---|---|---|---|---|---|---|
受到支援 | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ |
安裝 SDK
使用 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);
警告
由於 Microsoft Teams 變更,JavaScript 通話 SDK 1.21 版和更低版本會停止 Teams 謄寫並阻止 Teams 使用者開始謄寫。 如果您想要在通話和會議中使用 Teams 謄寫,您必須將通話 SDK 升級為至少 1.22 版。
通話謄寫
Transcription
是類別 Call
的擴充功能。 您必須先取得謄寫功能 API 物件
const callTranscriptionFeature = call.feature(Features.Transcription);
您可以在 isTranscriptionActive
屬性中檢查謄寫的狀態。 如果值設定為 true
,則謄寫為使用中。
const isTranscriptionActive = callTranscriptionFeature.isTranscriptionActive;
您可以訂閱當謄寫狀態變更時所觸發的事件:
const isTranscriptionActiveChangedHandler = () => {
console.log(callTranscriptionFeature.isTranscriptionActive);
};
callTranscriptionFeature.on('isTranscriptionActiveChanged', isTranscriptionActiveChangedHandler);
您可使用下列程式碼來取消訂閱事件:
callTranscriptionFeature.off('isTranscriptionActiveChanged', isTranscriptionActiveChangedHandler);
安裝 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();
警告
截至 Azure 通訊服務呼叫 Android SDK 的 1.1.0 版和 Beta 版本 1.1.0-Beta.1 為止,其中具有屬於 Call
物件一部分的 isTranscriptionActive
和 addOnIsTranscriptionActiveChangedListener
。 針對新的 Beta 版本,這些 API 已移動為 Call
的擴充功能,如下所示。
通話謄寫是核心 Call
物件的擴充功能。 您必須先取得謄寫功能物件:
TranscriptionCallFeature callTranscriptionFeature = call.feature(Features.TRANSCRIPTION);
然後,若要檢查是否正在謄寫通話,請檢查 callTranscriptionFeature
的 isTranscriptionActive
屬性。 它會傳回 boolean
。
boolean isTranscriptionActive = callTranscriptionFeature.isTranscriptionActive();
您也可以訂閱謄寫的變更:
private void handleCallOnIsTranscriptionChanged(PropertyChangedEvent args) {
boolean isTranscriptionActive = callTranscriptionFeature.isTranscriptionActive();
}
callTranscriptionFeature.addOnIsTranscriptionActiveChangedListener(handleCallOnIsTranscriptionChanged);
設定系統
建立 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")
}
})
警告
截至 Azure 通訊服務呼叫 iOS SDK 的 1.1.0 版和 Beta 版本 1.1.0-Beta.1 為止,其中具有屬於 Call
物件一部分的 isTranscriptionActive
以及 CallDelegate
委派一部分的 didChangeTranscriptionState
。 針對新的 Beta 版本,這些 API 已移動為 Call
的擴充功能,如下所示。
通話謄寫是核心 Call
物件的擴充功能。 您必須先取得謄寫功能物件:
let callTranscriptionFeature = call.feature(Features.transcription)
然後,若要檢查是否已謄寫通話,請檢查 callTranscriptionFeature
的 isTranscriptionActive
屬性。 它會傳回 Bool
。
let isTranscriptionActive = callTranscriptionFeature.isTranscriptionActive;
您也可以使用事件 didChangeTranscriptionState
在類別上實作 TranscriptionCallFeatureDelegate
委派,來訂閱謄寫的變更:
callTranscriptionFeature.delegate = self
// didChangeTranscriptionState is a member of TranscriptionCallFeatureDelegate
public func transcriptionCallFeature(_ transcriptionCallFeature: TranscriptionCallFeature, didChangeTranscriptionState args: PropertyChangedEventArgs) {
let isTranscriptionActive = callTranscriptionFeature.isTranscriptionActive
}
設定系統
建立 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 套件管理員來安裝套件和相依性
通話 SDK API 和程式庫可透過 NuGet 套件公開取得。
下列步驟示範如何尋找、下載及安裝通話 SDK NuGet 套件:
- 藉由選取 [工具]>[NuGet 套件管理員]>[管理解決方案的 NuGet 套件],開啟 NuGet 套件管理員。
- 選取 [瀏覽],然後在搜尋方塊中輸入
Azure.Communication.Calling.WindowsClient
。 - 確定已選取 [包含發行前版本] 核取方塊。
- 選取
Azure.Communication.Calling.WindowsClient
套件,然後選取Azure.Communication.Calling.WindowsClient
1.4.0-beta.1 或更新版本。 - 選取與右側索引標籤上的「通訊服務」專案相對應的核取方塊。
- 選取 [安裝] 按鈕。
通話謄寫是核心 Call
物件的擴充功能。 您必須先取得謄寫功能物件:
TranscriptionCallFeature transcriptionFeature = call.Features.Transcription;
然後,若要檢查是否正在謄寫通話,請檢查 transcriptionFeature
的 IsTranscriptionActive
屬性。 它會傳回 boolean
。
boolean isTranscriptionActive = transcriptionFeature.isTranscriptionActive;
您也可以訂閱謄寫的變更:
private async void Call__OnIsTranscriptionActiveChanged(object sender, PropertyChangedEventArgs args)
boolean isTranscriptionActive = transcriptionFeature.IsTranscriptionActive();
}
transcriptionFeature.IsTranscriptionActiveChanged += Call__OnIsTranscriptionActiveChanged;