音声ストリーミング機能¶
注意
この機能を利用する場合は事前にサポートまでご連絡ください
警告
音声ストリーミング機能は実験的機能のため、正式版では仕様が変更される可能性があります
概要¶
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.conf の default_audio_streaming_result_push が適用されます。
UnsubscribeAudioStreamingResultPush API¶
指定した接続が音声ストリーミングサーバーからの戻り値のプッシュ通知を購読しないよう設定します。
注釈
デフォルトの値は sora.conf の default_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 に返すゲートウェイです。