シグナリング通知¶
概要¶
シグナリング通知は、Sora がシグナリング利用に接続する WebSocket やデータチャネルを利用して、 自身の状態や、他のコネクションの状態をリアルタイムに通知する機能です
シグナリング通知を利用することで実現できること¶
配信されているストリームに対してユーザー名を表示する
新しくチャネルに参加したクライアントのユーザー名を通知する
現在のネットワークの状態をクライアント画面に表示する
離脱したユーザーの名前を表示する
録画の開始や停止をクライアントに通知する
スポットライト機能を利用した場合に、配信が切り替わったことをクライアントに通知する
シグナリング通知の有効 / 無効について¶
シグナリング通知はデフォルトで有効になっています。
シグナリング通知を無効にした場合はシグナリング通知が送られてこなくなります。
無効にするには、 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 の値が採用されます。
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¶
- デフォルト:
true
sora.conf
で signaling_notify_client_id = false
を指定することで、シグナリング通知時にクライアント ID を含まなくなります。
ただし スポットライト機能のシグナリング通知 には常にクライアント ID が含まれます。
signaling_notify_bundle_id¶
- デフォルト:
true
sora.conf
で signaling_notify_bundle_id = false
を指定することで、シグナリング通知時にバンドル ID を含まなくなります。
ただし スポットライト機能のシグナリング通知 には常にバンドル ID が含まれます。
signaling_notify_connection_id¶
- デフォルト:
true
sora.conf
で signaling_notify_connection_id = false
を指定することで、シグナリング通知時にコネクション ID を含まなくなります。
ただし スポットライト機能のシグナリング通知 、 転送フィルターのシグナリング通知 、 RTP ストリーム停止と再開のシグナリング通知 には常にコネクション ID が含まれます。
signaling_notify_connection_created_timestamp¶
- デフォルト:
true
これは event_type
が connection.created
の時のみ有効になります。
sora.conf
で signaling_notify_connection_created_timestamp = false
を指定することで、シグナリング通知時にコネクション生成時刻を含まなくなります。
signaling_notify_media¶
- デフォルト:
true
sora.conf
で signaling_notify_media = false
を指定することで、シグナリング通知時に音声や映像の情報を含まなくなります。
ただし スポットライト機能のシグナリング通知 には常に音声や映像の情報が含まれます。
signaling_notify_metadata¶
- デフォルト:
true
signaling_notify_metadata
は、ユーザーが参加や離脱したときに送られるシグナリング通知に含まれるメタデータです。
シグナリング通知メタデータの詳細は シグナリング通知メタデータ をご確認ください。
sora.conf
で signaling_notify_metadata = false
を指定すると コネクションのシグナリング通知 でシグナリング通知メタデータおよびシグナリング通知メタデータ拡張の情報を含まなくなります。
signaling_notify_metadata_ext¶
- デフォルト:
false
signaling_notify_metadata_ext
は、ユーザーが参加や離脱したときに送られるシグナリング通知に含まれるメタデータを、API 経由で自由に変更できるようにします。
シグナリング通知メタデータ拡張の詳細は シグナリング通知メタデータ拡張機能 をご確認ください。
signaling_notify_ice_connection_state¶
- デフォルト:
false
signaling_notify_ice_connection_state
は、ICE 接続の状態が変化したときに送られるシグナリング通知に含まれるメタデータです。
自分を含むセッション参加者全員に通知されます。
ICE コネクションステートの詳細は ICE コネクションステート機能 をご確認ください。
コネクションのシグナリング通知¶
クライアントに送信される JSON の仕様¶
event_type
string
connection.created
、connection.updated
、connection.destroyed
の 3 つの内のいずれかが入りますconnection.created
とconnection.destroyed
は、全員に通知されますconnection.updated
は、自身に通知されます
timestamp
string
RFC3339 (マイクロ秒)
connection.created
の時に、コネクション生成時間が含まれます
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, authz_metadata, auth_metadata
json
シグナリング通知メタデータ で利用する項目です。
sora.conf
で、signaling_notify_metadata
をfalse
にすることでこの値は含まれなくなります
data
json 型のリスト
json 型の中身は、以下の sora.conf の設定により変化します
上記の設定が全て
false
になり、通知する値がなくなった場合、この値は含まれなくなります設定値による json 型の中身は、 sora.conf の設定内容と connection.created 出力の例 をご確認ください
新規でチャネルに接続した際に、すでにチャネルに参加している接続一覧の情報がはいります
チャネル内で 1 つめの接続である場合は、この値は空のリストになります
接続を開始して初回の
connection.created
の場合のみこの値が入ります
sora.conf の設定内容と connection.created 出力の例¶
data
に含まれる項目を例に sora.conf の設定内容と connection.created
出力の例を示します。
デフォルト¶
デフォルトでは全て true
であり、値が通知されます。
# 全てコメントアウトされているため、デフォルト値が適用される
# signaling_notify_client_id = false
# signaling_notify_bundle_id = false
# signaling_notify_connection_id = false
# signaling_notify_connection_created_timestamp = false
# signaling_notify_metadata = false
一部項目を省略しています
{
"type": "notify",
"event_type": "connection.created",
"session_id": "P24NZ0AX2D6FX15VFHEGBXGMEW",
"bundle_id": "WHSSBG91XS7NXEVYY0F51YFEEW",
"client_id": "client3",
"connection_id": "WHSSBG91XS7NXEVYY0F51YFEEW",
"timestamp": "2023-12-18T07:12:11.876287Z",
"authn_metadata": {"spam": "egg"},
"authz_metadata": "bacon",
"metadata": "bacon",
"data": [
{
"bundle_id": "KKBFZTQXDD6H7FD2NYCQX8S474",
"client_id": "client1",
"connection_id": "KKBFZTQXDD6H7FD2NYCQX8S474",
"timestamp": "2023-12-18T07:11:56.585769Z",
"authn_metadata": 10,
"authz_metadata": {"authz": true},
"metadata": {"authz": true}
},
{
"bundle_id": "4D40YWH56N5S99QHJV6GAPNHB0",
"client_id": "client2",
"connection_id": "4D40YWH56N5S99QHJV6GAPNHB0",
"timestamp": "2023-12-18T07:11:58.685769Z",
"authn_metadata": 10,
"metadata": 10
}
]
}
client_id を通知しない¶
signaling_notify_client_id = false
を指定すると、client_id が含まれなくなります。
signaling_notify_client_id = false
# signaling_notify_bundle_id = false
# signaling_notify_connection_id = false
# signaling_notify_connection_created_timestamp = false
# signaling_notify_metadata = false
一部項目を省略しています
{
"type": "notify",
"event_type": "connection.created",
"session_id": "P24NZ0AX2D6FX15VFHEGBXGMEW",
"bundle_id": "WHSSBG91XS7NXEVYY0F51YFEEW",
"connection_id": "WHSSBG91XS7NXEVYY0F51YFEEW",
"timestamp": "2023-12-18T07:12:11.876287Z",
"authn_metadata": {"spam": "egg"},
"authz_metadata": "bacon",
"metadata": "bacon",
"data": [
{
"bundle_id": "KKBFZTQXDD6H7FD2NYCQX8S474",
"connection_id": "KKBFZTQXDD6H7FD2NYCQX8S474",
"timestamp": "2023-12-18T07:11:56.585769Z",
"authn_metadata": 10,
"authz_metadata": {"authz": true},
"metadata": {"authz": true}
},
{
"bundle_id": "4D40YWH56N5S99QHJV6GAPNHB0",
"connection_id": "4D40YWH56N5S99QHJV6GAPNHB0",
"timestamp": "2023-12-18T07:11:58.685769Z",
"authn_metadata": 10,
"metadata": 10
}
]
}
metadata を通知しない¶
signaling_notify_metadata = false
を指定すると metadata
, authz_metadata
, authn_metadata
が含まれなくなります。
# signaling_notify_client_id = false
# signaling_notify_bundle_id = false
# signaling_notify_connection_id = false
# signaling_notify_connection_created_timestamp = false
signaling_notify_metadata = false
一部項目を省略しています
{
"type": "notify",
"event_type": "connection.created",
"session_id": "P24NZ0AX2D6FX15VFHEGBXGMEW",
"bundle_id": "WHSSBG91XS7NXEVYY0F51YFEEW",
"connection_id": "WHSSBG91XS7NXEVYY0F51YFEEW",
"timestamp": "2023-12-18T07:12:11.876287Z",
"data": [
{
"bundle_id": "KKBFZTQXDD6H7FD2NYCQX8S474",
"connection_id": "KKBFZTQXDD6H7FD2NYCQX8S474",
"timestamp": "2023-12-18T07:11:56.585769Z"
},
{
"bundle_id": "4D40YWH56N5S99QHJV6GAPNHB0",
"connection_id": "4D40YWH56N5S99QHJV6GAPNHB0",
"timestamp": "2023-12-18T07:11:58.685769Z"
}
]
}
client_id と bundle_id と connection_id を通知しない¶
通知が不要のものを複数指定することができます。
signaling_notify_client_id = false
signaling_notify_bundle_id = false
signaling_notify_connection_id = false
# signaling_notify_connection_created_timestamp = false
# signaling_notify_metadata = false
一部項目を省略しています
{
"type": "notify",
"event_type": "connection.created",
"session_id": "P24NZ0AX2D6FX15VFHEGBXGMEW",
"timestamp": "2023-12-18T07:12:11.876287Z",
"authn_metadata": {"spam": "egg"},
"authz_metadata": "bacon",
"metadata": "bacon",
"data": [
{
"timestamp": "2023-12-18T07:11:56.585769Z",
"authn_metadata": 10,
"authz_metadata": {"authz": true},
"metadata": {"authz": true}
},
{
"timestamp": "2023-12-18T07:11:58.685769Z",
"authn_metadata": 10,
"metadata": 10
}
]
}
data 内の項目全てを通知しない¶
signaling_notify_client_id = false
signaling_notify_bundle_id = false
signaling_notify_connection_id = false
signaling_notify_connection_created_timestamp = false
signaling_notify_metadata = false
data
項目に関する通知を不要に設定すると、 data
項目自体が送信されなくなります。
一部項目を省略しています
{
"type": "notify",
"event_type": "connection.created",
"session_id": "P24NZ0AX2D6FX15VFHEGBXGMEW"
}
"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"¶
録画開始時に通知されます。
接続前にセッションウェブフック session.created
で "recording": true
や 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"
}
転送フィルターのシグナリング通知¶
これは実験的機能です
"event_type": "forwarding.blocked"¶
{
"type": "notify",
"event_type": "forwarding.blocked",
"kind": "video",
"destination_connection_id": "FCX8X05SJS3Y18RD5MYFZS62RR",
"source_connection_id": "SM7WDVYRTH739BB47ZSPQQ2BT4"
}
"event_type": "forwarding.allowed"¶
{
"type": "notify",
"event_type": "forwarding.allowed",
"kind": "video",
"destination_connection_id": "FCX8X05SJS3Y18RD5MYFZS62RR",
"source_connection_id": "SM7WDVYRTH739BB47ZSPQQ2BT4"
}
音声ストリーミング¶
"event_type": "audio-streaming.failed"¶
{
"type": "notify",
"event_type": "audio-streaming.failed",
"failed_connection_id": "4D40YWH56N5S99QHJV6GAPNHB0"
}
ICE コネクションステートのシグナリング通知¶
このシグナリング通知は、自分を含む同一チャネルに参加しているクライアント全員へ通知します。
"event_type": "ice-connection-state.connected"¶
{
"type": "notify",
"event_type": "ice-connection-state.connected",
"connection_id": "4D40YWH56N5S99QHJV6GAPNHB0"
}
"event_type": "ice-connection-state.checking"¶
{
"type": "notify",
"event_type": "ice-connection-state.checking",
"connection_id": "4D40YWH56N5S99QHJV6GAPNHB0"
}
"event_type": "ice-connection-state.disconnected"¶
{
"type": "notify",
"event_type": "ice-connection-state.disconnected",
"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,
}
RTP ストリーム停止と再開のシグナリング通知¶
これは実験的機能です
RTP ストリーム停止と再開のシグナリング通知はストリーム停止時には rtp_stream.pause
、ストリーム再開時には rtp_stream.resume
が通知されます。
sora.conf の設定¶
sora.conf
の signaling_notify_rtp_stream
で通知するかどうかを指定できます。デフォルトは true
で通知します。
signaling_notify_rtp_stream = false
"event_type": "rtp_stream.pause"¶
RTP ストリーム停止時に通知されます。RTP ストリームが停止される送信側および受信側の接続に通知されます。
{
"type": "notify",
"event_type": "rtp_stream.pause",
"recv_connection_id": "4D40YWH56N5S99QHJV6GAPNHB0",
"send_connection_id": "4SW2CB0E1D01S23W3G6JFCEN98"
}
"event_type": "rtp_stream.resume"¶
RTP ストリーム再開時に通知されます。RTP ストリームが再開される送信側および受信側の接続に通知されます。
{
"type": "notify",
"event_type": "rtp_stream.resume",
"stream_id": "4D40YWH56N5S99QHJV6GAPNHB0"
}
シーケンス図¶
コネクション関連の通知¶
sequenceDiagram participant C1 as クライアント1 participant C2 as クライアント2 participant S as Sora participant A as アプリケーションサーバー C1 ->>+ S: type: "connect"<br>client_id: "client1" S ->>+ A: 認証ウェブフック A -->>- S: 200 OK S ->>+ A: セッションウェブフック A -->>- S: 200 OK S -->>- C1: type: "offer" C1 -) S: type: "answer" note over C1, S: WebRTC 確立 par S ->>+ A: イベントウェブフック<br/>"type": "connection.created" A -->>- S: 200 OK and S -) C1: type: "notify"<br>event_type: "connection.created"<br>client_id: "client1" end note over C1, S: 1 分経過 par S ->>+ A: イベントウェブフック<br/>"type": "connection.updated" A -->>- S: 200 OK and S -) C1: type: "notify"<br>event_type: "connection.updated"<br>client_id: "client1" end C2 ->>+ S: type: "connect"<br>client_id: "client2" S ->>+ A: 認証ウェブフック A -->>- S: 200 OK S -->>- C2: type: "offer" C2 -) S: type: "answer" note over C2, S: WebRTC 確立 par S ->>+ A: イベントウェブフック<br/>"type": "connection.created" A -->>- S: 200 OK and S -) C2: type: "notify"<br>event_type: "connection.created"<br>client_id: "client2" and S -) C1: type: "notify"<br>event_type: "connection.created"<br>client_id: "client2" end C1 ->> S: type: "disconnect" note over C1, S: 切断 par S ->>+ A: イベントウェブフック<br/>"type": "connection.destroyed" A -->>- S: 200 OK and S -) C2: type: "notify"<br>event_type: "connection.destroyred"<br>client_id: "client1" end
録画関連の通知¶
sequenceDiagram participant C as クライアント participant S as Sora participant A as アプリケーションサーバー C ->>+ S: type: "connect"<br>client_id: "client1" S ->>+ A: 認証ウェブフック A -->>- S: 200 OK S ->>+ A: セッションウェブフック A -->>- S: 200 OK<br>recording: true S -->>- C: type: "offer" C -) S: type: "answer" note over C, S: WebRTC 確立 par S ->>+ A: イベントウェブフック<br/>"type": "connection.created" A -->>- S: 200 OK and S -) C: type: "notify"<br>event_type: "connection.created"<br>client_id: "client1" S -) C: type: "notify"<br>event_type: "recording.started"<br>client_id: "client1" end A ->>+ S: StopRecording API S -->>- A: 200 OK S -) C: type: "notify"<br>event_type: "recording.stopped"<br>client_id: "client1" S ->>+ A: イベントウェブフック<br/>"type": "archive.available" A -->>- S: 200 OK S ->>+ A: イベントウェブフック<br/>"type": "recording.report" A -->>- S: 200 OK