シグナリング

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

仕様

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

connect

クライアントは Sora に WebSocket で接続して、以下の JSON を送ってください。 metadata はオプションです。

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

offer

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

{
    "type": "offer",
    "sdp": "<Offer 用 SDP>",
    "connection_id": "<ユニークな ID (UUID)>"
    "client_id": "<クライアントや認証サーバが指定した、または Sora が生成した文字列>"
}

重要

client_idsys.config にて allow_client_id_assignmenttrue にした時のみ指定可能です

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
}

ビデオコーデック指定

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

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

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

  • VP8

    • "VP8"

  • VP9

    • "VP9"

    • Safari では利用できません

  • 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 から 50000 です。500 を指定した場合は、500kbps がビットレートの最大値です。 10Mbps を最大値としたい場合は 10000 を指定してください。ただし 15Mbps より大きい値は現時点ではサポート外となります。

指定しない場合は 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 はクライアント側に依存します。

client_id の指定

sys.configallow_client_id_assignmenttrue に設定した場合は client_id を指定することが可能です。

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

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

"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 の接続が成功するまでの許容時間を超えた場合に出るエラーです。

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

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

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