快速入門: 將字幕新增至您的通話應用程式

發行項
08/08/2024

必要條件

包含使用中訂用帳戶的 Azure 帳戶。如需詳細資料，請參閱建立免費帳戶。
Azure 通訊服務資源。請參閱建立 Azure 通訊服務資源。儲存此資源的連接字串。
具有語音和視訊通話的應用程式，請參閱我們的語音和視訊通話快速入門。

注意

請注意，您必須具有語音通話應用程式，才能使用 Azure 通訊服務通話 SDK 來存取本指南中所述的隱藏式輔助字幕功能。

模型

名稱	描述
CaptionsCallFeature	適用於字幕的 API
CaptionsCommon	字幕的基底類別
StartCaptionOptions	口語語言等隱藏式輔助字幕選項
CaptionsHandler	處理 CaptionsReceivedEventType 事件的回呼定義
CaptionsInfo	針對每個 CaptionsReceivedEventType 事件接收的資料結構

取得隱藏式輔助字幕功能

let captionsCallFeature: SDK.CaptionsCallFeature = call.feature(SDK.Features.Captions);

取得 captions 物件

您需要取得 Captions 物件並轉換，才能使用 Captions 特定功能。

let captions: SDK.Captions;
if (captionsCallFeature.captions.kind === 'Captions') {
    captions = captionsCallFeature.captions as SDK.Captions;
}

新增接聽程式以接收字幕作用中/非作用中狀態

const captionsActiveChangedHandler = () => {
    if (captions.isCaptionsFeatureActive) {
        /* USER CODE HERE - E.G. RENDER TO DOM */
    }
}
captions.on('CaptionsActiveChanged', captionsActiveChangedHandler);

新增所接收字幕資料的接聽程式

處理傳回的 CaptionsInfo 資料物件。

注意：物件包含 resultType 屬性，該屬性指出資料是部分字幕或最終的字幕版本。 ResultType Partial 表示未經過編輯的即時字幕，而 Final 表示句子的最終解譯版本 (即包括標點符號和大小寫)。

const captionsReceivedHandler : CaptionsHandler = (data: CaptionsInfo) => { 
    /** USER CODE HERE - E.G. RENDER TO DOM 
     * data.resultType
     * data.speaker
     * data.spokenLanguage
     * data.spokenText
     * data.timeStamp
    */
   // Example code:
   // Create a dom element, i.e. div, with id "captionArea" before proceeding with the sample code
    let mri: string;
    switch (data.speaker.identifier.kind) {
        case 'communicationUser': { mri = data.speaker.identifier.communicationUserId; break; }
        case 'phoneNumber': { mri = data.speaker.identifier.phoneNumber; break; }
    }
    const outgoingCaption = `prefix${mri.replace(/:/g, '').replace(/-/g, '')}`;

    let captionArea = document.getElementById("captionArea");
    const captionText = `${data.timestamp.toUTCString()}
        ${data.speaker.displayName}: ${data.spokenText}`;

    let foundCaptionContainer = captionArea.querySelector(`.${outgoingCaption}[isNotFinal='true']`);
    if (!foundCaptionContainer) {
        let captionContainer = document.createElement('div');
        captionContainer.setAttribute('isNotFinal', 'true');
        captionContainer.style['borderBottom'] = '1px solid';
        captionContainer.style['whiteSpace'] = 'pre-line';
        captionContainer.textContent = captionText;
        captionContainer.classList.add(outgoingCaption);

        captionArea.appendChild(captionContainer);
    } else {
        foundCaptionContainer.textContent = captionText;

        if (captionData.resultType === 'Final') {
            foundCaptionContainer.setAttribute('isNotFinal', 'false');
        }
    }
}; 
captions.on('CaptionsReceived', captionsReceivedHandler);

新增接聽程式以接收口語語言已變更狀態

// set a local variable currentSpokenLanguage to track the current spoken language in the call
let currentSpokenLanguage = ''
const spokenLanguageChangedHandler = () => {
    if (captions.activeSpokenLanguage !== currentSpokenLanguage) {
        /* USER CODE HERE - E.G. RENDER TO DOM */
    }
}
captions.on('SpokenLanguageChanged', spokenLanguageChangedHandler)

啟動字幕

設定所有接聽程序之後，您現在可以開始新增輔助字幕。

try {
    await captions.startCaptions({ spokenLanguage: 'en-us' });
} catch (e) {
    /* USER ERROR HANDLING CODE HERE */
}

停止字幕

try {
    captions.stopCaptions(); 
} catch (e) {
    /* USER ERROR HANDLING CODE HERE */
}

取消訂閱接聽程式

captions.off('CaptionsActiveChanged', captionsActiveChangedHandler);
captions.off('CaptionsReceived', captionsReceivedHandler);

口語語言支援

取得支援的口語語言清單

取得支援的口語語言清單，以便使用者在啟用隱藏式輔助字幕時從中選取。此屬性會傳回 bcp 47 格式的語言陣列。

const spokenLanguages = captions.supportedSpokenLanguages;

設定口語語言

從支援的口語語言陣列傳入值，以確保支援所要求的語言。根據預設，如果 contoso 未提供任何語言或提供不支援的語言，則口語語言會預設為 'en-us'。

// bcp 47 formatted language code
const language = 'en-us'; 

// Alternatively, pass a value from the supported spoken languages array
const language = spokenLanguages[0]; 

try {
    captions.setSpokenLanguage(language);
} catch (e) {
    /* USER ERROR HANDLING CODE HERE */
}

新增接聽程式以接收標題種類已變更狀態

如果 Teams/CTE 使用者加入通話，或通話變更為 Interop 呼叫類型，標題種類可能會從 Captions 變更為 TeamsCaptions。需要重新訂閱 Teams Captions接聽程式，才能繼續標題體驗。 TeamsCaptions 種類無法在通話中使用TeamsCaptions之後切換或變更回通話中的 Captions 種類。

const captionsKindChangedHandler = () => {
    /* USER CODE HERE - E.G. SUBSCRIBE TO TEAMS CAPTIONS */
}
captions.on('CaptionsKindChanged', captionsKindChangedHandler)

必要條件

包含使用中訂用帳戶的 Azure 帳戶。如需詳細資料，請參閱建立免費帳戶。
Azure 通訊服務資源。請參閱建立 Azure 通訊服務資源。儲存此資源的連接字串。
具有語音和視訊通話的應用程式，請參閱我們的語音和視訊通話快速入門。

注意

請注意，您必須具有語音通話應用程式，才能使用 Azure 通訊服務通話 SDK 來存取本指南中所述的隱藏式輔助字幕功能。

模型

名稱	描述
CaptionsCallFeature	適用於字幕呼叫功能的 API
CommunicationCaptions	通訊輔助字幕的 API
StartCaptionOptions	口語語言等隱藏式輔助字幕選項
CommunicationCaptionsReceivedEventArgs	針對每個接收的通訊標題所接收的數據物件

取得隱藏式輔助字幕功能

您需要取得 Captions 物件並轉換，才能使用 Captions 特定功能。

CaptionsCallFeature captionsCallFeature = call.Features.Captions;
CallCaptions callCaptions = await captionsCallFeature.GetCaptionsAsync();
if (callCaptions.CaptionsKind == CaptionsKind.CommunicationCaptions)
{
    CommunicationCaptions communicationCaptions = callCaptions as CommunicationCaptions;
}

新增接聽程式以接收字幕已啟用/已停用狀態

communicationCaptions.CaptionsEnabledChanged += OnIsCaptionsEnabledChanged;

private void OnIsCaptionsEnabledChanged(object sender, PropertyChangedEventArgs args)
{
    if (communicationCaptions.IsEnabled)
    {
    }
}

新增接聽程式以接收已變更的標題類型

當標題類型在CommunicationCaptionsTeamsCaptions邀請Microsoft 365位使用者到僅限 ACS 的通話時，將會觸發此事件。

captionsCallFeature.ActiveCaptionsTypeChanged += OnIsCaptionsTypeChanged;

private void OnIsCaptionsTypeChanged(object sender, PropertyChangedEventArgs args)
{
    // get captions
}

新增所接收字幕資料的接聽程式

communicationCaptions.CaptionsReceived += OnCaptionsReceived;

private void OnCaptionsReceived(object sender, CommunicationCaptionsReceivedEventArgs eventArgs)
{
    // Information about the speaker.
    // eventArgs.Speaker
    // The original text with no transcribed.
    // eventArgs.SpokenText
    // language identifier for the speaker.
    // eventArgs.SpokenLanguage
    // Timestamp denoting the time when the corresponding speech was made.
    // eventArgs.Timestamp
    // CaptionsResultKind is Partial if text contains partially spoken sentence.
    // It is set to Final once the sentence has been completely transcribed.
    // eventArgs.ResultKind
}

新增接聽程式以接收作用中口語語言已變更狀態

communicationCaptions.ActiveSpokenLanguageChanged += OnIsActiveSpokenLanguageChanged;

private void OnIsActiveSpokenLanguageChanged(object sender, PropertyChangedEventArgs args)
{
    // communicationCaptions.ActiveSpokenLanguage
}

啟動字幕

設定所有接聽程式後，您現在可以開始新增字幕。


private async void StartCaptions()
{
    var options = new StartCaptionsOptions
    {
        SpokenLanguage = "en-us"
    };
    try
    {
        await communicationCaptions.StartCaptionsAsync(options);
    }
    catch (Exception ex)
    {
    }
}

停止字幕

private async void StopCaptions()
{
    try
    {
        await communicationCaptions.StopCaptionsAsync();
    }
    catch (Exception ex)
    {
    }
}

移除字幕接收的接聽程式

communicationCaptions.CaptionsReceived -= OnCaptionsReceived;

口語語言支援

取得支援的口語語言清單

取得支援的口語語言清單，以便使用者在啟用隱藏式輔助字幕時從中選取。

// bcp 47 formatted language code
IReadOnlyList<string> sLanguages = communicationCaptions.SupportedSpokenLanguages;```

### Set spoken language 
When the user selects the spoken language, your app can set the spoken language that it expects captions to be generated from. 

``` cs 
public async void SetSpokenLanguage()
{
    try
    {
        await communicationCaptions.SetSpokenLanguageAsync("en-us");
    }
    catch (Exception ex)
    {
    }
}

清理

在這裡深入了解清除資源。

必要條件

包含使用中訂用帳戶的 Azure 帳戶。如需詳細資料，請參閱建立免費帳戶。
Azure 通訊服務資源。請參閱建立 Azure 通訊服務資源。儲存此資源的連接字串。
具有語音和視訊通話的應用程式，請參閱我們的語音和視訊通話快速入門。

注意

請注意，您必須具有語音通話應用程式，才能使用 Azure 通訊服務通話 SDK 來存取本指南中所述的隱藏式輔助字幕功能。

模型

名稱	描述
CaptionsCallFeature	適用於字幕呼叫功能的 API
CommunicationCaptions	通訊輔助字幕的 API
StartCaptionOptions	口語語言等隱藏式輔助字幕選項
CommunicationCaptionsListener	CommunicationCaptions addOnCaptionsReceivedListener 的接聽程式
CommunicationCaptionsReceivedEvent	針對每個 CommunicationCaptionsListener 事件接收的數據物件

取得隱藏式輔助字幕功能

您需要取得 Captions 物件並轉換，才能使用 Captions 特定功能。

CaptionsCallFeature captionsCallFeature = call.feature(Features.CAPTIONS);
captionsCallFeature.getCaptions().whenComplete(
    ((captions, throwable) -> {
        if (throwable == null) {
            CallCaptions callCaptions = captions;
            if (captions.getCaptionsType() == CaptionsType.COMMUNICATION_CAPTIONS) {
            // communication captions
            CommunicationCaptions communicationCaptions = (CommunicationCaptions) captions;
            }
        } else {
        // get captions failed
        // throwable is the exception/cause
        }
    }));

新增接聽程式以接收字幕已啟用/已停用狀態

public void addOnIsCaptionsEnabledChangedListener() {
    communicationCaptions.addOnCaptionsEnabledChangedListener( (PropertyChangedEvent args) -> {
        if(communicationCaptions.isEnabled()) {
            // captions enabled
        }
    });
}

新增接聽程式以接收已變更的標題類型

當標題類型在CommunicationCaptionsTeamsCaptions邀請Microsoft 365位使用者到僅限 ACS 的通話時，將會觸發此事件。

public void addOnIsCaptionsTypeChangedListener() {
    captionsCallFeature.addOnActiveCaptionsTypeChangedListener( (PropertyChangedEvent args) -> {
        if(communicationCaptions.isEnabled()) {
            // captionsCallFeature.getCaptions();
        }
    });
}

新增所接收字幕資料的接聽程式

CommunicationCaptionsListener captionsListener = (CommunicationCaptionsReceivedEvent args) -> {
  // Information about the speaker.
  // CallerInfo participantInfo = args.getSpeaker();
  // The original text with no transcribed.
  // args.getSpokenText();
  // language identifier for the speaker.
  // args.getSpokenLanguage();
  // Timestamp denoting the time when the corresponding speech was made.
  // args.getTimestamp();
  // CaptionsResultType is Partial if text contains partially spoken sentence.
  // It is set to Final once the sentence has been completely transcribed.
  // args.getResultType() == CaptionsResultType.FINAL;
}; 
public void addOnCaptionsReceivedListener() {
  communicationCaptions.addOnCaptionsReceivedListener(captionsListener); 
}

新增接聽程式以接收作用中口語語言已變更狀態

public void addOnActiveSpokenLanguageChangedListener() {
    communicationCaptions.addOnActiveSpokenLanguageChangedListener( (PropertyChangedEvent args) -> {
       // communicationCaptions.getActiveSpokenLanguage()
    });
}

啟動字幕

設定所有接聽程式後，您現在可以開始新增字幕。

public void startCaptions() {
    StartCaptionsOptions startCaptionsOptions = new StartCaptionsOptions();
    startCaptionsOptions.setSpokenLanguage("en-us");
    communicationCaptions.startCaptions(startCaptionsOptions).whenComplete((result, error) -> {
        if (error != null) {
        }
    });
}

停止字幕

public void stopCaptions() {
    communicationCaptions.stopCaptions().whenComplete((result, error) -> {
        if (error != null) {
        }
    });
}

移除字幕接收的接聽程式

public void removeOnCaptionsReceivedListener() {
    communicationCaptions.removeOnCaptionsReceivedListener(captionsListener);
}

口語語言支援

取得支援的口語語言清單

取得支援的口語語言清單，以便使用者在啟用隱藏式輔助字幕時從中選取。

// bcp 47 formatted language code
communicationCaptions.getSupportedSpokenLanguages();

設定口語語言

當使用者選取口語語言時，您的應用程式可以設定其預期要用來產生字幕的口語語言。

public void setSpokenLanguage() {
    communicationCaptions.setSpokenLanguage("en-us").whenComplete((result, error) -> {
        if (error != null) {
        }
    });
}

清理

在這裡深入了解清除資源。

必要條件

包含使用中訂用帳戶的 Azure 帳戶。如需詳細資料，請參閱建立免費帳戶。
Azure 通訊服務資源。請參閱建立 Azure 通訊服務資源。儲存此資源的連接字串。
具有語音和視訊通話的應用程式，請參閱我們的語音和視訊通話快速入門。

注意

請注意，您必須具有語音通話應用程式，才能使用 Azure 通訊服務通話 SDK 來存取本指南中所述的隱藏式輔助字幕功能。

模型

名稱	描述
CaptionsCallFeature	適用於字幕呼叫功能的 API
CommunicationCaptions	通訊輔助字幕的 API
StartCaptionOptions	口語語言等隱藏式輔助字幕選項
CommunicationCaptionsDelegate	通訊輔助字幕的委派
CommunicationCaptionsReceivedEventArgs	針對每個接收的通訊標題所接收的數據物件

取得隱藏式輔助字幕功能

您需要取得 Captions 物件並轉換，才能使用 Captions 特定功能。

if let call = self.call {
    @State var captionsCallFeature = call.feature(Features.captions)
    captionsCallFeature.getCaptions{(value, error) in
        if let error = error {
            // failed to get captions
        } else {
            if (value?.type == CaptionsType.communicationCaptions) {
                // communication captions
                @State var communicationCaptions = value as? CommunicationCaptions
            }
        }
    }
}

新增接聽程式以接收已啟用/停用的輔助字幕、輸入、口語語言、標題語言狀態已變更，以及接收的數據

當標題類型從 CommunicationCaptions 變更為 TeamsCaptions 時，邀請 Microsoft 365 位使用者到僅限 ACS 的呼叫時，就會觸發此事件didChangeActiveCaptionsType。

extension CallObserver: CommunicationCaptionsDelegate {
    // listener for receive captions enabled/disabled status
    public func communicationCaptions(_ communicationCaptions: CommunicationCaptions, didChangeCaptionsEnabledState args: PropertyChangedEventArgs) {
        // communicationCaptions.isEnabled
    }
    
    // listener for active spoken language state change
    public func communicationCaptions(_ communicationCaptions: CommunicationCaptions, didChangeActiveSpokenLanguageState args: PropertyChangedEventArgs) {
        // communicationCaptions.activeSpokenLanguage
    }
    
    // listener for captions data received
    public func communicationCaptions(_ communicationCaptions: CommunicationCaptions, didReceiveCaptions:CommunicationCaptionsReceivedEventArgs) {
            // Information about the speaker.
            // didReceiveCaptions.speaker
            // The original text with no transcribed.
            // didReceiveCaptions.spokenText
            // language identifier for the speaker.
            // didReceiveCaptions.spokenLanguage
            // Timestamp denoting the time when the corresponding speech was made.
            // didReceiveCaptions.timestamp
            // CaptionsResultType is Partial if text contains partially spoken sentence.
            // It is set to Final once the sentence has been completely transcribed.
            // didReceiveCaptions.resultType
    }
}

communicationCaptions.delegate = self.callObserver

extension CallObserver: CaptionsCallFeatureDelegate {
    // captions type changed
    public func captionsCallFeature(_ captionsCallFeature: CaptionsCallFeature, didChangeActiveCaptionsType args: PropertyChangedEventArgs) {
        // captionsCallFeature.getCaptions to get captions
    }
}

captionsCallFeature.delegate = self.callObserver

啟動字幕

設定所有接聽程式後，您現在可以開始新增字幕。

func startCaptions() {
    guard let communicationCaptions = communicationCaptions else {
        return
    }
    let startCaptionsOptions = StartCaptionsOptions()
    startCaptionsOptions.spokenLanguage = "en-us"
    communicationCaptions.startCaptions(startCaptionsOptions: startCaptionsOptions, completionHandler: { (error) in
        if error != nil {
            
        }
    })
}

停止字幕

func stopCaptions() {
    communicationCaptions.stopCaptions(completionHandler: { (error) in
        if error != nil {
            
        }
    })
}

移除字幕接收的接聽程式

communicationCaptions?.delegate = nil

口語語言支援

取得支援的口語語言清單

取得支援的口語語言清單，以便使用者在啟用隱藏式輔助字幕時從中選取。

// bcp 47 formatted language code
let spokenLanguage : String = "en-us"
for language in communicationCaptions?.supportedSpokenLanguages ?? [] {
    // choose required language
    spokenLanguage = language
}

設定口語語言

當使用者選取口語語言時，您的應用程式可以設定其預期要用來產生字幕的口語語言。

func setSpokenLanguage() {
    guard let communicationCaptions = self.communicationCaptions else {
        return
    }

    communicationCaptions.set(spokenLanguage: spokenLanguage, completionHandler: { (error) in
        if let error = error {
        }
    })
}

清理

在這裡深入了解清除資源。

清除資源

如果您想要清除並移除通訊服務訂用帳戶，您可以刪除資源或資源群組。刪除資源群組也會刪除與其相關聯的任何其他資源。深入了解如何清除資源。

下一步

如需詳細資訊，請參閱下列文章：

深入了解如何在 Teams Interop 案例中使用字幕。
查看我們的 Web 通話範例
了解通話 SDK 功能
深入了解通話的運作方式

共用方式為

快速入門: 將字幕新增至您的通話應用程式

必要條件

模型

取得隱藏式輔助字幕功能

取得 captions 物件

訂閱接聽程式

新增接聽程式以接收字幕作用中/非作用中狀態

新增所接收字幕資料的接聽程式

新增接聽程式以接收口語語言已變更狀態

啟動字幕

停止字幕

取消訂閱接聽程式

口語語言支援

取得支援的口語語言清單

設定口語語言

新增接聽程式以接收標題種類已變更狀態

必要條件

模型

取得隱藏式輔助字幕功能

訂閱接聽程式

新增接聽程式以接收字幕已啟用/已停用狀態

新增接聽程式以接收已變更的標題類型

新增所接收字幕資料的接聽程式

新增接聽程式以接收作用中口語語言已變更狀態

啟動字幕

停止字幕

移除字幕接收的接聽程式

口語語言支援

取得支援的口語語言清單

清理

必要條件

模型

取得隱藏式輔助字幕功能

訂閱接聽程式

新增接聽程式以接收字幕已啟用/已停用狀態

新增接聽程式以接收已變更的標題類型

新增所接收字幕資料的接聽程式

新增接聽程式以接收作用中口語語言已變更狀態

啟動字幕

停止字幕

移除字幕接收的接聽程式

口語語言支援

取得支援的口語語言清單

設定口語語言

清理

必要條件

模型

取得隱藏式輔助字幕功能

訂閱接聽程式

新增接聽程式以接收已啟用/停用的輔助字幕、輸入、口語語言、標題語言狀態已變更，以及接收的數據

啟動字幕

停止字幕

移除字幕接收的接聽程式

口語語言支援

取得支援的口語語言清單

設定口語語言

清理

清除資源

下一步

意見反應

其他資源