セッションウェブフック¶

概要¶

セッションウェブフックは、セッションの状態を送信するウェブフックです。

例えばチャネルに誰も接続していない状態で新しく接続されたタイミングや、誰も接続しない状態が一定時間続いたタイミングで、ウェブフックを利用してセッションの状態などを HTTP リクエストで送信する機能です。

また、セッション開始時にウェブフックの戻り値で音声ストリーミングや録画開始などを指定することができ、今まで API を叩いていた処理をウェブフックで行うことができるようになります。

目的¶

セッションは実際にチャネルに参加しているクライアントの集まりです。

もともと Sora にはチャネルを作るという概念がありません。チャネルに誰も接続していない状態で、新しく接続があれば、チャネルが利用されている状態になります。

そのため、チャネルが利用されているかどうかの判断は HTTP API を利用したり、イベントウェブフックリクエストの送信を利用したりして、アプリケーション側で判断する必要がありました。

このセッションウェブフックは、新しくチャネルに状態を持たせ、その状態をウェブフックリクエストで送信することで、API やイベントウェブフックを利用せずに、チャネルの状態を判断することができるようになります。

セッション ID¶

特定の期間チャネルに接続していたクライアントをグルーピングするために、 Sora はセッション ID という値を払い出します。セッション ID は Sora が指定するため、書き換えることはできません。

セッション ID は UUIDv4 を Base32 でエンコードした 26 バイトの文字列です。

HTTP ヘッダー¶

警告

この機能は実験的機能のため、正式版では仕様が変更される可能性があります

注釈

JSON のパース時の判断などに利用してください。

sora-session-webhook-type¶

注意

x-sora-session-webhook-type は非推奨です、 sora-session-webhook-type を利用してください

セッションウェブフックの HTTP ヘッダーに sora-session-webhook-type または x-sora-session-webhook-type というヘッダー名でセッションウェブフックのタイプが入ってきます。

type が session.created の場合は sora-session-webhook-type: session.created または x-sora-session-webhook-type: session.created のように値が入ってきます。

sora-session-id¶

セッションウェブフックの HTTP ヘッダーに sora-session-id というヘッダー名でセッション ID が入ってきます。

セッション ID が 46NNAV9S0X3TD778A1JBYYCBS8 の場合は sora-session-id: 46NNAV9S0X3TD778A1JBYYCBS8 のように値が入ってきます。

設定¶

session_webhook_url¶

セッションウェブフックリクエストの送信先を指定してください。

session_webhook_url = https://example.com/sora/session/webhook

session_created_timeout¶

セッションが存在しない状態で、新しくセッションを生成する際の制限時間です。これはセッションウェブフック処理も含めた時間で、この時間を超えるとタイムアウトとなり、切断されます。

デフォルトでは 5 秒です。

session_created_timeout = 5 s

session_destroyed_timeout¶

そのチャネルの接続数が 0 になってから新しい接続が無い場合に、 session.destroyed のセッションウェブフックリクエストを送信するまでの時間を指定します。

デフォルトでは 15 秒です。

session_destroyed_timeout = 15 s

session_updated_webhook_interval¶

session.updated の送信間隔を指定します。

デフォルトでは 1 min (1 分) です。単位は min しか指定できません。

session_updated_webhook_interval = 1 min

ログ¶

セッションウェブフックのログは log/session_webhook.jsonl に出力されます。これは session_webhook_url を指定していなくても出力されます。

`multistream` と `spotlight` が既存セッションと異なる場合の挙動¶

セッションが存在するタイミングでシグナリングのパラメーターが異なる接続が来た場合、接続数によって挙動が変わります。

既存セッションの接続数が 0 の場合¶

セッションの接続数が 0 のタイミングで multistream と spotlight がセッションと異なる新規接続が来た場合は、既存のセッションを破棄し session.destroyed ウェブフックリクエストを送信します。

その後に、新規でセッションを作成し session.created ウェブフックリクエストを送信します。

既存セッションの接続数が 0 ではない場合¶

セッションの接続数が 0 ではないタイミングで multistream と spotlight がセッションと異なる新規接続が来た場合は、 INVALID-SIGNALING-PARAMS エラーを返し切断します。

session.created¶

セッション生成

同時接続数が 0 のチャネル ID に対して、新しい接続の認証が成功したタイミングで session.created ウェブフックリクエストを送信します。

チャネルの同時接続数が 0 の場合でも、 multistream および spotlight の値が一致するセッションが過去に生成されており、まだ破棄されていない場合には、そのセッションが使用されるため session.created ウェブフックは送信されません。

キー	型	内容
type	string	"session.created"
id	string	ウェブフック ID (ユニーク)
label	string	sora.conf の label にて指定した値
node_name	string	Sora ノード名
version	string	Sora のバージョン
channel_id	string	チャネル ID
session_id	string	セッション ID
timestamp	string (RFC3339 UTC マイクロ秒)	ウェブフック作成時間
created_time	integer (UNIX 時間)	セッション生成時間
created_timestamp	integer (RFC3339 UTC マイクロ秒)	セッション生成時間
multistream	boolean	マルチストリームが有効かどうか
spotlight	boolean	スポットライトが有効かどうか
external_signaling_url	string	(クラスター機能が有効の場合) 接続先の external_signaling_url

{
  "channel_id": "sora",
  "created_time": 1638337454,
  "created_timestamp": "2021-12-01T05:44:14.523736Z",
  "id": "2YN2DQE5KD3GSFSVPAYZ7VTAV4",
  "label": "WebRTC SFU Sora",
  "multistream": true,
  "spotlight": false,
  "node_name": "[email protected]",
  "session_id": "NPR769YPQ914K10FW42PGH4TKW",
  "timestamp": "2021-12-01T05:44:14.523912Z",
  "external_signaling_url": "wss://node-01.example.com/signaling",
  "type": "session.created",
  "version": "2023.2.0"
}

connections¶

connections に入ってくる以下の二つは RFC3339 形式の時間ではなく null が入ってくる場合があります。

connection_created_timestamp
connection_destroyed_timestamp

これは、認証は成功し、セッションに参加はしたが、何らかの理由で WebRTC が確立に失敗した場合発生します。

両方ともの値に null が入ってきます。

戻り値¶

セッションウェブフックは "type": "session.created" の戻り値を指定できます。

session_metadata¶

session_metadata を指定した場合、セッション更新時の session.updated とセッション破棄時の "type": "session.destroyed" のウェブフックリクエストに session_metadata が含まれます。

{
  "session_metadata": "<JSON>"
}

recording¶

recording を true を指定した場合、セッション単位の録画を開始します。

{
  "recording": true
}

recording_expire_time¶

recording が true の場合のみ有効です。録画の有効期限を秒単位で指定します。

recording_expire_time を 3600 を指定した場合、 3600 秒後に録画は終了します。

{
  "recording_expire_time": 3600
}

recording_split_only¶

recording が true の場合のみ有効です。録画を分割のみで行うかどうかを指定します。

recording_split_only を true に指定した場合、録画は分割のみで行われます。

{
  "recording_split_only": true
}

recording_split_duration¶

recording が true の場合のみ有効です。分割録画の分割時間を秒単位で指定します。

recording_split_duration を 60 を指定した場合、 60 秒ごとに録画が分割されます。

{
  "recording_split_duration": 60
}

recording_metadata¶

recording が true の場合のみ有効です。recording.report ウェブフックやレポートファイルに含まれます。

{
  "recording_metadata": {"spam": "egg"}
}

forwarding_filter¶

forwarding_filter を指定した場合、転送フィルターをセッションに対して反映することができます。

転送フィルタールールの詳細については転送フィルター機能をご確認ください。

{
  "forwarding_filter": {
    "action": "allow",
    "rules": [
      // チャネルに接続しているすべてのコネクションに音声のみ転送する
      [
       {"field": "kind", "operator": "is_in", "values": ["audio"]}
      ]
    ]
  }
}

audio_streaming¶

audio_streaming を true に指定した場合、そのセッションで音声ストリーミングが有効になります。

音声ストリーミング機能の詳細については音声ストリーミング機能をご確認ください。

{
  "audio_streaming": true
}

audio_streaming_auto¶

audio_streaming_auto を true に指定した場合、そのセッションで音声ストリーミングが有効になり、かつ自動開始、自動停止機能が有効になります。この設定を true にするときには audio_streaming も true に設定する必要があります。

詳細は audio_streaming 関連の払い出し設定の組み合わせによる動作をご確認ください。

{
  "audio_streaming": true,
  "audio_streaming_auto": true
}

session.destroyed¶

セッション破棄

同時接続数が 0 になったチャネル ID が一定時間経過したタイミングで、 session.destroyed ウェブフックリクエストを送信します。

キー	型	内容
type	string	"session.destroyed"
id	string	ウェブフック ID (ユニーク)
label	string	sora.conf の label にて指定した値
node_name	string	Sora ノード名
version	string	Sora のバージョン
channel_id	string	チャネル ID
session_id	string	セッション ID
timestamp	string (RFC3339 UTC マイクロ秒)	ウェブフック作成時間
created_time	integer (UNIX 時間)	セッション生成時間
created_timestamp	integer (RFC3339 UTC マイクロ秒)	セッション生成時間
destroyed_time	integer (UNIX 時間)	セッション破棄時間
destroyed_timestamp	integer (RFC3339 UTC マイクロ秒)	セッション破棄時間
multistream	boolean	マルチストリームが有効かどうか
spotlight	boolean	スポットライトが有効かどうか
total_connections	integer	延べ接続数
max_connections	integer	最大同時接続数
connections	array (object)	(クラスター機能が無効の場合) セッションに参加した接続情報
session_metadata	json	(値がある場合) session.created の戻り値で指定した値
external_signaling_url	string	(クラスター機能が有効の場合) 接続先の external_signaling_url
reason	string	セッションが破棄された理由 ("normal", "terminated_api", "abort")

{
  "channel_id": "sora",
  "connections": [
    {
      "audio": true,
      "audio_codec_type": "OPUS",
      "client_id": "W9QE86Z0BS1QFFPZ2QB5DRZ2HC",
      "bundle_id": "W9QE86Z0BS1QFFPZ2QB5DRZ2HC",
      "connection_id": "W9QE86Z0BS1QFFPZ2QB5DRZ2HC",
      "connection_created_timestamp": "2021-12-01T05:44:23.051704Z",
      "connection_destroyed_timestamp": "2021-12-01T05:44:57.083215Z",
      "role": "sendrecv",
      "simulcast": false,
      "video": true,
      "video_bit_rate": 1000,
      "video_codec_type": "VP9",
      "video_vp9_params": { "profile_id": 0 },
    },
    {
      "audio": true,
      "audio_codec_type": "OPUS",
      "client_id": "JXMYW6GPX54EH0HGA5X4130FBM",
      "bundle_id": "JXMYW6GPX54EH0HGA5X4130FBM",
      "connection_id": "JXMYW6GPX54EH0HGA5X4130FBM",
      "connection_created_timestamp": "2021-12-01T05:44:21.500272Z",
      "connection_destroyed_timestamp": "2021-12-01T05:44:56.878019Z",
      "role": "sendrecv",
      "simulcast": false,
      "video": true,
      "video_bit_rate": 1000,
      "video_codec_type": "VP9",
      "video_vp9_params": { "profile_id": 0 },
    },
    {
      "audio": true,
      "audio_codec_type": "OPUS",
      "client_id": "F8VK9R71BN5S5EDE737C8XAA3C",
      "bundle_id": "F8VK9R71BN5S5EDE737C8XAA3C",
      "connection_id": "F8VK9R71BN5S5EDE737C8XAA3C",
      "connection_created_timestamp": "2021-12-01T05:44:19.811385Z",
      "connection_destroyed_timestamp": "2021-12-01T05:44:55.897819Z",
      "role": "sendrecv",
      "simulcast": false,
      "video": true,
      "video_bit_rate": 1000,
      "video_codec_type": "VP9",
      "video_vp9_params": { "profile_id": 0 },
    },
    {
      "audio": true,
      "audio_codec_type": "OPUS",
      "client_id": "VBYS5TV5S510F98GS2VK015AKG",
      "bundle_id": "VBYS5TV5S510F98GS2VK015AKG",
      "connection_id": "VBYS5TV5S510F98GS2VK015AKG",
      "connection_created_timestamp": "2021-12-01T05:44:14.716974Z",
      "connection_destroyed_timestamp": "2021-12-01T05:44:57.197372Z",
      "role": "sendrecv",
      "simulcast": false,
      "video": true,
      "video_bit_rate": 1000,
      "video_codec_type": "VP9",
      "video_vp9_params": { "profile_id": 0 },
    }
  ],
  "created_time": 1638337454,
  "created_timestamp": "2021-12-01T05:44:14.523736Z",
  "destroyed_time": 1638337502,
  "destroyed_timestamp": "2021-12-01T05:45:02.199179Z",
  "id": "M7K1AVS9KS34V9XFJJH04TB400",
  "label": "WebRTC SFU Sora",
  "max_connections": 4,
  "multistream": true,
  "node_name": "[email protected]",
  "session_id": "NPR769YPQ914K10FW42PGH4TKW",
  "spotlight": false,
  "timestamp": "2021-12-01T05:45:02.199419Z",
  "total_connections": 4,
  "session_metadata": {"spam": "egg"},
  "type": "session.destroyed",
  "version": "2023.2.0"
}

reason¶

session.destroyed には reason が含まれ、セッションが破棄された理由が入ります。

"normal" は通常のセッション破棄
"terminated_api" は TerminateSession API によるセッション破棄
"abort" は異常発生のセッション破棄

クラスター有効時¶

クラスター有効時には connections 項目は含まれません。

{
  "channel_id": "sora",
  "created_time": 1638337454,
  "created_timestamp": "2021-12-01T05:44:14.523736Z",
  "destroyed_time": 1638337502,
  "destroyed_timestamp": "2021-12-01T05:45:02.199179Z",
  "id": "M7K1AVS9KS34V9XFJJH04TB400",
  "label": "WebRTC SFU Sora",
  "max_connections": 4,
  "multistream": true,
  "node_name": "[email protected]",
  "session_id": "NPR769YPQ914K10FW42PGH4TKW",
  "spotlight": false,
  "timestamp": "2021-12-01T05:45:02.199419Z",
  "reason": "normal",
  "total_connections": 4,
  "session_metadata": {"spam": "egg"},
  "external_signaling_url": "wss://node-01.example.com/signaling",
  "type": "session.destroyed",
  "version": "2023.2.0"
}

session.updated¶

セッション更新

注釈

このウェブフックリクエストの送信を停止することができます。 sora.conf の ignore_session_updated_webhook を true にしてください。

session.created 送信後、一定間隔で session.updated ウェブフックリクエストを送信します。

送信間隔はデフォルトで 1 分です。 session_updated_webhook_interval で送信間隔を変更できます。

session.updated の状態を記録することで、もし何らかの理由で session.destroyed が送信されなかった場合でも、そのセッションが存在しているかどうかの判断を行う事ができるようになります。

キー	型	内容
type	string	"session.updated"
id	string	ウェブフック ID (ユニーク)
label	string	sora.conf の label にて指定した値
node_name	string	Sora ノード名
version	string	Sora のバージョン
channel_id	string	チャネル ID
session_id	string	セッション ID
timestamp	string (RFC3339 UTC マイクロ秒)	ウェブフック作成時間
created_time	integer (UNIX 時間)	セッション生成時間
created_timestamp	integer (RFC3339 UTC マイクロ秒)	セッション生成時間
multistream	boolean	マルチストリームが有効かどうか
spotlight	boolean	スポットライトが有効かどうか
total_connections	integer	延べ接続数
max_connections	integer	最大同時接続数
connections	array (object)	(クラスター機能が有効の場合) セッションに参加した接続情報
session_metadata	json	(値がある場合) session.created の戻り値で指定した値
external_signaling_url	string	(クラスター機能が有効の場合) 接続先の external_signaling_url

{
  "channel_id": "sora",
  "connections": [
    {
      "audio": true,
      "audio_codec_type": "OPUS",
      "client_id": "W9QE86Z0BS1QFFPZ2QB5DRZ2HC",
      "bundle_id": "W9QE86Z0BS1QFFPZ2QB5DRZ2HC",
      "connection_id": "W9QE86Z0BS1QFFPZ2QB5DRZ2HC",
      "connection_created_timestamp": "2021-12-01T05:44:23.051704Z",
      "connection_destroyed_timestamp": "2021-12-01T05:44:57.083215Z",
      "role": "sendrecv",
      "simulcast": false,
      "video": true,
      "video_bit_rate": 1000,
      "video_codec_type": "VP9",
      "video_vp9_params": { "profile_id": 0 },
    },
    {
      "audio": true,
      "audio_codec_type": "OPUS",
      "client_id": "JXMYW6GPX54EH0HGA5X4130FBM",
      "bundle_id": "JXMYW6GPX54EH0HGA5X4130FBM",
      "connection_id": "JXMYW6GPX54EH0HGA5X4130FBM",
      "connection_created_timestamp": "2021-12-01T05:44:21.500272Z",
      "connection_destroyed_timestamp": "2021-12-01T05:44:56.878019Z",
      "role": "sendrecv",
      "simulcast": false,
      "video": true,
      "video_bit_rate": 1000,
      "video_codec_type": "VP9",
      "video_vp9_params": { "profile_id": 0 },
    },
    {
      "audio": true,
      "audio_codec_type": "OPUS",
      "client_id": "F8VK9R71BN5S5EDE737C8XAA3C",
      "bundle_id": "F8VK9R71BN5S5EDE737C8XAA3C",
      "connection_id": "F8VK9R71BN5S5EDE737C8XAA3C",
      "connection_created_timestamp": "2021-12-01T05:44:19.811385Z",
      "connection_destroyed_timestamp": "2021-12-01T05:44:55.897819Z",
      "role": "sendrecv",
      "simulcast": false,
      "video": true,
      "video_bit_rate": 1000,
      "video_codec_type": "VP9",
      "video_vp9_params": { "profile_id": 0 },
    },
    {
      "audio": true,
      "audio_codec_type": "OPUS",
      "client_id": "VBYS5TV5S510F98GS2VK015AKG",
      "bundle_id": "VBYS5TV5S510F98GS2VK015AKG",
      "connection_id": "VBYS5TV5S510F98GS2VK015AKG",
      "connection_created_timestamp": "2021-12-01T05:44:14.716974Z",
      "connection_destroyed_timestamp": "2021-12-01T05:44:57.197372Z",
      "role": "sendrecv",
      "simulcast": false,
      "video": true,
      "video_bit_rate": 1000,
      "video_codec_type": "VP9",
      "video_vp9_params": { "profile_id": 0 },
    }
  ],
  "created_time": 1638337454,
  "created_timestamp": "2021-12-01T05:44:14.523736Z",
  "id": "M7K1AVS9KS34V9XFJJH04TB400",
  "label": "WebRTC SFU Sora",
  "max_connections": 4,
  "multistream": true,
  "node_name": "[email protected]",
  "session_id": "NPR769YPQ914K10FW42PGH4TKW",
  "spotlight": false,
  "timestamp": "2021-12-01T05:45:02.199419Z",
  "total_connections": 4,
  "session_metadata": {"spam": "egg"},
  "external_signaling_url": "wss://node-01.example.com/signaling",
  "type": "session.updated",
  "version": "2023.2.0"
}

クラスター有効時¶

クラスター有効時には connections 項目は含まれません。

{
  "channel_id": "sora",
  "created_time": 1638337454,
  "created_timestamp": "2021-12-01T05:44:14.523736Z",
  "id": "M7K1AVS9KS34V9XFJJH04TB400",
  "label": "WebRTC SFU Sora",
  "max_connections": 4,
  "multistream": true,
  "node_name": "[email protected]",
  "session_id": "NPR769YPQ914K10FW42PGH4TKW",
  "spotlight": false,
  "timestamp": "2021-12-01T05:45:02.199419Z",
  "total_connections": 4,
  "session_metadata": {"spam": "egg"},
  "external_signaling_url": "wss://node-01.example.com/signaling",
  "type": "session.updated",
  "version": "2023.2.0"
}

録画機能 (セッション単位) 有効時¶

セッションで録画機能 (セッション単位) が有効な場合、 "recording" が含まれます。録画が有効ではない場合は "recording" 項目は含まれません。

キー	型	内容
recording_id	string	録画機能 (セッション単位) の ID
recording_metadata (オプション)	JSON Value	録画機能 (セッション単位) のメタデータ
split_only	boolean	セッションでの録画が分割のみかどうか
expire_time (オプション)	integer	セッションでの録画期限
expired_at (オプション)	integer	セッションでの録画期限 (Unix time)
split_duration (オプション)	integer	セッションでの録画分割有効時の分割時間
start_timestamp	string	セッションでの録画が開始された時刻 (RFC 3339 (UTC))

{
  "channel_id": "sora",
  "created_time": 1638337454,
  "created_timestamp": "2021-12-01T05:44:14.523736Z",
  "id": "M7K1AVS9KS34V9XFJJH04TB400",
  "label": "WebRTC SFU Sora",
  "max_connections": 4,
  "multistream": true,
  "node_name": "[email protected]",
  "session_id": "NPR769YPQ914K10FW42PGH4TKW",
  "spotlight": false,
  "timestamp": "2021-12-01T05:45:02.199419Z",
  "total_connections": 4,
  "session_metadata": {"spam": "egg"},
  "external_signaling_url": "wss://node-01.example.com/signaling",
  "type": "session.destroyed",
  "version": "2023.2.0",
  "recording": {
    "recording_id": "WHEJ888HQ55KDCFE3TZ4VPFQHR",
    "recording_metadata": {"spam": "egg"},
    "expire_time": 3600,
    "expired_at": 1615527737,
    "split_duration": 3600,
    "split_only": false,
    "start_timestamp": "2021-03-12T04:42:17.455668Z"
  }
}

session.vanished¶

重要

このウェブフックリクエストが送信されるには sora.conf の ignore_session_vanished_webhook が false である必要があります。

Sora のモードが block_new_session または block_new_connection の時に、すべてのセッションがなくなったタイミングでウェブフックリクエストを送信します。

{
  "id": "047MK20PWD14QBPBA2JAK585JM",
  "label": "WebRTC SFU Sora",
  "node_name": "[email protected]",
  "timestamp": "2021-10-05T01:51:57.977800Z",
  "type": "session.vanished",
  "version": "2023.2.0"
}

recording.started¶

重要

このウェブフックリクエストが送信されるにはセッションベースの録画を利用する必要があります

録画開始

data.start_timestamp
- 録画機能 (セッション単位) を開始したタイムスタンプが入ります
data.expire_time
- この項目はオプションです
- API による開始を行った場合は StartRecording API で指定した expire_time が入ります
- session.created ウェブフックリクエストの戻り値により録画を開始した場合は戻り値 recording_expire_time が入ります
- 指定していない場合は expire_time の項目が入ってきません
data.expired_at
- この項目はオプションです
- API による開始を行った場合は StartRecording API で指定した expire_time から計算した有効期限 (UNIX Time) が入ります
- session.created ウェブフックリクエストの戻り値により録画を開始した場合は戻り値 recording_expire_time から計算した有効期限 (UNIX Time) が入ります
- expire_time を指定していない場合は expired_at の項目が入ってきません
data.split_duration
- この項目はオプションです
- API による開始を行った場合は StartRecording API で指定した split_duration が入ります
- session.created ウェブフックリクエストの戻り値により録画を開始した場合は戻り値 recording_split_duration が入ります
- 指定していない場合は split_duration の項目が入ってきません
data.split_only
- API による開始を行った場合は StartRecording API で指定した split_only が入ります
- session.created ウェブフックリクエストの戻り値により録画を開始した場合は戻り値 recording_split_only が入ります
- 指定していない場合は false が入ります
data.recording_metadata
- この項目はオプションです
- API による開始を行った場合は StartRecording API で指定した metadata が入ります
- session.created ウェブフックリクエストの戻り値により録画を開始した場合は戻り値 recording_metadata が入ります
- 指定していない場合は recording_metadata の項目が入ってきません

{
  "type": "recording.started",
  "id": "<Base32-UUIDv4>",
  "version": "<String>",
  "label": "<String>",
  "node_name": "<String>",
  "channel_id": "<String>",
  "session_id": "<Base32-UUIDv4>",
  "session_metadata": "<JSON>",
  "timestamp": "<UTC RFC3339 Timestamp>",
  "data": {
    "channel_id": "<String>",
    "recording_id": "<Base32-UUIDv4>",
    "recording_metadata": "<JSON-Object>",
    "split_only": "<Boolean>",
    "created_at": "<UNIX-Time>",
    "expire_time": "<Integer>",
    "expired_at": "<UNIX-Time>",
    "start_timestamp": "<UTC RFC3339 Timestamp>",
    "split_duration": "<Integer>"
  }
}

recording.report¶

重要

このウェブフックリクエストが送信するには、セッションベースの録画を利用する必要があります

注釈

セッションが終了したタイミングでの recording.report は session.destroyed の後に送信されます。

録画結果報告

data.archives[].start_time_offset
- 録画を開始してから何秒経過した後にこの録画が開始したかを表しています
data.archives[].stop_time_offset
- 録画を開始してから何秒経過した後にこの録画が終了したかを表しています
data.recording_metadata
- StartRecording API で指定した metadata 、または session.created で払い出した recording_metadata が入ります
- 指定していない場合は recording_metadata の項目が入ってきません
data.expired_at
- 期限が切れた日時を UNIX Time で返します

一括録画時 recording.report¶

{
    "type": "recording.report",
    "id": "<Base32-UUIDv4>",
    "version": "<String>",
    "label": "<String>",
    "node_name": "<String>",
    "channel_id": "<String>",
    "session_id": "<String",
    "session_metadata": "<JSON>",
    "timestamp": "<UTC RFC3339 Timestamp>",
    "data": {
        "channel_id": "<String>",
        "session_id": "<String>",
        "recording_id": "<Base32-UUIDv4>",
        "recording_metadata": "<JSON-Object>",
        "split_only": "<Boolean>",
        "split_duration": "<Integer>",
        "created_at": "<UNIX-Time>",
        "expire_time": "<Integer>",
        "expired_at": "<UNIX-Time>",
        "file_path": "<String>",
        "filename": "<String>",
        "file_written": "<Boolean>",
        "start_timestamp": "<UTC RFC3339 Timestamp>",
        "stop_timestamp": "<UTC RFC3339 Timestamp>",
        "archives": [
            {
                "label": "<String>",
                "node_name": "<String>",
                "client_id": "<String | Base32-UUIDv4>",
                "bundle_id": "<String | Base32-UUIDv4>",
                "connection_id": "<Base32-UUIDv4>",
                "file_path": "<String>",
                "filename": "<String>",
                "metadata_file_path": "<String>",
                "metadata_filename": "<String>",
                "start_time_offset": "<Integer>",
                "start_timestamp": "<UTC RFC3339 Timestamp>",
                "stop_time_offset": "<Integer>",
                "stop_timestamp": "<UTC RFC3339 Timestamp>",
                "size": "<Integer>"
            },
            {
                "label": "<String>",
                "node_name": "<String>",
                "client_id": "<String | Base32-UUIDv4>",
                "bundle_id": "<String | Base32-UUIDv4>",
                "connection_id": "<Base32-UUIDv4>",
                "file_path": "<String>",
                "filename": "<String>",
                "metadata_file_path": "<String>",
                "metadata_filename": "<String>",
                "start_time_offset": "<Integer>",
                "start_timestamp": "<UTC RFC3339 Timestamp>",
                "stop_time_offset": "<Integer>",
                "stop_timestamp": "<UTC RFC3339 Timestamp>",
                "size": "<Integer>"
            }
        ],
        "failed_archives": [
            {
                "label": "<String>",
                "node_name": "<String>",
                "client_id": "<String | Base32-UUIDv4>",
                "bundle_id": "<String | Base32-UUIDv4>",
                "connection_id": "<Base32-UUIDv4>"
            },
            {
                "label": "<String>",
                "node_name": "<String>",
                "client_id": "<String | Base32-UUIDv4>",
                "bundle_id": "<String | Base32-UUIDv4>",
                "connection_id": "<Base32-UUIDv4>"
            }
        ]
    }
}

分割録画時 recording.report¶

{
    "type": "recording.report",
    "id": "<Base32-UUIDv4>",
    "version": "<String>",
    "label": "<String>",
    "node_name": "<String>",
    "channel_id": "<String>",
    "session_id": "<String",
    "session_metadata": "<JSON>",
    "timestamp": "<UTC RFC3339 Timestamp>",
    "data": {
        "channel_id": "<String>",
        "session_id": "<String>",
        "recording_id": "<Base32-UUIDv4>",
        "recording_metadata": "<JSON-Object>",
        "split_only": "<Boolean>",
        "split_duration": "<Integer>",
        "created_at": "<UNIX-Time>",
        "expire_time": "<Integer>",
        "expired_at": "<UNIX-Time>",
        "file_path": "<String>",
        "filename": "<String>",
        "file_written": "<Boolean>",
        "start_timestamp": "<UTC RFC3339 Timestamp>",
        "stop_timestamp": "<UTC RFC3339 Timestamp>",
        "archives": [
            {
                "label": "<String>",
                "node_name": "<String>",
                "client_id": "<String | Base32-UUIDv4>",
                "bundle_id": "<String | Base32-UUIDv4>",
                "connection_id": "<Base32-UUIDv4>",
                "start_time_offset": "<Integer>",
                "start_timestamp": "<UTC RFC3339 Timestamp>",
                "stop_time_offset": "<Integer>",
                "stop_timestamp": "<UTC RFC3339 Timestamp>",
                "split_last_index": "<String>"
            },
            {
                "label": "<String>",
                "node_name": "<String>",
                "client_id": "<String | Base32-UUIDv4>",
                "bundle_id": "<String | Base32-UUIDv4>",
                "connection_id": "<Base32-UUIDv4>",
                "start_time_offset": "<Integer>",
                "start_timestamp": "<UTC RFC3339 Timestamp>",
                "stop_time_offset": "<Integer>",
                "stop_timestamp": "<UTC RFC3339 Timestamp>",
                "split_last_index": "<String>"
            }
        ],
        "failed_archives": [
            {
                "label": "<String>",
                "node_name": "<String>",
                "client_id": "<String | Base32-UUIDv4>",
                "bundle_id": "<String | Base32-UUIDv4>",
                "connection_id": "<Base32-UUIDv4>"
            },
            {
                "label": "<String>",
                "node_name": "<String>",
                "client_id": "<String | Base32-UUIDv4>",
                "bundle_id": "<String | Base32-UUIDv4>",
                "connection_id": "<Base32-UUIDv4>"
            }
        ]
    }
}

audio-streaming.started¶

重要

このウェブフックリクエストが送信されるには sora.conf の ignore_audio_streaming_webhook が false である必要があります。

以下の 2 つの条件で音声ストリーミングが開始した時にウェブフックリクエストを送信します。

StartAudioStreaming API が実行されるか、またはセッションウェブフックで audio_streaming: true 払い出されたタイミングでウェブフックリクエストを送信します。
音声ストリーミングのウェブフックを利用時に SubscribeAudioStreamingResultPush API が呼び出される、もしくはクライアントが接続されて、そのチャネルで音声ストリーミングの結果をサブスクライブしているクライアント数が 1 以上になった場合

session.created よりも必ず後にウェブフックが送信されます。

キー	型	内容
type	string	"audio-streaming.started"
id	string	ウェブフック ID (ユニーク)
label	string	sora.conf の label にて指定した値
node_name	string	Sora ノード名
version	string	Sora のバージョン
channel_id	string	チャネル ID
session_id	string	セッション ID
timestamp	string (RFC3339 UTC マイクロ秒)	ウェブフック作成時間
created_time	integer (UNIX 時間)	セッション生成時間
created_timestamp	string (RFC3339 UTC マイクロ秒)	セッション生成時間
multistream	boolean	マルチストリームが有効かどうか
spotlight	boolean	スポットライトが有効かどうか
session_metadata	json	(値がある場合) session.created の戻り値で指定した値
external_signaling_url	string	(クラスター機能が有効の場合) 接続先の external_signaling_url
data	object	音声ストリーミング固有

data には以下が含まれます。

キー	型	内容
audio_streaming_auto	boolean	自動開始/停止が有効かどうか
audio_streaming_started_timestamp	string (RFC3339 UTC マイクロ秒)	音声ストリーミングを開始した時間

{
  "channel_id": "sora",
  "created_time": 1638337454,
  "created_timestamp": "2021-12-01T05:44:14.523736Z",
  "id": "2YN2DQE5KD3GSFSVPAYZ7VTAV4",
  "label": "WebRTC SFU Sora",
  "multistream": true,
  "spotlight": false,
  "node_name": "[email protected]",
  "session_id": "NPR769YPQ914K10FW42PGH4TKW",
  "timestamp": "2022-12-01T05:44:14.523912Z",
  "type": "audio-streaming.started",
  "version": "2023.2.0",
  "session_metadata": {"spam": "egg"},
  "external_signaling_url": "wss://node-01.example.com/signaling",
  "data": {
    "audio_streaming_auto": true,
    "audio_streaming_started_timestamp": "2021-12-01T05:44:16.523912Z"
  }
}

audio-streaming.stopped¶

重要

このウェブフックリクエストが送信されるには sora.conf の ignore_audio_streaming_webhook が false である必要があります。

以下の 3 つの条件で音声ストリーミングが停止した時にウェブフックリクエストを送信します。

セッションが終了した場合
StopAudioStreaming API が呼び出す場合
音声ストリーミングのウェブフックを利用時に UnsubscribeAudioStreamingResultPush API が呼び出される、もしくはクライアントが切断されて、そのチャネルで音声ストリーミングの結果をサブスクライブしているクライアント数が 0 になった場合

session.destroyed よりも必ず前にウェブフックが送信されます。

キー	型	内容
type	string	"audio-streaming.started"
id	string	ウェブフック ID (ユニーク)
label	string	sora.conf の label にて指定した値
node_name	string	Sora ノード名
version	string	Sora のバージョン
channel_id	string	チャネル ID
session_id	string	セッション ID
timestamp	string (RFC3339 UTC マイクロ秒)	ウェブフック作成時間
created_time	integer (UNIX 時間)	セッション生成時間
created_timestamp	string (RFC3339 UTC マイクロ秒)	セッション生成時間
multistream	boolean	マルチストリームが有効かどうか
spotlight	boolean	スポットライトが有効かどうか
session_metadata	json	(値がある場合) session.created の戻り値で指定した値
external_signaling_url	string	(クラスター機能が有効の場合) 接続先の external_signaling_url
data	object	音声ストリーミング固有

data には以下が含まれます。

キー	型	内容
audio_streaming_auto	boolean	自動開始/停止が有効かどうか
audio_streaming_started_timestamp	string (RFC3339 UTC マイクロ秒)	音声ストリーミングを開始した時間
audio_streaming_stopped_timestamp	string (RFC3339 UTC マイクロ秒)	音声ストリーミングを停止した時間

{
  "channel_id": "sora",
  "created_time": 1638337454,
  "created_timestamp": "2021-12-01T05:44:14.523736Z",
  "id": "2YN2DQE5KD3GSFSVPAYZ7VTAV4",
  "label": "WebRTC SFU Sora",
  "multistream": true,
  "spotlight": false,
  "node_name": "[email protected]",
  "session_id": "NPR769YPQ914K10FW42PGH4TKW",
  "timestamp": "2022-12-01T05:44:14.523912Z",
  "type": "audio-streaming.stopped",
  "version": "2023.2.0",
  "session_metadata": {"spam": "egg"},
  "external_signaling_url": "wss://node-01.example.com/signaling",
  "data": {
    "audio_streaming_auto": true,
    "audio_streaming_started_timestamp": "2021-12-01T05:44:16.523912Z",
    "audio_streaming_stopped_timestamp": "2021-12-01T05:44:16.523912Z"
  }
}

API¶

TerminateSession API¶

セッションを強制的に終了させる API です。 channel_id を指定して、セッションを終了させます。 session_id を追加で指定することができますが、 session_id が見つからない場合はエラーになります。

API 実行中に新規の接続が来た場合、その接続はいったん保留して、セッション破棄後に新規セッションでの接続として扱います。

シーケンス図¶

sequenceDiagram autonumber participant C1 as クライアント1 participant C2 as クライアント2 participant S as Sora participant A as アプリケーションサーバー C1->>S: type: connect S->>+A: 認証ウェブフック A-->>-S: 200 OK S->>+A: セッションウェブフック type: session.created A-->>-S: 200 OK S->>C1: type: offer C1->>S: type: answer Note over C1,A: クライアント1 WebRTC 確立 S->>+A: イベントウェブフック type: connection.created A-->>-S: 200 OK C2->>S: type: connect S->>+A: 認証ウェブフック A-->>-S: 200 OK S->>C2: type: offer C2->>S: type: answer Note over C1,A: クライアント2 WebRTC 確立 S->>+A: イベントウェブフック type: connection.created A-->>-S: 200 OK C1->>S: "type": "disconnect" S->>+A: イベントウェブフック type: connection.destroyed A-->>-S: 200 OK S->>C1: WebSocket Close Note over C1,A: クライアント1 WebRTC 切断 C2->>S: "type": "disconnect" S->>+A: イベントウェブフック type: connection.destroyed A-->>-S: 200 OK S->>C2: WebSocket Close Note over C1,A: クライアント2 WebRTC 切断 note right of S: 接続数 0 から 15 秒経過 S->>+A: セッションウェブフック type: session.destroyed A-->>-S: 200 OK note right of S: セッションがすべて破棄された S->>+A: セッションウェブフック type: session.vanished A-->>-S: 200 OK

クラスター時の挙動について¶

セッションが存在していたノードで障害が起きた場合でも、 `session.destroyed` は送信されます¶

別のノードが session.destroyed を送信します。その際 reason 項目には abort が入ります。

reason が abort の場合、以下の情報が 最新の状態 ではない場合があります。

total_connections
max_connections

セッションが存在していたノードで障害が起きた際、同一ウェブフックが複数回送られる事があります¶

以下のウェブフックは複数回送られる可能性はあります、その際はウェブフックの "id" は同一になります。

session.destroyed
recording.started
recording.report
audio-streaming.stopped

セッションウェブフック¶

概要¶

目的¶

セッション ID¶

HTTP ヘッダー¶

sora-session-webhook-type¶

sora-session-id¶

設定¶

session_webhook_url¶

session_created_timeout¶

session_destroyed_timeout¶

session_updated_webhook_interval¶

ログ¶

multistream と spotlight が既存セッションと異なる場合の挙動¶

既存セッションの接続数が 0 の場合¶

既存セッションの接続数が 0 ではない場合¶

session.created¶

connections¶

戻り値¶

session_metadata¶

recording¶

recording_expire_time¶

recording_split_only¶

recording_split_duration¶

recording_metadata¶

forwarding_filter¶

audio_streaming¶

audio_streaming_auto¶

session.destroyed¶

reason¶

クラスター有効時¶

session.updated¶

クラスター有効時¶

録画機能 (セッション単位) 有効時¶

session.vanished¶

recording.started¶

recording.report¶

一括録画時 recording.report¶

分割録画時 recording.report¶

audio-streaming.started¶

audio-streaming.stopped¶

API¶

TerminateSession API¶

シーケンス図¶

クラスター時の挙動について¶

セッションが存在していたノードで障害が起きた場合でも、 session.destroyed は送信されます¶

セッションが存在していたノードで障害が起きた際、同一ウェブフックが複数回送られる事があります¶

`multistream` と `spotlight` が既存セッションと異なる場合の挙動¶

セッションが存在していたノードで障害が起きた場合でも、 `session.destroyed` は送信されます¶