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) を送ります。

シグナリングの処理の流れは、認証ウェブフックなし のシーケンス図を参照してください。

シグナリングの型の正確な仕様は シグナリングの型定義 を参照してください。

URL

デフォルトの設定では、シグナリングは 0.0.0.0:5000 でリッスンするため、 シグナリング URL は http://<サーバーのアドレス>:5000/signaling となります。

パス部分は /signaling 固定で変更できません 。

DataChannel 経由への切り替え

注意

実験的機能として、シグナリングを WebSocket 経由から DataChannel 経由へ変更する機能を提供中です

詳細は DataChannel 経由のシグナリング をご確認ください。

注意

シグナリングが完了しても WebSocket の接続は切断しないでください。WebSocket の接続が切れると Sora は WebRTC 接続を終了します。

設定

signaling_loopback_address_only

sora.conf にて signaling_loopback_address_only を true にすることで、 ループバックアドレスからのみアクセスできるようにします。

nginx などを前段に利用している場合は可能な限り有効にしてください。

シグナリングのタイプ

Sora のシグナリングは、タイプごとの JSON でクライアントとメッセージをやりとりします。

"type": "connect"

クライアントは Sora に接続の意思を伝える 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 を指定します。

{
    "type": "connect",
    "role": "recvonly",
    "channel_id": "Spam",
    "video": false
}

音声を受信せずに、映像だけを受信する場合は audio に false を指定してください。

{
    "type": "connect",
    "role": "recvonly",
    "channel_id": "Spam",
    "audio": false
}

重要

Chrome 使用時に配信者が音声だけを配信している場合、視聴者が音声と映像を選択すると正常に配信されません。

これは Chrome の仕様によるものです。 音声のみを配信する場合は、視聴者も音声のみを選択することでこの問題は回避できます。

オーディオコーデック指定

この項目はオプションです

配信者や視聴者はオーディオコーデックを指定することができます。

この設定はオプションです。

この設定が指定されない場合は、 OPUS がデフォルトで設定されます。

重要

Lyra は一部の Sora SDK では利用できません。

• Opus

  • "OPUS"

• Lyra

  • "LYRA"

{
    "type": "connect",
    "role": "sendonly",
    "channel_id": "Spam",
    "audio": {
        "codec_type":"OPUS"
    }
}

オーディオビットレート指定

この項目はオプションです

重要

オーディオビットレートは指定しないことをおすすめします。指定しないことで最適なビットレートが採用されます。

配信者はオーディオビットレートの最大値を指定することができます。

このビットレート指定は Opus にのみ有効で、 Lyra には適用されません。 Lyra の場合は lyra_params の bitrate を指定してください。

• bit_rate

  • 6-510

{
    "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

  • この機能を有効にした場合は録画がおかしくなります

{
    "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

{
    "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 では実験的機能を有効にすることで利用可能です

{
    "type": "connect",
    "role": "sendonly",
    "channel_id": "Spam",
    "video": {
        "codec_type":"VP9"
    }
}

ビデオビットレート指定

この項目はオプションです

配信者はビデオビットレートの最大値を指定することができます。単位は kbps です。

• bit_rate

  • 1-50000

{
    "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 に指定した値が採用されます。

認証メタデータ

この項目はオプションです

認証するための判断材料としてメタデータを使用することができます。

認証メタデータは必須ではありません。

{
    "type": "connect",
    "role": "sendonly",
    "channel_id": "Spam",
    "metadata": "1234abcd"
}

認証メタデータは、そのまま認証サーバーに送られます。詳細は 認証ウェブフック をご確認ください。

client_id の指定

この項目はオプションです

重要

client_id の値は重複することが可能です。

1-255 バイトまでの文字列であれば、どのような文字列でも指定可能です。

{
    "type": "connect",
    "role": "sendonly",
    "channel_id": "Spam",
    "client_id": "egg-ham"
}

bundle_id の指定

この項目はオプションです

重要

bundle_id の値は重複することが可能です。

1-255 バイトまでの文字列であれば、どのような文字列でも指定可能です。

マルチストリーム利用時に bundle_id が同じ接続からの音声や映像、メッセージングを受信しなくなります。

{
    "type": "connect",
    "role": "sendonly",
    "channel_id": "Spam",
    "bundle_id": "spam_egg"
}

マルチストリーム

この項目はオプションです

他のクライアントのストリームを複数受信することができる仕組みです。デフォルトで有効です。 もしマルチストリームを使わない場合は明示的に "multistream": false を指定してください。

{
    "type": "connect",
    "role": "sendrecv",
    "channel_id": "spam",
    "multistream": false
}

詳細は マルチストリーム機能 をご確認ください。

サイマルキャスト

この項目はオプションです

自分が配信する映像のストリームを複数本にすることで、 受信側にどのストリームを受信するかを選択させることが可能になります。

サイマルキャストを有効にする場合には "multistream": true も明示的に指定する必要があります。

{
    "type": "connect",
    "role": "sendrecv",
    "channel_id": "spam",
    "multistream": true,
    "simulcast": true
}

詳細は サイマルキャスト機能 をご確認ください。

スポットライト

この項目はオプションです

話をした人にフォーカスを当てて、フォーカスが当たっている人は高画質な映像と音声で配信、 フォーカスが当たっていない人は低画質な映像で配信するという、クライアントの負荷を下げる仕組みです。

{
    "type": "connect",
    "role": "sendrecv",
    "channel_id": "spam",
    "multistream": true,
    "simulcast": true,
    "spotlight": true
}

詳細は スポットライト機能 をご確認ください。

sdp

この項目はオプションです

Sora SDK や Sora クライアントで生成した offer SDP を Sora のログに記録します。 この項目は、ログの記録にのみ利用します。

{
    "type": "connect",
    "role": "sendrecv",
    "channel_id": "spam",
    "sdp": "..."
}

sora_client

この項目はオプションです

Sora SDK や Sora クライアントの情報を文字列で送ることができます。 これはログに記録されたり、認証ウェブフックリクエストで送信されたりします。

{
    "type": "connect",
    "role": "sendrecv",
    "channel_id": "sora",
    "sora_client": "Sora JavaScript SDK 2021.1.0"
}

environment

この項目はオプションです

Sora SDK や Sora クライアントの利用環境を文字列で送ることができます。 これはログに記録されたり、認証ウェブフックリクエストで送信されたりします。

Sora JavaScript SDK では userAgent の情報が入ります。

{
    "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 のバージョンを文字列で送ることができます。 これはログに記録されたり、認証ウェブフックリクエストで送信されたりします。

{
    "type": "connect",
    "role": "sendrecv",
    "channel_id": "sora",
    "libwebrtc": "Shiguredo-Build M90.4430@{#3} (90.4430.3.1 dee77cf2)"
}

"type": "offer"

認証ウェブフックが認証成功を返すと、Sora は以下のような JSON をクライアントに送ります。 SDK を利用している場合は、この仕様を意識する必要はありません。

{
    "type": "offer",
    "sdp": "<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 への切り替え要否の判断 をご確認ください

"type": "answer"

クライアントは offer を受け取りしだい、answer 用の SDP を生成します。

{
    "type": "answer",
    "sdp": "<Answer 用 SDP>"
}

その後、必要があればクライアントは取得した candidate を送ります。

{
    "type": "candidate",
    "candidate": "candidate:3179889176 1 tcp 1518214911 192.168.1.10 0 typ host tcptype active generation 0"
}

"type": "disconnect"

クライアントからこのメッセージを送ると、Sora は WebSocket を切断します。また、WebRTC 側も終了します。

クライアントから切断する際には、このメッセージを送るようにしてください。

{
    "type": "disconnect"
}

オプションとして reason を指定することも可能です。この値は connection.destoryed の type_disconnect_reason として含まれます。

{
    "type": "disconnect",
    "reason": "NO-ERROR"
}

"type": "ping"

サーバーからクライアント側に定期的に送られる通知です。この値をクライアントが受け取った場合は、すぐに以下の JSON を Sora に送信してください。

{
    "type": "pong"
}

"type": "ping" を送ってから 60 秒の間に一度も "type": "pong" が返ってこない場合、 Sora は正常な通信が行えていないと判断して、Sora からシグナリングの接続を切断します。

stats

注意

この機能は WebSocket 経由でのシグナリングの時のみ有効です

sora.conf にて user_agent_stats を true にしている場合は、 "type": "ping" 時に "stats": true が送られてきます。

{
    "type": "ping",
    "stats": true
}

この値を受け取った場合は、WebRTC の統計情報を取得して "type": "pong" 送信時に stats をキーにして値を含んで応答してください。

{
    "type": "pong",
    "stats": [{"type": "..."}, {"type": "..."}]
}

"type": "notify"

サーバーからクライアントに対して、参加しているチャネルの情報が通知されるようになります。

詳細は シグナリング通知機能 をご確認ください。

シグナリングエラー

切断時の 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 の設定で変更が可能です。

// これは 10 秒待っても、シグナリングが成功しない場合は接続を切断する設定です
connection_created_wait_timeout = 10 s

このログが sora.log に出力された場合は、 log/connection_created_wait_timeout_error/ 以下に詳細なログが出力されます。

シーケンス図

認証ウェブフックなし

認証ウェブフックあり

コンテンツ

• WebSocket 経由のシグナリング
  • 概要
  • 用語
    • channel_id
    • client_id
    • bundle_id
    • connection_id
  • 仕組み
    • URL
    • DataChannel 経由への切り替え
  • 注意
  • 設定
    • signaling_loopback_address_only
  • シグナリングのタイプ
    • "type": "connect"
      • role
      • channel_id
      • 視聴メディアの選択
      • オーディオコーデック指定
      • オーディオビットレート指定
      • オーディオの Opus 設定指定
      • オーディオの Lyra 設定指定
      • ビデオコーデック指定
      • ビデオビットレート指定
      • 認証メタデータ
      • client_id の指定
      • bundle_id の指定
      • マルチストリーム
      • サイマルキャスト
      • スポットライト
      • sdp
      • sora_client
      • environment
      • libwebrtc
    • "type": "offer"
    • "type": "answer"
    • "type": "disconnect"
    • "type": "ping"
      • stats
    • "type": "notify"
  • シグナリングエラー
    • AUTHENTICATION-FAILURE
    • CONNECTION-CREATED-WAIT-TIMEOUT-ERROR
  • シーケンス図
    • 認証ウェブフックなし
    • 認証ウェブフックあり