共用方式為


啟用隱藏式輔助字幕以達到 Teams 互通性

了解在使用者可能參與 Azure 通訊服務使用者與 Teams 用戶端使用者之間會議,或使用者透過其 Microsoft 365 身分識別使用 Azure 通訊服務通話 SDK 的 Teams 互通性案例中,如何讓使用者啟用隱藏式輔助字幕。

必要條件

注意

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

模型

名稱 描述
CaptionsCallFeature 適用於字幕呼叫功能的 API
TeamsCaptions 適用於 Teams 字幕的 API
StartCaptionOptions 口語語言等隱藏式輔助字幕選項
TeamsCaptionsReceivedEventArgs 針對每個已接收 Teams 字幕的事件接收的資料物件

取得隱藏式輔助字幕功能

外部身分識別使用者和 Microsoft 365 使用者

如果您要建置可讓 Azure 通訊服務使用者加入 Teams 會議的應用程式

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

訂閱接聽程式

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

teamsCaptions.CaptionsEnabledChanged += OnIsCaptionsEnabledChanged;

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

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

teamsCaptions.CaptionsReceived += OnCaptionsReceived;

private void OnCaptionsReceived(object sender, TeamsCaptionsReceivedEventArgs eventArgs)
{
    // Information about the speaker.
    // eventArgs.Speaker
    // The original text with no transcribed.
    // eventArgs.SpokenText
    // language identifier for the captions text.
    // eventArgs.CaptionLanguage
    // language identifier for the speaker.
    // eventArgs.SpokenLanguage
    // The transcribed text.
    // eventArgs.CaptionText
    // 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
}

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

teamsCaptions.ActiveSpokenLanguageChanged += OnIsActiveSpokenLanguageChanged;

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

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

teamsCaptions.ActiveCaptionLanguageChanged += OnIsActiveCaptionLanguageChanged;

private void OnIsActiveCaptionLanguageChanged(object sender, PropertyChangedEventArgs args)
{
    // teamsCaptions.ActiveCaptionLanguage
}

啟動字幕

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


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

停止字幕

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

移除字幕接收的接聽程式

teamsCaptions.CaptionsReceived -= OnCaptionsReceived;

口語語言支援

取得支援的口語語言清單

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

// bcp 47 formatted language code
IReadOnlyList<string> sLanguages = teamsCaptions.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 teamsCaptions.SetSpokenLanguageAsync("en-us");
    }
    catch (Exception ex)
    {
    }
}

字幕語言支援

取得支援的字幕語言

如果您的組織擁有有效的 Teams 進階授權,則只要會議的召集人具有 Teams 進階授權,Azure 通訊服務使用者就可以啟用翻譯字幕。 至於具有 Microsoft 365 身分識別的使用者,如果會議召集人沒有 Teams 進階授權,則會針對自己的使用者帳戶進行此檢查。

// ISO 639-1 formatted language code
IReadOnlyList<string> cLanguages = teamsCaptions.SupportedCaptionLanguages;

設定字幕語言

public async void SetCaptionLanguage()
{
    try
    {
        await teamsCaptions.SetCaptionLanguageAsync("en");
    }
    catch (Exception ex)
    {
    }
}

必要條件

注意

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

模型

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

取得隱藏式輔助字幕功能

外部身分識別使用者

如果您要建置可讓 Azure 通訊服務使用者加入 Teams 會議的應用程式。

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

Microsoft 365 使用者

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

取得 Teams 字幕物件

您需要取得並轉換 Teams 字幕物件,才能利用 Teams 字幕特定功能

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

訂閱接聽程式

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

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

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

處理傳回的 TeamsCaptionsInfo 資料物件。

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

let currentCaptionLanguage : string;
const captionsReceivedHandler : TeamsCaptionsHandler = (data: TeamsCaptionsInfo) => { 
    /** USER CODE HERE - E.G. RENDER TO DOM 
     * data.captionLanguage
     * data.captionText
     * data.resultType
     * data.speaker
     * data.spokenText
     * data.timeStamp
    */
   // Example code:
   // Create a dom element, i.e. div, with id "captionArea" before proceeding with the sample code
    if (!this._currentCaptionLanguage || this._currentCaptionLanguage === data.captionLanguage) {
        let mri: string;
        switch (data.speaker.identifier.kind) {
            case 'communicationUser': { mri = data.speaker.identifier.communicationUserId; break; }
            case 'microsoftTeamsUser': { mri = data.speaker.identifier.microsoftTeamsUserId; 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.captionText ?? 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(newClassName);

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

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

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

const spokenLanguageChangedHandler = () => {
    if (teamsCaptions.activeSpokenLanguage !== currentSpokenLanguage) {
        /* USER CODE HERE - E.G. RENDER TO DOM */
    }
}
teamsCaptions.on('SpokenLanguageChanged', spokenLanguageChangedHandler)

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

const captionLanguageChangedHandler = () => {
    if (teamsCaptions.activeCaptionLanguage !== currentCaptionLanguage) {
        /* USER CODE HERE - E.G. RENDER TO DOM */
    }
}
teamsCaptions.on('CaptionLanguageChanged', captionLanguageChangedHandler)

啟動字幕

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

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

停止字幕

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

取消訂閱接聽程式

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

口語語言支援

取得支援的口語語言清單

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

const spokenLanguages = teamsCaptions.supportedSpokenLanguages; 

設定口語語言

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

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

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

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

字幕語言支援

取得支援的字幕語言清單

如果您的組織有作用中的 Teams 進階授權,您可讓使用者使用 Teams 字幕所提供的翻譯字幕。 至於具有 Microsoft 365 身分識別的使用者,如果會議召集人沒有作用中的 Teams 進階授權,則會針對 Microsoft 365 使用者帳戶進行字幕語言檢查。

此屬性會傳回 ISO 639-1 標準中雙字母語言代碼的陣列。

const captionLanguages = teamsCaptions.supportedCaptionLanguages;

設定字幕語言

// ISO 639-1 formatted language code
const language = 'en'; 

// Altneratively, pass a value from the supported caption languages array
const language = captionLanguages[0];
try {
    teamsCaptions.setCaptionLanguage(language);
} catch (e) {
    /* USER ERROR HANDLING CODE HERE */
}

必要條件

注意

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

模型

名稱 描述
CaptionsCallFeature 適用於字幕呼叫功能的 API
TeamsCaptions 適用於 Teams 字幕的 API
StartCaptionOptions 口語語言等隱藏式輔助字幕選項
TeamsCaptionsListener TeamsCaptions addOnCaptionsReceivedListener 的接聽程式
TeamsCaptionsReceivedEvent 針對每個 TeamsCaptionsListener 事件收到的資料物件

取得隱藏式輔助字幕功能

外部身分識別使用者和 Microsoft 365 使用者

如果您要建置可讓使用者加入 Teams 會議的應用程式

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

訂閱接聽程式

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

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

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

TeamsCaptionsListener captionsListener = (TeamsCaptionsReceivedEvent args) -> {
  // Information about the speaker.
  // CallerInfo participantInfo = args.getSpeaker();
  // The original text with no transcribed.
  // args.getSpokenText();
  // language identifier for the captions text.
  // args.getCaptionLanguage();
  // language identifier for the speaker.
  // args.getSpokenLanguage();
  // The transcribed text.
  // args.getCaptionText();
  // 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() {
  teamsCaptions.addOnCaptionsReceivedListener(captionsListener); 
}

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

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

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

public void addOnActiveCaptionLanguageChangedListener() {
    teamsCaptions.addOnActiveCaptionLanguageChangedListener( (PropertyChangedEvent args) -> {
       // teamsCaptions.getActiveCaptionLanguage()
    });
}

啟動字幕

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

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

停止字幕

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

移除字幕接收的接聽程式

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

口語語言支援

取得支援的口語語言清單

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

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

設定口語語言

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

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

字幕語言支援

取得支援的字幕語言

如果您的組織擁有有效的 Teams 進階授權,則只要會議的召集人具有 Teams 進階授權,Azure 通訊服務使用者就可以啟用翻譯字幕。 至於具有 Microsoft 365 身分識別的使用者,如果會議召集人沒有 Teams 進階授權,則會針對自己的使用者帳戶進行此檢查。

// ISO 639-1 formatted language code
teamsCaptions.getSupportedCaptionLanguages();

設定字幕語言

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

必要條件

注意

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

模型

名稱 描述
CaptionsCallFeature 適用於字幕呼叫功能的 API
TeamsCaptions 適用於 Teams 字幕的 API
StartCaptionOptions 口語語言等隱藏式輔助字幕選項
TeamsCaptionsDelegate Teams 字幕的委派
TeamsCaptionsReceivedEventArgs 針對每個已接收 Teams 字幕的事件接收的資料物件

取得隱藏式輔助字幕功能

外部身分識別使用者和 Microsoft 365 使用者

如果您要建置可讓 Azure 通訊服務使用者加入 Teams 會議的應用程式

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.teamsCaptions) {
                // teams captions
                @State var teamsCaptions = value as? TeamsCaptions
            }
        }
    }
}

訂閱接聽程式

新增接聽程式以接收字幕已啟用/已停用、口語語言、變更的字幕語言狀態,以及接收的資料

extension CallObserver: TeamsCaptionsDelegate {
    // listener for receive captions enabled/disabled status
    public func teamsCaptions(_ teamsCaptions: TeamsCaptions, didChangeCaptionsEnabledState args: PropertyChangedEventArgs) {
        // teamsCaptions.isEnabled
    }
    
    // listener for active spoken language state change
    public func teamsCaptions(_ teamsCaptions: TeamsCaptions, didChangeActiveSpokenLanguageState args: PropertyChangedEventArgs) {
        // teamsCaptions.activeSpokenLanguage
    }
    
    // listener for active caption language state change
    public func teamsCaptions(_ teamsCaptions: TeamsCaptions, didChangeActiveCaptionLanguageState args: PropertyChangedEventArgs) {
        // teamsCaptions.activeCaptionLanguage
    }
    
    // listener for captions data received
    public func teamsCaptions(_ teamsCaptions: TeamsCaptions, didReceiveCaptions:TeamsCaptionsReceivedEventArgs) {
            // Information about the speaker.
            // didReceiveCaptions.speaker
            // The original text with no transcribed.
            // didReceiveCaptions.spokenText
            // language identifier for the captions text.
            // didReceiveCaptions.captionLanguage
            // language identifier for the speaker.
            // didReceiveCaptions.spokenLanguage
            // The transcribed text.
            // didReceiveCaptions.captionText
            // 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
    }
}

teamsCaptions.delegate = self.callObserver

啟動字幕

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

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

停止字幕

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

移除字幕接收的接聽程式

teamsCaptions?.delegate = nil

口語語言支援

取得支援的口語語言清單

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

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

設定口語語言

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

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

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

字幕語言支援

取得支援的字幕語言

如果您的組織擁有有效的 Teams 進階授權,則只要會議的召集人具有 Teams 進階授權,Azure 通訊服務使用者就可以啟用翻譯字幕。 至於具有 Microsoft 365 身分識別的使用者,如果會議召集人沒有 Teams 進階授權,則會針對自己的使用者帳戶進行此檢查。

// ISO 639-1 formatted language code
let captionLanguage : String = "en"
for language in teamsCaptions?.supportedCaptionLanguages ?? [] {
    // choose required language
    captionLanguage = language
}

設定字幕語言

func setCaptionLanguage() {
    guard let teamsCaptions = self.teamsCaptions else {
        return
    }

    teamsCaptions.set(captionLanguage: captionLanguage, completionHandler: { (error) in
        if let error = error {
        }
    })
}

清除資源

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

下一步

如需詳細資訊,請參閱下列文章: