シグナリング通知機能

概要

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

この機能を利用することで実現可能なこと

  • 配信されているストリームに対してユーザ名を表示する
  • 新しくチャネルに参加したクライアントのユーザ名を通知する

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

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

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

無効にするには sys.config で指定するか、認証ウェブフックの戻り値で指定をする必要があります。

sys.config の指定

sys.config で {signaling_notify, false} を指定することで、シグナリング通知機能が無効になります。

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

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

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

{
    "allowed": true,
    "signaling_notify": true,
    "signaling_notify_metadata": {
        "username": "時雨 小夜",
        "organization": "時雨堂"
    }
}

signaling_notify

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

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

  • sys.configsignaling_notifytrue で、認証ウェブフックの戻り値に signaling_notify の指定が無い場合
    • そのクライアントの signaling_notifytrue に設定されます
  • sys.configsignaling_notifyfalse で、認証ウェブフックの戻り値に signaling_notify の指定が無い場合
    • そのクライアントの signaling_notifyfalse に設定されます
  • sys.configsignaling_notifyfalse で、認証ウェブフックの戻り値に signaling_notifytrue の場合
    • そのクライアントの signaling_notifytrue に設定されます
  • sys.configsignaling_notifytrue で、認証ウェブフックの戻り値に signaling_notifyfalse の場合
    • そのクライアントの signaling_notifyfalse に設定されます

signaling_notify_metadata

signaling_notify_metadata はユーザが参加したときや離脱したときに送られる signaling_notify に自由に値を入れることができる仕組みです。

認証ウェブフックの戻り値に signaling_notify_metadata で JSON を指定することで利用可能になります。

自分が新しく参加したときにはすでに参加しているクライアントの signaling_notify_metadata がリストで送られきます。 その場合は以下のような JSON になります

{
    "type": "notify",
    "metadata_list": [
        "ここに指定したメタデータがリストで入ります"
    ]
}

すでに参加しており、他のクライアントが参加してきた場合や離脱した場合は以下の通りになります。

{
"type": "notify", "metadata": {}

}

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

  • event_type
    • connection.createdconnection.updatedconnection.destroyed の 3 種類が入ります
    • connection.createdconnection.updated は全員に通知されます
    • connection.updated は自身に通知されます
  • role
    • upstream または downstream が入ります
  • minutes
    • そのクライアントの接続経過時間 (分) が入ります
  • channel_connections
    • そのチャネルの接続数が入ります
  • channel_upstream_connections
    • そのチャネルの upstream 接続数が入ります
  • channel_downstream_connections
    • そのチャネルの downstream 接続数が入ります
  • client_id
    • connection.created の場合は参加してきたクライアントのクライアント ID が入ります
    • connection.destroyed の場合は離脱したクライアントのクライアント ID が入ります
    • connection.updated の場合は自身のクライアント ID が入ります
    • sys.config にて {signaling_notify_client_id, false} で無効にすることが可能です
  • audio
    • connection.created の場合は参加してきたクライアントの audio が有効かどうかが入ります
    • connection.destroyed の場合は離脱したクライアントの audio が有効かどうかが入ります
    • connection.updated の場合は自身の audio が有効かどうかが入ります
    • sys.config にて {signaling_notify_media, false} で無効にすることが可能です
  • video
    • connection.created の場合は参加してきたクライアントの video が有効かどうかが入ります
    • connection.destroyed の場合は離脱したクライアントの video が有効かどうかが入ります
    • connection.updated の場合は自身の video が有効かどうかが入ります
    • sys.config にて {signaling_notify_media, false} で無効にすることが可能です
  • metadata
    • sys.config にて {signaling_notify_metadata, false} で無効にすることが可能です
  • metadata_list
    • connection.created の場合のみこの値が入ります
    • sys.config にて {signaling_notify_metadata, false} で無効にすることが可能です
{
    "type": "notify",
    "event_type": "connection.created",
    "role": "upstream",
    "minutes": 0,
    "channel_connections": 1,
    "channel_upstream_connections": 0,
    "channel_downstream_connections": 1,
    "audio": true,
    "video": true,
    "client_id": "93645887-48b1-4804-9ce7-5f8331e0be70",
    "metadata": {
        "display_name": "時雨 小夜"
    }
}

"event_type": "connection.created"

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

この通知を利用することで upstream が配信を開始したことなどをクライアント側で把握することができます。

"event_type": "connection.updated"

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

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

"event_type": "connection.destroyed"

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

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

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

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

"event_type": "spotlight.changed"

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

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

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

  • event_type
    • spotlight.changed が入ります
  • channel_id
    • 現在利用しているチャネル ID が入ります
  • client_id
    • どのクライアントに配信が切り替わったかどうかが入ります
    • 配信者が居なくなった場合には null が入ります
  • spotlight_id
    • どのストリームが切り替わったかどうかが入ります
    • stream.id の値が入ります
  • audio
    • 切り替わった配信の audio が有効かどうかが入ります
  • video
    • 切り替わった配信の video が有効かどうかが入ります
  • fixed
    • 切り替わった配信が固定されているかどうかが入ります
{
    "type": "notify",
    "event_type": "spotlight.changed",
    "channel_id": "sora",
    "client_id": "d3cae3e6-d9ce-4f60-b04b-ad905a16da03",
    "spotlight_id": "spotlight-1",
    "audio": true,
    "video": true,
    "fixed": false
}