WebSocket 経由のシグナリング

WebRTC SFU Sora のシグナリングは WebSocket を使用します。 Sora の SDK を利用する場合は、以下の仕様を把握する必要は基本的にありません。

用語

channel_id

グルーピングに利用する ID で接続時に文字列を指定できます。自由に指定可能です。

client_id

接続時やサーバー認証成功時に任意の文字列を指定できる値です。指定しない場合はコネクション ID が入ります。自由に指定可能です。重複が可能な ID です。

connection_id

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

仕組み

Sora のシグナリングは、Sora からクライアントへ Offer (SDP) を送ります。 シグナリングの正確な仕様は シグナリングの型定義 を参照してください。

URL

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

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

DataChannel 経由への切り替え

注意

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

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

設定

signaling_loopback_address_only

sora.conf にて signaling_loopback_address_onlytrue にすることで、 ループバックアドレスからのみアクセスできるようにします。可能な限り有効にしてください。

"type": "connect"

クライアントは Sora に接続の意思を伝える JSON を送ります。以下は最小の JSON です。

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

ロール

rolesendrecv / sendonly / recvonly のどれかを指定してください。

そのクライアントの役割を指定します。この設定は必須です。

  • sendrecv

    • マルチストリーム、スポットライトで利用できる role で送受信を行います

  • sendonly

    • すべてで利用でき、送信のみを行い、受信を行いません

  • recvonly

    • すべてで利用でき、受信のみを行い、送信を行いません

チャネル ID

channel_id は 1-255 文字までの文字列であればどのような文字列でも指定可能です。

視聴メディアの選択

重要

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

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

視聴者は配信者からの映像や音声のどちらかだけを受け取る指定が可能です。

視聴者が映像を受信せず、音声のみを受信する場合は video に false を指定します。

映像だけの場合は audio に false を指定してください。

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

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

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

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

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

  • OPUS

    • "OPUS"

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

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

重要

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

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

{
    "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 M90 以降で利用可能です

  • H.264

    • "H264"

  • H.265

    • "H265"

    • Safari では実験的機能を有効にすることで利用可能です

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

ビデオビットレート指定

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

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

マルチストリーム

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

{
    "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",
    "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 が入ります

  • confing

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

"type": "ping"

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

{
    "type": "pong"
}

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

stats

注意

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

sora.conf にて remote_statstrue にしている場合は、 "type": "ping" 時に "stats": true が送られてきます。 この値を受け取った場合は、WebRTC の統計情報を取得して "type": "pong" 時に stats をキーにして値を含んで応答してください。

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

"type": "notify"

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

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

注意

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

シグナリングエラー

切断時の 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" が送られてきた場合のエラー

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/ 以下にもログが出力されます。

© Copyright 2021, Shiguredo Inc Created using Sphinx 4.2.0