シグナリング通知機能

概要

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

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

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

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

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

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

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

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

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

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

sora.conf の指定

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

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

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

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

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

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

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

  • sora.confsignaling_notifytrue で、認証ウェブフックの戻り値に signaling_notify の指定が無い場合

    • そのクライアントの signaling_notifytrue に設定されます

  • sora.confsignaling_notifyfalse で、認証ウェブフックの戻り値に signaling_notify の指定が無い場合

    • そのクライアントの signaling_notifyfalse に設定されます

  • sora.confsignaling_notifyfalse で、認証ウェブフックの戻り値に signaling_notifytrue の場合

    • そのクライアントの signaling_notifytrue に設定されます

  • sora.confsignaling_notifytrue で、認証ウェブフックの戻り値に signaling_notifyfalse の場合

    • そのクライアントの signaling_notifyfalse に設定されます

signaling_notify_client_id

sora.conf で signaling_notify_client_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 で JSON の値を指定すことで利用可能になります。

自分が新しく参加したときにはすでに参加しているクライアントの signaling_notify_metadata がリストで送られます。

この戻り値には signaling_notify_client_idsignaling_notify_connection_id の設定も影響するため、少し複雑になります。

sora.conf の指定

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

シグナリング接続時での指定

type: connect 時に signaling_notify_metadata にて JSON 型の好きな値を指定可能です。

{
    "type": "connect",
    "role": "sendonly",
    "channel_id": "bacon",
    "signaling_notify_metadata": {"spam": "egg"}
}

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

{
    "allowed": true,
    "signaling_notify_metadata": 10
}
  • signaling_notify_client_id = true

  • signaling_notify_connection_id = true

{
    "type": "notify",
    "event_type": "connection.created",
    "metadata": "bacon",
    "metadata_list": [
        {
            "client_id": "🐗🐗🐗🐗",
            "connection_id": "KKBFZTQXDD6H7FD2NYCQX8S474",
            "metadata": {"spam": "egg"}
        },
        {
            "client_id": "🐹🐹🐹🐹",
            "connection_id": "4D40YWH56N5S99QHJV6GAPNHB0",
            "metadata": 10
        }
    ]
}
  • {signaling_notify_client_id, false}

  • {signaling_notify_connection_id, true}

{
    "type": "notify",
    "event_type": "connection.created",
    "metadata": "bacon",
    "metadata_list": [
        {
            "connection_id": "KKBFZTQXDD6H7FD2NYCQX8S474",
            "metadata": {"spam": "egg"}
        },
        {
            "connection_id": "4D40YWH56N5S99QHJV6GAPNHB0",
            "metadata": 10
        }
    ]
}
  • signaling_notify_client_id = true

  • signaling_notify_connection_id = false

{
    "type": "notify",
    "event_type": "connection.created",
    "metadata": "bacon",
    "metadata_list": [
        {
            "client_id": "🐗🐗🐗🐗",
            "metadata": {"spam": "egg"}
        },
        {
            "client_id": "🐹🐹🐹🐹",
            "metadata": 10
        }
    ]
}
  • signaling_notify_client_id = false

  • signaling_notify_connection_id = false

{
    "type": "notify",
    "event_type": "connection.created",
    "metadata": "bacon",
    "metadata_list": [
        {"spam": "egg"},
        10
    ]
}

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

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

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

  • event_type

    • connection.createdconnection.updatedconnection.destroyed の 3 種類が入ります

    • connection.createdconnection.destroyed は全員に通知されます

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

  • role

    • string

    • sendrecv / sendonly / recvonly / upstream / downstream が入ります

  • minutes

    • integer

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

  • channel_connections

    • integer

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

  • channel_upstream_connections

    • integer

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

  • channel_downstream_connections

    • integer

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

  • client_id

    • string

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

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

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

    • sora.conf にて signaling_notify_client_idfalse にする事で無効にすることが可能です

  • connection_id

    • string

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

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

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

    • sora.conf にて signaling_notify_connection_idfalse にする事で無効にすることが可能です

  • 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_mediafalse にする事で無効にすることが可能です

  • metadata

    • json

    • sora.conf にて signaling_notify_metadatafalse にする事で無効にすることが可能です

  • metadata_list

    • [json]

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

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

        • signaling_notify_client_id = true

        • signaling_notify_connection_id = true

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

        • connection_id が含まれなくなります

        • signaling_notify_client_id = true

        • signaling_notify_connection_id = false

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

        • client_id が含まれなくなります

        • signaling_notify_client_id = false

        • signaling_notify_connection_id = true

      • json

        • connection_id と client_id が含まれなくなり metadata というキーもなくなります

        • signaling_notify_client_id = false

        • signaling_notify_connection_id = false

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

    • sora.conf にて signaling_notify_metadatafalse にする事で無効にすることが可能です

{
    "type": "notify",
    "event_type": "connection.created",
    "role": "sendonly",
    "minutes": 0,
    "channel_connections": 1,
    "channel_upstream_connections": 0,
    "channel_downstream_connections": 1,
    "audio": true,
    "video": true,
    "client_id": "4D40YWH56N5S99QHJV6GAPNHB0",
    "connection_id": "4D40YWH56N5S99QHJV6GAPNHB0",
    "metadata_list": [],
    "metadata": {
        "display_name": "時雨 小夜"
    }
}

"event_type": "connection.created"

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

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

"event_type": "connection.updated"

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

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

"event_type": "connection.destroyed"

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

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

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

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

"event_type": "spotlight.focused"

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

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

"event_type": "spotlight.unfocused"

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

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

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

  • event_type

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

  • channel_id

    • string

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

  • client_id

    • string

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

    • 配信者が居なくなった場合には null が入ります

  • connection_id

    • string

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

    • 配信者が居なくなった場合には null が入ります

  • spotlight_id

    • string

    • どのストリームが切り替わったかどうかが入ります

    • stream.id の値が入ります

  • audio

    • boolean

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

  • video

    • boolean

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

  • fixed

    • boolean

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

{
    "type": "notify",
    "event_type": "spotlight.focused",
    "client_id": "4D40YWH56N5S99QHJV6GAPNHB0",
    "spotlight_id": "spotlight-1",
    "audio": true,
    "video": true,
    "fixed": false
}
{
    "type": "notify",
    "event_type": "spotlight.unfocused",
    "client_id": "4D40YWH56N5S99QHJV6GAPNHB0",
    "spotlight_id": "spotlight-1",
    "audio": true,
    "video": true,
    "fixed": false
}

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

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

"event_type": "spotlight.changed"

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

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

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

  • event_type

    • spotlight.changed が入ります

  • client_id

    • string

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

    • 配信者が居なくなった場合には null が入ります

  • connection_id

    • string

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

    • 配信者が居なくなった場合には null が入ります

  • spotlight_id

    • string

    • どのストリームが切り替わったかどうかが入ります

    • stream.id の値が入ります

  • audio

    • boolean

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

  • video

    • boolean

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

  • fixed

    • boolean

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

{
    "type": "notify",
    "event_type": "spotlight.changed",
    "channel_id": "sora",
    "client_id": "4D40YWH56N5S99QHJV6GAPNHB0",
    "spotlight_id": "spotlight-1",
    "audio": true,
    "video": true,
    "fixed": false
}

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

これは実験的機能です

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

"event_type": "network.status"

この通知は 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,
}