クイックスタート: 通話アプリにクローズドキャプションを追加する

[アーティクル]
06/13/2024

前提条件

アクティブなサブスクリプションを持つ Azure アカウント。詳細については、アカウントの無料作成に関するページを参照してください。
Azure Communication Services リソース。 Azure Communication Services リソースの作成に関する記事を参照してください。このリソースの接続文字列を保存します。
音声通話とビデオ通話を使用するアプリについては、Microsoft の音声とビデオでの通話に関するクイックスタートを参照してください。

Note

このガイドで説明されているクローズドキャプション機能にアクセスするには、Azure Communication Services の Calling SDK を使用する音声通話アプリが必要であることに注意してください。

モデル

名前	説明
CaptionsCallFeature	キャプション用の API
CaptionsCommon	キャプションの基本クラス
StartCaptionOptions	音声言語などのクローズドキャプションのオプション
CaptionsHandler	CaptionsReceivedEventType イベントを処理するコールバック定義
CaptionsInfo	CaptionsReceivedEventType イベントごとに受信したデータ構造

クローズドキャプション機能を取得する

let captionsCallFeature: SDK.CaptionsCallFeature = call.feature(SDK.Features.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 ユーザーが通話に参加した場合、または通話が相互運用機能呼び出しの種類に変更された場合に、キャプションの種類が Captions から TeamsCaptions に変更される場合があります。 Captions エクスペリエンスを引き続き利用するには、Teams Captions リスナーへの再スクライブが必要です。 TeamsCaptions が通話で利用されるようになると、TeamsCaptions タイプは Captions タイプに切り替えたり、戻したりすることはできません。

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

前提条件

アクティブなサブスクリプションを持つ Azure アカウント。詳細については、アカウントの無料作成に関するページを参照してください。
Azure Communication Services リソース。 Azure Communication Services リソースの作成に関する記事を参照してください。このリソースの接続文字列を保存します。
音声通話とビデオ通話を使用するアプリについては、Microsoft の音声とビデオでの通話に関するクイックスタートを参照してください。

Note

モデル

名前	説明
CaptionsCallFeature	キャプション呼び出し機能に使用する API
CommunicationCaptions	通信キャプション用 API
StartCaptionOptions	音声言語などのクローズドキャプションのオプション
CommunicationCaptionsReceivedEventArgs	コミュニケーションキャプション受信イベントごとに受信したデータオブジェクト

クローズドキャプション機能を取得する

キャプション固有の機能を利用するには、キャプションオブジェクトを取得してキャストする必要があります。

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)
    {
    }
}

変更されたキャプションの種類を受け取るリスナーを追加する

このイベントは、Microsoft 365 ユーザーを ACS のみの呼び出しに招待するときにキャプションの種類が CommunicationCaptions から TeamsCaptions に変更されたときにトリガーされます。

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 Communication Services リソース。 Azure Communication Services リソースの作成に関する記事を参照してください。このリソースの接続文字列を保存します。
音声通話とビデオ通話を使用するアプリについては、Microsoft の音声とビデオでの通話に関するクイックスタートを参照してください。

Note

モデル

名前	説明
CaptionsCallFeature	キャプション呼び出し機能に使用する API
CommunicationCaptions	通信キャプション用 API
StartCaptionOptions	音声言語などのクローズドキャプションのオプション
CommunicationCaptionsListener	CommunicationCaptions addOnCaptionsReceivedListener のリスナー
CommunicationCaptionsReceivedEvent	CommunicationCaptionsListener イベントごとに受信したデータオブジェクト

クローズドキャプション機能を取得する

キャプション固有の機能を利用するには、キャプションオブジェクトを取得してキャストする必要があります。

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
        }
    });
}

変更されたキャプションの種類を受け取るリスナーを追加する

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 Communication Services リソース。 Azure Communication Services リソースの作成に関する記事を参照してください。このリソースの接続文字列を保存します。
音声通話とビデオ通話を使用するアプリについては、Microsoft の音声とビデオでの通話に関するクイックスタートを参照してください。

Note

モデル

名前	説明
CaptionsCallFeature	キャプション呼び出し機能に使用する API
CommunicationCaptions	通信キャプション用 API
StartCaptionOptions	音声言語などのクローズドキャプションのオプション
CommunicationCaptionsDelegate	コミュニケーションキャプションの委任
CommunicationCaptionsReceivedEventArgs	コミュニケーションキャプション受信イベントごとに受信したデータオブジェクト

クローズドキャプション機能を取得する

キャプション固有の機能を利用するには、キャプションオブジェクトを取得してキャストする必要があります。

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
            }
        }
    }
}

キャプションの有効化/無効化、種類、音声言語、キャプション言語の状態の変更、受信データを受信するリスナーを追加する

このイベント didChangeActiveCaptionsType は、Microsoft 365 ユーザーを ACS のみの呼び出しに招待するときにキャプションの種類が CommunicationCaptions から TeamsCaptions に変更されたときにトリガーされます。

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 {
        }
    })
}

クリーンアップ

リソースのクリーンアップの詳細についてはこちらを参照してください。

リソースをクリーンアップする

Communication Services サブスクリプションをクリーンアップして解除する場合は、リソースまたはリソースグループを削除できます。リソースグループを削除すると、それに関連付けられている他のリソースも削除されます。詳細については、リソースのクリーンアップに関する記事を参照してください。

次の手順

詳細については、次の記事を参照してください。

Teams の相互運用シナリオでのクローズドキャプションの使用の詳細について確認する。
Microsoft の Web 通話のサンプルを確認する
Calling SDK の機能について確認する
通話のしくみの詳細について確認する

次の方法で共有

クイック スタート: 通話アプリにクローズド キャプションを追加する

前提条件

モデル

クローズド キャプション機能を取得する

キャプション オブジェクトを取得する

リスナーをサブスクライブする

有効/無効状態のキャプションを受け取るリスナーを追加する

受信したキャプション データのリスナーを追加する

音声言語の変更状態を受け取るリスナーを追加する

キャプションを開始する

キャプションを停止する

リスナーの登録を解除する

音声言語のサポート

サポートされている音声言語のリストを取得する

音声言語を設定する

キャプションの種類が変更された状態を受け取るリスナーを追加する

前提条件

モデル

クローズド キャプション機能を取得する

リスナーをサブスクライブする

有効/無効状態のキャプションを受け取るリスナーを追加する

変更されたキャプションの種類を受け取るリスナーを追加する

受信したキャプション データのリスナーを追加する

アクティブな音声言語の変更状態を受け取るリスナーを追加する

キャプションを開始する

キャプションを停止する

キャプションを受信したリスナーを削除する

音声言語のサポート

サポートされている音声言語のリストを取得する

クリーンアップ

前提条件

モデル

クローズド キャプション機能を取得する

リスナーをサブスクライブする

有効/無効状態のキャプションを受け取るリスナーを追加する

変更されたキャプションの種類を受け取るリスナーを追加する

受信したキャプション データのリスナーを追加する

アクティブな音声言語の変更状態を受け取るリスナーを追加する

キャプションを開始する

キャプションを停止する

キャプションを受信したリスナーを削除する

音声言語のサポート

サポートされている音声言語のリストを取得する

音声言語を設定する

クリーンアップ

前提条件

モデル

クローズド キャプション機能を取得する

リスナーをサブスクライブする

キャプションの有効化/無効化、種類、音声言語、キャプション言語の状態の変更、受信データを受信するリスナーを追加する

キャプションを開始する

キャプションを停止する

キャプションを受信したリスナーを削除する

音声言語のサポート

サポートされている音声言語のリストを取得する

音声言語を設定する

クリーンアップ

リソースをクリーンアップする

次の手順

フィードバック

その他のリソース

クイックスタート: 通話アプリにクローズドキャプションを追加する

クローズドキャプション機能を取得する

キャプションオブジェクトを取得する

受信したキャプションデータのリスナーを追加する

クローズドキャプション機能を取得する

受信したキャプションデータのリスナーを追加する

クローズドキャプション機能を取得する

受信したキャプションデータのリスナーを追加する

クローズドキャプション機能を取得する