WebSocket 経由のシグナリング¶

概要¶

重要

Sora の SDK を利用する場合は、ここに書かれているシグナリングの細かい仕様を把握する必要は基本的にありません。

Sora のシグナリングにはデフォルトでは WebSocket を使用します。

用語¶

channel_id¶

接続のグルーピングに利用する ID です。接続時に任意の文字列、最大 255 バイトまでを自由に指定できます。

session_id¶

channel_id への接続が 0 から 1 に切り替わったタイミングで生成される id です。 1 から 0 になり、一定期間が経過したタイミングでセッションは破棄されます。

セッションが破棄された後、再度同一 channel_id で接続が 0 から 1 になった場合、新しい session_id が生成されます。

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

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 バイトまでの文字列であればどのような文字列でも指定できます。

配信または視聴メディアの選択¶

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

audio と video を指定することにより配信、または視聴するメディアを選択することができます。 role に sendrecv または sendonly を指定した場合は配信するメディア、 recvonly を指定したときは視聴するメディアについての指定となります。

この設定が未指定の場合は、 true がデフォルトで指定され、映像と音声両方の配信、または映像と音声両方の受信が行われます。

以下の例では role に sendrecv が指定されており、音声のみが配信されます。

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

注釈

role に sendrecv が指定された場合は常に映像と音声両方を受信します。

以下の例では role に sendonly が指定されており、映像のみが配信されます。

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

以下の例では role に recvonly が指定されており、音声のみが受信されます。

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

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

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

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

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

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

Opus
- "OPUS"

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

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

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

重要

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

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

このビットレート指定は Opus にのみ有効です。

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 の設定を指定できます。

opus_params
- 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"
AV1
- "AV1"
- Chrome M96 以降で利用できます
- Sora SDK で利用できます
H.264
- "H264"
H.265
- "H265"
- Sora iOS/Android SDK で利用できます
- 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 に指定した値が採用されます。

ビデオの VP9 設定指定¶

配信者は VP9 のプロファイル ID を指定できます。 VP9 のプロファイル ID を指定をする場合は、あわせて codec_type に VP9 を指定する必要があります。

vp9_params
- profile_id
  - integer
  - 0-3

この値を指定するには sora.conf にて signaling_vp9_params を true に設定する必要があります。

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

ビデオの AV1 設定指定¶

配信者は AV1 のプロファイルを指定できます。 AV1 のプロファイルを指定をする場合は、あわせて codec_type に AV1 を指定する必要があります。

av1_params
- profile
  - integer
  - 0-2

この値を指定するには sora.conf にて signaling_av1_params を true に設定する必要があります。

{
    "type": "connect",
    "role": "sendonly",
    "channel_id": "Spam",
    "video": {
        "codec_type": "AV1",
        "av1_params": {
            "profile": 0
        }
    }
}

ビデオの H.264 設定指定¶

配信者は H.264 のプロファイルレベル ID を指定できます。 H.264 のプロファイルレベル ID を指定をする場合は、あわせて codec_type に H264 を指定する必要があります。

h264_params
- profile_level_id
  - string
  - "42e01f" など

この値を指定するには sora.conf にて signaling_h264_params を true に設定する必要があります。

{
    "type": "connect",
    "role": "sendonly",
    "channel_id": "Spam",
    "video": {
        "codec_type": "H264",
        "h264_params": {
            "profile_level_id": "42e01f"
        }
    }
}

ビデオの H.265 設定指定¶

注意

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

警告

この機能はまだ対応しているライブラリが存在しません。

配信者は H.265 のプロファイルレベル ID を指定できます。 H.265 のプロファイルレベル ID を指定をする場合は、あわせて codec_type に H265 を指定する必要があります。

h265_params
- level_id
  - integer
  - 93 など

この値を指定するには sora.conf にて signaling_h265_params を true に設定する必要があります。

{
    "type": "connect",
    "role": "sendonly",
    "channel_id": "Spam",
    "video": {
        "codec_type": "H265",
        "h265_params": {
            "level_id": 93
        }
    }

認証メタデータ¶

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

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

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

{
    "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 が同じ接続からの音声や映像、メッセージングを受信しなくなります。

この値を指定するには sora.conf にて signaling_bundle_id を true に設定する必要があります。

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

サイマルキャスト¶

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

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

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

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

スポットライト¶

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

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

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

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

転送フィルター¶

注意

この機能は実験的機能です。

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

接続時に転送フィルターを指定することで、条件に該当する他のチャネル参加者の音声や映像の受信をブロックする仕組みです。

forwarding_filter
- 受信をブロックする条件を指定します
- 接続後は転送フィルター API を利用してフィルターの変更、削除ができます

この値を指定するには sora.conf にて signaling_forwarding_filter を true に設定する必要があります。

{
    "type": "connect",
    "role": "sendrecv",
    "channel_id": "spam",
    "forwarding_filter": {
        "action": "block",
        "rules": [
            [
            {"field": "kind", "operator": "is_in", "values": ["audio"]}
            ]
        ]
    }
}

詳細は転送フィルター機能をご確認ください。

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>",
    "channel_id": "sora",
    "session_id": "05JTBDGM1H3GB7FK0B1CJ45JE0",
    "connection_id": "ECF3W1RGMD02DETH30CDZTHNRW",
    "client_id": "ECF3W1RGMD02DETH30CDZTHNRW",
    "bundle_id": "ECF3W1RGMD02DETH30CDZTHNRW",
    "multistream": true,
    "simulcast": false,
    "spotlight": false,
    "version": "2023.2.0",
    "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"
      }
    ]
}

channel_id
- "type": "connect" の channel_id で指定した値が入ります
session_id
- UUIDv4 を Base32 でエンコードしたユニークな ID が入ります
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.destroyed の type_disconnect_reason として含まれます。

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

"type": "ping"¶

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

{
    "type": "pong"
}

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

指定時間はデフォルトでは 60 秒に設定されており、この値は sora.conf の設定 websocket_signaling_pong_timeout で変更できます。

stats¶

注意

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

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

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

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

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

"type": "notify"¶

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

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

"type": "push"¶

Sora のプッシュ API やシグナリング通知メタデータ拡張機能、音声ストリーミング機能利用時にクライアントに送信されるプッシュ通知です。

data 内に各機能に応じた情報が設定されます。

{
    "type": "push",
    "data": {
        <key>: <object>,
        <key>: <object>,
        ...
    }
}

シグナリングエラー¶

切断時の 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 情報が含まれていなかった場合のエラー
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 の設定 connection_created_wait_timeout で変更できます。

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

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

シーケンス図¶

認証ウェブフックなし¶

sequenceDiagram autonumber participant C as クライアント participant S as WebRTC SFU Sora participant A as アプリケーションサーバー C->>+S: "type": "connect" S->>-C: "type": "offer" C->>S: "type": "answer" C->>S: "type": "candidate" note over C,A: WebRTC 確立 S->>+A: イベントウェブフック "type": "connection.created" A-->-S: 200 OK C->>S: "type": "disconnect" S->>+A: イベントウェブフック "type": "connection.destroyed" A-->>-S: 200 OK S->>C: Websocket Close

認証ウェブフックあり¶

sequenceDiagram autonumber participant C as クライアント participant S as WebRTC SFU Sora participant A as アプリケーションサーバー C->>+S: "type": "connect" S->>+A: 認証ウェブフック A-->>-S: 200 OK {"allowed": "true"} S->>-C: "type": "offer" C->>S: "type": "answer" C->>S: "type": "candidate" note over C,A: WebRTC 確立 S->>+A: イベントウェブフック "type": "connection.created" A-->-S: 200 OK C->>S: "type": "disconnect" S->>+A: イベントウェブフック "type": "connection.destroyed" A-->>-S: 200 OK S->>C: Websocket Close