音声ストリーミング機能

注意

この機能を利用する場合は事前にサポートまでご連絡ください

警告

音声ストリーミング機能は実験的機能のため、正式版では仕様が変更される可能性があります

概要

Sora に WebRTC で送られてきた音声を接続ごとに HTTP/2 で外部へ出力し、解析結果をクライアントへプッシュで通知する機能です。

仕様

マルチストリームでのみ利用可能

音声ストリーミング機能はマルチストリームを有効にした状態でのみ利用できます。

言語コードの指定

音声ストリーミングを利用する場合、 言語コードを指定する必要があります。

シグナリング接続時、または認証成功時の払い出しで {"audio_streaming_language_code": "ja-JP"} のように指定してください。 指定するのは 文字列であればなんでもかまいません 。Sora 自体は言語コードには関与しません。あくまでただの文字列として扱います。

注意

言語コードが指定されていない接続は、音声ストリーミングが開始している場合でも音声ストリーミングを行いません。 言語コードは音声を解析するにあたり必要になるためこのような仕様になっています。

セッションウェブフック経由での開始

音声ストリーミングはセッション単位で開始、終了します。

セッション開始時から音声ストリーミングを開始したい場合、 セッションウェブフックの戻り値に {"audio_streaming": true} を指定することで音声ストリーミングが開始します。

そのセッションに参加してきた言語コードが指定されているクライアントはすべて音声ストリーミングが行われます。

セッション終了時の音声ストリーミング終了

チャネルのセッションが終了したタイミングで音声ストリーミングは終了します。

API 経由での開始

セッションの途中で音声ストリーミングを開始する場合は StartAudioStreaming API を利用する必要があります。

API 経由での終了

セッションの途中で音声ストリーミングを終了する場合は StopAudioStreaming API を利用する必要があります。

1 コネクション 1 HTTP/2 コネクション

音声ストリーミングが開始している状態でそのチャネルに新規クライアントが参加すると、 audio_streaming_url 宛てに新しく HTTP/2 コネクションが張られ、 クライアントから送られてきた Opus のバイナリデータがそのまま送られます。

HTTP/2 コネクションを張る際のヘッダーには以下の値が入ります。

  • sora-channel-id

    • クライアントのチャネル ID

  • sora-connection-id

    • クライアントのコネクション ID

  • sora-audio-streaming-language-code

    • クライアントの言語コード

プッシュ通知経由での戻り値の通知

シグナリングのプッシュ通知経由で外部サーバーからの戻り値を通知します。

{
    "type": "push",
    "data": {
        "type": "audio_streaming_result",
        "connection_id": "<connection_id>",
        "result": "レスポンスがそのまま含まれる"
    }
}

設定

audio_streaming_url

デフォルト:

指定なし

音声ストリーミングゲートウェイの URL を指定してください。 音声ストリーミングゲートウェイは HTTP/2 に対応している必要があります。

詳細は audio_streaming_url をご確認ください。

default_audio_streaming_result_push

デフォルト:

true

音声ストリーミングゲートウェイからのレスポンスをシグナリングプッシュ通知で送ることをデフォルトで行うかを指定してください。

詳細は default_audio_streaming_result_push をご確認ください。

default_audio_streaming_language_code

デフォルト:

指定なし

音声ストリーミングゲートウェイ接続時に HTTP ヘッダー sora-audio-steraming-language-code にデフォルトで含める文字列を指定してください。

詳細は default_audio_streaming_language_code をご確認ください。

audio_streaming_tls_fullchain_file

デフォルト:

指定なし

音声ストリーミングゲートウェイとの通信に HTTPS で mTLS を利用するための設定で、 中間証明書を含む PEM 形式 のクライアント証明書のパスを設定して下さい。

詳細は audio_streaming_tls_fullchain_file をご確認ください。

audio_streaming_tls_privkey_file

デフォルト:

指定なし

音声ストリーミングゲートウェイとの通信に HTTPS で mTLS を利用するための設定で、 PEM 形式のクライアント証明書秘密鍵のパスを設定して下さい。

詳細は audio_streaming_tls_privkey_file をご確認ください。

audio_streaming_tls_verify_cacert_file

デフォルト:

指定なし

音声ストリーミングゲートウェイとの通信に HTTPS を利用した際、 サーバー証明書のチェックを行う PEM 形式の CA ファイルのパスを設定して下さい。

詳細は audio_streaming_tls_verify_cacert_file をご確認ください。

API

StartAudioStreaming API

セッションが存在し、音声ストリーミングが開始していないチャネルに対して音声ストリーミングを開始します。

詳細は StartAudioStreaming をご確認ください。

StopAudioStreaming API

セッションが存在し、音声ストリーミングが開始しているチャネルに対して音声ストリーミングを停止します。

注釈

音声ストリーミングを終了すると、すべて接続の購読状態は初期化され、デフォルトの値に戻ります。

詳細は StopAudioStreaming をご確認ください。

SubscribeAudioStreamingResultPush API

指定した接続が音声ストリーミングサーバーからの戻り値のプッシュ通知を購読するよう設定します。

詳細は SubscribeAudioStreamingResultPush をご確認ください。

注釈

デフォルトの値は sora.confdefault_audio_streaming_result_push が適用されます。

UnsubscribeAudioStreamingResultPush API

指定した接続が音声ストリーミングサーバーからの戻り値のプッシュ通知を購読しないよう設定します。

注釈

デフォルトの値は sora.confdefault_audio_streaming_result_push が適用されます。

詳細は UnsubscribeAudioStreamingResultPush をご確認ください。

Audio Streaming Gateway Suzu

重要

Audio Streaming Gateway Suzu は Sora サポートの対象外です

shiguredo/suzu: Audio Streaming Gateway Suzu

Sora から HTTP/2 経由で送られてくるヘッダーや Opus 音声データを、 音声からテキストに変換するサービスへを Ogg 形式にして送信し、 サービスから受信した変換結果を Sora に返すゲートウェイです。

対応サービス

シーケンス図

Suzu + AWS Transcribe

sequenceDiagram autonumber participant クライアント participant Sora participant Suzu participant AWS Transcribe クライアント->>Sora: SRTP クライアント->>Sora: SRTP クライアント->>Sora: SRTP note over クライアント, AWS Transcribe: StartAudioStreaming API 実行 クライアント->>Sora: SRTP Sora->>Suzu: Opus over HTTP/2 Suzu->>AWS Transcribe: Ogg over HTTP/2 クライアント->>Sora: SRTP Sora->>Suzu: Opus over HTTP/2 Suzu->>AWS Transcribe: Ogg over HTTP/2 クライアント->>Sora: SRTP Sora->>Suzu: Opus over HTTP/2 Suzu->>AWS Transcribe: Ogg over HTTP/2 AWS Transcribe->>Suzu: JSON over HTTP/2 Suzu->>Sora: JSON over HTTP/2 Sora->>クライアント: シグナリングプッシュ通知
© Copyright 2023, Shiguredo Inc Created using Sphinx 5.3.0