シグナリング通知

概要

シグナリング通知は、Sora に接続情報をもたせることで、 クライアントの参加や離脱の情報をリアルタイムに通知する機能です。

シグナリング通知を利用することで実現可能なこと

  • 配信されているストリームに対してユーザー名を表示する

  • 新しくチャネルに参加したクライアントのユーザー名を通知する

  • 現在のネットワークの状態をクライアント画面に表示する

  • 離脱したユーザーの名前を表示する

シグナリング通知の有効 / 無効について

シグナリング通知はデフォルトで有効になっています。

シグナリング通知を無効にした場合はシグナリング通知が送られてこなくなります。

無効にするには、sora.conf でシグナリング通知の無効を指定するか、または、認証ウェブフックの戻り値で無効を指定する必要があります。

sora.conf での指定

sora.conf でシグナリング通知の有無を指定する方法です。

sora.conf で signaling_notify = false を指定することで、シグナリング通知が無効になります。

ただし、この値は認証ウェブフックの戻り値で上書きすることが可能です。

認証ウェブフックの戻り値での指定

認証ウェブフックの戻り値を利用して、クライアント毎に signaling_notify の true / false を指定する方法です。

認証ウェブフックの戻り値に {"signaling_notify": false} を指定することで、そのクライアントに対して signaling_notify を無効にすることができます。

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

認証ウェブフックの戻り値に signaling_notify の指定が無い場合は、sora.conf の signaling_notify の値が採用されます。

表 1. sora.conf と認証ウェブフックの戻り値の signaling_notify の組み合わせによるクライアントの signaling_notify の採用値

sora.conf の signaling_notify

認証ウェブフックの戻り値の signaling_notify

クライアントの signaling_notify の採用値

true

指定なし

true

true

false

false

true

true

true

false

指定なし

false

false

false

false

false

true

true

sora.conf によるシグナリング通知関連の設定

signaling_notify_client_id

sora.conf で signaling_notify_client_id = false を指定することで、シグナリング通知時にクライアント ID を含まなくなります。

signaling_notify_bundle_id

sora.conf で signaling_notify_bundle_id = false を指定することで、シグナリング通知時にバンドル ID を含まなくなります。

signaling_notify_connection_id

sora.conf で signaling_notify_connection_id = false を指定することで、シグナリング通知時にコネクション ID を含まなくなります。

signaling_notify_media

sora.conf で signaling_notify_media = false を指定することで、シグナリング通知時に音声や映像の情報を含まなくなります。

signaling_notify_metadata

signaling_notify_metadata は、ユーザーが参加や離脱したときに送られるシグナリング通知に含まれるメタデータです。

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

signaling_notify_metadata_ext

signaling_notify_metadata_ext は、ユーザーが参加や離脱したときに送られるシグナリング通知に含まれるメタデータを、API 経由で自由に変更できるようにします。

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

クライアントに送信される JSON の仕様

  • event_type

    • string

    • connection.created 、 connection.updated 、 connection.destroyed の 3 つの内のいずれかが入ります

    • connection.created と connection.destroyed は、全員に通知されます

    • connection.updated は、自身に通知されます

  • role

    • string

    • sendrecv / sendonly / recvonly が入ります

  • minutes

    • integer

    • その接続の接続経過時間 (分) が入ります

  • channel_connections

    • integer

    • そのチャネルの接続数が入ります

  • channel_sendonly_connections

    • integer

    • そのチャネルの sendonly 接続数が入ります

  • channel_recvonly_connections

    • integer

    • そのチャネルの recvonly 接続数が入ります

  • channel_sendrecv_connections

    • integer

    • そのチャネルの sendrecv 接続数が入ります

  • client_id

    • string

    • connection.created の場合は、参加してきたクライアントのクライアント ID が入ります

    • connection.destroyed の場合は、離脱したクライアントのクライアント ID が入ります

    • connection.updated の場合は、自身のクライアント ID が入ります

    • sora.conf で、 signaling_notify_client_id を false にすることで無効にすることが可能です

  • bundle_id

    • string

    • connection.created の場合は、参加してきたクライアントのバンドル ID が入ります

    • connection.destroyed の場合は、離脱したクライアントのバンドル ID が入ります

    • connection.updated の場合は、自身のバンドル ID が入ります

    • sora.conf で、 signaling_notify_bundle_id を false にすることで無効にすることが可能です

  • connection_id

    • string

    • connection.created の場合は、参加してきたクライアントのコネクション ID が入ります

    • connection.destroyed の場合は、離脱したクライアントのコネクション ID が入ります

    • connection.updated の場合は、自身のコネクション ID が入ります

    • sora.conf で、 signaling_notify_connection_id を false にすることで無効にすることが可能です

  • audio

    • boolean

    • connection.created の場合は、参加してきたクライアントの audio が有効かどうかが入ります

    • connection.destroyed の場合は、離脱したクライアントの audio が有効かどうかが入ります

    • connection.updated の場合は、自身の audio が有効かどうかが入ります

    • sora.conf で、 signaling_notify_media を false にすることで無効にすることが可能です

  • video

    • boolean

    • connection.created の場合は、参加してきたクライアントの video が有効かどうかが入ります

    • connection.destroyed の場合は、離脱したクライアントの video が有効かどうかが入ります

    • connection.updated の場合は、自身の video が有効かどうかが入ります

    • sora.conf で、 signaling_notify_media を false にすることで無効にすることが可能です

  • metadata

    • json

    • sora.conf で、 signaling_notify_metadata を false にすることで無効にすることが可能です

  • data

    • json 型のリスト

      • json 型の中身は、 signaling_notify_client_id や signaling_notify_bundle_id 、 signaling_notify_connection_id の設定により変化します

      • signaling_notify_client_id と signaling_notify_connection_id の設定値による json 型の中身は、下記の 表 2 をご確認ください

    • connection.created の場合のみこの値が入ります

    • sora.conf で、 signaling_notify_metadata を false にすることで無効にすることが可能です

表 2. signaling_notify_client_id および signaling_notify_connection_id の設定値による json 型の中身

signaling_notify_client_id

signaling_notify_bundle_id

signaling_notify_connection_id

json 型の中身

true

true

true

{"client_id": string, "bundle_id": string, "connection_id": string, "metadata": json}

false

true

true

{"bundle_id": string, "connection_id": string, "metadata": json}

true

false

true

{"client_id": string, "connection_id": string, "metadata": json}

true

true

false

{"client_id": string, "bundle_id": string, "metadata": json}

true

false

false

{"client_id": string, "metadata": json}

false

true

false

{"bundle_id": string, "metadata": json}

false

false

true

{"connection_id": string, "metadata": json}

false

false

false

{"metadata": json}

 
{
  "type": "notify",
  "event_type": "connection.created",
  "role": "recvonly",
  "minutes": 0,
  "channel_connections": 2,
  "channel_recvonly_connections": 1,
  "channel_sendonly_connections": 1,
  "channel_sendrecv_connections": 0,
  "client_id": "4DFFDF56RX3E3DPBCDSWPTCAV0",
  "bundle_id": "4DFFDF56RX3E3DPBCDSWPTCAV0",
  "connection_id": "4DFFDF56RX3E3DPBCDSWPTCAV0",
  "audio": true,
  "video": true,
  "metadata": {
      "diaplay_name": "小夜"
  },
  "data": [
      {
          "authz_metadata": {
              "diaplay_name": "時雨"
          },
          "client_id": "4SW2CB0E1D01S23W3G6JFCEN98",
          "bundle_id": "4SW2CB0E1D01S23W3G6JFCEN98",
          "connection_id": "4SW2CB0E1D01S23W3G6JFCEN98",
          "metadata": {
              "diaplay_name": "時雨"
          }
      }
  ],
  "authz_metadata": {
      "diaplay_name": "小夜"
  },
  "turn_transport_type": "udp"
}

"event_type": "connection.created"

この event_type は、参加しているチャネルに接続があった場合に、 signaling_notify を有効にしている全員に通知されます。

この通知を利用することで、他のクライアントが接続してきたことをクライアント側で把握することができます。

新規接続クライアントと bundle_id が等しいクライアントに対しては、このイベントは通知されません。 また通知 JSON の data の中身からも bundle_id が等しいクライアントは除外されます。

"event_type": "connection.updated"

この event_type は、クライアントごとに異なり、 1 分間隔で通知されます。

この通知を利用することで、現在クライアントの累計接続時間をクライアント側で把握することができます。

"event_type": "connection.destroyed"

この event_type は、参加しているチャネルに切断があった場合に、 signaling_notify を有効にしている全員に通知されます。

この通知を利用することで、他のクライアントが切断したことをクライアント側で把握することができます。

切断クライアントと bundle_id が等しいクライアントに対しては、このイベントは通知されません。

スポットライト機能のシグナリング通知

スポットライト機能を利用した場合のシグナリング通知は上記の connection.* とは別に spotlight.* が通知されます。

"event_type": "spotlight.focused"

この event_type は、参加しているチャネルの配信がフォーカスされた場合に、 signaling_notify を有効にしている全員に通知されます。

この通知を利用することで、配信が切り替わったことをクライアントが気付くことができるようになります。

フォーカスされたクライアントと bundle_id が等しいクライアントに対しては、このイベントは通知されません。

"event_type": "spotlight.unfocused"

この event_type は、参加しているチャネルの配信からフォーカスが外れた場合に、 signaling_notify を有効にしている全員に通知されます。

この通知を利用することで、配信が切り替わったことをクライアントが気付くことができるようになります。

フォーカスが外れたクライアントと bundle_id が等しいクライアントに対しては、このイベントは通知されません。

クライアントに送信される JSON の仕様

  • event_type

    • string

    • spotlight.focused または spotlight.unfocused が入ります

  • channel_id

    • string

    • 現在利用しているチャネル ID が入ります

  • client_id

    • string

    • どのクライアントに配信が切り替わったかが入ります

  • bundle_id

    • string

    • 切り替わった配信のバンドル ID が入ります

  • connection_id

    • string

    • どの接続に配信が切り替わったかが入ります

  • spotlight_number

    • integer

    • 現在のスポットライト数が入ります

  • audio

    • boolean

    • 切り替わった配信の audio が有効かどうかが入ります

  • video

    • boolean

    • 切り替わった配信の video が有効かどうかが入ります

  • fixed

    • boolean

    • 切り替わった配信が固定されているかどうかが入ります

{
    "type": "notify",
    "event_type": "spotlight.focused",
    "client_id": "4D40YWH56N5S99QHJV6GAPNHB0",
    "bundle_id": "4D40YWH56N5S99QHJV6GAPNHB0",
    "connection_id": "4D40YWH56N5S99QHJV6GAPNHB0",
    "spotlight_number": 3,
    "audio": true,
    "video": true,
    "fixed": false
}

{
    "type": "notify",
    "event_type": "spotlight.unfocused",
    "client_id": "4D40YWH56N5S99QHJV6GAPNHB0",
    "bundle_id": "4D40YWH56N5S99QHJV6GAPNHB0",
    "connection_id": "4D40YWH56N5S99QHJV6GAPNHB0",
    "spotlight_number": 3,
    "audio": true,
    "video": true,
    "fixed": false
}

録画のシグナリング通知

これは実験的機能です

録画のシグナリング通知は録画開始時には recording.started 、録画終了時には recording.stopped が通知されます。

Tip

role が recvonly のクライアントには通知されません。

sora.conf の設定

sora.conf の signaling_notify_recording で通知するかどうかを指定可能です。デフォルトは true で通知します。

signaling_notify_recording = false

"event_type": "recording.started"

録画開始時に通知されます。接続前にすでに StartRecording API が実行されていた場合は、 connection.created の後に通知されます。

{
    "type": "notify",
    "event_type": "recording.started",
    "client_id": "4D40YWH56N5S99QHJV6GAPNHB0",
    "bundle_id": "4D40YWH56N5S99QHJV6GAPNHB0",
    "connection_id": "4D40YWH56N5S99QHJV6GAPNHB0"
}

"event_type": "recording.stopped"

録画終了時に通知されます。StopRecording API が実行されたタイミング、または期限が切れたタイミングで通知されます。

{
    "type": "notify",
    "event_type": "recording.stopped",
    "client_id": "4D40YWH56N5S99QHJV6GAPNHB0",
    "bundle_id": "4D40YWH56N5S99QHJV6GAPNHB0",
    "connection_id": "4D40YWH56N5S99QHJV6GAPNHB0"
}

ネットワークのシグナリング通知

これは実験的機能です

ネットワークのシグナリング通知は、上記の connection.* とは別に network.* が通知されます。

"event_type": "network.status"

この event_type は、 signaling_notify を有効にしている全員に通知されます。

この通知を利用することで、ネットワークの状態をクライアントが把握することが可能になります。

送られる条件

現時点では映像を Sora に対して配信していることが通知の条件になります。

以下は通知されません

  • 受信のみ

  • 音声だけの配信

現在の判定材料

  • クライアント、またはサーバーからの再送要求の頻度

クライアントに送信される JSON の仕様

  • event_type

    • string

    • network.status が入ります

  • unstable_level

    • integer

    • ネットワークの不安定レベルが入ります

      • 0

        • とても安定したネットワークです

      • 1

        • 安定したネットワークです

      • 2

        • 不安定なネットワークです

      • 3

        • とても不安定なネットワークです

{
    "type": "notify",
    "event_type": "network.status",
    "unstable_level": 0,
}

シーケンス図

blockdiag クライアント Sora アプリケーション サーバー "type": "offer" "type": "answer" イベントウェブフック "type": "connection.created" 200 OK シグナリング通知 "type": "connection.craeted" イベントウェブフック "type": "connection.updated" 200 OK シグナリング通知 "type": "connection.updated" 認証成功 WebRTC 確立 接続から 1 分経過
© Copyright 2022, Shiguredo Inc Created using Sphinx 5.0.2