音声ストリーミング機能¶

OBS (WHIP) 機能利用時の Opus の設定¶

OBS の Opus のビットレートがデフォルトの場合は正常に動作しない場合があります。 その場合はビットレートを 128 kbps まで下げて見てください。

IPv6 非対応¶

現時点で、音声ストリーミングは IPv6 を利用できません。

音声ストリーミングの送信単位¶

音声ストリーミングを audio_streaming_url へ送信するのは、 コネクション単位であり、セッション単位ではありません。

リトライを行う¶

• 音声ストリーミングゲートウェイへ接続ができなかった場合
• 音声ストリーミングゲートウェイへ接続時に 5xx 系のステータスコードが返された場合

リトライを行わない¶

• 接続時に 4xx 系が送られてきた場合
• 接続後に "type": "error" が送られてきた場合

音声ストリーミングゲートウェイへの接続¶

セッションウェブフックの session.created 時に払い出した、 audio_streaming, audio_streaming_auto の組み合わせごとの 配信者接続時 の音声ストリーミングゲートウェイへの接続の有無は下記の通りです。

クライアントへの解析結果の送信¶

セッションウェブフックの session.created 時に払い出した、 audio_streaming, audio_streaming_auto の組み合わせごとの subscribe しているクライアントへの解析結果の送信有無は下記の通りです。

audio-streaming.started¶

• セッションで音声ストリーミングが開始した場合に通知されます
• 自動開始/停止が有効の場合は "audio_streaming_auto": true が入ってきます
• 音声ストリーミングを開始した時間が "audio_streaming_started_timestamp" に入ってきます
• このウェブフックはかならず session.created よりも後に送信されます

{
  "data": {
    "audio_streaming_auto": false,
    "audio_streaming_started_timestamp": "2023-05-01T08:23:58.489262Z"
  },
  "id": "VWGZ8NK2C55XBCGQ54SECK7J08",
  "label": "WebRTC SFU Sora",
  "timestamp": "2023-05-01T08:24:20.757279Z",
  "type": "audio-streaming.started",
  "version": "2023.2.0",
  "max_connections": 1,
  "node_name": "sora@127.0.0.1",
  "session_id": "DYPX8R6F4D11ZEG6XCX6N8EEWM",
  "channel_id": "sora",
  "spotlight": false,
  "created_time": 1682929437,
  "total_connections": 1,
  "created_timestamp": "2023-05-01T08:23:57.274844Z"
}

audio-streaming.stopped¶

• セッションで音声ストリーミング停止した場合に通知されます
• 自動開始/停止が有効な場合は "audio_streaming_auto": true が入ってきます
• 音声ストリーミングを開始した時間が "audio_streaming_started_timestamp" に入ってきます
• 音声ストリーミングを停止した時間が "audio_streaming_stopped_timestamp" に入ってきます
• このウェブフックはかならず session.destroyed よりも前に送信されます

{
  "data": {
    "audio_streaming_auto": false,
    "audio_streaming_started_timestamp": "2023-05-01T08:23:58.489262Z",
    "audio_streaming_stopped_timestamp": "2023-05-01T08:24:20.756785Z"
  },
  "id": "VWGZ8NK2C55XBCGQ54SECK7J08",
  "label": "WebRTC SFU Sora",
  "timestamp": "2023-05-01T08:24:20.757279Z",
  "type": "audio-streaming.stopped",
  "version": "2023.2.0",
  "max_connections": 1,
  "node_name": "sora@127.0.0.1",
  "session_id": "DYPX8R6F4D11ZEG6XCX6N8EEWM",
  "channel_id": "sora",
  "spotlight": false,
  "created_time": 1682929437,
  "total_connections": 1,
  "created_timestamp": "2023-05-01T08:23:57.274844Z"
}

audio-streaming.failed¶

このウェブフックは、Sora が接続する音声ストリーミングゲートウェイが利用するサービスに不具合があったことを、Sora に伝える仕組みです。

• sora.conf の audio_streaming_max_retries が 0 では無い場合に有効になります
• sora.conf の ignore_audio_streaming_failed_webhook が false の場合にウェブフックが送られるようになります
  • true にした場合でも event_webhook.jsonl にログは出力されます

リトライが発生する場合は最大リトライ数を超えている場合に、以下の状況でウェブフックが送信されます。

• 音声ストリーミングゲートウェイに接続した際 5xx 系のエラーが返ってきた場合に送信します
• 音声ストリーミングゲートウェイに接続した際 4xx 系のエラーが返ってきた場合に送信します
• 音声ストリーミングゲートウェイから "type": "error" が返ってきた場合に送信します
• 音声ストリーミングゲートウェイへの接続確立がタイムアウト以外で失敗した場合に送信します

音声ストリーミングを再開したい場合は、再接続をしてください。

音声ストリーミングゲートウェイへの接続がタイムアウトになった場合にはウェブフックは送信されません。

{
  "data": {
    "failed_reason": "<string>"
  },
  "id": "VWGZ8NK2C55XBCGQ54SECK7J08",
  "label": "WebRTC SFU Sora",
  "timestamp": "2023-05-01T08:24:20.757279Z",
  "type": "audio-streaming.failed",
  "role": "sendrecv",
  "version": "2024.1.0",
  "node_name": "sora@127.0.0.1",
  "client_id": "B2JPGFZPMD3H973Y811MF8ZZ70",
  "connection_id": "B2JPGFZPMD3H973Y811MF8ZZ70",
  "bundle_id": "B2JPGFZPMD3H973Y811MF8ZZ70",
  "session_id": "DYPX8R6F4D11ZEG6XCX6N8EEWM",
  "channel_id": "sora",
  "simulcast": false,
  "spotlight": false,
  "log_written": true
}

audio_streaming_url¶

デフォルト:

指定なし

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

https または http から始まる URL を指定してください。

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

audio_streaming_max_retries¶

デフォルト:

0

範囲:

0..10

音声ストリーミングゲートウェイへの接続が失敗した場合の最大リトライ回数を指定してください。

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

audio_streaming_retry_interval¶

デフォルト:

5 s

範囲:

0..60 s

音声ストリーミングゲートウェイへの接続が失敗した場合のリトライ間隔を指定してください。

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

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 をご確認ください。

StartAudioStreaming API¶

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

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

StopAudioStreaming API¶

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

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

SubscribeAudioStreamingResultPush API¶

指定した接続が、音声ストリーミングゲートウェイからの戻り値のプッシュ通知をサブスクライブするよう設定します。

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

UnsubscribeAudioStreamingResultPush API¶

指定した接続が、音声ストリーミングゲートウェイからの戻り値のプッシュ通知をサブスクライブしないよう設定します。

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

ListAudioStreamingResultPushState API¶

指定したチャネルのセッションのコネクションごとのサブスクライブの状態を確認します。

[
  {
    "connection_id": "B2JPGFZPMD3H973Y811MF8ZZ70",
    "subscribe": true
  },
  {
    "connection_id": "KT116Z11KX5Y547KA1V12HW8PG",
    "subscribe": false
  },
  {
    "connection_id": "A5GYXGRYAX6590M3AFH7F9Z2H4",
    "subscribe": false
  }
]

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

対応サービス¶

• Amazon Transcribe
• Google Cloud Speech-to-Text

Suzu + AWS Transcribe¶

sequenceDiagram
    autonumber
    participant C as クライアント
    participant S as Sora
    participant Suzu
    participant AWS Transcribe
    C->>S: SRTP
    C->>S: SRTP
    C->>S: SRTP
    note over C, AWS Transcribe: StartAudioStreaming API 実行
    C->>S: SRTP
    S->>Suzu: Opus over HTTP/2
    Suzu->>AWS Transcribe: Ogg over HTTP/2
    C->>S: SRTP
    S->>Suzu: Opus over HTTP/2
    Suzu->>AWS Transcribe: Ogg over HTTP/2
    C->>S: SRTP
    S->>Suzu: Opus over HTTP/2
    Suzu->>AWS Transcribe: Ogg over HTTP/2
    AWS Transcribe->>Suzu: JSON over HTTP/2
    Suzu->>S: JSON over HTTP/2
    S->>C: シグナリングプッシュ通知

自動開始/停止¶