音声ストリーミング機能

警告

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

概要

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

仕様

言語コードの指定

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

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

言語コードが指定されていない接続は、音声ストリーミングが開始している場合でも音声ストリーミングを行いません。

注釈

言語コードは音声を解析するにあたり必要になるためこのような仕様になっています。

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

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

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

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

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

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

API 経由での開始

セッションの途中で音声ストリーミングを開始したり終了したりしたい場合は 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

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

  • sora-audio-codec-type

    • 未実装

    • クライアントの音声コーデックタイプ

  • sora-audio-sample-rate

    • 未実装

    • クライアントの音声サンプルレート

メッセージング経由での戻り値の通知

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

{
    "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 を利用した際、サーバー証明書のチェックを行う CA ファイルを PEM 形式で設定して下さい。

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

API

StartAudioStreaming API

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

詳細は 音声ストリーミング開始 をご確認ください。

StopAudioStreaming API

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

詳細は 音声ストリーミング終了 をご確認ください。

ListStartedAudioStreaming API

未実装

音声ストリーミングが開始しているチャネル一覧を表示します。

SubscribeAudioStreamingResultPush API

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

詳細は 音声ストリーミング結果プッシュ購読 をご確認ください。

UnsubscribeAudioStreamingResultPush API

音声ストリーミングサーバーからの戻り値のプッシュ通知を指定した接続が購読しないよう設定します。 詳細は 音声ストリーミング結果プッシュ購読解除 をご確認ください。

Audio Streaming Gateway Suzu

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

対応サービス

シーケンス図

Suzu + AWS Transcribe

blockdiag クライアント Sora Suzu AWS Transcribe SRTP SRTP SRTP SRTP Opus over HTTP/2 Ogg over HTTP/2 SRTP Opus over HTTP/2 Ogg over HTTP/2 SRTP Opus over HTTP/2 Ogg over HTTP/2 JSON over HTTP/2 Json over HTTP/2 DataChannel StartAudioStreaming API 実行
© Copyright 2022, Shiguredo Inc Created using Sphinx 5.3.0