シグナリング

WebRTC SFU Sora のシグナリングは WebSocket を使用します。

仕様

Sora のシグナリングは、Sora からクライアントへ Offer を送ります。

connect

クライアントは Sora に WebSocket で接続して、以下の JSON を送ります。

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

offer

認証が成功すると Sora は以下の JSON をクライアントに送ります。

{
    "type": "offer",
    "sdp": "<Offer 用 SDP>",
    "client_id": "<ユニークな ID>"
}

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

disconnect

クライアントからこのメッセージを送ると Sora は WebSocket を切断し、WebRTC 側も終了します。切断する際はこの API を叩くようにしてください。

{
    "type": "disconnect"
}

"type": "connect"

metadata

metadata は必須ではありません。これは認証するための判断材料として使用することができます。

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

視聴メディアの選択

重要

Chrome を使用している場合、配信者が音声だけで視聴者が音声と映像を指定した場合正常に配信されません。音声のみを配信する場合は、視聴も音声のみを指定することで回避可能です。これは Chrome の仕様によるものです。

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

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

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

{
    "type": "connect",
    "role": "downstream",
    "channel_id": "Spam",
    "metadata": "1234abcd",
    "video": false
}

ビデオコーデック指定

重要

Firefox の場合、VP9 は Firefox 51 から使用可能です

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

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

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

  • VP8
    • "VP8"
  • VP9
    • "VP9"
  • H.264
    • "H264"
{
    "type": "connect",
    "role": "upstream",
    "channel_id": "Spam",
    "metadata": "1234abcd",
    "video": {
        "codec_type":"VP9"
    }
}

ビデオビットレート指定

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

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

指定できる値は 1 から 30000 です。500 を指定した場合は、500kbps がビットレートの最大値です。 10Mbps を最大値としたい場合は 10000 を指定してください。ただし 5Mbps より大きい値は現時点ではサポート外となります。

指定しない場合は sys.config の default_video_bit_rate に指定した値が採用されます。

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

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

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

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

  • OPUS
    • "OPUS"
  • PCMU
    • "PCMU"
{
    "type": "connect",
    "role": "upstream",
    "channel_id": "Spam",
    "metadata": "1234abcd",
    "video": {
        "codec_type":"VP9"
    },
    "audio": {
        "codec_type":"PCMU"
    }
}

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

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

{
    "type": "connect",
    "role": "upstream",
    "channel_id": "Spam",
    "metadata": "1234abcd",
    "audio": {
        "codec_type": "OPUS",
        "bit_rate": 64
    }
}

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

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

"type": "ping"

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

{
    "type": "pong"
}

このの Ping/Pong が失敗すると Sora は接続を破棄します。

"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 から 5 の範囲外、または他の参加者と異なる値の場合のエラー
FAILURE-SDP-PARSE 不正な SDP の場合のエラー
FAILURE-MISSING-SDP type: answer に期待している 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 を送ってきた場合のエラー
INVALID-VIDEO-FORMAT video: に指定した値が間違っている場合のエラー
INVALID-AUDIO-FORMAT audio: に指定した値が間違っている場合のエラー
MISSING-UPSTREAMS マルチストリーム利用時に配信者がいないのに視聴者が接続した場合のエラー
EXCEED-MAX-CONNECTIONS ライセンスの接続数を超えた接続が来た場合のエラー
CLIENT-ERROR クライアントが想定外の動作をした場合のエラー
BAD-FINGERPRINT 証明書検証が失敗した場合のエラー
ANSWER-TIMEOUT-ERROR 30 秒以内に type: answer を返さなかった場合のエラー
SIGNALING-INTERNAL-ERROR シグナリング内部エラー
TRANSPORT-INTERNAL-ERROR 通信内部エラー
ROUTER-INTERNAL-ERROR 通信内部エラー
INTERNAL-ERROR 内部エラー

AUTHENTICATION-FAILURE

このエラーはクライアントに通知されることはなく、ログにしか出力されません。

CONNECTION-CREATED-WAIT-TIMEOUT-ERROR

シグナリングを実行してから Sora と WebRTC の接続が成功するまでの許容時間を超えた場合に出るエラーです。

この許容時間はデフォルトでは 5 秒に設定されており、この値は sys.config の設定で変更が可能です。

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

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