# WebSocket 経由のシグナリング ## 概要 > **重要** > > Sora の SDK を利用する場合は、ここに書かれているシグナリングの細かい仕様を把握する必要は基本的にありません。 Sora のシグナリングにはデフォルトでは WebSocket を使用します。 ## 用語 ### channel_id 接続のグルーピングに利用する ID です。接続時に任意の文字列、最大 255 バイトまでを自由に指定可能です。 ### client_id 接続時やサーバー認証成功時に任意の文字列を最大 255 バイトまで指定できる値です。 指定しない場合はコネクション ID が入ります。自由に指定可能です。重複が可能な ID です。 ### bundle_id `bundle_id` を指定した場合、マルチストリーム利用時に `bundle_id` が等しい接続からの音声や映像、メッセージング、シグナリング通知を受信しなくなります。 接続時やサーバー認証成功時に任意の文字列を最大 255 バイトまで指定できる値です。指定しない場合はコネクション ID が入ります。 シグナリングでのバンドル ID の指定はデフォルトでは無効になっているため、有効にする場合には `sora.conf` にて `signaling_bundle_id` を `true` にする必要があります。 ### connection_id 接続ごとのユニークな値です。UUIDv4 で生成した値を Base32 でエンコードした値で、Sora が払い出します。指定はできません。 **connection_id の例** : "FW0CJSHETX0RXAGX8WWEXNBQN8" ## 仕組み Sora のシグナリングは、Sora からクライアントへ Offer (SDP) を送ります。 シグナリングの処理の流れは、[認証ウェブフックなし](SIGNALING.html#cea9ce) のシーケンス図を参照してください。 シグナリングの型の正確な仕様は [シグナリングの型定義](SIGNALING_TYPE.html) を参照してください。 ### URL デフォルトの設定では、シグナリングは `0.0.0.0:5000` でリッスンするため、 シグナリング URL は `http://<サーバーのアドレス>:5000/signaling` となります。 **パス部分は /signaling 固定で変更できません** 。 ### DataChannel 経由への切り替え > **注意** > > 実験的機能として、シグナリングを WebSocket 経由から DataChannel 経由へ変更する機能を提供中です 詳細は [DataChannel 経由のシグナリング](DATA_CHANNEL_SIGNALING.html) をご確認ください。 ## 注意 シグナリングが完了しても WebSocket の接続は切断しないでください。WebSocket の接続が切れると Sora は WebRTC 接続を終了します。 ## 設定 ### signaling_loopback_address_only `sora.conf` にて [signaling_loopback_address_only](SORA_CONF.html#e22105) を `true` にすることで、 ループバックアドレスからのみアクセスできるようにします。 nginx などを前段に利用している場合は可能な限り有効にしてください。 ## シグナリングのタイプ Sora のシグナリングは、タイプごとの JSON でクライアントとメッセージをやりとりします。 ### "type": "connect" クライアントは Sora に接続の意思を伝える JSON を送ります。以下は最小の JSON です。 ```json { "type": "connect", "role": "sendonly", "channel_id": "Spam" } ``` #### role そのクライアントの役割を指定します。この設定は必須です。 `role` には `sendrecv` / `sendonly` / `recvonly` のどれかを指定してください。 - sendrecv- マルチストリーム、スポットライトで利用できます。送信及び受信を行います - sendonly- すべてで利用できます。送信のみを行い、受信を行いません - recvonly- すべてで利用できます。受信のみを行い、送信を行いません #### channel_id `channel_id` は 1-255 バイトまでの文字列であればどのような文字列でも指定可能です。 #### 視聴メディアの選択 **この項目はオプションです** 視聴者は配信者からの映像と音声、または、映像や音声のどちらかだけを受け取る指定が可能です。 視聴者が映像を受信せずに、音声のみを受信する場合は video に false を指定します。 ```json { "type": "connect", "role": "recvonly", "channel_id": "Spam", "video": false } ``` 音声を受信せずに、映像だけを受信する場合は audio に false を指定してください。 ```json { "type": "connect", "role": "recvonly", "channel_id": "Spam", "audio": false } ``` > **重要** > > Chrome 使用時に配信者が音声だけを配信している場合、視聴者が音声と映像を選択すると正常に配信されません。 これは Chrome の仕様によるものです。 音声のみを配信する場合は、視聴者も音声のみを選択することでこの問題は回避できます。 #### オーディオコーデック指定 **この項目はオプションです** 配信者や視聴者はオーディオコーデックを指定することができます。 この設定はオプションです。 この設定が指定されない場合は、 `OPUS` がデフォルトで設定されます。 > **重要** > > Lyra は一部の Sora SDK では利用できません。 - Opus- "OPUS" - Lyra- "LYRA" ```json { "type": "connect", "role": "sendonly", "channel_id": "Spam", "audio": { "codec_type":"OPUS" } } ``` #### オーディオビットレート指定 **この項目はオプションです** > **重要** > > オーディオビットレートは指定しないことをおすすめします。指定しないことで最適なビットレートが採用されます。 配信者はオーディオビットレートの最大値を指定することができます。 このビットレート指定は Opus にのみ有効で、 Lyra には適用されません。 Lyra の場合は `lyra_params` の `bitrate` を指定してください。 - bit_rate- 6-510 ```json { "type": "connect", "role": "sendonly", "channel_id": "Spam", "audio": { "codec_type": "OPUS", "bit_rate": 64 } } ``` 指定できる値は 6 から 510 です。32 を指定した場合は、32kbps がビットレートの最大値です。 指定しない場合は `sora.conf` の `default_audio_bit_rate` に指定した値が採用されます。 `default_audio_bit_rate` も指定していない場合、ビットレートはクライアント側に依存します。 #### オーディオの Opus 設定指定 > **注意** > > この機能は実験的機能です。この機能を利用される場合は必ず事前にサポートまでご連絡ください 配信者は Opus の設定を指定することができます。 - channels- 1-8 - maxplaybackrate- 8000-48000 - stereo- boolean - sprop_stereo- boolean - minptime- integer 3-120 - useinbandfec- boolean - usedtx- boolean - **この機能を有効にした場合は録画がおかしくなります** ```json { "type": "connect", "role": "sendonly", "channel_id": "Spam", "audio": { "codec_type": "OPUS", "opus_params": { "stereo": false, "useinbandfec": false } } } ``` #### オーディオの Lyra 設定指定 > **注意** > > この機能は実験的機能です。この機能を利用される場合は必ず事前にサポートまでご連絡ください **この項目は Lyra を使う場合必須です** - version- string - 1.2.0 や 1.3.0 といった Lyra のバージョンを指定します - bitrate- integer 3200 or 6000 or 9200 ```json { "type": "connect", "role": "sendonly", "channel_id": "Spam", "audio": { "codec_type": "LYRA", "lyra_params": { "version": "1.3.0", "bitrate": 6000 } } } ``` #### ビデオコーデック指定 **この項目はオプションです** 配信者や視聴者はビデオコーデックを指定することができます。 この設定はオプションです。 この設定が指定されない場合は、VP9 がデフォルトで設定されます。 - VP8- `"VP8"` - VP9- "`VP9"` - Safari では実験的機能を有効にすることで利用可能です - AV1- `"AV1"` - Chrome M96 以降で利用可能です - H.264- `"H264"` - H.265- `"H265"` - Safari では実験的機能を有効にすることで利用可能です ```json { "type": "connect", "role": "sendonly", "channel_id": "Spam", "video": { "codec_type":"VP9" } } ``` #### ビデオビットレート指定 **この項目はオプションです** 配信者はビデオビットレートの最大値を指定することができます。単位は **kbps** です。 - bit_rate- 1-50000 ```json { "type": "connect", "role": "sendonly", "channel_id": "Spam", "video": { "codec_type": "VP9", "bit_rate": 500 } } ``` 指定できる値は 1 から 50000 です。500 を指定した場合は、500 kbps がビットレートの最大値です。 10 Mbps を最大値としたい場合は 10000 を指定してください。ただし 15 Mbps より大きい値は現時点ではサポート外となります。 指定しない場合は `sora.conf` の `default_video_bit_rate` に指定した値が採用されます。 #### 認証メタデータ **この項目はオプションです** 認証するための判断材料としてメタデータを使用することができます。 認証メタデータは必須ではありません。 ```json { "type": "connect", "role": "sendonly", "channel_id": "Spam", "metadata": "1234abcd" } ``` 認証メタデータは、そのまま認証サーバーに送られます。詳細は [認証ウェブフック](AUTH_WEBHOOK.html) をご確認ください。 #### client_id の指定 **この項目はオプションです** > **重要** > > `client_id` の値は重複することが可能です。 1-255 バイトまでの文字列であれば、どのような文字列でも指定可能です。 ```json { "type": "connect", "role": "sendonly", "channel_id": "Spam", "client_id": "egg-ham" } ``` #### bundle_id の指定 **この項目はオプションです** > **重要** > > `bundle_id` の値は重複することが可能です。 1-255 バイトまでの文字列であれば、どのような文字列でも指定可能です。 マルチストリーム利用時に `bundle_id` が同じ接続からの音声や映像、メッセージングを受信しなくなります。 ```json { "type": "connect", "role": "sendonly", "channel_id": "Spam", "bundle_id": "spam_egg" } ``` #### マルチストリーム **この項目はオプションです** 他のクライアントのストリームを複数受信することができる仕組みです。デフォルトで有効です。 もしマルチストリームを使わない場合は明示的に `"multistream": false` を指定してください。 ```json { "type": "connect", "role": "sendrecv", "channel_id": "spam", "multistream": false } ``` 詳細は [マルチストリーム機能](MULTISTREAM.html) をご確認ください。 #### サイマルキャスト **この項目はオプションです** 自分が配信する映像のストリームを複数本にすることで、 受信側にどのストリームを受信するかを選択させることが可能になります。 サイマルキャストを有効にする場合には `"multistream": true` も明示的に指定する必要があります。 ```json { "type": "connect", "role": "sendrecv", "channel_id": "spam", "multistream": true, "simulcast": true } ``` 詳細は [サイマルキャスト機能](SIMULCAST.html) をご確認ください。 #### スポットライト **この項目はオプションです** 話をした人にフォーカスを当てて、フォーカスが当たっている人は高画質な映像と音声で配信、 フォーカスが当たっていない人は低画質な映像で配信するという、クライアントの負荷を下げる仕組みです。 ```json { "type": "connect", "role": "sendrecv", "channel_id": "spam", "multistream": true, "simulcast": true, "spotlight": true } ``` 詳細は [スポットライト機能](SPOTLIGHT.html) をご確認ください。 #### sdp **この項目はオプションです** Sora SDK や Sora クライアントで生成した offer SDP を Sora のログに記録します。 この項目は、ログの記録にのみ利用します。 ```json { "type": "connect", "role": "sendrecv", "channel_id": "spam", "sdp": "..." } ``` #### sora_client **この項目はオプションです** Sora SDK や Sora クライアントの情報を文字列で送ることができます。 これはログに記録されたり、認証ウェブフックリクエストで送信されたりします。 ```json { "type": "connect", "role": "sendrecv", "channel_id": "sora", "sora_client": "Sora JavaScript SDK 2021.1.0" } ``` #### environment **この項目はオプションです** Sora SDK や Sora クライアントの利用環境を文字列で送ることができます。 これはログに記録されたり、認証ウェブフックリクエストで送信されたりします。 Sora JavaScript SDK では userAgent の情報が入ります。 ```json { "type": "connect", "role": "sendrecv", "channel_id": "sora", "environment": "Mozilla\/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit\/537.36 (KHTML, like Gecko) Chrome\/93.0.4522.0 Safari\/537.36" } ``` #### libwebrtc **この項目はオプションです** Sora SDK や Sora クライアントの libwebrtc のバージョンを文字列で送ることができます。 これはログに記録されたり、認証ウェブフックリクエストで送信されたりします。 ```json { "type": "connect", "role": "sendrecv", "channel_id": "sora", "libwebrtc": "Shiguredo-Build M90.4430@{#3} (90.4430.3.1 dee77cf2)" } ``` ### "type": "offer" 認証ウェブフックが認証成功を返すと、Sora は以下のような JSON をクライアントに送ります。 SDK を利用している場合は、この仕様を意識する必要はありません。 ```json { "type": "offer", "sdp": "", "connection_id": "ECF3W1RGMD02DETH30CDZTHNRW", "client_id": "ECF3W1RGMD02DETH30CDZTHNRW", "bundle_id": "ECF3W1RGMD02DETH30CDZTHNRW", "multistream": true, "simulcast": false, "spotlight": false, "version": "2021.1", "metadata": "1234abcd", "config": { "iceServers": [ { "credential": "ClDTPB4DjgFLrclpSBxjTiXg7K8kYsGf", "urls": [ "turn:192.0.2.1:443?transport=tcp" ], "username": "sYL5WdMt" } ], "iceTransportPolicy": "relay" }, "mid": { "audio": "audio_aDScYe", "video": "video_i2sNRq" }, "data_channels": [ { "compress": true, "label": "stats" }, { "compress": false, "label": "e2ee" }, { "compress": true, "label": "push" }, { "compress": true, "label": "notify" }, { "compress": true, "label": "signaling" } ] } ``` - connection_id- UUIDv4 を Base32 でエンコードしたユニークな ID が入ります - client_id- クライアントや認証サーバーが指定した値、または、Sora が生成した connection_id が入ります - bundle_id- クライアントや認証サーバーが指定した値、または、Sora が生成した connection_id が入ります - config- RTCPeerConnection に渡す設定が入ります - 主に TURN の情報です - mid- audio と video の MediaStream Id が入ります - version- Sora のバージョンが入ります - metadata- これはオプションです - 認証サーバーから払い出された metadata が入ります - data_channels- これは DataChannel 経由のシグナリングを有効にしている場合にのみ利用されます - 詳細は [DataChannel への切り替え要否の判断](DATA_CHANNEL_SIGNALING.html#1abf7f) をご確認ください ### "type": "answer" クライアントは offer を受け取りしだい、answer 用の SDP を生成します。 ```json { "type": "answer", "sdp": "" } ``` その後、必要があればクライアントは取得した candidate を送ります。 ```json { "type": "candidate", "candidate": "candidate:3179889176 1 tcp 1518214911 192.168.1.10 0 typ host tcptype active generation 0" } ``` ### "type": "disconnect" クライアントからこのメッセージを送ると、Sora は WebSocket を切断します。また、WebRTC 側も終了します。 クライアントから切断する際には、このメッセージを送るようにしてください。 ```json { "type": "disconnect" } ``` オプションとして reason を指定することも可能です。この値は `connection.destoryed` の `type_disconnect_reason` として含まれます。 ```json { "type": "disconnect", "reason": "NO-ERROR" } ``` ### "type": "ping" サーバーからクライアント側に定期的に送られる通知です。この値をクライアントが受け取った場合は、すぐに以下の JSON を Sora に送信してください。 ```json { "type": "pong" } ``` `"type": "ping"` を送ってから 60 秒の間に一度も `"type": "pong"` が返ってこない場合、 Sora は正常な通信が行えていないと判断して、Sora からシグナリングの接続を切断します。 #### stats > **注意** > > この機能は WebSocket 経由でのシグナリングの時のみ有効です `sora.conf` にて `user_agent_stats` を `true` にしている場合は、 `"type": "ping"` 時に `"stats": true` が送られてきます。 ```json { "type": "ping", "stats": true } ``` この値を受け取った場合は、WebRTC の統計情報を取得して `"type": "pong"` 送信時に `stats` をキーにして値を含んで応答してください。 ```json { "type": "pong", "stats": [{"type": "..."}, {"type": "..."}] } ``` ### "type": "notify" サーバーからクライアントに対して、参加しているチャネルの情報が通知されるようになります。 詳細は [シグナリング通知機能](SIGNALING_NOTIFY.html) をご確認ください。 ## シグナリングエラー 切断時の reason を利用してハンドリングすることが可能です。 - Sora のシグナリング失敗時には必ず WebSocket が切断されます。 - どのようなエラーでも、ステータスコードは固定で 4490 が返ってきます。 - reason にはエラーメッセージが入ります ``` "DUPLICATED-CHANNEL-ID" ``` * - reason - 解説 * - FAILURE-JSON-DECODE - 不正な JSON 形式のメッセージの場合のエラー * - DUPLICATED-CHANNEL-ID - 同一の channel_id をすでに使用中の場合のエラー * - AUTHENTICATION-FAILURE - 認証に失敗した場合のエラー * - AUTHENTICATION-INTERNAL-ERROR - 認証サーバーが意図しないレスポンスを返してきた場合のエラー * - UNKNOWN-CODEC-TYPE - 不正な codec_type を指定した場合のエラー * - UNMATCH-VIDEO-CODEC-TYPE - Plan B でのマルチストリーム、またはスポットライト機能で映像のコーデックが他の参加者と異なる値の場合のエラー * - UNMATCH-AUDIO-CODEC-TYPE - スポットライト機能で音声のコーデックが他の参加者と異なる値の場合のエラー * - INVALID-SPOTLIGHT-COUNT - スポットライト機能の配信数が 1 から 8 の範囲外、または他の参加者と異なる値の場合のエラー * - FAILURE-SDP-PARSE - 不正な SDP の場合のエラー * - UNEXPECTED-SIGNALING-TYPE - シグナリングのフローとして許されない type を受信した場合のエラー * - INVALID-SIGNALING-TYPE - type の値が不正である場合のエラー * - CONNECT-WAIT-TIMEOUT - Open したあと一定時間以内に "type": "connect" のメッセージを送信しなかった場合のエラー * - MISSING-ICE-SDP - SDP に ICE 情報が含まれていなかった場合のエラー * - FAILURE-SDP-PARSE - answer や update、 candidate の SDP のパースに失敗したエラー * - MISSING-TYPE - type: が JSON に含まれていなかった場合のエラー * - INVALID-JSON - JSON 形式が間違っていた場合のエラー * - PONG-TIMEOUT-ERROR - Ping の応答が返ってこなかった場合のエラー * - CONNECT-WAIT-TIMEOUT-ERROR - シグナリング開始後 5 秒以内に "type": "connect" を送ってこなかった場合のエラー * - CONNECTION-CREATED-WAIT-TIMEOUT-ERROR - シグナリング開始してから指定した時間シグナリングが成功しなかった場合のエラー * - NO-MEDIA - 音声も映像も有効にせずに "type": "connect" を送ってきた場合のエラー * - EXCEED-MAX-CONNECTIONS - ライセンスの接続数を超えた接続が来た場合のエラー * - CLIENT-ERROR - クライアントが想定外の動作をした場合のエラー * - BAD-FINGERPRINT - 証明書検証が失敗した場合のエラー * - ANSWER-TIMEOUT-ERROR - 30 秒以内に "type": "answer" を返さなかった場合のエラー * - TOO-MANY-CANDIDATE - 多くの "type": "candidate" が送られてきた場合のエラー * - NO-ACCEPTABLE-NODE - クラスターのどのノードも受け入れられない場合のエラー * - INVALID-SIGNALING-PARAMS - セッションが残っている状態かつ、接続数が 0 ではない際にシグナリング項目が一致しない接続がきた場合のエラー * - INITIAL - モードが ``initial`` のノードに、接続がきた場合のエラー * - BLOCK-NEW-CONNECTION - モードが ``block_new_connection`` のノードに、接続がきた場合のエラー * - BLOCK-NEW-SESSION - ノードのモードが ``block_new_session`` かつ、そのノードが担当していないセッションに対しての接続がきた場合のエラー * - SIGNALING-INTERNAL-ERROR - シグナリング内部エラー * - TRANSPORT-INTERNAL-ERROR - 通信内部エラー * - ROUTER-INTERNAL-ERROR - 通信内部エラー * - INTERNAL-ERROR - 内部エラー ### AUTHENTICATION-FAILURE このエラーはクライアントに通知されることはなく、ログにしか出力されません。 ### CONNECTION-CREATED-WAIT-TIMEOUT-ERROR シグナリングを実行してから Sora と WebRTC の接続が成功するまでの許容時間を超えた場合に出力されるエラーです。 この許容時間はデフォルトでは 30 秒に設定されており、この値は `sora.conf` の設定で変更が可能です。 ```ini // これは 10 秒待っても、シグナリングが成功しない場合は接続を切断する設定です connection_created_wait_timeout = 10 s ``` このログが sora.log に出力された場合は、 `log/connection_created_wait_timeout_error/` 以下に詳細なログが出力されます。 ## シーケンス図 ### 認証ウェブフックなし seqdiag { default_fontsize = 15; edge_length = 250; クライアント ->> Sora [label = '"type": "connect"']; クライアント <<- Sora [label = '"type": "offer"']; クライアント ->> Sora [label = '"type": "answer"', noactivate]; クライアント ->> Sora [label = '"type": "candidate"', noactivate]; === WebRTC 確立 === Sora -> アプリケーションサーバー [label = 'イベントウェブフック\n"type": "connection.created"']; Sora <-- アプリケーションサーバー [label = '200 OK']; === クライアント切断 === クライアント ->> Sora [label = '"type": "disconnect"', noactivate]; Sora -> アプリケーションサーバー [label = 'イベントウェブフック\n"type": "connection.destroyed"']; Sora <-- アプリケーションサーバー [label = '200 OK']; クライアント <<- Sora [label = 'WebSocket Close']; } ### 認証ウェブフックあり seqdiag { default_fontsize = 14; edge_length = 200; クライアント ->> Sora [label = '"type": "connect"']; Sora -> アプリケーションサーバー [label = '認証ウェブフック']; Sora <-- アプリケーションサーバー [label = '200 OK\n{"allowed": true}']; クライアント <<- Sora [label = '"type": "offer"']; クライアント ->> Sora [label = '"type": "answer"', noactivate]; クライアント ->> Sora [label = '"type": "candidate"', noactivate]; === WebRTC 確立 === Sora -> アプリケーションサーバー [label = 'イベントウェブフック\n"type": "connection.created"']; Sora <-- アプリケーションサーバー [label = '200 OK']; === クライアント切断 === クライアント ->> Sora [label = '"type": "disconnect"', noactivate]; Sora -> アプリケーションサーバー [label = 'イベントウェブフック\n"type": "connection.destroyed"']; Sora <-- アプリケーションサーバー [label = '200 OK']; クライアント <<- Sora [label = 'WebSocket Close']; }