在用戶端上顯示通話謄寫狀態

您必須先徵得通話中所有參與者的同意，才能謄寫他們的通話內容。 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()至 和allprojects下的buildscript存放庫清單：

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 架構，因此您應該將 Language 設定為 Swift，並將 Interface 設定為 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

若要從 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 專案

針對 通用 Windows 平台 應用程式，請在 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 套件：

1. 藉由選取 [工具]>[NuGet 套件管理員]>[管理解決方案的 NuGet 套件]，開啟 NuGet 套件管理員。
2. 選取 [ 瀏覽]，然後在搜尋方塊中輸入 Azure.Communication.Calling.WindowsClient 。
3. 請確定 已選取 [包含發行前版本 ] 複選框。
4. 選取 Azure.Communication.Calling.WindowsClient 套件，然後選取 [Azure.Communication.Calling.WindowsClient 1.4.0-beta.1] 或更新版本。
5. 選取對應至右窗格中 Azure 通訊服務 項目的複選框。
6. 選取 [安裝]。

通話謄寫是核心 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;

下一步

• 了解如何管理視訊
• 了解如何管理通話
• 了解如何錄製通話