認証ウェブフック成功時の払い出し

概要

Sora では認証ウェブフック成功時に様々な値を外部の認証サーバーから払い出すことができます。

Sora は払い出された値を反映した状態でクライアントへの接続要求 "type": "offer" を送ります。

範囲表記

2..10 と書いてある場合 2 以上、10 以下の値を指定できることを表しています。

audio の払い出し

クライアントが指定してきた音声のコーデックやビットレートなどのパラメーターに対して、 認証サーバー側で新たに値を払い出すことで、上書きを行えます。

クライアントが指定してきた値を上書きできるため、 サーバー側でそれぞれのクライアントに対して、音声のコーデックやビットレートをコントロールできます。

指定項目一覧

  • audio

    • true または false が指定できます

注意

audio_codec_type や audio_bit_rate 等の audio 関連のパラメーターを指定する場合は、あわせて audio に true を指定する必要があります

  • audio_codec_type

    • "OPUS"

    • codec_type を指定しないこともできます

  • audio_bit_rate

    • 6..510

    • 単位は kbps です

    • デフォルトで最適なビットレートが選択されるようになっているため指定する必要はありません

  • audio_opus_params

払い出し例

この機能を使用する場合は、認証成功時のレスポンス JSON に audio や audio_codec_type や audio_bit_rate を指定してください。 ここで使用できるのはシグナリングの "type": "connect" 時に指定できる audio の値です。

{
  "allowed": true,
  "audio": true,
  "audio_codec_type": "OPUS",
  "audio_bit_rate": 64
}

video の払い出し

クライアントが指定してきた映像のコーデックやビットレートなどのパラメーターに対して、 認証サーバー側で新たに値を払い出すことで、上書きを行えます。

クライアントが指定してきた値を上書きできるため、 サーバー側でそれぞれのクライアントに対して、映像のコーデックやビットレートを指定できます。

指定項目一覧

  • "video"

    • true または false が指定できます

注意

video_codec_type や video_bit_rate 等の video 関連のパラメーターを指定する場合は、あわせて video に true を指定する必要があります

  • "video_codec_type"

    • この項目を指定する場合は "video": true をあわせて指定してください

    • 文字列で指定できます

    • "VP8"

    • "VP9"

    • "AV1"

    • "H264"

    • "H265"

      • sora.conf にて h265 を true にしている必要があります

    • codec_type を指定しないこともできます

  • "video_bit_rate"

    • 1..30000

      • サポートされている値は 1..15000 です

    • 単位は kbps です

    • video_bit_rate を指定しないこともできます

  • video_vp9_params

  • video_av1_params

  • video_h264_params

  • video_h265_params

払い出し例

この機能を使用する場合は、認証成功時のレスポンス JSON に video や video_codec_type や video_bit_rate を指定してください。 ここで使用できるのはシグナリングの "type": "connect" 時に指定できる video の値です。

{
  "allowed": true,
  "video": true,
  "video_codec_type": "VP9",
  "video_bit_rate": 1000
}

client_id の払い出し

Sora は認証成功時の戻り値に client_id を認証サーバーから返すことができます。

シグナリング接続時にも、 認証成功時の戻り値にも client_id を指定しない場合は connection_id と同じ値が client_id に割りあてられます。

{
  "allowed": true,
  "client_id": "spam"
}

  • client_id

    • 1 から 255 の長さの文字列

bundle_id の払い出し

Sora は認証成功時の戻り値に bundle_id を認証サーバーから返すことができます。

bundle_id を指定した場合、マルチストリーム利用時に bundle_id の値が同じ接続からの音声や映像、メッセージング、シグナリング通知を受信しなくなります。

シグナリング接続時にも、 認証成功時の戻り値にも bundle_id を指定しない場合は connection_id と同じ値が bundle_id に割りあてられます。

{
  "allowed": true,
  "bundle_id": "spam"
}

  • bundle_id

    • 1 から 255 バイトの文字列

simulcast / simulcast_rid の払い出し

Sora は、認証成功時のタイミングで接続単位での simulcast と simulcast_rid の値を認証サーバーから払い出すことができます。

{
  "allowed": true,
  "simulcast": true
}

{
  "allowed": true,
  "simulcast": true,
  "simulcast_rid": "r0"
}

この値は sora.conf の default_simulcast_rid の値を上書きします。

simulcast_encodings の払い出し

Sora は、認証成功時のタイミングで接続単位での simulcast_encodings の値を認証サーバーから払い出すことができます。

{
  "allowed": true,
  "simulcast_encodings": [
    {"rid": "r0", "active": true, "scaleResolutionDownBy": 2.0, "maxFramerate": 1.0},
    {"rid": "r1", "active": true, "scaleResolutionDownBy": 2.0, "maxFramerate": 10.0},
    {"rid": "r2", "active": true, "scaleResolutionDownBy": 1.0, "maxFramerate": 30.0}
  ]
}

詳細については サイマルキャスト の 映像のエンコーディングパラメーターのカスタマイズ をご確認ください。

simulcast_codecs の払い出し

Sora は、認証成功時のタイミングで接続単位での simulcast_codecs の値を認証サーバーから払い出すことができます。

{
  "allowed": true,
  "simulcast": true,
  "simulcast_multicodec": true,
  "simulcast_codecs": [
    {"rid": "r0", "codec_type": "AV1", "codec_params": {"profile": 0}},
    {"rid": "r1", "codec_type": "AV1", "codec_params": {"profile": 0}},
    {"rid": "r2", "codec_type": "VP9", "codec_params": {"profile_id": 0}}
  ]
}

詳細については サイマルキャストマルチコーデック をご確認ください。

spotlight_encodings の払い出し

Sora は、認証成功時のタイミングで接続単位での spotlight_encodings の値を認証サーバーから払い出すことができます。

{
  "allowed": true,
  "spotlight_encodings": [
    {"rid": "r0", "active": true, "scaleResolutionDownBy": 4.0, "maxFramerate": 1.0},
    {"rid": "r1", "active": true, "scaleResolutionDownBy": 1.0, "maxFramerate": 10.0},
    {"rid": "r2", "active": false}
  ]
}

詳細については スポットライト機能 の スポットライト利用時の映像のエンコーディングパラメーターのカスタマイズ をご確認ください。

spotlight の払い出し

Sora は、認証成功時のタイミングで接続単位での spotlight の値を認証サーバーから払い出すことができます。

{
  "allowed": true,
  "spotlight": true
}

spotlight_number の払い出し

警告

この払い出しは非推奨です。 セッション単位での払い出し spotlight_number を利用してください。

Sora は、認証成功時のタイミングで接続単位での spotlight_number の値を認証サーバーから払い出すことができます。

spotlight_number はセッションに参加している全てのクライアントが同一の値を指定する必要があります。

{
  "allowed": true,
  "spotlight": true,
  "spotlight_number": 3
}

data_channel_signaling の払い出し

Sora は、認証成功時のタイミングで接続単位での data_channel_signaling の値を認証サーバーから払い出すことができます。

{
  "allowed": true,
  "data_channel_signaling": true
}

この値は "type": "connect" の data_channel_signaling や sora.conf の default_data_channel_signaling の値を上書きします。

認証成功時にクライアントが受け取る JSON

{
  "type": "offer",
  "sdp": "<SDP>",
  "data_channel_signaling": true,
  "ignore_disconnect_websocket": false
}

ignore_disconnect_websocket の払い出し

Sora は、認証成功時のタイミングで接続単位での ignore_disconnect_websocket の値を認証サーバーから払い出すことができます。

{
  "allowed": true,
  "ignore_disconnect_websocket": true
}

この値は "type": "connect" の ignore_disconnect_websocket や sora.conf の default_ignore_disconnect_websocket の値を上書きします。

ただし data_channel_signaling が true の時のみ、この値は有効になります。

認証成功時にクライアントが受け取る JSON

data_channel_signaling が有効な場合、 "type": "switched" が送られる際に ignore_disconnect_websocket も送られます。

{
  "type": "switched",
  "ignore_disconnect_websocket": "<Boolean>",
}

data_channels の払い出し

Sora は、認証成功時のタイミングで接続単位での data_channels の値を認証サーバーから払い出すことができます。

{
  "allowed": true,
  "data_channels": [
    {
      "label": "#spam",
      "max_packet_life_time": 5000,
      "ordered": true,
      "protocol": "efg",
      "compress": false,
      "direction": "sendonly"
    },
    {
      "label": "#egg",
      "max_retransmits": 0,
      "ordered": false,
      "protocol": "abc",
      "compress": false,
      "direction": "recvonly"
    }
  ]
}

data_channels の詳細仕様は data_channels 仕様 をご確認ください。

metadata の払い出し

Sora は、認証成功時のタイミングで metadata という値を認証サーバーから払い出すことができます。

{
  "allowed": true,
  "metadata": {"spam": "egg"}
}

認証サーバーが認証成功時に metadata を含めた場合、クライアントへ送る "type": "offer" に metadata をそのまま送ります。

この機能を使うことで、認証成功のタイミングでユーザー毎に任意の値を送ることができます。

認証成功時にクライアントが受け取る JSON

認証成功の場合は Offer 送信時の JSON に metadata が含められます。

{
  "type": "offer",
  "sdp": "<SDP>",
  "metadata": {"spam": "egg"}
}

event_metadata の払い出し

重要

event_metadata はクライアントには送られません

Sora は、認証成功時のタイミングで event_metadata という値を認証サーバーから払い出すことができます。

認証サーバーが認証成功時に event_metadata を含めた場合、 イベントウェブフックリクエスト送信時に event_metadata という項目が追加されます。

{
  "allowed": true,
  "event_metadata": {"pk": 1}
}

event_metadata はクライアントに知られることのない値です。 Sora イベントウェブフックリクエスト送信先のサーバーのみが知り得る値となります。

使用例

この event_metadata の値は、クライアントに知られることはありません。そのためユーザー ID を直接入れておくという仕組みも使用できます。

こうすることで通知の際、サーバー側がユーザーの判定をしやすくなります。

シグナリング経由での通知機能の払い出し

Sora は、認証成功時のタイミングで signaling_notify という値を認証サーバーから払い出すことができます。

{
  "allowed": true,
  "signaling_notify": true
}

signaling_notify の値を返すことで、クライアントごとにシグナリング通知を受け取るかどうかを指定できるようになります。

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

シグナリング経由での通知機能を利用したメタデータの払い出し

Sora は、認証成功時のタイミングで signaling_notify_metadata という値を認証サーバーから払い出すことができます。

ここに値を指定することで、参加時や離脱時に外の参加者に情報を通知できます。

{
  "allowed": true,
  "signaling_notify_metadata": {
      "username": "spam"
  }
}

詳細は シグナリング通知メタデータ をご確認ください。

シグナリング通知メタデータ拡張機能の初期値払い出し

Sora は、認証成功時のタイミングで signaling_notify_metadata_ext という値を認証サーバーから払い出すことができます。

払い出しを利用する場合はシグナリング通知メタデータ拡張が有効である必要があります。

払い出した値がシグナリング通知メタデータ拡張の初期値として使用されます。

{
  "allowed": true,
  "signaling_notify_metadata_ext": {
    "mute": true
  }
}

録画ブロック機能の払い出し

重要

録画ブロック機能は新しい録画機能(セッション単位)でのみ利用できます。

Sora は、認証成功時のタイミングで recording_block という値を認証サーバーから払い出すことができます。

ここに true を設定することで、録画有効時にその接続の録画をブロックすることができます。 録画がブロックされた接続の録画ファイルは出力されません。

未指定の場合は recording_block は false として扱われます。

{
  "allowed": true,
  "recording_block": true
}

cluster_affinity の払い出し

クラスターリレー機能利用時に cluster_affinity を指定することで、コネクション単位で同一ノードへの集約を制御できます。 この値は sora.conf の default_cluster_affinity の値を上書きします。

cluster_affinity を true に指定した場合、そのセッションでは同一ノードへの集約を試みます。

{
  "allowed": true,
  "cluster_affinity": true
}

cluster_affinity を false に指定した場合、そのセッションでは同一ノードへの集約を行わず、 接続したノードでの WebRTC 確立を試みます。

{
  "allowed": true,
  "cluster_affinity": false
}

connection_lifetime の払い出し

Sora は、認証成功時のタイミングで connection_lifetime を認証サーバーから払い出すことができます。

例えば 3600 を指定すると 1 時間 (3600 秒) 後に接続が切断されます。

{
  "allowed": true,
  "connection_lifetime": 3600
}

  • 秒 で指定してください

  • 最大 2,592,000 秒 (30 日) まで指定できます

  • コネクション生成後に変更することはできません

  • connection_lifetime が未指定の場合は 無制限 です

  • connection.destroyed の reason に lifetime_expired が入ります

  • コネクションのライフタイムが終了すると、コネクションが破棄され切断します

  • コネクションのライフタイムが終了すると、コネクションウェブフック connection.destroyed が送信されます

  • コネクションのライフタイムよりセッションのライフタイムが優先されます

playout_delay_min_delay と playout_delay_max_delay の払い出し

Sora は、認証成功時のタイミングで playout_delay_min_delay と playout_delay_max_delay を認証サーバーから払い出すことができます。 プレイアウト遅延機能をコネクションに指定する場合は、 playout_delay_min_delay と playout_delay_max_delay の両方を指定する必要があります。

{
  "allowed": true,
  "playout_delay_min_delay": 0,
  "playout_delay_max_delay": 100
}

この値は sora.conf の default_playout_delay_min_delay と default_playout_delay_max_delay の値を上書きします。

0..40950 の範囲で指定します。単位はミリ秒です。

この機能を利用することで、コネクション毎にプレイアウト遅延を指定できます。

詳細は プレイアウト遅延機能 をご確認ください。

ipv4_address と ipv6_address の払い出し

Sora は、認証成功時のタイミングで ipv4_address または ipv6_address を認証サーバーから払い出すことができます。 ipv4_address と ipv6_address は片方だけでも、両方返しても問題ありません。

{
  "allowed": true,
  "ipv4_address": "192.0.2.10",
  "ipv6_address": "2001:0DB8::10"
}

この値は SDP の offer 時の a=candidate と TURN-UDP と TURN-TCP の URL の払い出しに使用されます。

sora.conf の ipv4_address と ipv6_address のがこの戻り値で上書きされます。 指定する IP アドレスを間違えると繋がらなくなるため、使用には注意してください。

この機能を使用することでコネクション毎に経路を指定できます。

turn_fqdn 払い出し

Sora は、認証成功時のタイミングで接続単位での turn_fqdn の値を認証サーバーから払い出すことができます。

{
  "allowed": true,
  "turn_fqdn": "sora-turn.example.com"
}

この値は sora.conf の turn_fqdn の値を上書きします。

指定する FQDN を間違えると繋がらなくなるため、使用には注意してください。

turn_tls_fqdn の 払い出し

Sora は、認証成功時のタイミングで接続単位での turn_tls_fqdn の値を認証サーバーから払い出すことができます。

{
  "allowed": true,
  "turn_tls_fqdn": "sora-turn.example.com"
}

この値は sora.conf の turn_tls_fqdn の値を上書きします。指定する FQDN を間違えると繋がらなくなるため、使用には注意してください。

rtc_stats の払い出し

Sora は、認証成功時のタイミングで接続単位での rtc_stats の値を認証サーバーから払い出すことができます。

{
  "allowed": true,
  "rtc_stats": true
}

この値は sora.conf の default_rtc_stats の値を上書きします。

user_agent_stats の払い出し

注意

この設定は 2025 年 6 月に廃止されます。 rtc_stats の払い出し を利用してください。

Sora は、認証成功時のタイミングで接続単位での user_agent_stats の値を認証サーバーから払い出すことができます。

{
  "allowed": true,
  "user_agent_stats": true
}

この値は sora.conf の user_agent_stats の値を上書きします。

audio_streaming_language_code の払い出し

Sora は、認証成功時のタイミングで音声ストリーミングのランゲージコードの値を認証サーバーから払い出すことができます。

{
  "allowed": true,
  "audio_streaming_language_code": "ja-JP"
}

この値は接続時の audio_streaming_language_code と sora.conf の default_audio_streaming_language_code の値を上書きします。

stats_exporter の払い出し

Sora は、認証成功時のタイミングで統計エクスポートをするかどうかの値を認証サーバから払い出すことができます。

{
  "allowed": true,
  "stats_exporter": false
}

この値は sora.conf の default_stats_exporter の値を上書きします。

turn_tcp_only / turn_tls_only の払い出し

重要

この設定は検証時のみ利用してください。

Sora は、認証成功時のタイミングで接続単位での turn_tcp_only または turn_tls_only の値を認証サーバーから払い出すことができます。

{
  "allowed": true,
  "turn_tcp_only": true
}

{
  "allowed": true,
  "turn_tls_only": true
}

この値は sora.conf の turn_tcp_only や turn_tls_only の値を上書きします。

rtp_packet_loss_simulator_incoming / rtp_packet_loss_simulator_outgoing の払い出し

重要

この設定は検証時のみ利用してください。

範囲:

0..100

Sora は、認証成功時のタイミングで接続単位での RTP パケットロスシミュレーターの値を認証サーバーから払い出すことができます。

{
  "allowed": true,
  "rtp_packet_loss_simulator_outgoing": 5
}

{
  "allowed": true,
  "rtp_packet_loss_simulator_incoming": 5
}

この値は sora.conf の rtp_packet_loss_simulator_incoming や rtp_packet_loss_simulator_outgoing の値を上書きします。

シーケンス図

        sequenceDiagram
    participant C as クライアント
    participant S as Sora
    participant A as アプリケーションサーバー
    C->>+S: "type": "connect"
    S->>+A: 認証ウェブフック
    note right of A: ここで払い出しする
    A-->>-S: 200 OK<br>"allowed": true
    S-)-C: "type": "offer"
    C-)S: "type": "answer"
    note over C,S: ICE 確立
    note over C,S: DTLS 確立
    note over C,S: WebRTC 確立
© Copyright 2024, Shiguredo Inc Created using Sphinx 8.1.3