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_idtrue にする必要があります。

connection_id

接続ごとのユニークな値です。UUIDv4 生成した値を Base32 でエンコードした値で、Sora が払い出します。指定はできません。

仕組み

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_onlytrue にすることで、 ループバックアドレスからのみアクセスできるようにします。

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 がデフォルトで設定されます。

  • Opus

    • "OPUS"

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

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

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

重要

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

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

  • bit_rate

    • 6-510

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

指定できる値は 6 から 510 です。32 を指定した場合は、32kbps がビットレートの最大値です。

指定しない場合は sora.confdefault_audio_bit_rate に指定した値が採用されます。 default_audio_bit_rate も指定していない場合、bit_rate はクライアント側に依存します。

オーディオの Opus 設定指定

注意

この機能は実験的機能です。この機能を利用される場合は必ず事前にサポートまでご連絡ください

配信者は Opus の設定を指定することができます。

  • clock_rate

    • 1600-48000

  • 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
        }
    }
}

ビデオコーデック指定

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

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

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

この設定が指定されない場合は、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"
    }
}

ビデオビットレート指定

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

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

  • bit_rate

    • 1-50000

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

指定できる値は 1 から 50000 です。500 を指定した場合は、500kbps がビットレートの最大値です。

10Mbps を最大値としたい場合は 10000 を指定してください。ただし 15Mbps より大きい値は現時点ではサポート外となります。

指定しない場合は sora.confdefault_video_bit_rate に指定した値が採用されます。

メタデータ

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

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

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

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

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

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

マルチストリーム

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

他のクライアントのストリームを複数受信する事ができる仕組みです。

{
    "type": "connect",
    "role": "sendrecv",
    "channel_id": "spam",
    "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": "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"
}

environment

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

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

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

{
    "type": "connect",
    "role": "sendrecv",
    "channel_id": "sora",
    "sora_client": "Sora JavaScript SDK 2021.1.0",
    "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",
    "sora_client": "WebRTC Native Client Momo 2021.3 (1334a266)",
    "environment": "[arm64] macOS Version 11.4 (Build 20F71)",
    "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",
    "version": "2021.1",
    "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

"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 を指定することも可能です。この値は conenction.destoryedtype_disconnect_reason として含まれます。

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

"type": "ping"

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

{
    "type": "pong"
}

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

stats

注意

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

sora.conf にて remote_statstrue にしている場合は、 "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 ではない際にシグナリング項目が一致しない接続きた場合のエラー

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

このログが sora.log に出力された場合は、log/connection-created-wait-timeout-error/ 以下にもログが出力されます。

シーケンス図

認証ウェブフックなし

blockdiag クライアント Sora アプリケーション サーバー "type": "connect" "type": "offer" "type": "answer" "type": "candidate" イベントウェブフック "type": "connection.created" 200 OK "type": "disconnect" イベントウェブフック "type": "connection.destroye d" 200 OK WebSocket Close WebRTC 確立 クライアント切断

認証ウェブフックあり

blockdiag クライアント Sora アプリケーションサ ーバー "type": "connect" 認証ウェブフック 200 OK {"allowed": true} "type": "offer" "type": "answer" "type": "candidate" イベントウェブフック "type": "connection.creat ed" 200 OK "type": "disconnect" イベントウェブフック "type": "connection.destr oyed" 200 OK WebSocket Close WebRTC 確立 クライアント切断
© Copyright 2022, Shiguredo Inc Created using Sphinx 5.0.0b1