WebRTC SFU Sora ドキュメント

このドキュメントは WebRTC SFU Sora 2024.2.0 に対応しています。

製品のお問い合わせなどは sora at shiguredo.jp までお願いいたします。 (このメールアドレスへの特定電子メールの送信を拒否いたします)

重要なお知らせ

署名アルゴリズムに SHA-1 が利用されている中間証明書をご利用されているお客様へ

Sora 2023.2.0 から 2024.1.0 までは署名アルゴリズムが SHA-1 の中間証明書を利用した場合、 Bad Certificate エラーとして接続が拒否されます。

影響のある機能は下記の機能です。

• ウェブフック機能

• 音声ストリーミング機能

• 統計エクスポーター機能

もし、このエラーがログに出力された場合、 Sora 2024.1.3 をご利用ください。

Sora RHEL 版の追加料金について

RHEL 9 のフルサポートが終了する 2027 年 6 月 1 日より、Sora RHEL 版をご利用のお客様については、 サポート費用としてライセンス料金に 10% (ただし最大で 10 万円) の料金を上乗せさせていただきます。

料金例

• ライセンス料金が 60 万円の場合は 6 万円

• ライセンス料金が 84 万円の場合は 8.4 万円

• ライセンス料金が 120 万円の場合は 10 万円

• ライセンス料金が 252 万円の場合は 10 万円

RHEL の場合、Ubuntu と比べて維持や Sora の動作検証コストが大きいためで、 ご理解いただきますようお願いいたします。

レガシー録画機能の廃止について

2023 年 12 月リリースの Sora 2023.2.0 で新しい録画機能を追加しました。 今までの録画機能はレガシー録画機能と名前を変更しました。 2025 年 12 月リリース予定の Sora でレガシー録画機能を廃止します。

移行については レガシー録画機能から新しい録画機能への移行 をご確認ください。

廃止については レガシー録画機能の廃止 をご確認ください。

レガシー録画機能をご利用のお客様は、新しい録画機能へ移行をご検討ください。

機能や移行に関してのご不明点などがあれば、サポートまでお問い合わせください。

レガシーストリーム(非マルチストリーム)機能の廃止について

2024 年 6 月リリースの Sora 2024.1.0 でレガシーストリーム機能をデフォルトで無効にしました。

2025 年 6 月リリース予定の Sora でレガシーストリーム機能を廃止します。

移行については レガシーストリーム(非マルチストリーム)機能からマルチストリームへの移行 をご確認ください。

廃止については レガシーストリーム(非マルチストリーム)機能の廃止 をご確認ください。

レガシーストリーム機能をご利用のお客様は、マルチストリーム機能へ移行をご検討ください。

機能や移行に関してのご不明点などがあれば、サポートまでお問い合わせください。

Ubuntu 24.04 版の提供開始について

Sora 2024.1.0 から Ubuntu 24.04 版の提供を開始しました。

Ubuntu 24.04 版への切り替えをご希望のお客様はサポートまでご連絡ください。

Ubuntu 20.04 版の提供終了について

Ubuntu 20.04 は 2025 年 4 月末でサポートが終了となるのに合わせて、Sora の Ubuntu 20.04 版については以下のとおりとなります。

パッケージの提供

2024 年 6 月のリリースの 2024.1.0、およびその後リリースされる可能性のある 2024.1.x の提供をもって終了

サポートの終了

2024.1.0 およびおよびその後リリースされる可能性のある 2024.1.x に対しては 2025 年 6 月末で終了

Ubuntu 20.04 版をご利用のお客様は、早めに OS の変更をご検討の上、移行先の OS をサポートまでご連絡下さい。

CentOS 7 版の提供終了について

CentOS 7 は 2024 年 6 月末でサポートが終了となるのに合わせて、Sora の CentOS 7 版については以下のとおりとなります。

パッケージの提供

2023 年 12 月にリリースの 2023.2.0、およびその後リリースされる可能性のある 2023.2.x の提供をもって終了

サポートの終了

2023.2.0 およびおよびその後リリースされる可能性のある 2023.2.x に対しては 2024 年 12 月末で終了

CentOS 7 版をご利用のお客様は、早めに OS の変更をご検討の上、移行先の OS をサポートまでご連絡下さい。

古いドキュメントについて

古いドキュメント をご確認ください。

2024.1.x から 2024.2.x への移行

概要

2024.1.x から 2024.2.x への移行について変更点や注意点をまとめています。

もし不明点がある場合はサポートまでお問い合わせください。

レガシー録画機能のデフォルト無効

レガシー録画機能を利用する sora.conf の legacy_recording をデフォルトで false に変更しました。

レガシー録画機能を利用する場合は true へ変更をお願いします。

レガシー録画機能は 2025 年 12 月リリース予定の Sora にて廃止しますので、録画機能(セッション単位)への移行をお願いします。

以降については レガシー録画機能から新しい録画機能 (セッション単位) への移行 をご確認ください。

セッション単位での同時接続数を制限する trial_max_connections の追加

セッション単位での同時接続数を制限する trial_max_connections を追加しました。

詳細については trial_max_connections をご確認ください。

JSON Lines 形式のログ出力に対してエスケープ処理を行わないよう変更

JSON Lines 形式のログ出力に対してエスケープ処理を行わないよう変更しました。

ウェブフック送信を行わない場合でもログを出力するように変更

ウェブフックの送信を行わない (ignore) の設定した場合でも、以下のウェブフックはログを出力するように変更しました。

• recording.started セッションウェブフック

• session.updated セッションウェブフック

• session.vanished セッションウェブフック

• connection.failed イベントウェブフック

• archive.started イベントウェブフック

• recording.started イベントウェブフック

ただし、 legacy_signaling_error が true かつ ignore_connection_failed_webhook が true の場合は、 connection.failed イベントウェブフックのログは出力されません。

既存のセッションの同時接続数が 0 の際に、このセッションと異なる multistream または spotlight 設定の新規接続が来た場合の挙動の変更

Sora にてセッションウェブフックの multistream と spotlight が既存セッションと異なる場合の挙動 を変更します。

今までは既存セッションの同時接続数が 0 の場合に、 multistream または spotlight の設定が、 既存セッションと異なる新規接続が来た場合、 既存セッションを破棄し、新規セッションで接続できるようになっていましたが、 既存セッションを破棄せずにエラーになるように変更しました。

プレイアウト遅延機能が配信側から視聴側への適用に変更

Sora 2024.1.x まで、プレイアウト機能は配信側にのみ適用されていましたが、 2024.2.x からは視聴側のみに適用されるようになりました。

詳細は プレイアウト遅延 をご確認ください。

録画の出力ファイルが MP4 形式に対応しました

StartRecording API で format を mp4 に指定するか、 session.created の払い出しで recording_format を mp4 に指定することで、 MP4 形式で録画の出力ファイルが作成されます。

また、 sora.conf の default_recording_format を mp4 に設定することで、 録画の出力ファイルのデフォルトが MP4 形式になります。

• 2025 年 12 月リリース予定の Sora では default_recording_format のデフォルトが webm から mp4 になります

ウェブフック

• session.updated や session.destroyed の recording の format を追加しました

• recording.started に format を追加しました

キーフレーム要求間隔の変更

MP4 形式での出力時に、Sora からクライアントへのキーフレーム要求 (PLI) の間隔を default_recording_mp4_pli_interval で指定できるようになりました。

WebM 形式ではキーフレームの間隔が最大でも 31 秒までという制約がありましたが、 MP4 形式ではこの制約がなくなりました。

詳細は MP4 形式のキーフレーム要求間隔の変更 をご確認ください。

WebSocket シグナリング時のフレームサイズが大きい場合のエラー改善

WebSocket のフレームサイズが大きい場合は今まで Websocket の Close Code 4490 で切断していましたが、 WebSocket の仕様に合わせて 1009 で切断するようになりました。

WebSocket シグナリングのメッセージサイズの最大は 5 MiB です。

クライアントからの "type": "disconnect" による切断の改善

WebSocket シグナリングを利用している場合は、 WebSocket の Close フレームの Reason に "TYPE-DISCONNECT" が入るようになりました。

DataChannel シグナリングのみを利用している場合は、 DataChannel を閉じて終了します。

WebSocket シグナリング利用時に Sora から正常切断が発生した際の改善

切断系 API やライフタイム期限などのSora からの正常切断時に、 WebSocket シグナリングを利用している場合、 WebSocket Close フレームの Code に 1000 、 Reason に切断理由が入るようになりました。

正常な場合の切断理由は以下の 3 つです。

• LIFETIME-EXPIRED

  • ライフタイムによるコネクションの破棄

• SESSION-DESTROYED

  • API やライフタイムなどによるセッションの破棄

• DISCONNECTED-API

  • API によるコネクションの破棄

DataChannel シグナリングのみの利用時に Sora から切断が発生した際の "type": "close" メッセージの送信

DataChannel シグナリングのみの利用時に Sora から切断が発生した際、 DataChannel を閉じる前に "type": "close" メッセージを送信する設定を追加しました。

sora.conf の data_channel_signaling_close_message を true に設定することで有効になります。 デフォルトは false です。

DataChannel が閉じられたのが正常な処理なのか、それとも何か問題が発生したのかを明確にするための仕組みです。

正常な場合の切断理由は以下の 3 つです。

• LIFETIME-EXPIRED

  • ライフタイムによるコネクションの破棄

• SESSION-DESTROYED

  • API やライフタイムなどによるセッションの破棄

• DISCONNECTED-API

  • API によるコネクションの破棄

data_channel_signaling_close_message = false

        sequenceDiagram
   participant C as Client
   participant S as Sora
   participant A as App
   note over C,S: WebRTC 確立
   S-)C: "type": "switched"<br>"ignore_websocket_disconnect": true
   A->>+S: Disconnect API
   S->>-A: 200 OK
   S->>C: DataChannels Close
    

data_channel_signaling_close_message = true

        sequenceDiagram
   participant C as Client
   participant S as Sora
   participant A as App
   note over C,S: WebRTC 確立
   S-)C: "type": "switched"<br>"ignore_websocket_disconnect": true
   A->>+S: Disconnect API
   S->>-A: 200 OK
   S->>C: "type": "close" over DataChannel<br>1000<br>"DISCONNECT-API"
   S->>C: DataChannels Close
    

"type": "close" メッセージの正常終了時の reason について

• 正常な切断では code は 1000 で、 reason には切断理由が入ります

• 異常による切断では code は 4490 で、 reason には切断理由がはいります

Sora からの正常切断時の reason の値を空文字にする設定

signaling_normal_close_reason はデフォルトで true で、切断理由が入りますが、 false にすることで切断理由を空文字を入れるようになります。

シグナリングエラー時の改善

シグナリングエラー時のログの出力先やウェブフック connection.failed の通知タイミングを改善しました。

• シグナリング時のエラーが sora.jsonl に出力されなくなりました

• シグナリング時のエラーが signaling_error.jsonl に出力されるようになりました

• 認証失敗時のエラーが sora.jsonl に出力されなくなりました

• 認証失敗時のエラーが signaling_error.jsonl に出力されるようになりました

• イベントウェブフック connection.failed が認証失敗時には通知されなくなりました

• イベントウェブフック connection.failed が認証成功後に接続に失敗した時のみ通知されるようになりました

この設定は legacy_signaling_error を true にすることで無効になります。

認証失敗時のエラーログの改善

認証失敗時のログを sora.jsonl から signaling_error.jsonl に出力するように変更しました。

認証時失敗時のエラーはシグナリングエラーと同等として扱うことにしました。 sora.jsonl に ERROR で出力されるシグナリング失敗のエラーメッセージは connection.created 以降に変更しました。

イベントウェブフック connection.failed の改善

今まで connection.failed はシグナリング時にエラーが発生した場合通知する仕組みでしたが、 今後は認証が成功した後に接続が失敗した場合のみ通知されるように変更しました。

これにより、認証が失敗した場合には connection.failed ウェブフックは通知されなくなります。 そもそも認証の失敗自体は認証ウェブフックで判断しているため、通知自体が不要でした。

また認証ウェブフック処理前のバリデーションエラーなどは、 channel_id がなかったり role がなかったりなど、 ウェブフックに飛ぶ情報が不確定な情報が多いため、 ウェブフックを飛ばしても扱いに困ると判断しました。

2024.1.x までの挙動を維持する

sora.conf の legacy_signaling_error を true に設定することで、 2024.1.x までと同等の sora.jsonl に認証失敗のエラーメッセージが出力されるようになります。

シグナリングエラー時のエラーメッセージの改善

今まで細かいエラーを出力していましたが、わかりにくいエラーログが多かったため、 今まで出力していた詳細なエラーについては signaling_error.jsonl に出力するように変更しました。

エラーメッセージ変更内容

• UNAUTHORIZED

  • AUTHENTICATION-FAILURE

• INTERNAL-ERROR

  • SIGNALING-INTERNAL-ERROR

  • AUTH-WEBHOOK-RESPONSE-EMPTY-BODY

  • AUTH-WEBHOOK-RESPONSE-UNEXPECTED-STATUS-CODE

  • INVALID-AUTHZ-MEDIA

  • WHEP-INCOMPATIBLE-UPSTREAM-TRACK

  • DUPLICATED-CONNECTION-ID-ERROR

  • INVALID-SPOTLIGHT-NUMBER

  • DUPLICATED-CHANNEL-ID

  • UNMATCH-CODEC-TYPE-ERROR

• SERVICE-UNAVAILABLE

  • EXCEED-MAX-CONNECTIONS

  • BLOCK-NEW-CONNECTION

  • BLOCK-NEW-SESSION

• TIMEOUT

  • CONNECTION-CREATED-WAIT-TIMEOUT-ERROR

  • CONNECT-WAIT-TIMEOUT-ERROR

  • ANSWER-TIMEOUT-ERROR

  • PONG-TIMEOUT-ERROR,

• INVALID-MESSAGE

  • INVALID-JSON

  • INVALID-SIGNALING-TYPE

  • INVALID-SIGNALING-PARAMS

  • MISSING-TYPE

  • BAD-FINGERPRINT

  • TOO-LARGE-JSON

  • TOO-MANY-CANDIDATE

  • INVALID-VIDEO-FORMAT

  • FAILURE-SDP-PARSE

  • MISSING-ICE-SDP

  • INVALID-VIDEO-FORMAT

  • INVALID-AUDIO-FORMAT

  • FAILURE-JSON-DECODE

  • UNEXPECTED-SIGNALING-TYPE

  • UNKNOWN-AUDIO-CODEC-TYPE

  • INVALID-AUDIO-BIT-RATE

  • UNKNOWN-VIDEO-CODEC-TYPE

  • INVALID-VIDEO-BIT-RATE

クラスターのローリングアップデートについて

2024.1.x から 2024.2.x へのローリングアップデートができます。

1 台 1 台ローリングアップデートを行ってください。

2023.2.x から 2024.2.x へのローリングアップデートはできません、 かならず 2023.2.x からのアップデートを行う場合、 2024.1.x を経由してから 2024.2.x へアップデートを行っていください。

統計情報 total_received_intra_frame を total_received_key_frame に変更しました

統計情報に含まれる total_received_intra_frame を total_received_key_frame に変更しました。

RequestKeyFrame API に合わせた変更になります。

JoinCluster API を廃止しました

今後は全く同じ機能を提供している RegisterClusterNode API をご利用ください。

ListClusterNodes API の include_all_known_nodes を廃止しました

ListClusterNodes API の include_all_known_nodes を廃止しました

常にクラスターに登録されている全てのノード情報を返すようになりました。

詳しくは ListClusterNodes API の include_all_known_nodes の廃止 をご確認ください。

sora.conf の legacy_auth_webhook_log を廃止しました

移行用の設定 sora.conf の legacy_auth_webhook_log を廃止しました。

認証ウェブフックのエラーログは auth_webhook_error.jsonl に出力されるようになりました。

詳しくは sora.conf の legacy_auth_webhook_log の廃止 をご確認ください。

sora.conf の legacy_event_webhook_connection_destroyed_reason を廃止しました

移行用の設定 sora.conf の legacy_event_webhook_connection_destroyed_reason を廃止しました。

connection.destroyed の reason には normal / disconnected_api / session_destroyed / lifetime_expired のいずれかが入るようになりました。

詳しくは sora.conf の legacy_event_webhook_connection_destroyed_reason の廃止 をご確認ください。

signaling_forwarding_filter を非推奨にしました

複数の転送フィルターを指定できる signaling_forwarding_filters を追加したことから、 signaling_forwarding_filter を非推奨にしました。

2025 年 12 月リリース予定の Sora にて廃止します。

移行に際する不明点などはサポートまでお問い合わせください。

認証成功時とセッション生成時の払い出し forwarding_filter を非推奨にしました

複数の転送フィルターを指定できる forwarding_filters を追加したことから、 認証成功時とセッション生成時の払い出し forwarding_filter を非推奨にしました。

2025 年 12 月リリース予定の Sora にて廃止します。

移行に際する不明点などはサポートまでお問い合わせください。

session.vanished ウェブフックを非推奨にしました

Sora Exporter を利用する事で、より柔軟なセッションの監視ができることから、 session.vanished ウェブフックを非推奨にしました。

2025 年 6 月リリース予定の Sora にて廃止します。

移行に際する不明点などはサポートまでお問い合わせください。

RTP ストリーム停止/再開 API を非推奨にしました

RTP ストリーム停止/再開 API は 転送フィルター により同等の機能が提供でき、 重複機能となるため非推奨にしました。

今後は 転送フィルター をご利用ください。

2025 年 12 月リリース予定の Sora にて廃止します。

移行に際する不明点などはサポートまでお問い合わせください。

レガシー録画機能から新しい録画機能 (セッション単位) への移行

重要

レガシー録画機能は 2025 年 12 月リリースの Sora にて廃止します。

Sora 2023.2.0 から新しくセッション単位の録画機能を追加し、既存の録画機能をレガシー録画機能としました。

レガシー録画の有効化

sora.conf にて legacy_recording を true にすることでレガシー録画機能を有効にできます。

レガシー録画機能ではできて、新しい録画機能ではできないこと

セッションが存在しない状態では録画の開始ができなくなった

レガシー録画機能では 20161101.StartRecording API を利用することで、セッションが存在しない状態でも録画を開始することができました。

新しい録画機能ではセッションが生成される前に録画を開始することはできません。

代わりにセッションが生成されたタイミングで、 セッションウェブフック session.created の戻り値に "recording": true を指定することで、 セッション生成と同時に録画を開始することができます。

セッションをまたいだ録画ができなくなった

レガシー録画機能では、一度録画を開始したら録画の期限が来るか、 StopRecording API を実行するまでは録画が続いてしまい、 録画したままという状態が残ってしまうことがありました。

新しい録画機能では、セッションが破棄されたタイミングで録画も終了するため、誰もそのチャネルに接続していないにもかかわらず、 録画したままという状態はなくなります。

変更点

API の変更

• レガシー録画で利用していた 20161101.StartRecording API と 20161101.StopRecording API はバージョンを 20231220 に変更してください

• レガシー録画で利用していた StartRecording API は StartRecording API を利用してください

• レガシー録画で利用していた StopRecording API は StopRecording API を利用してください

• レガシー録画で利用していた GetStartedRecording API は GetSession API を利用してください

• レガシー録画で利用していた ListStartedRecording API は ListSessions API を利用してください

• レガシー録画で利用していた ListArchiving API には代わりの API がありません、今後 GetSessionRecordingState API を提供予定です

  • API の変更についてのご質問がある場合はサポートまでご連絡ください

セッション生成時の録画開始

セッションが存在しないタイミングでの録画開始はできなくなりました。

代わりにセッションが生成されたタイミングで、 セッションウェブフック session.created の戻り値に "recording": true を指定することで、 セッション生成と同時に録画を開始することができます。

録画を開始するための API を実行する必要はありません。

セッション破棄時の録画終了

セッション破棄時に録画を終了するようになりました。

録画を終了するための API を実行する必要はありません。

expire_time で指定した時間よりも先にセッションが破棄された場合は、その時点で録画を終了します。

expire_time のオプション化

レガシー録画では StartRecording API の expire_time は必須でしたが、 新しい録画では expire_time はオプションに変更しています。

• expire_time を指定しない場合は未定義になります。ウェブフックなどでは項目が含まれなくなります

  • レガシー録画では expire_time 未定義の場合は 0 が入っていました

• expire_time が未指定の場合は、 expired_at も項目として含まれなくなります

• expire_time に 0 は指定できなくなり、 0 より大きい値のみ指定可能になりました

• 分割録画ファイルのみ出力を行う場合でも expire_time が指定できるようになりました

セッションウェブフック recording.started と recording.report への切り替え

今まで録画開始/終了のウェブフックはイベントウェブフックで送信していましたが、 新しい録画機能ではセッションウェブフックを利用します。

録画開始 recording.started と録画レポート recording.report ウェブフックの中身は以下が異なります。

• session_id を追加しています

• session_metadata を追加しています

• 録画メタデータが指定された場合、 recording_metadata を追加しています

  • metadata を recording_metadata に変更しています

• イベントウェブフック固有の log_written を削除しています

それ以外は同じです。

接続単位の録画ファイルに関してのイベントウェブフック archive.* については、変更はありません。

report-<recording_id>.json ファイルの metadata を recording_metadata に変更

録画メタデータが指定された場合の項目を metadata から recording_metadata に変更しています。

接続単位の録画ブロック機能

今までの録画機能では接続単位での録画ブロックができませんでしたが、 新しい録画機能では認証成功時に "recording_block": true を払い出すことで、 その接続の録画をブロックし、録画ファイルを出力しなくなります。

この機能は新しい録画機能だけで利用できます。

レガシー録画機能と新しい録画機能の同時利用

レガシー録画機能と新しい録画機能 (セッション単位) は、異なるチャネルであれば同時に利用できます。 例えば、channel_id a ではレガシー録画機能、channel_id b では新しい録画機能（セッション単位）といった利用が可能です。

レガシーストリーム(非マルチストリーム)機能からマルチストリーム機能への移行

重要

レガシーストリーム機能は 2025 年 6 月リリースの Sora にて廃止します。

シグナリング接続時に "multistream": false を指定した機能をレガシーストリーム機能としました。

なぜレガシーストリームを廃止するのか

レガシーストリーム機能は 10 年以上前の WebRTC の初期の仕様に基づいて開発されたため、 現在では時代遅れとなっています。

マルチストリーム機能は WebRTC の最新仕様に合わせて開発され、 より柔軟な配信や視聴ができます。

レガシーストリームでは実現困難な機能が増え、維持コストも高くなってきています。 また、レガシーストリームに似ている仕組みである WHIP/WHEP への対応を行いました。

レガシーストリームの役割は終了したと考え、 2025 年 6 月リリース予定の Sora にて廃止します。

Sora 2024.1.0 からレガシーストリームをデフォルトで無効にし非推奨へ

2024 年 6 月リリースの Sora から、レガシーストリーム機能はデフォルトで無効になり、非推奨となります。 そのため multistream: false で接続した場合、シグナリングエラーになります。

もし、レガシーストリーム機能を引き続き利用したい場合は、 legacy_stream オプションを true に設定してください。

2025 年 6 月リリース予定の Sora でレガシーストリームが廃止に

2025 年 6 月リリース予定の Sora にて、レガシーストリーム機能を廃止します。

レガシーストリーム機能ではできて、マルチストリーム機能ではできないこと

視聴側の SDP 再交換を発生させずに、同一メディアストリームでストリームを受信できる

マルチストリームでは配信者が切り替わるたびに SDP 再交換が必須となります。 このため、挙動が大きく異なりますので注意してください。

移行時の注意点

不明点などはサポートまでお問い合わせください。

参加/離脱の挙動

これまで視聴側は SDP を一度交換するだけでしたが、 マルチストリーム機能では配信者が切り替わるたびに SDP 交換が必要となります。

マルチストリームでは新しく配信者が参加したタイミングでストリームやトラックを追加する処理が必要になります。 同じように配信者が離脱したタイミングでストリームやトラックを削除する処理が必要になります。

複数配信のサポート

レガシーストリームでは配信者は常に 1 つでしたが、マルチストリームでは複数配信することができます。

リリースノート

CHANGE

後方互換性のない変更

UPDATE

後方互換性がある変更

ADD

後方互換性がある追加

FIX

バグ修正

2024.2.1

バグフィックスアップデート

リリース:

2025 年 1 月 8 日

変更履歴

• [FIX] AV1 コーデック利用時、主にハードウェアエンコーダーなど、 libwebrtc が採用している libaom 以外のエンコーダーを利用するとキーフレーム判定が失敗する場合がある問題を修正しました

• [FIX] クラスター構成で Sora 2024.1.x からのローリングアップデート中、録画が開始できない場合がある問題を修正しました

• [FIX] クラスター構成で Sora 2024.1.x からのローリングアップデート中、録画を開始すると recording.report ウェブフックが送信されない場合がある問題を修正しました

2024.2.0

メジャーアップデート

リリース:

2024 年 12 月 18 日

重要

Sora 2024.1.x から 2024.2.x への移行については 2024.1.x から 2024.2.x への移行 をご確認ください。

ハイライト

• 録画アーカイブファイルの MP4 形式による出力に対応しました

• 録画アーカイブファイルの H.265 コーデックによる出力に対応しました

• リアルタイムメッセージング機能で、メッセージのヘッダーに送信元の connection_id を付与する機能を追加しました

• 実験的機能として、転送フィルター機能で複数のフィルターを設定できる「マルチ転送フィルター機能」を追加しました

• 実験的機能として、 session.created の払い出しに、セッションの同時接続数を制限する trial_max_connections を追加しました

• 指定したコネクションにキーフレームを要求する RequestKeyFrame API を追加しました

正式版

今回のリリースで以下の機能が実験的機能から正式版になりました。

• クラスター機能

• センシティブデータ

• OBS (WHIP) 対応

• メディア配信ワーカー機能

• セッションライフタイム機能

• コネクションライフタイム機能

• TerminateSession API

破壊的変更

• 既存のセッションの同時接続数が 0 の際に、このセッションと異なる multistream または spotlight 設定の新規接続が来た場合、エラーになるように変更しました

  • 詳細は 既存のセッションの同時接続数が 0 の際に、このセッションと異なる multistream または spotlight 設定の新規接続が来た場合の挙動の変更 をご確認ください

• クライアントに通知されるエラーメッセージを改善しました

  • 詳細は シグナリングエラー時のエラーメッセージの改善 をご確認ください

• 転送フィルターの認証成功時の払い出しエラーが発生した場合、接続が失敗するようになりました

• 転送フィルターのセッション生成時の払い出しエラーが発生した場合、セッションが破棄されるようになりました

  • session_created_response_validate_warning_as_error が false の場合でもエラーとなりセッションを破棄します

• 統計情報に含まれる total_received_intra_frame を total_received_key_frame に変更しました

• JSON Lines 形式のログ出力に対してエスケープ処理を行わないようにしました

廃止情報

• JoinCluster API を廃止しました

  • 今後は同じ機能を持つ RegisterClusterNode API をご利用ください

• E2EE 機能を廃止しました

  • 将来的に Message Layer Security (MLS) を利用した E2EE 機能を提供予定です

  • ウェブフックに含まれる e2ee 項目は予約項目として常に false が含まれます

  • sora.conf から e2ee 項目を廃止しました

• sora.conf の移行用の設定 legacy_auth_webhook_log 設定を廃止しました

• sora.conf の移行用の設定 legacy_event_webhook_connection_destroyed_reason 設定を廃止しました

非推奨情報

• 転送フィルターを認証成功時やセッション生成時の払い出しで指定できる forwarding_filter を非推奨にしました

  • forwarding_filter は 2025 年 12 月リリース予定の Sora で廃止します

  • 代わりに複数の転送フィルターを指定できる forwarding_filters をご利用ください

• シグナリング接続時に転送フィルターを指定できる signaling_forwarding_filter を非推奨にしました

  • signaling_forwarding_filter は 2025 年 12 月リリース予定の Sora で廃止します

  • 代わりに複数の転送フィルターを指定できる signaling_forwarding_filters をご利用ください

• session.vanished を非推奨にしました

  • session.vanished は 2025 年 6 月リリース予定の Sora にて廃止します

  • 代わりに GetStatsReport API の total_ongoing_connections をご利用ください。

  • 値の監視については Sora Exporter の利用をお勧めします

• RTP ストリーム停止/再開 API を非推奨にしました

  • RTP ストリーム停止/再開 API は 2025 年 12 月リリース予定の Sora にて廃止します

  • 代わりに 転送フィルター をご利用ください

変更履歴

• [CHANGE] JSON Lines 形式のログ出力に対してエスケープ処理を行わないようにしました

• [CHANGE] 統計情報に含まれる total_received_intra_frame を total_received_key_frame に変更しました

  • RequestKeyFrame API に合わせた変更になります

• [CHANGE] spotlight.focused と spotlight.unfocused イベントウェブフックの送信を行わない場合はログを書き込まないよう変更しました

• [CHANGE] ウェブフックを送信を行わない (ignore) の設定した場合でも以下のウェブフックはログを出力するように変更しました

  • recording.started セッションウェブフック

  • session.updated セッションウェブフック

  • session.vanished セッションウェブフック

  • connection.failed イベントウェブフック

    • legacy_signaling_error が true かつ ignore_connection_failed_webhook が true の場合、 ログを出力しません

  • archive.started イベントウェブフック

  • recording.started イベントウェブフック

• [CHANGE] E2EE 機能を廃止しました

  • sora.conf の e2ee を廃止しました

  • ウェブフックに含まれる e2ee は常に false が含まれます

• [ADD] copy_websocket_signaling_header_names で指定した WebSocket シグナリングの HTTP ヘッダーを rtc_stats.jsonl と connection.jsonl に copy_headers 項目で出力するようにしました

• [ADD] 特定環境向けに TURN 利用時に 5-TUPLE を無視する設定を追加しました

  • この機能を利用する場合は事前にサポートまでご連絡ください

  • sora.conf の ignore_turn_five_tuple を true に設定することで、送られてくるパケットの 5-TUPLE を無視するようになります

• [ADD] "type": "offer" メッセージに audio と video 関連項目を追加しました

  • audio は必ず含まれます

  • audio_codec_type はオプションで、 audio が true かつ role が sendrecv または sendonly の場合に含まれます

  • audio_bit_rate はオプションで、 audio が true かつ role が sendrecv または sendonly で audio_bit_rate が指定された場合に含まれます

  • video は必ず含まれます

  • video_codec_type はオプションで、 video が true かつ role が sendrecv または sendonly の場合に含まれます

  • video_bit_rate はオプションで、 video が true かつ role が sendrecv または sendonly の場合に含まれます

• [ADD] サイマルキャスト機能の設定項目に scaleResolutionDownTo を追加しました

  • {"maxHeight": 1080, "maxWidth": 1920} のように解像度を指定することができるようになります

  • この機能は Chrome/Edge 131 以降で利用できます

  • https://w3c.github.io/webrtc-extensions/#dom-rtcrtpencodingparameters-scaleresolutiondownto

• [ADD] connection.jsonl に simulcast_encodings と simulcast_codecs 項目を追加しました

  • simulcast のみ true の場合は simulcast_encodings を出力します

  • simulcast と simulcast_multicodec が true の場合は simulcast_codecs も出力します

• [FIX] Safari や Chrome Canary で H.265 の配信ができない問題を修正しました

• [FIX] コネクションの切断が発生しない録画失敗のログレベルを error から warning に修正しました

• [FIX] 録画ファイル書き込みに失敗するとクラッシュログが出力されることがある問題を修正しました

• [FIX] サイマルキャスト機能利用時に simulcast_encodings に active を未指定だと接続が失敗する問題を修正しました

• [FIX] H.264 の RTP ペイロードヘッダーが不正な場合、サイレントディスカードするように修正しました

sora.conf

• [CHANGE] sora.conf の legacy_recording のデフォルトを true から false に変更しました

• [CHANGE] sora.conf の移行用の設定 legacy_auth_webhook_log 設定を廃止しました

• [CHANGE] sora.conf の移行用の設定 legacy_event_webhook_connection_destroyed_reason 設定を廃止しました

• [CHANGE] sora.conf の default_h264_param_profile_level_id のデフォルト値を 42e01f から 42e02a へ変更しました

  • Chrome / Edge がデフォルト値を変更した事への追従です

• [UPDATE] sora.conf の connection_created_wait_timeout の最小値を 1 s から 0 s へ変更しました

  • 挙動確認などで意図的にエラーを発生させられるように変更しました

• [FIX] ウェブフック送信時にボディを待つ時間に webhook_response_timeout が反映されていない問題を修正しました

• [FIX] ウェブフック送信時に TCP コネクションの確立を待つ時間に webhook_connect_timeout が反映されていない問題を修正しました

API

• [UPDATE] ListConnections API の戻り値に node_name を追加しました

• [UPDATE] ListChannelConnections API の戻り値に node_name を追加しました

• [UPDATE] GetStatsAllConnections API の戻り値に session_id を追加しました

• [UPDATE] GetStatsConnection API の戻り値に session_id を追加しました

• [UPDATE] GetStatsClient API の戻り値に session_id を追加しました

• [ADD] 指定したクライアントにキーフレームを要求する RequestKeyFrame API を追加しました

  • レガシーストリーム では利用できません

• [FIX] GetStatsReport API のウェブフック統計情報はウェブフックを送信したときのみカウントされるように修正しました

• [FIX] GetStatsReport API のウェブフック統計情報が正しくカウントされない問題を修正しました

  • total_ignored_session_webhook が実際よりも少なくカウントされていた問題を修正しました

  • audio-streaming.started と audio-streaming.stopped のウェブフック統計情報が total_ignored_XXX_webhook と total_successful_XXX_webhook の両方がカウントされていた問題を修正しました

セッション単位での同時接続数制限機能

これは実験的機能です

認証ウェブフックでの接続制限はウェブフックが並列で送信されるため、厳密な同時接続制限ができませんでした。 この機能ではセッション単位での同時接続数を制限することで、厳密に同時接続制限ができるようになります。

この機能を利用することで認証に成功した場合でも、セッションに接続できない場合があります。 その場合は、クライアントには SERVICE-UNAVAILABLE が通知されます。

この機能は実験的機能のトライアル中です。 将来的にロール単位やクライアント ID 単位での接続制限機能などを加えていく予定です。

正式版と明確に区別するため trial_ を prefix として付与しています。

• [ADD] session.created の払い出しにセッションの同時接続数を制限する trial_max_connections を追加しました

  • デフォルトは未指定で制限がない状態です

  • 指定できる範囲は 0..10000 です

  • trial_max_connections が 0 の場合は誰も接続することができなくなります

  • セッションが同時接続数制限に達した場合はクライアントに SERVICE-UNAVAILABLE を通知します

統計情報の追加

• [ADD] GetStatsReport API に SRTP パケットの統計情報を追加しました

  • total_received_srtp

    • 受信した SRTP パケットの合計数

  • total_received_srtp_byte_size

    • 受信した SRTP パケットの合計バイト数

  • total_sent_srtp

    • 送信した SRTP パケットの合計数

  • total_sent_srtp_byte_size

    • 送信した SRTP パケットの合計バイト数

  • total_decrypted_srtp

    • 復号した SRTP パケットの合計数

  • total_decrypted_srtp_byte_size

    • 復号した SRTP パケットの合計バイト数

• [ADD] GetStatsReport API に DataChannel で利用している SCTP パケットの統計情報を追加しました

  • total_received_sctp

    • DataChannel で受信した SCTP パケットの合計数

  • total_received_sctp_byte_size

    • DataChannel で受信した SCTP パケットの合計バイト数

  • total_sent_sctp

    • DataChannel で送信した SCTP パケットの合計数

  • total_sent_sctp_byte_size

    • DataChannel で送信した SCTP パケットの合計バイト数

• [ADD] GetStatsReport API に無視されたウェブフックの統計情報を追加しました

  • total_ignored_session_webhook

    • 無視されたセッションウェブフックの合計数

  • total_ignored_event_webhook

    • 無視されたイベントウェブフックの合計数

  • total_ignored_stats_webhook

    • 無視された統計ウェブフックの合計数

Sora 側からのシグナリング切断時のクライアントへの通知改善

• [CHANGE] WebSocket シグナリング利用時にメッセージサイズが大きすぎる場合の code を 4490 から 1009 に変更しました

  • メッセージサイズの最大は 5 MiB です

  • WebSocket の仕様に合わせました

• [CHANGE] WebSocket シグナリング利用時に Sora 側からのクライアントへの通知を改善しました

  • 正常切断

    • code は 1000 です

    • reason には切断理由が含まれます

      • TYPE-DISCONNECT

      • DISCONNECTED-API

      • LIFETIME-EXPIRED

      • SESSION-DESTROYED

  • 異常切断

    • 異常が発生して Sora 側から切断した場合は code に 4490 が含まれます

    • reason には切断理由が含まれます

• [ADD] sora.conf に data_channel_signaling_close_message を追加しました

  • デフォルトは false です

  • true の場合は Sora からコネクションを切断する際、 DataChannel シグナリングが有効かつ、 ignore_disconnect_websocket が true な場合 signaling ラベルに "type": "close" メッセージを送信します

  • false の場合は今まで通り、 DataChannel を閉じます

  • "type": "close" メッセージには code と reason が含まれます

  • 正常切断

    • 切断 API や期限切れで Sora 側から切断した場合は code に 1000 が含まれます

    • reason には切断理由が含まれます

      • LIFETIME-EXPIRED

      • SESSION-DESTROYED

      • DISCONNECTED-API

  • 異常切断

    • 異常が発生して Sora 側から切断した場合は code に 4490 が含まれます

    • reason には切断理由が含まれます

• [ADD] sora.conf に signaling_normal_close_reason を追加しました

  • デフォルトは true です

  • false を指定した場合、正常切断時の reason が空文字になります

  • false を指定した場合でも異常切断時は reason は含まれます

シグナリングエラーの改善

• [ADD] sora.conf にレガシーシグナリングエラーを有効にする設定を追加しました legacy_signaling_error を追加しました

  • デフォルトは false です

  • この設定は移行用で 2025 年 6 月に廃止します

  • この設定は 2024.1.x までの Sora との後方互換性を維持するための機能です

  • false の場合は log/connection_created_wait_timeout にログが出力されなくなりました

  • false の場合は log/signaling_error.jsonl にシグナリングエラーログが出力されるようになりました

  • false の場合は connection.failed ウェブフックは 認証成功時 かつ connection.created が送信されていない場合のみ送信されるようになりました

  • false の場合は sora.jsonl に認証失敗ログが出力されなくなりました

  • false の場合は sora.jsonl にシグナリング失敗ログが出力されなくなりました

  • true の場合は今まで通り ignore_connection_failed_webhook が true の場合、 event_webhook.jsonl にシグナリングログが出力されません

• [CHANGE] クライアントに通知するエラーメッセージを変更しました

  • クライアントへ通知するエラーがあまりにもサーバーよりのメッセージが多く、混乱を招くため整理しました

  • Sora の内部的なエラーは INTERNAL-ERROR を通知するよう変更しました

    • 以下のメッセージはクライアントへは通知されなくなりました

    • SIGNALING-INTERNAL-ERROR

    • AUTH-WEBHOOK-RESPONSE-EMPTY-BODY

    • AUTH-WEBHOOK-RESPONSE-UNEXPECTED-STATUS-CODE

    • INVALID-AUTHZ-MEDIA

    • WHEP-INCOMPATIBLE-UPSTREAM-TRACK

    • DUPLICATED-CONNECTION-ID-ERROR

    • INVALID-SPOTLIGHT-NUMBER

    • DUPLICATED-CHANNEL-ID

    • UNMATCH-CODEC-TYPE-ERROR

  • Sora が一時的に利用できない場合は SERVICE-UNAVAILABLE を通知するように変更しました

    • 以下のメッセージはクライアントへは通知されなくなりました

    • EXCEED-MAX-CONNECTIONS

    • BLOCK-NEW-CONNECTION

    • BLOCK-NEW-SESSION

    • INVALID-MODE

  • Sora でタイムアウトが発生した場合は TIMEOUT を通知するように変更しました

    • 以下のメッセージはクライアントへは通知されなくなりました

    • CONNECTION-CREATED-WAIT-TIMEOUT-ERROR

    • CONNECT-WAIT-TIMEOUT-ERROR

    • ANSWER-TIMEOUT-ERROR

    • PONG-TIMEOUT-ERROR

  • シグナリングメッセージが不正な場合は INVALID-MESSAGE を通知するように変更しました

    • 以下のメッセージはクライアントへは通知されなくなりました

    • INVALID-JSON

    • INVALID-SIGNALING-TYPE

    • INVALID-SIGNALING-PARAMS

    • MISSING-TYPE

    • BAD-FINGERPRINT

    • TOO-LARGE-JSON

    • TOO-MANY-CANDIDATE

    • INVALID-VIDEO-FORMAT

    • FAILURE-SDP-PARSE

    • MISSING-ICE-SDP

    • INVALID-VIDEO-FORMAT

    • INVALID-AUDIO-FORMAT

    • FAILURE-JSON-DECODE

    • UNEXPECTED-SIGNALING-TYPE

    • UNKNOWN-AUDIO-CODEC-TYPE

    • INVALID-AUDIO-BIT-RATE

    • UNKNOWN-VIDEO-CODEC-TYPE

    • INVALID-VIDEO-BIT-RATE

録画機能

• [CHANGE] 録画ファイル処理の開始に失敗した場合のログレベルを ERROR から WARNING に変更しました

• [ADD] イベントウェブフック archive.* と split-archive.* に項目を追加しました

  • split_only

    • 指定していない場合、値は false になります

  • format

    • mp4 または webm が含まれます

  • expire_time

    • 指定していない場合は項目が含まれません

  • expired_at

    • 指定していない場合は項目が含まれません

  • split_duration

    • 指定していない場合は項目が含まれません

• [FIX] AV1 サイマルキャスト使用時に録画が正常に行われない問題を修正しました

MP4 録画機能

これは実験的機能です

MP4 形式での録画ファイル出力に対応しました。

• [ADD] MP4 形式での録画に対応しました

  • MP4 録画機能はレガシー録画機能では利用できません

  • OBS が提唱する Hybrid MP4 形式に対応しています

    • https://obsproject.com/kb/hybrid-mp4

    • https://obsproject.com/blog/obs-studio-hybrid-mp4

• [ADD] sora.conf に default_recording_format を追加しました

  • デフォルトは webm です

  • webm と mp4 が指定できます

  • MP4 録画機能はレガシー録画機能では利用できません

• [ADD] StartRecording API に format (オプション) を追加しました

  • format には webm と mp4 が指定できます

  • format が未指定の場合は default_recording_format の値が利用されます

  • 映像コーデックが H.265 の場合 format に mp4 を指定しない場合、録画が行われません

• [ADD] session.created の払い出しに recording_format を追加しました

  • recording_format には webm と mp4 が指定できます

  • recording_format が未指定の場合は default_recording_format の値が利用されます

  • 映像コーデックが H.265 の場合 format に mp4 を指定しない場合、録画が行われません

• [ADD] session.updated の recording に format を追加しました

  • "format": "webm" または "format": "mp4" が含まれるようになりました

• [ADD] セッションウェブフック recording.* に data.format を追加しました

  • "format": "webm" または "format": "mp4" が含まれるようになりました

• [ADD] イベントウェブフック archive.* と split-archive.* に data.format を追加しました

  • "format": "webm" または "format": "mp4" が含まれるようになりました

• [ADD] sora.conf に録画機能(セッション単位) 利用時に MP4 形式を利用した場合、クライアントへ送るキーフレーム要求 (PLI) の間隔を指定できる default_recording_mp4_pli_interval を追加しました

  • デフォルトは 20 s です

  • 最小は 1 s で、最大は 240 s です

  • WebM 形式ではキーフレームの間隔が最大でも 31 秒までという制約がありましたが、 MP4 形式ではこの制約がなくなりました

H.265 録画機能

これは実験的機能です

H.265 コーデックでの録画機能に対応しました。

• [ADD] H.265 録画機能に対応しました

  • H.265 は format に mp4 が設定されている場合のみ録画ができます

  • WebM 形式を設定した場合 H.265 の録画は行われません

  • H.265 録画機能はレガシー録画では利用できません

ICE コネクションステート変更のシグナリング通知

これは実験的機能です

ICE コネクションステートが変更した際、 同一チャネルに接続している自分を含むクライアント全員へ通知する仕組みを追加しました。

この機能を利用することで、 自分の ICE コネクションステートの変更を 同じセッションに参加している自分を含むクライアント全員 へシグナリング通知が送信されます。 また、接続時に 既にチャネルに参加しているクライアント全員の ICE コネクションステート を取得できるようになります。

他のシグナリング通知機能とは異なり、この設定は有効にした場合、 自分を含むチャネル参加者全員へ通知を行いますので注意してください。

用途としては 4 人で双方向のビデオ通話をしている際、 特定のクライアントが不安定だという事を知ったり、 1:50 の片方配信の際に配信者の通信状態を視聴者側が知ったりすることができるようになります。

通知されるタイミングは 4 種類あります。

1. connected から checking になった時

2. checking から connected になった時

3. checking から disconnected になった時

4. disconnected から checking になった時

• [ADD] sora_conf に signaling_notify_ice_connection_state を追加しました

  • デフォルトは false です

  • true に設定すると ICE コネクションステートが変更された際に、同一チャネルに接続しているクライアントへシグナリング通知 ice-connection-state.changes を送信します

  • true にするとチャネル参加時のシグナリング通知 connection.created の既存参加者の data に ice_connection_state が含まれるようになります

• [ADD] 認証成功時の払い出しに signaling_notify_ice_connection_state を追加しました

  • デフォルトは signaling_notify_ice_connection_state の値が採用されます

  • false を払い出すことで自身の ICE コネクションステートの状態を他のチャネルに参加しているクライアントへシグナリング通知が送信されなくなります

• [ADD] ICE コネクションステートを強制的に変更し維持する LockIceConnectionState テスト API を追加しました

転送フィルター機能

• [CHANGE] 認証成功時の転送フィルターの払い出しがエラーになった場合、接続が失敗するように変更しました

  • INTERNAL-ERROR エラーとなります

• [CHANGE] セッション生成時の転送フィルターの払い出しがエラーになった場合、セッションを破棄するように変更しました

  • INTERNAL-ERROR エラーとなります

  • session_created_response_validate_warning_as_error が false の場合でもエラーとなりセッションを破棄します

マルチ転送フィルター機能

これは実験的機能です

マルチ転送フィルター機能は 1 チャネルや 1 コネクションに対して 1 つしか指定できなかった転送フィルターを 名前と優先度を設定し、複数の転送フィルターを指定できるようにする機能です。

• [ADD] 認証成功時の払い出しに複数の転送フィルターを設定できる forwarding_filters を追加しました

  • 既存の forwarding_filter は 2025 年 12 月リリース予定の Sora にて廃止します

• [ADD] セッション生成時の払い出しに複数の転送フィルターを設定できる forwarding_filters を追加しました

  • forwarding_filter は 2025 年 12 月リリース予定の Sora にて廃止します

• [ADD] sora.conf にシグナリング時に複数の転送フィルターを設定できる forwarding_filters を設定できるようになる signaling_forwarding_filters を追加しました

  • signaling_forwarding_filter は 2025 年 12 月リリースの Sora にて廃止します

• [ADD] 転送フィルター設定時に name と priority を指定できるようになりました

• [ADD] 転送フィルター API ListForwardingFilters にチャネルの転送フィルターをリストで表示する channel_forwarding_filters を追加しました

  • 既存の channel_forwarding_filter は 2025 年 12 月リリース予定の Sora にて廃止します

• [ADD] 転送フィルター API CreateChannelForwardingFilter と CreateConnectionForwardingFilter に name と priority を追加しました

• [ADD] 転送フィルター API UpdateChannelForwardingFilter と UpdateConnectionForwardingFilter に name と priority を追加しました

• [ADD] 転送フィルター API DeleteChannelForwardingFilter と DeleteConnectionForwardingFilter に name を追加しました

詳細は マルチ転送フィルター機能 をご確認ください。

OBS WHIP

• [FIX] OBS WHIP で H.264 で一部のエンコーダーを利用した際、録画ファイルの映像が正常に記録されない問題を修正しました

• [FIX] OBS WHIP で AV1 で録画できない問題を修正しました

メッセージングヘッダー機能

リアルタイムメッセージング機能において、 メッセージに Sora 側でヘッダーを追加する機能です。 sender_connection_id を追加できます。

• [ADD] data_channels にメッセージングにヘッダーを追加する header 項目を新しく追加しました

  • ヘッダーを付与するかどうかはメッセージを受信する側が指定します

    • {"label": "#spam", "direction": "recvonly", "header": [{"type": "sender_connection_id"}]

    • この設定を行ったクライアントは #spam ラベルのメッセージは常に先頭 26 バイトに sender_connection_id が含まれるようになります

  • ヘッダーは Sora 側で付与します

  • header はオプションです

  • header には [{"type": "sender_connection_id"}] のように指定します

  • type は sender_connection_id のみ指定可能です

    • sender_connection_id はメッセージングの送信元の connection_id です

    • 先頭 26 バイトが sender_connection_id になります

    • 将来的に指定できる type を増やして行く予定です

  • "type": "offer" 時の data_channels に header が含まれる場合、 length 項目を追加します

    • length は sender_connection_id の長さです

    • length の単位はバイトです

    • sender_connection_id の場合 length は 26 固定です

音声ストリーミングヘッダー機能

音声ストリーミング機能において、HTTP/2 経由で送信する音声パケットに Sora 側でヘッダーを追加する機能です。

• [ADD] 音声ストリーミング機能利用時に sora.conf に audio_streaming_header を追加しました

  • デフォルトは false です

  • true に設定すると音声パケットに Sora がヘッダーを追加します

  • ヘッダーのフォーマットは [Timestamp:64 bit, SequenceNumber:64 bit, Length:32 bit] です

  • timestamp は音声パケット送信時の UTC 時間マイクロ秒の整数です

    • RTP のタイムスタンプとは異なります

  • seq_num は音声パケットのシーケンス番号で、 1 から始まります

    • RTP のシーケンス番号とは異なります

  • length はヘッダーを除いた音声パケットの長さです

        ---
title: "音声ストリーミングヘッダーフォーマット"
---
packet-beta
0-63: "Timestamp"
64-127: "SeqNum"
128-159: "Length"
    

プレイアウト遅延機能

実験的機能です

プレイアウト遅延機能の仕様を変更しました。 今までは配信側に影響する設定でしたが、今回のリリースから視聴側に影響する設定に変更しました。

この変更により視聴側毎にプレイアウト遅延を指定できるようになりました。

• [ADD] sendrecv と recvonly のロールに影響するよう設定を変更しました

  • sendonly には影響しません

• [CHANGE] sora.conf の default_playout_delay_min_delay は視聴側のプレイアウト遅延の最小値のデフォルトを指定するように変更しました

  • デフォルトは未指定です

• [CHANGE] sora.conf の default_playout_delay_max_delay は視聴側のプレイアウト遅延の最大値のデフォルトを指定するように変更しました

  • デフォルトは未指定です

• [CHANGE] 認証成功時の払い出し playout_delay_min_delay は視聴側の最小値を指定するように変更しました

  • playout_delay_max_delay も一緒に指定する必要があります

• [CHANGE] 認証成功時の払い出し playout_delay_max_delay は視聴側の最大値を指定するように変更しました

  • playout_delay_min_delay も一緒に指定する必要があります

詳細は プレイアウト遅延機能 をご確認ください。

テスト API

• [UPDATE] テスト API がクラスターで利用できるようになりました

• [UPDATE] テスト向け API の録画失敗を意図的に起こす FailArchive API をクラスターに対応しました

• [UPDATE] テスト向け API のシグナリング通知を送信する SendSignalingNotify API をクラスターに対応しました

用語集

クライアント

クライアントは Sora と WebSocket や WebRTC で接続している個を指し、各接続にはユニークな ID が与えられます。

1. 1 接続 1 クライアントの原則:

   • Sora における各接続はそれぞれ別個のクライアントとして扱われます。つまり、1 つの接続は 1 つのクライアントとして扱われます

2. ユニークな ID であるコネクション ID の割り当て:

   • クライアントが Sora に接続すると、その接続には固有の ID (コネクション ID) が割り当てられます

3. 複数クライアントのサポート:

   • SDK を利用することで、ユーザーは複数のクライアントを使用し、複数の接続を確立することが可能です

4. 同一ユーザーによる接続の統合:

   • 同じユーザーが複数の接続を行う場合、これらの接続に同じクライアント ID を指定することで、ユーザーを一意に識別できます

5. クライアント ID の自動割り当て:

   • クライアント ID を指定しない場合、 Sora はコネクション ID をクライアント ID として自動的に割り当てます

チャネル

チャネルは Sora で使用される「ルーム」や「グループ」として機能する、独立したコミュニケーションのスペースです。

1. コミュニケーションの制限:

   • チャネルに接続したクライアントは、そのチャネル内でのみ音声、映像、データのやりとりが可能です。 異なるチャネルのクライアント間での直接のコミュニケーションはできません

2. 複数チャネルへのアクセス:

   • 一つのウェブブラウザを使用して、複数のクライアントが同時に複数のチャネルにアクセスすることが可能です

3. チャネル ID:

   • 利用者はチャネルに 255 バイトまでの値を ID として指定できます

セッション

セッションは実際にチャネルに参加しているクライアントの集まりを指し、各セッションにはユニークな ID が与えられます。

1. セッションの存在:

   • チャネルに 1 つ以上のクライアントが接続している状態を「セッションが存在する」と言い、 逆にクライアントが 1 人も接続していない場合は「セッションが存在しない」と言います

2. セッションの生成:

   • セッションは、セッションがまだ存在しないチャネルにクライアントが接続した時に生成されます。

3. セッションの破棄:

   • 全てのクライアントがチャネルから切断した後、一定期間が経過するとセッションは破棄されます。

4. セッション ID:

   • セッションには Sora が自動で生成する一意の ID が割り当てられます

コネクション

コネクションはクライアントが接続している状態を指し、各コネクションにはユニークな ID が与えられます。

1. コネクションの生成:

   • クライアントが接続し、認証に成功した後、WebRTCが確立されるとコネクションが生成されます

2. コネクションの破棄:

   • クライアントが切断すると、そのコネクションは破棄されます

3. コネクション ID の自動割り当て:

   • コネクションには Sora が自動で生成する一意の ID が割り当てられます

ロール

Sora のロールは、クライアントが音声や映像をどのように取り扱うかを決定する役割を果たします。

1. sendrecv (送受信):

   • sendrecv ロールを選択したクライアントは、音声および映像の送受信が可能です。 これは、クライアントが他のクライアントと音声や映像を交換する、双方向のコミュニケーションができる状態を意味します

2. sendonly (送信のみ):

   • sendonly ロールを選択したクライアントは、音声および映像の送信のみが可能です。 これは、自分の音声や映像を他のクライアントに送ることはできますが、他からの音声や映像を受け取ることはできない状態を意味します

3. recvonly (受信のみ):

   • recvonly ロールを選択したクライアントは、音声および映像の受信のみが可能です。 これは、他のクライアントからの音声や映像は受け取ることができますが、自分から送ることはできない状態を意味します

4. ロールの選択タイミング:

   • クライアントは接続時にのみロールを選択できます。一度選択されたロールは、その後の接続中に変更することはできません

5. ロールとメッセージング機能の独立性:

   • ロールの選択はSoraのメッセージング機能には影響しません。 メッセージング機能の方向性（送信、受信、またはその両方）については、別の項目「direction」で管理されます

既知の問題

既知の問題の詳細についてはサポートまでお問い合わせください

Chrome/Edge の不具合による録画機能利用時の音ズレ問題について

Chrome/Edge の不具合により、音声トラックを削除し、その後音声トラックを追加した際に、 音声パケットやそれに関連するタイムスタンプが正しく処理されない場合があり、 これにより録画機能を利用する際に音ズレが発生する問題があります。

この Chrome/Edge の問題は残念ながら解決の見込みはありませんが、録画機能への影響があまりにも大きいため、 Sora 2024.1.0 でこの問題の改善を行いました。

しかし、この改善のための変更が Chrome の別の不具合の影響を受けて新たな問題が発生することが判明したため、 本変更をデフォルトで無効にすることにしました。

この問題への改善は今後も継続していく予定です。

この問題に関して不明点がありましたら、サポートまでご連絡ください。

警告

Safari および Safari Technology Preview でも音ズレが発生する問題を確認しています。

Sora 2024.1.3 での変更点

Sora 2024.1.0 で rtp_hdrext_abs_capture_time のデフォルトを true へ変更し、 RTP ヘッダー拡張 abs-capture-time を利用することで録画機能利用時の音ズレを回避する仕組みを追加しました。

しかし、一部の端末では予期しない挙動が発生し、録画自体に問題が発生することが判明したため、 Sora 2024.1.3 で rtp_hdrext_abs_capture_time の デフォルトを false へ変更しました。

この設定を true にする場合は、事前にサポートまでご連絡ください。

署名アルゴリズムに SHA-1 が利用されている中間証明書をご利用されているお客様へ

Sora 2023.2.x から、署名アルゴリズムが SHA-1 の中間証明書を利用した場合、 Bad Certificate エラーとして接続が拒否されます。

影響のある機能は下記の機能です。

• ウェブフック機能

• 音声ストリーミング機能

• 統計エクスポーター機能

もし、このエラーがログに出力された場合はサポートまでご連絡ください。

サイマルキャスト録画機能

• Windows 版 Chrome で H.264 のサイマルキャストを録画した場合に画質が悪くなります

• AV1 サイマルキャスト時の録画を利用する場合 scalabilityMode が L1T1 以外では正常に再生できません

マルチストリーム機能

• "type": "sendrecv" 利用時に音声のみや映像のみを指定した場合でも、音声と映像の両方が送られてきます

  • 転送フィルター機能を利用してください

  • 将来的に改善予定です

OBS WHIP/WHEP 機能

スポットライト利用時に音声が自動で配信されない

• OBS 側の WHIP に利用している WebRTC スタック実装で音量レベルを音声パケットに載せてこないため判断ができません

  • FocusSpotlightFixed API を利用して OBS の接続にフォーカスをあてることで音声を配信できます

• WHIP でのスポットライト有効時は音声を自動で配信する仕組みを導入するか、 OBS 側の WHIP に利用している WebRTC スタックへ貢献することを検討しています

仕様としての制限

マルチトラック

• 1 つのストリームに 1 オーディオトラック、1 ビデオトラックしか設定できません

  • マルチトラックへの対応は検討していますが未定です

実験的機能

重要

実験的機能を本番環境で利用する場合は 必ず サポートまでご連絡ください。

概要

実験的機能とは、正式リリースに向けて積極的に改善を行っている機能、および正式リリースを行うかについて決定を保留にしている機能であり、 今後、後方互換性のない仕様変更を行う可能性があります。

仕様の変更はあるものの、動作が不安定であることやバグを多く含んでいることを意味するものではなく、ご利用の場合はサポートの対象となります。 また、実験的機能に関するお客様からのお問い合わせやフィードバックを基に、今後の開発方針を決定することがあります。

ごく稀に、正式リリースを見合わせて削除する機能もありますので、具体的な機能については以下の一覧でご確認いただくとともに、 実際に本番環境でご利用いただく場合は事前にサポートまでご連絡いただきますようお願いします。

トライアル一覧

セッション単位での最大同時接続数制限機能

重要

この機能はトライアル中で、正式リリースに向けてサポートへのフィードバックをお願いしています。

注意

この機能を利用する場合は事前にサポートまでご連絡ください。

セッション生成時の払い出しで trial_max_connections を払い出すことで、セッション単位での同時接続数を厳密に制限することができます。

詳細は trial_max_connections をご覧ください。

実験的機能一覧

正式リリースに向けて改善を進めている機能

• リレー機能

  • 2025 年 6 月リリースの Sora にて正式リリースの予定です

• アフィニティ機能

  • 2025 年 6 月リリースの Sora にて正式リリースの予定です

• テンポラリーノード機能

  • 2025 年 6 月リリースの Sora にて正式リリースの予定です

• 統計ウェブフック機能

  • 2025 年 6 月リリースの Sora にて正式リリースの予定です

• RTC 統計情報 API

  • 2025 年 6 月リリースの Sora にて正式リリースの予定です

• シグナリング通知メタデータ拡張 API

  • 2025 年 12 月リリースの Sora にて正式リリースの予定です

• シグナリング通知 ICE コネクションステート

  • 2025 年 12 月リリースの Sora にて正式リリースの予定です

• マルチ転送フィルター機能

  • 2025 年 12 月リリースの Sora にて正式リリースの予定です

• MP4 形式録画機能

  • 2025 年 12 月リリースの Sora にて正式リリースの予定です

• プレイアウト遅延機能

  • 2025 年 12 月リリースの Sora にて正式リリースの予定です

• OBS (WHEP) 対応

  • OBS の WHEP 対応がリリースされた後、正式リリースの予定です

• サイマルキャストマルチコーデック機能

  • 2026 年 6 月リリースの Sora にて正式リリースの予定です

• H.265 対応

  • Chrome/Edge の H.265 対応がリリースされた後、正式リリースの予定です

正式リリースが未定の機能

• 映像コーデックパラメーター指定機能

  • signaling_vp9_params

  • signaling_av1_params

  • signaling_h264_params

  • signaling_h265_params

  • default_vp9_param_profile_id

  • default_av1_param_profile

  • default_h264_param_profile_level_id

  • default_h265_param_level_id

  • ビデオの VP9 設定指定

  • ビデオの AV1 設定指定

  • ビデオの H.264 設定指定

  • ビデオの H.265 設定指定

• 音声コーデックパラメーター指定機能

• ウェブフック HTTP ヘッダー

• 統計 API

• GetStatsReport API

• session.vanished

正式リリースを行うかについて検討を保留にしている機能

• H.264/H.265 B-frame 対応

  • h264_b_frame

  • h265_b_frame

• RTP 転送 API

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

• ListChannels API

• 片方向配信時の視聴側帯域推定を利用した配信ビットレートの自動変更機能

• 映像コーデックのビットレートを 15 Mbps より大きく指定した場合

廃止予定がある実験的機能

• 統計エクスポーター機能

• RTP ストリーム停止/再開 API

非推奨機能

ここでは今後廃止される非推奨の機能について説明していきます。

不明点はサポートまでお問い合わせください。

CentOS 7 対応

CentOS 7 は 2024 年 6 月末でサポートが終了となるのに合わせて、Sora の CentOS 7 版については以下のとおりとなります。

パッケージの提供:

2023 年 12 月にリリースの 2023.2.0、およびその後リリースされる可能性のある 2023.2.x の提供をもって終了

サポートの終了:

2023.2.0 およびおよびその後リリースされる可能性のある 2023.2.x に対しては 2024 年 12 月末で終了

• EOL CentOS | End of Life (EOL) | Lifecycle

CentOS 7 版をご利用のお客様は、早めに OS の変更をご検討の上、移行先の OS をサポートまでご連絡下さい。

Ubuntu 20.04 対応

Ubuntu 20.04 は 2025 年 4 月末でサポートが終了となるのにあわせて、Sora の Ubuntu 20.04 版については以下のとおりとなります。

パッケージの提供:

2024 年 6 月にリリースの 2024.1.0、およびその後リリースされる可能性のある 2024.1.x の提供をもって終了

サポートの終了:

2024.1.0 およびおよびその後リリースされる可能性のある 2024.1.x に対しては 2025 年 6 月末で終了

Ubuntu 20.04 版をご利用のお客様は、早めに OS の変更をご検討の上、移行先の OS をサポートまでご連絡下さい。

レガシー録画機能の廃止

重要

2025 年 12 月リリース予定の Sora にて廃止

レガシー録画機能 を廃止します。

今後は 録画機能 (セッション単位) をご利用ください。

移行に関しては レガシー録画機能から新しい録画機能 (セッション単位) への移行 をご確認ください。

• 2024 年 12 月リリース予定の Sora にて legacy_recording のデフォルトを false に変更します

• 2025 年 12 月リリース予定の Sora にて legacy_recording の設定を廃止し、レガシーレコーディングを廃止します。

レガシーストリーム(非マルチストリーム)機能の廃止

重要

2025 年 6 月リリース予定の Sora にて廃止

レガシーストリーム(非マルチストリーム)機能を廃止します。

今後はマルチストリームをご利用ください。

移行に関しては レガシーストリーム(非マルチストリーム)機能からマルチストリームへの移行 をご確認ください。

• 2024 年 6 月リリースの Sora にて legacy_stream の設定をデフォルト false にて追加しました

• 2025 年 6 月リリース予定の Sora にて legacy_stream の設定を廃止し、レガシーストリームを廃止します

ListForwardingFilters API の channel_forwarding_filter の廃止

重要

2025 年 12 月リリース予定の Sora にて廃止

ListForwardingFilters API の戻り値 channel_forwarding_filter を廃止します。

今後は channel_forwarding_filters をご利用ください。

移行期間中は channel_forwarding_filter と channel_forwarding_filters の両方を API の戻り値として出力します

認証成功時とセッション生成時の forwarding_filter の廃止

重要

2025 年 12 月リリース予定の Sora にて廃止

認証成功時とセッション生成時の forwarding_filter を廃止します。

今後は forwarding_filters をご利用ください。

移行期間中は forwarding_filter と forwarding_filters の両方を払い出すことができます。 その場合は forwarding_filters の値を優先します。

RTP ストリーム停止/再開 API の廃止

重要

2025 年 12 月リリース予定の Sora にて廃止

RTP 転送ストリーム停止/再開 API は 転送フィルター により同等の機能が提供でき、 重複機能となるため廃止します。

今後は 転送フィルター をご利用ください。

統計エクスポーター機能の廃止

重要

2025 年 6 月リリース予定の Sora にて廃止

実験的機能として提供している統計エクスポーター機能を廃止します。

今後は 統計ウェブフック をご利用ください。

ユーザーエージェント統計の廃止

重要

2025 年 6 月リリース予定の Sora にて廃止

統計エクスポーター機能廃止に伴い、ユーザーエージェント統計関連も廃止します。

今後は RTC 統計を利用してください。

• 認証ウェブフック成功時の払い出しで利用する user_agent_stats を廃止します

  • rtc_stats をご利用ください

• sora.conf の user_agent_stats を廃止します

  • default_rtc_stats をご利用ください

session.vanished の廃止

重要

2025 年 6 月リリース予定の Sora にて廃止

session.vanished を廃止します。

代わりに GetStatsReport API の total_ongoing_connections をご利用ください。

また Sora Exporter をご利用いただくことで、Sora の統計情報を OpenMetrics 形式で取得できますので、 こちらもご利用ください。

スポットライト機能 spotlight_number 項目の認証成功時の払い出しの非推奨化

重要

現時点では廃止予定はありませんが、将来的に 1 年の移行期間をもうけて廃止する予定です。

セッションウェブフック session.created で spotlight_number の値を払い出すことができるようになりました。

そのためスポットライト機能の spotlight_number 項目を認証ウェブフック成功時の払い出しで利用するのは非推奨でになります。 現時点では廃止予定はありませんが、将来的に 1 年以上の移行期間を経て廃止される予定です。

ウェブフックと統計エクスポーターの HTTP ヘッダー x-sora prefix の非推奨化

重要

現時点では廃止予定はありませんが、将来的に 1 年の移行期間をもうけて廃止する予定です。

x-sora prefix とは別に sora prefix の HTTP ヘッダーを追加しました。 これは RFC 6648 による x- prefix の非推奨化に準拠するためです。

x-sora prefix は非推奨になります。現時点では廃止予定はありませんが、将来的に 1 年以上の移行期間を経て廃止される予定です。

• セッションウェブフックの x-sora-session-webhook-type ヘッダーは非推奨です、 sora-session-webhook-type ヘッダーを利用してください

• イベントウェブフックの x-sora-event-webhook-type ヘッダーは非推奨です、 sora-event-webhook-type ヘッダーを利用してください

• 統計エクスポーターの x-sora-stats-exporter-type ヘッダーは非推奨です、 sora-stats-exporter-type ヘッダーを利用してください

  • 統計エクスポーターが 2024 年 12 月リリース予定の Sora にて廃止されるため、この項目は廃止される予定です

API

非推奨 API をご確認ください

廃止機能

概要

廃止機能とはすでに廃止された機能です。

API の廃止については 廃止 API をご確認ください。

ListClusterNodes API の include_all_known_nodes の廃止

2024 年 12 月リリースの Sora にて廃止

ListClusterNodes API の include_all_known_nodes は廃止しました。

今後はそのクラスターへ登録されている全てのノード情報が常に含まれるようになります。

もし一時的に離脱しているノードを含めない場合は API の結果を "connected": true でフィルタリングしてください。

sora.conf の legacy_auth_webhook_log の廃止

2024 年 12 月リリースの Sora にて廃止

今まで認証ウェブフックが 200 番台を返さなかったり、 "allowed" 項目を含まなかったり、 "allowed": false なのに "reason" が含まれていなかったり、送信先から応答がなくタイムアウトしたなどで、 処理が正常に行えなかった場合は auth_webhook.jsonl に res 項目なしで出力していました。

この仕様を維持する legacy_auth_webhook_log 設定を廃止しました。

今後は auth_webhook_error.jsonl に reason 項目を追加して出力するように変更しました。

sora.conf の legacy_event_webhook_connection_destroyed_reason の廃止

2024 年 12 月リリースの Sora にて廃止

Sora 2023.2.x まで connection.destroyed の reason には、 disconnect_api_reason と同じ値が含まれており、 コネクション切断系 API で reason が指定されていない場合は null が含めていました。

この仕様を維持する legacy_event_webhook_connection_destroyed_reason 設定を廃止しました。

今後は connection.destroyed の reason には以下のような値が入ります。

• "normal" は通常のコネクション破棄

• "disconnected_api" はコネクション切断系 API によるコネクション破棄

• "session_destroyed" はセッションライフタイム期限切れ、または API によるセッション破棄によるコネクション破棄

• "lifetime_expired" はライフタイム期限切れによるコネクション破棄

認証成功時の払い出し h264_profile_level_id の廃止

2024 年 6 月リリースの Sora にて廃止

認証成功時の払い出しで H264 のプロファイルレベルの値を指定する h264_profile_level_id を廃止しました。

"video_h264_params": {"profile_level_id": ...} をご利用ください。

sora.conf の default_h264_profile_level_id の廃止

2024 年 6 月リリースの Sora にて廃止

H264 のプロファイルレベルのデフォルト値を指定する default_h264_profile_level_id を廃止しました。

default_h264_param_profile_level_id をご利用ください。

Lyra コーデック対応の廃止

2024 年 6 月リリースの Sora にて廃止

Lyra コーデック対応を廃止しました。

Opus 1.5 で Lyra 同様の低ビットレートが利用可能になったこと、Lyra が 2 年間更新がないことが廃止の理由です。

sora.conf の legacy_log_format の廃止

2023 年 12 月リリースの Sora にて廃止

sora ログや internal ログをレガシーフォーマットで出力する sora.conf の legacy_log_format 設定を廃止しました。

sora.conf の legacy_log_extension の廃止

2023 年 12 月リリースの Sora にて廃止

JSONL 形式で出力するログの拡張子を .log でファイル出力する sora.conf の legacy_log_extension 設定を廃止しました。

sora.conf の legacy_webhook_audio_video_json_structure の廃止

2023 年 12 月リリースの Sora にて廃止

ウェブフックで利用する audio と video の JSON 構造を {"audio": {"codec_type": "OPUS"}} といった入れ子構造にする sora.conf の legacy_webhook_audio_video_json_structure 設定を廃止しました。

DataChannel で利用している SCTP 関連の実験的な設定の廃止

2023 年 6 月リリースの Sora にて廃止

DataChannel で利用している SCTP 関連の実験的な設定である dcsctp_heartbeat_interval と dcsctp_slow_start_tcp_style の設定を廃止しました。

Ubuntu 18.04 サポートの終了

サポート提供終了:

2023 年 4 月末

Ubuntu release cycle | Ubuntu

Ubuntu 18.04 は 2023 年 6 月末で通常サポートが終了しました。

Ubuntu 側から 4 月末での通常サポート終了が 6 月末まで延長されましたが、 Sora は当初の予定のまま 2023 年 4 月末をもって Ubuntu 18.04 版のサポートとパッケージの提供を終了しました。

Ubuntu 20.04 または Ubuntu 22.04 版への移行をお願いいたします。

Ubuntu 18.04 を利用しているお客様は、サポートまで切り替え先の OS をご連絡ください。

sora.conf の split_archive_legacy_prefix の廃止

2023 年 6 月リリースの Sora にて廃止

sora.conf の split_archive_legacy_prefix 設定を廃止しました。

• 分割録画ファイル名 archive-<connection_id>_<index>.(json|webm) が利用できなくなりました

  • split-archive-<connection_id>_<index>.(json|webm) を利用するように変更してください

• 分割録画時のイベントウェブフックタイプ "type": "archive.split" が利用できなくなりました

  • "type": "split-archive.available" を利用するように変更してください

• 分割録画時のイベントウェブフックタイプ "type": "archive.end" が利用できなくなりました

  • "type": "split-archive.end" を利用するように変更してください

sora.conf の default_multistream の廃止

2023 年 6 月リリース予定の Sora にて廃止

sora.conf の default_multistream 設定を廃止しました。

今後は接続時に multistream を指定せずに接続した場合は常にマルチストリームが有効になります。

redact_archive_metadata_sensitive_data と redact_api_sensitive_data の廃止

2022 年 12 月リリースの Sora にて廃止

録画メタデータと API のセンシティブデータを "REDACTED" という文字列に書き換えを廃止しました。 今後はこれらのデータは書き換えを行いません。

recording.report の metadata_filename と metadata_file_path の廃止

2022 年 12 月リリースの Sora にて廃止

録画イベントウェブフックの recording.report に含まれる metadata_filename と metadata_file_path が filename と file_path に変更されます。

2021 年 12 月リリースの Sora にて filename と file_path が追加されていますので、そちらを利用するように変更してください。

シグナリング通知メタデータ metadata_list の廃止

2022 年 6 月リリースの Sora にて廃止

metadata_list が data に変更されました。

"type": "update" の廃止

2022 年 6 月リリースの Sora にて廃止

マルチストリーム機能利用時のシグナリングで利用する "type": "update" を廃止し、 "type": "re-offer" と "type": "re-answer" に変更しました。

sora.conf の demo の廃止

2022 年 6 月リリースの Sora にて廃止

sora.conf の demo を廃止しました。今後は devtools を利用してください。

これは デモ機能 が 開発者ツール へと名前を変更したことによる影響です。

sora.conf の remote_stats の廃止

2022 年 6 月リリースの Sora にて廃止

sora.conf の remote_stats を廃止しました。今後は user_agent_stats を利用してください。

これは リモート統計情報 が ユーザーエージェント統計情報 へと名前を変更したことによる影響です。

StopRecording API の redirect の配信

2022 年 6 月リリースの Sora にて廃止

録画機能がクラスターで共有できるようになったことにより、 redirect 指定が不要になったため廃止しました。

CentOS 8 対応

サポート提供終了:

2021 年 12 月

• CentOS Project shifts focus to CentOS Stream – Blog.CentOS.org

• FAQ - CentOS Project shifts focus to CentOS Stream

• FAQ: CentOS Stream Updates

CentOS 8 は 2021 年 12 月をもってサポートが終了しました。 それに伴い Sora は 2021 年 12 月末をもって CentOS 8 版のサポートとパッケージの提供を終了しました。

extmap_allow_mixed 設定のデフォルト有効化と廃止

2021 年 12 月リリースの Sora にて廃止

Chrome M89 にて a=extmap-allow-mixed がデフォルトで設定されるようになり、 また Firefox 側でも動作に問題がなくなったことからこちらの設定が不要となりました。 2021 年 6 月リリースの Sora でデフォルト有効とし、2021 年 12 月リリースの Sora にて設定を廃止しました。

スポットライトレガシー機能の廃止

2021 年 12 月リリースの Sora にて廃止

スポットライトレガシー機能は 2021 年 12 月リリースの Sora で廃止しました。

今後は スポットライト機能 を利用してください。

rtp にある RTCP 関連統計情報を廃止

2021 年 12 月リリースの Sora にて廃止

統計 API の rtp 項目に入っている RTCP 関連統計情報を rtcp 項目として独立させました。

これに伴い rtp にある RTCP 関連統計情報を廃止しました。

sora.conf の opus_param_clock_rate を廃止

2021 年 12 月リリースの Sora にて廃止

実験的機能として提供していた opus_param_clock_rate を廃止しました。

sora.conf の dcsctp_association_max_retrans を廃止

2021 年 12 月リリースの Sora にて廃止

実験的機能として提供していた dcsctp_association_max_retrans を廃止しました。

今後は ICE コネクションステート機能 を利用してください。

role の upstream と downstream を廃止

2021 年 6 月リリースの Sora にて廃止

upstream と downstream は 2021 年の 6 月リリースの Sora で廃止しました。

• マルチストリームの upstream は sendrecv をお使い下さい

• マルチストリームの downstream は recvonly をお使い下さい

• スポットライトの upstream は sendrecv をお使い下さい

• スポットライトの downstream は recvonly をお使い下さい

• 片方配信の upstream は sendonly をお使い下さい

• 片方配信の downstream は recvonly をお使い下さい

シグナリング接続

• シグナリング接続時に指定する role の upstream と downstream を廃止しました

認証ウェブフック

• 認証ウェブフックの channel_upstream_connections を廃止しました

  • 今後は channel_sendrecv_connections または channel_sendonly_connections をご利用ください

• 認証ウェブフックの channel_downstream_connections を廃止しました

  • 今後は channel_recvonly_connections をご利用ください

イベントウェブフック

• イベントウェブフック *.connection の channel_upstream_connections を廃止しました

  • 今後は channel_sendrecv_connections または channel_sendonly_connections をご利用ください

• イベントウェブフック *.connection の channel_downstream_connections を廃止しました

  • 今後は channel_recvonly_connections をご利用ください

シグナリング通知

• シグナリング通知 *.connection の channel_upstream_connections を廃止しました

  • 今後は channel_sendrecv_connections または channel_sendonly_connections をご利用ください

• シグナリング通知 *.connection の channel_downstream_connections を廃止しました

  • 今後は channel_recvonly_connections をご利用ください

API

• Sora_20151104.DisconnectChannelUpstream API を廃止しました

  • 今後は DisconnectChannelByRole API をご利用ください

• Sora_20151104.DisconnectChannelDownstream API を廃止しました

  • 今後は DisconnectChannelByRole API をご利用ください

• Sora_20160711.PushUpstream API を廃止しました

  • 今後は PushChannelByRole API をご利用ください

• Sora_20160711.PushDownStream API を廃止しました

  • 今後は PushChannelByRole API をご利用ください

client_id を指定する設定の廃止

2021 年 6 月リリースの Sora にて廃止

sora.conf の allow_client_id_assignment 設定を廃止し client_id はクライアント側で指定できるようにします。

sora.conf

• sora.conf の allow_client_id_assignment を廃止しました

API

• Sora_20170529.GetStats API を廃止しました

  • allow_client_id_assignment 廃止に伴う廃止のため代替はありません

• Sora_20170814.StartForwardingRtp API の client_id 指定を廃止しました

  • allow_client_id_assignment 廃止に伴う廃止のため代替はありません

• Sora_20170814.StopForwardingRtp API の client_id 指定を廃止しました

  • allow_client_id_assignment 廃止に伴う廃止のため代替はありません

• Sora_20151104.ListConnections API を廃止しました

  • 今後は ListChannelConnections API をご利用ください

• Sora_20151104.Disconnect API を廃止しました

  • 今後は DisconnectClient API をご利用ください

旧サイマルキャスト画質変更 API の廃止

2021 年 6 月リリースの Sora にて廃止しました

• Sora_20180820.ChangeSimulcastQuality

  • 今後は RequestRtpStream API をご利用ください

この API の廃止に伴い、シグナリング接続時や認証成功時に指定するサイマルキャストの quality での low / middle / high 指定を廃止しました。 今後は rid と r0 / r1 / r2 を利用してください。

bin/sora start の廃止

2020 年 12 月リリースの Sora にて廃止しました

bin/sora start は 2020 年 12 月リリースの Sora 2020.3 で廃止しました。 今後は bin/sora daemon を利用してください。

systemd を利用されている方は bin/sora foreground を利用されていると思いますが、こちらに変更はありません。

Ubuntu 16.04 サポートの終了

サポート提供終了:

2021 年 4 月末

Ubuntu release cycle | Ubuntu

Ubuntu 16.04 は 2021 年 4 月を持って通常サポートが終了しました。 それに伴い Sora は 2021 年 4 月末をもって Ubuntu 16.04 版のサポートとパッケージの提供を終了しました。

Ubuntu 18.04 または Ubuntu 20.04 版への移行をお願いいたします。

Ubuntu 16.04 を利用しているお客様は、サポートまで切り替え先の OS をご連絡ください。

FAQ

ここでは WebRTC SFU Sora に関するよくある質問についてまとめています。

WebRTC 全般

双方向配信には対応していますか？

対応しています。WebRTC のマルチストリームという技術を利用して実現しています。

クライアント側の負荷を考慮し、 1 チャネルに参加するクライアントは 12 までを推奨としています。

1 チャネルで 12 より多いクライアントで双方向の配信を行いたい場合は スポットライト機能 を検討するかサポートまでお問い合わせ下さい。

片方向配信には対応していますか？

対応しています。

片方向配信はどのくらいの接続数まで対応していますか？

Sora 1 で 1 チャネルに 1 万接続程度まで対応しています。

クラスターリレー機能を利用する事で 100 万接続以上への配信もできます。

音声検出による映像の切り替えには対応していますか？

対応しています。Sora 独自のスポットライト機能という名前で提供しています。

この機能は多人数で会議を行う場合に、クライアントやサーバーの負荷を減らせる技術です。

100 名以上が 1 チャネルに参加できます。

詳細は スポットライト機能 をご確認ください

スクリーンキャプチャ機能には対応していますか？

2024 年 12 月 の時点でスクリーンキャプチャ機能はブラウザでは Chrome と Firefox と Safari と Edge が対応しています。 getDisplayMedia を利用することで、実現できます。

MediaDevices.getDisplayMedia() - Web APIs | MDN

マルチストリームには対応していますか？

Tip

Sora はデフォルトでマルチストリームを利用します。

対応しています。ブラウザでは Chrome と Firefox と Safari と Edge で対応しています。

また、すべての SDK が対応しています。

マルチトラックには対応していますか？

対応していません。 Sora は 1 メディアストリームにつき 1 音声トラック、1 映像トラックまでしか対応していません。

マルチトラックへの対応は今のところ未定です。

複数の音声や複数の映像を 1 つのコネクションで配信することはできますか？

いいえ。 1 つのコネクションで複数ストリームを配信をすることはできません。

1 接続では 1 ストリーム (1 音声/1 映像) のみの配信ができます。

複数の配信を行いたい場合はマルチストリームの sendonly ロールを利用して複数接続してください。

1 ユーザーで送受信と送信のみを利用している場合、送受信側で送信のみの音声や映像を受信しないことはできますか？

はい、できます。接続時、または認証成功時に bundle_id で同じ値を指定してください。

注釈

シグナリング時に bundle_id を指定する場合は sora.conf の signaling_bundle_id を true にする必要があります。

bundle_id が同じ接続では送信のみの音声と映像を送受信側で受信しなくなります。

映像コーデックは何がお勧めですか？

すべてのブラウザ、さらにほぼすべての端末で動作する VP9 か H.264 がお勧めです。

ただし、端末に VP9 のハードウェアアクセラレータが搭載されていることはほとんどないため、 H.264 を採用した方が電池消費量は減ります。

一方で、H.264 は一部の Android 端末で正常に動作しないことがあります。

すべての環境が Chrome に統一できる場合は AV1 をお勧めします。

H.264 や VP9 での映像配信に対応していますか？

ブラウザがそれぞれのコーデックに対応していれば、 Sora は問題なく配信できます。

2024 年 12 月 の時点では ...

• Chrome 131 は VP8、 VP9、 AV1、 H.264 に対応しています

  • Field Trial として H.265 対応が追加されています

• Firefox 131 は VP8、 VP9、 H.264 に対応しています

• Edge 131 は VP8、 VP9、 AV1 、H.264 に対応しています

• Safari 18.1 は VP8、 VP9、 H.264, H265 に対応しています

  • 実験的機能として AV1 対応が追加されています

Sora は配信者がコーデックを選択できる仕組みを採用しています。

詳細は シグナリング をご確認ください

Safari は WebRTC に対応していますか？

はい。 Safari 12 で WebRTC に対応しました。

詳細は Apple Safari の WebRTC について をご確認ください。

Chrome や Edge では HTTPS が必須ですか？

はい。ローカルホスト以外からのアクセスでブラウザで getUserMedia を使用する場合は HTTPS が必須になります。

もし、開発中に HTTP でアクセスしたい場合は、以下を参考にしてください。

http でのアクセスでカメラの映像を取得する - Qiita

Safari では HTTPS が必須ですか？

はい。ただし、 開発者メニューから HTTP でも getUserMedia を使用できるようにするオプションが用意されています。

Edge は WebRTC に対応していますか？

はい。 Chrome とほぼ同等のレベルで WebRTC が利用できます。

詳細は Microsoft Edge の WebRTC について をご確認ください。

サーバー側からクライアントごとにコーデックやビットレートを指定できますか？

できます。 Sora からクライアントへ送信する Offer に含める SDP を、クライアントごとに指定できます。

詳細については 認証ウェブフック成功時の払い出し をご確認ください。

コーデックが異なるクライアントでも同じチャネルでの双方向通信はできますか？

できます。マルチストリームを利用することで接続ごとにコーデックを指定できます。

例えば、iOS の Safari は H.264 、デスクトップの Chrome は VP8 という場合でも同じチャネルでの双方向通信が利用できます。

ただし、ブラウザが非対応の場合はもちろん送受信できませんのでご注意ください。

Firefox で複数タブで音声デバイスを利用できますか？

いいえ。 Firefox 56 から複数タブで音声デバイスを利用できなくなりました。

Safari で音声が有効な場合、自動で視聴を開始できますか？

いいえ。 Safari の仕様で、音声が含まれている映像を自動で再生することはできません。

高いビットレートで配信することはできますか？

できます。ただし、Sora では最大 50 Mbps での配信ができますが、 今のところは 15 Mbps より大きなビットレートでの配信はサポート対象外とさせていただいています。

配信自体はできますが、クライアント、サーバーともに不安定になることがあるためです。

今後、高いビットレートでの配信を安定して実現できるようにしていく予定です。

4K 30fps を実現したいのですができますか？

できます。ただしクライアント側の負荷がとても高くなるため、かなり条件は厳しいです。

クライアントの負荷が高い場合、 ブラウザは自動的に解像度やフレームレートを下げる仕組みが入っているため、 4K 30fps を配信するためにはソフトウェアエンコードでの配信はかなり厳しいです。

そのため 4K 30fps に対応したハードウェアエンコーダーが必要になります。

時雨堂が公開している SDK はハードウェアエンコーダーに対応していますので、 対応しているハードウェアを用意していただければと思います。

また、時雨堂では WebRTC Native Client Momo という、 様々なハードウェアエンコーダーに対応したクライアントをオープンソースで公開していますので、是非試してみてください。

shiguredo/momo: WebRTC Native Client Momo

映像をフレームレート 60 や 120 で配信することはできますか？

できます。ただし Sora は映像のフレームレートには関与しません。

そのため、フレームレートはカメラが対応していること、また、クライアントが対応していることが必要になります。

カメラで指定した解像度より低い解像度で配信されるのですが？

カメラ映像の解像度と WebRTC でエンコードされて配信される解像度は一致しません。

カメラから入ってくる映像を WebRTC では圧縮して配信します。WebRTC は圧縮時に CPU 使用率が高い、ネットワーク帯域不足などの状況に応じ、自動で解像度やフレームレートを落として配信できる状態にして配信します。

WebRTC DataChannel には対応していますか？

対応しています。

2024 年 12 月 の時点では、シグナリング機能と リアルタイムメッセージング機能 として DataChannel を利用できます。

詳細は DataChannel 経由のシグナリング や リアルタイムメッセージング機能 をご確認ください。

音声のステレオには対応していますか？

対応しています。

ただしステレオで音声をエンコード/デコードするかどうかはクライアント側に依存します。

例えばブラウザの場合はデフォルトでステレオに対応していますが、エコーキャンセルが有効な場合はステレオは利用できません。 エコーキャンセルを無効にすることでステレオが利用できるようになります。

エコーキャンセルの設定は以下を参考にしてください。

Media Capture and Streams

MediaStreamTrack から connection_id は取得できますか？

できます。

Sora では自分以外の MediaStreamTrack の ID に {connection_id}-{audio | video} という形式が含まれるようになっています。 そのため、MediaStreamTrack の ID から connection_id を取得することができます。

MediaStreamTrack の id や label 、getCapabilities の deviceId や getSettings の deviceId がこの形式になります。

• "id": "CQE8KR2MAN1B1DD149NA2EX4MM-video"

• "label": "CQE8KR2MAN1B1DD149NA2EX4MM-video"

• "getCapabilities": {"deviceId": "CQE8KR2MAN1B1DD149NA2EX4MM-video", ...

• "getSettings": {"deviceId": "CQE8KR2MAN1B1DD149NA2EX4MM-video", ...

危険

Firefox には対応していません

WebRTC 統計情報 inbound-rtp から connection_id は取得できますか？

できます。

Sora では WebRTC 統計情報 inbound-rtp の trackIdentifier に {connection_id}-{audio | video} という形式が含まれるようになっています。 そのため、 trackIdentifier から connection_id を取得することができます。

"trackIdentifier": "CQE8KR2MAN1B1DD149NA2EX4MM-video" の用に含まれます。

危険

Firefox には対応していません

シグナリング

シグナリングは独自仕様ですか？

独自仕様です。 WebRTC の規格ではシグナリング部分は定義されていないため、 WebRTC で利用されるシグナリングは独自仕様が前提になります。

Sora は JSON over WebSocket または JSON over DataChannel をシグナリングの仕様として採用しています。 Sora の SDK を利用すればシグナリングを意識する必要がありません。

Sora のシグナリングの詳細な仕様について確認したい場合は、シグナリング をご確認ください。

注釈

OBS 向けのシグナリングは WHIP / WHEP という RFC で定義されているプロトコルに対応しています。

シグナリングに WebSocket (WS) ではなく WebSocket over TLS (WSS) を使うことはできますか？

できます。

getUserMedia を使用する場合、 ローカルホスト以外のアクセスは WSS を必須としています。 ただし、Sora は WS のみに対応しています。

これは、実運用を考慮して、前段にリバースプロキシサーバーを立てていることを前提としており、 リバースプロキシサーバーで TLS を終端する構成を想定しているためです。

そのため、もし WSS を使う場合は、 nginx などのリバースプロキシサーバーを使用して TLS を終端してください。

注意

nginx の設定などについてはサポート対象外となりますので、お問い合わせはご遠慮ください

弊社では、TLS を終端するリバースプロキシサーバーには nginx の使用を推奨しています。

詳細については nginx をご確認ください。

OBS などで利用できる WHIP / WHEP 形式のシグナリングに対応していますか？

対応しています。

WHIP / WHEP は OBS のみの対応となります WHIP と WHEP に対応しています。

詳細については OBS Studio WHIP 対応機能 や OBS Studio WHEP 対応機能 をご確認ください。

接続単位で接続時間を知ることはできますか？

できます。Sora は接続ごとにタイマーを保持しており、 接続後 1 分ごとに外部のアプリケーションサーバーに HTTP 経由で接続の状態を報告します。

この報告はクライアントごとに独立しており、報告にはクライアント ID やチャネル ID やアプリケーションサーバーが認証時に指定した event_metadata が含まれています。 これらの情報を使用して、例えば、ユーザーごとに接続から 10 分経過したら切断する等の処理が簡単に行えます。

シグナリングで利用している WebSocket や DataChannel を使ってクライアントにメッセージ送ることはできますか？

できます。 プッシュ API を利用することでシグナリングで利用している WebSocket や DataChannel 経由でクライアントにメッセージを送ることができます。

または リアルタイムメッセージング機能 を利用してクライアント間でメッセージがやりとりできます。

クライアントがシグナリング経由で他の人の接続を通知で受け取ることはできますか？

できます、ただし同一チャネルのみに限ります。

シグナリング通知 をご確認ください。

シグナリングに DataChannel を使うことはできますか？

できます。ただし、WebRTC 接続確立までは WebSocket を利用する必要があります。

詳細は DataChannel 経由のシグナリング をご確認ください。

認証

シグナリング時の認証はできますか？

できます。ただし、Sora は認証機能を持っていますが、認証の判断をする仕組みを持っていません。 認証は外部のアプリケーションサーバーへウェブフックを送信し、その戻り値で判断を行います。

認証の判断材料として、 Sora のシグナリング開始時に任意の情報をクライアントに送ることができる metadata を指定できます。 これは外部のアプリケーションサーバー側で払い出して使用できます。

認証のフローを以下に簡単に書き出しておきます。

1. 外部のアプリケーションサーバーでアクセストークンをクライアントに払い出す

2. そのアクセストークンを metadata に入れて Sora に接続する

3. Sora はそのアクセストークンやコネクション ID を外部のアプリケーションサーバーに HTTP 経由で問い合わせる

4. 外部のアプリケーションサーバーはそのアクセストークンが正しいことを確認し、 {"allowed": true} を HTTP ステータスコード 200 番台で Sora に返す

5. Sora は Offer をクライアントに送る

        sequenceDiagram
    participant C as クライアント
    participant S as Sora
    participant A as アプリケーションサーバー
    C->>+S: "type": "connect"
    S->>+A: 認証ウェブフック
    A-->>-S: 200 OK<br>"allowed": true
    S-)-C: "type": "offer"
    C-)S: "type": "answer"
    note over C,S: WebRTC 確立
    

外部の HTTP サーバーに対してウェブフックを送信し、 {"allowed": true} と HTTP ステータスコード 200 番台 が返ってきたら認証を許可します。

詳細は 認証ウェブフック をご確認ください

シグナリングの認証失敗時に失敗の理由をクライアントに返せますか？

できます。外部のアプリケーションサーバーで Sora への認証ウェブフックの戻り値を返す場合、 {"allowed": false, "reason": "最大 100 バイトまでの文字列"} という値を返す必要があります。

この reason 部分はクライアントに通知されます。

詳細は 認証ウェブフック をご確認ください

通知

チャネルに参加中のクライアントが、別のクライアントの参加や離脱を知ることはできますか？

できます。シグナリング通知機能を利用することにより、接続や切断のタイミングで、 シグナリングで利用している WebSocket または DataChannel 経由で通知されます。

詳細は シグナリング通知 をご確認ください。

チャネルに参加中のクライアントが、自分の録画開始/終了を知ることはできますか？

できます。シグナリング通知機能を利用することにより、録画の開始や終了のタイミングで、 シグナリングで利用している WebSocket または DataChannel 経由で通知されます。

詳細は シグナリング通知 をご確認ください。

参加者に Sora 側で変更できるメタデータをもたせることはできますか？

できます。シグナリング通知メタデータ拡張機能を利用することで、 接続や切断のタイミングで API 経由で変更したメタデータを通知できます。 さらにメタデータの変更時に参加者全員にプッシュで通知することもできます。

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

API

指定したコネクションのみを切断することはできますか？

できます。 Sora はチャネル ID とコネクション ID を指定して接続を切断できます。

詳細は DisconnectConnection をご確認ください。

指定したコネクションを切断した際に切断理由を含めることはできますか？

できます。 reason を指定することで、イベントウェブフック connection.destroyed の disconnect_api_reason として指定した値が入ってきます。

詳細は DisconnectConnection をご確認ください。

指定したクライアントのみを切断することはできますか？

できます。 Sora はチャネル ID とクライアント ID を指定して接続を切断できます。

詳細は DisconnectClient をご確認ください。

指定したチャネルの配信者や視聴者のみを切断することはできますか？

できます。 Sora はチャネル ID を指定して配信者や視聴者のみを接続を切断できます。

詳細は DisconnectChannelByRole をご確認ください。

指定した配信者の映像を、指定した視聴者が受信しないことはできますか？

できます。Sora は配信者、視聴者のコネクション ID を指定して映像を Sora で一時的に止めることができます。

詳細は PauseRtpStream をご確認ください。

録画

Sora で録画した場合に出力されるファイルの形式は何ですか？

WebM 形式です。

• The WebM Project | Welcome to the WebM Project

• WebM - Wikipedia

Sora で録画した複数の WebM 形式のファイルを一つのファイルに出力することはできますか？

できますが、サポートの範囲外になります。 録画ファイル合成ツールをオープンソースとして公開しています。

Recording Composition Tool Hisui

録画した WebM 形式のファイルはブラウザで閲覧できますか？

できます。Chrome と Firefox、Edge で閲覧できます。 Safari では WebM 形式のファイルの閲覧に対応はしていますが VP9/Opus のファイルのみに対応しています。

警告

iOS 15.1 の Safari では WebM 形式を正常に読み込むことができません。 これは Safari 側のバグのようで、対応待ちです。

録画できるコーデックは何ですか？

映像コーデックは VP8 と VP9 と H.264 と AV1 、また音声コーデックは Opus に対応しています。 録画ファイルは WebM 形式で保存されます。

H.265 の録画には現時点で対応していません。

音声のみを録音できますか？

できます。Opus コーデックで音声のみの録音が可能になります。

webma ファイルではなく webm ファイルで出力されますのでご注意ください。

録画した WebM のサイズの例を教えてください

基本的には指定したビットレートで決まります。

例として、VP8 と Opus の組み合わせの WebM で、 VP8 の解像度が 640x480 でビットレートが 300kbps 程度、音声ありの場合、 1 分の映像で約 2.5 M バイトです。

録画が終了するタイミングを教えて下さい

録画終了するタイミングは 3 つあります。

1. StopRecording API が呼ばれた場合

2. 接続が切断した場合

3. 録画開始時に指定した期限が来た場合

録画の開始と終了をクライアントへ通知することはできますか？

できます。

シグナリング通知で recording.started と recording.stopped が送られます。

サイマルキャスト機能を利用した場合に録画はできますか？

できます。映像の優先度が一番低い映像を録画します。

映像の優先度については 映像の優先度 をご確認下さい。

スポットライト機能を利用した場合に録画はできますか？

できます。映像の優先度が一番低い映像を録画します。

映像の優先度については 映像の優先度 をご確認下さい。

録画関連ファイルをアップロードする仕組みはありますか？

できますが、サポートの範囲外になります。

Sora が出力した録画関連ファイルを、 Amazon S3 や S3 互換オブジェクトストレージにアップロードするツールをオープンソースとしてとして公開しています。

Sora Archive Uploader

replaceTrack(null) を使うと、再生時に音声と映像がずれてしまいます

Chrome には、特定の条件で RTP タイムスタンプが正しく進まないという問題があり、 そのため Sora が生成する WebM ファイルの再生時に音声と映像がずれてしまうことがあります。

発生条件は、音声ストリームに対して RTCRtpSender.replaceTrack(null) https://developer.mozilla.org/en-US/docs/Web/API/RTCRtpSender/replaceTrack を実行した後に RTCRtpSender.replaceTrack(audioTrack) した場合です。 この問題は Chrome/WebRTC のバグトラッカー https://bugs.chromium.org/p/webrtc/issues/detail?id=12020 で 管理されています。

録画時のキーフレーム要求間隔は何秒ですか？

録画機能利用時の Sora からのキーフレーム要求間隔は 20 秒です。

TURN

TURN サーバーを立てる必要はありますか？

Sora は TURN 機能を組み込んでありますので TURN サーバーを立てる必要はありません。 また、Sora とは別に TURN サーバーを立てることは推奨していません。

Sora の組み込み TURN サーバーは TURN-TCP や TURN-TLS に対応していますか？

対応しています。ただし、TURN-TLS 機能を使用するためには nginx が必要となります。

• TURN-UDP

  • ポート変動

• TURN-TCP

  • ポート固定

• TURN-TLS

  • ポート固定

  • nginx 必須

詳細は TURN 機能 をご確認ください

HTTPS で利用される 443 番のポートを TURN 機能で利用することはできますか？

できますが、nginx の利用が必須です。 詳細は TURN-TLS、TURN-TCP、シグナリングで 443 番ポートを使用する をご確認ください。

注意

nginx の設定などについてはサポート対象外となりますので、お問い合わせはご遠慮ください

Sora を使った場合、TURN サーバーで使用するユーザー名やクレデンシャルはどう払い出せば良いですか？

いくつか方法がありますが、ここでは Sora の認証機能と合わせて使用する方法をご紹介します。

Sora は認証を外部のアプリケーションサーバーに問い合わせます。この問い合わせの戻り値の JSON に metadata を含むことができます。 その戻された JSON の metadata はそのままクライアントまで払い出されます。

これを利用して、認証に成功した場合にのみ TURN の認証に使用するユーザー名とクレデンシャルを払い出すことができます。

認証時のクライアントへの metadata の払い出しについての詳細は metadata の払い出し をご確認ください。

TURN で UDP と TCP、TLS でどの経路が選択されるかはどう決められますか？

クライアント側の実装に依存します。Sora はクライアントがどの経路を選択するかには関与しません。

TURN IPv6 に対応していますか？

対応しています。

TURN の FQDN 設定はどのようなときに設定が必要ですか？

NAT64/DNS64 ネットワーク環境に対しては TURN の FQDN を設定する必要があります。

ウェブフック

ウェブフックのリクエスト送信先は複数登録できますか？

できません。

もし、送信先を複数にしたい場合は、登録した送信先のアプリケーションサーバーなどで対応をお願いします。

ウェブフックにベーシック認証は利用できますか？

できます。

sora.conf にて webhook_basic_authn の設定を有効にして下さい。

詳細については ウェブフックリクエスト送信先のサーバーがベーシック認証を利用している場合 をご確認ください。

ウェブフックのタイムアウト値を設定できますか？

できます。

sora.conf にて webhook_response_timeout を設定することで、ウェブフックのレスポンスのタイムアウトが変更できます。

イベントウェブフックの session.updated の送信間隔を 1 分から変更できますか？

できます。 sora.conf にて session_updated_webhook_interval に 3 min と設定することで、 session.updated のイベントウェブフックリクエストの送信間隔を 3 分に変更できます。

イベントウェブフックの session.updated を送らない設定はできますか？

できます。 sora.conf にて ignore_session_updated_webhook を true を設定することで、 session.updated のイベントウェブフックリクエストが送信されなくなります。

イベントウェブフックの connection.updated の戻り値を使用して切断などはできますか？

できません。切断をする場合は Sora が持つ切断 API を使用してください。

イベントウェブフックの connection.updated の送信間隔を 1 分から変更できますか？

できます。 sora.conf にて connection_updated_webhook_interval に 3 min と設定することで、 connection.updated のイベントウェブフックリクエストの送信間隔を 3 分に変更できます。

イベントウェブフックの connection.updated を送らない設定はできますか？

できます。 sora.conf にて ignore_connection_updated_webhook を true を設定することで、 connection.updated のイベントウェブフックリクエストが送信されなくなります。

イベントウェブフックのワーカー数を変更することはできますか？

できます。同時接続数が増えた場合や、ウェブフックリクエスト送信先のサーバーの応答速度が遅い場合は、 sora.conf にて event_webhook_worker_number の値を変更してください。

イベントウェブフックのワーカー割り当てに利用している値は channel_id となります。 ワーカーが 10 の場合、 channel_id が 100 利用している場合、1 ワーカーに 10 の channel_id が割り当てられます。

イベントウェブフックの処理が遅くなった場合の挙動はどうなりますか？

イベントウェブフックワーカーがキューを持っており、もしそのワーカーがリクエストを処理中の場合、キューに追加されます。 そのリクエストの処理が終わりったらキューから取り出され処理されます。

認証ウェブフックの同時接続数の項目を利用してセッション単位の接続数制限をかけることはできますか？

ウェブフック送信先で接続制限をかけることはできますが、厳密な制限をすることはできません。

厳密な接続制限をする場合は trial_max_connections を利用してください。

ただし、この機能は 実験的機能のトライアル中 であり、正式リリース時には変更が入る予定があります。

DataChannel

DataChannel でメッセージを送ることはできますか？

できます。 Sora のメッセージング機能は DataChannel を利用しています。

詳細については リアルタイムメッセージング機能 をご確認ください。

role が recvonly で受信のみでもメッセージング機能を利用してメッセージを送ることはできますか？

できます。メッセージングが送ることができるかどうかは direction にのみ影響を受けます。

送られてきたメッセージをどのクライアントが送ってきたかを判断することはできますか？

できます。 メッセージング機能のヘッダー付与を利用してください。

詳細については header をご確認ください。

DataChannel でクライアントが RTCPeerConnection.createDataChannel() を利用することはできますか？

できません。Sora 側で用意された DataChannel を利用してください。

クラスター機能

クラスターには対応していますか？

対応しています。現在 1 クラスター最大 100 ノードまで対応しています。

詳細については クラスター機能 をご確認ください。

クラスター構築時に同一のライセンスを使う方法はありますか？

あります。通常は同一のライセンスを複数のノードで利用することはできませんが 最大ノード数ライセンス を利用することでできるようになります。

ロードバランスには対応していますか？

対応しています。

クラスター機能の一つとして、新規チャネルの接続は接続割合が少ない Sora ノードに割り振ります。

クラスターへの自動登録には対応していますか？

対応していません。

RegisterClusterNode API を利用してクラスターにノードを登録する必要があります。

クラスターの自動復旧には対応していますか？

対応しています。

ネットワーク障害やノード障害により、クラスターから離脱した場合 Sora は再度クラスターへの参加を自動で試みます。

ノード間通信は暗号化されていますか？

されていません。そのためプライベートネットワークまたは暗号化されたネットワークを利用してください。

2 ノードでもクラスターを構築できますか？

できます。ただし推奨していません。

2 ノードの場合、どちらかのノードに障害が発生するとクラスター全体が止まってしまうため、 可用性は 1 ノードの場合よりも低くなります。

そのため 3 ノード以上でクラスターを組むことをお勧めします。

クラスターからノードを離脱させたい場合はどうすれば良いですか？

Sora を終了することで離脱を行います。丁寧に離脱したい場合はモード切替で 新規コネクションブロックモード を指定し、 すべての接続を切断してから終了してください。

もしそのノードが今後もクラスターに参加しない場合、 PurgeClusterNode API を利用してクラスターからそのノードの情報を完全消去してください。

なおノード情報を完全消去せずに、一度に過半数のノードを離脱させてしまうと、 残ったノードも接続を処理できなくなってしまうので注意が必要です。 詳細については 全ノードが半数以下のグループに所属した場合の挙動 をご確認ください。

クラスターのディザスタリカバリーには対応していますか？

対応していません。今後対応予定はありますが、リリース時期は未定です。

クラスターのリレーには対応していますか？

対応しています。

クラスターの最大ノード数はいくつですか？

クラスターを構築するノードの最大数は 100 を想定しています。 これ以上のノード数でのクラスター構築を検討されている場合はサポートまでご連絡ください。

その他

IP アドレスは複数指定できますか？

できますが、運用が複雑になるため、現時点ではドキュメントには記載していません。 もし、IP アドレスの複数指定を利用したい場合は、サポートまでお問い合わせください。

基本的には、クライアントごとに IP アドレスを変更したい場合は、認証時の戻り値を使用してください。

配信者は音声と映像を配信し、視聴者は音声のみを受信することはできますか？

できます。視聴者は配信者からの映像や音声のどちらかだけを受け取るよう指定できます。

詳細は 配信または視聴メディアの選択 をご確認ください。

複数のユーザーの中で、発言していないユーザーは低画質な映像のみを配信し、発言しているユーザーは音声と高画質な映像を配信することはできますか？

スポットライト機能を利用すればできます。

詳細は スポットライト機能 をご確認ください

サイマルキャストに対応していますか？

対応しています。ブラウザは Chrome と Edge と Safari の最新バージョンに対応しています。 それ以外のブラウザでは配信はできませんが、視聴はできます。

映像コーデックは VP8、VP9、AV1、H.264、H.265 に対応しています。

• VP8 サイマルキャストは Chrome と Edge と Safari が対応しています

• VP9 サイマルキャストは Chrome と Edge が対応しています

• AV1 サイマルキャストは Chrome と Edge が対応しています

• H.264 サイマルキャストは Chrome と Edge と Safari が対応しています

• H.265 サイマルキャストは Safari 実験的機能のみが対応しています

映像や音声を WebRTC 以外で出力する仕組みはありますか？

StartForwardingRtp API と StopForwardingRtp API を利用することで、 外部のサーバーに対して WebRTC の DTLS (暗号部分) を除いた RTP パケットを送ることができます。

FFmpeg などを使用することで、 RTP から HLS や MPEG-DASH などに変換することもできます。

映像の配信を一時的に止める仕組みはありますか？

PauseRtpStream API と ResumeRtpStream API を利用することで、 指定した接続からの映像の配信を一時的に停止できます。

HLS 配信はできますか？

Sora 単体ではできません。ただし、Sora の RTP 転送 API を利用して FFmpeg などに転送することで、HLS での配信ができます。

こちらのドキュメントは古いため参考程度にお願いします

HLS 配信 をご確認ください。

追いかけ再生はできますか？

Sora 単体ではできません。

ただし、Sora の RTP 転送 API を利用して FFmpeg などに転送することで、HLS での配信ができます。 そのため、この HLS での配信を利用することで追いかけ再生を実現できます。

こちらのドキュメントは古いため参考程度にお願いします

HLS 配信 をご確認ください。

WebRTC 確立するまでにかかる時間は知ることができますか？

GetStatsReport API の average_setup_time_msec でシグナリング接続開始から WebRTC 接続が確立するまでにかかった平均時間が取得できます。

性能

負荷試験はどう行えばよいですか？

サポートの範囲外になりますが、Sora 専用の負荷試験ツールをオープンソースとして公開しています。

WebRTC Load Testing Tool Zakuro

Sora は CPU をどの程度使用しますか？

重要

WebRTC ではすべての通信が暗号化されているため、暗号化/復号処理で最も CPU リソースを消費します

通信環境やビットレートに影響するため一概には言えませんが、参考値を紹介します。

環境は AWS の C5n.4xlarge を利用しています。

以下の CPU の % は 1 コアを 100% とした場合です。

解像度が QVGA / 20fps / 1000kbps の映像と音声の送受信で 1 チャネル 8 クライアントを 12 ルーム (96 接続) で CPU 使用率を 200 % 程度利用します。

Sora はメモリをどの程度使用しますか？

Sora は再送のキャッシュ用途にメモリを使用します。 100 接続であれば 4 GB 以上あれば十分です。

また、録画利用時にはフレーム組み立てのため一時的にメモリを使用します。こちらはビットレートに依存します。

Sora はディスクをどの程度使用しますか？

主に録画したファイルとログによりディスクが使用されます。

録画する映像の容量はコーデックやビットレートに依存するため一概には言えません。

マルチストリームは 1 チャネルで最大何クライアントまで対応していますか？

2024.2.0 時点で最大 12 クライアントまで対応しています。それ以上を接続することもできますが、お勧めはできません。

もし、大規模での会議を行いたい場合は、現在実験的機能として提供中の スポットライト機能 の利用を検討してください。

運用

Sora を利用する場合、インターネット接続が必要ですか？

いいえ、必要ありません。

Sora はデフォルトでは外部アクセスをいっさい行わず、ライセンス確認も Sora 単体で行っています。 外部アクセスが発生するのは、ユーザーが sora.conf に明示的に設定を追加して、ウェブフック機能などを有効化した場合のみです。

その為、閉域網などのパブリックなネットワークへのアクセスができない環境でも利用頂けます。

WebSocket が通らないプロキシ環境がある場合はどうしたらよいですか？

WebSocket は TLS を利用しているため、おそらくプロキシは TLS を一度終端するタイプかと思われます。

接続に対して中身の解析を行うプロキシであれば、 WebSocket だけでなく、TURN-UDP や TURN-TCP、TURN-TLS も通らない可能性が高いです。

結果として WebSocket が通らないプロキシを利用している場合は WebRTC 自体が利用できない可能性が高いため、プロキシの設定を変更してもらう以外の方法はありません。

Sora は Prometheus 形式に対応した監視情報を出力しますか？

Sora 自体は Prometheus 形式の監視情報は出力しません。

その代わりにオープンソースとして Sora exporter を公開しています。

Prometheus exporter for WebRTC SFU Sora metrics.

Sora をデーモン化せずに起動することはできますか？

できます。 Sora を起動する際、 bin/sora foreground で起動してください。

Sora を systemd で利用することはできますか？

できます。 詳細は systemd をご確認ください。

Sora クラスターを利用せず、ロードバランサーを利用することはできますか？

できません。

Sora ではかならず同一チャネルの接続を同一 Sora に集約する必要があるためです。 もしロードバランサーを利用したい場合はクラスターを構築する必要があります。

Sora クラスターを利用して、ロードバランサーを利用することはできますか？

できます。

ロードバランサーは WebSocket に対応している必要があります。 さらにロードバランサー側では 30 秒以上のタイムアウトを設定する必要があります。 これは Sora は WebSocket と DataChannel をシグナリングに併用した場合 30 秒間隔で Ping を Sora から送るためです。

また、ロードバランサーを経由しないシグナリング接続もできるようにする必要があります。 これは Sora 側でシグナリングのリダイレクトを行い別の Sora に直接接続させる仕組みがあるためです。

Sora はコンテナ上で利用できますか？

Sora をコンテナで運用するのは推奨していませんが、利用できます。 サポートへ問い合わせする場合はコンテナに関係する問題を切り分けをして頂く必要があります。

Sora の WebSocket を利用したシグナリングのキープアライブの切断条件は何ですか？

Sora は デフォルトの設定では WebSocket 経由で 5 秒間隔で "type": "ping" を送信し、 60 秒間で 1 回も "type": "pong" が返って来こなかった場合、 Sora はシグナリング接続を切断します。

これらの時間について sora.conf の設定 websocket_signaling_ping_interval と websocket_signaling_pong_timeout で変更できます。

Sora の DataChannel を利用したシグナリングの Sora 側からの切断条件は何ですか？

Sora は定期的に接続状態を確認する仕組みを持っており、その仕組みで切断かどうかを判断しています。

詳細は ICE コネクションステート をご確認ください。

Sora 1 台のサーバーでは最大同時接続数はいくつですか？

現状 1 台では 5000 接続までを推奨しています。

多くの接続を 1 台で行いたい場合、まずはサポートまでご相談ください。

Sora が対応している OS は何ですか？

2024.2.0 の時点では以下の OS に対応しています。

• Ubuntu 24.04 LTS x86_64

• Ubuntu 24.04 LTS arm64

• Ubuntu 22.04 LTS x86_64

• Ubuntu 22.04 LTS arm64

• Ubuntu 20.04 LTS x86_64

• Ubuntu 20.04 LTS arm64

• Red Hat Enterprise Linux 9 x86_64

  • マイナーバージョンアップ版は全てサポート対象です

  • 可能な限り最新のバージョンをご利用ください

• Red Hat Enterprise Linux 8 x86_64

  • マイナーバージョンアップ版は全てサポート対象です

  • 可能な限り最新のバージョンをご利用ください

Sora は Amazon Linux に対応していますか？

対応していません。

Sora が対応していると明記している OS 以外で動作させている場合は Sora はサポート対象外となります。

Sora のプロセス名は何になりますか？

bin/sora daemon で起動した場合、Sora 本体は run_erl というプロセスになります。こちらの死活監視をお願いします。

Sora を終了しても epmd というプロセスが残りますが問題ありませんか？

問題ありません。 Sora と関係するプロセスですが独立しており、起動し続けていて構いません。

カーネルパラメーターの設定は何をすれば良いですか？

まずはファイルディスクリプタ数をご確認ください。値は 65535 に設定しておくことをお勧めします。

その他のチューニング項目については Linux カーネルチューニング をご確認ください。

ログローテーションはどうすれば良いですか？

sora.jsonl と connection.jsonl はローテションされませんので必要な部分で mv コマンドなどで移動してください。 ファイルが無い場合、新しく作られます。

erlang.log については自動でログローテーションを行いますので気にする必要はありません。

ログの詳細については ログファイル をご確認ください。

ログのタイムゾーンを教えてください

UTC です。

Sora が使用する UDP のポート範囲を教えてください

Sora が使用する UDP ポートは Linux のエフェメラルポートを使用しています。

エフェメラルポートの範囲は sysctl などで確認してください。

実行例:

$ sysctl -n net.ipv4.ip_local_port_range
32768 60999

Sora が使用する UDP のポート範囲を制限できますか？

できます。Sora が使用する UDP ポートの範囲はエフェメラルポートの範囲です。 Linux 側でエフェメラルポートの範囲を設定してください。

sysctl にて net.ipv4.ip_local_port_range の範囲を指定してください。

ブラウザで WebRTC の詳細情報を取得することはできますか？

できます。

• Chrome であれば URL に chrome://webrtc-internals を入力してみてください

• Firefox であれば URL に about:webrtc を入力してみてください

• Edge であれば URL に edge://webrtc-internals を入力してみてください

• Safari であれば JavaScript コンソールの設定の一般から WebRTC を設定できます

SELinux を利用する際の注意点はありますか？

Sora の log ディレクトリ以下にログを書き込めるようにする必要があります。

以下を参考にしてみてください。

• logging - logrotate cron job not rotating certain logs - Stack Overflow

• linux - Configuring SELINUX to allow logging to a file that's outside /var/log - Unix & Linux Stack Exchange

映像が乱れたり止まったりする場合は何を確認するのが良いですか？

映像が乱れたり止まったりする場合はネットワーク回線が不安定なことがほとんどです。

この場合は切断時に生成される connection.jsonl を確認してみてください。

このログで映像の送信側と受信側の統計情報が確認できますので、 映像が乱れたり止まったりした接続の connection_id を記録しておいて下さい。

• total_received_rtcp_rtpfb_generic_nack

• total_sent_rtcp_rtpfb_generic_nack

この値が多ければ多いほど「再送要求」の回数が多く、回線が不安定だったことが把握できます。

connection.jsonl の詳細については connection ログ をご確認ください。

Sora が突然終了しました

Sora は何か問題があり Sora が終了した場合 erl_crash.dump というログを出力します。 このログが出力された場合はサポート問い合わせの手順に従ってサポートまでご連絡ください。

もし erl_crash.dump が出力されずに Sora が終了した場合はカーネル側から停止された可能性があります。 まずは OOM Killer で殺されていないかどうかを確認してみてください。

Sora で利用している Erlang VM のフラグを指定することはできますか？

重要

この設定を利用する場合はサポートまでお問い合わせください

できます。環境変数 SORA_ADDITIONAL_ERL_ARGS を利用してください。

クライアント毎に Sora への経路を変更することはできますか？

できます。認証成功時にクライアントに ipv4_address または ipv6_address を払い出すことで、 クライアントはその IP アドレスを利用して Sora へ接続を試みるようになります。

例えばインターネット経由とプライベートネットワーク経由で接続先を変えることができます。

• パブリックネットワーク経由の場合は ipv4_address または ipv6_address に Sora が利用しているサーバーのパブリック IP アドレスを設定してください

• プライベートネットワーク経由の場合は ipv4_address または ipv6_address に Sora が利用しているサーバーのプライベート IP アドレスを設定してください

SDK

Sora の SDK は基本的にシグナリング処理のための SDK です。 WebRTC 部分は webrtc.org <https://webrtc.org/?hl=ja> が提供しているライブラリを利用しています。

Sora の SDK へのサポートはありますか？

Sora の SDK サポートは提供していません。また有償のサポートも提供していません。

もしアドバイスが必要だったり、問題が起きたりした場合は Discord へお願いします。バグ対応は最優先で行います。

Discord サーバーの招待 URL

https://discord.gg/shiguredo

SDK の質問や相談については sora-sdk-faq を利用してください。

• Sora JavaScript SDK

  • 投稿時に sora-js-sdk タグを指定してください

• Sora iOS SDK

  • 投稿時に sora-ios-sdk タグを指定してください

• Sora Android SDK

  • 投稿時に sora-android-sdk タグを指定してください

• Sora Unity SDK

  • 投稿時に sora-unity-sdk タグを指定してください

• Sora C++ SDK

  • 投稿時に sora-cpp-sdk タグを指定してください

• Sora Python SDK

  • 投稿時に sora-python-sdk タグを指定してください

• Sora C SDK

  • 投稿時に sora-c-sdk タグを指定してください

JavaScript SDK はありますか？

Sora の JavaScript SDK に関しては以下をご確認ください。

• Sora JavaScript SDK ドキュメント — Sora JavaScript SDK

• WebRTC SFU Sora JavaScript SDK

iOS SDK はありますか？

Sora の iOS SDK に関しては以下をご確認ください。 Swift で書かれています。

• Sora iOS SDK ドキュメント — Sora iOS SDK

• WebRTC SFU Sora iOS SDK

• WebRTC SFU Sora iOS SDK クイックスタート

• WebRTC SFU Sora iOS SDK サンプル集

Android SDK はありますか？

Sora の Android SDK に関しては以下をご確認ください。 Kotlin で書かれています。

• Sora Android SDK ドキュメント — Sora Android SDK

• WebRTC SFU Sora Android SDK

• WebRTC SFU Sora Android SDK クイックスタート

• WebRTC SFU Sora Android SDK サンプルアプリケーション

C++ SDK はありますか？

Sora の C++ SDK に関しては以下をご確認ください。 C++ で書かれています。

• WebRTC SFU Sora C++ SDK

Unity SDK はありますか？

Sora の Unity SDK に関しては以下をご確認ください。 C++ SDK をベースにしています。

• Sora Unity SDK ドキュメント — ora Unity SDK ドキュメント

• WebRTC SFU Sora Unity SDK

• WebRTC SFU Sora Unity SDK サンプル集

Python SDK はありますか？

Sora の Python SDK に関しては以下をご確認ください。 C++ SDK をベースにしています。

• Sora Python SDK ドキュメント — Sora Python SDK

• WebRTC SFU Sora Python SDK

JavaScript SDK は認証付き HTTP Proxy に対応していますか？

JavaScript SDK はブラウザで動作するため、ブラウザが WebRTC での HTTP Proxy に対応している必要があります。

主要なブラウザは HTTP Proxy に対応済みです。利用する場合はブラウザで HTTP Proxy の設定をしてください。

iOS / Android / Unity / C++ SDK / Python SDK は認証付き HTTP Proxy に対応していますか？

対応しています。ただし Basic 認証のみの対応で、 OS の設定や PAC ファイルへの対応は未定です 。

• iOS SDK

  • 最新版で対応済みです

• Android SDK

  • 最新版で対応済みです

• C++ SDK

  • 最新版で対応済みです

• Unity SDK

  • 最新版で対応済みです

• Python SDK

  • 最新版で対応済みです

• C SDK

  • 対応していません

ブラウザレスな WebRTC クライアントアプリケーションはありますか？

OSS として WebRTC Native Client Momo を公開しています。

• WebRTC Native Client Momo

• shiguredo/momo: WebRTC Native Client Momo

ライセンス

同時接続とは具体的に何を指していますか？

シグナリングの同時接続数を指しています。1 シグナリング接続で 1 同時接続です。

ライセンスの同時接続数を超えた時はどうなりますか？

もし、最大同時 100 接続のライセンスファイルを利用している場合で 101 本目の接続がきた場合、 Sora は 101 本目の接続を拒否します。

その際、クライアントには SERVICE-UNAVAILABLE というエラーメッセージを通知します。

Sora 側では sora.jsonl ログに EXCEED-MAX-CONNECTIONS というエラーログを出力します。

ライセンスの同時接続数の最小の値はいくつですか？

ライセンスの同時接続数の最小は 100 となります。

10 や 50 といったライセンスは提供しておりません。

ライセンスの同時接続数は 100 単位ですか？

はい、その通りです。100 の次は 200 となり、100 同時接続単位となります。

110 や 150 といったライセンスは提供おりません。

ライセンスの期限を過ぎた場合はどうなりますか？

動作上、既存の接続に対しては特に何もありませんが、新規の接続を受け付けなくなります。

Sora の現在の同時接続数を確認する方法はありますか？

GetStatsReport API の total_ongoing_connections で現在 Sora に接続している同時接続数が確認できます。

また、 Sora Exporter を利用することで、現在の同時接続数を監視することができます。

ライセンス期限のタイムゾーンを教えてください

UTC です。

クラスター利用時に同一のライセンスを利用する方法はありますか？

あります。 最大ノード数ライセンス を契約することで、 1 つのクラスター構築時に同一のライセンスを利用できるようになります。

最大ノード数ライセンス では、 1 クラスターで同一のライセンスを最大いくつのノードに適用できるかがあらかじめ定義されています。 クラスターを構築する際に、その最大ノード数までは同一ライセンスを利用できます。

詳細は 最大ノード数ライセンス をご確認ください。

最大ノード数ライセンスで契約できる最大ノード数はいくつですか？

最大ノード数は 100 を想定しています。

アップデート

アップデートは有償ですか？

ライセンスをご契約いただいている期間は、無償でアップデートを提供させていただきます。

アップデートのタイミングは決まっていますか？

原則として毎年 6 月と 12 月に、機能の追加や改善、削除を目的としたアップデートを行います。

その他、必要に合わせて不定期に修正のアップデートを行うことがあります。

詳細は サポートライフサイクル をご確認ください。

Sora のバージョン表記

バージョン表記:

YYYY.MAJOR.FIX

• YYYY はリリースした年を示します

• MAJOR はその年のメジャーアップデートのリリース回数を示します

• FIX はバグフィックスアップデートおよびホットフィックスアップデートのリリース回数を示します

詳細は サポートライフサイクル をご確認ください。

サポート

古いバージョンの Sora のサポートは提供していますか？

以前は最新バージョンの利用に対してのみサポートを提供していましたが、Sora 2023.1.0 以降はサポート提供期間を約 12 ヶ月間に変更しました。

詳細は サポートライフサイクル をご確認ください。

Sora のサポートは電話で受け付けていますか？

いいえ。サポートはサポート専用のメールでのみ、受け付けています。

Sora のサポートは 24 時間 365 日ですか？

いいえ。サポートは弊社営業日の 10:00-17:00 のみ、対応しています。

SDK の有償サポートは受け付けていますか？

いいえ。Sora SDK の有償サポートは行っていません。

ただし GitHub 上ですべてのコードを公開しています。 もし何か問題が起きた場合は時雨堂コミュニティの Discord にてご相談ください。 バグ対応は最優先で行います。

https://discord.gg/shiguredo

Zakuro や Hisui など関連ツールの有償サポートは受け付けていますか？

いいえ。関連ツールの有償サポートは行っていません。

ただし GitHub 上ですべてのコードを公開しています。 もし何か問題が起きた場合は時雨堂コミュニティの Discord にてご相談ください。 バグ対応は最優先で行います。

https://discord.gg/shiguredo

トラブルシューティング

突然切断された

sora ログに PONG-TIMEOUT-ERROR | reason=<<"WebSocket">> が出力されている場合

Sora からデフォルトの設定で 5 秒間隔で送っている {"type": "ping"} に対して、 クライアントが {"type": "pong"} を 60 秒間返してこない場合に発生します。 また、これらの時間設定は sora.conf の設定 websocket_signaling_ping_interval と websocket_signaling_pong_timeout で変更できます。

これは Sora がクライアントが疎通不能だと判断して切断した、正常な終了です。 まずはクライアントのネットワーク状況を確認してみてください。

WebSocket が詰まることを回避する方法としては、 DataChannel 経由のシグナリング の利用を検討してください。

sora ログに tcp_closed という文字列が含まれている場合

この場合、通信に TURN-TCP が採用されており、OS 側で TCP の切断を検知し、接続を終了しています。 connection ログの turn_transport_type で tcp になっているかどうかを確認してみてください。

OS による TCP の切断に関しては Sora 側で対処できる事は基本的にはありません。

VP9 の映像が乱れる

Windows で Intel の GPU を利用している場合に、VP9 のハードウェアアクセラレーターが正常に動作しないことがあります。 この場合は VP9 を利用せずに、他のコーデックを利用する事で回避してください。

ハードウェアアクセラレーターを明示的に無効にすることで回避することもできますが、 こちらはあまり現実的ではありません。

chrome://flags/#disable-accelerated-video-decode を Disabled にする事で、 ハードウェアアクセラレーターを利用しなくなります。

問題が発生した場合の確認方法

chrome://webrtc-internals の inbound-rtp を見ていただき、 [codec] と decoderImplementation を確認してみてください。

ここで VP9 と ExternalDecoder となっている場合、 VP9 のデコードにハードウェアアクセラレーターが利用されていることが確認できます。

Sora が期待どおりに動かない場合、または、動作に問題がある場合

Sora が期待どおりに動かない場合、 または動作に問題がある場合の問い合わせ時の事前確認と注意事項をまとめています。

事前確認

問い合わせの前に、まずは以下の項目について事前に確認をお願いします。

サポートしている Sora のバージョン

• Sora 2023.2.x

  • 2024 年 12 月 31 日までサポート

• Sora 2024.1.x

  • 2025 年 6 月 30 日までサポート

• Sora 2024.2.X

  • 2025 年 12 月 31 日までサポート

利用している Sora のバージョンがサポート期限内かどうかを確認してください

もし、サポートしているバージョンを利用していない場合は、 サポートしているバージョンへのアップデート後に問題が再現するかの確認をお願いします。

Sora の SDK サポートについては Sora サポート範囲外のため Discord サーバーの各チャンネルをご利用ください

時雨堂コミュニティサーバー:

https://discord.gg/shiguredo

SDK の質問や相談については sora-sdk-faq を利用してください。

• Sora JavaScript SDK

  • 投稿時に sora-js-sdk タグを指定してください

• Sora iOS SDK

  • 投稿時に sora-ios-sdk タグを指定してください

• Sora Android SDK

  • 投稿時に sora-android-sdk タグを指定してください

• Sora Unity SDK

  • 投稿時に sora-unity-sdk タグを指定してください

• Sora C++ SDK

  • 投稿時に sora-cpp-sdk タグを指定してください

• Sora Python SDK

  • 投稿時に sora-python-sdk タグを指定してください

• Sora C SDK

  • 投稿時に sora-c-sdk タグを指定してください

利用しているブラウザが安定版の最新版か確認してください

ブラウザが古い場合、うまく接続できない可能性があります。

もし、ブラウザが古い場合は、最新版で再度問題が発生するかどうか確認をお願いします。

開発ツールを有効にして開発ツールで問題が再現するか確認してください

クライアント側の実装の問題もあるため、必ず確認をお願いしています。

もし、クライアント側の問題の場合は、 Sora のサポートでは対応することができません。ご了承下さい。

クライアントのシグナリング接続が WebSocket over TLS で接続しているかどうかを確認してください

WebSocket over TLS ではない場合は、まずは WebSocket over TLS で接続するようにお願いいたします。

Sora のサポート範囲外の質問はご遠慮ください

Sora の挙動や使い方以外はサポートの範囲外です。

• Sora を利用したサービスの設計や開発

• nginx 全般

• WebRTC 全般

• Sora SDK 全般

• WebRTC Native Client Momo

• WebRTC Load Testing Tool Zakuro

• Recording Composition Tool Hisui

• WebRTC Stats Collector Kohaku

• Audio Streaming Gateway Suzu

• Sora Archive Uploader

• 各種クラウドサービス

上記はすべて Sora のサポート範囲外となります。

問い合わせの場合、お送り頂く情報

重要

前述の事前の確認後、以下の情報を 必ず お送り下さい。

情報をお送り頂くときは テキストファイル でお送りください。

• サーバーやクライアントのスペック

  • わかれば機種名

  • CPU

  • メモリ

  • ディスク

• Linux Kernel のバージョン

  • uname -a の出力

• OS の種類、バージョン

  • Ubuntu と Red Hat Enterprise Linux のどちらを利用しているか

  • 利用している OS のバージョン

  • x86_64 または arm64 のどちらのアーキテクチャを利用しているのか

• Sora のバージョン

  • 2022.1.2 など

• クラスターを利用している場合はクラスターの構成

• Sora の sora.conf 設定ファイル

• Sora の log ディレクトリ以下すべてのログファイル

  • クラスターを利用している場合は全ノードのログ

  • tar.gz または zip などで圧縮し、パッケージ提供時にお送りしているログアップローダーを利用してお送りください

  • 評価中の場合は tar.gz または zip などで圧縮し、メールにてお送り下さい

  • 問題発生時の前後 1 週間分をめどにお送りください

詳細な問題発生状況

何をどうすると問題が発生したのかの状況を可能な限り詳細にお教え下さい

重要

以下の情報については 必ず お送り下さい。

• 問題が発生したコネクションのシグナリング情報

  • チャネル ID

  • セッション ID

  • コネクション ID

  • 音声の有無

    • コーデック

    • ビットレート

  • 映像の有無

    • コーデック

    • ビットレート

    • 解像度

  • サイマルキャスト機能の有無

  • マルチストリーム機能の有無

  • スポットライト機能の有無

• 問題が発生したブラウザバージョン

  • Chrome 119.0.6045.159 や Safari 17.1 など

• SDK の種類とバージョン

  • Sora JavaScript SDK 2020.2.5 や Sora iOS SDK 2020.4.1 など

• 問題が発生したブラウザまたは SDK を利用している OS の種類とバージョン

  • iOS 14.4 や macOS 11.2.3 や Windows 10 1903 など

• 問題の発生状況

  • 発生時刻 (何度か発生している場合は複数)

  • 発生したタイミング (接続した直後、配信が10分以上継続した後、など)

  • 発生頻度

  • 発生時の配信者数、視聴者数

  • 発生の確率 (ある手順を踏むと必ず発生する、同じ手順でも5回に1回程度のみ発生する、など)

再現方法

Sora 内蔵の開発ツールでの再現方法をお送りください

• 再現の手順

  • 開発ツールで問題が発生する場合、その手順をお送り下さい

    • 接続する開発ツールの URL

      • 開発ツールの copy URL を押すと現在の設定を反映した URL がコピーされます

    • 複数クライアントを接続したときに発生する場合は、その順序と接続間隔 (ほぼ同時、数分おいて接続、など)

  • 開発ツールでは発生しない場合、開発ツールに準じた情報をお送り下さい

    • シグナリングのパラメーター

    • 複数クライアントの接続の場合、その順序と接続間隔 (ほぼ同時、数分おいて接続、など)

  • 問題を再現するための独立したアプリケーションが作成できるようであれば、 そちらをご用意いただくと解決までの距離が短くなります

録画関連の問い合わせについて

録画については以下の点をご注意ください

録画ファイルの取り扱いについて

重要

もし、何か録画に問題があった場合でも、録画ファイルを送ることは 絶対 にしないでください。 録画したファイルの代わりに録画したファイルの情報を取得して送ってください。

録画ファイルの情報は mkvinfo と mediainfo コマンドを録画ファイルに対して実行した結果を、テキストファイルでお送りください。

mkvinfo は macOS で Homebrew を利用していれば brew install mkvtoolnix でインストールできます。

それ以外は以下からダウンロードしてください。

MKVToolNix news – Matroska tools for Linux/Unix and Windows

mediainfo は macOS で Homebrew を利用していれば brew install media-info でインストールできます。

それ以外は以下からダウンロードしてください。

MediaInfo - Download

mkvinfo コマンド例:

$ mkvinfo -t -z -v -v -v archive-K3FZ5EZJWS7HXBAJFR37ZYT4GR.webm

mediainfo コマンド例:

$ mediainfo --Details=2 archive-K3FZ5EZJWS7HXBAJFR37ZYT4GR.webm

問題が起きた状況について

• ブラウザで再生して問題が起きた場合は、ブラウザの種類とバージョン、プラットフォームをお教えください

• VLC で再生して問題が起きた場合は、VLC のバージョンとプラットフォームをお教えください

HLS や MPEG-DASH の問い合わせについて

HLS や MEPG-DASH といった Sora が録画したファイルを変換した状態で発生した問題についてはサポート対象外です。

Sora の仕様や使い方に関して質問がある場合

ドキュメントに記載されている Sora の仕様や使い方に関して不明点がある場合は Sora のバージョンとドキュメントの URL を添えてお送りください。

サポートライフサイクル

概要

Sora 2023.1.0 より、サポートの提供期間を変更しています。

変更内容

これまでは Sora の最新バージョンの利用に対してのみサポートを提供していましたが、Sora 2023.1.0 以降はサポートの提供期間をより長く変更します。 また、合わせて Sora のアップデートを以下のとおりに区別します。

メジャーアップデート

サポート提供期間:

メジャーアップデートがリリースされた日から 12 ヶ月後の月末最終日まで

• 原則として毎年 6 月と 12 月に、機能の追加や改善、廃止を目的として行うアップデートをメジャーアップデートといいます

• このアップデートでは、以前のバージョンと後方互換性のない新機能が含まれたり、以前のバージョンの機能が廃止されたりする場合があります

重要

• 2024 年 12 月 18 日にリリースされた Sora 2024.2.0 は、2025 年 12 月 31 日までサポートを提供します

• 2024 年 6 月 26 日にリリースされた Sora 2024.1.0 は、2025 年 6 月 30 日までサポートを提供します

バグフィックスアップデート

サポート提供期間:

修正の対象となるメジャーアップデートがリリースされた日から 12 ヶ月後の月末最終日まで

• メジャーアップデートをリリースして以降、次のメジャーアップデートまでの約 6 ヶ月の間に、問題の修正を目的として不定期に行うアップデートをバグフィックスアップデートといいます

ホットフィックスアップデート

サポート提供期間:

修正の対象となるメジャーアップデートがリリースされた日から 12 ヶ月後の月末最終日まで

• メジャーアップデート、バグフィックスアップデート以外に、ごく稀に緊急のアップデートが必要と判断する場合に行うアップデートをホットフィックスアップデートといいます

• 最新バージョン以外にも、アップデートの必要があると判断する以前のバージョン、およびその両方に対してリリースを行う可能性があります

Sora のバージョン表記

YYYY.MAJOR.FIX

• YYYY はリリースした年を示します

• MAJOR はその年のメジャーアップデートのリリース回数を示します

  • Sora 2024.1.0 は、2024 年の 1 回目のメジャーアップデートであることを示します

• FIX は バグフィックスアップデートおよびホットフィックスアップデートのリリース回数を示します

  • Sora 2024.2.1 は、Sora 2024.2.0 に対する 1 回目のバグフィックスアップデートもしくはホットフィックスアップデートであることを示します

  • FIX のリリース回数は社内のみのリリースも含むことがあるため、公開時のリリース回数は飛ぶ可能性があります

サポートライフサイクル例

対応 OS のサポートライフサイクル

Ubuntu 24.04 LTS

スタンダードサポートまで対応

2029 年 4 月 30 日にメンテナンスサポートが終了するため、 2028 年 6 月リリース予定の Sora までがサポート対象となります。

Ubuntu 22.04 LTS

スタンダードサポートまで対応

2027 年 4 月 30 日にスタンダードサポートが終了するため、 2026 年 6 月リリース予定の Sora までがサポート対象となります。

Ubuntu 20.04 LTS

スタンダードサポートまで対応

2025 年 4 月 30 日にスタンダードサポートが終了するため、 2024 年 6 月リリースの Sora までがサポート対象となります。

Red Hat Enterprise Linux 9

メンテナンスサポートまで対応

2032 年 5 月 31 日にメンテナンスサポートが終了するため、 2031 年 6 月リリース予定の Sora までがサポート対象となります.

Red Hat Enterprise Linux 8

メンテナンスサポートまで対応

2029 年 5 月 31 日にメンテナンスサポートが終了するため、 2028 年 6 月リリース予定の Sora までがサポート対象となります。

チュートリアル

概要

このチュートリアルでは、Sora に組み込まれている開発者ツールを動かして、ひととおり使ってみるところまでを説明します。

チュートリアルの注意点

注意

繋がらないという問い合わせのほとんどは UDP のポート開放忘れです。必ずポートを開放してください。

• このチュートリアルでは、リバースプロキシとしての nginx や HTTPS の知識を必要とします

• Sora は TCP と UDP の両方を利用します

  • TCP はデフォルトであれば 3000 番と 5000 番を利用します

  • UDP はデフォルトであればエフェメラルポートの範囲を利用します

• Sora の開発者ツールは Sora に組み込まれているものを利用して下さい

• Sora の開発者ツールは HTTPS 非対応のため、nginx をリバースプロキシとして利用して、TLS 終端を行ってから Sora に繋ぐ必要があります

• Sora のシグナリングは WebSocket over TLS 非対応のため、nginx をリバースプロキシとして利用して、 TLS 終端を行い Sora のシグナリングへ繋ぐ必要があります

Sora の展開

tar.gz で圧縮されていますので、展開して下さい。

$ tar xfz sora-<version>-<os>-<arch>.tar.gz

設定ファイル

設定ファイルは Sora を展開した sora-<version>/etc/sora.conf にあります。まずは開発者ツールを動作させるまでの最低限の設定を行います。

# はコメントになっている部分ですので、設定する項目がコメントになっている場合は # を削除して設定項目を有効にしてください。

1. ライセンスファイルの指定

   • ライセンスファイルを etc/ において、cp コマンドを利用して license.json に変更して下さい。

2. 開発者ツールの有効化

   • Sora には簡単に検証してもらうための開発者ツールを組み込んでいます。 devtools 項目の # を削除して設定を有効にし、 加えて、設定値に true を指定して Sora に組み込まれている開発者ツールを有効化してください。

## ライセンスファイルを指定してください
## この設定はオプションで、デフォルトは "etc/license.json" です
# license_file = etc/license.json

## 開発者ツールを有効にするかどうかを指定してください
## オプションでデフォルト false です
devtools = true

他の設定はここでは不要です。

起動

設定が終わったらサーバーを起動します。

$ sora-<version>/bin/sora daemon

停止

以下で停止できます。

$ sora-<version>/bin/sora stop

シグナリングへの HTTPS の適用

HTTPS (WebSocket over TLS を含む) の適用は必ず行ってください。HTTPS への接続以外はサポート対象外となります

ブラウザで WebRTC の機能の一つである getUserMedia を利用する場合は HTTPS が必須となります。 ただし、Sora 自体は HTTPS 非対応のため、Sora の前段にリバースプロキシとして nginx を設置して TLS 終端を行ってください。

nginx の location ディレクティブの設定については nginx を参考にして設定をお願いします。

注意

nginx の設定に関する質問については Sora のサポート範囲外となりますのでご了承下さい。

証明書については Let's Encrypt - Free SSL/TLS Certificates の利用をおすすめします。

注意

Let's Encrypt に関する質問については Sora のサポート範囲外となりますのでご了承下さい。

リバースプロキシとしての nginx の役割:

// 開発者ツールの静的ファイルの場合
クライアント -> <HTTPS:443> -> nginx -> <HTTP:5000> -> Sora

// シグナリングの場合
クライアント -> <WebSocket over TLS:443> -> nginx -> <WebSocket:5000> -> Sora

開発者ツールを利用してみる

Sora に組み込まれている開発者ツールの使い方を説明します。 開発者ツールでは Sora の持っている一通りの配信機能を試すことができます。

ブラウザで https://<設定したドメイン>/ にアクセスして以下のような画面が表示されれば成功です。

開発者ツールが動作するブラウザ一覧

以下の最新のブラウザで動作します。

• Google Chrome

• Mozilla Firefox

• Apple Safari

• Microsoft Edge

ただし一部の機能は特定のブラウザでのみ動作します。

動作確認

警告

ハウリングする可能性があります。

ビデオ会議システムなどで利用されるような双方向での配信機能です。 受信だけ、送信だけでの利用もできます。

マルチストリーム送受信 を開き connect を押して、 その後、別のブラウザやタブで同じ URL を開いて、 connect を押して下さい。

追加でタブを開いて connect していけば参加者を増やせます。

開発ツールでは気軽にいろいろな設定を試せるようになっています。触ってみてください。

次のステップ

本番稼働に向けて で Sora の本番稼働向けの設定を行ってください。

Sora はいろいろな機能を持っていますので、一通りドキュメントをご確認下さい。 ドキュメントで不明な点がありましたら、お気軽にお問い合わせください。

注釈

アプリケーション連携チュートリアル は Sora を利用したアプリケーション連携用のチュートリアルを Python にて説明しています。

トラブルシューティング

タイムアウトが起きてつながらない場合

重要

OS の設定やファイアウォールで UDP の通信ができない場合は接続に失敗します。

Sora が利用する UDP のポートの範囲は通常 32768 から 60999 です。この範囲の通信を許可にしてみてください。

それでもうまく繫がらない場合

サーバーの IPv4 アドレスを ipv4_address に指定して、 ipv6 を false にしてみてください。

## ライセンスファイルを指定してください
## この設定はオプションで、デフォルトは "etc/license.json" です
# license_file = etc/license.json

## サーバーで利用する IPv4 アドレスを指定してください
## 指定が無い場合は、自動で見つけたアドレスを利用します
ipv4_address = 192.0.2.10

## 開発者ツールを有効にするかどうかを指定してください
## オプションでデフォルト false です
devtools = true

注釈

Amazon EC2 インスタンス等のようなパブリック IP アドレスとプライベート IP アドレスが異なる環境では ブラウザからアクセスできる IP アドレス（パブリック IP アドレス）を ipv4_address に設定してください。

よくある問題

ここでは利用しているドメインを仮に example.com としています。

• https://example.com/ にアクセスできない

  • nginx の設定が間違っている可能性があります。nginx の設定を見直して下さい

• https://example.com/ にアクセスしても 404 になる

  • Sora の組み込みの開発者ツールが有効になっていない可能性があります

    • sora.conf の設定で開発者ツールが有効になっているか確認して下さい

    • http://example.com:5000/ にアクセスして開発者ツールが有効になっているかを確認して下さい

  • Sora が利用するポートを他のプロセスが利用していないかを確認してください

    • Sora が利用したいポートを他のプロセスが既に利用しているために、Sora が起動していない可能性があります

それでも繋がらない場合

お問い合わせ前に以下を確認してください

• チュートリアル以外のことはやっていないかどうかを確認して下さい

• ファイアウォールの設定をすべて無効にして確認してください

• IPv6 アドレスを無効にして確認してください

• Sora では基本的にロードバランサーを利用することはできませんので、ロードバランサーなしで確認してください

すべてを確認しても繋がらない場合はお問い合わせください。

その際に以下の情報を 必ず お送りください。

• どんな環境でチュートリアルを実行しているか

• Sora のバージョン

• Sora の設定ファイルである sora.conf

• log ディレクトリ以下すべてを tar.gz にて圧縮してお送りください

  • 容量が 1 メガバイトを超える場合は事前にご連絡ください。アップローダーをご提供します

• 繋がらなかった開発者ツール

  • たとえば sendonly など

• 繋がらなかったブラウザを利用している OS とバージョン

  • たとえば macOS Sonoma 14.5 や Windows 10 2004 など

• 繋がらなかったブラウザの種類とバージョン

  • たとえば Chrome 125.0.6422.142 など

それ以外にも可能な限り、こちらがサポートをするために必要そうな情報をお送りください。

本番稼働に向けて

この資料はチュートリアルで Sora をなんとなく体験したあとに、 本番環境に向けてどのような準備が必要なのか、どの機能を使っていけばいいのかをまとめたものです。

重要

不明点などはサポートまでお問い合わせください。

優先順位

Sora で外部から指定する値には優先順位があります。

上から順に優先度が高く、同じ優先度の場合は後から指定した値が優先されます。

1. セッション生成時の払い出しで指定した値

2. 認証成功時の払い出しで指定した値

3. シグナリング接続時に指定した値

4. sora.conf で設定した値

• sora.conf で設定した値は、シグナリング接続時の値で上書きできます

• シグナリング接続時の値は、認証成功時の払い出しで上書きできます

• 認証成功時の払い出しは、セッション生成時の払い出しで上書きできます

本番環境ではシグナリング接続時の値を利用するのは避けて、 認証成功時やセッション生成時の値を利用するようにしてください。

IPv4 アドレスの固定

sora.conf の ipv4_address にサーバーの IP アドレスを指定してください。

ipv4_address = 192.0.2.10

IPv6 アドレスの利用について

Safari は IPv6 環境での動作が不安定なため、 Safari をターゲットデバイスに含んでいる場合は sora.conf の IPv6 設定を無効にする ipv6 = false を推奨しています。

ファイアーウォールを利用される場合は IPv6 向け設定もご確認ください。

sora.conf の turn_fqdn を設定する

iOS の場合は TURN は FQDN を利用しないと接続ができない場合があるため、 TURN-UDP / TURN-TCP で利用するドメインを指定してください。

sora.conf の ipv4_address に指定した IP アドレスを設定してある FQDN を指定してください。

設定例

 turn_fqdn = sora-turn.example.com

ウェブフックなどで利用する CA 証明書のインストール

もしウェブフックなどで HTTPS サーバへのアクセスを行う場合に、 自前で CA 証明書を設定しない場合、信頼された CA 証明書のインストールを行ってください。

• Ubuntu は apt install ca-certificates でインストールされる証明書を利用します

• RHEL (または CentOS) は dnf install ca-certificates でインストールされる証明書を利用します

影響を受ける機能

• 認証ウェブフック

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

• イベントウェブフック

• 音声ストリーミング機能

• 統計エクスポーター機能

ただし、以下の設定で自前で CA 証明書を指定している場合は、この影響を受けません。

• webhook_tls_verify_cacert_file

• audio_streaming_tls_verify_cacert_file

• stats_exporter_tls_verify_cacert_file

HTTP API のループバックアドレスからのみのアクセス

重要

この設定を導入することを強く推奨します

Sora の HTTP API は TLS を利用したセキュアな通信機能や認証機能を持ち合わせていません。

そのため、本番環境では sora.conf の api_loopback_address_only の値を true にしてください。 こうすることでループバックアドレスからのみ HTTP API が叩けるようになります。

アプリケーションからの HTTP API へのアクセスは Nginx などのリバースプロキシ経由で利用してください。

シグナリングのループバックアドレスからのみのアクセス

重要

この設定を導入することを強く推奨します

Sora の WebSocket は TLS を利用したセキュアな通信機能を持ち合わせていません。

そのため、本番環境では sora.conf の signaling_loopback_address_only の値を true にしてください。 こうすることでループバックアドレスからのみシグナリングが叩けるようになります。

WebRTC クライアントからシグナリングへのアクセスは Nginx などのリバースプロキシ経由で利用してください。

ファイルディスクリプタ数の設定

Sora は 1 接続で少なくとも 2 つ以上のファイルディスクリプタを利用します。 また、ウェブフックやログの書き込みでも追加でファイルディスクリプタを利用します。 同時接続数が 100 の場合は Linux のデフォルト値である 1024 でも足りるとは思いますが、 ある程度大きめのファイルディスクリプタ数に変更してください。

systemd の適用

重要

この仕組みを導入することを強く推奨します

Sora の起動/停止に bin/sora daemon を利用するのではなく systemd を適用してください。

デーモン化せずに Sora を動かすには bin/sora foreground を利用します。

詳細は systemd をご確認ください。

TURN-TLS、TURN-TCP、シグナリングで 443 番ポートを使用する

重要

この仕組みを導入することを強く推奨します。 この設定は Sora 2021.1 以降に最適化されています。

注意

nginx および systemd の設定に関する質問については Sora のサポート範囲外となります。

この設定はある程度の nginx や証明書の知識が必要になります

nginx のバージョンは 1.11.5 以降が必須です。

TURN-TLS、TURN-TCP、シグナリング（HTTPS）を 443 番ポートのみで受信する場合は次の設定を追加してください。

注意

nginx の停止に QUIT シグナルを使用している場合は、nginx 起動時に作成された UNIX domain socket のソケットファイルは削除されないため、nginx の再起動に失敗します。 そのため、サービス停止を QUIT シグナルではなく TERM シグナルを使用するように変更するか、または、daemon off で起動することをお勧めします。 systemd を使用している場合も、ドロップインファイル等を作成して、nginx 停止時のシグナルを QUIT シグナルから TERM シグナルへ変更するか、daemon off による管理へ変更することをお勧めします。

nginx のストリーム機能と ssl_preread 機能を利用する

• https://nginx.org/en/docs/stream/ngx_stream_core_module.html

• https://nginx.org/en/docs/stream/ngx_stream_ssl_preread_module.html

Tip

Ubuntu 24.04 では nginx のストリーム機能は apt install libnginx-mod-stream で明示的にインストールする必要があります。

nginx の機能を利用して、同一ポートの待受で複数のプロトコルを扱えるようにします。

その機能を利用した nginx の参考設定です。証明書には Let's Encrypt を利用している想定です。

利用する証明書はマルチドメイン (SANs) またはワイルドカード証明書が前提となります。

• sora.example.com

  • シグナリングの WebSocket over TLS で利用するドメイン

• sora-turn.example.com

  • TURN-TLS で利用するドメイン

nginx.conf

stream {
    # SNI のサーバー名が取得できない場合、または、該当するサーバー名が指定されていない場合は TURN-TCP へ
    # 該当するサーバー名が指定されている場合は TURN-TLS または シグナリングへ
    map $ssl_preread_server_name $upstream {
        default sora-turn.example.com;
        "sora-turn.example.com" unix:/tmp/tls.sock;
        "sora.example.com" unix:/tmp/https.sock;
    }

    # Sora の TURN-TCP へ転送
    upstream sora-turn.example.com {
        # Sora の TURN-TCP へ
        # ここの IP アドレスは Sora の ipv4_address に指定した値を指定してください
        # ここを 127.0.0.1 にすると Firefox で繋がらなくなることを確認しています
        server 192.0.2.1:3478;
    }


    # TURN-TCP, TURN-TLS, シグナリングを TCP で待ち受け
    server {
        listen 443;
        # IPv6 を利用している場合は下記を有効にしてください
        # listen [::]:443;

        proxy_pass $upstream;
        proxy_protocol on;

        ssl_preread on;
    }

    # TURN-TLS, シグナリングの TLS 終端し TURN-TCP へ転送
    server {
        listen unix:/tmp/tls.sock ssl proxy_protocol;

        # SNI を見て TURN-TLS の場合は TURN-TCP へ転送
        # シグナリング（HTTPS）の場合は HTTP へ転送
        proxy_pass $ssl_server_name;
        proxy_protocol on;

        ssl_certificate /etc/letsencrypt/live/sora.example.com/fullchain.pem;
        ssl_certificate_key /etc/letsencrypt/live/sora.example.com/privkey.pem;

        ssl_protocols TLSv1.2;
        ssl_prefer_server_ciphers on;

        ssl_handshake_timeout 10s;

        ssl_session_cache off;
        ssl_session_tickets off;
    }
}

http {
    include mime.types;
    default_type application/octet-stream;
    sendfile on;
    keepalive_timeout 65;
    gzip on;

    # $proxy_protocol_addr を利用することでクライアントの IP が保持できるようになる
    log_format proxy '$proxy_protocol_addr - $remote_user [$time_local] '
                        '"$request" $status $body_bytes_sent '
                        '"$http_referer" "$http_user_agent"';

    # 定義した proxy を利用する
    access_log /var/log/nginx/access.log proxy;

    server {
        listen unix:/tmp/https.sock ssl proxy_protocol;

        root /var/www/html;

        index index.html index.htm;

        ssl_certificate /etc/letsencrypt/live/sora.example.com/fullchain.pem;
        ssl_certificate_key /etc/letsencrypt/live/sora.example.com/privkey.pem;

        ssl_protocols TLSv1.2;

        ssl_prefer_server_ciphers on;

        ssl_session_cache off;
        ssl_session_tickets off;

        real_ip_header proxy_protocol;

        server_name sora.example.com;

        # シグナリングを Sora に Proxy します
        location = /signaling {
                proxy_http_version 1.1;
                proxy_set_header Upgrade $http_upgrade;
                proxy_set_header Connection "upgrade";
                proxy_pass http://127.0.0.1:5000/signaling;

                proxy_set_header X-Real-IP       $proxy_protocol_addr;
                proxy_set_header X-Forwarded-For $proxy_protocol_addr;
        }

        # Sora の HTTP API に Proxy します
        # 本番環境では認証などの機能を利用してください
        location /api {
                proxy_http_version 1.1;
                proxy_pass http://127.0.0.1:3000/;
        }

        # OBS (WHIP/WHEP) 向けのシグナリングを Sora に Proxy します
        location ~ ^/(whip|whip-resource|whep|whep-resource)/ {
                proxy_pass http://127.0.0.1:5000;
                proxy_set_header Host $host;
                proxy_set_header X-Real-IP $remote_addr;
                proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
                proxy_set_header Authorization $http_authorization;
        }

        # Sora のヘルスチェックに Proxy します
        # 公開するかどうかは検討してください
        location /.ok {
                proxy_http_version 1.1;
                proxy_pass http://127.0.0.1:5000;
        }

        # Sora の開発ツールに Proxy します
        # 本番環境では不要です
        location / {
                proxy_http_version 1.1;
                proxy_pass http://127.0.0.1:5000;
        }
    }
}

TURN-TCP、 TURN-TLS、シグナリングを 443 番で使用する場合の sora.conf の設定は以下になります。

turn_tcp_port, turn_tls_port を 443 に変更します。

sora.conf

## TURN 機能を有効にするかどうかを指定してください
turn = true

## TURN 機能で利用するレルムを指定してください
turn_realm = sora-turn.example.com

## TURN 機能で TURN URL 払い出し機能で利用する FQDN (最後の . なし)を指定してください
turn_fqdn = sora-turn.example.com

## TURN 機能で TURN-TCP を有効にするかどうかを指定してください
turn_tcp = true

## TURN 機能で TURN-TCP を有効にした際に利用するポート番号を指定してください
turn_tcp_listen_port = 3478

## TURN 機能で TURN-TCP URL 払い出し時のポート番号を指定してください
turn_tcp_port = 443

## TURN 機能で TURN-TLS URL 払い出し機能を有効にするかどうかを指定してください
## オプションでデフォルトは false です
turn_tls = true

## TURN 機能で TURN-TLS URL 払い出し機能で利用する FQDN (最後の . なし)を指定してください
## turn_tls_fqdn は turn_fqdn の値を上書きします
turn_tls_fqdn = sora-turn.example.com

## TURN 機能で TURN-TLS URL 払い出し機能を有効にした際に利用するポート番号を指定してください
turn_tls_port = 443

Ubuntu の Nginx で Unix Domain Socket を利用する際の注意点

SIGTERM を利用するようにしないと、リスタートすることができません。

$ sudo vim  /lib/systemd/system/nginx.service

# Stop dance for nginx
# =======================
#
# ExecStop sends SIGSTOP (graceful stop) to the nginx process.
# If, after 5s (--retry QUIT/5) nginx is still running, systemd takes control
# and sends SIGTERM (fast shutdown) to the main process.
# After another 5s (TimeoutStopSec=5), and if nginx is alive, systemd sends
# SIGKILL to all the remaining processes in the process group (KillMode=mixed).
#
# nginx signals reference doc:
# http://nginx.org/en/docs/control.html
#
[Unit]
Description=A high performance web server and a reverse proxy server
Documentation=man:nginx(8)
After=network.target

[Service]
Type=forking
PIDFile=/run/nginx.pid
ExecStartPre=/usr/sbin/nginx -t -q -g 'daemon on; master_process on;'
ExecStart=/usr/sbin/nginx -g 'daemon on; master_process on;'
ExecReload=/usr/sbin/nginx -g 'daemon on; master_process on;' -s reload
# 変更前の設定
# ExecStop=-/sbin/start-stop-daemon --quiet --stop --retry QUIT/5 --pidfile /run/nginx.pid
# 変更後の設定
ExecStop=-/sbin/start-stop-daemon --quiet --stop --signal TERM --pidfile /run/nginx.pid
TimeoutStopSec=5
KillMode=mixed

[Install]
 WantedBy=multi-user.target

ExecStop=-/sbin/start-stop-daemon --quiet --stop --signal TERM --pidfile /run/nginx.pid に変更してください。

その後、以下のコマンドを実行してください。

$ sudo systemctl daemon-reload
$ sudo systemctl restart nginx

カーネルパラメーターの適用

Sora は UDP を利用します。音声や映像の配信では大量の UDP を処理するため Linux のデフォルトの設定だと厳しい場合があります。

そのため、パラメーターの変更を推奨しています。

詳細は Linux カーネルチューニング をご確認ください。

コンテナ環境での利用する場合

認識するコア数と利用できるコア数に矛盾がないかの確認

Sora をコンテナ環境で利用する場合、 コンテナが認識するコア数と実際にコンテナが利用できるなコア数が異なる環境があります。

Sora は コンテナが認識するコア数を想定した挙動 をするため、 Sora の性能劣化が発生する場合があります。

コンテナが認識するコア数とコンテナが利用できるコア数が異なる場合は 必ずサポートまでご連絡ください 。

コンテナが認識するコア数は以下のコマンドで確認できます。

$ grep processor /proc/cpuinfo | wc -l

• AWS ECS on EC2 利用時にコンテナが認識するコア数と利用できるコア数が異なる事を確認しています

SDK の利用

Sora へ接続をする場合は弊社がオープンソースとして公開している SDK を利用してください。

• https://github.com/shiguredo/sora-js-sdk

• https://github.com/shiguredo/sora-ios-sdk

• https://github.com/shiguredo/sora-android-sdk

• https://github.com/shiguredo/sora-unity-sdk

• https://github.com/shiguredo/sora-cpp-sdk

• https://github.com/shiguredo/sora-python-sdk

• https://github.com/shiguredo/sora-c-sdk

これらのライブラリは弊社によって最新版の Sora で動作するようにメンテナンスされています。

導入もとても簡単になっているので、是非利用してください。

重要

SDK に関する質問・要望・バグなどの報告は Discord の利用をお願いします。 Sora のライセンス契約の有無に関わらず、 応答時間と問題の解決を保証しませんのでご了承ください。

ただし、明らかなバグについては優先的に対応しますので、ご安心ください。

https://discord.gg/shiguredo

SDK の質問や相談については sora-sdk-faq を利用してください。

• Sora JavaScript SDK

  • 投稿時に sora-js-sdk タグを指定してください

• Sora iOS SDK

  • 投稿時に sora-ios-sdk タグを指定してください

• Sora Android SDK

  • 投稿時に sora-android-sdk タグを指定してください

• Sora Unity SDK

  • 投稿時に sora-unity-sdk タグを指定してください

• Sora C++ SDK

  • 投稿時に sora-cpp-sdk タグを指定してください

• Sora Python SDK

  • 投稿時に sora-python-sdk タグを指定してください

• Sora C SDK

  • 投稿時に sora-c-sdk タグを指定してください

やりたいことが 1:1 の双方向配信の場合

配信が 1:1 の双方向の場合はマルチストリーム機能を利用してください。

詳細は マルチストリーム機能 をご確認ください。

やりたいことが複数人での双方向配信の場合

複数人で双方向の配信を行いたい場合はスポットライト機能を検討してください。

スポットライト機能を利用することで、クライアントとサーバー側の負荷をかなり抑えられるようになります。

詳細は スポットライト機能 をご確認ください。

やりたいことが 1:多 の双方向配信の場合

配信が 1:多 の片方向の場合でもマルチストリーム機能を利用してください。

role に sendonly と recvonly を利用してください。

詳細は マルチストリーム機能 をご確認ください。

やりたいことが 1:多 の片方向配信で、大規模の場合

配信が 1:多 の片方向で大規模な場合は、クラスターリレー機能を利用してください。

クラスターリレー機能を利用することで、1 チャネルで大規模な配信を行うことができます。

詳細は リレー機能 をご確認ください。

やりたいことが OBS からの配信の場合

OBS からの配信を行いたい場合は OBS (WHIP) 対応機能を利用してください。

詳細は OBS (WHIP) 対応機能 をご確認ください。

やりたいことが OBS での取り込みの場合

OBS へ取り込みを行いたい場合は OBS (WHEP) 対応機能を利用してください。

詳細は OBS (WHEP) 対応機能 をご確認ください。

Edge が機能要件に含まれている場合

最新の Edge であれば、ほとんど Chrome と同じ動きをしますので安心してお使いください。

Firefox が機能要件に含まれている場合

Firefox の WebRTC 実装はかなり中途半端なため、 できるだけ Firefox は機能要件から外すことをお勧めします。

認証を外部の指定した HTTP サーバーで判断したい場合

認証ウェブフック機能を利用してください。この機能は外部の指定した HTTP サーバーで認証を判断できるようになります。

外部の HTTP サーバーの URL 指定は sora.conf の auth_webhook_url に設定してください。

そうすることで、外部に認証を移譲できます。

詳細は 認証ウェブフック をご確認ください。

接続、切断の検知を外部の指定した HTTP サーバーで利用したい場合

イベントウェブフック機能を利用してください。この機能は外部の指定した HTTP サーバーでクライアント単位での接続、切断を検知できるようになります。

外部の HTTP サーバーの URL 指定は sora.conf の event_webhook_url に設定してください。

そうすることで、外部にイベントをリクエスト送信できます。

詳細は イベントウェブフック をご確認ください。

配信されている音声や映像を記録したい場合

Sora には録画機能があります。もし利用を検討されている場合はいくつか注意事項があります。

• 録画を終了させる、またはクライアントが切断するまで、録画ファイルは生成されない

• 複数人数が参加する会議の録画ファイルはクライアントごとに生成される

  • 5 人が会議に参加していれば 5 個ファイルが生成されます

これらを踏まえて録画機能の利用を検討してください。

録画機能の詳細は 録画機能 をご確認ください。

クライアント側で参加してきたユーザーの情報を通知したい場合

Sora では「〜さんが会議に参加しました」や「〜さんが会議から退席しました」というメッセージをクライアント側で流すことができます。

これにはシグナリング通知を利用します。

シグナリング通知機能はシグナリングで利用している WebSocket もしくは DataChannel を経由して、 参加しているチャネルに新しく参加、または退席した状態を通知する機能です。自分が参加したときも自身に参加通知は飛びます。

ただシグナリング通知に含まれる標準の情報はあくまでコネクション ID のみになるため、 そのコネクション ID が誰なのかはどこからか取得する必要があります。

そのコネクション ID が誰なのかを問い合わせる処理が毎回走ってしまうのは無駄なため、 認証ウェブフックの戻り値で、 signaling_notify_metadata （シグナリング通知メタデータ）にそのコネクション ID の値のユーザー名を含めてください。 そうすることで、Sora がその参加者のユーザー名を signaling_notify_metadata に含めて返すようになります。

この signaling_notify_metadata は新しく参加した人には data として、 既存の参加している人の signaling_notify_metadata が含まれたリストが参加時に通知されるようになっています。

さらに、新しく参加者がいた場合はその参加者の metadata が通知されます。もちろん退席者の場合でもその退席者の metadata が含まれて通知されます。

metadata にユーザー名が含まれるため、サーバーへ問い合わせをしなくても参加者や退席者のユーザー名を取得できます。

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

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

ライセンス

Sora はライセンスファイルを読み込ませることで起動します。

ライセンスファイルのパス設定と配置

ライセンスファイルのパスは sora.conf の license_file で設定できます。 Sora を起動する前に設定し、ライセンスファイルを配置してください。

デフォルト設定のまま使う場合は、ライセンスファイルを sora ディレクトリ以下の etc/license.json にコピーしてください。

$ cp 123ABC-SRA-E001-202301-100.json sora/etc/license.json

ライセンスの更新

ライセンスを更新する場合は sora.conf の license_file で指定しているファイルを cp コマンドで上書きしてください。 デフォルト設定では sora ディレクトリ以下にある etc/license.json です。

$ cp 123ABC-SRA-E002-201901-100.json sora/etc/license.json

その後、ライセンス更新 API である UpdateLicense API を実行することで更新されます。 Sora の再起動は不要です。

192.0.2.1 の部分には実際に利用している IP アドレスかドメインを指定してください

$ http POST 192.0.2.1:3000/ x-sora-target:Sora_20171218.UpdateLicense -vvv

正常に反映されているかを GetLicense API を実行して serial_code を確認してください。

$ http POST 192.0.2.1:3000/ x-sora-target:Sora_20171218.GetLicense -vvv

ライセンスの更新に失敗した場合

もし、誤って壊れているライセンスファイル等を使用して更新に失敗しても、既存のライセンス情報は上書きされません。

ライセンスの更新時のライセンス適用について

ライセンスが更新される際に新しい接続が発生したとしても、 更新前または更新後のいずれかのライセンスが適用され、最大同時接続数の確認が行われます。

ライセンスの状態が一時的に空白になることはありません。

同時接続数制限を超えて接続しよう賭した場合

重要

最大同時接続数を超過したとしても既に接続しているクライアントには影響がありません。

ライセンスファイルには最大同時接続数が定義してあり、その最大同時接続数を超えて接続することはできません。

sora.jsonl への出力

既存の接続は継続されますが、新規接続ができなくなります。 sora.jsonl に EXCEED-MAX-CONNECTIONS というエラーログが出力します。

クライアントへの通知

最大同時接続数を超えて接続ができなかったクライアントには、 SERVICE-UNAVAILABLE というエラーメッセージが通知されます。

同時接続数が +1 されるタイミング

認証が成功し、セッションへ参加し、そのご WebRTC での接続が確立したタイミングで初めて同時接続数が +1 カウントします。

認証が成功しただけでは同時接続数は増えません。

同時接続数が -1 されるタイミング

コネクションが切断したタイミングで同時接続数から -1 カウントします。

エラーメッセージを通知するタイミング

シグナリング開始で WebSocket で "type": "connect" 送信後に、 最大同時接続数を超えた場合にエラーメッセージが通知され、シグナリングの WebSocket が切断されます。

ライセンス期限が過ぎている場合

重要

ライセンスの期限が過ぎていても Sora を起動する事はできます。

sora.jsonl への出力

既存の接続は継続されますが、新規接続ができなくなります。 sora.jsonl に EXPIRED-LICENSE というエラーログが出力します。

ライセンスの期限時刻

ライセンスの期限が 2022-01 の場合は UTC で 2022 年 2 月 1 日の 0 時から新規接続ができなくなります。

クライアントへ通知するエラーメッセージについて

ライセンス期限が過ぎているため接続ができなかったクライアントには、 SERVICE-UNAVAILABLE というエラメッセージが通知されます。

ライセンスファイルのパスの更新

ライセンスファイルのパスの更新は、一度 Sora を停止し、 sora.conf の license_file のパスを変更して Sora を起動する必要があります。

最大ノード数ライセンス

2022 年 6 月から 最大ノード数ライセンス という形式のライセンスを提供しています。

通常の Sora のライセンスは Sora 1 起動 1 ライセンスと固定されており、 同一のライセンスを複数の Sora で利用することはできません。

最大ノード数ライセンス は、クラスター構築時に、あらかじめライセンスに定義されている最大ノード数までは同一のライセンスを利用できます。

危険

最大ノード数に対応していないライセンスで複数の Sora を起動することはできません。

最大ノード数に対応したライセンスファイルの中身の例

{
  "expired_at": "2013-03",
  "max_connections": 100,
  "max_nodes": 3,
  "product_name": "Sora",
  "serial_code": "DOC123-SRA-E002-201303-N3-100",
  "signature": "****",
  "type": "Experimental"
}

ファイルの中身に "max_nodes": 3 と書かれているライセンスでは、クラスターを組む際に最大 3 ノードまで同一のライセンスが利用できます。

注釈

max_nodes 1 につき 1 ライセンス分の料金が必要になります。例えば max_nodes が 3 の場合は 3 ライセンス分の料金となります。

危険

最大ノード数に対応しているライセンスを利用した場合に構築できるクラスターは 1 つのみです。複数のクラスターを構築することはできません。

最大ノード数ライセンス について不明な部分がある場合はサポートにお問い合わせください。

最大ノード数ライセンスの非クラスター利用について

注意

契約済みの最大ノード数ライセンスを非クラスターで利用したい場合はサポートまでご連絡ください。

最大ノード数ライセンスはクラスターを利用しない場合は通常のライセンスと同じように利用できます。 ただし、 その場合は 1 ライセンスとして扱うため、1 ノードでしか利用できません。 もし "max_nodes": 3 と記載されていても、クラスターを利用しない場合は 1 ノードでしか利用できません。

最大ノード数ライセンスへの切り替えについて

通常のライセンスから最大ノード数ライセンスへの切り替えができます。詳細はサポートまでご連絡ください。

最大ノード数ライセンスと通常ライセンスの混在について

最大ノード数ライセンスと通常ライセンスを混在して利用することはできません。

最大ノード数ライセンスでのみ利用できる機能

• クラスターリレー機能

• クラスターリレー利用時のアフィニティ機能

• クラスター利用時のテンポラリーノード機能

• クラスター利用時のライセンスで決められた最大同時接続数の合計を維持する機能

最大ノード数ライセンス利用時のノード数超過について

InitCluster API で新規に登録する場合のノード数超過

InitCluster API で新規に登録する場合、 node_name_list に指定したノード数が "max_nodes" で指定された最大ノード数を超える場合、 EXCEED-MAX-NODES というエラーメッセージが通知され、クラスターの初期化に失敗します。

RegisterClusterNode API で新規に登録する場合のノード数超過

RegisterClusterNode API で新規に登録する場合、 既にクラスターが最大ノード数ライセンスの "max_nodes" で指定された最大ノード数に達している場合、 EXCEED-MAX-NODES というエラーメッセージが通知され、ノードの登録に失敗します。

ライセンスエラー時の動作確認用ライセンスの提供について

ライセンス期限が過ぎたり、最大同時接続数を超過した際の動作確認を行うためのライセンスを提供しています。 動作確認用ライセンスが必要なお客様はサポートまでご連絡ください。

ライセンスエラー時の動作確認用ライセンスはクラスターでも確認できるよう、最大ノード数ライセンスでの提供となります。 最大ノード数ライセンスはクラスターを利用しない場合は通常のライセンスと同じように利用できます。

ライセンス期限が古く、最大同時接続数が 1 のライセンス

ライセンス期限が過ぎたテストにご利用ください。

ライセンス期限が新しく、最大同時接続数が 0 のライセンス

同時接続数が超過したテストにご利用ください。

ログファイル

サポート問い合わせの場合は log/ ディレクトリ以下をすべて圧縮して送ってください

log/ 以下のログファイル

Sora は log/ ディレクトリ以下にログファイルを出力します。

Sora の運用に関係するログ

• sora.jsonl

  • Sora の開始、終了や問題があった場合に出力されますので、まずはこの監視をお願いします

  • ログローテーションされませんので、ログローテーションをお願いします

  • 週次ログローテーションを推奨します

• cluster.jsonl

  • Sora クラスターに関するログが出力されます

  • Sora クラスターを利用していない場合も出力されます

  • ログローテーションされませんので、ログローテーションをお願いします

  • 週次ログローテーションを推奨します

• auth_webhook.jsonl

  • 認証ウェブフックの送信が 正常に動作した 処理を書き込みます

  • ログローテーションされませんので、ログローテーションをお願いします

  • 週次ログローテーションを推奨します

• auth_webhook_error.jsonl

  • 認証ウェブフックの送信が失敗した処理を書き込みます

    • レスポンスがステータスコードが 200 番台以外であった場合

    • レスポンスの JSON に "allowed" 項目が含まれていない場合

    • レスポンスの JSON が "allowed": false にもかかわらず "reason" 項目が含まれていない場合

    • 送信先からの応答がなく、タイムアウトした場合

  • ログローテーションされませんので、ログローテーションをお願いします

  • 週次ログローテーションを推奨します

• session_webhook.jsonl

  • セッションウェブフックの送信が 正常に動作した 処理を書き込みます

  • ログローテーションされませんので、ログローテーションをお願いします

  • 週次ログローテーションを推奨します

• session_webhook_error.jsonl

  • セッションウェブフックの送信が失敗した処理を書き込みます

    • レスポンスがステータスコードが 200 番台以外であった場合

    • 送信先からの応答がなく、タイムアウトした場合

  • ログローテーションされませんので、ログローテーションをお願いします

  • 週次ログローテーションを推奨します

• event_webhook.jsonl

  • イベントウェブフックで送信した すべて の処理を書き込みます

  • ログローテーションされませんので、ログローテーションをお願いします

  • 週次ログローテーションを推奨します

• event_webhook_error.jsonl

  • イベントウェブフックの送信が失敗した処理を書き込みます

    • レスポンスがステータスコードが 200 番台以外であった場合

    • 送信先からの応答がなく、タイムアウトした場合

  • ログローテーションされませんので、ログローテーションをお願いします

  • 週次ログローテーションを推奨します

• stats_webhook.jsonl

  • このログは stats_webhook_log を true に設定した場合に出力されます

  • 統計ウェブフックで送信した すべて の処理を書き込みます

  • ログローテーションされませんので、ログローテーションをお願いします

  • 週次ログローテーションを推奨します

• stats_webhook_error.jsonl

  • このログは stats_webhook_log を true に設定した場合に出力されます

  • 統計ウェブフックの送信が失敗した処理を書き込みます

    • レスポンスがステータスコードが 200 番台以外であった場合

    • 送信先からの応答がなく、タイムアウトした場合

  • ログローテーションされませんので、ログローテーションをお願いします

  • 週次ログローテーションを推奨します

• rtc_stats.jsonl

  • このログは rtc_stats_log を true に設定した場合に出力されます

  • クライアントの RTC 統計情報を出力します

  • ログローテーションされませんので、ログローテーションをお願いします

  • 週次ログローテーションを推奨します

Sora のサポートに関係するログ

• connection.jsonl

  • 接続が切断した際にクライアントとサーバーの統計情報を出力するログです

  • ログローテーションされませんので、ログローテーションをお願いします

  • 週次ログローテーションを推奨します

• signaling.jsonl

  • シグナリングでやりとりされている offer / answer / candidate / re-offer / re-answer と接続終了 (close) を記録したログです

  • OBS WHIP/WHEP 用の whip-offer / whip-answer / whep-offer / whep-answer も出力します

  • ログローテーションされませんので、ログローテーションをお願いします

  • 週次ログローテーションを推奨します

• signaling_error.jsonl

  • legacy_signaling_error を false に設定している場合にのみ出力されます

    • デフォルトは false です

  • シグナリングでエラーが発生した際にエラー情報を出力します

  • ログローテーションされませんので、ログローテーションをお願いします

  • 週次ログローテーションを推奨します

• api.jsonl

  • 一部の API 操作に関するログを出力します

  • ログローテーションされませんので、ログローテーションをお願いします

  • 週次ログローテーションを推奨します

• internal.jsonl

  • Sora が予定外の動作をしたときに出力されるログです。問題解決に必須のログです

  • ログローテーションされませんので、ログローテーションをお願いします

  • 週次ログローテーションを推奨します

• crash.log

  • Sora が予定外の動作をしたときに出力されるログです。問題解決に必須のログです

  • ログローテーションされませんので、ログローテーションをお願いします

  • 週次ログローテーションを推奨します

• erlang.log.<1..5>

  • サポート時に必要となるログですので、気にする必要はありません

  • 自動でログローテーションされますので、ログローテーションは不要です

  • bin/sora foreground コマンドで起動する場合には出力されません

• sysctl.log

  • 起動時に取得するログで、毎回上書きされます

  • sysctl -a の実行結果を記録します

  • ログローテーションは不要です

• ulimit.log

  • 起動時に取得するログで、毎回上書きされます

  • ulimit -n の実行結果を記録します

  • ログローテーションは不要です

• run_erl.log

  • 起動時に出力されるログのため、ほとんどログが出力されることはありません

  • ログローテーションは不要です

  • bin/sora foreground コマンドで起動する場合には出力されません

• connection_created_wait_timeout_error/<timestamp>_<connection_id>.jsonl

  • sora ログに CONNECTION-CREATED-WAIT-TIMEOUT-ERROR が出力された際の接続情報を出力します

  • クライアントと Sora との間で WebRTC が確立できなかった場合の情報です

  • ファイル名は時刻とコネクション ID の組み合わせです

特別なログ

Sora が異常終了した際 erl_crash.dump というファイルが log/ ディレクトリに生成されます。

こちらは 必ず 保存し、送っていただけるようお願いいたします。

監視用確認目的で erl_crash.dump ログを強制的に出力させる方法

監視を行う際に実際に erl_crash.dump を生成したい場合には、 bin/sora daemon で起動した上で、 kill -SIGUSR1 を使用して run_erl プロセスを落としてください。

$ kill -SIGUSR1 <プロセス ID>

この方法で log/ ディレクトリに erl_crash.dump が生成されます。

JSONL (JSON Lines) 形式

Sora は一部のログを除いて JSONL 形式でログを出力します。

JSONL の仕様は JSON Lines に記載されているものに準拠します。

• UTF-8 エンコード

• 改行は \n

• 各行は JSON 値

• ファイル拡張子は jsonl

JSONL 形式で出力されるログ

• sora ログ

• cluster ログ

• internal ログ

• api ログ

• signaling ログ

• connection ログ

• auth_webhook ログ

• auth_webhook_error ログ

• session_webhook ログ

• session_webhook_error ログ

• event_webhook ログ

• event_webhook_error ログ

• stats_webhook ログ

• stats_webhook_error ログ

• connection_created_wait_timeout_error ログ

id

Sora が出力する全ての JSONL 形式のログには UUIDv4 を Base32 でエンコードした "id" が含まれます。

"id": "JKBYVZA3KN6QH249B6QTKDCX8M"

auth_webhook ログ

出力ファイル名:

auth_webhook.jsonl

{
  "timestamp": "2024-01-19T02:44:22.799941Z",
  "id": "7N7RTNSEVN43ZB7NVXGAYPETJ4",
  "req": {
    "timestamp": "2024-01-19T02:44:22.793747Z",
    "id": "1EYTQSFVZ56MZ2BRZC12GQYQKW",
    "x_forwarded_for": "49.97.11.19",

    "version": "2024.1.0",
    "label": "WebRTC SFU Sora",
    "node_name": "[email protected]",

    "role": "sendrecv",
    "channel_id": "sora",
    "connection_id": "9SRMRSDWA959XFN74DCV3Z6XA0",

    "multistream": true,
    "simulcast": false,
    "spotlight": false,

    "audio": true,
    "audio_codec_type": "OPUS",

    "video": true,
    "video_codec_type": "VP9",
    "video_bit_rate": 500,
    "video_vp9_params": {
      "profile_id": 0
    },

    "data_channel_signaling": true,
    "ignore_disconnect_websocket": false,

    "channel_connections": 0,
    "channel_sendrecv_connections": 0,
    "channel_sendonly_connections": 0,
    "channel_recvonly_connections": 0,

    "sora_client": {
      "raw": "Sora JavaScript SDK 2024.1.0",
      "type": "Sora JavaScript SDK",
      "version": "2024.1.0",
      "environment": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36"
    },

    "e2ee": false
  },
  "res": {
    "allowed": true,
    "client_id": "client-01"
  },
  "url": "http://192.0.2.1:9000/webhook/auth"
}

auth_webhook_error ログ

出力ファイル名:

auth_webhook_error.jsonl

認証ウェブフックが正常に動作しなかった場合に出力します。

auth_webhook ログとは異なり res ではなく reason が出力されます。

session_webhook ログ

出力ファイル名:

session_webhook.jsonl

レスポンスが返却されない場合、 res は出力されません。

{
  "id": "XJ227VDDFH60BAB833C1R2HDBW",
  "timestamp": "2024-04-19T05:32:25.583312Z",
  "req": {
    "id": "D5PAF0ZHDX00B4VAWMZAR866MR",
    "label": "WebRTC SFU Sora",
    "timestamp": "2024-04-19T05:32:24.280641Z",
    "type": "session.created",
    "version": "2024.1.0",
    "node_name": "[email protected]",
    "session_id": "NAA3DGPJQH2J7FDV698RZ9X6R0",
    "channel_id": "sora",
    "multistream": true,
    "spotlight": false,
    "created_time": 1713504744,
    "created_timestamp": "2024-04-19T05:32:24.277809Z"
  },
  "url": "http://192.0.2.1/webhook/session",
  "res": {
    "recording": true
  }
}

connection ログ

出力ファイル名:

connection.jsonl

Sora は接続単位で統計情報を保持しています。クライアント側の統計情報とサーバー側の統計情報の両方をログとして出力します。

クライアント側の統計情報はユーザーエージェント統計情報機能を利用しているため、 SDK 側がユーザーエージェント統計機能に対応している必要があります。

こちらのログはログローテーションしないため、ローテーションが必要となります。

sora ログ

出力ファイル名:

sora.jsonl

sora ログは主にサポートで利用するためのログを出力します。そのためエラーメッセージがかなり技術的な表現になっています。

• sora ログは何かあって大量のログが出たとしてもうまい具合にスキップする機能が入っています

UTC に固定

sora ログのタイムスタンプは RFC 3339 UTC (マイクロ秒) 形式に固定されています。 timestamp という項目でタイムスタンプが出力されます。

{
  "id": "QGJMC1AF3552V448N8F53CZBJ4",
  "level": "debug",
  "channel_id": "sora",
  "multistream": true,
  "role": "sendonly",
  "simulcast": false,
  "spotlight": false,
  "node_name": "[email protected]",
  "connection_id": "NXHKH46FP93571ZM4PZBSFD4Z4",
  "timestamp": "2022-08-02T04:43:02.828358Z"
}

クラスター利用時

{
  "id": "QR6YX8VW8H76N6S3B7HBCXJ4PM",
  "level": "debug",
  "channel_id": "sora",
  "multistream": true,
  "role": "sendonly",
  "simulcast": false,
  "spotlight": false,
  "node_name": "[email protected]",
  "connection_id": "NXHKH46FP93571ZM4PZBSFD4Z4",
  "timestamp": "2022-08-02T04:43:02.828358Z"
}

オプション情報

{
  "level": "debug",
  "channel_id": "sora",
  "multistream": true,
  "role": "sendonly",
  "simulcast": false,
  "spotlight": false,
  "node_name": "[email protected]",
  "connection_id": "NXHKH46FP93571ZM4PZBSFD4Z4",
  "timestamp": "2022-08-02T04:43:02.828358Z"
}

出力例

シグナリング接続時に認証サーバーがステータスコード 400 を返してきた際に出力される AUTH-WEBHOOK-RESPONSE-UNEXPECTED-STATUS-CODE の出力例は次の通りです。

{
  "channel_id": "sora",
  "connection_id": "J9RQEB074S2EB9SFBCN9AH7ASM",
  "domain": [
    "sora",
    "signaling"
  ],
  "level": "error",
  "msg": "AUTH-WEBHOOK-RESPONSE-UNEXPECTED-STATUS-CODE | reason={auth_webhook_response_unexpected_status_code,#{status_code => 400}}",
  "multistream": true,
  "node": "[email protected]",
  "role": "recvonly",
  "simulcast": false,
  "sora_version": "2022.2.0",
  "spotlight": false,
  "timestamp": "2022-08-03T03:43:13.588364Z"
}

シグナリング接続時の "type": "connect" で指定する JSON が間違っており、Sora 側から切断した際に出力される INVALID-JSON の出力例は次のとおりです。

{
  "msg": "INVALID-JSON | reason=...",
  "node": "[email protected]",
  "level": "error",
  "domain": [
    "sora",
    "signaling"
  ],
  "channel_id": "sora",
  "timestamp": "2023-11-02T02:12:35.854402Z",
  "sora_version": "2022.2.0"
}

シグナリングに WebSocket を利用している場合に、指定時間に一度も "type": "pong" が返ってこない場合Sora 側から切断した際に出力される PONG-TIMEOUT-ERROR の出力例は次の通りです。

指定時間のデフォルト値は 60 秒です。 sora.conf の設定 websocket_signaling_pong_timeout で変更できます。

{
  "msg": "PONG-TIMEOUT-ERROR | reason=<<\"WebSocket\">>",
  "node": "[email protected]",
  "role": "sendrecv",
  "level": "error",
  "domain": [
    "sora",
    "signaling"
  ],
  "simulcast": false,
  "spotlight": false,
  "timestamp": "2023-11-02T02:12:35.854402Z",
  "channel_id": "sora",
  "multistream": true,
  "sora_version": "2023.1.0",
  "connection_id": "174QEZP34D45B6S7665Y32MSQ0"
}

warning

ログレベル warning は「接続自体は維持できる問題」の際に出力します。 このログが出力された場合でも Sora 側から切断は行いません。

• 一般

  • WEBSOCKET-TERMINATE

    • DataChannel シグナリングで ignore_disconnect_websocket: true の際に WebSocket が想定外の終了をした場合に出力します

  • MULTISTREAM-RE-ANSWER-NO-ICE-UFRAG

    • マルチストリーム利用時 type: re-answer を受信した際に ICE に必要な SDP が含まれていない場合に出力します

  • MULTISTREAM-INTERNAL-ERROR

• ウェブフック

  • INVALID-AUTHZ-VALUE

    • 認証ウェブフック成功時に認証サーバーからの払い出した値がおかしい場合に出力します

  • TERMINATE-EVENT-WORKER

    • イベントウェブフックのワーカーが何らかの理由で終了した場合に出力します

  • MISSING-WEBHOOK-BASIC-AUTH-USER-ID

    • ウェブフック利用時にベーシック認証のユーザー ID が見つからない場合に出力します

  • MISSING-WEBHOOK-BASIC-AUTH-PASSWORD

    • ウェブフック利用時にベーシック認証のパスワードが見つからない場合に出力します

  • MISSING-WEBHOOK-PROXY-AUTH-PASSWORD

    • ウェブフック利用時にプロキシのパスワードが見つからない場合に出力します

• 録画

  • ARCHIVE-FINAL-SPLIT-ERROR

    • 録画ファイルの分割がエラーになった場合に出力します、ただし全体出力に向けて処理は継続します

  • MISSING-RECORDING-WORKER-PID

    • 録画処理が完了したワーカーが見つからず正常終了できない場合に出力します

• プロトコル

  • DTLS-ALERT

    • DTLS でレベルが WARNING のアラートメッセージがクライアントから送られてきた場合に出力します

  • TURN-SEND-INDICATION-BINDING-ERROR

    • TURN 利用時に STUN-Binding-Error over STUN-Send-Indication を受信した場合に出力します

  • TURN-CHANNEL-DATA-BINDING-ERROR

    • TURN 利用時に STUN-Binding-Error over TURN-Channel-Data を受信した場合に出力します

  • SIMULCAST-DUPLICATED-RID

    • クライアントから複数の SSRC から同一の RID が送られてきた場合に出力します

  • UNKNOWN-RTP

    • role: recvonly にもかかわらず RTP パケットが送られてきた場合に出力します

    • Sora の内部エラーでも出力される場合があります

  • UNKNOWN-RTCP

    • 見知らぬ RTCP を受信した場合に出力します

  • ULPFEC-RECOVER-ERROR

    • ULPFEC を利用している場合にリカバーを試みて失敗した場合に出力します

  • RTP-PACKET-LOSS-SIMULATOR-INCOMING-ENABLED

    • 受信パケロスシュミレーターを有効にしている場合に出力します

  • RTP-PACKET-LOSS-SIMULATOR-OUTGOING-ENABLED

    • 送信パケロスシュミレーターを有効にしている場合に出力します

error

ログレベル error は「接続自体を維持できない問題」の際に出力します。 このログが出力された場合、Sora 側から切断を行います。

• 一般

  • UNEXPECTED-EXIT

• シグナリング

  • INVALID-JSON

    • 無効な JSON を受け取った場合に出力します

  • FAILURE-JSON-DECODE

    • JSON のデコードに失敗した場合に出力します

  • AUTHENTICATION-FAILURE

    • 認証ウェブフックで認証が失敗した場合に出力します

  • AUTHENTICATION-INTERNAL-ERROR

    • 認証ウェブフックで 200 番台以外が返ってきた場合に出力します

  • INTERNAL-ERROR

    • Sora の内部エラーです

  • MISSING-SDP-FINGERPRINT

    • SDP に DTLS の証明書検証に利用するフィンガープリントが見つからなかった場合に出力します

  • MISSING-ICE-SDP

    • SDP に ICE で利用する情報が見つからなかった場合に出力します

  • FAILURE-SDP-PARSE

    • SDP のパースに失敗した場合に出力します

  • INVALID-SIGNALING-TYPE

    • 送られてきたシグナリングメッセージの type が無効な場合に出力します

  • UNEXPECTED-SIGNALING-TYPE

    • 送られてきたシグナリングメッセージの type が見知らぬ場合に出力します

  • MISSING-TYPE

    • 送られてきたシグナリングメッセージに type が見つからない場合に出力します

  • TOO-LARGE-JSON

    • 送られてきた JSON が巨大な場合に出力されます

  • TOO-MANY-CANDIDATE

    • あまりにも多い "type": "candidate" を送ってきた場合に出力します

  • SIGNALING-INTERNAL-ERROR

    • シグナリングでの内部エラーが発生した場合に出力します

  • TRANSPORT-INTERNAL-ERROR

    • 通信での内部エラーが発生した場合に出力します

  • BAD-FINGERPRINT

    • DTLS の証明書の検証に失敗した場合に出力します

  • PONG-TIMEOUT-ERROR

    • 指定時間間隔 (デフォルト 5 秒) で type: ping を送信し、指定時間内に (デフォルト 60 秒間) 1 度も type: pong が返ってこない場合に出力します

    • これらの時間は sora.conf の設定 websocket_signaling_ping_interval と websocket_signaling_pong_timeout で変更できます。

  • CONNECT-WAIT-TIMEOUT-ERROR

    • WebSocket を確立して一定時間以内に "type": "connect" を送ってこない場合に出力します

  • CONNECTION-CREATED-WAIT-TIMEOUT-ERROR

    • 一定時間以内に WebRTC が確立しない場合に出力します

  • ANSWER-TIMEOUT-ERROR

    • 一定時間以内に "type": "answer" を送ってこない場合に出力します

• ライセンス

  • EXPIRED-LICENSE

    • ライセンスが切れている場合に出力されます

  • EXCEED-MAX-CONNECTIONS

    • ライセンスの同時接続数を超えて接続をしようとしたクライアントがいた場合に出力されます

• 認証ウェブフック

  • AUTH-WEBHOOK-INTERNAL-ERROR

    • 認証ウェブフックで内部エラーが発生した場合出力します

  • AUTH-WEBHOOK-AUTHZ-INTERNAL-ERROR

    • 認証ウェブフックの戻り値で内部エラーが発生した場合出力します

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

  • SESSION-WEBHOOK-INTERNAL-ERROR

    • セッションウェブフックが正常に送信できなかった、または内部エラーが発生した場合出力します

• イベントウェブフック

  • EVENT-WEBHOOK-ERROR

    • イベントウェブフックリクエストが正常に送信できなかった場合に出力します

• DataChannel

  • INVALID-DATA-CHANNEL-USER-DATA

    • 片方向でしか利用していない DataChannel にメッセージが送られてきた場合に出力します

• 録画

  • ARCHIVE-FAILED

    • 録画ファイルの生成に失敗した際に出力します

  • RECORDING-INTERNAL-ERROR

    • 録画で内部エラーが発生した際に出力します

• プロトコル

  • TURN-UDP-INTERNAL-ERROR

    • TURN UDP で内部エラーが発生した場合に出力します

  • DTLS-ALERT

    • DTLS でレベルが FATAL のアラートメッセージが送られてきたとき出力します

emergency

ログレベル emergency は「Sora の起動を維持できない問題」の際に出力します。 このログが出力された場合、Sora を終了します。

• SORA-NODE-DUPLICATED

  • 同一ノード名の Sora が既に起動している場合に出力します

• BOOT-FAILED

  • Sora が正常に起動できない場合に出力します

• 設定

  • SORA-CONF-ERROR

    • sora.conf が正常に読み込めない場合に出力します

• クラスター

  • CLUSTER-INTERNAL-FAILURE

    • クラスター内部で問題が発生した際に出力します

sora.conf リファレンス

Sora の設定ファイルは key = value 形式です。 文字列であっても "" で囲わないでください。

単位指定

sora.conf では一部の設定に単位の指定が必須です。

• 利用できる単位

  • ミリ秒 ms

  • 秒 s

  • 分 min

  • 時 h

• 数値と単位の間にはスペースを入れてください

設定例

 webhook_response_timeout = 30 s

注釈

利用できる単位が制限されている設定項目も存在します。

範囲表記

• 2..10 と書いてある場合 2 以上、10 以下の値を指定できることを表しています

• 2..10 s と書いてある場合は 2 秒以上、10 秒以下の値を指定できることを表しています

license_file

デフォルト:

"etc/license.json"

ライセンスファイルのパスを指定してください、可能な限り 絶対パス を指定してください。

設定例

license_file = etc/license.json

label

デフォルト:

"WebRTC SFU Sora"

認証やイベントウェブフックリクエスト送信時に送られる、サーバー固有の値を指定してください。

設定例

label = sora-node-001.example.com

ipv4_address

デフォルト:

設定無し

この値を有効にしなくても自動で IPv4 アドレスを収集しますが、 固定された IPv4 アドレスがサーバーに割り当てられている場合は指定することを推奨しています。

IPv4 アドレスを指定してください。 192.0.2.10 のように指定してください。

設定例

ipv4_address = 192.0.2.10

ipv6

デフォルト:

false

IPv6 機能を有効にするかどうか指定してください。デフォルトでは無効になっています。

この機能を有効にすると以下の機能が有効になります

• ipv6_address が指定されていない場合は自動で IPv6 アドレスが収集される

• ipv6_address で指定された値が使用される

• IPv6 アドレスが使用できる場合、 TURN サーバーの URL が IPv6 でも払い出される

この機能はシグナリングや API を IPv6 有効にする機能ではありません。シグナリングや API は IPv6 非対応です。

設定例

ipv6 = false

ipv6_address

デフォルト:

設定無し

この値を有効にしなくても ipv6 が true の場合は、自動で IPv6 アドレスを収集しますが、 固定された IPv6 アドレスがサーバーに割り当てられている場合は指定することを推奨しています。

IPv6 アドレスを指定してください。 2001:0DB8::10 のように指定してください。

設定例

ipv6_address = 2001:0DB8::10

ipv6_only

デフォルト:

false

IPv6 アドレスのみを利用するようになります。この設定はシグナリングや API には影響しません。

設定例

ipv6_only = true

devtools

デフォルト:

false

Sora には機能をすぐに試してもらえるように開発ツールが含まれています。

開発ツールを有効にする場合は、 true を指定し、有効にしてください。

詳細は 開発者ツール をご確認ください。

設定例

devtools = true

media_publish_worker_number

デフォルト:

1

音声や映像の 1 配信に利用する配信ワーカー数を指定してください。

設定例

media_publish_worker_number = 1

auth_webhook_url

デフォルト:

指定なし

認証機能を有効にしたときに、問い合わせに行く HTTP URL を指定してください。その戻り値に含まれる値によって認証の可否を判定します。

設定例

auth_webhook_url = https://example.com/sora/webhook/auth

auth_webhook_log

デフォルト:

true

認証ウェブフックをすべてログファイルに出力します。詳細は 認証ウェブフックログ をご確認ください。

設定例

auth_webhook_log = true

session_webhook_url

デフォルト:

指定なし

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

設定例

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

session_webhook_worker_number

デフォルト:

5

範囲:

5..5000

セッションウェブフックのワーカー数を指定してください。

設定例

session_webhook_worker_number = 5

session_created_timeout

デフォルト:

5 s

範囲:

0..300 s

セッションが存在しない状態で、新規接続が来た際にセッション生成に利用できる時間を指定してください。 この時間はセッションウェブフックにかかる時間も含まれます。

設定例

session_created_timeout = 5 s

session_destroyed_timeout

デフォルト:

15 s

範囲:

0..300 s

セッションに同時接続数が 0 になった場合、セッション破棄する時間を指定してください。

設定例

session_destroyed_timeout = 15 s

session_updated_webhook_interval

デフォルト:

1 min

範囲:

1..10 min

単位:

min のみ

セッション更新時のセッションウェブフック session.updated の間隔を指定してください。 時間単位には 分 min のみ指定できます。

設定例

session_updated_webhook_interval = 1 min

session_created_response_validate_warning_as_error

注意

この設定を利用する場合は事前にサポートまでご連絡ください

デフォルト:

false

セッションウェブフック session.created の戻り値が正常でない場合にエラーとし、セッションを破棄するかどうかを指定してください。

注釈

この設定が false の場合、戻り値が正常でない場合は sora ログに警告が出力され、デフォルトの戻り値が設定されます。 セッションも破棄されません。

設定例

session_created_response_validate_warning_as_error = true

event_webhook_url

デフォルト:

指定なし

クライアントの接続や切断、録画ファイル生成の終了などのイベントを通知する HTTP URL を指定してください。

設定例

event_webhook_url = https://example.com/sora/webhook/event

event_webhook_worker_number

デフォルト:

5

範囲:

5..5000

イベントウェブフックのワーカー数を指定してください。 イベントウェブフックのワーカー割り当てに利用する値は channel_id です。

設定例

event_webhook_worker_number = 5

stats_webhook_url

デフォルト:

指定なし

統計情報を通知する HTTP URL を指定してください。

設定例

stats_webhook_url = https://example.com/sora/webhook/stats

stats_webhook_log

デフォルト:

false

統計ウェブフックのログをファイルに出力します。

設定例

stats_webhook_log = true

stats_webhook_worker_number

デフォルト:

5

範囲:

5..5000

統計ウェブフックのワーカー数を指定してください。 統計ウェブフックのワーカー割り当てに利用する値は channel_id です。

設定例

stats_webhook_worker_number = 5

webhook_ipv6

デフォルト:

false

ウェブフックで IPv6 を利用するかどうかを指定してください。

この設定を true にしない限り、ウェブフックでは IPv4 が利用されます。

設定例

webhook_ipv6 = true

webhook_connect_timeout

デフォルト:

30 s

範囲:

1..600 s

ウェブフックの接続確立までのタイムアウト時間を指定してください。

設定例

webhook_connect_timeout = 120 s

webhook_response_timeout

デフォルト:

5 s

範囲:

1..600 s

ウェブフックのレスポンス受信までのタイムアウト時間を指定してください。

設定例

webhook_response_timeout = 5 s

connection_updated_webhook_interval

デフォルト:

1 min

範囲:

1..10 min

単位:

min のみ

接続更新時のイベントウェブフック connection.updated の間隔を指定してください。 時間単位には 分 min のみ指定できます。

設定例

connection_updated_webhook_interval = 1 min

webhook_insecure

注意

この設定を利用する場合は事前にサポートまでご連絡ください

デフォルト:

false

ウェブフックで HTTPS を利用する際に証明書のチェックを行わない場合はこの設定を有効にしてください。

設定例

webhook_insecure = true

webhook_basic_authn

デフォルト:

false

ウェブフックで HTTP ベーシック認証を利用するかどうかを指定してください。

設定例

webhook_basic_authn = true

webhook_basic_authn_user_id

デフォルト:

指定なし

ウェブフックで HTTP ベーシック認証を利用する際のユーザー ID を指定してください。 basic-authn-user-id の用に文字列で指定してください。

設定例

webhook_basic_authn_user_id = basic-authn-user-id

webhook_basic_authn_password

デフォルト:

指定なし

ウェブフックで HTTP ベーシック認証を利用する際のパスワードを指定してください。 basic-authn-password の用に文字列で指定してください。

設定例

webhook_basic_authn_password = basic-authn-password

webhook_proxy_url

指定しない場合はコメントアウトしたままにしてください

デフォルト:

指定なし

ウェブフックで利用する HTTP Proxy の URL を指定してください。 http://proxy.example.com:8080 の用に URL を指定してください。

設定例

webhook_proxy_url = http://proxy.example.com:8080

webhook_proxy_auth_user

指定しない場合はコメントアウトしたままにしてください

デフォルト:

指定なし

ウェブフックで利用する HTTP Proxy の認証ユーザーを指定してください。 proxy-auth-user の用に文字列で指定してください。

設定例

webhook_proxy_auth_user = proxy-auth-user

webhook_proxy_auth_password

指定しない場合はコメントアウトしたままにしてください

デフォルト:

指定なし

ウェブフックで利用する HTTP Proxy の認証パスワードを指定してください。 proxy-auth-password の用に文字列で指定してください。

設定例

webhook_proxy_auth_password = proxy-auth-password

webhook_tls_fullchain_file

指定しない場合はコメントアウトしたままにしてください

デフォルト:

指定なし

ウェブフックリクエスト送信先との通信に HTTPS で mTLS を利用するための設定で、 中間証明書を含むクライアント証明書を PEM 形式で設定してください。

設定例

webhook_tls_fullchain_file = /path/to/fullchain.pem

webhook_tls_privkey_file

指定しない場合はコメントアウトしたままにしてください

デフォルト:

指定なし

ウェブフックリクエスト送信先との通信に HTTPS で mTLS を利用するための設定で、 クライアント証明書の秘密鍵を PEM 形式で設定してください。

重要

秘密鍵にはパスフレーズが設定されている場合エラーとなります

設定例

webhook_tls_privkey_file = /path/to/privkey.pem

webhook_tls_verify_cacert_file

指定しない場合はコメントアウトしたままにしてください

デフォルト:

指定なし

ウェブフックリクエスト送信先との通信に HTTPS を利用した際、サーバー証明書のチェックを行う CA ファイルを PEM 形式で設定してください。

設定例

webhook_tls_verify_cacert_file = /path/to/server_cacert.pem

重要

この設定がない場合、 OS 組み込みのルート CA 証明書を利用してサーバー証明書をチェックします。 OS 組み込みのルート CA 証明書については ウェブフックリクエストなどの送信先サーバー証明書の検証に利用する OS 組み込みのルート CA 証明書について をご確認ください。

ignore_connection_updated_webhook

デフォルト:

false

イベントウェブフックの接続の更新時に event_webhook_url に指定された URL へ connection.updated を送るかどうかを指定してください。 デフォルトではリクエストの送信を行います。

この設定が true の場合でも、 event_webhook.jsonl には connection.updated のログが出力されます。

設定例

ignore_connection_updated_webhook = false

ignore_connection_failed_webhook

デフォルト:

true

接続が失敗時に event_webhook_url に指定された URL へ connection.failed リクエストを送るかどうかを指定してください。 デフォルトではリクエストの送信を行いません。

この設定が true の場合でも、 event_webhook.jsonl には connection.failed のログが出力されます。 ただし、 legacy_signaling_error を true に設定した場合は、 connection.failed のログは出力されません。

設定例

ignore_connection_failed_webhook = false

ignore_session_updated_webhook

デフォルト:

false

セッションウェブフックのセッションの更新時に session_webhook_url に指定された URL へ session.updated を送るかどうかを指定してください。 デフォルトではリクエストの送信を行います。

この設定が true の場合でも、 session_webhook.jsonl には session.updated のログが出力されます。

設定例

ignore_session_updated_webhook = false

ignore_session_vanished_webhook

デフォルト:

true

モードが block_new_session または block_new_connection の際に、 session_webhook_url に指定された URL に session.vanished リクエストを送るかどうか指定してください。

デフォルトではリクエストの送信を行いません。

この設定が true の場合でも、 session_webhook.jsonl には session.vanished のログが出力されます。

設定例

ignore_session_vanished_webhook = false

ignore_audio_streaming_webhook

デフォルト:

true

音声ストリーミング機能で音声が送信された場合に、 session_webhook_url に登録された URL に audio_streaming.started と audio_streaming.stopped リクエストを送るかどうかを指定してください。

デフォルトではリクエストの送信を行いません。

この設定が true の場合でも、 session_webhook.jsonl には audio_streaming.started と audio_streaming.stopped のログが出力されます。

設定例

ignore_audio_streaming_webhook = false

ignore_audio_streaming_failed_webhook

デフォルト:

true

音声ストリーミング機能利用時に、音声ストリーミング送り先から "type": "error" が送られてきたなどで、 正常に処理が行えなくなった場合に、 event_webhook_url に指定された URL に audio_streaming.failed リクエストを送るかどうかを指定してください。

この設定が true の場合でも、 event_webhook.jsonl には audio_streaming.failed のログが出力されます。

設定例

ignore_audio_streaming_failed_webhook = false

ignore_spotlight_changed_webhook

デフォルト:

true

スポットライト機能で発言者が切り替わった場合に、 event_webhook_url に登録された URL に spotlight.focused と spotlight.unfocused リクエストを送るかどうかを指定してください。

デフォルトではリクエストの送信を行いません。

この設定が true の場合でも、 event_webhook.jsonl には spotlight.focused と spotlight.unfocused のログが 出力されません 。

設定例

ignore_spotlight_changed_webhook = true

ignore_recording_started_webhook

デフォルト:

false

録画機能で、録画を開始した場合に、 event_webhook_url または session_webhook_url に登録された URL に recording.started リクエストを送るかどうかを指定してください。

デフォルトではリクエストの送信を行います。

この設定が true の場合でも、 event_webhook.jsonl または session_webhook.jsonl``には ``recording.started のログが出力されます。

設定例

ignore_recording_started_webhook = true

ignore_archive_started_webhook

デフォルト:

false

録画機能で、コネクションのアーカイブを開始した場合に、 イベントウェブフック event_webhook_url に登録された URL に archive.started リクエストを送信するかどうかを指定してください。

デフォルトではリクエストの送信を行います。

この設定が true の場合でも、 event_webhook.jsonl には archive.started のログが出力されます。

設定例

ignore_archive_started_webhook = true

ignore_split_archive_available_webhook

デフォルト:

false

録画機能で、分割録画を含む場合に分割した録画ファイルが利用可能になった際、 イベントウェブフック split-archive.available リクエストを送信するかどうかを指定してください。

デフォルトではリクエストの送信を行います。

この設定が true の場合でも、 event_webhook.jsonl には split-archive.available のログが出力されます。

設定例

ignore_split_archive_available_webhook = true

ignore_connection_rtc_webhook

デフォルト:

false

クライアントから RTC 統計情報が送られてきた際、 統計ウェブフック connection.rtc リクエストを stats_webhook_url に登録された URL に送信するかどうか指定してください。

デフォルトではリクエストの送信を行います。

ログの出力は stats_webhook_url をご確認ください。

設定例

ignore_connection_rtc_webhook = true

archive_dir

デフォルト:

archive

録画ファイルが保存されるディレクトリを指定してください。可能な限り 絶対パス で指定してください。

設定例

archive_dir = /path/to/archive

注意

archive_dir と archive_tmp_dir は違うディレクトリを指定してください

archive_tmp_dir

デフォルト:

tmp/archive

録画に使用する一時ファイルを保存するディレクトリを指定してください。可能な限り 絶対パス で指定してください。

重要

録画が失敗した場合には、このディレクトリに保存されたファイルは自動的に削除されません。 そのため録画失敗時には一時ファイルが残り続けます。

設定例

archive_tmp_dir = /path/to/tmp/archive

注意

archive_dir と archive_tmp_dir は違うディレクトリを指定してください

default_recording_format

デフォルト:

webm

録画ファイルのデフォルトのフォーマットを指定してください。 webm と mp4 が指定できます。

設定例

default_recording_format = mp4

default_recording_mp4_pli_interval

デフォルト:

20 s

範囲:

1..240 s

録画機能(セッション単位) 利用時に MP4 形式を利用した場合、クライアントへ送るキーフレーム要求 (PLI) の間隔を指定してください。

設定例

default_recording_mp4_pli_interval = 100 s

recording_max_expire_time

デフォルト:

86400 s

範囲:

1..86400 s

録画時に指定する expire_time の最大値を指定してください。

設定例

recording_max_expire_time = 10 min

recording_max_split_duration

デフォルト:

86400 s

範囲:

1..86400 s

録画で分割または一括＆分割録画時に split_duration の最大値を指定してください。

設定例

recording_max_split_duration = 10 min

recording_expire_time_required

デフォルト:

false

重要

この設定は一括録画時に録画ファイルが大きくなりすぎるのを防ぐための設定です。

録画で一括または一括＆分割録画時に expire_time の指定を必須にするかどうかを指定してください。

設定例

recording_expire_time_required = true

recording_dual_output

デフォルト:

true

録画で一括＆分割録画を利用できるようにするかどうかを指定してください。

重要

この設定が false になっている際に一括＆分割録画をしようとするとエラーになります

設定例

recording_dual_output = false

signaling_port

デフォルト:

5000

シグナリングに使用するポート番号を指定してください。

設定例

signaling_port = 5000

signaling_loopback_address_only

デフォルト:

false

シグナリングへのアクセスをループバックアドレスからのみに制限します。可能な限り有効にしてください。

設定例

signaling_loopback_address_only = true

signaling_normal_close_reason

デフォルト:

true

正常切断時の reason に切断理由を含むかどうかを指定してください。 false を指定した場合は空文字 "" が含まれるようになります。

設定例

signaling_normal_close_reason = false

signaling_notify

デフォルト:

true

シグナリング経由で接続や切断、更新の通知を受け取るかどうか指定してください。この設定はすべての設定に影響します。 個別の設定の場合は認証ウェブフックのレスポンス時で指定してください。

シグナリング経由での通知機能の詳細は シグナリング通知機能 をご確認ください

認証の戻り値に関しては 認証ウェブフックの戻り値での指定 を確認してください。

設定例

signaling_notify = true

signaling_notify_session_id

デフォルト:

true

シグナリング通知機能が有効な際、通知にセッション ID を含むかどうかを指定してください。

設定例

signaling_notify_session_id = true

signaling_notify_client_id

デフォルト:

true

シグナリング通知機能が有効な際、通知にクライアント ID を含むかどうかを指定してください。

設定例

signaling_notify_client_id = true

signaling_notify_bundle_id

デフォルト:

true

シグナリング通知機能が有効な際、通知にバンドル ID を含むかどうかを指定してください。

設定例

signaling_notify_bundle_id = true

signaling_notify_connection_id

デフォルト:

true

シグナリング通知機能が有効な際、通知にコネクション ID を含むかどうかを指定してください。

設定例

signaling_notify_connection_id = true

signaling_notify_connection_created_timestamp

デフォルト:

true

シグナリング通知機能が有効な際、"event_type": "connection.created" に timestamp を含むかどうかを指定してください。

設定例

signaling_notify_connection_created_timestamp = true

signaling_notify_media

デフォルト:

true

シグナリング通知機能が有効な際、通知に音声や映像が有効かどうかを含むかどうかを指定してください。

設定例

signaling_notify_media = true

signaling_notify_metadata

デフォルト:

true

シグナリング通知機能が有効な際、 "type": "connect" の signaling_notify_metadata で指定した値、 または認証ウェブフックの戻り値の signaling_notify_metadata で指定した値を通知するかどうかを指定してください。

設定例

signaling_notify_metadata = true

signaling_notify_metadata_ext

デフォルト:

false

シグナリング通知メタデータ拡張機能を有効にするかどうかを指定してください。 シグナリング通知機能が無効でも通知されないだけで API は利用できます。

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

設定例

signaling_notify_metadata_ext = true

signaling_notify_authn_metadata_max_size

デフォルト:

64512

範囲:

0..1048576

注釈

この設定を 0 にすることでクライアントからシグナリング通知メタデータを指定できなくなります。

クライアントから接続時に送られてくるシグナリング通知メタデータの最大サイズをバイト単位で指定してください。

設定例

signaling_notify_authn_metadata_max_size = 64512

signaling_notify_network

デフォルト:

true

シグナリング通知機能が有効な際、ネットワークの状態を通知するかどうかを指定してください。

設定例

signaling_notify_network = true

signaling_notify_rtp_stream

デフォルト:

true

シグナリング通知機能が有効な際、 RTP ストリームの停止と再開の状態を通知するかどうかを指定してください。

設定例

signaling_notify_rtp_stream = true

signaling_notify_recording

デフォルト:

true

シグナリング通知機能が有効な際、 録画の開始と停止の状態を通知するかどうかを指定してください。

設定例

signaling_notify_recording = true

signaling_notify_forwarding_filter

デフォルト:

true

シグナリング通知機能が有効な際、 転送フィルターのブロック開始とブロック解除の通知をするかどうかを指定してください。

設定例

signaling_notify_forwarding_filter = true

signaling_notify_audio_streaming_failed

デフォルト:

false

シグナリング通知機能が有効な際、音声ストリーミングサーバーへの接続が失敗した際にチャネル参加者全員に通知をするかどうかを指定してください。

設定例

signaling_notify_audio_streaming_failed = true

signaling_notify_ice_connection_state

デフォルト:

false

シグナリング通知機能が有効な際、 ICE 接続の状態を自分を含む同一セッションに参加しているクライアント全員に通知するかどうかを指定してください。

設定例

signaling_notify_ice_connection_state = true

signaling_vp9_params

デフォルト:

false

シグナリングで VP9 のパラメーターを指定できるようにするかを指定してください。

設定例

signaling_vp9_params = true

signaling_av1_params

デフォルト:

false

シグナリングで AV1 のパラメーターを指定できるようにするかを指定してください。

設定例

signaling_av1_params = true

signaling_h264_params

デフォルト:

false

シグナリングで H.264 のパラメーターを指定できるようにするかを指定してください。

設定例

signaling_h264_params = true

signaling_h265_params

デフォルト:

false

シグナリングで H.265 のパラメーターを指定できるようにするかを指定してください。

設定例

signaling_h265_params = true

signaling_bundle_id

デフォルト:

false

シグナリングでバンドル ID を指定できるようにするかを指定してください。

設定例

signaling_bundle_id = true

copy_websocket_signaling_header_names

デフォルト:

未指定

ウェブフックやログにコピーしたい WebSocket シグナリングの HTTP ヘッダー名を指定してください。 ヘッダー名は複数指定することができます。ヘッダー名はカンマ区切りで指定してください。

ウェブフックの場合は HTTP ヘッダー にコピーされます。ログの場合は copy_headers 項目にコピーされます。

設定例

copy_websocket_signaling_header_names = X-Forwarded-For, X-Real-IP, Tracestate

ヘッダーがコピーされるウェブフック

• 認証ウェブフック

copy_headers が出力されるログ

• auth_webhook.jsonl

• auth_webhook_error.jsonl

• rtc_stats.jsonl

• connection.jsonl

websocket_signaling_ping_interval

単位指定必須

デフォルト:

5 s

範囲:

5..300 s

WebSocket 経由のシグナリングの場合に、サーバーからクライアントへネットワーク死活監視のために "type": "ping" を送信する間隔を指定してください。

重要

ここで指定する値は websocket_signaling_pong_timeout より短くしてください。

設定例

websocket_signaling_ping_interval = 5 s

websocket_signaling_pong_timeout

単位指定必須

デフォルト:

60 s

範囲:

60..600 s

WebSocket 経由のシグナリングの場合に、クライアントから返却される "type": "pong" のタイムアウト時間を指定してください。 この時間内に "type": "pong" が返却されない場合はサーバーから接続を切断します。

重要

ここで指定する値は websocket_signaling_ping_interval より長くしてください。

設定例

websocket_signaling_pong_timeout = 60 s

websocket_stats_timer_interval

単位指定必須

デフォルト:

60 s

範囲:

5..600 s

WebSocket 経由のシグナリングの場合に、サーバーからクライアントに統計情報の送信を要求する "stats": true を設定する間隔を指定してください。

設定例

websocket_stats_timer_interval = 60 s

default_data_channel_signaling

注意

この機能を本番環境で利用する場合は事前にサポートまでご連絡ください

デフォルト:

false

シグナリング経路を WebSocket から DataChannel に切り替えるかどうかを指定してください。

設定例

default_data_channel_signaling = false

data_channel_signaling_close_message

デフォルト:

false

Sora から DataChannel シグナリングを切断する際に "type": "close" メッセージを送信するかどうかを指定してください。

設定例

data_channel_signaling_close_message = true

default_ignore_disconnect_websocket

注意

この機能を本番環境で利用する場合は事前にサポートまでご連絡ください

デフォルト:

false

シグナリング経路を DataChannel に切り替えた際に WebSocket が切断されても接続の切断と判断しないかどうかを指定してください。

設定例

default_ignore_disconnect_websocket = false

data_channel_messaging

注意

この機能を本番環境で利用する場合は事前にサポートまでご連絡ください

デフォルト:

false

DataChannel を使用したメッセージング機能を利用するかどうかを指定してください。

設定例

data_channel_messaging = false

data_channel_messaging_only

注意

この機能を本番環境で利用する場合は事前にサポートまでご連絡ください

デフォルト:

false

DataChannel メッセージングの利用時に、音声と映像を false にした場合でも接続できるようにするかどうかを指定してください。

設定例

data_channel_messaging_only = false

data_channel_stats_timer_interval

単位指定必須

デフォルト:

60 s

範囲:

5..600 s

シグナリング経路を DataChannel に切り替えた際にクライアントへの統計情報を要求する間隔を指定してください。

設定例

data_channel_stats_timer_interval = 60 s

data_channel_stats_max_retransmits

注意

この設定を利用する場合は事前にサポートまでご連絡ください

デフォルト:

指定なし

範囲:

0..8

シグナリング経路を DataChannel に切り替えた際にクライアントが統計情報を送信するときのメッセージの再送回数を指定してください。

設定例

data_channel_stats_max_retransmits = 1

whip

デフォルト:

false

OBS の WHIP 形式のシグナリングを有効にするかどうか指定してください。

設定例

whip = true

whip_bearer_token_metadata_key

デフォルト:

指定なし

OBS の WHIP 形式のシグナリング時の Authentication ヘッダーに含まれるトークンを、メタデータとして送信する際のキーを指定してください。

設定例

whip_bearer_token_metadata_key = access_token

whip_turn

重要

この設定は 2025 年 6 月リリース予定の Sora にてデフォルト true になり、 2025 年 12 月リリース予定の Sora にて廃止します。

デフォルト:

false

OBS の WHIP/WebRTC で TURN 経由で配信するかどうかを指定してください。

設定例

whip_turn = true

whep

注意

この設定を利用する場合は事前にサポートまでご連絡ください

デフォルト:

false

OBS の WHEP 形式のシグナリングを有効にするかどうか指定してください。

設定例

whep = true

whep_bearer_token_metadata_key

注意

この設定を利用する場合は事前にサポートまでご連絡ください

デフォルト:

指定なし

OBS の WHEP 形式のシグナリング時の Authentication ヘッダーに含まれるトークンを、メタデータとして送信する際のキーを指定してください。

設定例

whep_bearer_token_metadata_key = access_token

whep_turn

注意

この設定を利用する場合は事前にサポートまでご連絡ください

デフォルト:

false

OBS の WHEP/WebRTC で TURN 経由で配信するかどうかを指定してください。

設定例

whep_turn = true

api_port

デフォルト:

3000

API に使用するポート番号を指定してください。

設定例

api_port = 3000

api_loopback_address_only

デフォルト:

false

API へのアクセスをループバックアドレスからのみに制限します。可能な限り有効にしてください。

設定例

api_loopback_address_only = true

api_cors_origin

デフォルト:

指定なし

API の戻りのヘッダーに CORS (Cross-Origin Resource Sharing) を含める際のドメインを指定してください。 http から始めて、パスの / は含まないでください。

設定例

api_cors_origin = http://127.0.0.1:5000

turn

デフォルト:

true

注意

この機能を false にする場合は事前にサポートまでご連絡ください

使用しない場合の設定

設定例

turn = false

turn_realm

デフォルト:

"sora-turn.example.com"

TURN 機能で使用するレルムを指定してください。 文字列であれば何でも良いのですが、会社のドメインなどを指定することをおすすめします。

設定例

turn_realm = sora-turn.example.com

turn_fqdn

デフォルト:

なし

TURN 機能の URL で使用する FQDN (最後の . なし) を指定してください。

指定した場合は TURN-UDP, TURN-TCP, TURN-TLS に共通で採用されます。 TURN-TLS の FQDN は turn_tls_fqdn 設定で上書きできます。

ドメイン名が sora-turn.example.com の場合

設定例

turn_fqdn = sora-turn.example.com

turn_tls_fqdn

TURN 機能で TURN-TLS の URL で使用する FQDN (最後の . なし) を指定してください。

指定しない場合は turn_fqdn の値が採用されます。 どちらも設定されていない場合 TURN-TLS を利用することはできません。

ドメイン名が sora.example.com の場合

設定例

turn_tls_fqdn = sora-turn.example.com

turn_tcp

デフォルト:

true

TURN 機能で TURN-TCP を使用するかどうかを指定してください。使用しない場合は false を指定してください。

使用しない場合の設定

設定例

turn_tcp = false

turn_tcp_allocate_success_delay_time

デフォルト:

100 ms

範囲:

0..1 s

TURN 機能で TURN-TCP 時の Allocate-Success を返す時間を遅らせます。

設定例

turn_tcp_allocate_success_delay_time = 100 ms

turn_tcp_listen_port

デフォルト:

3478

TURN 機能で TURN-TCP を有効にした際に使用するポート番号を指定してください。デフォルトでは 3478 番ポートが使用されます。

設定例

turn_tcp_listen_port = 3478

turn_tcp_port

デフォルト:

turn_tcp_listen_port の値を利用

TURN 機能で TURN-TCP URL 払い出し時のポート番号を指定してください。デフォルトでは turn_tcp_listen_port の値が利用されます。

設定例

turn_tcp_port = 3478

turn_tcp_only

デフォルト:

false

危険

この機能はあくまで検証時のみ有効にしてください

TURN-TCP を強制的に利用するようになります。この機能を有効にした場合 warning ログが出力されます。

検証する場合

turn_tcp_only = true

turn_tls

デフォルト:

false

TURN 機能で TURN-TLS の URL 払い出し機能を使用するかどうかを指定してください。使用しない場合は false を指定してください。

設定例

turn_tls = true

turn_tls_port

デフォルト:

5349

TURN 機能で TURN-TLS の URL 払い出し機能を有効にした際に使用するポート番号を指定してください。デフォルトでは 5349 番ポートが使用されます。

設定例

turn_tls_port = 443

turn_tls_only

デフォルト:

false

危険

この機能はあくまで検証時のみ有効にしてください

TURN-TLS を強制的に利用するようになります。この機能を有効にした場合 warning ログが出力されます。

検証する場合

turn_tls_only = true

rtx

注意

この設定を無効にする場合は事前にサポートまでご連絡ください

デフォルト:

true

RTX を有効にするかどうかを指定してください。デフォルトでは true で有効になっています。

現時点では Chrome / Safari / Edge / Firefox が使用できます。 iOS / Android / Unity は libwebrtc の最新版を利用している場合は対応しています。

設定例

rtx = false

ulpfec

注意

この設定を有効にする場合は事前にサポートまでご連絡ください

デフォルト:

false

ULPFEC を有効にするかどうかを指定してください。デフォルトでは無効になっています。

現時点では Chrome と Safari が使用でき、 Firefox は対応しておりません。 iOS/Android は libwebrtc を使用した場合は対応しています。

設定例

ulpfec = false

audio_red

注意

この設定を有効にする場合は事前にサポートまでご連絡ください

デフォルト:

false

音声冗長化を有効にするかどうかを指定してください。デフォルトでは無効になっています。

現時点では Chrome M95 以降で使用できます。非対応ブラウザが混在していても利用できます。

設定例

audio_red = true

generic_nack

注意

この設定を無効にする場合は事前にサポートまでご連絡ください

デフォルト:

true

Generic NACK を有効にするかどうかを指定してください。一つのチャネルに対して、 視聴者がかなり多い場合などはこの設定を無効にすることで、サーバー側の負荷を抑えることができるようになります。

設定例

generic_nack = true

default_audio_bit_rate

設定しないことをおすすめします

単位:

k(キロ)bps

範囲:

6..510

デフォルト:

指定なし

音声が使用できるビットレートを指定してください。デフォルトの場合はブラウザ側の判断に依存します。

設定例

default_audio_bit_rate = 32

default_video_bit_rate

デフォルト:

500

単位:

k(キロ)bps

範囲:

1..50000

映像が使用できるビットレートを指定してください。デフォルトでは 500kbps です。この値を少なく指定すると解像度が不安定になります。

基本は 500 で余裕があるのであれば 800 などに設定することをお勧めします。

15000 より大きい値はまだ十分に検証ができていないため、現時点ではサポート外となります。ご了承ください。

設定例

default_video_bit_rate = 500

default_vp9_param_profile_id

デフォルト:

0

範囲:

0..3

VP9 で利用するプロファイル ID のデフォルト値を指定してください。

設定例

default_vp9_param_profile_id = 0

default_av1_param_profile

デフォルト:

0

範囲:

0..2

AV1 で利用するプロファイルのデフォルト値を指定してください。

設定例

default_av1_param_profile = 0

default_h264_param_profile_level_id

デフォルト:

42e02a

H.264 で利用するプロファイルレベル ID のデフォルト値を文字列で指定してください。

設定例

default_h264_param_profile_level_id = 42e02a

default_h265_param_level_id

重要

2024 年 12 月 現在、このプロファイルを利用できる WebRTC クライアントが存在しません。

デフォルト:

93

範囲:

0..255

H.265 で利用するレベル ID のデフォルト値を数値で指定してください。

設定例

default_h265_param_level_id = 93

default_simulcast_rid

デフォルト:

r0

サイマルキャスト利用時に、視聴する rid を指定せずに接続した場合に採用される rid の値を指定してください。

デフォルトでは r0 になっています。

r1 または r2 にすることもできます。

設定例

default_simulcast_rid = r0

simulcast_encodings_file

デフォルト:

なし

サイマルキャストで利用するエンコーディングパラメーターのカスタマイズを JSON 形式のファイルで指定してください。

詳細は 映像のエンコーディングパラメーターのカスタマイズ をご確認ください。

設定例

simulcast_encodings_file = etc/simulcast_encodings.json

simulcast_multicodec

注意

この設定を利用する場合は事前にサポートまでご連絡ください

デフォルト:

false

サイマルキャストマルチコーデックを有効にするかどうかを指定してください。

設定例

simulcast_multicodec = true

simulcast_codecs_file

注意

この設定を利用する場合は事前にサポートまでご連絡ください

デフォルト:

なし

サイマルキャストマルチコーデックで利用するコーデックパラメーターのカスタマイズを JSON 形式のファイルで指定してください。

詳細は サイマルキャストマルチコーデックのデフォルト値を変更する をご確認ください。

設定例

simulcast_codecs_file = etc/simulcast_codecs.json

default_forwarding_pli_interval

注意

この設定を利用する場合は事前にサポートまでご連絡ください

単位指定必須

デフォルト:

10 s

範囲:

1..90 s

RTP 転送 API 利用時に、クライアントに対して PLI を送る間隔を指定してください。

設定例

default_forwarding_pli_interval = 10 s

録画機能併用時には、 20 s より大きな値を指定したとしても、録画機能の PLI 送信間隔 20 s が適用されます。

もし default_forwarding_pli_interval に 20 s より小さな値を指定した場合は、 PLI 送信間隔には default_forwarding_pli_interval の値が適用されます。

録画機能の利用を継続し、RTP 転送機能を停止したタイミングで、 録画機能の PLI 送信間隔 20 s が適用されます。

forwarding_simulcast

注意

この設定を利用する場合は事前にサポートまでご連絡ください

単位指定必須

デフォルト:

single

RTP 転送 API 利用時にサイマルキャストの転送オプションを指定してください。

• single は最も優先度の低いストリームのみを転送します

• all はすべてのストリームを転送します

設定例

forwarding_simulcast = all

signaling_forwarding_filters

デフォルト:

false

転送フィルターをシグナリング接続時に設定できるかどうかを指定してください。

設定例

signaling_forwarding_filters = true

signaling_forwarding_filter

注意

この設定は 2025 年 12 月に廃止します。 signaling_forwarding_filters を利用してください

デフォルト:

false

転送フィルターをシグナリング接続時に設定できるかどうかを指定してください。

設定例

signaling_forwarding_filter = true

audio_streaming_url

デフォルト:

指定なし

統計コレクターの URL を指定してください。 http を指定した場合は HTTP/2 (h2c) で送られます。 https の場合は HTTP/2 (h2) で送られます。

統計コレクターは HTTP/2 に対応している必要があります。

HTTP 設定例

audio_streaming_url = http://192.0.2.10:48080/speech

HTTPS 設定例

audio_streaming_url = https://suzu.example.com/speech

audio_streaming_header

デフォルト:

false

音声ストリーミングヘッダーを有効にするかどうかを指定してください。

設定例

audio_streaming_header = true

default_audio_streaming_result_push

デフォルト:

true

音声ストリーミングゲートウェイからのレスポンスをシグナリングプッシュ通知で送ることをデフォルトで行うかを指定してください。

設定例

default_audio_streaming_result_push = true

default_audio_streaming_language_code

デフォルト:

指定なし

音声ストリーミングゲートウェイ接続時に HTTP ヘッダー sora-audio-streaming-language-code にデフォルトで含める文字列を指定してください。

この設定がない場合、接続時に audio_streaming_language_code で文字列が指定されていない場合、 音声ストリーミングが有効になっても Sora は接続の音声ストリーミングを開始しません。

設定例

default_audio_streaming_language_code = ja-JP

audio_streaming_max_retries

デフォルト:

0

音声ストリーミングゲートウェイへの接続が失敗した場合の最大リトライ回数を指定してください。

リトライが発生するのは、 この値と audio_streaming_retry_interval が 0 以外が指定されており、 音声ストリーミングゲートウェイへの接続確立が失敗、または音声ストリーミングゲートウェイが 5xx 系でエラーを返した場合です。

設定例

audio_streaming_max_retries = 3

audio_streaming_retry_interval

デフォルト:

5 s

音声ストリーミングゲートウェイへの接続が失敗した場合のリトライ間隔を指定してください。

設定例

audio_streaming_retry_interval = 10 s

audio_streaming_tls_fullchain_file

注意

この設定を利用する場合は事前にサポートまでご連絡ください

デフォルト:

指定なし

音声ストリーミングゲートウェイとの通信に HTTPS で mTLS を利用するための設定で、 中間証明書を含むクライアント証明書を PEM 形式で設定してください。

設定例

audio_streaming_tls_fullchain_file = /path/to/fullchain.pem

audio_streaming_tls_privkey_file

注意

この設定を利用する場合は事前にサポートまでご連絡ください

デフォルト:

指定なし

音声ストリーミングゲートウェイとの通信に HTTPS で mTLS を利用するための設定で、 クライアント証明書の秘密鍵を PEM 形式で設定してください。

重要

秘密鍵にはパスフレーズが設定されている場合エラーとなります

設定例

audio_streaming_tls_privkey_file = /path/to/privkey.pem

audio_streaming_tls_verify_cacert_file

注意

この設定を利用する場合は事前にサポートまでご連絡ください

デフォルト:

指定なし

音声ストリーミングゲートウェイとの通信に HTTPS を利用した際、サーバー証明書のチェックを行う CA ファイルを PEM 形式で設定してください。

設定例

audio_streaming_tls_verify_cacert_file = /path/to/server_cacert.pem

重要

この設定がない場合、 OS 組み込みのルート CA 証明書を利用してサーバー証明書をチェックします。 OS 組み込みのルート CA 証明書については ウェブフックリクエストなどの送信先サーバー証明書の検証に利用する OS 組み込みのルート CA 証明書について をご確認ください。

recycle_media_section

デフォルト:

true

SDP でアクティブではなくなったメディアセクション （m=） を再利用する機能を有効化するかどうかを指定してください。

設定例

recycle_media_section = false

hide_origin_username

デフォルト:

false

有効にした場合は SDP の Offer 時に送られる o=<username> の username の部分を shiguredo...SORA-<version> から _ に変更します。

設定例

hide_origin_username = false

connection_created_wait_timeout

単位指定必須

デフォルト:

30 s

範囲:

0..600 s

WebRTC SFU と WebRTC の接続が確立するまでの許容時間を指定してください。 基本的に WebRTC SFU との接続確立は数百ミリ秒で終わります。

ただし iOS などでカメラの使用などを許可するといった設定が入る場合を考慮しデフォルトは 30 秒としています。

設定例

connection_created_wait_timeout = 30 s

注釈

値を 0 s にすることで、意図的に connection_created_wait_timeout のエラーを発生させることができます。

default_spotlight_focus_rid

デフォルト:

r1

指定できる rid:

none / r0 / r1 / r2

スポットライト機能利用時に、フォーカスした際に利用する rid を指定してください。

none は映像自体を配信しません。

設定例

default_spotlight_focus_rid = r1

default_spotlight_unfocus_rid

デフォルト:

r0

範囲:

none, r0, r1, r2

スポットライト機能利用時に、フォーカスなしで利用する rid を指定してください。

none は映像自体を配信しません。

設定例

default_spotlight_unfocus_rid = none

default_spotlight_unfocus_audio

デフォルト:

true

スポットライト機能利用時に、フォーカスなしでの音声配信を指定してください。

設定例

default_spotlight_unfocus_audio = false

default_spotlight_unfocus_audio_rate_limit

デフォルト:

2

範囲:

0..5

スポットライト機能利用時に、フォーカスなしの音声転送の上限レートを指定してください。

単位は 1 音声ストリーム = 50 packets / s となります。

設定例

default_spotlight_unfocus_audio_rate_limit = 2

default_spotlight_delayed_focus

デフォルト:

true

スポットライト機能利用時に、遅延フォーカスの有無を指定してください。

遅延フォーカスは音声が有効になってもすぐにフォーカスせず、一定時間音声が有効な際に初めてフォーカスする仕組みです。

設定例

default_spotlight_delayed_focus = true

default_spotlight_delayed_focus_interval

デフォルト:

2000 ms

範囲:

1..60000 ms

スポットライト機能利用時に、遅延フォーカスが有効な際に、どの程度遅延をさせるか指定してください。

設定例

default_spotlight_delayed_focus_interval = 2000 ms

default_spotlight_auto_unfocus

デフォルト:

true

スポットライト機能利用時の自動アンフォーカスの有無を指定してください。

設定例

default_spotlight_auto_unfocus = true

default_spotlight_auto_unfocus_interval

デフォルト:

10 s

範囲:

1 ms 以上 30 s 以下

スポットライト機能の自動アンフォーカスの時間間隔を指定してください。

設定例

default_spotlight_auto_unfocus_interval = 10 s

default_spotlight_focus_min_interval

デフォルト:

2000 ms

範囲:

0 ms 以上 60 s 以下

スポットライト機能でフォーカスしてからアンフォーカスされるまでの最低時間間隔を指定してください。

設定例

default_spotlight_focus_min_interval = 2000 ms

default_spotlight_number

デフォルト:

1

範囲:

1..8

スポットライトで同時にフォーカスされるデフォルトの数を指定してください。

設定例

default_spotlight_number = 2

spotlight_encodings_file

デフォルト:

なし

スポットライトで利用するエンコーディングパラメーターのカスタマイズを JSON 形式のファイルで指定してください。

詳細は スポットライト利用時の映像のエンコーディングパラメーターのカスタマイズ をご確認ください。

設定例

spotlight_encodings_file = etc/spotlight_encodings.json

multistream_auto_sharing_video_bit_rate

デフォルト:

true

マルチストリームで配信者が利用する映像ビットレートを自動で共有する機能です。

映像のビットレートに 1000kbps を指定した場合 4 人の配信者がいる場合はそれぞれの配信者のビットレートは 250kbps になります。

設定例

multistream_auto_sharing_video_bit_rate  = true

default_rtc_stats

デフォルト:

true

Sora から SDK やクライアントへ RTC 統計情報を要求するかどうかを指定してください。 SDK やクライアント側がシグナリングの "type": "stats" に対応している必要があります。

設定例

default_rtc_stats = true

rtc_stats_log

デフォルト:

false

SDK やクライアントから送られてきた RTC 統計情報をログとして保存するかどうかを指定してください。 デフォルトではログは保存されません。

警告

ログはかなりの量になるため、利用する際は注意してください

設定例

rtc_stats_log = true

user_agent_stats

注意

この設定は 2025 年 6 月に廃止します。 default_rtc_stats を利用してください。

デフォルト:

true

Sora から SDK やクライアントへ RTC 統計情報を要求するかどうかを指定してください。 SDK やクライアント側がシグナリングの "type": "stats" に対応している必要があります。

設定例

user_agent_stats = true

ice_connection_state_disconnected_timeout

注意

この設定を利用する場合は事前にサポートまでご連絡ください

デフォルト:

5 s

範囲:

1..300 s

ICE コネクションステートが checking から disconnected の状態に移行するまでの時間を指定してください。

設定例

ice_connection_state_disconnected_timeout = 5 s

ice_connection_state_failed_timeout

注意

この設定を利用する場合は事前にサポートまでご連絡ください

デフォルト:

10 s

範囲:

1..300 s

ICE コネクションステートが disconnected から failed の状態に移行するまでの時間を指定してください。

設定例

ice_connection_state_failed_timeout = 10 s

skip_redact_sensitive_data

デフォルト:

false

ログファイル中のセンシティブなデータを "REDACTED" という文字列に書き換えて出力する処理をスキップします。

設定例

skip_redact_sensitive_data = true

センシティブなデータを書き換える対象は以下のとおりです。

• auth_webhook.jsonl の event_metadata を "REDACTED" に書き換えます

• session_webhook.jsonl の session_metadata と event_metadata を "REDACTED" に書き換えます

• event_webhook.jsonl の event_metadata を "REDACTED" に書き換えます

stats_collector_url

注意

この設定は 2025 年 6 月に廃止します。

注意

この設定を利用する場合は事前にサポートまでご連絡ください

デフォルト:

指定なし

統計コレクターの URL を指定してください。 http を指定した場合は HTTP/2 (h2c) で送られます。 https の場合は HTTP/2 (h2) で送られます。

統計コレクターは HTTP/2 に対応している必要があります。

HTTP 設定例

stats_collector_url = http://192.0.2.10:5890/collector

HTTPS 設定例

stats_collector_url = https://kohaku.example.com/collector

default_stats_exporter

注意

この設定は 2025 年 6 月に廃止します。

注意

この設定を利用する場合は事前にサポートまでご連絡ください

デフォルト:

true

stats_collector_url に URL が指定されている場合に、 統計エクスポーターをデフォルトで有効にするかどうかを指定してください。

この設定を false にした場合に、統計エクスポーターを有効にするには、 認証成功時の払い出しで "stats_exporter": true を払い出す必要があります。

HTTPS 設定例

default_stats_exporter = true

stats_exporter_number

注意

この設定は 2025 年 6 月に廃止します。

注意

この設定を利用する場合は事前にサポートまでご連絡ください

デフォルト:

5

統計エクスポーターの数を指定してください。同時接続数が多くなった場合増やすことを検討してください。

設定例

stats_exporter_number = 10

stats_exporter_tls_fullchain_file

注意

この設定は 2025 年 6 月に廃止します。

注意

この設定を利用する場合は事前にサポートまでご連絡ください

デフォルト:

指定なし

統計コレクターサーバーとの通信に HTTPS で mTLS を利用するための設定で、 中間証明書を含むクライアント証明書を PEM 形式で設定してください。

設定例

stats_exporter_tls_fullchain_file = /path/to/fullchain.pem

stats_exporter_tls_privkey_file

注意

この設定は 2025 年 6 月に廃止します。

注意

この設定を利用する場合は事前にサポートまでご連絡ください

デフォルト:

指定なし

統計コレクターサーバーとの通信に HTTPS で mTLS を利用するための設定で、 クライアント証明書の秘密鍵を PEM 形式で設定してください。

重要

秘密鍵にはパスフレーズが設定されている場合エラーとなります

設定例

stats_exporter_tls_privkey_file = /path/to/privkey.pem

stats_exporter_tls_verify_cacert_file

注意

この設定は 2025 年 6 月に廃止します。

注意

この設定を利用する場合は事前にサポートまでご連絡ください

デフォルト:

指定なし

統計コレクターサーバーとの通信に HTTPS を利用した際、サーバー証明書のチェックを行う CA ファイルを PEM 形式で設定してください。

設定例

stats_exporter_tls_verify_cacert_file = /path/to/server_cacert.pem

重要

この設定がない場合、 OS 組み込みのルート CA 証明書を利用してサーバー証明書をチェックします。 OS 組み込みのルート CA 証明書については ウェブフックリクエストなどの送信先サーバー証明書の検証に利用する OS 組み込みのルート CA 証明書について をご確認ください。

node_name

デフォルト:

指定なし

クラスター機能で利用するノード名を指定してください。

ノード名の @ の前には、正規表現 [0-9A-Za-z_\\-]+ にマッチする文字列を指定してください。 また @ の後ろには、サーバーのドメイン名（FQDN）や、IP アドレスを指定してください。

設定例

node_name = [email protected]

cluster

デフォルト:

false

クラスター機能を利用するかどうかを指定してください。

設定例

cluster = true

cluster_temporary_node

デフォルト:

false

テンポラリーノードとして利用するかどうかを指定してください。

設定例

cluster_temporary_node = true

cluster_relay

注意

この機能を利用するには 最大ノード数ライセンス が必要です。

デフォルト:

true

クラスターリレー機能を利用するかどうかを指定してください。

設定例

cluster_relay = true

default_cluster_affinity

注意

この機能を利用するには 最大ノード数ライセンス が必要です。

デフォルト:

true

クラスターリレー機能利用時にアフィニティ機能を利用するかどうかのデフォルト値を指定してください。

設定例

default_cluster_affinity = true

cluster_affinity_threshold

注意

この設定を利用する場合は事前にサポートまでご連絡ください

デフォルト:

10

範囲:

1..10000

クラスターのリレー機能とアフィニティ機能が有効な場合、 別ノードにセッションを作成するノード単位の同一セッションに対する同時接続数の基準値を指定してください。

設定例

cluster_affinity_threshold = 50

external_signaling_url

デフォルト:

指定なし

ノードに対するシグナリング URL を指定してください。クラスター機能のリダイレクト時に用います。

設定例

external_signaling_url = ws://127.0.0.1:5000/signaling

external_api_url

デフォルト:

指定なし

ノードに対する Sora API の URL を指定してください。クラスター機能のリダイレクト時に用います。

設定例

external_api_url = http://127.0.0.1:3000/

cluster_listen_min_port

注意

この設定を利用する場合は事前にサポートまでご連絡ください

デフォルト:

49010

sora.conf にクラスター利用時のノード間通信に使用するポート番号範囲の最小値を指定してください。

設定例

cluster_listen_min_port = 49010

cluster_listen_max_port

注意

この設定を利用する場合は事前にサポートまでご連絡ください

デフォルト:

49020

sora.conf にクラスター利用時のノード間通信に使用するポート番号範囲の最大値を指定してください。

設定例

cluster_listen_max_port = 49020

data_dir

注意

この設定を利用する場合は事前にサポートまでご連絡ください

デフォルト:

data

Sora 内部で利用する情報を書き出すディレクトリを指定してください。可能な限り 絶対パス で指定してください。

設定例

data_dir = /path/to/data

av1

デフォルト:

true

AV1 が利用できるようになります。

設定例

av1 = true

h265

デフォルト:

true

H.265 が利用できるようになります。

設定例

h265 = true

h264_b_frame

重要

2024 年 12 月 時点で Sora SDK では B-frame を利用する事はできません。

デフォルト:

false

H.264 で B-frame が利用できるようになります。

設定例

h264_b_frame = true

h265_b_frame

重要

2024 年 12 月 時点で Sora SDK では B-frame を利用する事はできません。

デフォルト:

false

H.265 で B-frame が利用できるようになります。

設定例

h265_b_frame = true

legacy_recording

デフォルト:

false

危険

この設定は 2025 年 12 月リリースの Sora にて廃止します

レガシー録画を利用するかどうかを指定してください。 false にすることでレガシー録画の API が利用できなくなります。

設定例

legacy_recording = false

legacy_recording を false にする際の注意点

クラスター機能利用時にレガシー録画の録画予約が存在する状態で、 legacy_recording を false にした場合でも、レガシー録画の録画予約は停止されません。

そのため、 legacy_recording を false にする際は、レガシー録画の録画予約を全て停止してください。

legacy_signaling_error

デフォルト:

false

危険

この設定は 2025 年 6 月リリースの Sora にて廃止します

Sora 2024.1.x までのシグナリングエラーログの出力方式を維持する設定です。

• false の場合は log/connection_created_wait_timeout にログが出力されなくなりました

• false の場合は log/signaling_error.jsonl にシグナリングエラーログが出力されるようになりました

• false の場合は connection.failed ウェブフックは 認証成功時 かつ connection.created が送信されていない場合のみ送信されるようになりました

• false の場合は sora.jsonl に認証失敗ログが出力されなくなりました

• false の場合は sora.jsonl にシグナリング失敗ログが出力されなくなりました

設定例

legacy_signaling_error = true

legacy_stream

デフォルト:

false

危険

この設定は 2025 年 6 月リリースの Sora にて廃止します

レガシーストリームを利用するかどうかを指定してください。 true にすることでレガシーストリームが利用できるようになります。

設定例

legacy_stream = true

rtp_hdrext_video_orientation

注意

この設定を利用する場合は事前にサポートまでご連絡ください

デフォルト:

false

RTP ヘッダー拡張 urn:3gpp:video-orientation を利用するかどうかを指定してください。

設定例

rtp_hdrext_video_orientation = true

rtp_hdrext_video_content_type

注意

この設定を利用する場合は事前にサポートまでご連絡ください

デフォルト:

false

RTP ヘッダー拡張 http://www.webrtc.org/experiments/rtp-hdrext/video-content-type を利用するかどうかを指定してください。

設定例

rtp_hdrext_video_content_type = true

rtp_hdrext_video_timing

注意

この設定を利用する場合は事前にサポートまでご連絡ください

デフォルト:

false

RTP ヘッダー拡張 http://www.webrtc.org/experiments/rtp-hdrext/video-timing を利用するかどうかを指定してください。

設定例

rtp_hdrext_video_timing = true

rtp_hdrext_playout_delay

デフォルト:

true

RTP ヘッダー拡張 http://www.webrtc.org/experiments/rtp-hdrext/playout-delay を利用するかどうかを指定してください。

設定例

rtp_hdrext_playout_delay = false

default_playout_delay_min_delay

デフォルト:

未指定

単位:

ms のみ

範囲:

0..40950

プレイアウト遅延機能を利用する際の最小値(ミリ秒)を指定してください。

設定例

default_playout_delay_min_delay = 0 ms
default_playout_delay_max_delay = 100 ms

default_playout_delay_max_delay

デフォルト:

未指定

単位:

ms のみ

範囲:

0..40950

プレイアウト遅延機能を利用する際の最大値(ミリ秒)を指定してください。

設定例

default_playout_delay_min_delay = 0 ms
default_playout_delay_max_delay = 100 ms

rtp_hdrext_color_space

注意

この設定を利用する場合は事前にサポートまでご連絡ください

デフォルト:

false

RTP ヘッダー拡張 http://www.webrtc.org/experiments/rtp-hdrext/color-space を利用するかどうかを指定してください。

設定例

rtp_hdrext_color_space = true

rtp_hdrext_sdes_mid

注意

この設定を利用する場合は事前にサポートまでご連絡ください

デフォルト:

false

RTP ヘッダー拡張 urn:ietf:params:rtp-hdrext:sdes:mid を利用するかどうかを指定してください。

設定例

rtp_hdrext_sdes_mid = true

rtp_hdrext_abs_capture_time

デフォルト:

false

RTP ヘッダー拡張 http://www.webrtc.org/experiments/rtp-hdrext/abs-capture-time を利用するかどうかを指定してください。

設定例

rtp_hdrext_abs_capture_time = true

rtp_hdrext_dependency_descriptor_vp9

警告

この設定を true にした場合、 Firefox で VP9 が利用できなくなります。

デフォルト:

false

RTP ヘッダー拡張 https://aomediacodec.github.io/av1-rtp-spec/#dependency-descriptor-rtp-header-extension を VP9 で利用するかどうかを指定してください。

設定例

rtp_hdrext_dependency_descriptor_vp9 = true

rtp_packet_loss_simulator_incoming

危険

この機能はあくまで検証時のみ有効にしてください

デフォルト:

0

範囲:

0..100

Sora が受信する RTP パケットを指定したパーセント分ドロップさせます。

値を 0 より大きくした場合、クライアントが接続するたびに warning が発生します。

Sora が受信する RTP パケットを 10 % パケロスさせる場合

設定例

rtp_packet_loss_simulator_incoming = 10

rtp_packet_loss_simulator_outgoing

危険

この機能はあくまで検証時のみ有効にしてください

デフォルト:

0

範囲:

0..100

Sora が送信する RTP パケットを指定したパーセント分ドロップさせます。

値を 0 より大きくした場合、クライアントが接続するたびに warning が発生します。

Sora が送信する RTP パケットを 10 % パケロスさせる場合

設定例

rtp_packet_loss_simulator_outgoing = 10

data_channel_packet_loss_simulator_incoming

危険

この機能はあくまで検証時のみ有効にしてください

デフォルト:

0

範囲:

0..100

Sora が受信する DataChannel パケットを指定したパーセント分ドロップさせます。

値を 0 より大きくした場合、クライアントが接続するたびに warning が発生します。

Sora が受信する DataChannel パケットを 10 % パケロスさせる場合

設定例

data_channel_packet_loss_simulator_incoming = 10

data_channel_packet_loss_simulator_outgoing

危険

この機能はあくまで検証時のみ有効にしてください

デフォルト:

0

範囲:

0..100

Sora が送信する DataChannel パケットを指定したパーセント分ドロップさせます。

値を 0 より大きくした場合、クライアントが接続するたびに warning が発生します。

Sora が送信する DataChannel パケットを 10 % パケロスさせる場合

設定例

data_channel_packet_loss_simulator_outgoing = 10

ignore_turn_five_tuple

注意

この設定を利用する場合は事前にサポートまでご連絡ください

デフォルト:

false

TURN 利用時に送られてくるパケットの 5-TUPLE を無視するかどうかを指定してください。

設定例

ignore_turn_five_tuple = true

opus_param_channels

注意

この設定を利用する場合は事前にサポートまでご連絡ください

デフォルト:

2

範囲:

1..8

opus_param_maxplaybackrate

注意

この設定を利用する場合は事前にサポートまでご連絡ください

デフォルト:

48000

範囲:

8000..48000

opus_param_stereo

注意

この設定を利用する場合は事前にサポートまでご連絡ください

デフォルト:

true

opus_param_sprop_stereo

注意

この設定を利用する場合は事前にサポートまでご連絡ください

デフォルト:

true

opus_param_ptime

注意

この設定を利用する場合は事前にサポートまでご連絡ください

デフォルト:

20

範囲:

3..120

opus_param_minptime

注意

この設定を利用する場合は事前にサポートまでご連絡ください

デフォルト:

10

範囲:

3..120

opus_param_useinbandfec

注意

この設定を利用する場合は事前にサポートまでご連絡ください

デフォルト:

true

opus_param_usedtx

注意

この設定を利用する場合は事前にサポートまでご連絡ください

デフォルト:

false

systemd

bin/sora foreground はデーモン化せずに Sora を起動するコマンドです。

設定

ユニットファイル

/etc/systemd/system/ に sora.service のユニットファイルを作成します。

ユニットファイルの例:

[Unit]
Description=WebRTC SFU Sora Service
After=network.target

[Service]
Environment="HOME=/home/shiguredo"
ExecStart=/home/shiguredo/sora/bin/sora foreground
Type=simple
Restart=always
RestartSec=60s
User=shiguredo
KillMode=process

[Install]
WantedBy=multi-user.target

[Service] セクションの Environment、 User はそれぞれ、実際に Sora サービスを開始するユーザーの $HOME、 $USER に置き換えてください。 また、 ExecStart は Sora のインストール先による実行コマンドのパスに置き換えてください。

Sora サービスの有効化と開始

sora.service の有効化:

$ sudo systemctl enable sora.service

sora.service の開始:

$ sudo systemctl start sora.service

Sora サービスの停止

sora.service の停止:

$ sudo systemctl stop sora.service

Linux カーネルチューニング

Sora は UDP に対して大きな負荷がかかるシステムです。そのためカーネルをチューニングする必要があります。

確認方法

netstat コマンドで Errors が出ていた場合はバッファが足りない可能性が高いです。

$ netstat -su

Ubuntu

sysctl

sysctl にて、以下の値を設定することを推奨します。 このあたりの値はサーバースペックによりますので、こちらは推奨値となります。

sudo sysctl -w net.core.rmem_default=33554432
sudo sysctl -w net.core.rmem_max=33554432

sudo sysctl -w net.core.wmem_default=33554432
sudo sysctl -w net.core.wmem_max=33554432

sudo sysctl -w net.core.somaxconn=65535
sudo sysctl -w net.core.optmem_max=25165824
sudo sysctl -w net.core.netdev_max_backlog=65536

sudo sysctl -w net.ipv4.tcp_mem='786432 1048576 26777216'
sudo sysctl -w net.ipv4.tcp_rmem='8192 87380 33554432'
sudo sysctl -w net.ipv4.tcp_wmem='8192 65536 33554432'

sudo sysctl -w net.ipv4.udp_mem='65536 131072 262144'
sudo sysctl -w net.ipv4.udp_rmem_min=16384
sudo sysctl -w net.ipv4.udp_wmem_min=16384

IPv6 での動作について

概要

Sora は WebRTC とウェブフックが IPv6 での動作に対応しています。ただし、ブラウザ側やサーバー側が非対応な場合があります。 特に、IPv6 での TURN 機能にクライアントが対応していない場合は接続できないことがあります。

お問い合わせの際の情報について

IPv6 環境は様々な組み合わせがあるため、問題を解析するには多くの情報が必要になります。

お問い合わせの際は以下の情報をお送りください。

• クライアント側の IPv6 の有無について

• Sora 側の IPv6 の設定の有無について

• Sora が動作しているサーバーの A または AAAA レコードの有無について

• クライアントが IPv4 または IPv6 または IPv4 と IPv6 どの環境かについて

他にも何か気づいた点などがありましたらそちらも合わせてお問い合わせください。

IPv6 のみ

Sora の WebRTC を IPv6 のみの通信のみでの動作させます。

sora.conf にて ipv6_only を true にすることで、 WebRTC の接続を IPv6 のみに制限することができます。

シグナリングや API 部分を IPv6 のみにしたい場合は Nginx 側の設定を変更してください。

ウェブフックの IPv6 対応

Sora のウェブフックは IPv6 での動作に対応しています。

sora.conf にて webhook_ipv6 を true にすることで、 ウェブフックの接続で IPv6 を利用する事ができます。

メタデータ

概要

Sora では様々なメタデータを扱っているため、それぞれのメタデータの説明をしています。

接続時の認証メタデータ指定

クライアントが Sora へ接続する際に、認証に利用する metadata を指定できます。 これは認証ウェブフックに metadata として含まれます。

{
  "type": "connect",
  "role": "sendrecv",
  "channel_id": "sora",
  "metadata": {"spam": "egg"}
}

この値はクライアントと Sora だけで共有される値です。他のクライアントには一切共有されません。

認証ウェブフック成功時のメタデータ払い出し

認証ウェブフック成功時に metadata を払い出すことができます。 この値は Sora が "type": "offer" をクライアントへ送る際に metadata として送られます。

{
  "allowed": true,
  "metadata": {"spam": "egg"}
}

{
  "type": "offer",
  "sdp": "...",
  "metadata": {"spam": "egg"}
}

この値は Sora とクライアントだけで共有される値です。他のクライアントには一切共有されません。

認証ウェブフック成功時のイベントメタデータ払い出し

認証ウェブフック成功時に event_metadata を払い出すことができます。 この値は Sora がイベントウェブフックリクエストを送信する際に event_metadata として含まれます。

{
  "allowed": true,
  "event_metadata": {"spam": "egg"}
}

{
  "type": "connection.created",
  "event_metadata": {"spam": "egg"}
}

この値は Sora と認証ウェブフックとイベントウェブフック先のサーバーとのみで共有されます。 クライアントには通知されません。

接続時のシグナリング通知メタデータ指定

シグナリング接続時の "type": "connect" で signaling_notify_metadata が指定できます。 ここで指定した値は同じチャネルに参加しているクライアントと新しく参加するクライアントに通知されます。

{
  "type": "connect",
  "signaling_notify_metadata": {"spam": "egg"}
}

{
  "type": "connection.created",
  "authn_metadata": {"spam": "egg"}
  "metadata": {"spam": "egg"}
}

シグナリング通知メタデータ拡張が有効な場合

シグナリング通知メタデータ拡張有効になっている場合は以下のように authn_metadata のみに値が含まれます。

{
  "type": "connection.created",
  "authn_metadata": {"spam": "egg"}
  "metadata": {}
}

もしこのシグナリング通知メタデータを接続時にしていさせたくない場合、 signaling_notify_authn_metadata_max_size を 0 に設定してください。

認証ウェブフック成功時のシグナリング通知メタデータ払い出し

認証ウェブフック成功時に signaling_notify_metadata を払い出すことができます。 この値は同じチャネルに参加しているクライアントと新しく参加するクライアントに通知されます。

もし接続時に signaling_notify_metadata が指定されていた場合は、 認証成功時のシグナリング通知メタデータ払い出しで 上書き されます。

{
  "allowed": true,
  "signaling_notify_metadata": {"spam": "egg"}
}

{
  "type": "connection.created",
  "authz_metadata": {"spam": "egg"}
  "metadata": {"spam": "egg"}
}

シグナリング通知メタデータ拡張が有効な場合

シグナリング通知メタデータ拡張が有効になっている場合は以下のように authz_metadata のみに値が含まれます。

{
  "type": "connection.created",
  "authz_metadata": {"spam": "egg"}
  "metadata": {}
}

シグナリング通知メタデータ拡張

シグナリング通知メタデータ拡張 を利用すると接続ごとに状態を持てるようになり、

API でそのメタデータを変更し、通知することができるようになります。

本来、シグナリング通知メタデータは接続時か認証成功払い出し時にしか指定できず一度指定したら変更できません。 シグナリング通知メタデータ拡張を利用した場合は HTTP API を利用して途中でメタデータの値を変更できます。

この機能を有効にするとシグナリング時の通知メタデータに指定した値は metadata に含まれなくなります。

セッション生成時のセッションメタデータ払い出し

セッション生成時に送信される session.created の戻り値に指定することで session_metadata を払い出すことができます。 この値は一定間隔で送られる session.updated と、 このセッションが破棄された時に送られる session.destroyed に含まれます。

{
  "session_metadata": "<JSON>"
}

一括録画ファイルメタデータ archive-<connection_id>.json

録画機能で一括録画を指定した際に archive/<recording-id>/ 以下に生成されるファイルです。 かならず archive-<connection_id>.webm ファイルとペアになります。

分割録画ファイルメタデータ split-archive-<connection_id>_<index>.json

録画機能で分割録画を指定した際に archive/<recording-id>/ 以下に生成されるファイルです。 かならず split-archive-<connection_id>_<index>.webm ファイルとペアになります。

録画(セッション単位) の StartRecording API で指定するメタデータ

StartRecording API では metadata を指定できます。

この値は以下のセッションウェブフックに recording_metadata として含まれます。

• recording.started

• recording.report

• session.updated

また、 report-<recording_id>.json ファイルにも記録されます。

録画(セッション単位) のセッションウェブフック session.created で指定するメタデータ

録画(セッション単位) ではセッションウェブフック session.created の戻り値として、 recording_metadata を払い出すことができます。

{
  "recording": true,
  "recording_metadata": "<JSON>"
}

この値は以下のセッションウェブフックに recording_metadata として含まれます。

• recording.started

• recording.report

• session.updated

また、 report-<recording_id>.json ファイルにも記録されます。

レガシー録画の StartRecording API で指定するメタデータ

StartRecording API では metadata を指定できます。

この値は、以下のイベントウェブフックに metadata として含まれます。

• recording.started

• recording.report

また、 report-<recording_id>.json ファイルにも記録されます。

センシティブデータ

概要

Sora ではログと API で出力されるセンシティブデータを "REDACTED" という文字列に書き換えます。

対象ログと項目

Sora のログは以下の内容のセンシティブデータを "REDACTED" に書き換えて出力します。

• auth_webhook.jsonl の event_metadata を "REDACTED" に書き換えて出力します。

• session_webhook.jsonl の session_metadata と event_metadata を "REDACTED" に書き換えて出力します。

• event_webhook.jsonl の event_metadata を "REDACTED" に書き換えて出力します。

event_webhook_error ログ

重要

event_webhook_error.jsonl の event_metadata については "REDACTED" の書き換えは行いません

session_webhook_error ログ

重要

session_webhook_error.jsonl の session_metadata と event_metadata については "REDACTED" の書き換えは行いません

書き換えをスキップする

重要

この書き換えを無効にすることは推奨していません。

センシティブなデータを利用している場合は、 "REDACTED" への書き換えをスキップする設定を提供しています。

sora.conf の skip_redact_sensitive_data を true にすることでセンシティブなデータの "REDACTED" への書き換えをスキップします。

録画メタデータの扱いについて

StartRecording API やセッションウェブフックの戻り値で指定できる録画メタデータについてはセンシティブなデータとして扱っていません。 これは録画ファイル出力時の録画メタデータファイルに含まれ、映像合成時に利用する事を想定しているためです。

アプリケーション連携チュートリアル

重要

このドキュメントについては Sora サポートの対象外です。

このドキュメントは Sora のウェブフックと API を利用したアプリケーションサーバー開発者向けです。

概要

Sora はウェブフックと API を利用して、アプリケーションサーバーと連携することができます。

ウェブフック

ウェブフックは認証と払い出し、そしてコネクションやセッション、録画などの状況の取得です。

Sora から一定間隔で送られてくるウェブフックを利用する事で定期的な状態を取得することができます。 どのコネクションが何分繫いでいたかの把握や、そのセッションは何分で終了させるといったことも実現できます。

ウェブフックは Sora からアプリケーションサーバーへ HTTP/1.1 でリクエストで送信します。

API

ウェブフックはコネクションの切断、セッションの破棄、統計情報の取得などアプリケーションサーバーが必要とするタイミングで送信することができます。

API はアプリケーションサーバーから Sora へ HTTP/1.1 でリクエストを送信する必要があります。

JSON

Sora がアプリケーションに送信するウェブフックの JSON は snake_case を採用しています。 camelCase ではないことに注意してください。

snake_case の JSON はシグナリング、ウェブフック、 API で利用します。

ウェブフックのローカル開発

Sora をサーバーに立て、ウェブフックの送信先をローカルにしたい場合には ngrok がお勧めです。

ngrok の利用方法

URL:

https://ngrok.com/

ngrok は無料プランでも、静的ドメインを一つ利用する事ができるため、 この静的ドメインを Sora 側に指定することにより、ローカルのウェブフックを利用することができます。

ngrok は Windows / Linux / macOS で利用可能です。

また ngrok が HTTPS を終端し、HTTP でアプリケーションサーバーにリクエストを送信するため、 アプリケーションサーバー側を HTTPS にする必要はありません。

シーケンス図

ngrok を利用した場合のシーケンス図です。 --domain には example ではなく ngrok のダッシュボードに表示されているドメインを指定してください。

        sequenceDiagram
    participant C as クライアント
    participant S as Sora
    participant NS as Ngrok Server<br>https://example.ngrok-free.app
    box ローカル環境
    participant NC as Ngrok Client<br>$ ngrok http --domain=example.ngrok-free.app 8080
    participant A as ローカルアプリケーション<br>http://localhost:8080
    end
    C ->>+ S: "type": "connect"
    S ->>+ NS: 認証ウェブフック
    NS ->>+ NC: 認証ウェブフック
    NC ->>+ A: 認証ウェブフック
    A -->>- NC: 200 OK<br>"allowed": true
    NC -->>- NS: 200 OK<br>"allowed": true
    NS -->>- S: 200 OK<br>"allowed": true
    S ->>- C: "type": "offer"
    

サンプルコードについて

アプリケーションサーバーのサンプルコードを Python を利用しています。 あくまで例であり、実際のアプリケーションでの利用は想定しておりません。

現在は OpenAI ChatGPT や GitHub Copilot を利用する事で、 他の言語への変換がとても簡単に行えるようになったこともあり、 サンプルコードに利用するプログラミング言語を Python に統一しています。

Python 3.12 以降で動作確認をしています。

aiohttp

サンプルコードでは Python の非同期 HTTP ライブラリである aiohttp を利用しています。

$ pip install aiohttp でインストールして利用してください。

• https://github.com/aio-libs/aiohttp

• https://pypi.org/project/aiohttp/

• https://docs.aiohttp.org/en/stable/index.html

Django 風

ウェブフックの処理を行うコードです。 このドキュメントではこちらの書き方を利用します。

from aiohttp import web


async def auth_webhook(request: web.Request) -> web.Response:
    return web.json_response({"allowed": True})


app = web.Application()
app.router.add_routes(
    [
        web.post("/auth", auth_webhook),
    ]
)

if __name__ == "__main__":
    web.run_app(app, port=8000)

Flask 風

デコレーターを利用して、ウェブフックの処理を行うコードです。 Django 風と Flask 風、どちらを利用するかは好みの問題ですので、 好きな方を利用してください。

from aiohttp import web

routes = web.RouteTableDef()


@routes.post("/auth")
async def auth_webhook(request: web.Request) -> web.Response:
    return web.json_response({"allowed": True})


app = web.Application()
app.router.add_routes(routes)

if __name__ == "__main__":
    web.run_app(app, port=8000)

ウェブフック HTTP 実装

ウェブフックを処理するコードです。

sora.conf の以下の設定に URL を指定してください。

• auth_webhook_url

• session_webhook_url

• event_webhook_url

例として ngrok を利用している URL を指定しています。

auth_webhook_url = https://example.ngrok-free.app/auth
session_webhook_url = https://example.ngrok-free.app/session
event_webhook_url = https://example.ngrok-free.app/event

認証が常に成功するようなコードになっています。

from aiohttp import web


async def auth_webhook(request: web.Request) -> web.Response:
    return web.json_response({"allowed": True})


async def session_webhook(request: web.Request) -> web.Response:
    return web.Response(status=204)


async def event_webhook(request: web.Request) -> web.Response:
    return web.Response(status=204)


app = web.Application()
app.router.add_routes(
    [
        web.post("/auth", auth_webhook),
        web.post("/session", session_webhook),
        web.post("/event", event_webhook),
    ]
)

if __name__ == "__main__":
    web.run_app(app, port=8000)

ウェブフック HTTPS 対応

Sora のウェブフックは HTTPS にも対応しています。

Sora の HTTPS はサーバ証明書のチェックをデフォルトで OS に組み込まれた証明書を利用して行います。 自前で用意した証明書などを利用したい場合は webhook_tls_verify_cacert_file を利用してください。

詳細は ウェブフックリクエストなどの送信先サーバー証明書の検証に利用する OS 組み込みのルート CA 証明書について をご確認ください。

import ssl

from aiohttp import web


async def auth_webhook(request: web.Request) -> web.Response:
    return web.json_response({"allowed": True})


async def session_webhook(request: web.Request) -> web.Response:
    return web.Response(status=204)


async def event_webhook(request: web.Request) -> web.Response:
    return web.Response(status=204)


app = web.Application()
app.router.add_routes(
    [
        web.post("/auth", auth_webhook),
        web.post("/session", session_webhook),
        web.post("/event", event_webhook),
    ]
)


# サーバー証明書
certfile: str = "192.0.2.1.pem"
# サーバー証明書のプライベートキー
keyfile: str = "192.0.2.1-key.pem"

if __name__ == "__main__":
    # SSL コンテキストの作成
    ssl_context = ssl.create_default_context(ssl.Purpose.CLIENT_AUTH)
    ssl_context.load_cert_chain(certfile, keyfile)

    # HTTPS サーバーとして起動
    web.run_app(app, port=4433, ssl_context=ssl_context)

ウェブフック mTLS (mutual-TLS またはクライアント認証) 対応

Sora のウェブフックは mTLS にも対応しています。 その場合、アプリケーションサーバー側に、Sora に設定した証明書の CA 証明書を指定する必要があります。

import ssl

from aiohttp import web


async def auth_webhook(request: web.Request) -> web.Response:
    return web.json_response({"allowed": True})


async def session_webhook(request: web.Request) -> web.Response:
    return web.Response(status=204)


async def event_webhook(request: web.Request) -> web.Response:
    return web.Response(status=204)


app = web.Application()
app.router.add_routes(
    [
        web.post("/auth", auth_webhook),
        web.post("/session", session_webhook),
        web.post("/event", event_webhook),
    ]
)

# サーバー証明書
certfile: str = "192.0.2.1.pem"
# サーバー証明書のプライベートキー
keyfile: str = "192.0.2.1-key.pem"
# クライアント証明書のCA証明書
cafile: str = "ca.pem"

if __name__ == "__main__":
    # SSL コンテキストの作成
    ssl_context = ssl.create_default_context(ssl.Purpose.CLIENT_AUTH)
    ssl_context.load_cert_chain(certfile, keyfile)
    ssl_context.load_verify_locations(cafile)

    # クライアント証明書の検証を要求
    ssl_context.verify_mode = ssl.CERT_REQUIRED

    # HTTPS サーバーとして起動
    web.run_app(app, port=4433, ssl_context=ssl_context)

ウェブフック IPv6 対応

Sora は昨今の IPv4 事情を考慮して IPv6 にも対応しています。

sora.conf の webhook_ipv6 を true にすることで、 IPv6 のみのウェブフックエンドポイントと通信をすることができます。

認証ウェブフック

Sora 自体は認証処理を持っていません。 そのため、アプリケーションサーバー側で認証の仕組みを開発する必要があります。

Sora は auth_webhook_url に指定した URL にクライアントから送られてきた情報などを、 アプリケーションサーバに対して HTTP (または HTTPS) リクエストとして送信します。

認証メタデータ

認証ウェブフックにはクライアントが送ってくる metadata が含まれます。 これはクライアントが自由に値を含められる場所で、ここの値を使って認証を行うことを推奨しています。

from aiohttp import web


async def auth_webhook(request: web.Request) -> web.Response:
    data = await request.json()
    # metadata がない場合は None が返る
    metadata = data.get("metadata")
    if not metadata:
        # metadata がない場合は認証を許可しない
        # 認証を拒否する場合は 'allowed': False と 'reason': '認証失敗理由' を返す
        # この認証失敗理由はクライアントまで通知されるので注意すること
        return web.json_response({"allowed": False, "reason": "metadata not found"})

    # 認証を許可する JSON を返す
    return web.json_response({"allowed": True})

認証メタデータに JWT

認証メタデータの中に access_token として JWT が入ってきた場合の処理です。

PyJWT を利用して、JWT をデコードして認証を行います。

import os

import jwt
from aiohttp import web


async def auth_webhook(request: web.Request) -> web.Response:
    data = await request.json()
    metadata = data.get("metadata")
    if not metadata:
        return web.json_response({"allowed": False, "reason": "metadata not found"})

    access_token = metadata.get("access_token")
    if not access_token:
        return web.json_response({"allowed": False, "reason": "access_token not found"})

    # 環境変数からシークレットキーを取得
    secret = os.environ.get("JWT_SECRET_KEY")
    if not secret:
        return web.json_response({"allowed": False, "reason": "secret key not found"})

    try:
        # PyJWT を利用して JWT をデコードし、署名を検証する
        jwt.decode(access_token, secret, algorithms=["HS256"])
    except jwt.InvalidTokenError:
        # トークンが無効の場合は認証を拒否
        return web.json_response({"allowed": False, "reason": "invalid token"})

    # 認証を許可する JSON を返す
    return web.json_response({"allowed": True})

イベントメタデータ

認証ウェブフックで、認証成功時にイベントメタデータを払い出すことができます。 イベントメタデータはイベントウェブフックの connection.{created, updated, destroyed} に含まれます。

このイベントメタデータは Sora とアプリケーションサーバー間だけでやり取りされ、クライアントには送られません。 そのためデータベースの Primary Key などを入れておいたりすることができます。

from aiohttp import web


async def auth_webhook(request: web.Request) -> web.Response:
    # ここでデータベースなどの値を引っ張る
    account_pk = 1

    # イベントメタデータ
    event_metadata = {
        "account_pk": account_pk,
    }

    # 認証を許可する JSON を返す
    return web.json_response({"allowed": True, "event_metadata": event_metadata})
    return web.json_response({"allowed": True, "event_metadata": event_metadata})

イベントメタデータはウェブフックログには REDACTED として記録されます。 これはセンシティブデータを含んでいる可能性があるためです。

REDACTED については センシティブデータ をご確認ください。

        sequenceDiagram
    participant C as クライアント
    participant S as Sora
    participant A as アプリケーション
    C ->>+ S: "type": "connect"
    S ->>+ A: 認証ウェブフック
    A -->>- S: 200 OK<br>"allowed": true<br>"event_metadata": {"account_pk": 1}
    S ->>+ A: セッションウェブフック<br>session.created
    A -->>- S: 200 OK
    S ->>- C: "type": "offer"
    note over C,S: WebRTC 確立
    S ->>+ A: イベントウェブフック<br>connection.created<br>"event_metadata": {"account_pk": 1}
    A -->>- S: 200 OK
    S ->>+ A: イベントウェブフック<br>connection.updated<br>"event_metadata": {"account_pk": 1}
    A -->>- S: 200 OK
    note over S,A: connection.updated は一定間隔で送信
    C -) S: "type": "disconnect"
    S -) C: "Close"
    note over C,S: WebRTC 切断
    S ->>+ A: イベントウェブフック<br>connection.destroyed<br>"event_metadata": {"account_pk": 1}
    A -->>- S: 200 OK
    

セッションウェブフック

セッションウェブフックはセッション単位の変化を通知するためのウェブフックです。

Sora は session_webhook_url に指定した URL にセッションの変化を HTTP リクエストとして送信します。

セッション

セッションはチャネルで少なくとも 1 つのクライアントが接続しているチャネルの状態を指します。

セッションメタデータ

from aiohttp import web


async def session_webhook(request: web.Request) -> web.Response:
    # ここでデータベースなどの値を引っ張る
    room_pk = 2
    return web.json_response({"session_metadata": {"room_pk": room_pk}})

セッション録画開始

セッションウェブフックの session.created の戻り値に recording: true を含める事で、 そのセッションが開始したタイミングから録画を開始することができます。

from aiohttp import web


async def session_webhook(request: web.Request) -> web.Response:
    # このセッションで録画を有効にする
    return web.json_response({"recording": True})

イベントウェブフック

イベントウェブフックはコネクション単位での変化を通知するためのウェブフックです。

• コネクションが接続したら、コネクション接続のイベントが送信されます

• コネクションが接続している間は、コネクション更新のイベントが一定間隔で送信されます

  • デフォルトでは 1 分間隔で送信されますが、 connection_updated_webhook_interval で変更可能です

• コネクションが切断したら、コネクション切断のイベントが送信されます

connection.{created,updated,destroyed}

from aiohttp import web


async def event_webhook(request: web.Request) -> web.Response:
    data = await request.json()

    match data.get("type"):
        case "connection.created":
            # connection.created イベントの処理
            # データベースに保存したりする
            pass
        case "connection.updated":
            # connection.updated イベントの処理
            # データベースに保存したりする
            pass
        case "connection.destroyed":
            # connection.destroyed イベントの処理
            # データベースに保存したりする
            pass
        case _:
            # 未対応のイベントの処理
            pass

    return web.Response(status=204)

API

Sora の API は、パスを利用せず、ヘッダーを利用して判定する方式を採用しています。

• メソッドは常に POST を利用します

• パスは常に / を利用します

• x-sora-target ヘッダーを利用して、どの API にアクセスするかを判定します

指定したチャネルのコネクションを切断する

import asyncio

import aiohttp


async def main():
    url = "https://sora.example.com"
    headers = {
        "X-Sora-Target": "Sora_20151104.DisconnectConnection",
    }
    data = {
        "channel_id": "sora",
        "connection_id": "T34CDBMRJS1B5BVPF17RTBQA3C",
    }

    async with aiohttp.ClientSession() as session:
        # Nginx で api の prefix を /api に設定している場合は以下のように変更
        # response = await session.post(f"{url}/api", json=data, headers=headers)
        response = await session.post(url, json=data, headers=headers)

        print(response.status)
        response_data = await response.text()
        print(response_data)


if __name__ == "__main__":
    asyncio.run(main())

接続してから 3 分経過したコネクションを切断する

イベントウェブフック connection.updated と、 コネクション切断 DisconnectConnection API を利用して、 接続してから 3 分経過したコネクションを切断します。

import aiohttp
from aiohttp import web


async def auth_webhook(request: web.Request) -> web.Response:
    return web.json_response({"allowed": True})


async def session_webhook(request: web.Request) -> web.Response:
    return web.Response(status=204)


async def event_webhook(request: web.Request) -> web.Response:
    data = await request.json()
    match data.get("type"):
        case "connection.updated":
            if data.get("minutes", 0) >= 3:
                channel_id = data.get("channel_id")
                connection_id = data.get("connection_id")

                url = "https://sora.example.com/api"

                headers = {
                    "X-Sora-Target": "Sora_20151104.DisconnectConnection",
                }

                data = {
                    "channel_id": channel_id,
                    "connection_id": connection_id,
                }

                async with aiohttp.ClientSession() as session:
                    async with session.post(
                        url,
                        headers=headers,
                        json=data,
                    ) as response:
                        if response.status != 200:
                            # エラー処理
                            pass
        case _:
            # 見知らぬイベントの処理
            pass

    return web.Response(status=204)


app = web.Application()
app.router.add_routes(
    [
        web.post("/auth", auth_webhook),
        web.post("/session", session_webhook),
        web.post("/event", event_webhook),
    ]
)

if __name__ == "__main__":
    web.run_app(app, port=8000)

シーケンス図

        sequenceDiagram
    participant C as クライアント
    participant S as Sora
    participant A as アプリケーション
    C ->>+ S: "type": "connect"
    S ->>+ A: 認証ウェブフック
    A -->>- S: 200 OK<br>"allowed": true
    S ->>+ A: セッションウェブフック<br>session.created
    A -->>- S: 200 OK
    S ->>- C: "type": "offer"
    note over C,S: WebRTC 確立
    S ->>+ A: イベントウェブフック<br>connection.created<br>"minutes": 0
    A -->>- S: 200 OK
    S ->>+ A: イベントウェブフック<br>connection.updated<br>"minutes": 1
    A -->>- S: 200 OK
    S ->>+ A: イベントウェブフック<br>connection.updated<br>"minutes": 2
    A -->>- S: 200 OK
    note over C,A: WebRTC 確立してから 10 分経過
    S ->>+ A: イベントウェブフック<br>connection.updated<br>"minutes": 10
    A -->>- S: 200 OK
    A ->>+ S: DisconnectConnection API
    S -->>- A: 200 OK
    S -) C: "Close"
    note over C,S: WebRTC 切断
    S ->>+ A: イベントウェブフック<br>connection.destroyed<br>"minutes": 10
    A -->>- S: 200 OK
    

WebSocket 経由のシグナリング

概要

重要

Sora の SDK を利用する場合は、ここに書かれているシグナリングの細かい仕様を把握する必要は基本的にありません。

Sora のシグナリングにはデフォルトでは WebSocket を使用します。

用語

channel_id

接続のグルーピングに利用する ID です。 接続時に任意の文字列、最大 255 バイトまでを自由に指定できます。

session_id

channel_id への接続が 0 から 1 に切り替わったタイミングで生成される id です。 1 から 0 になり、一定期間が経過したタイミングでセッションは破棄されます。

セッションが破棄された後、 再度同一 channel_id で接続が 0 から 1 になった場合、新しい session_id が生成されます。

セッションごとのユニークな値です。 UUIDv4 で生成した値を Base32 でエンコードした値で、Sora が払い出します。指定はできません。

client_id

接続時やサーバー認証成功時に任意の文字列を最大 255 バイトまで指定できる値です。 指定しない場合は connection_id が入ります。自由に指定できます。重複が可能な ID です。

bundle_id

bundle_id を指定した場合、マルチストリーム利用時に bundle_id が等しい接続からの音声や映像、メッセージング、シグナリング通知を受信しなくなります。

接続時やサーバー認証成功時に任意の文字列を最大 255 バイトまで指定できる値です。指定しない場合は connection_id が入ります。

シグナリングでの bundle_id の指定はデフォルトでは無効になっているため、有効にする場合には sora.conf にて signaling_bundle_id を true にする必要があります。

connection_id

接続ごとのユニークな値です。 UUIDv4 で生成した値を Base32 でエンコードした値で、Sora が払い出します。指定はできません。

connection_id の例

"FW0CJSHETX0RXAGX8WWEXNBQN8"

仕組み

Sora のシグナリングは、Sora からクライアントへ Offer (SDP) を送ります。

シグナリングの処理の流れは、認証ウェブフックなし のシーケンス図を参照してください。

シグナリングの型の正確な仕様は シグナリングの型定義 を参照してください。

URL

デフォルトの設定では、シグナリングは 0.0.0.0:5000 でリッスンするため、 シグナリング URL は http://<サーバーのアドレス>:5000/signaling となります。

パス部分は /signaling 固定で変更できません 。

DataChannel 経由への切り替え

注意

実験的機能として、シグナリングを WebSocket 経由から DataChannel 経由へ変更する機能を提供中です

詳細は DataChannel 経由のシグナリング をご確認ください。

注意

シグナリングが完了しても WebSocket の接続は切断しないでください。WebSocket の接続が切れると Sora は WebRTC 接続を終了します。

設定

signaling_loopback_address_only

sora.conf にて signaling_loopback_address_only を true にすることで、 ループバックアドレスからのみアクセスできるようにします。

nginx などを前段に利用している場合は可能な限り有効にしてください。

シグナリングのタイプ

Sora のシグナリングは、タイプごとの JSON でクライアントとメッセージをやりとりします。

"type": "connect"

クライアントは Sora に接続の意思を伝える JSON を送ります。以下は最小の JSON です。

{
  "type": "connect",
  "role": "sendonly",
  "channel_id": "Spam"
}

role

そのクライアントの役割を指定します。この設定は必須です。

role には sendrecv / sendonly / recvonly のどれかを指定してください。

• sendrecv

  • マルチストリーム、スポットライトで利用できます。送信及び受信を行います

• sendonly

  • すべてで利用できます。送信のみを行い、受信を行いません

• recvonly

  • すべてで利用できます。受信のみを行い、送信を行いません

channel_id

channel_id は 1-255 バイトまでの文字列であればどのような文字列でも指定できます。

配信または視聴メディアの選択

この項目はオプションです

audio と video を指定することにより配信、または視聴するメディアを選択することができます。 role に sendrecv または sendonly を指定した場合は配信するメディア、 recvonly を指定したときは視聴するメディアについての指定となります。

この設定が未指定の場合は、 true がデフォルトで指定され、映像と音声両方の配信、または映像と音声両方の受信が行われます。

以下の例では role に sendrecv が指定されており、音声のみが配信されます。

{
    "type": "connect",
    "role": "sendrecv",
    "channel_id": "Spam",
    "video": false
}

注釈

role に sendrecv が指定された場合は常に映像と音声両方を受信します。

以下の例では role に sendonly が指定されており、映像のみが配信されます。

{
    "type": "connect",
    "role": "sendonly",
    "channel_id": "Spam",
    "audio": false
}

以下の例では role に recvonly が指定されており、音声のみが受信されます。

{
    "type": "connect",
    "role": "recvonly",
    "channel_id": "Spam",
    "video": false
}

オーディオコーデック指定

この項目はオプションです

配信者や視聴者はオーディオコーデックを指定できます。

この設定はオプションです。

この設定が指定されない場合は、 OPUS がデフォルトで設定されます。

• Opus

  • "OPUS"

{
  "type": "connect",
  "role": "sendonly",
  "channel_id": "Spam",
  "audio": {
    "codec_type":"OPUS"
  }
}

オーディオビットレート指定

この項目はオプションです

重要

オーディオビットレートは指定しないことをおすすめします。指定しないことで最適なビットレートが採用されます。

配信者はオーディオビットレートの最大値を指定できます。

このビットレート指定は Opus にのみ有効です。

• bit_rate

  • 6-510

{
  "type": "connect",
  "role": "sendonly",
  "channel_id": "Spam",
  "audio": {
    "codec_type": "OPUS",
    "bit_rate": 64
  }
}

指定できる値は 6 から 510 です。32 を指定した場合は、32kbps がビットレートの最大値です。

指定しない場合は sora.conf の default_audio_bit_rate に指定した値が採用されます。 default_audio_bit_rate も指定していない場合、ビットレートはクライアント側に依存します。

オーディオの Opus 設定指定

注意

この機能は実験的機能です。この機能を利用される場合は必ず事前にサポートまでご連絡ください

配信者は Opus の設定を指定できます。

• opus_params

  • channels

    • 1-8

  • maxplaybackrate

    • 8000-48000

  • stereo

    • boolean

  • sprop_stereo

    • boolean

  • minptime

    • integer 3-120

  • useinbandfec

    • boolean

  • usedtx

    • boolean

    • この機能を有効にした場合は録画がおかしくなります

{
  "type": "connect",
  "role": "sendonly",
  "channel_id": "Spam",
  "audio": {
    "codec_type": "OPUS",
    "opus_params": {
      "stereo": false,
      "useinbandfec": false
    }
  }
}

ビデオコーデック指定

この項目はオプションです

配信者や視聴者はビデオコーデックを指定できます。

この設定はオプションです。

この設定が指定されない場合は、VP9 がデフォルトで設定されます。

• VP8

  • "VP8"

• VP9

  • "VP9"

• AV1

  • "AV1"

  • Chrome M96 以降で利用できます

  • Sora SDK で利用できます

• H.264

  • "H264"

• H.265

  • "H265"

  • Sora iOS/Android SDK で利用できます

  • Safari では実験的機能を有効にすることで利用できます

{
  "type": "connect",
  "role": "sendonly",
  "channel_id": "Spam",
  "video": {
    "codec_type":"VP9"
  }
}

ビデオビットレート指定

この項目はオプションです

配信者はビデオビットレートの最大値を指定できます。単位は kbps です。

• bit_rate

  • 1-50000

{
  "type": "connect",
  "role": "sendonly",
  "channel_id": "Spam",
  "video": {
    "codec_type": "VP9",
    "bit_rate": 500
  }
}

指定できる値は 1 から 50000 です。500 を指定した場合は、500 kbps がビットレートの最大値です。

10 Mbps を最大値としたい場合は 10000 を指定してください。ただし 15 Mbps より大きい値は現時点ではサポート外となります。

指定しない場合は sora.conf の default_video_bit_rate に指定した値が採用されます。

ビデオの VP9 設定指定

配信者は VP9 のプロファイル ID を指定できます。 VP9 のプロファイル ID を指定をする場合は、あわせて codec_type に VP9 を指定する必要があります。

• vp9_params

  • profile_id

    • integer

    • 0-3

この値を指定するには sora.conf にて signaling_vp9_params を true に設定する必要があります。

{
  "type": "connect",
  "role": "sendonly",
  "channel_id": "Spam",
  "video": {
    "codec_type": "VP9",
    "vp9_params": {
      "profile_id": 2
    }
  }
}

ビデオの AV1 設定指定

配信者は AV1 のプロファイル を指定できます。 AV1 のプロファイル を指定をする場合は、あわせて codec_type に AV1 を指定する必要があります。

• av1_params

  • profile

    • integer

    • 0-2

この値を指定するには sora.conf にて signaling_av1_params を true に設定する必要があります。

{
  "type": "connect",
  "role": "sendonly",
  "channel_id": "Spam",
  "video": {
    "codec_type": "AV1",
    "av1_params": {
      "profile": 0
    }
  }
}

ビデオの H.264 設定指定

配信者は H.264 のプロファイルレベル ID を指定できます。 H.264 のプロファイルレベル ID を指定をする場合は、あわせて codec_type に H264 を指定する必要があります。

• h264_params

  • profile_level_id

    • string

    • "42e02a" など

  • b_frame

    • boolean

    • sora.conf にて h264_b_frame が true に指定されているときに指定できます

この値を指定するには sora.conf にて signaling_h264_params を true に設定する必要があります。

{
    "type": "connect",
    "role": "sendonly",
    "channel_id": "Spam",
    "video": {
        "codec_type": "H264",
        "h264_params": {
            "profile_level_id": "42e02a"
        }
    }
}

ビデオの H.265 設定指定

注意

この機能は実験的機能です。この機能を本番環境で利用される場合は必ず事前にサポートまでご連絡ください

警告

この機能はまだ対応しているライブラリが存在しません。

配信者は H.265 のプロファイルレベル ID を指定できます。 H.265 のプロファイルレベル ID を指定をする場合は、あわせて codec_type に H265 を指定する必要があります。

• h265_params

  • level_id

    • integer

    • 93 など

  • b_frame

    • boolean

    • sora.conf にて h265_b_frame が true に指定されているときに指定できます

この値を指定するには sora.conf にて signaling_h265_params を true に設定する必要があります。

{
    "type": "connect",
    "role": "sendonly",
    "channel_id": "Spam",
    "video": {
        "codec_type": "H265",
        "h265_params": {
            "level_id": 93
        }
    }

認証メタデータ

この項目はオプションです

認証するための判断材料としてメタデータを使用できます。

認証メタデータは必須ではありません。

{
    "type": "connect",
    "role": "sendonly",
    "channel_id": "Spam",
    "metadata": "1234abcd"
}

認証メタデータは、そのまま認証サーバーに送られます。詳細は 認証ウェブフック をご確認ください。

client_id の指定

この項目はオプションです

重要

client_id の値は重複することができます。

1-255 バイトまでの文字列であれば、どのような文字列でも指定できます。

{
    "type": "connect",
    "role": "sendonly",
    "channel_id": "Spam",
    "client_id": "egg-ham"
}

bundle_id の指定

この項目はオプションです

重要

bundle_id の値は重複することができます。

1-255 バイトまでの文字列であれば、どのような文字列でも指定できます。

マルチストリーム利用時に bundle_id が同じ接続からの音声や映像、メッセージングを受信しなくなります。

この値を指定するには sora.conf にて signaling_bundle_id を true に設定する必要があります。

{
    "type": "connect",
    "role": "sendonly",
    "channel_id": "Spam",
    "bundle_id": "spam_egg"
}

サイマルキャスト

この項目はオプションです

自分が配信する映像のストリームを複数本にすることで、 受信側にどのストリームを受信するかを選択させることができるようになります。

{
    "type": "connect",
    "role": "sendrecv",
    "channel_id": "spam",
    "simulcast": true
}

詳細は サイマルキャスト機能 をご確認ください。

サイマルキャストマルチコーデック

この項目はオプションです

自分が配信する映像のストリームを複数本かつ、複数コーデックにすることができます。

サイマルキャストマルチコーデック機能を利用する場合、 sora.conf にて simulcast_multicodec を true に設定する必要があります。

{
    "type": "connect",
    "role": "sendrecv",
    "channel_id": "spam",
    "simulcast": true,
    "simulcast_multicodec": true
}

詳細は サイマルキャストマルチコーデック機能 をご確認ください。

スポットライト

この項目はオプションです

話をした人にフォーカスを当てて、フォーカスが当たっている人は高画質な映像と音声で配信、 フォーカスが当たっていない人は低画質な映像で配信するという、クライアントの負荷を下げる仕組みです。

{
    "type": "connect",
    "role": "sendrecv",
    "channel_id": "spam",
    "simulcast": true,
    "spotlight": true
}

詳細は スポットライト機能 をご確認ください。

転送フィルター

この項目はオプションです

接続時に転送フィルターを指定することで、条件に該当する他のチャネル参加者の音声や映像の受信をブロックする仕組みです。

• forwarding_filters

  • 受信をブロックする条件をリストで指定します

  • 接続後は 転送フィルター API を利用してフィルターの変更、削除ができます

  • この機能を利用するには signaling_forwarding_filters を true に設定する必要があります

• forwarding_filter

  • 2025 年 12 月リリースの Sora にて廃止予定です

  • 受信をブロックする条件を指定します

  • 接続後は 転送フィルター API を利用してフィルターの変更、削除ができます

  • この機能を利用するには signaling_forwarding_filter を true に設定する必要があります

{
    "type": "connect",
    "role": "sendrecv",
    "channel_id": "spam",
    "forwarding_filters": [
      {
        "action": "block",
        "rules": [
            [
            {"field": "kind", "operator": "is_in", "values": ["audio"]}
            ]
        ]
      }
    ]
}

{
    "type": "connect",
    "role": "sendrecv",
    "channel_id": "spam",
    "forwarding_filter": {
        "action": "block",
        "rules": [
            [
            {"field": "kind", "operator": "is_in", "values": ["audio"]}
            ]
        ]
    }
}

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

sdp

この項目はオプションです

Sora SDK や Sora クライアントで生成した offer SDP を Sora のログに記録します。 この項目は、ログの記録にのみ利用します。

{
    "type": "connect",
    "role": "sendrecv",
    "channel_id": "spam",
    "sdp": "..."
}

sora_client

この項目はオプションです

Sora SDK や Sora クライアントの情報を文字列で送ることができます。 これはログに記録されたり、認証ウェブフックリクエストで送信されたりします。

{
    "type": "connect",
    "role": "sendrecv",
    "channel_id": "sora",
    "sora_client": "Sora JavaScript SDK 2021.1.0"
}

environment

この項目はオプションです

Sora SDK や Sora クライアントの利用環境を文字列で送ることができます。 これはログに記録されたり、認証ウェブフックリクエストで送信されたりします。

Sora JavaScript SDK では userAgent の情報が入ります。

{
    "type": "connect",
    "role": "sendrecv",
    "channel_id": "sora",
    "environment": "Mozilla\/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit\/537.36 (KHTML, like Gecko) Chrome\/93.0.4522.0 Safari\/537.36"
}

libwebrtc

この項目はオプションです

Sora SDK や Sora クライアントの libwebrtc のバージョンを文字列で送ることができます。 これはログに記録されたり、認証ウェブフックリクエストで送信されたりします。

{
    "type": "connect",
    "role": "sendrecv",
    "channel_id": "sora",
    "libwebrtc": "Shiguredo-Build M90.4430@{#3} (90.4430.3.1 dee77cf2)"
}

redirect

クラスター利用時に、接続先の Sora から "type": "redirect" を受け取って、 再度 Sora へ接続する際に、この値に true を指定する必要があります。

"type": "offer"

認証ウェブフックが認証成功を返すと、Sora は以下のような JSON をクライアントに送ります。 SDK を利用している場合は、この仕様を意識する必要はありません。

{
    "type": "offer",
    "sdp": "<SDP>",
    "channel_id": "sora",
    "session_id": "05JTBDGM1H3GB7FK0B1CJ45JE0",
    "connection_id": "ECF3W1RGMD02DETH30CDZTHNRW",
    "client_id": "ECF3W1RGMD02DETH30CDZTHNRW",
    "bundle_id": "ECF3W1RGMD02DETH30CDZTHNRW",
    "multistream": true,
    "simulcast": false,
    "spotlight": false,
    "version": "2024.2.0",
    "metadata": "1234abcd",
    "audio": true,
    "audio_codec_type": "OPUS",
    "video": true,
    "video_codec_type": "VP9",
    "video_bit_rate": 500,
    "config": {
      "iceServers": [
        {
          "credential": "ClDTPB4DjgFLrclpSBxjTiXg7K8kYsGf",
          "urls": [
            "turn:192.0.2.1:443?transport=tcp"
          ],
          "username": "sYL5WdMt"
        }
      ],
      "iceTransportPolicy": "relay"
    },
    "mid": {
        "audio": "audio_aDScYe",
        "video": "video_i2sNRq"
    },
    "data_channels": [
      {
        "compress": true,
        "label": "stats"
      },
      {
        "compress": true,
        "label": "push"
      },
      {
        "compress": true,
        "label": "notify"
      },
      {
        "compress": true,
        "label": "signaling"
      }
    ]
}

• channel_id

  • "type": "connect" の channel_id で指定した値が入ります

• session_id

  • UUIDv4 を Base32 でエンコードしたユニークな ID が入ります

• connection_id

  • UUIDv4 を Base32 でエンコードしたユニークな ID が入ります

• client_id

  • クライアントや認証サーバーが指定した値、または、Sora が生成した connection_id が入ります

• bundle_id

  • クライアントや認証サーバーが指定した値、または、Sora が生成した connection_id が入ります

• config

  • RTCPeerConnection に渡す設定が入ります

  • 主に TURN の情報です

• mid

  • audio と video の MediaStream Id が入ります

• audio

  • 音声の配信を行うかどうかが入ります

• audio_codec_type

  • これはオプションです

  • audio が true かつ role が sendrecv または sendonly の場合に含まれます

  • 音声のコーデックが入ります

• audio_bit_rate

  • これはオプションです

  • audio が true かつ role が sendrecv または sendonly で audio_bit_rate が指定された場合に含まれます

  • 音声のビットレートが入ります

• video

  • 映像の配信を行うかどうかが入ります

• video_codec_type

  • これはオプションです

  • video が true かつ role が sendrecv または sendonly の場合に含まれます

  • 映像のコーデックが入ります

• video_bit_rate

  • これはオプションです

  • video が true かつ role が sendrecv または sendonly の場合に含まれます

  • 映像のビットレートが入ります

• version

  • Sora のバージョンが入ります

• metadata

  • これはオプションです

  • 認証サーバーから払い出された metadata が入ります

• data_channels

  • これは DataChannel 経由のシグナリングを有効にしている場合にのみ利用されます

  • 詳細は DataChannel への切り替え要否の判断 をご確認ください

"type": "answer"

クライアントは offer を受け取りしだい、answer 用の SDP を生成します。

{
  "type": "answer",
  "sdp": "<Answer 用 SDP>"
}

その後、必要があればクライアントは取得した candidate を送ります。

{
  "type": "candidate",
  "candidate": "candidate:3179889176 1 tcp 1518214911 192.168.1.10 0 typ host tcptype active generation 0"
}

"type": "disconnect"

クライアントからこのメッセージを送ると、Sora は WebSocket を切断します。また、WebRTC 側も終了します。

クライアントから切断する際には、このメッセージを送るようにしてください。

{
  "type": "disconnect"
}

オプションとして reason を指定することもできます。 この値は connection.destroyed の type_disconnect_reason として含まれます。

reason は最大 128 バイトまで指定する事ができます。

{
  "type": "disconnect",
  "reason": "NO-ERROR"
}

"type": "ping"

サーバーからクライアント側に定期的に送られる通知です。この値をクライアントが受け取った場合は、すぐに以下の JSON を Sora に送信してください。

{
    "type": "pong"
}

"type": "ping" を送ってから指定時間の間に一度も "type": "pong" が返ってこない場合、 Sora は正常な通信が行えていないと判断して、Sora からシグナリングの接続を切断します。

指定時間はデフォルトでは 60 秒に設定されており、この値は sora.conf の設定 websocket_signaling_pong_timeout で変更できます。

stats

注意

この機能は WebSocket 経由でのシグナリングの時のみ有効です

sora.conf にて user_agent_stats または rtc_stats を true にしている場合は、 "type": "ping" 時に "stats": true が送られてきます。

{
    "type": "ping",
    "stats": true
}

この値を受け取った場合は、WebRTC の統計情報を取得して "type": "pong" 送信時に stats をキーにして値を含んで応答してください。

{
    "type": "pong",
    "stats": [{"type": "..."}, {"type": "..."}]
}

"type": "notify"

サーバーからクライアントに対して、参加しているチャネルの情報が通知されるようになります。

詳細は シグナリング通知機能 をご確認ください。

"type": "push"

Sora の プッシュ API や シグナリング通知メタデータ拡張機能 、 音声ストリーミング機能 利用時にクライアントに送信されるプッシュ通知です。

data 内に各機能に応じた情報が設定されます。

{
    "type": "push",
    "data": {
        <key>: <object>,
        <key>: <object>,
        ...
    }
}

シグナリングエラー

切断時の reason を利用してハンドリングできます。

• Sora のシグナリング失敗時には必ず WebSocket が切断されます。

• どのようなエラーでも、ステータスコードは固定で 4490 が返ってきます。

• reason にはエラーメッセージが入ります

クライアントに返されるエラーの種類

• INTERNAL-ERROR

• SERVICE-UNAVAILABLE

• TIMEOUT

• INVALID-MESSAGE

重要

Sora はライセンスの期限が切れていたとしても、クライアントには SERVICE-UNAVAILABLE というエラーを返します。

signaling_error.jsonl に出力される message 一覧

• UNAUTHORIZED

  • このエラーはクライアントに通知されることはなく、ログにしか出力されません

• INTERNAL-ERROR

• SERVICE-UNAVAILABLE

• TIMEOUT

• INVALID-MESSAGE

signaling_error.jsonl に出力される details.reason の一部

details.reason	解説
connection_created_wait_timeout	シグナリングを実行してから Sora と WebRTC の接続が成功するまでの許容時間を超えた場合に出力されるエラー
answer_timeout	30 秒以内に "type": "answer" を返さなかった場合のエラー
pong_timeout	Ping の応答が返ってこなかった場合のエラー
duplicated_channel_id	同一の channel_id をすでに使用中の場合のエラー
connect_wait_timeout	Open したあと一定時間以内に "type": "connect" のメッセージを送信しなかった場合のエラー
missing_type	type: が JSON に含まれていなかった場合のエラー
invalid_json	JSON 形式が間違っていた場合のエラー
no_media	音声も映像も有効にせずに "type": "connect" を送ってきた場合のエラー
unexpected_type	シグナリングのフローとして許されない type を受信した場合のエラー
unknown_type	未知の type を受信した場合のエラー
validate_error	シグナリングメッセージのバリデーションに失敗した場合のエラー
exceed_max_connections	ライセンスの接続数を超えた接続が来た、またはライセンスの期限が切れている場合のエラー
bad_fingerprint	証明書検証が失敗した場合のエラー
missing_sdp_fingerprint	SDP に fingerprint が含まれていない場合のエラー
too_many_candidate	多くの "type": "candidate" が送られてきた場合のエラー
no_acceptable_node	クラスターのどのノードも受け入れられない場合のエラー
invalid_signaling_params	セッションが残っている状態かつ、接続数が 0 ではない際にシグナリング項目が一致しない接続がきた場合のエラー
block_new_connection	モードが block_new_connection のノードに、接続がきた場合のエラー
block_new_session	ノードのモードが block_new_session かつ、そのノードが担当していないセッションに対しての接続がきた場合のエラー
internal_error	内部エラー

connection_created_wait_timeout

シグナリングを実行してから Sora と WebRTC の接続が成功するまでの許容時間を超えた場合に出力されるエラーです。

多くの場合はシグナリングの WebSocket は確立したものの、WebRTC の接続が失敗している場合に出力されます。

この許容時間はデフォルトでは 30 秒に設定されており、この値は sora.conf の設定 connection_created_wait_timeout で変更できます。

// これは 10 秒待っても、シグナリングが成功しない場合は接続を切断する設定です
connection_created_wait_timeout = 10 s

legacy_signaling_error が true の場合は log/connection_created_wait_timeout_error/ 以下に詳細なログが出力されます。

注釈

connection_created_wait_timeout の値を 0 s にすることで、 意図的に connection_created_wait_timeout のエラーを発生させることができます。

シーケンス図

認証ウェブフックなし

        sequenceDiagram
    autonumber
    participant C as クライアント
    participant S as WebRTC SFU Sora
    participant A as アプリケーションサーバー
    C->>+S: "type": "connect"
    S->>-C: "type": "offer"
    C->>S: "type": "answer"
    C->>S: "type": "candidate"
    note over C,A: WebRTC 確立
    S->>+A: イベントウェブフック<br/>"type": "connection.created"
    A-->-S: 200 OK
    C->>S: "type": "disconnect"
    S->>+A: イベントウェブフック<br/>"type": "connection.destroyed"
    A-->>-S: 200 OK
    S->>C: Websocket Close
    

認証ウェブフックあり

        sequenceDiagram
    autonumber
    participant C as クライアント
    participant S as WebRTC SFU Sora
    participant A as アプリケーションサーバー
    C->>+S: "type": "connect"
    S->>+A: 認証ウェブフック
    A-->>-S: 200 OK<br/>{"allowed": "true"}
    S->>-C: "type": "offer"
    C->>S: "type": "answer"
    C->>S: "type": "candidate"
    note over C,A: WebRTC 確立
    S->>+A: イベントウェブフック<br/>"type": "connection.created"
    A-->-S: 200 OK
    C->>S: "type": "disconnect"
    S->>+A: イベントウェブフック<br/>"type": "connection.destroyed"
    A-->>-S: 200 OK
    S->>C: Websocket Close
    

DataChannel 経由のシグナリング

概要

DataChannel は WebRTC の機能の一つでデータの送受信を行える機能です。 Sora では WebRTC 接続確立後に、シグナリングを WebSocket 経由から DataChannel 経由に切り替えることができます。

目的

WebSocket は TCP ベースのため Head of Line Blocking が存在し、不安定な回線などでパケットが詰まってしまうことがあります。 DataChannel は WebSocket とは異なり、パケットを並列でやりとりできるため、不安定な回線などでもパケットが詰まることが少なくなります。 シグナリングを WebSocket 経由から DataChannel 経由へ切り替える機能を提供することでより安定した接続が維持できます。

SDK 対応状況

• 最新版の JavaScript SDK

  • 対応済みです

• 最新版の iOS SDK

  • 対応済みです

• 最新版の Android SDK

  • 対応済みです

• 最新版の Unity SDK

  • 対応済みです

• 最新版の C++ SDK

  • 対応済みです

• 最新版の Python SDK

  • 対応済みです

• 最新版の C SDK

  • 対応済みです

注意

DataChannel 経由のシグナリングを有効にした場合、ラベルが違うメッセージは並列に処理されます。 そのため、ラベルをまたいだメッセージ間の順序は保証されなくなります。

例えば、WebSocket 経由のシグナリングを利用する場合は、マルチストリーム時の SDP 再交換メッセージ "type": "re-offer" によって発火する ontrack イベントが、 参加通知である "type": "notify", "event_type": "connection.created" イベントより先に発火することが多くなります。 DataChannel 経由のシグナリングでは ontrack と "type": "notify", "event_type": "connection.created" 順序は不定となります。

不明点がある場合はサポートまでお問い合わせください。

制限

• Sora の DataChannel 機能では、クライアント側から DataChannel を作成することはできません。

  • Sora 側で用意した DataChannel の Label のみを利用できます

• Sora の DataChannel 機能では、クライアント側からデータを送信する際には特定の条件を満たす必要があります。

推奨メッセージサイズ

DataChannel で利用している SCTP というプロトコルはもともと小さなメッセージを送るために設計されたため、 大きなメッセージを送るのには向いていません。そのため 1 メッセージサイズは 64 KiB 以内を推奨しています。

64 KiB 以上のメッセージを送る場合は、大きくても 64 KiB 以下のメッセージなるように分割して送るようにしてください。

注釈

Sora は Chrome の仕様に合わせてメッセージサイズの最大値を 256 KiB にしていますが、 64 KiB 以下のメッセージを送ることを推奨しています。

今後

libwebrtc が DataChannel の SCTP の I-DATA チャンクを実装する事で、 より大きなメッセージに対応できるようになる予定です。

• 5696 - Support ndata for SCTP - webrtc

• RFC 8260 - Stream Schedulers and User Message Interleaving for the Stream Control Transmission Protocol

参考資料

• https://developer.mozilla.org/en-US/docs/Web/API/RTCDataChannel/send

• https://developer.mozilla.org/en-US/docs/Web/API/WebRTC_API/Using_data_channels#understanding_message_size_limits

• https://developer.mozilla.org/en-US/docs/Web/API/WebRTC_API/Using_data_channels#concerns_with_large_messages

• https://lgrahl.de/articles/demystifying-webrtc-dc-size-limit.html

• https://www.rfc-editor.org/rfc/rfc8841.html#name-sdp-max-message-size-attrib

シグナリング切り替え

DTLS が確立したタイミングで、シグナリングのやりとりを WebSocket 経由から DataChannel 経由に切り替える仕組みです。

重要

切り替えが完了した場合でも、Sora 側からは WebSocket を切断しません。

シグナリングの切り替えを含めた DataChannel 経由のシグナリングの処理の流れは、DataChannel シグナリング のシーケンス図をご確認ください。

シグナリングの切り替えを有効にする

シグナリングの切り替えを有効にするには、次の 3 つの方法があります。

• "type": "connect" 時に data_channel_signaling を true にする

• 認証成功時に data_channel_signaling を true で払い出す

• sora.conf の default_data_channel_signaling を true にする

Sora SDK を利用している限りは、これらの設定のみで、シグナリングの WebSocket 経由から DataChannel 経由への切り替えを利用できます。

"type": "switched"

DataChannel へ完全に切り替わるタイミングで、 Sora は "type": "switched" を WebSocket 経由でクライアントへ送ります。

DataChannel に切り替わる前に WebSocket が閉じた場合、Sora はその接続が無効と判断して、接続を終了します。

DataChannel へ切り替わった後（"type": "switched" 後）の WebSocket での "type": "ping" / "type": "pong" について

WebSocket から DataChannel に切り替わると、 WebSocket の "type": "ping" を送る間隔が 5 秒から 30 秒に引き延ばされます。 さらに Sora が "type": "pong" を期待しなくなります。

WebSocket が閉じたことを無視する

Sora は、デフォルトでは接続の切断判定に WebSocket を利用しています。WebSocket が閉じると、Sora は接続が切断したと判断します。

ただし、WebSocket が閉じた場合でも、接続が切断したと判断しないようにしたい場面もあるため、 ignore_disconnect_websocket という設定を用意しています。

この設定は sora.conf 、 "type": "connect" または認証成功時の払い出しで指定できます。

この設定を true にすることで、Sora は WebSocket が閉じてもその接続が切断したとは判断せずに、 WebRTC のやりとりを継続します。

注意

"type": "disconnect" を送らずに終了した場合、 DataChannel が切断に気付くまでには早くても 10 秒はかかります。

クライアント側の切断タイミング

もし、 ignore_disconnect_websocket を true にして WebSocket を切断したい場合は、 必ず Sora から "type": "switched" を受け取った後にしてください。

ignore_disconnect_websocket が true の場合でも、 "type": "switched" を受け取る前に WebSocket を切断すると、 Sora はその接続が無効と判断して接続を終了します。

DataChannel への切り替え要否の判断

"type": "offer" に "data_channels" が含まれることを確認することで、DataChannel への切り替えが必要と判断できます。

切り替えが不要な場合は "data_channels" は送られてきません。

{
  "type": "offer",
  "data_channels": [
    {
      "compress": true,
      "label": "stats"
    },
    {
      "compress": true,
      "label": "push"
    },
    {
      "compress": true,
      "label": "notify"
    },
    {
      "compress": true,
      "label": "signaling"
    }
  ]
}

label 単位の圧縮

Sora は、DataChannel 経由のメッセージを zlib/deflate で圧縮した送受信を要求する場合があります。

メッセージの圧縮や展開は Label 毎に要求します。

メッセージの圧縮や展開を要求する Label の情報は、 "type": "offer" 時に data_channels で compress を true に指定してクライアントに送ります。

• Sora は圧縮時に zlib ヘッダーを付けて送ってきます

• Sora は展開時に zlib ヘッダーを必要とします

• Sora は圧縮レベルは default を利用します

圧縮されるデフォルト Label

• signaling

• notify

• push

• stats

設定

default_data_channel_signaling

シグナリングを WebSocket から DataChannel 経由に切り替えるかどうかの設定です。 デフォルトは false です。

default_ignore_disconnect_websocket

シグナリングを DataChannel 経由に切り替えた際に、 WebSocket が閉じても、接続が切断したとみなさない設定です。

デフォルトは false です。

data_channel_signaling_close_message

シグナリングを DataChannel 経由かつ ignore_disconnect_websocket が true の場合に、 signaling ラベルに "type": "close" メッセージを送るかどうかの設定です。

デフォルトは false です。

label とシグナリングのタイプ

重要

これらの DataChannel 経由のシグナリングで Sora が利用するラベルは data_channels で指定することはできません。 data_channels で指定するラベルは リアルタイムメッセージング機能 用で、必ず先頭に # を付ける必要があります。

各 label とシグナリングのタイプについては、DataChannel シグナリング の図も下記の説明と合わせてご確認ください。

"label": "signaling"

順番:

あり

信頼性:

あり

圧縮:

あり

WebRTC が確立する前の type: connect/offer/answer/candiate については、DataChannel 経由のシグナリングでは利用できません。

"type": "re-offer" は "label": "signaling" に送られてきます。

"type": "re-answer" 、 "type": "disconnect" は "label": "signaling" に送ります。

"type": "ping" と "type": "pong" は DataChannel では利用しません。

"type": "re-offer"

重要

"type": "update" の代わりに Sora からは "type": "re-offer" が送られてきます。

マルチストリーム利用時に SDP 再交換を行う際に、 Sora から送られてきます。

"type": "re-answer"

重要

"type": "update" の代わりに Sora へ "type": "re-answer" を送ります。

マルチストリーム利用時に SDP 再交換を行う際に、 Sora へ送ります。

"type": "disconnect"

接続を切断することを通知するために Sora へ送ります。

"type": "close"

DataChannel シグナリングで新しく追加されたタイプです

Sora から切断する場合に送ります。ただし、 "type": "disconnect" が送られてきた時は送りません。

data_channel_signaling_close_message が true かつ、 ignore_disconnect_websocket が true の場合に送ります。

"label": "notify"

順番:

あり

信頼性:

あり

圧縮:

あり

"type": "notify" は "label": "notify" に送られてきます。

中身は WebSocket 経由の値と変わりません。

"label": "push"

順番:

あり

信頼性:

あり

圧縮:

あり

"type": "push" は "label": "push" に送られてきます。

中身は WebSocket 経由の値と変わりません。

"label": "stats"

順番:

あり

信頼性:

あり

圧縮:

あり

DataChannel シグナリングで新しく追加されたタイプです

今まで "type": "ping" と "type": "pong" 内部でやりとりしていた stats は DataChannel 経由では独立しました。

Sora から {"type": "req-stats"} が送られてきたら、 {"type": "stats", "reports": [{"id": "...", ...}, ...]} で reports の中に、 WebSocket 経由時には "type": "pong" で入れていた統計情報を入れて送り返してください。

"type": "req-stats"

DataChannel シグナリングで新しく追加されたタイプです

Sora からクライアントに stats 情報を要求します。

"type": "stats"

クライアントから Sora に stats 情報を送ります。

DataChannel 関連の設定

data_channel_stats_timer_interval

シグナリングを DataChannel 経由に切り替えた際に、 Sora からクライアントへ統計情報の要求を送る間隔の設定です。

デフォルトは 60 s です。

シーケンス図

認証ウェブフックあり

        sequenceDiagram
    autonumber
    participant C as クライアント
    participant S as Sora
    participant A as アプリケーションサーバー
    C->>+S: "type": "connect"
    S->>+A: 認証ウェブフック
    A-->>-S: 200 OK<br/>{"allowed": "true"}
    S->>-C: "type": "offer"
    C->>S: "type": "answer"
    C->>S: "type": "candidate"
    note over C,A: WebRTC 確立
    S->>+A: イベントウェブフック<br/>"type": "connection.created"
    A-->-S: 200 OK
    note over C,A: DataChannel 確立
    S->>C: "type": "switched"
    note over C,A: これ以降は DataChannel が利用される
    

DataChannel シグナリング

        sequenceDiagram
    autonumber
    participant C as クライアント
    participant S as Sora
    note over C,S: WebRTC 確立
    note over C,S: DataChannel 確立
    S->>C: "type": "switched"
    note over C,S: これ以降は DataChannel が利用される
    S->>C: "type": "re-offer"
    note right of S: label: signaling
    C->>S: "type": "re-answer"
    note left of C: label: signaling
    S->>C: "type": "notify"
    note right of S: label: notify
    S->>C: "type": "push"
    note right of S: label: push
    S->>C: "type": "req-stats"
    note right of S: label: stats
    C->>S: "type": "stats"
    note left of C: label: stats
    

シグナリングの型定義

この章ではシグナリングの型について説明します。 シグナリングの仕様については シグナリング を参照ください。

型の表記は TypeScript で記述します。

基本的なデータ型

// JSON 値を表します。
// 仕様は RFC 8259 に従います。
type JSONValue =
  | null
  | boolean
  | number
  | string
  | JSONValue[]
  | { [key: string]: JSONValue | undefined };

// UnixTime
// 例: 1704067199
type UnixTime = number;

// RFC3339 UTC (マイクロ秒)
// 例: 2023-12-31T23:59:59.999999Z
type Timestamp = string;

// ストリームの種別
type Role = "sendrecv" | "sendonly" | "recvonly";

// サイマルキャストで視聴する映像の種類
type SimulcastRid = "r0" | "r1" | "r2";

// 音声の設定
type Audio =
  | boolean
  | {
      codec_type?: AudioCodecType;
      bit_rate?: number;
      opus_params?: OpusParams;
    };

type OpusParams = {
  channels?: number;
  maxplaybackrate?: number;
  minptime?: number;
  ptime?: number;
  stereo?: boolean;
  sprop_stereo?: boolean;
  useinbandfec?: boolean;
  usedtx?: boolean;
};

// 映像の設定
type Video =
  | boolean
  | {
      codec_type?: VideoCodecType;
      bit_rate?: number;
      // 利用するには sora.conf で signaling_vp9_params = true を設定する必要があります
      vp9_params?: VP9Params;
      // 利用するには sora.conf で signaling_av1_params = true を設定する必要があります
      av1_params?: AV1Params;
      // 利用するには sora.conf で signaling_h264_params = true を設定する必要があります
      h264_params?: H264Params;
      // 利用するには sora.conf で signaling_h265_params = true を設定する必要があります
      h265_params?: H265Params;
    };

type VP9Params = {
  // 0..3
  profile_id?: number;
};

type AV1Params = {
  // 0..2
  profile?: number;
};

type H264Params = {
  profile_level_id?: string;
  // sora.conf で h264_b_frame = true を設定する必要があります
  b_frame?: boolean;
};

type H265Params = {
  level_id?: number;
  // sora.conf で h265_b_frame = true を設定する必要があります
  b_frame?: boolean;
};

// 音声コーデックの種類
type AudioCodecType = "OPUS";

// 映像コーデックの種類
type VideoCodecType = "VP9" | "VP8" | "AV1" | "H264" | "H265";

// DataChannel の方向
type Direction = "sendrecv" | "sendonly" | "recvonly";

type DataChannelMessagingHeaderFieldType = "sender_connection_id";

type DataChannelMessagingHeaderField = {
  type: DataChannelMessagingHeaderFieldType;
  // * length は "type": "offer" 時の data_channels にのみ含まれる
  // * length は"type": "connect" 時には指定できない
  // * length は認証成功時の払い出し時には指定できない
  length?: number;
};

// DataChannels
type DataChannel = {
  label: string;
  direction: Direction;
  ordered?: boolean;
  max_packet_life_time?: number;
  max_retransmits?: number;
  protocol?: string;
  compress?: boolean;
  header?: DataChannelMessagingHeaderField[];
};

type TurnTransportType = "udp" | "tcp";

type ForwardingFilterRuleField = "connection_id" | "client_id" | "kind";

type ForwardingFilterRuleOperator = "is_in" | "is_not_in";

type ForwardingFilterRuleKindValue = "audio" | "video";

type ForwardingFilterRule = {
  field: ForwardingFilterRuleField;
  operator: ForwardingFilterRuleOperator;
  values: [string];
};

type ForwardingFilterAction = "block" | "allow";

type ForwardingFilter = {
  version?: string;
  metadata?: JSONValue;
  name?: string;
  priority?: number;
  action?: ForwardingFilterAction;
  rules: [[ForwardingFilterRule]];
};

type SoraClientType =
  | "Sora JavaScript SDK"
  | "Sora iOS SDK"
  | "Sora Android SDK"
  | "Sora Unity SDK"
  | "Sora C++ SDK"
  | "Sora Python SDK"
  | "Sora C SDK"
  | "OBS-Studio-WHIP"
  | "OBS-Studio-WHEP";

// SoraClient
type SoraClient = {
  environment?: string;
  raw?: string;
  type?: SoraClientType;
  version?: string;
  commit_short?: string;
  libwebrtc?: string;
};

// RTCRtpCodecParameters
// https://www.w3.org/TR/webrtc/#dom-rtcrtpcodecparameters
type SimulcastCodec = {
  // payloadType や channels は省略
  mimeType: string;
  clockRate: number;
  sdpFmtpLine?: string;
};

// RTCRtpEncodingParameters
// https://w3c.github.io/webrtc-pc/#dom-rtcrtpencodingparameters
type SimulcastEncoding = {
  // https://www.w3.org/TR/webrtc/#dom-rtcrtpcodingparameters-rid
  rid: SimulcastRid;
  // https://www.w3.org/TR/webrtc/#dom-rtcrtpencodingparameters-active
  active?: boolean;
  // https://www.w3.org/TR/webrtc/#dom-rtcrtpencodingparameters-maxframerate
  maxFramerate?: number;
  // https://www.w3.org/TR/webrtc/#dom-rtcrtpencodingparameters-maxbitrate
  maxBitrate?: number;
  // https://www.w3.org/TR/webrtc/#dom-rtcrtpencodingparameters-scaleresolutiondownby
  scaleResolutionDownBy?: number;
  // https://www.w3.org/TR/webrtc/#dom-rtcrtpcodec
  codec?: SimulcastCodec;
  // https://w3c.github.io/webrtc-extensions/#dom-rtcrtpencodingparameters-scaleresolutiondownto
  // @ts-ignore: RTCResolutionRestriction は typed で未定義のため型チェックを無視(型定義が追加され次第 ts-ignore を削除)
  scaleResolutionDownTo?: RTCResolutionRestriction;
  // https://w3c.github.io/webrtc-extensions/#dom-rtcrtpencodingparameters-adaptiveptime
  adaptivePtime?: boolean;
  // https://www.w3.org/TR/webrtc-svc/#dom-rtcrtpencodingparameters-scalabilitymode
  scalabilityMode?: string;
};

シグナリング

シグナリングは「クライアントからサーバー (Sora) に送信される」メッセージと「サーバー (Sora) からクライアントに送信される」メッセージに分かれます。

クライアントからサーバーに送信されるメッセージ

• connect

• answer

• candidate

• re-answer

• pong

  • WebSocket 経路利用時のみ

• disconnect

• stats

  • DataChannel 経路利用時のみ

Server からクライアントに送信されるメッセージ

• offer

• re-offer

• ping

  • WebSocket 経路利用時のみ

• push

• notify

• req-stats

  • DataChannel 経路利用時のみ

完全な型定義

// シグナリング
type SignalingMessage = SendSignalingMessage | ReceiveSignalingMessage;

// クライアントから Sora に送信されるメッセージ
type SendSignalingMessage =
  | SignalingConnectMessage
  | SignalingAnswerMessage
  | SignalingReAnswerMessage
  | SignalingCandidateMessage
  | SignalingPongMessage
  | SignalingDisconnectMessage
  | SignalingStatsMessage;

// Sora からクライアントに送信されるメッセージ
type ReceiveSignalingMessage =
  | SignalingRedirectMessage
  | SignalingOfferMessage
  | SignalingReOfferMessage
  | SignalingPingMessage
  | SignalingPushMessage
  | SignalingNotifyMessage
  | SignalingReqStatsMessage
  | SignalingSwitchedMessage
  | SignalingCloseMessage;

// type: "connect"
type SignalingConnectMessage = {
  type: "connect";
  role: Role;
  channel_id: string;

  client_id?: string;
  bundle_id?: string;

  audio?: Audio;
  video?: Video;

  // multistream: false は 2025 年 6 月リリースの Sora にて廃止します
  // 未指定の場合は true として扱われます
  multistream?: boolean;

  // 未指定の場合は false として扱われます
  simulcast?: boolean;
  simulcast_rid?: SimulcastRid;
  // sora.conf にて simulcast_multicodec = true を有効にする必要があります
  simulcast_multicodec?: boolean;

  // 未指定の場合は false として扱われます
  spotlight?: boolean;
  // 非推奨です
  // session.created の戻り値をご利用ください
  spotlight_number?: number;
  spotlight_focus_rid?: SimulcastRid | "none";
  spotlight_unfocus_rid?: SimulcastRid | "none";

  metadata?: JSONValue;
  signaling_notify_metadata?: JSONValue;

  data_channel_signaling?: boolean;
  data_channels?: DataChannel[];
  ignore_disconnect_websocket?: boolean;

  forwarding_filters?: ForwardingFilter[];
  // forwarding_filter は 2025 年 12 月リリース予定の Sora にて廃止します
  // 今後は forwarding_filters をご利用ください
  forwarding_filter?: ForwardingFilter;

  // type: redirect で戻されて再度 type: connect で接続するときに有効にする必要があります
  redirect?: boolean;

  audio_streaming_language_code?: string;

  sdp?: string;

  sora_client?: string;
  environment?: string;
  libwebrtc?: string;
};

// type: "redirect"
type SignalingRedirectMessage = {
  type: "redirect";
  location: string;
};

type Mid = {
  audio?: string;
  video?: string;
};

// type: "offer"
type SignalingOfferMessage = {
  type: "offer";
  sdp: string;

  mid: Mid;
  version: string;

  multistream: boolean;
  simulcast: boolean;
  simulcast_multicodec: boolean;
  spotlight: boolean;

  channel_id: string;
  session_id: string;
  client_id: string;
  bundle_id: string;
  connection_id: string;

  audio: boolean;
  // audio が false または role が recvonly の際は含まれません
  audio_codec_type?: AudioCodecType;
  // audio が false または role が recvonly の際は含まれません
  audio_bit_rate?: number;

  video: boolean;
  // audio が false または role が recvonly の際は含まれません
  video_codec_type?: VideoCodecType;
  // audio が false または role が recvonly の際は含まれません
  video_bit_rate?: number;

  metadata?: JSONValue;
  config?: RTCConfiguration;
  encodings?: SimulcastEncoding[];

  data_channels?: DataChannel[];
};

// type: "answer"
type SignalingAnswerMessage = {
  type: "answer";
  sdp: string;
};

// type: "candidate"
type SignalingCandidateMessage = {
  type: "candidate";
  candidate: string;
};

// type: "switched"
type SignalingSwitchedMessage = {
  type: "switched";
  ignore_disconnect_websocket: boolean;
};

// type: "re-offer"
type SignalingReOfferMessage = {
  type: "re-offer";
  sdp: string;
};

// type: "re-answer"
type SignalingReAnswerMessage = {
  type: "re-answer";
  sdp: string;
};

// type: "close"
// サーバー側からの切断を通知するためのメッセージ
// data_channel_signaling = true かつ ignore_disconnect_websocket = true の場合のみ
// sora.conf にて data_channel_signaling_close_message = true を有効にする必要がある
type SignalingCloseMessage = {
  type: "close";
  code: number;
  reason: string;
};

// type: "ping"
type SignalingPingMessage = {
  type: "ping";
  stats?: boolean;
};

// type: "pong"
type SignalingPongMessage = {
  type: "pong";
  stats?: RTCStatsReport[];
};

// type: "push"
type SignalingPushMessage = {
  type: "push";
  data: Record<string, unknown>;
};

// type: "disconnect"
type SignalingDisconnectMessage = {
  type: "disconnect";
  reason: string;
};

// type: "req-stats"
// DataChannel シグナリング
type SignalingReqStatsMessage = {
  type: "req-stats";
};

// type: "stats"
// DataChannel シグナリング
type SignalingStatsMessage = {
  type: "stats";
  reports: RTCStatsReport[];
};

// type: "notify"
type SignalingNotifyMessage =
  | SignalingNotifyConnectionCreated
  | SignalingNotifyConnectionUpdated
  | SignalingNotifyConnectionDestroyed
  | SignalingNotifySpotlightFocused
  | SignalingNotifySpotlightUnfocused
  | SignalingNotifyRecordingStarted
  | SignalingNotifyRecordingStopped
  | SignalingNotifyForwardingBlocked
  | SignalingNotifyForwardingAllowed
  | SignalingNotifyNetworkStatus
  | SignalingNotifyIceConnectionStateChanged
  // 2025 年 12 月リリース予定の Sora にて廃止します
  | SignalingNotifyRtpStreamPause
  // 2025 年 12 月リリース予定の Sora にて廃止します
  | SignalingNotifyRtpStreamResume;

// 接続中のクライアントの情報
type SignalingNotifyMetadata = {
  client_id?: string;
  bundle_id?: string;
  connection_id?: string;
  ice_connection_state?: SignalingNotifyIceConnectionState;
  authn_metadata?: JSONValue;
  authz_metadata?: JSONValue;
  metadata?: JSONValue;
  timestamp?: Timestamp;
};

// "connection.created",
type SignalingNotifyConnectionCreated = {
  type: "notify";
  event_type: "connection.created";
  timestamp?: Timestamp;
  role: Role;
  session_id?: string;
  client_id?: string;
  bundle_id?: string;
  connection_id?: string;
  audio?: boolean;
  video?: boolean;
  authn_metadata?: JSONValue;
  authz_metadata?: JSONValue;
  metadata?: JSONValue;
  data?: SignalingNotifyMetadata[];
  minutes: number;
  channel_connections: number;
  channel_sendrecv_connections: number;
  channel_sendonly_connections: number;
  channel_recvonly_connections: number;
  turn_transport_type: TurnTransportType;
};

// "connection.updated"
type SignalingNotifyConnectionUpdated = {
  type: "notify";
  event_type: "connection.updated";
  role: Role;
  session_id?: string;
  client_id?: string;
  bundle_id?: string;
  connection_id?: string;
  audio?: boolean;
  video?: boolean;
  authn_metadata?: JSONValue;
  authz_metadata?: JSONValue;
  metadata?: JSONValue;
  minutes: number;
  channel_connections: number;
  channel_sendrecv_connections: number;
  channel_sendonly_connections: number;
  channel_recvonly_connections: number;
  turn_transport_type: "udp" | "tcp";
};

// "connection.destroyed"
type SignalingNotifyConnectionDestroyed = {
  type: "notify";
  event_type: "connection.destroyed";
  role: Role;
  session_id?: string;
  client_id?: string;
  bundle_id?: string;
  connection_id?: string;
  audio?: boolean;
  video?: boolean;
  minutes: number;
  authn_metadata?: JSONValue;
  authz_metadata?: JSONValue;
  metadata?: JSONValue;
  channel_connections: number;
  channel_sendrecv_connections: number;
  channel_sendonly_connections: number;
  channel_recvonly_connections: number;
  turn_transport_type: "udp" | "tcp";
};

// "spotlight.focused"
type SignalingNotifySpotlightFocused = {
  type: "notify";
  event_type: "spotlight.focused";
  client_id: string | null;
  bundle_id: string | null;
  connection_id: string;
  audio: boolean;
  video: boolean;
  fixed: boolean;
  spotlight_number: number;
};

// "spotlight.unfocused"
type SignalingNotifySpotlightUnfocused = {
  type: "notify";
  event_type: "spotlight.unfocused";
  client_id: string | null;
  bundle_id: string | null;
  connection_id: string;
  audio: boolean;
  video: boolean;
  spotlight_number: number;
};

// "recording.started"
type SignalingNotifyRecordingStarted = {
  type: "notify";
  event_type: "recording.started";
  client_id: string | null;
  bundle_id: string | null;
  connection_id: string;
};

// "recording.stopped"
type SignalingNotifyRecordingStopped = {
  type: "notify";
  event_type: "recording.stopped";
  client_id: string | null;
  bundle_id: string | null;
  connection_id: string;
};

// "forwarding.blocked"
type SignalingNotifyForwardingBlocked = {
  type: "notify";
  event_type: "forwarding.blocked";
  kind: ForwardingFilterRuleKindValue;
  destination_connection_id: string;
  source_connection_id: string;
};

// "forwarding.allowed"
type SignalingNotifyForwardingAllowed = {
  type: "notify";
  event_type: "forwarding.allowed";
  kind: ForwardingFilterRuleKindValue;
  destination_connection_id: string;
  source_connection_id: string;
};

// "audio-streaming.failed"
type SignalingNotifyAudioStreamingFailed = {
  type: "notify";
  event_type: "audio-streaming.failed";
  failed_connection_id: string;
};

// "network.status"
type SignalingNotifyNetworkStatus = {
  type: "notify";
  event_type: "network.status";
  unstable_level: 0 | 1 | 2 | 3;
};

type SignalingNotifyIceConnectionState =
  | "connected"
  | "checking"
  | "disconnected";

// "ice_connection_state.changed"
type SignalingNotifyIceConnectionStateChanged = {
  type: "notify";
  event_type: "ice-connection-state.changed";
  timestamp: Timestamp;
  connection_id: string;
  current_state: SignalingNotifyIceConnectionState;
  previous_state: SignalingNotifyIceConnectionState;
};

// 2025 年 12 月リリース予定の Sora にて廃止します
type SignalingNotifyRtpStreamPause = {
  type: "notify";
  event_type: "rtp_stream.pause";
  recv_connection_id: string;
  send_connection_id: string;
};

// 2025 年 12 月リリース予定の Sora にて廃止します
type SignalingNotifyRtpStreamResume = {
  type: "notify";
  event_type: "rtp_stream.resume";
  stream_id: string;
};

シグナリング通知

概要

シグナリング通知は、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 の値が採用されます。

表 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

デフォルト:

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, authn_metadata

  • json

  • シグナリング通知メタデータ で利用する項目です。

  • sora.conf で、 signaling_notify_metadata を false にすることでこの値は含まれなくなります

• data

  • json 型のリスト

    • json 型の中身は、以下の sora.conf の設定により変化します

      • signaling_notify_client_id

      • signaling_notify_bundle_id

      • signaling_notify_connection_id

      • signaling_notify_connection_created_timestamp

      • signaling_notify_metadata

    • 上記の設定が全て 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 が等しいクライアントに対しては、このイベントは通知されません。

重要

新規にチャネルに参加したクライアントには connection.created の後に spotlight.focused が通知され、 既に参加しているどのクライアントがスポットライト機能でフォーカスされているのかを知ることができます。

"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.changed"

{
  "type": "notify",
  "event_type": "ice-connection-state.changed",
  "connection_id": "MV7VSJTA092V70F4796DCS9BAR",
  "timestamp": "2024-12-06T03:32:58.091149Z",
  "current_state": "connected",
  "previous_state": "checking"
}

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

これは実験的機能です

ネットワークのシグナリング通知は、上記の 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
    

シグナリング通知メタデータ

概要

signaling_notify_metadata はクライアントの状態が変化したときに送られる、シグナリング通知に含まれるメタデータです。

シグナリング接続時、または認証ウェブフック成功の戻り値に signaling_notify_metadata で JSON 値を指定することで利用できるようになります。

新しく参加した際に、すでにそのチャネルに参加しているクライアントの signaling_notify_metadata の値がリストで共有されます。

注意

シグナリング通知メタデータの認証成功時払い出しによる上書き

接続時に指定したシグナリング通知メタデータは、認証成功時に signaling_notify_metadata の払い出しによって上書きされます。

詳細は 接続時のシグナリング通知メタデータを認証払い出し時のシグナリング通知メタデータで上書き をご確認ください。

シグナリング通知メタデータ拡張

シグナリング通知メタデータ拡張機能 を有効にしている場合、 metadata はシグナリング通知メタデータ拡張で利用されるため、 signaling_notify_metadata で指定した値は metadata には含まれません。

• 接続時に指定したシグナリング通知メタデータは authn_metadata として含まれます

• 認証成功時に払い出したシグナリング通知メタデータは authz_metadata として含まれます

設定

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

設定を行ったときの出力例は sora.conf の設定内容と connection.created 出力の例 をご確認ください。

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

"type": "connect" 接続時に signaling_notify_metadata で JSON 値を指定できます。

{
  "type": "connect",
  "role": "sendrecv",
  "channel_id": "sora",
  "signaling_notify_metadata": {"authn": true}
}

シグナリング接続時に指定した値は、通知時に metadata として通知されます。 また authn_metadata としても通知されます。

"data" にはすでにそのチャネルが参加しているクライアントの情報がリストで含まれます。

{
  "type": "notify",
  "event_type": "connection.created",
  "authn_metadata": {"authn": true},
  "metadata": {"authn": true}
  "data": [
    {
      "connection_id": "KKBFZTQXDD6H7FD2NYCQX8S474",
      "authz_metadata": "xyz",
      "metadata": "xyz"
    },
    {
      "connection_id": "4D40YWH56N5S99QHJV6GAPNHB0",
      "authn_metadata": 10,
      "metadata": 10
    }
  ]
}

シグナリング接続時に指定できるシグナリング通知メタデータのサイズ制限

重要

シグナリング接続時に指定できるシグナリング通知メタデータのサイズはのデフォルトは 64 KiB (65536 バイト) です。

メタデータのサイズはメタデータ拡張機能をエンコード済みの JSON 、つまり文字列としてサイズを計算します。

例えば {"a":"b"} の場合は 9 バイトで、 {"a":"b","c":1200} は 18 バイトです。

最大値を変更したい場合は sora.conf の signaling_notify_authn_metadata_max_size を変更してください。

また、シグナリング通知メタデータを接続時に指定できなくする場合は signaling_notify_authn_metadata_max_size を 0 にしてください。

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

認証ウェブフックでの戻り値は、シグナリング接続時に指定した値を上書きします。

{
  "allowed": true,
  "signaling_notify_metadata": "authz"
}

認証ウェブフックの戻り値で指定した値は、通知時に metadata としても通知されます。 また authz_metadata としても通知されます。

"data" にはすでにそのチャネルが参加しているクライアントの情報がリストで含まれます。

{
  "type": "notify",
  "event_type": "connection.created",
  "authn_metadata": "authz",
  "metadata": "authz"
  "data": [
    {
      "connection_id": "KKBFZTQXDD6H7FD2NYCQX8S474",
      "authz_metadata": "xyz",
      "metadata": "xyz"
    },
    {
      "connection_id": "4D40YWH56N5S99QHJV6GAPNHB0",
      "authn_metadata": 10,
      "metadata": 10
    }
  ]
}

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

{
  "type": "notify",
  "authz_metadata": {"username": "alice"},
  "metadata": {"username": "alice"},
}

認証成功時払い出しのシグナリング通知メタデータのサイズ制限

制限はありません。

接続時のシグナリング通知メタデータを認証払い出し時のシグナリング通知メタデータで上書き

接続時に指定したシグナリング通知メタデータは、 認証成功時の払い出しのシグナリング通知メタデータで上書きされます。

接続時に指定したシグナリング通知メタデータ

接続時に指定したシグナリング通知メタデータを "authn" と指定しています。

{
  "type": "connect",
  "role": "sendrecv",
  "channel_id": "sora",
  "signaling_notify_metadata": {"authn": true}
}

認証成功時に払い出したシグナリング通知メタデータ

認証成功時にシグナリング通知メタデータを "authz" と払い出しています。

{
  "allowed": true,
  "signaling_notify_metadata": "authz"
}

クライアントへ送られるシグナリング通知メタデータ

認証成功時に払い出したシグナリング通知メタデータである "authz" が metadata として通知されます。

{
  "type": "notify",
  "event_type": "connection.created",
  "authn_metadata": {"authn": true},
  "authz_metadata": "authz",
  "metadata": "authz",
  "data": []
}

シグナリング通知メタデータ拡張機能

警告

シグナリング通知メタデータ拡張機能は実験的機能のため正式版では仕様が変更される可能性があります

概要

シグナリング通知メタデータ拡張機能(以降メタデータ拡張機能)は、 Sora に API 経由で変更できるメタデータを接続ごとに保持する機能です。

• メタデータは新規参加者にシグナリング通知経由で共有されます

• メタデータを API 経由で変更した際に変更をプッシュで通知することもできるようになります

目的

接続ごとに持たせたメタデータを API 経由で変更し、 既存参加者にはプッシュで通知、新規参加者には参加時に通知するような仕組みを提供することです。

シグナリング通知メタデータの課題

今までのシグナリング通知メタデータは、接続時の指定した値を認証成功時の払い出しで上書きするといったものでした。 そのため 接続ごとの状態変更 を管理するために別の仕組みを用意する必要がありました。

メタデータ拡張を利用することで、接続ごとの状態、 例えば「忙しい」といったプレゼンス情報を Sora で管理し、他の接続に通知できるようになります。

メタデータ拡張機能を利用することで実現できること

• 参加者のプレゼンス状態を変更した際に既存参加者にはプッシュで共有し、新規参加者にはシグナリング通知で共有できるようになる

• マイクミュート状態を既存参加者にはプッシュで共有し、新規参加者にはシグナリング通知で共有できるようになる

• 画面共有中の配信者を既存参加者にはプッシュで共有し、新規参加者にはシグナリング通知で共有できるようになる

今まで別の場所で保持していた変更可能な状態を Sora 側で持つことができます。

メタデータ拡張機能の有効 / 無効について

メタデータ拡張機能はデフォルトで無効になっています。

sora.conf の指定

メタデータ拡張機能を有効にするには設定を有効にする必要があります。

signaling_notify_metadata_ext = true

有効にした際の変更点

• API 経由で connection.created 時に共有される metadata が key / value 形式で指定できるようになります

• シグナリング通知時に送られる metadata は API でのみ反映され、接続時や認証時の signaling_notify_metadata は反映されません

• シグナリング通知時に送られる metadata の初期値は {} で空オブジェクトです

• 接続時に指定していた signaling_notify_metadata は authn_metadata を利用してください

  • 指定しない場合は authn_metadata はシグナリング通知時に含まれません

• 認証成功時に払い出していた signaling_notify_metadata は authz_metadata を利用してください

  • 指定しない場合は authz_metadata はシグナリング通知時に含まれません

メタデータ拡張機能の特徴

• API 実行時に "push": true を指定することで、メタデータの変更と通知を同時に行えます

  • 通知は "type": "push" で行われます

• API 経由で以外では変更できません

メタデータ拡張機能の制限

重要

1 接続が保持できるメタデータ拡張のサイズは最大 32 KiB (32768 バイト) です。

メタデータのサイズはメタデータ拡張機能をエンコード済みの JSON 、つまり文字列としてサイズを計算します。

例えば {"a":"b"} の場合は 9 バイトで、 {"a":"b","c":1200} は 18 バイトです。

メタデータ拡張の初期値

メタデータ拡張機能の初期値を認証ウェブフックの成功時に払い出すことができます。

{
   "allowed": true,
   "signaling_notify_metadata_ext": {
      "abc": 10
   }
}

払い出す値は JSON Object である必要があります。

利用方法

開発ツールを利用します

注意

シグナリング通知メタデータ拡張 API が有効になるのはイベントウェブフックの connection.created が通知されてからです。

1. シグナリング通知メタデータ拡張機能を有効にしましょう

   • sora.conf の signaling_notify_metadata_ext = true を設定します

2. まず１つ目の接続をしてみましょう

   • 開発ツールの マルチストリーム送受信 を開いて、右上の debug にチェックを入れて connect を押してください

   • channel_id はデフォルトの sora のままで問題ありません

   • connection_id を PPD3R008XH0S11CG535JFKQFH0 とします

3. この時点で、まだ PPD3R008XH0S11CG535JFKQFH0 の metadata は {} です

4. PPD3R008XH0S11CG535JFKQFH0 のメタデータに新しいアイテムを追加してみましょう

   • HTTP API の PutSignalingNotifyMetadataItem を利用します

   • key を "abc" とし value を 10 としてアイテムを追加します

   • ついでにプッシュ通知も行うように push を true にします

   http POST 127.0.0.1:3000/ x-sora-target:Sora_20201124.PutSignalingNotifyMetadataItem \
       channel_id=sora connection_id=PPD3R008XH0S11CG535JFKQFH0 \
       key=abc value:=10 push:=true
   HTTP/1.1 200 OK
   access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
   access-control-allow-methods: POST, OPTIONS
   access-control-allow-origin: http://127.0.0.1:5000
   access-control-max-age: 1000
   content-length: 10
   content-type: application/json
   date: Wed, 25 Nov 2020 08:16:44 GMT
   server: Cowboy
   
   {
       "abc": 10
   }
   

   • Push タブにプッシュ通知が来ていたら成功です

5. 項目に値が入っているか確認してみましょう

   http POST 127.0.0.1:3000/ x-sora-target:Sora_20201124.GetSignalingNotifyMetadata \
       channel_id=sora connection_id=PPD3R008XH0S11CG535JFKQFH0 -vvv
   
   HTTP/1.1 200 OK
   access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
   access-control-allow-methods: POST, OPTIONS
   access-control-allow-origin: http://127.0.0.1:5000
   access-control-max-age: 1000
   content-length: 10
   content-type: application/json
   date: Wed, 25 Nov 2020 08:14:34 GMT
   server: Cowboy
   
   {
       "abc": 10
   }
   

6. 新しい接続に追加したアイテムが反映されているメタデータが通知されるか確認してみましょう

   • 別のタブで マルチストリーム送受信 を開いて、debug にチェックを入れて connect して Notify タブを見てみて下さい

   • data の中に connection_id: PPD3R008XH0S11CG535JFKQFH0 があり、その metadata が先程作成した値であれば成功です

Sora クライアント要求仕様

概要

Sora SDK や Sora クライアントの開発者に向けた資料です。

クライアント側の終了処理条件

RTCPeerConnectionState が failed になる

すべての接続において RTCPeerConnectionState が failed になったタイミングで "type": "disconnect" は送らず、 クライアント側で終了処理をしてください。

WebSocket のみ

• RTCPeerConnectionState が failed になった

  • 終了処理に入る

• WebSocket onclose が上がった

  • 終了処理に入る

• WebSocket onerror が上がった

  • 終了処理に入る

WebSocket と DataChannel

• RTCPeerConnectionState が failed になった

  • 終了処理に入る

• WebSocket onclose が上がった

  • "type": "switched" が送られてきていない

    • 終了処理に入る

  • "type": "switched", "ignore_disconnect_websocket": true が送られてきていた

    • 何もしない

  • "type": "switched", "ignore_disconnect_websocket": false が送られてきていて、 RTCPeerConnectionState が failed になっている

    • 終了処理に入る

  • "type": "switched", "ignore_disconnect_websocket": false が送られてきていて、 RTCPeerConnectionState が failed になっていない

    • DataChanel で "type": "disconnect", reason: "WEBSOCKET-ONCLOSE" を送ることを試みる

    • 終了処理に入る

• WebSocket onerror が上がった

  • "type": "switched" が送られてきていない

    • 終了処理に入る

  • "type": "switched", "ignore_disconnect_websocket": true が送られてきていた

    • 何もしない

  • "type": "switched", "ignore_disconnect_websocket": false が送られてきていて、 RTCPeerConnectionState が failed になっている

    • 終了処理に入る

  • "type": "switched", "ignore_disconnect_websocket": false が送られてきていて、 RTCPeerConnectionState が failed になっていない

    • DataChanel で "type": "disconnect", reason: "WEBSOCKET-ONERROR" を送ることを試みる

    • 終了処理に入る

DataChannel のみ

• RTCPeerConnectionState が failed になった

  • 終了処理に入る

DataChannel の終了

Sora SDK の切断タイムアウトのデフォルト値は 3000 ミリ秒です。

• RTCDataChannel onclose が上がった

  • RTCDataChannel onerror にコールバックをセットしている場合

    • 終了処理に入る、または切断タイマーを開始し、すべての RTCDataChannel の readyState がすべて closed にならずタイムアウトした場合は終了処理にはいる

  • RTCDataChannel onerror にコールバックをセットしていない場合

    • 終了処理に入る

• RTCDataChannel onerror が上がった

  • 終了処理に入る

アプリケーション経由の "type": "disconnect" 送信後の終了処理

Sora SDK の切断タイムアウトのデフォルト値は 3000 ミリ秒です。

WebSocket のみ

data_channel_signaling: false の場合。

• WebSocket 経由で "type": "disconnect", reason: "NO-ERROR" を送る

  • 終了処理に入る、または切断タイマーを開始し、WebSocket onclose が上がらずタイムアウトした場合は終了処理に入る

WebSocket と DataChannel

data_channel_signaling: true で ignore_disconnect_websocket: false の場合。

• "type": "switched" が送られて来ていない

  • WebSocket 経由で "type": "disconnect", reason: "NO-ERROR" を送る

  • 終了処理にはいる、または切断タイマーを開始し、WebSocket onclose が上がらずタイムアウトした場合は終了処理にはいる

• "type": "switched", "ignore_disconnect_websocket": false が送られてきていて、 WebSocket は切断していない

  • DataChannel 経由で "type": "disconnect", reason: "NO-ERROR" を送る

  • RTCDataChannel onerror にコールバックをセットしている場合

    • 終了処理に入る、または切断タイマーを開始し、WebSocket の onclose かつ、すべての RTCDataChannel の readyState がすべて closed にならずタイムアウトした場合は終了処理にはいる

  • RTCDataChannel onerror にコールバックをセットしていない場合

    • 終了処理に入る

DataChannel のみ

data_channel_signaling: true で ignore_disconnect_websocket: true の場合。

• "type": "switched" が送られて来ていない

  • WebSocket 経由で "type": "disconnect", reason: "NO-ERROR" を送る

  • 切断タイマーを開始する

  • WebSocket onclose が上がらずタイムアウトした場合は終了処理に入る

• "type": "switched", "ignore_disconnect_websocket": true が送られてきていて、 WebSocket も切断している

  • DataChannel 経由で "type": "disconnect", reason: "NO-ERROR" を送る

  • RTCDataChannel onerror にコールバックをセットしている場合

    • 終了処理に入る、または切断タイマーを開始し、すべての RTCDataChannel の readyState がすべて closed にならずタイムアウトした場合は終了処理にはいる

  • RTCDataChannel onerror にコールバックをセットしていない場合

    • 終了処理に入る

異常発生による終了

シグナリングの異常

終了処理に入ってください。

シグナリング以外の異常

"type": "disconnect", reason: "INTERNAL-ERROR" を送り、終了処理に入って下さい。

ライセンスエラーによる終了

"type": "connect" を送った際、ライセンスの期限が過ぎていたり、最大同時接続数を超えた場合、 Sora はエラーメッセージ SERVICE-UNAVAILABLE を送信し、 WebSocket を切断し終了します。

RTCPeerConnectionState が定義されていない場合

注釈

ブラウザでは Firefox が RTCPeerConnectionState が定義されていません

RTCDtlsTransport が実装されていない場合 RTCPeerConnectionState が正常に動作しないため、 RTCIceConnectionState を利用してください。

RTCIceConnectionState が disconnect になった場合、切断タイマーを開始し、 タイムアウトした場合 disconnect から変化がなければ切断してください。

Sora SDK の RTCIceConnectionState 用の切断タイマーはデフォルトで 10 秒です。

クライアントの状態

認証失敗

接続を試みて、認証ウェブフックが接続を許可しなかった状態です。

Sora は認証失敗理由を WebSocket で送信後に、WebSocket を切断します。

認証成功

接続を試みて、認証ウェブフックが接続を許可した状態です。

この時点ではまだ WebRTC での接続に成功していません。そのため、同時接続数としてもカウントされません 認証は成功しているが、WebRTC での接続に失敗するということがありえるためです。

セッション参加

認証が許可されると、そのチャネル ID のセッションが存在していれば セッションへの参加 が行われます。 もしセッションが存在していなければ セッションの生成 が行われます。

この時点ではまだ WebRTC での接続に成功していません。そのため、同時接続数としてもカウントされません 認証は成功しているが、WebRTC での接続に失敗するということがありえるためです。

認証が成功したタイミングで、 Sora はクライアントをセッションに参加させます。 この後、クライアントは Sora からの "type": "offer" を受け取り、WebRTC の確立を試みます。

セッション離脱

セッションからの離脱は、コネクションが破棄された後に発生します。

セッションが API で破棄されたり、セッションのライフタイムが終了した場合、 そのセッションに参加しているクライアントのコネクションを破棄し、セッションから離脱します。

コネクション生成

認証が成功し、セッションへ参加後、WebRTC のコネクションが確立された状態です。

つまり connection.created ウェブフックが送信されたタイミングになります。

このタイミングで Sora は初めて同時接続数に +1 をします。

コネクション破棄

何かしらの理由で、WebRTC のコネクションが破棄された状態です。

このタイミングで Sora は同時接続数から -1 をします。

クライアントからの "type": "disconnect" による切断

WebSocket シグナリングを利用している場合は、 WebSocket の Close フレームの Reason に "TYPE-DISCONNECT" が入るようになりました。

DataChannel シグナリングのみを利用している場合は、 DataChannel を閉じて終了します。

WebSocket シグナリング利用時に Sora から正常切断

切断系 API やライフタイム期限などのSora からの正常切断時に、 WebSocket シグナリングを利用している場合、 WebSocket Close フレームの Code に 1000 、 Reason に切断理由が入ります。

正常な場合の切断理由は以下の 3 つです。

• LIFETIME-EXPIRED

  • ライフタイムによるコネクションの破棄

• SESSION-DESTROYED

  • API やライフタイムなどによるセッションの破棄

• DISCONNECTED-API

  • API によるコネクションの破棄

DataChannel シグナリングのみ利用時に Sora から切断が発生した際の "type": "close" メッセージの送信

DataChannel シグナリングのみ利用時に Sora から切断が発生した際、 DataChannel を閉じる前に "type": "close" メッセージを送信します。

sora.conf の data_channel_signaling_close_message を true に設定することで有効になります。 デフォルトは false です。

DataChannel が閉じられたのが正常な処理なのか、それとも何か問題が発生したのかを明確にするための仕組みです。

正常な場合の切断理由は以下の 3 つです。

• LIFETIME-EXPIRED

  • ライフタイムによるコネクションの破棄

• SESSION-DESTROYED

  • API やライフタイムなどによるセッションの破棄

• DISCONNECTED-API

  • API によるコネクションの破棄

ウェブフック

概要

Sora では認証の判断や状態の通知などを全てウェブフックを利用します。 認証ウェブフックやセッションウェブフックの一部では、ウェブフックの戻り値で設定を払い出すことができます。

ウェブフックリクエスト

• ウェブフックは HTTP/1.1 で送信します

• content-type は application/json です

ウェブフックの設定

• ウェブフック URL を設定しない場合は、ウェブフックリクエストを送信しません

• ウェブフックログを出力しない設定は認証ウェブフックログと統計ウェブフックログができます

認証ウェブフック

設定:

auth_webhook_url に認証ウェブフックの URL を指定します。

正常ログ:

auth_webhook.jsonl に認証ウェブフックが 正常に動作したログ が出力されます

エラーログ:

auth_webhook_error.jsonl に認証ウェブフックがエラーになったログが出力されます

詳細は 認証ウェブフック をご確認ください。

セッションウェブフック

設定:

session_webhook_url にセッションウェブフックの URL を指定します。

正常ログ:

session_webhook.jsonl にセッションウェブフックが 正常に動作したログ が出力されます

エラーログ:

session_webhook_error.jsonl にセッションウェブフックがエラーになったログが出力されます

詳細は セッションウェブフック をご確認ください。

イベントウェブフック

イベント:

event_webhook_url にイベントウェブフックの URL を指定します。

全てのログ:

event_webhook.jsonl にイベントウェブフックの 全てのログ が出力されます

エラーログ:

event_webhook_error.jsonl にイベントウェブフックでエラーになったログが出力されます

詳細は イベントウェブフック をご確認ください。

統計ウェブフック

イベント:

stats_webhook_url にイベントウェブフックの URL を指定します。

全てのログ:

stats_webhook.jsonl に統計ウェブフックの 全てのログ が出力されます

エラーログ:

stats_webhook_error.jsonl に統計ウェブフックでエラーになったログが出力されます

詳細は 統計ウェブフック をご確認ください。

ウェブフックのタイムアウト時間の指定

コネクション確立のタイムアウト時間の指定

Sora がウェブフックを送信する際に、ウェブフック送信先のサーバーとのコネクションを確立する際のタイムアウト時間を指定できます。

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

sora.conf の webhook_connect_timeout を設定してください。

レスポンスのタイムアウト時間の指定

Sora がウェブフックを送信し、そのレスポンスを受け取るまでのタイムアウト時間を指定できます。

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

sora.conf の webhook_response_timeout を設定してください。

ウェブフックリクエストなどの送信先サーバー証明書の検証に利用する OS 組み込みのルート CA 証明書について

Sora は外部サーバーに HTTPS で通信を行う際、デフォルトでは OS に組み込まれた信頼された CA 証明書を利用します。

• Ubuntu は apt install ca-certificates でインストールされる証明書を利用します

• RHEL (または CentOS) は dnf install ca-certificates でインストールされる証明書を利用します

それぞれの OS の CA 証明書のパス以下になります。

• Ubuntu は /etc/ssl/certs/ca-certificates.crt のパスにある信頼された CA 証明書を利用します

• RHEL (または CentOS) は /etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem のパスにある信頼された CA 証明書を利用します

OS の証明書の読み込みに失敗した場合は、サーバーから送られてくる証明書の検証を行わないようになり、接続毎に warning ログが出力されます。

ウェブフックで利用する CA 証明書は webhook_tls_verify_cacert_file に指定することができます。

音声ストリーミングや統計エクスポーターでも CA 証明書を指定することができます。

• audio_streaming_tls_verify_cacert_file

• stats_exporter_tls_verify_cacert_file

ウェブフックリクエスト送信先のサーバーがベーシック認証を利用している場合

もしウェブフックリクエスト送信先のサーバーがベーシック認証を利用している場合は、 sora.conf にて webhook_basic_authn を true に設定することでベーシック認証を利用できます。

webhook_basic_authn_user_id と webhook_basic_authn_password に利用するユーザー ID とパスワードを設定して下さい。

ウェブフックリクエスト送信先のサーバーが自己発行証明書などを利用している場合

Sora は sora.conf にて CA 証明書を指定しない限り OS に組み込まれた信頼された CA 証明書を利用します。 そのため、自己発行証明書などの正規の認証局から発行されていない証明書を使用した場合には、信頼できないと判断しエラーになります。

この場合は sora.conf にて webhook_tls_verify_cacert_file を指定することで、 指定されたルート CA を利用してサーバー証明書の検証を行います。

Sora にて自己署名証明書(Self-signed certificate)を利用する場合、 sora.conf にて、 webhook_insecure を true に設定する必要があります。

ウェブフックリクエスト送信先のサーバーが mTLS を利用している場合

mTLS を利用する場合は sora.conf にて webhook_tls_fullchain_file にクライアント証明書、 webhook_tls_privkey_file にクライアント秘密鍵を指定します。 送信先のサーバーが自己証明書などを利用している場合は webhook_tls_verify_cacert_file にサーバー CA 証明書を指定します。

ウェブフックリクエスト送信先が IPv6 アドレスのみ対応している場合

Sora は sora.conf にて webhook_ipv6 を true にすることで、 IPv6 のみのサーバーに対して、ウェブフックリクエストを送信できるようになります。

connection.updated と session.updated ウェブフック

session.updated と connection.updated は一定間隔で送信してくるウェブフックです。

これらのウェブフックをアプリケーションサーバー側で記録しておくことで、 もし何か障害が発生しウェブフックが通知されなくなった場合でも、 そのコネクションが存在するかどうかの判断を行う事ができるようになります。

ウェブフックの順番保証

Sora は一部のイベントウェブフックリクエストを送信する際、順番を保証して送信します。

• connection.created の前に connection.destroyed が送信されることはありません

• archive.started の前に archive.available や split-archive.available や split-archive.end が送信されることはありません

ウェブフックの警告メッセージ

これらの警告メッセージは sora.jsonl に出力されます。

• AUTH-WEBHOOK-INTERNAL-ERROR

• SESSION-WEBHOOK-ERROR

• EVENT-WEBHOOK-ERROR

• STATS-WEBHOOK-ERROR

reason

• reason に nxdomain が含まれる場合

  • DNS A レコードまたは AAAA レコードが存在しない

• reason に timeout が含まれる場合

  • ウェブフック送信先のサーバーとの確立が webhook_connect_timeout で設定した時間を超えた

  • ウェブフック送信先のサーバーからのレスポンスが webhook_response_timeout で設定した時間を超えた

• reason に closed が含まれる場合

  • ウェブフック送信先の TCP 接続が意図しないタイミングで切断された

  • この問題が発生した場合はウェブフックは失敗と判断します

• reason に enotconn が含まれる場合

  • ウェブフック送信先の TCP 接続が意図しないタイミングで切断された際、何かしらの処理を行った

  • この問題が発生した場合はウェブフックは失敗と判断します

認証ウェブフック

概要

Sora は認証機能を持っていますが、クライアントからの接続可否を判断する機能は持っていません。 接続可否は外部のアプリケーションサーバーにウェブフックを送信し、その戻り値で判断します。

Sora はシグナリング経由で送られてきた情報や、 そのチャネルに接続している情報を HTTP/1.1 POST で sora.conf の auth_webhook_url に指定された URL へ送信します。 このとき送信する情報は JSON 形式です。

注意

シグナリング "type": "connect" 経由で送られてきた情報がそのまま認証ウェブフックのリクエストとして送信されるわけではありません。

ログの出力

sora.conf の auth_webhook_url を有効にしない場合でも log/auth_webhook.jsonl は生成されます。

HTTP ヘッダー

警告

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

注釈

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

sora-connection-id

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

コネクション ID が WCJC78EWK935N7P7Z8FYAKFW9M の場合は sora-connection-id: WCJC78EWK935N7P7Z8FYAKFW9M のように値が入ってきます。

設定

auth_webhook_url

デフォルト:

未設定

認証可否の判断に使用する HTTP リクエストの送信先を sora.conf の auth_webhook_url に設定します。 認証ウェブフック機能を使用する場合は指定してください。

HTTP のレスポンスは認証の可否に関わらず、 200 OK 等 200 番台のステータスコードを返す必要があります。

auth_webhook_url = http://127.0.0.1:8080/sora/auth/webhook

auth_webhook_log

危険

何か特別な理由がない限り false へ変更しないでください。

デフォルト:

true

認証ウェブフックがログを出力するかどうかを sora.conf の auth_webhook_log で設定します。

• 認証ウェブフックが 正常に処理された場合 は log/auth_webhook.jsonl にログが出力されます

• 認証ウェブフックの 処理が失敗した場合 は log/auth_webhook_error.jsonl にログが出力されます

  • 戻りのステータスコードが 200 番台以外の場合

  • 戻りの JSON に "allowed" 項目が含まれていない場合

  • 戻りの JSON が "allowed": false で "reason" が含まれていない場合

  • 送信先が応答せずタイムアウトになった場合

認証処理時に送信する JSON

Sora は、 sora.conf の auth_webhook_url に設定した URL に対して POST リクエスト で次のような JSON を送ります。

型については 認証ウェブフック を確認してください。

{
  "audio": true,
  "audio_codec_type": "OPUS",
  "channel_connections": 0,
  "channel_id": "sora",
  "channel_recvonly_connections": 0,
  "channel_sendonly_connections": 0,
  "channel_sendrecv_connections": 0,
  "connection_id": "VSMDDJG3ZH1RHB93W260APVEQW",
  "data_channel_signaling": true,
  "data_channels": [
    {
      "compress": false,
      "direction": "sendrecv",
      "label": "#abc",
      "ordered": true
    }
  ],
  "e2ee": false,
  "ignore_disconnect_websocket": false,
  "label": "WebRTC SFU Sora",
  "multistream": true,
  "node_name": "[email protected]",
  "role": "sendrecv",
  "simulcast": false,
  "sora_client": {
    "environment": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.6099.109 Safari/537.36",
    "raw": "Sora JavaScript SDK 2023.2.0",
    "type": "Sora JavaScript SDK",
    "version": "2023.2.0"
  },
  "spotlight": false,
  "timestamp": "2022-06-08T07:51:32.593704Z",
  "version": "2024.1.0",
  "video": true,
  "video_bit_rate": 1000,
  "video_codec_type": "VP9",
  "video_vp9_params": { "profile_id": 0 }
}

• version

  • Sora のバージョンが 文字列 で入ってきます

• label

  • sora.conf の label で指定した値が入ってきます

• node_name

  • Sora のノード名が入ってきます

• timestamp

  • ウェブフックリクエスト送信時のタイムスタンプが RFC3339 フォーマットで入ってきます

  • マイクロ秒まで含まれています

• id

  • Base32-UUIDv4 です

  • ウェブフック毎に割り当てられるユニークな値です

• e2ee

  • 将来的に Message Layer Security (MLS) を利用した End to End Encryption (E2EE) に対応した際の予約項目です

  • 現時点では常に false が含まれます

• multistream

  • マルチストリームでの接続要求を出しているかどうかの値が入ってきます

  • クライアントが送ってこない場合は true が設定されます

  • true の場合はマルチストリームを希望している接続です

• simulcast

  • サイマルキャストでの接続要求を出しているかどうかの値が入ってきます

  • true の場合はサイマルキャストを希望している接続です

  • クライアントが送ってこない場合は false が設定されます

• simulcast_rid

  • simulcast が true かつ spotlight が false の場合のみこの値が入ってきます

  • サイマルキャストでの受け取る rid を指定します

• simulcast_multicodec

  • simulcast が true の場合のみこの値が入ってきます

  • サイマルキャストマルチコーデックを利用するかどうかの値が入ってきます

• spotlight

  • スポットライトでの接続要求を出しているかどうかの値が入ってきます

  • クライアントが送ってこない場合は false が設定されます

• spotlight_focus_rid

  • spotlight が true の場合のみこの値が入ってきます

  • スポットライトでフォーカスされた参加者の映像を受信する rid を指定します

• spotlight_unfocus_rid

  • spotlight が true の場合のみこの値が入ってきます

  • スポットライトでフォーカスされていない参加者の映像を受信する rid を指定します

• spotlight_number

  • この項目はオプションです

  • クライアントが送ってこない場合は、この値は含まれません

  • spotlight_number をシグナリングの connect 時に送ってきた場合に値が入ります

• whip

  • WHIP を利用したシグナリングを利用するかどうかの値が入ってきます

• whep

  • WHEP を利用したシグナリングを利用するかどうかの値が入ってきます

• role

  • 以下が入ってきます

  • sendrecv (送受信)

  • sendonly (送信)

  • recvonly (受信)

• metadata

  • この項目はオプションです

  • ユーザーが定義を自由にできる値です

  • JSON で使用できる形式ならどんな値でも指定できます

  • "type": "connect" で metadata が送られてこない場合、アプリケーション側にも送られません

• authn_metadata

  • この項目は metadata と同じです

  • metadata の別名です

  • "type": "connect" で metadata が送られてこない場合、アプリケーション側にも送られません

• channel_id

  • 認証対象のクライアントが接続要求を出しているチャネル ID です

• client_id

  • この項目はオプションです

  • 認証対象のクライアントが利用要求を出しているクライアント ID です

  • クライアントが指定しない場合は入ってきません

• bundle_id

  • この項目はオプションです

  • 認証対象のコネクションが利用要求を出しているバンドル ID です

  • クライアントが指定しない場合は入ってきません

• connection_id

  • Base32-UUIDv4 です

  • 認証対象のコネクションに割り当てられたユニークな ID です

• channel_connections

  • 現在そのチャネルの接続数です

  • 自分は含まれません

• channel_sendrecv_connections

  • 現在そのチャネルで送受信をしている配信者の接続数です

  • 自分は含まれません

• channel_sendonly_connections

  • 現在そのチャネルで送信のみをしている配信者の接続数です

  • 自分は含まれません

• channel_recvonly_connections

  • 現在そのチャネルの配信を受信のみしている視聴者の接続数です

  • 自分は含まれません

• audio

  • true または false が入ってきます

  • false の場合は audio を使用しません

• audio_codec_type

  • この項目はオプションです

  • audio が false の場合は含まれません

  • コーデックはクライアントが送ってこない場合はデフォルトで OPUS が使用されます

  • コーデックの種類は OPUS のみです

• audio_bit_rate

  • この項目はオプションです

  • audio が false やクライアントが送ってこない場合、含まれません

  • この設定は audio_codec_type が OPUS の時のみ有効です

  • default_audio_bit_rate に値を指定していた場合はその値が利用されます

  • 最小が 6 で、最大が 510 です

  • 単位は kbps です

• video

  • true または false が入ってきます

  • false の場合は video を使用しません

• video_codec_type

  • この項目はオプションです

  • video が false の場合は含まれません

  • コーデックはクライアントが送ってこない場合はデフォルトで VP9 が使用されます

  • コーデックの種類は VP8、 VP9、 AV1、 H264、 H265 です

• video_bit_rate

  • この項目はオプションです

  • video が false の場合は含まれません

  • ビットレートはクライアントが送ってこない場合は sora.conf の default_video_bit_rate が使用されます

  • デフォルトは 500 です

  • 最小が 1 で、最大が 30000 です

  • 15000 より大きい値は現時点でサポート範囲外です

  • 単位は kbps です

• video_vp9_params

  • この項目はオプションです

  • video_codec_type が VP9 の場合に含まれます

  • 配信者が利用するビデオの VP9 の設定がオブジェクトとして入ってきます

  • 詳細は ビデオの VP9 設定指定 も参考にしてください

  • クライアントが profile_id の値を送ってこない場合は sora.conf の default_vp9_param_profile_id の値が使用されます

• video_av1_params

  • この項目はオプションです

  • video_codec_type が AV1 の場合に含まれます

  • 配信者が利用するビデオの AV1 の設定がオブジェクトとして入ってきます

  • 詳細は ビデオの AV1 設定指定 も参考にしてください

  • クライアントが profile の値を送ってこない場合は sora.conf の default_av1_param_profile の値が使用されます

• video_h264_params

  • この項目はオプションです

  • video_codec_type が H264 の場合に含まれます

  • 配信者が利用するビデオの H264 の設定がオブジェクトとして入ってきます

  • 詳細は ビデオの H.264 設定指定 も参考にしてください

  • クライアントが profile_level_id の値を送ってこない場合は sora.conf の default_h264_param_profile_level_id の値が使用されます

  • b_frame は sora.conf の h264_b_frame が true のときに含まれます

  • クライアントが b_frame の値を送ってこない場合の値は false です

• video_h265_params

  • この項目はオプションです

  • video_codec_type が H265 の場合に含まれます

  • 配信者が利用するビデオの H264 の設定がオブジェクトとして入ってきます

  • 詳細は ビデオの H.264 設定指定 も参考にしてください

  • クライアントが level_id の値を送ってこない場合は sora.conf の default_h265_param_level_id の値が使用されます

  • b_frame は sora.conf の h265_b_frame が true のときに含まれます

  • クライアントが b_frame の値を送ってこない場合の値は false です

• metadata

  • この項目はオプションです

  • ユーザーが定義を自由にできる値です

  • JSON で使用できる形式ならどんな値でも指定できます

  • "type": "connect" で metadata が送られてこない場合、アプリケーション側にも送られません

• authn_metadata

  • この項目はオプションです

  • この項目は metadata と同じです

  • metadata の別名です

  • "type": "connect" で metadata が送られてこない場合、アプリケーション側にも送られません

• data_channel_signaling

  • シグナリングの DataChannel 切り替えをするかどうか

• ignore_disconnect_websocket

  • シグナリングの DataChannel 切り替え時に WebSocket の切断を無視するかどうか

• data_channels

  • この項目はオプションです

  • DataChannel を利用したメッセージングの定義が入ってきます

• forwarding_filter

  • この項目はオプションです

  • この項目は 2025 年 12 月リリース予定の Sora にて廃止します

    • forwarding_filters を利用してください

  • 転送フィルターが入ってきます

  • クライアントが指定しない場合は入ってきません

• forwarding_filters

  • この項目はオプションです

  • 転送フィルターのリストが入ってきます

  • クライアントが指定しない場合は入ってきません

• sora_client

  • この項目はオプションです

  • クライアントから送られてきた情報が入ってきます

認証ウェブフックに含まれる同時接続数について

重要

認証ウェブフックで送られてくる同時接続数、そのウェブフックが送られたタイミングの値であり、 厳密にそのチャネルの同時接続数を制限する値としては利用できません。

• channel_connections

• channel_sendrecv_connections

• channel_sendonly_connections

• channel_recvonly_connections

これら認証ウェブフックに含まれる同時接続数は WebRTC が確立した後に +1 され、WebRTC が切断されたタイミングで -1 されます。 そのため認証タイミングと WebRTC 確立時の時間差が存在します。

さらに、認証ウェブフックは並列で処理されるため、アプリ側でこの同時接続数の値を利用した厳密な同時接続数の制限を行う事はできません。

もし厳密なチャネル単位での同時接続数を制限したい場合は、 イベントウェブフック connection.created を利用して、 アプリ側でデータベースでロックを取ってカウントを行い、ロックを取って数値をチェックして認証を行ってください。

sora_client

認証ウェブフックの sora_client にはクライアントから送られてきた情報が入ってきます。 クライアントから情報が送られてこなければ含まれません。 Sora SDK を利用している場合は必ず入ってきます。

"sora_client": {
  "environment": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.77 Safari/537.36",
  "raw": "Sora JavaScript SDK 2021.1.0",
  "type": "Sora JavaScript SDK",
  "version": "2023.2.0"
},

• type

  • オプションです

  • クライアントから送られてきた Sora SDK またはクライアントのタイプが入ってきます

• raw

  • オプションです

  • クライアントから送られてきた sora_client の値がそのまま入ってきます

• version

  • オプションです

  • クライアントから送られてきた Sora SDK またはクライアントのバージョンが入ってきます

• commit_short

  • オプションです

  • クライアントから送られてきた Sora SDK のコミットハッシュが入ってきます

• environment

  • オプションです

  • クライアントから送られてきた端末情報が入ってきます

• libwebrtc

  • オプションです

  • クライアントから送られてきた libwebrtc のバージョン情報が入ってきます

認証成功時のレスポンス JSON

認証に成功した場合は、以下の JSON をステータスコード 200 番台で返してください。

{
  "allowed": true
}

Sora は "allowed" が true の場合は認証を成功と判断して処理をします。

認証成功時の払い出し項目

認証成功時に様々な項目を払い出すことができます。

詳細は 認証ウェブフック成功時の払い出し をご確認ください。

認証失敗時のレスポンス JSON

認証に失敗した場合は、以下の JSON を返してください。

{
  "allowed": false,
  "reason": "<String>"
}

注釈

認証失敗の場合も HTTP レスポンスのステータスコードは 200 番台である必要があります

Sora は "allowed" が false で、 "reason" が含まれている場合に認証失敗と判断して処理します。

"reason" は必須です、何かしらエラー理由を 100 バイト以内 の文字列を指定してください。

認証に失敗した場合、認証サーバーから送られてきた "reason" の内容は、 WebSocket シグナリング切断時のメッセージとしてクライアントに送られます。

例

認証ウェブフックの戻り値で "reason" に "REJECT" を返した場合、 WebSocket シグナリング切断時のメッセージの "reason" に "REJECT" が含まれます。

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

{
  "allowed": false,
  "reason": "REJECT"
}

WebSocket シグナリング切断時のメッセージ

• "code" が 4490

• "reason" が "REJECT"

認証ウェブフック成功時の払い出し

認証サーバーは認証成功時に様々な値を出すことができます。

{
  "allowed": true,
  "event_metadata": {
    "pk": 1
  }
}

詳細は 認証ウェブフック成功時の払い出し をご確認ください。

WebSocket シグナリング時の HTTP ヘッダーを認証ウェブフックにコピーする機能

sora.conf の copy_websocket_signaling_header_names を設定することで、 認証ウェブフックの HTTP ヘッダーに WebSocket シグナリング時の HTTP ヘッダーをコピーすることができます。

copy_websocket_signaling_header_names = X-Forwarded-For, X-Real-IP, Tracestate

危険

この機能は指定された WebSocket シグナリング時の HTTP ヘッダーを そのままコピー して認証ウェブフックに送信します。 そのため、指定されたヘッダー名や、実際のヘッダー値に何が含まれていても何も検証は行いません。注意して利用してください。

認証ウェブフックログ

sora.conf の auth_webhook_log を true にしている場合は log/auth_webhook.jsonl が出力されます。

重要

auth_webhook_log はデフォルトで true です。

このログには認証ウェブフックのリクエストとレスポンス、ウェブフック URL、タイムスタンプが含まれます。

• req

  • 認証ウェブフックの送信リクエストがそのまま入ります

• res

  • 認証ウェブフックの戻り値がそのまま入ります

• url

  • auth_webhook_url を指定していない場合はログに含まれません

• timestamp

  • RFC3339 フォーマットのタイムスタンプが入ります

  • UTC です

  • マイクロ秒まで含まれています

• copy_headers

  • copy_websocket_signaling_header_names でコピーされた HTTP ヘッダーが入ります

auth_webhook_url あり / レスポンスあり

{
  "req": {
    "audio": true,
    "audio_codec_type": "OPUS",
    "channel_connections": 0,
    "channel_id": "sora",
    "channel_recvonly_connections": 0,
    "channel_sendonly_connections": 0,
    "channel_sendrecv_connections": 0,
    "connection_id": "F2SMT1W59S5ADDZ84CMQ8CDBX4",
    "e2ee": false,
    "label": "WebRTC SFU Sora",
    "multistream": true,
    "node_name": "[email protected]",
    "role": "sendrecv",
    "simulcast": false,
    "sora_client": {
      "environment": "Mozilla/5.0 (Macintosh; Intel Mac OS X 11_0_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/87.0.4280.88 Safari/537.36",
      "raw": "Sora JavaScript SDK 2020.5.0",
      "type": "Sora JavaScript SDK",
      "version": "2023.2.0"
    },
    "spotlight": false,
    "timestamp": "2020-12-07T09:16:54.079650Z",
    "version": "2024.1.0",
    "video": true,
    "video_bit_rate": 1000,
    "video_codec_type": "VP9",
    "video_vp9_params": { "profile_id": 0 }
  },
  "res": {
    "allowed": true,
    "event_metadata": {
      "abc": "efg"
    },
    "metadata": "abc",
    "signaling_notify_metadata": {
      "a": "b"
    }
  },
  "timestamp": "2020-12-07T09:16:54.089962Z",
  "url": "http://127.0.0.1:3001/sora/auth/webhook"
}

auth_webhook_url あり / レスポンスなし

• res がありません

{
  "req": {
    "audio": true,
    "audio_codec_type": "OPUS",
    "channel_connections": 0,
    "channel_id": "sora",
    "channel_recvonly_connections": 0,
    "channel_sendonly_connections": 0,
    "channel_sendrecv_connections": 0,
    "connection_id": "0FBC8HF84544ZDHYYN9BCRNZG8",
    "e2ee": false,
    "label": "WebRTC SFU Sora",
    "multistream": true,
    "node_name": "[email protected]",
    "role": "sendrecv",
    "simulcast": false,
    "sora_client": {
      "environment": "Mozilla/5.0 (Macintosh; Intel Mac OS X 11_0_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/87.0.4280.88 Safari/537.36",
      "raw": "Sora JavaScript SDK 2020.5.0",
      "type": "Sora JavaScript SDK",
      "version": "2023.2.0"
    },
    "spotlight": false,
    "timestamp": "2020-12-07T06:30:56.240917Z",
    "version": "2024.1.0",
    "video": true,
    "video_bit_rate": 1000,
    "video_codec_type": "VP9",
    "video_vp9_params": { "profile_id": 0 }
  },
  "timestamp": "2020-12-07T06:30:56.252785Z",
  "url": "http://127.0.0.1:3001/sora/authn/webhook"
}

auth_webhook_url なし

• url がありません

{
  "req": {
    "audio": true,
    "audio_codec_type": "OPUS",
    "channel_connections": 0,
    "channel_id": "sora",
    "channel_recvonly_connections": 0,
    "channel_sendonly_connections": 0,
    "channel_sendrecv_connections": 0,
    "client_id": "K8PCW533MN1WK24YNZ83HDP74C",
    "connection_id": "K8PCW533MN1WK24YNZ83HDP74C",
    "e2ee": false,
    "label": "WebRTC SFU Sora",
    "multistream": true,
    "node_name": "[email protected]",
    "role": "sendrecv",
    "simulcast": false,
    "sora_client": {
      "environment": "Mozilla/5.0 (Macintosh; Intel Mac OS X 11_0_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/87.0.4280.88 Safari/537.36",
      "raw": "Sora JavaScript SDK 2020.5.0",
      "type": "Sora JavaScript SDK",
      "version": "2023.2.0"
    },
    "spotlight": false,
    "timestamp": "2020-12-07T06:26:58.916204Z",
    "version": "2024.1.0",
    "video": true,
    "video_bit_rate": 1000,
    "video_codec_type": "VP9",
    "video_vp9_params": { "profile_id": 0 }
  },
  "res": {
    "allowed": true
  },
  "timestamp": "2020-12-07T06:26:58.916242Z"
}

クラスターリレー機能利用時に認証が 2 回行われる場合がある

クラスターリレー機能を有効にしている場合、1 クライアントへの認証が 2 回 行われる場合があります。

特定のノードに同時接続素の寄せを発生させるアフィニティ機能は認証成功時の払い出しで有効か無効かを指定できるため、 リレー機能が存在する場合はアフィニティの確認をするために必ず認証を行います。

その後、アフィニティが有効だったり、ライセンス上限に達していた場合で、別ノードへのリダイレクトが行われた場合、 リダイレクト先のノードで再度認証が発生します。

アフィニティが有効で、アフィニティが発生し接続したノードにセッションが存在しない場合

クラスター全体のライセンスに余裕があれば、 既にセッションがある別ノードへリダイレクトを行い、再度認証を行います。

アフィニティが有効で、かつ cluster_affinity_threshold の値を超えた場合

クラスター全体のライセンスに余裕があれば、 別ノードへリダイレクトを行い、再度認証を行います。

アフィニティ関係なく、接続先ノードのライセンス上限の場合

クラスター全体でライセンスの上限に達していない場合、 別ノードへリダイレクトを行い、再度認証を行います。

エラーメッセージ

これらエラーメッセージは sora.jsonl に出力されます。

AUTH-WEBHOOK-RESPONSE-UNEXPECTED-STATUS-CODE

認証サーバーが返すステータスコードが 200 系ではなかった場合に出力されます。

例えばステータスコードが 400 だと出力されます。

INVALID-AUTH-WEBHOOK-RESPONSE-JSON

認証サーバーが返す JSON に必須で項目が含まれていない場合に出力されます。

例えば allowed が含まれていない場合に出力されます。

AUTH-WEBHOOK-RESPONSE-BAD-JSON

認証サーバーが返す JSON のデコードに失敗した場合に出力されます。

例えば {"a: b"} といったような JSON と判断できない場合に出力されます。

AUTH-WEBHOOK-RESPONSE-EMPTY-BODY

認証サーバーがステータスコードが 200 系で空のボディを返した場合に出力されます。

シーケンス図

認証成功

        sequenceDiagram
    autonumber
    participant C as クライアント
    participant S as Sora
    participant A as アプリケーションサーバー
    C->>+S: "type": "connect"
    S->>+A: 認証ウェブフック
    A-->>-S: 200OK<br />{"allowed": true}
    S-->>-C: "type": "offer"
    C->>S: "type": "answer"
    note over C,A: WebRTC 確立
    

認証拒否

        sequenceDiagram
    autonumber
    participant C as クライアント
    participant S as Sora
    participant A as アプリケーションサーバー
    C->>+S: "type": "connect"
    S->>+A: 認証ウェブフック
    A-->>-S: 200OK<br />{"allowed": false, "reason": "REJECT"}
    S->>C: WebSocket Close<br/>"code": 4490<br/>"reason": "REJECT"
    

認証ウェブフック成功時の払い出し

概要

Sora では認証ウェブフック成功時に様々な値を外部の認証サーバーから払い出すことができます。

Sora は払い出された値を反映した状態でクライアントへの接続要求 "type": "offer" を送ります。

範囲表記

2..10 と書いてある場合 2 以上、10 以下の値を指定できることを表しています。

audio の払い出し

クライアントが指定してきた音声のコーデックやビットレートなどのパラメーターに対して、 認証サーバー側で新たに値を払い出すことで、上書きを行えます。

クライアントが指定してきた値を上書きできるため、 サーバー側でそれぞれのクライアントに対して、音声のコーデックやビットレートをコントロールできます。

指定項目一覧

• audio

  • true または false が指定できます

注意

audio_codec_type や audio_bit_rate 等の audio 関連のパラメーターを指定する場合は、あわせて audio に true を指定する必要があります

• audio_codec_type

  • "OPUS"

  • codec_type を指定しないこともできます

• audio_bit_rate

  • 6..510

  • 単位は kbps です

  • デフォルトで最適なビットレートが選択されるようになっているため指定する必要はありません

• audio_opus_params

  • オーディオの Opus 設定指定 をオブジェクトとして指定できます

    • オーディオの Opus 設定指定 の opus_params を audio_opus_params に変更して指定してください

払い出し例

この機能を使用する場合は、認証成功時のレスポンス JSON に audio や audio_codec_type や audio_bit_rate を指定してください。 ここで使用できるのはシグナリングの "type": "connect" 時に指定できる audio の値です。

{
  "allowed": true,
  "audio": true,
  "audio_codec_type": "OPUS",
  "audio_bit_rate": 64
}

video の払い出し

クライアントが指定してきた映像のコーデックやビットレートなどのパラメーターに対して、 認証サーバー側で新たに値を払い出すことで、上書きを行えます。

クライアントが指定してきた値を上書きできるため、 サーバー側でそれぞれのクライアントに対して、映像のコーデックやビットレートを指定できます。

指定項目一覧

• "video"

  • true または false が指定できます

注意

video_codec_type や video_bit_rate 等の video 関連のパラメーターを指定する場合は、あわせて video に true を指定する必要があります

• "video_codec_type"

  • この項目を指定する場合は "video": true をあわせて指定してください

  • 文字列で指定できます

  • "VP8"

  • "VP9"

  • "AV1"

  • "H264"

  • "H265"

    • sora.conf にて h265 を true にしている必要があります

  • codec_type を指定しないこともできます

• "video_bit_rate"

  • 1..30000

    • サポートされている値は 1..15000 です

  • 単位は kbps です

  • video_bit_rate を指定しないこともできます

• video_vp9_params

  • ビデオの VP9 設定指定 をオブジェクトとして指定できます

    • ビデオの VP9 設定指定 の vp9_params を video_vp9_params に変更して指定してください

• video_av1_params

  • ビデオの AV1 設定指定 をオブジェクトとして指定できます

    • ビデオの AV1 設定指定 の av1_params を video_av1_params に変更して指定してください

• video_h264_params

  • ビデオの H.264 設定指定 をオブジェクトとして指定できます

    • ビデオの H.264 設定指定 の h264_params を video_h264_params に変更して指定してください

• video_h265_params

  • ビデオの H.265 設定指定 をオブジェクトとして指定できます

    • ビデオの H.265 設定指定 の h265_params を video_h265_params に変更して指定してください

払い出し例

この機能を使用する場合は、認証成功時のレスポンス JSON に video や video_codec_type や video_bit_rate を指定してください。 ここで使用できるのはシグナリングの "type": "connect" 時に指定できる video の値です。

{
  "allowed": true,
  "video": true,
  "video_codec_type": "VP9",
  "video_bit_rate": 1000
}

client_id の払い出し

Sora は認証成功時の戻り値に client_id を認証サーバーから返すことができます。

シグナリング接続時にも、 認証成功時の戻り値にも client_id を指定しない場合は connection_id と同じ値が client_id に割りあてられます。

{
  "allowed": true,
  "client_id": "spam"
}

• client_id

  • 1 から 255 の長さの文字列

bundle_id の払い出し

Sora は認証成功時の戻り値に bundle_id を認証サーバーから返すことができます。

bundle_id を指定した場合、マルチストリーム利用時に bundle_id の値が同じ接続からの音声や映像、メッセージング、シグナリング通知を受信しなくなります。

シグナリング接続時にも、 認証成功時の戻り値にも bundle_id を指定しない場合は connection_id と同じ値が bundle_id に割りあてられます。

{
  "allowed": true,
  "bundle_id": "spam"
}

• bundle_id

  • 1 から 255 バイトの文字列

simulcast / simulcast_rid の払い出し

Sora は、認証成功時のタイミングで接続単位での simulcast と simulcast_rid の値を認証サーバーから払い出すことができます。

{
  "allowed": true,
  "simulcast": true
}

{
  "allowed": true,
  "simulcast": true,
  "simulcast_rid": "r0"
}

この値は sora.conf の default_simulcast_rid の値を上書きします。

simulcast_encodings の払い出し

Sora は、認証成功時のタイミングで接続単位での simulcast_encodings の値を認証サーバーから払い出すことができます。

{
  "allowed": true,
  "simulcast_encodings": [
    {"rid": "r0", "active": true, "scaleResolutionDownBy": 2.0, "maxFramerate": 1.0},
    {"rid": "r1", "active": true, "scaleResolutionDownBy": 2.0, "maxFramerate": 10.0},
    {"rid": "r2", "active": true, "scaleResolutionDownBy": 1.0, "maxFramerate": 30.0}
  ]
}

詳細については サイマルキャスト の 映像のエンコーディングパラメーターのカスタマイズ をご確認ください。

simulcast_codecs の払い出し

Sora は、認証成功時のタイミングで接続単位での simulcast_codecs の値を認証サーバーから払い出すことができます。

{
  "allowed": true,
  "simulcast": true,
  "simulcast_multicodec": true,
  "simulcast_codecs": [
    {"rid": "r0", "codec_type": "AV1", "codec_params": {"profile": 0}},
    {"rid": "r1", "codec_type": "AV1", "codec_params": {"profile": 0}},
    {"rid": "r2", "codec_type": "VP9", "codec_params": {"profile_id": 0}}
  ]
}

詳細については サイマルキャストマルチコーデック をご確認ください。

spotlight_encodings の払い出し

Sora は、認証成功時のタイミングで接続単位での spotlight_encodings の値を認証サーバーから払い出すことができます。

{
  "allowed": true,
  "spotlight_encodings": [
    {"rid": "r0", "active": true, "scaleResolutionDownBy": 4.0, "maxFramerate": 1.0},
    {"rid": "r1", "active": true, "scaleResolutionDownBy": 1.0, "maxFramerate": 10.0},
    {"rid": "r2", "active": false}
  ]
}

詳細については スポットライト機能 の スポットライト利用時の映像のエンコーディングパラメーターのカスタマイズ をご確認ください。

spotlight の払い出し

Sora は、認証成功時のタイミングで接続単位での spotlight の値を認証サーバーから払い出すことができます。

{
  "allowed": true,
  "spotlight": true
}

spotlight_number の払い出し

警告

この払い出しは非推奨です。 セッション単位での払い出し spotlight_number を利用してください。

Sora は、認証成功時のタイミングで接続単位での spotlight_number の値を認証サーバーから払い出すことができます。

spotlight_number はセッションに参加している全てのクライアントが同一の値を指定する必要があります。

{
  "allowed": true,
  "spotlight": true,
  "spotlight_number": 3
}

data_channel_signaling の払い出し

Sora は、認証成功時のタイミングで接続単位での data_channel_signaling の値を認証サーバーから払い出すことができます。

{
  "allowed": true,
  "data_channel_signaling": true
}

この値は "type": "connect" の data_channel_signaling や sora.conf の default_data_channel_signaling の値を上書きします。

認証成功時にクライアントが受け取る JSON

{
  "type": "offer",
  "sdp": "<SDP>",
  "data_channel_signaling": true,
  "ignore_disconnect_websocket": false
}

ignore_disconnect_websocket の払い出し

Sora は、認証成功時のタイミングで接続単位での ignore_disconnect_websocket の値を認証サーバーから払い出すことができます。

{
  "allowed": true,
  "ignore_disconnect_websocket": true
}

この値は "type": "connect" の ignore_disconnect_websocket や sora.conf の default_ignore_disconnect_websocket の値を上書きします。

ただし data_channel_signaling が true の時のみ、この値は有効になります。

認証成功時にクライアントが受け取る JSON

data_channel_signaling が有効な場合、 "type": "switched" が送られる際に ignore_disconnect_websocket も送られます。

{
  "type": "switched",
  "ignore_disconnect_websocket": "<Boolean>",
}

data_channels の払い出し

Sora は、認証成功時のタイミングで接続単位での data_channels の値を認証サーバーから払い出すことができます。

{
  "allowed": true,
  "data_channels": [
    {
      "label": "#spam",
      "max_packet_life_time": 5000,
      "ordered": true,
      "protocol": "efg",
      "compress": false,
      "direction": "sendonly"
    },
    {
      "label": "#egg",
      "max_retransmits": 0,
      "ordered": false,
      "protocol": "abc",
      "compress": false,
      "direction": "recvonly"
    }
  ]
}

data_channels の詳細仕様は data_channels 仕様 をご確認ください。

metadata の払い出し

Sora は、認証成功時のタイミングで metadata という値を認証サーバーから払い出すことができます。

{
  "allowed": true,
  "metadata": {"spam": "egg"}
}

認証サーバーが認証成功時に metadata を含めた場合、クライアントへ送る "type": "offer" に metadata をそのまま送ります。

この機能を使うことで、認証成功のタイミングでユーザー毎に任意の値を送ることができます。

認証成功時にクライアントが受け取る JSON

認証成功の場合は Offer 送信時の JSON に metadata が含められます。

{
  "type": "offer",
  "sdp": "<SDP>",
  "metadata": {"spam": "egg"}
}

event_metadata の払い出し

重要

event_metadata はクライアントには送られません

Sora は、認証成功時のタイミングで event_metadata という値を認証サーバーから払い出すことができます。

認証サーバーが認証成功時に event_metadata を含めた場合、 イベントウェブフックリクエスト送信時に event_metadata という項目が追加されます。

{
  "allowed": true,
  "event_metadata": {"pk": 1}
}

event_metadata はクライアントに知られることのない値です。 Sora イベントウェブフックリクエスト送信先のサーバーのみが知り得る値となります。

使用例

この event_metadata の値は、クライアントに知られることはありません。そのためユーザー ID を直接入れておくという仕組みも使用できます。

こうすることで通知の際、サーバー側がユーザーの判定をしやすくなります。

シグナリング経由での通知機能の払い出し

Sora は、認証成功時のタイミングで signaling_notify という値を認証サーバーから払い出すことができます。

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

signaling_notify の値を返すことで、クライアントごとにシグナリング通知を受け取るかどうかを指定できるようになります。

シグナリング経由での通知機能の詳細は シグナリング通知機能 をご確認ください

シグナリング経由での通知機能を利用したメタデータの払い出し

Sora は、認証成功時のタイミングで signaling_notify_metadata という値を認証サーバーから払い出すことができます。

ここに値を指定することで、参加時や離脱時に外の参加者に情報を通知できます。

{
  "allowed": true,
  "signaling_notify_metadata": {
      "username": "spam"
  }
}

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

シグナリング経由での通知機能を利用した ICE コネクションステートの払い出し

警告

この機能は実験的機能です。

重要

この機能は signaling_notify_ice_connection_state の値が false の場合でも利用できます。

Sora は、認証成功時のタイミングで signaling_notify_ice_connection_state という値を認証サーバーから払い出すことができます。

signaling_notify_ice_connection_state を true で払い出すことで、Sora は ICE コネクションステートが変更した際に、 同一チャネルに接続している自分を含むクライアント全員へ通知するようになります。

この値のデフォルト値は sora.conf の signaling_notify_ice_connection_state の値です。

{
  "allowed": true,
  "signaling_notify_ice_connection_state": true
}

シグナリング通知メタデータ拡張機能の初期値払い出し

Sora は、認証成功時のタイミングで signaling_notify_metadata_ext という値を認証サーバーから払い出すことができます。

払い出しを利用する場合はシグナリング通知メタデータ拡張が有効である必要があります。

払い出した値がシグナリング通知メタデータ拡張の初期値として使用されます。

{
  "allowed": true,
  "signaling_notify_metadata_ext": {
    "mute": true
  }
}

録画ブロック機能の払い出し

重要

録画ブロック機能は新しい録画機能(セッション単位)でのみ利用できます。

Sora は、認証成功時のタイミングで recording_block という値を認証サーバーから払い出すことができます。

ここに true を設定することで、録画有効時にその接続の録画をブロックすることができます。 録画がブロックされた接続の録画ファイルは出力されません。

未指定の場合は recording_block は false として扱われます。

{
  "allowed": true,
  "recording_block": true
}

cluster_affinity の払い出し

クラスターリレー機能利用時に cluster_affinity を指定することで、コネクション単位で同一ノードへの集約を制御できます。 この値は sora.conf の default_cluster_affinity の値を上書きします。

cluster_affinity を true に指定した場合、そのセッションでは同一ノードへの集約を試みます。

{
  "allowed": true,
  "cluster_affinity": true
}

cluster_affinity を false に指定した場合、そのセッションでは同一ノードへの集約を行わず、 接続したノードでの WebRTC 確立を試みます。

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

forwarding_filters の払い出し

Sora は、認証成功時のタイミングで forwarding_filters を認証サーバーから払い出すことができます。

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

{
  "allowed": true,
  "forwarding_filters": [
    {
      "action": "allow",
      "name": "audio-only",
      "priority": 128,
      "rules": [
        [
          {
            "field": "kind",
            "operator": "is_in",
            "values": [
              "audio"
            ]
          }
        ]
      ]
    }
  ]
}

forwarding_filter の払い出し

注意

forwarding_filter は 2025 年 12 月に廃止します。 forwarding_filters の払い出し を利用してください

Sora は、認証成功時のタイミングで forwarding_filter を認証サーバーから払い出すことができます。

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

{
  "allowed": true,
  "forwarding_filter": {
    "action": "allow",
    "name": "audio-only",
    "priority": 128,
    "rules": [
      [
        {
          "field": "kind",
          "operator": "is_in",
          "values": [
            "audio"
          ]
        }
      ]
    ]
  }
}

connection_lifetime の払い出し

Sora は、認証成功時のタイミングで connection_lifetime を認証サーバーから払い出すことができます。

例えば 3600 を指定すると 1 時間 (3600 秒) 後に接続が切断されます。

{
  "allowed": true,
  "connection_lifetime": 3600
}

• 秒 で指定してください

• 最大 2,592,000 秒 (30 日) まで指定できます

• コネクション生成後に変更することはできません

• connection_lifetime が未指定の場合は 無制限 です

• connection.destroyed の reason に lifetime_expired が入ります

• コネクションのライフタイムが終了すると、コネクションが破棄され切断します

• コネクションのライフタイムが終了すると、コネクションウェブフック connection.destroyed が送信されます

• コネクションのライフタイムよりセッションのライフタイムが優先されます

playout_delay_min_delay と playout_delay_max_delay の払い出し

Sora は、認証成功時のタイミングで playout_delay_min_delay と playout_delay_max_delay を認証サーバーから払い出すことができます。 プレイアウト遅延機能をコネクションに指定する場合は、 playout_delay_min_delay と playout_delay_max_delay の両方を指定する必要があります。

{
  "allowed": true,
  "playout_delay_min_delay": 0,
  "playout_delay_max_delay": 100
}

この値は sora.conf の default_playout_delay_min_delay と default_playout_delay_max_delay の値を上書きします。

0..40950 の範囲で指定します。単位はミリ秒です。

この機能を利用することで、コネクション毎にプレイアウト遅延を指定できます。

詳細は プレイアウト遅延機能 をご確認ください。

ipv4_address と ipv6_address の払い出し

Sora は、認証成功時のタイミングで ipv4_address または ipv6_address を認証サーバーから払い出すことができます。 ipv4_address と ipv6_address は片方だけでも、両方返しても問題ありません。

{
  "allowed": true,
  "ipv4_address": "192.0.2.10",
  "ipv6_address": "2001:0DB8::10"
}

この値は SDP の offer 時の a=candidate と TURN-UDP と TURN-TCP の URL の払い出しに使用されます。

sora.conf の ipv4_address と ipv6_address のがこの戻り値で上書きされます。 指定する IP アドレスを間違えると繋がらなくなるため、使用には注意してください。

この機能を使用することでコネクション毎に経路を指定できます。

turn_fqdn 払い出し

Sora は、認証成功時のタイミングで接続単位での turn_fqdn の値を認証サーバーから払い出すことができます。

{
  "allowed": true,
  "turn_fqdn": "sora-turn.example.com"
}

この値は sora.conf の turn_fqdn の値を上書きします。

指定する FQDN を間違えると繋がらなくなるため、使用には注意してください。

turn_tls_fqdn の 払い出し

Sora は、認証成功時のタイミングで接続単位での turn_tls_fqdn の値を認証サーバーから払い出すことができます。

{
  "allowed": true,
  "turn_tls_fqdn": "sora-turn.example.com"
}

この値は sora.conf の turn_tls_fqdn の値を上書きします。指定する FQDN を間違えると繋がらなくなるため、使用には注意してください。

rtc_stats の払い出し

Sora は、認証成功時のタイミングで接続単位での rtc_stats の値を認証サーバーから払い出すことができます。

{
  "allowed": true,
  "rtc_stats": true
}

この値は sora.conf の default_rtc_stats の値を上書きします。

user_agent_stats の払い出し

注意

この設定は 2025 年 6 月に廃止します。

注意

この設定は 2025 年 6 月に廃止します。 rtc_stats の払い出し を利用してください。

Sora は、認証成功時のタイミングで接続単位での user_agent_stats の値を認証サーバーから払い出すことができます。

{
  "allowed": true,
  "user_agent_stats": true
}

この値は sora.conf の user_agent_stats の値を上書きします。

audio_streaming_language_code の払い出し

Sora は、認証成功時のタイミングで音声ストリーミングのランゲージコードの値を認証サーバーから払い出すことができます。

{
  "allowed": true,
  "audio_streaming_language_code": "ja-JP"
}

この値は接続時の audio_streaming_language_code と sora.conf の default_audio_streaming_language_code の値を上書きします。

stats_exporter の払い出し

注意

この設定は 2025 年 6 月に廃止します。

Sora は、認証成功時のタイミングで統計エクスポートをするかどうかの値を認証サーバから払い出すことができます。

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

この値は sora.conf の default_stats_exporter の値を上書きします。

turn_tcp_only / turn_tls_only の払い出し

重要

この設定は検証時のみ利用してください。

Sora は、認証成功時のタイミングで接続単位での turn_tcp_only または turn_tls_only の値を認証サーバーから払い出すことができます。

{
  "allowed": true,
  "turn_tcp_only": true
}

{
  "allowed": true,
  "turn_tls_only": true
}

この値は sora.conf の turn_tcp_only や turn_tls_only の値を上書きします。

rtp_packet_loss_simulator_incoming / rtp_packet_loss_simulator_outgoing の払い出し

重要

この設定は検証時のみ利用してください。

範囲:

0..100

Sora は、認証成功時のタイミングで接続単位での RTP パケットロスシミュレーターの値を認証サーバーから払い出すことができます。

{
  "allowed": true,
  "rtp_packet_loss_simulator_outgoing": 5
}

{
  "allowed": true,
  "rtp_packet_loss_simulator_incoming": 5
}

この値は sora.conf の rtp_packet_loss_simulator_incoming や rtp_packet_loss_simulator_outgoing の値を上書きします。

シーケンス図

        sequenceDiagram
    participant C as クライアント
    participant S as Sora
    participant A as アプリケーションサーバー
    C->>+S: "type": "connect"
    S->>+A: 認証ウェブフック
    note right of A: ここで払い出しする
    A-->>-S: 200 OK<br>"allowed": true
    S-)-C: "type": "offer"
    C-)S: "type": "answer"
    note over C,S: ICE 確立
    note over C,S: DTLS 確立
    note over C,S: WebRTC 確立
    

セッションウェブフック

概要

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

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

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

目的

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

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

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

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

セッション ID

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

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

設定

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 と log/session_webhook_error.jsonl に出力されます。 これは session_webhook_url を指定していなくても出力されます。

session_webhook.jsonl

セッションウェブフックの送信が 正常に動作した 処理を書き込みます。

項目

• id

  • Base32 UUIDv4

• timestamp

  • RFC 3339 UTC マイクロ秒

• req

  • リクエスト

  • センシティブデータはマスクされます

• res

  • レスポンス

  • センシティブデータはマスクされます

• url

  • セッションウェブフック URL

  • セッションウェブフックが指定されていなければ含まれません

session_webhook_error.jsonl

セッションウェブフックの送信が正常に処理できなかった処理を書き込みます。

• ステータスコードが 200 番台以外の場合

• タイムアウトした場合

項目

• id

  • Base32 UUIDv4

• timestamp

  • RFC 3339 UTC マイクロ秒

• req

  • リクエスト

  • センシティブデータはマスクされません

• reason

  • ウェブフックエラー理由

• url

  • セッションウェブフック URL

  • セッションウェブフックが指定されていなければ含まれません

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

既存セッションが存在する場合、 multistream と spotlight が異なる新規接続が来た場合は、 INVALID-MESSAGE エラーを返し切断するようになります。

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	string (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"
}

戻り値

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

session_metadata

注釈

この項目はセンシティブデータとして扱われます。

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

{
  "session_metadata": "<JSON>"
}

session_lifetime

セッション生成のタイミングで、セッションのライフタイムを指定することができます。

例えば 3600 を指定した場合、 3600 秒後にセッションは破棄されます

{
  "session_lifetime": 3600
}

• session_lifetime の指定にかかわらず、セッションの同時接続数が 0 になると、 session_destroyed_timeout に指定した時間が経過したタイミングでセッションが破棄されます

• 秒 で指定してください

• 最大 2,592,000 秒 (30 日) まで指定できます

• セッション生成後に変更することはできません

• session_lifetime が未指定の場合は 無制限 です

• session.destroyed の reason に lifetime_expired が入ります

• connection.destroyed の reason に session_destroyed が入ります

• セッションのライフタイムが終了すると、セッションが破棄され切断します

• セッションのライフタイムが終了すると、セッションウェブフック session.destroyed が送信されます

spotlight_number

セッション生成のタイミングで、スポットライト機能が有効な場合に、スポットライトの数を指定することができます。

クライアント単位でのシグナリング接続時や認証ウェブフック成功時の spotlight_number と異なる値を払い出した場合、 エラーとなりますので注意してください。 spotlight_number はセッションウェブフックでの指定を推奨します。

セッション単位の spotlight_number を変更するには ChangeSpotlightNumber API を利用する必要があります。

{
  "spotlight_number": 3
}

trial_max_connections

重要

この機能は実験的機能のトライアル中です、正式リリースに向けてサポートへのフィードバックをお願いしています。

注意

この機能を利用する場合は事前にサポートまでご連絡ください。

• trial_max_connections を指定した場合、セッション単位での最大同時接続数が指定した値になります。

• 途中で最大同時接続数を変更することはできません。指定できる範囲は 0..10000 です

• trial_max_connections が 0 の場合は誰も接続することができなくなります

• セッションが同時接続数制限に達した場合はクライアントに SERVICE-UNAVAILABLE を通知します

{
  "trial_max_connections": 3
}

recording

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

詳細は 録画機能 (セッション単位) の session.created をご確認ください。

{
  "recording": true
}

recording_expire_time

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

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

詳細は 録画機能 (セッション単位) の session.created をご確認ください。

{
  "recording_expire_time": 3600
}

recording_split_only

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

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

詳細は 録画機能 (セッション単位) の session.created をご確認ください。

{
  "recording_split_only": true
}

recording_split_duration

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

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

詳細は 録画機能 (セッション単位) の session.created をご確認ください。

{
  "recording_split_duration": 60
}

recording_metadata

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

詳細は 録画機能 (セッション単位) の session.created をご確認ください。

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

recording_format

recording が true の場合のみ有効です。録画ファイルのフォーマットを指定します。

webm と mp4 が指定できます。

詳細は 録画機能 (セッション単位) の session.created をご確認ください。

{
  "recording_format": "mp4"
}

forwarding_filters

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

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

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

forwarding_filter

注意

forwarding_filter は 2025 年 12 月リリース予定の Sora にて廃止します。

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	string (RFC3339 UTC マイクロ秒)	セッション生成時間
destroyed_time	integer (UNIX 時間)	セッション破棄時間
destroyed_timestamp	string (RFC3339 UTC マイクロ秒)	セッション破棄時間
multistream	boolean	マルチストリームが有効かどうか
spotlight	boolean	スポットライトが有効かどうか
spotlight_number	integer	スポットライトが有効な場合、スポットライト数
total_connections	integer	延べ接続数
max_connections	integer	最大同時接続数
connections	array (object)	(クラスター機能が無効の場合) セッションに参加した接続情報
session_metadata	json	(値がある場合) session.created の戻り値で指定した値
external_signaling_url	string	(クラスター機能が有効の場合) 接続先の external_signaling_url
reason	string	セッションが破棄された理由 ("normal", "validation_error", "webhook_error", "terminated_api", "lifetime_expired", "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"
}

connections

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

• connection_created_timestamp

• connection_destroyed_timestamp

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

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

reason

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

• "normal" は通常のセッション破棄

• "validation_error" は session.created の戻り値が正常ではなかったことによるエラーによるセッション破棄

  • このセッション破棄は session_created_response_validate_warning_as_error が true の場合のみ発生します

  • 例外: 転送フィルター機能 に関するバリデーション失敗は、この設定に関わらずエラーになりセッション破棄になります

• "webhook_error" はセッション生成時のウェブフック session.created のウェブフック処理中にエラーが発生したことによるセッション破棄

  • 以下はエラー例です

  • session_webhook_url と接続できなかった場合

  • ウェブフック送信先からステータスコードが 2XX 以外だった場合

  • ウェブフック送信先からの JSON がパースできなかった場合

  • ウェブフック送信先からの JSON のパース結果が JSON Object 以外だった場合

  • ウェブフック送信先との HTTPS に失敗した場合

  • ウェブフック送信先との mTLS に失敗した場合

• "terminated_api" は TerminateSession API によるセッション破棄

• "lifetime_expired" はセッションライフタイムの期限切れによるセッション破棄

• "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	string (RFC3339 UTC マイクロ秒)	セッション生成時間
multistream	boolean	マルチストリームが有効かどうか
spotlight	boolean	スポットライトが有効かどうか
spotlight_number	integer	スポットライトが有効な場合、スポットライト数
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

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

• connection_created_timestamp

• connection_destroyed_timestamp

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

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

クラスター有効時

クラスター有効時には 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
format	string	録画機能 (セッション単位) のフォーマット
start_timestamp	string	セッションでの録画が開始された時刻 (RFC 3339 (UTC))
split_only	boolean	セッションでの録画が分割のみかどうか
recording_metadata (オプション)	JSONValue	録画機能 (セッション単位) のメタデータ
expire_time (オプション)	integer	セッションでの録画期限
expired_at (オプション)	integer	セッションでの録画期限 (Unix time)
split_duration (オプション)	integer	セッションでの録画分割有効時の分割時間

{
  "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",
    "format": "mp4",
    "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

注意

セッションウェブフック session.vanished 利用する場合は事前にサポートまでご連絡ください

警告

セッションウェブフック 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

  • 録画機能 (セッション単位) を開始したタイムスタンプ (RFC3339 UTC マイクロ秒) が入ります

• 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 の項目が入ってきません

• data.format

  • この項目はオプションです

  • API による開始を行った場合は StartRecording API で指定した format が入ります

  • session.created ウェブフックリクエストの戻り値により録画を開始した場合は戻り値 recording_format が入ります

  • 指定していない場合は default_recording_format の値が入ります

{
  "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>",
    "format": "<String{webm, mp4}>"
  }
}

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>",
    "format": "<String{webm, mp4}>",
    "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>",
    "format": "<String{webm, mp4}>",
    "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 実行中に新規の接続が来た場合、その接続はいったん保留して、セッション破棄後に新規セッションでの接続として扱います。

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

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

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

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

• total_connections

• max_connections

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

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

• session.destroyed

• recording.started

• recording.report

• audio-streaming.stopped

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

セッションウェブフックはどのノードが送信しますか？

session.created を送信したノードが session.destroyed を送信します。

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 のように値が入ってきます。

シーケンス図

        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: セッションウェブフック<br/>type: session.created
    A-->>-S: 200 OK
    S->>C1: type: offer
    C1->>S: type: answer
    Note over C1,A: クライアント1 WebRTC 確立
    S->>+A: イベントウェブフック<br/>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: イベントウェブフック<br/>type: connection.created
    A-->>-S: 200 OK
    C1->>S: "type": "disconnect"
    S->>+A: イベントウェブフック<br/>type: connection.destroyed
    A-->>-S: 200 OK
    S->>C1: WebSocket Close
    Note over C1,A: クライアント1 WebRTC 切断
    C2->>S: "type": "disconnect"
    S->>+A: イベントウェブフック<br/>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: セッションウェブフック<br/>type: session.destroyed
    A-->>-S: 200 OK
    note right of S: セッションがすべて破棄された
    S->>+A: セッションウェブフック<br/>type: session.vanished
    A-->>-S: 200 OK
    

イベントウェブフック

概要

Sora は、予め設定しておいた URL に、シグナリングの接続や切断、 録画の開始や終了といった様々なイベントを HTTP リクエストとして送信するウェブフックの機能を持っています。

この機能を使うことで、Sora のイベントをアプリケーション側と簡単に連携できます。

注意

sora.conf の event_webhook_url を有効にしない場合でも log/event_webhook.jsonl は生成されます。

ログ

イベントウェブフックのログは log/event_webhook.jsonl と log/event_webhook_error.jsonl に出力されます。 これは event_webhook_url を指定していなくても出力されます。

event_webhook.jsonl

イベントウェブフックで送信した すべて の処理を書き込みます。

event_webhook_error.jsonl

イベントウェブフックの送信が正常に処理できなかった処理を書き込みます。

• ステータスコードが 200 番台以外の場合

• タイムアウトした場合

設定

event_webhook_url

デフォルト:

未設定

イベントウェブフックリクエスト送信先の URL です。イベントウェブフック機能を利用する場合は指定してください。

この URL には HTTP または HTTPS の URL を指定することができます。

HTTPS の URL を指定する場合、リクエスト送信先のアプリケーションについて基本的には正規の認証局から発行された証明書を利用してください。

独自の証明書を利用する場合は ウェブフックリクエスト送信先のサーバーが自己発行証明書などを利用している場合 をご確認ください。

HTTP のレスポンスは 200 OK 等の 200 番台のステータスコードの必要があります。

connection_updated_webhook_interval

デフォルト:

1 min

イベントウェブフック connection.updated の送信間隔を設定します。設定は分単位 (min) のみで行えます。

詳細は connection_updated_webhook_interval をご確認ください。

ignore_connection_updated_webhook

デフォルト:

false

イベントウェブフック connection.updated の送信有無を設定します。

詳細は ignore_connection_updated_webhook をご確認ください。

接続イベント

• connection.created と connection.destroyed はセットです

• connection.created がリクエスト送信されずに connection.destroyed がリクエスト送信されることはありません

• connection.created がリクエスト送信された場合、 connection.destroyed が 必ず リクエスト送信されます

• connection.created の後に connection.destroyed がリクエスト送信されます。順番は保証されます

共通項目

• id

  • イベントごとの ID です

• version

  • Sora のバージョンが 文字列 で入ってきます

• label

  • sora.conf の label で指定した値が入ってきます

• node_name

  • Sora のノード名が入ってきます

• log_written

  • イベントウェブフックログの書き込みが成功したかどうかが入ってきます

  • 書き込みが成功した場合は true が入ってきます

• minutes

  • 接続経過時間 (分) が入ってきます

• created_time

  • connection.created 時の時間が UNIX 時間形式で入ってきます

  • 例: 1704067199

• created_timestamp

  • connection.created 時の時間が RFC 3339 UTC 形式 (マイクロ秒) で入ってきます

  • 例: 2023-12-31T23:59:59.999999Z

• total_received_bytes

  • Sora がクライアントから受信したパケットの合計数です

• total_sent_bytes

  • Sora がクライアントへ送信したパケットの合計数です

• turn_transport_type

  • udp か tcp が入ってきます

  • TURN-UDP または TURN-TCP (TURN-TLS 含む) のどちらを使用したかがわかります

• audio

  • true または false が入ってきます

  • false の場合は audio を使用しません

• audio_codec_type

  • この項目はオプションです

  • audio が false の場合は含まれません

  • コーデックの種類は OPUS です

• audio_bit_rate

  • この項目はオプションです

  • audio が false やクライアントが送ってこない場合、含まれません

  • この設定は audio_codec_type が OPUS の時のみ有効です

  • default_audio_bit_rate に値を指定していた場合はその値が利用されます

  • 最小が 6 で、最大が 510 です

  • 単位は kbps です

• video

  • true または false が入ってきます

  • false の場合は video を使用しません

• video_codec_type

  • この項目はオプションです

  • video が false の場合は含まれません

  • コーデックはクライアントが送ってこない場合はデフォルトで VP9 が使用されます

  • コーデックの種類は VP8、 VP9、 AV1、 H264、 H265 です

• video_bit_rate

  • この項目はオプションです

  • video が false の場合は含まれません

  • ビットレートはクライアントが送ってこない場合は sora.conf の default_video_bit_rate が使用されます

  • デフォルトは 500 です

  • 最小が 1 で、最大が 30000 です

  • 15000 より大きい値は現時点でサポート範囲外です

  • 単位は kbps です

• video_vp9_params

  • この項目はオプションです

  • video が false の場合は含まれません

  • 詳細は ビデオの VP9 設定指定 をご確認ください

• video_av1_params

  • この項目はオプションです

  • video が false の場合は含まれません

  • 詳細は ビデオの AV1 設定指定 をご確認ください

• video_h264_params

  • この項目はオプションです

  • video が false の場合は含まれません

  • 詳細は ビデオの H.264 設定指定 をご確認ください

• video_h265_params

  • この項目はオプションです

  • video が false の場合は含まれません

  • 詳細は ビデオの H.265 設定指定 をご確認ください

• multistream

  • true の場合はマルチストリームが有効な接続です

• simulcast

  • true の場合はサイマルキャストが有効な接続です

• simulcast_multicodec

  • この項目はオプションです

  • true の場合はサイマルキャストでマルチコーデックが有効な接続です

• spotlight

  • true の場合はスポットライトが有効な接続です

• role

  • sendrecv (送受信) / sendonly (送信のみ) / recvonly (受信のみ)

• event_metadata

  • この項目はオプションです

  • サーバーが定義を自由にできる値です

  • 認証サーバーから event_metadata を返した値が含まれます

  • 詳細は event_metadata の払い出し をご確認ください

• channel_id

  • コネクションが接続しているチャネル ID です

• session_id

  • コネクションが接続しているチャネル の現在のセッションの ID です

  • UUIDv4 を Base32 でエンコードした 26 バイトの文字列です

• client_id

  • コネクションに割り当てられたクライアント ID です

• bundle_id

  • コネクションに割り当てられたバンドル ID です

• connection_id

  • コネクションに割り当てられたユニークな ID です

  • UUIDv4 を Base32 でエンコードした 26 バイトの文字列です

• ice_connection_state

  • total_checking_duration_ms

    • ICE 接続の状態が checking になった時間の合計 (ミリ秒) です

  • total_disconnected_duration_ms

    • ICE 接続の状態が disconnected になった時間の合計 (ミリ秒) です

• recording_block

  • 録画(セッション単位)時に録画をブロックするかどうかが入ってきます

  • true であれば録画をブロックします

  • false であれば録画をブロックしません

connection.created

接続

シグナリングの接続が成功して、WebRTC としての通信が開始できるようになった時の状態を送信します。

• data.channel_connections

  • 現在そのチャネルに接続しているクライアントの接続数です

  • 自分は含まれます

• data.channel_sendrecv_connections

  • 現在そのチャネルで送受信している配信者の接続数です

  • 自分は含まれます

• data.channel_sendonly_connections

  • 現在そのチャネルを送信のみしている配信者の接続数です

  • 自分は含まれます

• data.channel_recvonly_connections

  • 現在そのチャネルを受信のみしている視聴者の接続数です

  • 自分は含まれます

{
  "type": "connection.created",
  "channel_id": "<String>",
  "session_id": "<Base32-UUIDv4>",
  "client_id": "<String | Base32-UUIDv4>",
  "bundle_id": "<String | Base32-UUIDv4>",
  "connection_id": "<Base32-UUIDv4>",
  "timestamp": "<UTC RFC3339 Timestamp>",
  "event_metadata": "<JSON Object>",
  "data": {
    "ice_connection_state": {
      "total_checking_duration_ms": "<Integer>",
      "total_disconnected_duration_ms": "<Integer>"
    },
    "recording_block": "<Boolean>",
    "created_time": "<UNIX-Time>",
    "created_timestamp": "<UTC RFC3339 Timestamp>",
    "audio": "<Boolean>",
    "audio_codec_type": "<String>",
    "channel_connections": "<Integer>",
    "channel_recvonly_connections": "<Integer>",
    "channel_sendonly_connections": "<Integer>",
    "channel_sendrecv_connections": "<Integer>",
    "minutes": "<Integer>",
    "total_received_bytes": "<Integer>",
    "total_sent_bytes": "<Integer>",
    "turn_transport_type": "<String>",
    "video": "<Boolean>",
    "video_bit_rate": "<Integer>",
    "video_codec_type": "<String>"
  },
  "id": "<Base32-UUIDv4>",
  "label": "<String>",
  "node_name": "<String>",
  "log_written": "<Boolean>",
  "role": "<sendrecv | sendonly | recvonly>",
  "multistream": "<Boolean>",
  "simulcast": "<Boolean>",
  "spotlight": "<Boolean>",
  "version": "<String>"
}

connection.destroyed

切断

シグナリングの接続が切断した時に送信します。

• data.type_disconnect_reason

  • クライアントから "type": "disconnect" シグナリングメッセージに "reason" が項目に含まれていた際、その 文字列 が入ります

  • シグナリングメッセージに "reason" が含まれていなかった場合、この項目は含まれません

• data.disconnect_api_reason

  • DisconnectChannel API または DisconnectConnection API を利用して切断した際、オプションの "reason" に指定した JSON オブジェクト がこの "reason" に含まれます

  • "reason" を指定されていなかった場合、この項目は含まれません

• data.reason

  • コネクションが破棄された理由が含まれます

    • この値は常に含まれます

    • "normal" は通常のコネクション破棄

    • "disconnected_api" シグナリング切断系 API でのコネクション破棄

    • "session_destroyed" セッションライフタイム期限切れ、または TerminateSession API によるセッションの強制破棄でのコネクション破棄

    • "lifetime_expired" ライフタイム期限切れによるコネクション破棄

• data.channel_connections

  • 現在そのチャネルに接続しているクライアントの接続数です

  • 自分は含まれません

• data.channel_sendrecv_connections

  • 現在そのチャネルで送受信している配信者の接続数です

  • 自分は含まれません

• data.channel_sendonly_connections

  • 現在そのチャネルを送信のみしている配信者の接続数です

  • 自分は含まれません

• data.channel_recvonly_connections

  • 現在そのチャネルを受信のみしている視聴者の接続数です

  • 自分は含まれません

• data.destroyed_time

  • connection.destroyed 時の時間が UNIX 時間形式で入ってきます

• data.destroyed_timestamp

  • connection.destroyed 時の時間が RFC 3339 UTC 形式 (マイクロ秒) で入ってきます

{
  "type": "connection.destroyed",
  "channel_id": "<String>",
  "session_id": "<Base32-UUIDv4>",
  "client_id": "<String | Base32-UUIDv4>",
  "bundle_id": "<String | Base32-UUIDv4>",
  "connection_id": "<Base32-UUIDv4>",
  "timestamp": "<UTC RFC3339 Timestamp>",
  "event_metadata": "<JSON Object>",
  "data": {
    "ice_connection_state": {
      "total_checking_duration_ms": "<Integer>",
      "total_disconnected_duration_ms": "<Integer>"
    },
    "recording_block": "<Boolean>",
    "created_time": "<UNIX-Time>",
    "created_timestamp": "<UTC RFC3339 Timestamp>",
    "destroyed_time": "<UNIX-Time>",
    "destroyed_timestamp": "<UTC RFC3339 Timestamp>",
    "audio": "<Boolean>",
    "audio_codec_type": "<String>",
    "channel_connections": "<Integer>",
    "channel_recvonly_connections": "<Integer>",
    "channel_sendonly_connections": "<Integer>",
    "channel_sendrecv_connections": "<Integer>",
    "minutes": "<Integer>",
    "reason": "<String>",
    "type_disconnect_reason": "<String>",
    "total_received_bytes": "<Integer>",
    "total_sent_bytes": "<Intger>",
    "turn_transport_type": "<String>",
    "video": "<Boolean>",
    "video_bit_rate": "<Integer>",
    "video_codec_type": "<String>"
  },
  "id": "<Base32-UUIDv4>",
  "label": "<String>",
  "node_name": "<String>",
  "log_written": "<Boolean>",
  "role": "<sendrecv | sendonly | recvonly>",
  "multistream": "<Boolean>",
  "simulcast": "<Boolean>",
  "spotlight": "<Boolean>",
  "version": "<String>"
}

connection.updated

接続状態更新

注釈

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

connection.created を送信したタイミングから、クライアントごとの接続状態が、それぞれ一定間隔で送信されます。

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

• data.channel_connections

  • 現在そのチャネルに接続しているクライアントの接続数です

  • 自分が含まれます

• data.channel_sendrecv_connections

  • 現在そのチャネルで送受信している配信者の接続数です

  • 自分が含まれます

• data.channel_sendonly_connections

  • 現在そのチャネルを送信のみしている配信者の接続数です

  • 自分が含まれます

• data.channel_recvonly_connections

  • 現在そのチャネルを受信のみしている視聴者の接続数です

  • 自分が含まれます

{
  "type": "connection.updated",
  "channel_id": "<String>",
  "session_id": "<Base32-UUIDv4>",
  "client_id": "<String | Base32-UUIDv4>",
  "bundle_id": "<String | Base32-UUIDv4>",
  "connection_id": "<Base32-UUIDv4>",
  "timestamp": "<UTC RFC3339 Timestamp>",
  "event_metadata": "<JSON>",
  "data": {
    "ice_connection_state": {
      "total_checking_duration_ms": "<Integer>",
      "total_disconnected_duration_ms": "<Integer>"
    },
    "recording_block": "<Boolean>",
    "audio": "<Boolean>",
    "audio_codec_type": "<String>",
    "channel_connections": ,
    "channel_recvonly_connections": "<Integer>",
    "channel_sendonly_connections": "<Integer>",
    "channel_sendrecv_connections": "<Integer>",
    "created_time": "<UNIX-Time>",
    "created_timestamp": "<UTC RFC3339 Timestamp>",
    "minutes": "<Integer>",
    "total_received_bytes": "<Integer>",
    "total_sent_bytes": "<Integer>",
    "turn_transport_type": "<String>",
    "video": "<Boolean>",
    "video_bit_rate": "<Integer>",
    "video_codec_type": "<String>"
  },
  "id": "<Base32-UUIDv4>",
  "label": "<String>",
  "node_name": "<String>",
  "log_written": "<Boolean>",
  "role": "<sendrecv | sendonly | recvonly>",
  "multistream": "<Boolean>",
  "simulcast": "<Boolean>",
  "spotlight": "<Boolean>",
  "version": "<String>"
}

connection.failed

接続失敗

重要

このイベントのログの出力やウェブフックを出力する場合、 sora.conf にて ignore_connection_failed_webhook を無効にする必要があります。

sora.conf の legacy_signaling_error が false の場合は認証成功後、 かつ connection.created の送信前に接続に失敗した際に送られます。

• connection.created の送信前に失敗や異常が起きた場合に送信されます

• connection.created の送信後に失敗や異常が起きた場合、 connection.destroyed が送信されます

{
  "type": "connection.failed",
  "id": "<Base32-UUIDv4>",
  "role": "<sendrecv | sendonly | recvonly>",
  "channel_id": "<String>",
  "client_id": "<String | Base32-UUIDv4>",
  "bundle_id": "<String | Base32-UUIDv4>",
  "connection_id": "<Base32-UUIDv4>",
  "timestamp": "<UTC RFC3339 Timestamp>",
  "data": {
    "message": "<String>",
    "channel_connections": "<Integer>",
    "channel_sendrecv_connections": "<Integer>",
    "channel_sendonly_connections": "<Integer>",
    "channel_recvonly_connections": "<Integer>",
    "total_received_bytes": "<Integer>",
    "total_sent_bytes": "<Integer>"
  },
  "label": "<String>",
  "node_name": "<String>",
  "log_written": "<Boolean>",
  "multistream": "<Boolean>",
  "simulcast": "<Boolean>",
  "spotlight": "<Boolean>",
  "version": "<String>"
}

録画・録音イベント

危険

このレガシー録画向けのイベントウェブフックは 2025 年 12 月に廃止します 録画機能 (セッション単位) への移行をお願いします。

重要

このイベントウェブフックは レガシー録画機能 利用時に送信します。

recording.started

重要

このイベントには event_metadata は含まれません

レガシー録画開始

• data.start_timestamp

  • StartRecording API を実行したタイムスタンプが入ります

• data.expire_time

  • StartRecording API で指定した expire_time が入ります

• data.expired_at

  • StartRecording API で指定した expire_time から計算した有効期限が入ります

• data.split_duration

  • この項目はオプションです

  • StartRecording API で指定した split_duration が入ります

  • 指定していない場合は split_duration の項目が入ってきません

• data.split_only

  • この項目はオプションです

  • StartRecording API で指定した split_only が入ります

  • 指定していない場合は false が入ります

• data.metadata

  • この項目はオプションです

  • StartRecording API で指定した metadata が入ります

  • 指定していない場合は metadata の項目が入ってきません

{
  "type": "recording.started",
  "id": "<Base32-UUIDv4>",
  "version": "<String>",
  "label": "<String>",
  "node_name": "<String>",
  "log_written": "<Boolean>",
  "channel_id": "<String>",
  "timestamp": "<UTC RFC3339 Timestamp>",
  "data": {
    "channel_id": "<String>",
    "recording_id": "<Base32-UUIDv4>",
    "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

重要

このイベントには event_metadata は含まれません

レガシー録画結果報告

• data.archives[].start_time_offset

  • StartRecording API を叩いてから何秒経過した後にこの録画が開始したかを表しています

• data.archives[].stop_time_offset

  • StartRecording API を叩いてから何秒経過した後にこの録画が終了したかを表しています

• data.metadata

  • StartRecording API で指定した metadata が入ります

  • 指定していない場合は metadata の項目が入ってきません

• data.expired_at

  • 期限が切れた日時を UNIX Time で返します

一括録画時 recording.report

{
  "type": "recording.report",
  "id": "<Base32-UUIDv4>",
  "version": "<String>",
  "label": "<String>",
  "node_name": "<String>",
  "log_written": "<Boolean>",
  "channel_id": "<String>",
  "timestamp": "<UTC RFC3339 Timestamp>",
  "data": {
    "channel_id": "<String>",
    "recording_id": "<Base32-UUIDv4>",
    "metadata": "<JSON-Object>",
    "split_only": "<Boolean>",
    "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>",
  "log_written": "<Boolean>",
  "channel_id": "<String>",
  "timestamp": "<UTC RFC3339 Timestamp>",
  "data": {
    "channel_id": "<String>",
    "recording_id": "<Base32-UUIDv4>",
    "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>"
      }
    ]
  }
}

録画・録音保存イベント

archive.started

録画ファイル保存開始

• data.start_timestamp

  • この録画が開始された時間 (UTC) を RFC 3339 形式 (マイクロ秒) で表しています

• data.format

  • 録画ファイルのフォーマット

  • webm または mp4 が入ります

{
  "type": "archive.started",
  "id": "<Base32-UUIDv4>",
  "version": "<String>",
  "label": "<String>",
  "node_name": "<String>",
  "log_written": "<Boolean>",
  "channel_id": "<String>",
  "session_id": "<Base32-UUIDv4>",
  "client_id": "<String | Base32-UUIDv4>",
  "bundle_id": "<String | Base32-UUIDv4>",
  "connection_id": "<Base32-UUIDv4>",
  "timestamp": "<UTC RFC3339 Timestamp>",
  "event_metadata": "<JSON>",
  "data": {
    "channel_id": "<String>",
    "recording_id": "<Base32-UUIDv4>",
    "session_id": "<Base32-UUIDv4>",
    "client_id": "<String | Base32-UUIDv4>",
    "bundle_id": "<String | Base32-UUIDv4>",
    "connection_id": "<Base32-UUIDv4>",
    "created_at": "<Unix Time>",
    "audio": true,
    "audio_codec_type": "<String>",
    "video": true,
    "video_codec_type": "<String>",
    "video_bit_rate": "<Integer>",
    "start_time": "<Unix Time>",
    "start_time_offset": "<Integer>",
    "start_timestamp": "<UTC RFC3339 Timestamp>",
    "format": "<String{webm, mp4}>"
  }
}

archive.available

録画保存ファイル出力

録画ファイルが出力されて利用できるようになったことを通知するウェブフックです。

• data.start_timestamp

  • この録画が開始された時間 (UTC) を RFC 3339 形式 (マイクロ秒) で表しています

• data.stop_timestamp

  • この録画が終了した時間(UTC) を RFC 3339 形式 (マイクロ秒) で表しています

• data.start_time

  • この録画が開始された時間を UNIX 時間形式で表しています

• data.stop_time

  • この録画が終了した時間を UNIX 時間形式で表しています

• data.start_time_offset

  • StartRecording API を叩いてから何秒経過した後にこの録画が開始したかを表しています

• data.stop_time_offset

  • StartRecording API を叩いてから何秒経過した後にこの録画が終了したかを表しています

• data.stats

  • サポート向けに、録画に使用したパケット情報の統計を格納しています

  • 内部向け情報のため、予告なく変更されることがあります

• data.format

  • 録画ファイルのフォーマット

  • webm または mp4 が入ります

{
  "type": "archive.available",
  "id": "<Base32-UUIDv4>",
  "version": "<String>",
  "label": "<String>",
  "node_name": "<String>",
  "log_written": "<Boolean>",
  "channel_id": "<String>",
  "session_id": "<Base32-UUIDv4>",
  "client_id": "<String | Base32-UUIDv4>",
  "bundle_id": "<String | Base32-UUIDv4>",
  "connection_id": "<Base32-UUIDv4>",
  "timestamp": "<UTC RFC3339 Timestamp>",
  "event_metadata": "<JSON>",
  "data": {
    "channel_id": "<String>",
    "recording_id": "<Base32-UUIDv4>",
    "session_id": "<Base32-UUIDv4>",
    "client_id": "<String | Base32-UUIDv4>",
    "bundle_id": "<String | Base32-UUIDv4>",
    "connection_id": "<Base32-UUIDv4>",
    "created_at": "<Unix Time>",
    "file_path": "<String>",
    "filename": "<String>",
    "metadata_file_path": "<String>",
    "metadata_filename": "<String>",
    "size": "<Integer>",
    "audio": true,
    "audio_codec_type": "<String>",
    "video": true,
    "video_codec_type": "<String>",
    "video_bit_rate": "<Integer>",
    "video_height": "<Integer>",
    "video_width": "<Integer>",
    "stats": {},
    "start_time": "<Unix Time>",
    "start_time_offset": "<Integer>",
    "start_timestamp": "<UTC RFC3339 Timestamp>",
    "stop_time": "<Unix Time>",
    "stop_time_offset": "<Integer>",
    "stop_timestamp": "<UTC RFC3339 Timestamp>",
    "format": "<String{webm, mp4}>"
  }
}

split-archive.available

分割録画ファイル出力

分割録画ファイルが出力されて利用できるようになったことを通知するウェブフックです。

• data.split_index

  • 分割された録画ファイルのインデックス

  • 0001 から始まり 9999 までいったら、その後は 10000, 10001 と増えていきます

• data.start_timestamp

  • 分割して出力された録画ファイルを開始された時間 (UTC) を RFC 3339 形式 (マイクロ秒) で表しています

• data.stop_timestamp

  • 分割して出力された録画ファイルを終了した時間 (UTC) を RFC 3339 形式 (マイクロ秒) で表しています

• data.start_time

  • 分割して出力された録画ファイルを開始した時間を UNIX 時間形式で表しています

• data.stop_time

  • 分割して出力された録画ファイルを終了した時間を UNIX 時間形式で表しています

• data.start_time_offset

  • この分割して出力された録画が、StartRecording API を叩いてから何秒経過した後に開始したかを表しています

• data.stop_time_offset

  • この分割して出力された録画が、StartRecording API を叩いてから何秒経過した後に終了したかを表しています

• data.stats

  • サポート向けに、録画に使用したパケット情報の統計を格納しています

  • 内部向け情報のため、予告なく変更されることがあります

{
  "type": "split-archive.available",
  "id": "<Base32-UUIDv4>",
  "version": "<String>",
  "label": "<String>",
  "node_name": "<String>",
  "log_written": "<Boolean>",
  "channel_id": "<String>",
  "session_id": "<Base32-UUIDv4>",
  "client_id": "<String | Base32-UUIDv4>",
  "bundle_id": "<String | Base32-UUIDv4>",
  "connection_id": "<Base32-UUIDv4>",
  "timestamp": "<UTC RFC3339 Timestamp>",
  "event_metadata": "<JSON>",
  "data": {
    "channel_id": "<String>",
    "recording_id": "<Base32-UUIDv4>",
    "split_index": "<String>",
    "session_id": "<Base32-UUIDv4>",
    "client_id": "<String | Base32-UUIDv4>",
    "bundle_id": "<String | Base32-UUIDv4>",
    "connection_id": "<Base32-UUIDv4>",
    "created_at": "<Unix Time>",
    "file_path": "<String>",
    "filename": "<String>",
    "metadata_file_path": "<String>",
    "metadata_filename": "<String>",
    "size": "<Integer>",
    "audio": true,
    "audio_codec_type": "<String>",
    "video": true,
    "video_codec_type": "<String>",
    "video_bit_rate": "<Integer>",
    "video_height": "<Integer>",
    "video_width": "<Integer>",
    "stats": {
    },
    "start_time": "<Unix Time>",
    "start_time_offset": "<Integer>",
    "start_timestamp": "<UTC RFC3339 Timestamp>",
    "stop_time": "<Unix Time>",
    "stop_time_offset": "<Integer>",
    "stop_timestamp": "<UTC RFC3339 Timestamp>",
    "format": "<String{webm, mp4}>"
  }
}

注釈

stats は省略しています

split-archive.end

分割録画終了

分割録画ファイルが全て出力し終わったことを通知するウェブフックです。 このウェブフック以降は split-archive.available は送信されません。

• data.start_time

  • 録画を開始した UNIX 時間形式で表しています

• data.stop_time

  • 録画を終了した UNIX 時間形式で表しています

• data.start_timestamp

  • 録画を開始した時間 (UTC) を RFC 3339 形式 (マイクロ秒) で表しています

• data.stop_timestamp

  • 録画を終了した時間 (UTC) を RFC 3339 形式 (マイクロ秒) で表しています

• data.stats

  • サポート向けに、録画に使用したパケット情報の統計を格納しています

  • 内部向け情報のため、予告なく変更されることがあります

{
  "type": "split-archive.end",
  "id": "<Base32-UUIDv4>",
  "version": "<String>",
  "label": "<String>",
  "node_name": "<String>",
  "log_written": "<Boolean>",
  "channel_id": "<String>",
  "session_id": "<Base32-UUIDv4>",
  "client_id": "<String | Base32-UUIDv4>",
  "bundle_id": "<String | Base32-UUIDv4>",
  "connection_id": "<Base32-UUIDv4>",
  "timestamp": "<UTC RFC3339 Timestamp>",
  "event_metadata": "<JSON>",
  "data": {
    "split_last_index": "<String>",
    "recording_id": "<Base32-UUIDv4>",
    "channel_id": "<String>",
    "session_id": "<Base32-UUIDv4>",
    "client_id": "<String | Base32-UUIDv4>",
    "bundle_id": "<String | Base32-UUIDv4>",
    "connection_id": "<Base32-UUIDv4>",
    "audio": true,
    "audio_codec_type": "<String>",
    "video": true,
    "video_codec_type": "<String>",
    "video_bit_rate": "<Integer>",
    "file_path": "<String>",
    "filename": "<String>",
    "stats": {},
    "start_time": "<Unix Time>",
    "start_time_offset": "<Integer>",
    "start_timestamp": "<UTC RFC3339 Timestamp>",
    "stop_time": "<Unix Time>",
    "stop_time_offset": "<Integer>",
    "stop_timestamp": "<UTC RFC3339 Timestamp>",
    "format": "<String{webm, mp4}>"
  }
}

archive.failed

録画ファイル保存失敗

このウェブフックが発生するのは、ディスク容量が足らなかったり、ディスクが故障してたり、 パーミッションにより書き込めなかった場合です。

単一録画、分割録画関係なくクライアントの録画ファイル保存に失敗した場合には発生し、クライアントの録画は停止されます。 書き込めない可能性がとても高いため、分割録画の場合でも録画はその時点で停止します。

もし問題を解決できた場合は、一度録画を停止し、再度録画を開始するようにしてください。

{
  "type": "archive.failed",
  "id": "<Base32-UUIDv4>",
  "version": "<String>",
  "label": "<String>",
  "node_name": "<String>",
  "log_written": "<Boolean>",
  "timestamp": "<UTC RFC3339 Timestamp>",
  "channel_id": "<String>",
  "session_id": "<Base32-UUIDv4>",
  "client_id": "<String | Base32-UUIDv4>",
  "bundle_id": "<String | Base32-UUIDv4>",
  "connection_id": "<Base32-UUIDv4>",
  "event_metadata": "<JSON>",
  "data": {
    "recording_id": "<Base32-UUIDv4>",
    "session_id": "<Base32-UUIDv4>",
    "split": "<Boolean>",
    "split_only": "<Boolean>",
    "file_path": "<String>",
    "filename": "<String>",
    "audio": true,
    "audio_codec_type": "<String>",
    "video": true,
    "video_codec_type": "<String>",
    "video_bit_rate": "<Integer>",
    "video_height": "<Integer>",
    "video_width": "<Integer>",
    "stats": {},
    "start_time": "<Unix Time>",
    "start_timestamp": "<UTC RFC3339 Timestamp>",
    "stop_time": "<Unix Time>",
    "stop_timestamp": "<UTC RFC3339 Timestamp>",
    "format": "<String{webm, mp4}>"
  }
}

スポットライト機能

spotlight.focused

フォーカス設定

フォーカスされた際にウェブフックを送信します。

{
  "type": "spotlight.focused",
  "channel_id": "<String>",
  "client_id": "<String | Base32-UUIDv4>",
  "bundle_id": "<String | Base32-UUIDv4>",
  "connection_id": "<Base32-UUIDv4>",
  "timestamp": "<UTC RFC3339 Timestamp>",
  "spotlight_number:": "<Integer>",
  "fixed": "<Boolean>",
  "id": "<Base32-UUIDv4>",
  "label": "<String>",
  "version": "<String>",
  "node_name": "<String>",
  "log_written": "<Boolean>",
  "audio": "<Boolean>",
  "video": "<Boolean>"
}

spotlight.unfocused

フォーカス解除

フォーカスが外れた際にウェブフックを送信します。

{
  "type": "spotlight.unfocused",
  "channel_id": "<String>",
  "client_id": "<String | Base32-UUIDv4>",
  "bundle_id": "<String | Base32-UUIDv4>",
  "connection_id": "<Base32-UUIDv4>",
  "timestamp": "<UTC RFC3339 Timestamp>",
  "spotlight_number:": "<Integer>",
  "audio": "<Boolean>",
  "id": "<Base32-UUIDv4>",
  "label": "<String>",
  "version": "<String>",
  "node_name": "<String>",
  "log_written": "<Boolean>",
  "audio": "<Boolean>",
  "video": "<Boolean>"
}

音声ストリーミング機能

audio-streaming.failed

音声ストリーミング URL への接続を諦めた際にウェブフックを送信します。

{
  "type": "audio-streaming.failed",
  "id": "<Base32-UUIDv4>",
  "timestamp": "<UTC RFC3339 Timestamp>",
  "label": "<String>",
  "version": "<String>",
  "node_name": "<String>",
  "log_written": "<Boolean>",
  "channel_id": "<String>",
  "session_id": "<Base32-UUIDv4>",
  "client_id": "<String | Base32-UUIDv4>",
  "bundle_id": "<String | Base32-UUIDv4>",
  "connection_id": "<Base32-UUIDv4>",
  "data": {
    "failed_reason": "<String>"
  },
  "role": "<sendrecv | sendonly | recvonly>",
  "multistream": "<Boolean>",
  "simulcast": "<Boolean>",
  "spotlight": "<Boolean>"
}

HTTP ヘッダー

警告

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

注釈

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

sora-event-webhook-type

注意

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

イベントウェブフックの HTTP ヘッダー に sora-event-webhook-type と x-sora-event-webhook-type というヘッダー名でイベントウェブフックのタイプが入ってきます。

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

sora-session-id

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

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

sora-connection-id

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

コネクション ID が 7WSWCM0Z2H0614W5PJERR3F5WR の場合は sora-connection-id: 7WSWCM0Z2H0614W5PJERR3F5WR のように値が入ってきます。

シーケンス図

connection.*

        sequenceDiagram
    participant C as クライアント
    participant S as WebRTC SFU S
    participant A as アプリケーションサーバー
    note over C,A: 認証成功
    S->>C: "type": "offer"
    C->>S: "type": "answer"
    note over C,S: WebRTC 確立
    S->>+A: イベントウェブフック<br/>"type": "connection.created"
    A-->>-S: 200 OK
    note over C,S: 接続から 1 分経過
    S->>+A: イベントウェブフック<br/>"type": "connection.updated"
    A-->>-S: 200 OK
    C->>S: "type": "disconnect"
    S->>+A: イベントウェブフック<br/>"type": "connection.destroyed"
    A-->-S: 200 OK
    S->>C: WebSocket Close
    

event_metadata

        sequenceDiagram
    participant C as クライアント
    participant S as WebRTC SFU S
    participant A as アプリケーションサーバー
    C->>+S: "type": "connect"
    S->>+A: 認証ウェブフック
    A-->>-S: 200 OK<br>"allowed: true,<br>"event_metadata": {"pk": 1}
    S->>C: "type": "offer"
    C->>S: "type": "answer"
    note over C,S: WebRTC 確立
    S->>+A: イベントウェブフック<br/>"type": "connection.created",<br>"event_metadata": {"pk": 1}
    A-->>-S: 200 OK
    note over C,S: 接続から 1 分経過
    S->>+A: イベントウェブフック<br/>"type": "connection.updated",<br>"event_metadata": {"pk": 1}
    A-->>-S: 200 OK
    C->>S: "type": "disconnect"
    S->>+A: イベントウェブフック<br/>"type": "connection.destroyed",<br>"event_metadata": {"pk": 1}
    A-->-S: 200 OK
    S->>C: WebSocket Close
    

統計ウェブフック

注意

この機能を利用する場合は事前にサポートまでご連絡ください

警告

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

概要

統計情報をウェブフックで送信する機能です。

注意

sora.conf の stats_webhook_url を有効にしない場合、 log/stats_webhook.jsonl は生成されません。

ログ

統計ウェブフックのログは log/stats_webhook.jsonl と log/stats_webhook_error.jsonl に出力されます。

統計ウェブフックのログではデフォルトで出力されません。 stats_webhook_url を有効にしたとしても stats_webhook_log を true に設定するまでは、 ログが出力されません。

stats_webhook.jsonl

統計ウェブフックで送信した すべて の処理を書き込みます。

stats_webhook_error.jsonl

統計ウェブフックの送信が失敗した処理を書き込みます。

統計ウェブフックの間隔

Sora は一定間隔でクライアントへ統計情報を要求します。

統計ウェブフックの送信間隔はクライアントが送ってくる RTC 統計情報の間隔に依存します。デフォルトは 60 秒です。

WebSocket シグナリングを利用している場合

websocket_stats_timer_interval に指定した間隔になります。

WebSocket の場合は "type": "ping" に "stats": true を付けて送信することで、 クライアントへ統計情報を要求します。

クライアントは "type": "pong" で "stats": ... に統計情報を含めて送ります。 この "stats" が統計ウェブフックの "stats" 項目として送信されます。

        sequenceDiagram
    participant C as クライアント
    participant S as Sora
    participant A as アプリケーションサーバー
    note over C,S: WebRTC 確立
    S-)C: "type": "ping"<br>WebSocket
    C-)S: "type": "pong"<br>WebSocket

    S-)C: "type": "ping"<br>"stats": true<br>WebSocket
    C-)S: "type": "pong"<br>"stats": ...<br>WebSocket
    S->>+A: Stats over HTTP/1.1
    A->>-S: 200 OK
    note over C,S: 60 秒経過
    S-)C: "type": "ping"<br>"stats": true<br>WebSocket
    C-)S: "type": "pong"<br>"stats": ...<br>WebSocket
    S->>+A: Stats over HTTP/1.1
    A->>-S: 200 OK
    

DataChannel シグナリングを利用している場合

data_channel_stats_timer_interval に指定した間隔になります。

DataChannel シグナリングの場合は stats ラベルを利用して、 "type": "req-stats" を送ってクライアントへ統計情報を要求します。

クライアントは stats ラベルを利用して、 "type": "stats" で "reports" に統計情報を含めて送ります。 この "reports" が統計ウェブフックの "stats" 項目として送信されます。

        sequenceDiagram
    participant C as クライアント
    participant S as Sora
    participant A as アプリケーションサーバー
    note over C,S: WebRTC 確立
    S-)C: "type": "stats-req"<br>DataChannel
    C-)S: "type": "stats"<br>DataChannel
    S->>+A: Stats over HTTP/1.1
    A->>-S: 200 OK
    note over C,S: 60 秒経過
    S-)C: "type": "stats-req"<br>DataChannel
    C-)S: "type": "stats"<br>DataChannel
    S->>+A: Stats over HTTP/1.1
    A->>-S: 200 OK
    

設定

stats_webhook_url

統計情報を送信するウェブフック URL を指定します。 HTTP または HTTPS の URL が指定できます。

stats_webhook_url = http://192.0.2.10:5890/sora/webhook/stats

stats_webhook_log

統計情報ウェブフックのログを出力するかどうかを指定します。デフォルトは false で出力しません。

• 統計情報ウェブフックの送信した 全ての処理 は log/stats_webhook.jsonl ログに出力されます

• 統計情報ウェブフックの送信が 失敗した処理 は log/stats_webhook_error.jsonl ログに出力されます

stats_webhook_log = true

ignore_connection_rtc_webhook

統計情報ウェブフックの type: connection.rtc を送信するかどうかを指定します。デフォルトは false で送信します。

rtc_stats_log

統計情報ウェブフックの type: connection.rtc の stats をリストではなく個別に rtc_stats.jsonl として出力するどうかを指定します。

ログは log/rtc_stats.jsonl に出力されます。

rtc_stats_log = true

stats_webhook_worker_number

統計ウェブフックのワーカー数を指定できます。 基本的にはデフォルトの 5 で足りますが、同時接続数が多い場合は変更をお勧めします。

stats_webhook_worker_number = 5

統計情報

統計情報をウェブフック URL に対して送信します

共通

• type

  • 統計情報の種類が入ります

• id

  • ウェブフック ID が入ります

• node_name

  • Sora のノード名が入ります

  • クラスター機能を利用していない場合は sora@127.0.0.1 です

• version

  • Sora のバージョンが入ります

• label

  • sora.conf に設定された label が入ります

• timestamp

  • Sora が stats を送る直前の時間 RFC3339 形式 (UTC) が入ります

HTTP ヘッダー

注釈

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

統計ウェブフックの HTTP ヘッダー に sora-stats-webhook-type というヘッダー名で統計ウェブフックのタイプが入ってきます。 type が connection.rtc の場合は sora-stats-webhook-type: connection.rtc が入ってきます。

type: connection.rtc

クライアントから送られてくる統計情報です。

クライアント統計情報は W3C の Identifiers for WebRTC's Statistics API に準拠している必要があります。

• type

  • connection.rtc

• channel_id

  • チャネル ID が入ります

• role

• session_id

  • セッション ID が入ります

• client_id

• bundle_id

• connection_id

• multistream

• simulcast

• spotlight

• stats

{
  "channel_id": "sora",
  "session_id": "78K3N8E5M551XEKEWR8QN77PHW",
  "client_id": "NCD5EF3ME900ZDJ3SE27Y6AB6R",
  "bundle_id": "NCD5EF3ME900ZDJ3SE27Y6AB6R",
  "connection_id": "NCD5EF3ME900ZDJ3SE27Y6AB6R",
  "id": "N6W0DBF6A957B01BKNJJR1HC04",
  "label": "WebRTC SFU Sora",
  "multistream": true,
  "spotlight": false,
  "simulcast": true,
  "stats": [
    {
      "id": "RTCAudioSource_5",
      "kind": "audio",
      "timestamp": 1629449091306.655,
      "type": "media-source",
      "audioLevel": 0.02237006744590594,
      "totalAudioEnergy": 0.15581033797981153,
      "totalSamplesDuration": 5.089999999999936,
      "trackIdentifier": "922dd031-8a4f-4122-9687-ce094fa11ee2"
    }, ...
  ],
  "timestamp": "2021-08-20T08:44:51.308778Z",
  "type": "connection.rtc",
  "node_name": "[email protected]",
  "version": "2024.1.0",
  "log_written": false
}

stats 項目に含まれる統計情報の送信頻度

変化が無かったり変化の少ない stats 項目に含まれる統計情報を送る頻度を減らしています。

デフォルト 600 秒間隔にしています。

type: connection.rtc

送信頻度を抑えている RTCStatsType は以下の通りです。

• codec

  • Sora の場合、初期値から変更される項目が無いため

• local-candidate

  • Sora の場合、初期値から変更される項目が無いため

• remote-candidate

  • Sora の場合、初期値から変更される項目が無いため

• certificate

  • Sora の場合、初期値から変更される項目が無いため

• peer-connection

  • Sora の場合、初期値から変更される項目が無いため

• track

  • DEPRECATED 項目のため

• stream

  • DEPRECATED 項目のため

これらの統計情報は 600 秒間隔で stats 項目に含まれるようになります。

RTC 統計情報ログ出力

sora.conf で rtc_stats_log = true に設定すると、 log/rtc_stats.jsonl に RTC 統計情報が出力されます。 解析をしやすくするため、このログは type: connection.rtc の stats をリストではなく個別に出力します。

項目

• rtc_timestamp

  • RTCStats の timestamp が浮動小数点で入ります

  • https://www.w3.org/TR/webrtc-stats/#dom-rtcstats-timestamp

• rtc_type

  • RTCStats の type が文字列で入ります

  • https://www.w3.org/TR/webrtc-stats/#dom-rtcstats-type

• rtc_id

  • RTCStats の id が文字列で入ります

  • https://www.w3.org/TR/webrtc-stats/#dom-rtcstats-id

• rtc_data

  • RTCStats がそのまま入ります

例

{
   "connection_id": "16ZN7HHK5H3PFDFRZCZQN3WVD4",
   "id": "Z47B1V0DBN7R1AV90HY98CF6Y8",
   "label": "WebRTC SFU Sora",
   "timestamp": "2024-03-24T07:14:37.423158Z",
   "type": "connection.rtc",
   "version": "2024.1.0",
   "node_name": "[email protected]",
   "session_id": "FVR7SV953D08ZA0Z3SVCF9HFBR",
   "role": "sendrecv",
   "channel_id": "sora",
   "client_id": "16ZN7HHK5H3PFDFRZCZQN3WVD4",
   "bundle_id": "16ZN7HHK5H3PFDFRZCZQN3WVD4",
   "multistream": true,
   "spotlight": false,
   "simulcast": false,
   "log_written": true,
   "rtc_data": {
      "active": true,
      "id": "OTdata1A2223648171",
      "type": "outbound-rtp",
      "kind": "audio",
      "ssrc": 2223648171,
      "mid": "audio_jDlbho",
      "bytesSent": 117003,
      "codecId": "COTdata1_109_maxplaybackrate=48000;minptime=10;sprop-stereo=1;stereo=1;usedtx=0;useinbandfec=1",
      "headerBytesSent": 1248040,
      "mediaSourceId": "SA21",
      "mediaType": "audio",
      "nackCount": 0,
      "packetsSent": 39001,
      "remoteId": "RIA2223648171",
      "retransmittedBytesSent": 0,
      "retransmittedPacketsSent": 0,
      "targetBitrate": 64000,
      "totalPacketSendDelay": 0.0139959999999999997605,
      "transportId": "Tdata1"
   },
   "rtc_id": "OTdata1A2223648171",
   "rtc_timestamp": 1711264477421.78710938,
   "rtc_type": "outbound-rtp"
}
{
   "connection_id": "16ZN7HHK5H3PFDFRZCZQN3WVD4",
   "id": "Z47B1V0DBN7R1AV90HY98CF6Y8",
   "label": "WebRTC SFU Sora",
   "timestamp": "2024-03-24T07:14:37.423158Z",
   "type": "connection.rtc",
   "version": "2024.1.0",
   "node_name": "[email protected]",
   "session_id": "FVR7SV953D08ZA0Z3SVCF9HFBR",
   "role": "sendrecv",
   "channel_id": "sora",
   "client_id": "16ZN7HHK5H3PFDFRZCZQN3WVD4",
   "multistream": true,
   "spotlight": false,
   "simulcast": false,
   "log_written": true,
   "rtc_data": {
      "id": "Tdata1",
      "type": "transport",
      "bytesReceived": 104251,
      "bytesSent": 28783357,
      "dtlsCipher": "TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256",
      "dtlsRole": "client",
      "dtlsState": "connected",
      "iceLocalUsernameFragment": "90QS",
      "iceRole": "controlled",
      "iceState": "connected",
      "localCertificateId": "CF1F:6E:2B:47:36:FB:64:72:F9:D7:63:C3:16:6D:02:BB:72:62:E9:C0:E1:40:B6:13:E0:90:B2:E5:6C:49:98:6A",
      "packetsReceived": 1305,
      "packetsSent": 74835,
      "remoteCertificateId": "CF0E:AE:2F:F6:0D:EC:07:E4:27:13:34:38:02:EE:BB:EC:07:BA:77:9D:1C:B5:19:93:E0:A2:87:D5:A6:AA:6B:9A",
      "selectedCandidatePairChanges": 5,
      "selectedCandidatePairId": "CPLE514/b5_sVhdyppm",
      "srtpCipher": "AEAD_AES_128_GCM",
      "tlsVersion": "FEFD"
   },
   "rtc_id": "Tdata1",
   "rtc_timestamp": 1711264477421.78710938,
   "rtc_type": "transport"
}

ウェブフックの型定義

ここではウェブフックの型について説明します。

型の表記は TypeScript で記述します。

基本的なデータ型

// JSON 値を表します。
// 仕様は RFC 8259 に従います。
type JSONValue =
  | null
  | boolean
  | number
  | string
  | JSONValue[]
  | { [key: string]: JSONValue | undefined };

// UnixTime
// 例: 1704067199
type UnixTime = number;

// RFC3339 UTC (マイクロ秒)
// 例: 2023-12-31T23:59:59.999999Z
type Timestamp = string;

// ストリームの種別
type Role = "sendrecv" | "sendonly" | "recvonly";

// サイマルキャストで視聴する映像の種類
type SimulcastRid = "r0" | "r1" | "r2";

// 音声の設定
type Audio =
  | boolean
  | {
      codec_type?: AudioCodecType;
      bit_rate?: number;
      opus_params?: OpusParams;
    };

type OpusParams = {
  channels?: number;
  maxplaybackrate?: number;
  minptime?: number;
  ptime?: number;
  stereo?: boolean;
  sprop_stereo?: boolean;
  useinbandfec?: boolean;
  usedtx?: boolean;
};

// 映像の設定
type Video =
  | boolean
  | {
      codec_type?: VideoCodecType;
      bit_rate?: number;
      // 利用するには sora.conf で signaling_vp9_params = true を設定する必要があります
      vp9_params?: VP9Params;
      // 利用するには sora.conf で signaling_av1_params = true を設定する必要があります
      av1_params?: AV1Params;
      // 利用するには sora.conf で signaling_h264_params = true を設定する必要があります
      h264_params?: H264Params;
      // 利用するには sora.conf で signaling_h265_params = true を設定する必要があります
      h265_params?: H265Params;
    };

type VP9Params = {
  // 0..3
  profile_id?: number;
};

type AV1Params = {
  // 0..2
  profile?: number;
};

type H264Params = {
  profile_level_id?: string;
  // sora.conf で h264_b_frame = true を設定する必要があります
  b_frame?: boolean;
};

type H265Params = {
  level_id?: number;
  // sora.conf で h265_b_frame = true を設定する必要があります
  b_frame?: boolean;
};

// 音声コーデックの種類
type AudioCodecType = "OPUS";

// 映像コーデックの種類
type VideoCodecType = "VP9" | "VP8" | "AV1" | "H264" | "H265";

// DataChannel の方向
type Direction = "sendrecv" | "sendonly" | "recvonly";

type DataChannelMessagingHeaderFieldType = "sender_connection_id";

type DataChannelMessagingHeaderField = {
  type: DataChannelMessagingHeaderFieldType;
  // * length は "type": "offer" 時の data_channels にのみ含まれる
  // * length は"type": "connect" 時には指定できない
  // * length は認証成功時の払い出し時には指定できない
  length?: number;
};

// DataChannels
type DataChannel = {
  label: string;
  direction: Direction;
  ordered?: boolean;
  max_packet_life_time?: number;
  max_retransmits?: number;
  protocol?: string;
  compress?: boolean;
  header?: DataChannelMessagingHeaderField[];
};

type TurnTransportType = "udp" | "tcp";

type ForwardingFilterRuleField = "connection_id" | "client_id" | "kind";

type ForwardingFilterRuleOperator = "is_in" | "is_not_in";

type ForwardingFilterRuleKindValue = "audio" | "video";

type ForwardingFilterRule = {
  field: ForwardingFilterRuleField;
  operator: ForwardingFilterRuleOperator;
  values: [string];
};

type ForwardingFilterAction = "block" | "allow";

type ForwardingFilter = {
  version?: string;
  metadata?: JSONValue;
  name?: string;
  priority?: number;
  action?: ForwardingFilterAction;
  rules: [[ForwardingFilterRule]];
};

type SoraClientType =
  | "Sora JavaScript SDK"
  | "Sora iOS SDK"
  | "Sora Android SDK"
  | "Sora Unity SDK"
  | "Sora C++ SDK"
  | "Sora Python SDK"
  | "Sora C SDK"
  | "OBS-Studio-WHIP"
  | "OBS-Studio-WHEP";

// SoraClient
type SoraClient = {
  environment?: string;
  raw?: string;
  type?: SoraClientType;
  version?: string;
  commit_short?: string;
  libwebrtc?: string;
};

// RTCRtpCodecParameters
// https://www.w3.org/TR/webrtc/#dom-rtcrtpcodecparameters
type SimulcastCodec = {
  // payloadType や channels は省略
  mimeType: string;
  clockRate: number;
  sdpFmtpLine?: string;
};

// RTCRtpEncodingParameters
// https://w3c.github.io/webrtc-pc/#dom-rtcrtpencodingparameters
type SimulcastEncoding = {
  // https://www.w3.org/TR/webrtc/#dom-rtcrtpcodingparameters-rid
  rid: SimulcastRid;
  // https://www.w3.org/TR/webrtc/#dom-rtcrtpencodingparameters-active
  active?: boolean;
  // https://www.w3.org/TR/webrtc/#dom-rtcrtpencodingparameters-maxframerate
  maxFramerate?: number;
  // https://www.w3.org/TR/webrtc/#dom-rtcrtpencodingparameters-maxbitrate
  maxBitrate?: number;
  // https://www.w3.org/TR/webrtc/#dom-rtcrtpencodingparameters-scaleresolutiondownby
  scaleResolutionDownBy?: number;
  // https://www.w3.org/TR/webrtc/#dom-rtcrtpcodec
  codec?: SimulcastCodec;
  // https://w3c.github.io/webrtc-extensions/#dom-rtcrtpencodingparameters-scaleresolutiondownto
  // @ts-ignore: RTCResolutionRestriction は typed で未定義のため型チェックを無視(型定義が追加され次第 ts-ignore を削除)
  scaleResolutionDownTo?: RTCResolutionRestriction;
  // https://w3c.github.io/webrtc-extensions/#dom-rtcrtpencodingparameters-adaptiveptime
  adaptivePtime?: boolean;
  // https://www.w3.org/TR/webrtc-svc/#dom-rtcrtpencodingparameters-scalabilitymode
  scalabilityMode?: string;
};

完全な型定義

認証ウェブフック

// 認証ウェブフックリクエスト
type AuthWebhookRequest = {
  timestamp: Timestamp;
  id: string;

  version: string;
  label: string;
  node_name: string;

  role: Role;
  channel_id: string;
  client_id?: string;
  bundle_id?: string;
  connection_id: string;

  multistream: boolean;
  simulcast: boolean;
  simulcast_rid?: SimulcastRid;
  simulcast_multicodec?: boolean;
  spotlight: boolean;
  spotlight_number?: number;
  spotlight_focus_rid?: "none" | SimulcastRid;
  spotlight_unfocus_rid?: "none" | SimulcastRid;

  audio: boolean;
  audio_codec_type?: string;
  audio_bit_rate?: number;

  video: Video;
  video_codec_type?: VideoCodecType;
  video_bit_rate?: number;
  video_vp9_params?: VP9Params;
  video_av1_params?: AV1Params;
  video_h264_params?: H264Params;
  video_h265_params?: H265Params;

  data_channel_signaling: boolean;
  ignore_disconnect_websocket: boolean;
  data_channels?: [DataChannel];

  forwarding_filters?: ForwardingFilter[];
  // forwarding_filter は 2025 年 12 月リリース予定の Sora にて廃止します
  // 今後は forwarding_filters をご利用ください
  forwarding_filter?: ForwardingFilter;

  authn_metadata?: JSONValue;
  metadata?: JSONValue;

  whip?: boolean;
  whep?: boolean;

  sora_client?: SoraClient;

  channel_connections: number;
  channel_sendrecv_connections: number;
  channel_sendonly_connections: number;
  channel_recvonly_connections: number;

  e2ee: false;
};

// type: offer の encodings に含まれる codec 払い出される値とは異なるので注意
type SimulcastCodecs = [
  {
    rid: SimulcastRid;
    codec_type: VideoCodecType;
    codec_params?: VP9Params | AV1Params | H264Params | H265Params;
  },
];

// 認証ウェブフック成功レスポンス
// 200 OK で返してください
type AuthWebhookAcceptResponse = {
  allowed: true;

  audio?: boolean;
  audio_codec_type?: string;
  audio_bit_rate?: number;
  audio_opus_params?: OpusParams;

  video?: boolean;
  video_codec_type?: string;
  video_bit_rate?: number;

  video_vp9_params?: VP9Params;
  video_av1_params?: AV1Params;
  video_h264_params?: H264Params;
  video_h265_params?: H265Params;

  client_id?: string;
  bundle_id?: string;

  simulcast?: boolean;
  simulcast_rid?: SimulcastRid;
  simulcast_encodings?: [SimulcastEncoding];
  simulcast_multicodec?: boolean;
  simulcast_codecs?: SimulcastCodecs;

  spotlight?: boolean;
  // 非推奨です
  // session.created の戻り値をご利用ください
  spotlight_number?: number;
  spotlight_focus_rid?: "none" | SimulcastRid;
  spotlight_unfocus_rid?: "none" | SimulcastRid;
  spotlight_encodings?: [SimulcastEncoding];

  data_channel_signaling?: boolean;
  ignore_disconnect_websocket?: boolean;
  data_channels?: [DataChannel];

  forwarding_filters?: ForwardingFilter[];
  // forwarding_filter は 2025 年 12 月リリース予定の Sora にて廃止します
  // 今後は forwarding_filters をご利用ください
  forwarding_filter?: ForwardingFilter;

  connection_lifetime?: number;

  cluster_affinity?: string;

  metadata?: JSONValue;
  event_metadata?: JSONValue;

  signaling_notify?: boolean;
  signaling_notify_metadata?: JSONValue;
  signaling_notify_metadata_ext?: JSONValue;
  signaling_notify_ice_connection_state?: boolean;

  recording_block?: boolean;

  ipv4_address?: string;
  ipv6_address?: string;

  turn_fqdn?: string;
  turn_tls_fqdn?: string;

  playout_delay_min_delay?: number;
  playout_delay_max_delay?: number;

  // user_agent_stats は 2025 年 6 月リリース予定の Sora にて廃止予定です
  user_agent_stats?: boolean;
  // user_agent_stats の代わりに rtc_stats をご利用ください
  rtc_stats?: boolean;

  stats_exporter?: boolean;

  audio_streaming_language_code?: string;

  turn_tcp_only?: boolean;
  turn_tls_only?: boolean;

  rtp_packet_loss_simulator_incoming?: number;
  rtp_packet_loss_simulator_outgoing?: number;
};

// 認証ウェブフック失敗レスポンス
// 200 OK で返してください
type AuthWebhookRejectResponse = {
  allowed: false;
  reason: string;
};

セッションウェブフック

// セッションウェブフック生成リクエスト
type SessionWebhookCreatedRequest = {
  type: "session.created";

  timestamp: Timestamp;
  id: string;

  version: string;
  label: string;
  node_name: string;

  // cluster = true の時のみ含まれる
  external_signaling_url?: string;

  channel_id: string;
  session_id: string;

  multistream: boolean;
  spotlight: boolean;

  created_time: UnixTime;
  created_timestamp: Timestamp;
};

// 200 OK で返してください
type SessionWebhookCreatedResponse = {
  // 最大 2,592,000 秒 (30 日) まで指定できます
  session_lifetime?: number;
  session_metadata?: JSONValue;

  spotlight_number?: number;

  // * forwarding_filter と forwarding_filters は同時に指定できる
  // * forwarding_filters が優先される
  forwarding_filters?: ForwardingFilter[];
  // forwarding_filter は 2025 年 12 月リリース予定の Sora にて廃止します
  // 今後は forwarding_filters をご利用ください
  forwarding_filter?: ForwardingFilter;

  audio_streaming?: boolean;
  audio_streaming_auto?: boolean;

  recording?: boolean;
  recording_metadata?: JSONValue;
  recording_expire_time?: number;
  recording_split_only?: boolean;
  recording_split_duration?: number;
  recording_format?: RecordingFormat;
};

// セッションウェブフック更新リクエスト
type SessionWebhookUpdatedRequest = {
  type: "session.updated";

  timestamp: Timestamp;
  id: string;

  version: string;
  label: string;
  node_name: string;

  // cluster = true の時のみ含まれる
  external_signaling_url?: string;

  channel_id: string;
  session_id: string;

  multistream: boolean;
  spotlight: boolean;
  spotlight_number: number;

  created_time: number;
  created_timestamp: string;

  max_connections: number;
  total_connections: number;

  session_metadata?: JSONValue;

  // 録画機能 (セッション単位) が有効な時のみ
  recording?: SessionRecording;

  // クラスター有効の場合は含まれない
  connections?: [SessionConnection];
};

type SessionWebhookDestroyedReason =
  | "normal"
  | "validation_error"
  | "webhook_error"
  | "terminated_api"
  | "lifetime_expired"
  | "abort";

// セッションウェブフック破棄リクエスト
type SessionWebhookDestroyedRequest = {
  type: "session.destroyed";

  timestamp: Timestamp;
  id: string;

  version: string;
  label: string;
  node_name: string;

  // cluster = true の時のみ含まれる
  external_signaling_url?: string;

  channel_id: string;
  session_id: string;

  multistream: boolean;
  spotlight: boolean;
  spotlight_number?: number;

  created_time: number;
  created_timestamp: string;

  destroyed_time: number;
  destroyed_timestamp: string;

  reason: SessionWebhookDestroyedReason;

  max_connections: number;
  total_connections: number;

  session_metadata?: JSONValue;

  // クラスター有効の場合は含まれない
  connections?: [SessionConnection];
};

type SessionRecording = {
  recording_id: string;

  // 未指定の場合は含まれない
  recording_metadata?: JSONValue;

  // 未指定の場合は含まれない
  expire_time?: number;
  // expire_time が未指定の場合は含まれない
  expired_at?: number;

  split_only: boolean;
  split_duration?: number;

  format: RecordingFormat;

  start_timestamp: string;
};

type SessionConnection = {
  role: Role;
  client_id: string;
  bundle_id: string;
  connection_id: string;

  simulcast: boolean;

  audio: boolean;
  audio_codec_type?: string;
  audio_bit_rate?: number;

  video: boolean;
  video_codec_type?: string;
  video_bit_rate?: number;
  video_vp9_params?: VP9Params;
  video_av1_params?: AV1Params;
  video_h264_params?: H264Params;
  video_h265_params?: H265Params;

  // 認証は成功したが WebRTC が確立できなかった場合、 null が入ってくる
  connection_created_timestamp: Timestamp | null;
  // 認証は成功したが WebRTC が確立できなかった場合、 null が入ってくる
  connection_destroyed_timestamp: Timestamp | null;

  event_metadata?: JSONValue;
};

// このウェブフックは 2025 年 6 月リリース予定の Sora にて廃止します
// セッションウェブフック全破棄リクエスト
type SessionWebhookVanishedRequest = {
  type: "session.vanished";

  timestamp: Timestamp;
  id: string;

  version: string;
  label: string;
  node_name: string;

  // cluster = true の時のみ含まれる
  external_signaling_url?: string;
};

セッションウェブフック (録画)

type RecordingFormat = "webm" | "mp4";

type SessionWebhookRecordingStartedRequest = {
  type: "recording.started";

  timestamp: Timestamp;
  id: string;

  version: string;
  label: string;
  node_name: string;

  channel_id: string;
  session_id: string;
  session_metadata?: JSONValue;

  data: SessionWebhookRecordingStartedData;
};

type SessionWebhookRecordingStartedData = {
  channel_id: string;
  session_id: string;
  recording_id: string;
  recording_metadata?: JSONValue;
  split_only: boolean;
  split_duration?: number;
  created_at: number;
  expire_time?: number;
  expired_at?: number;
  start_timestamp: Timestamp;
  format: RecordingFormat;
};

type SessionWebhookRecordingReportRequest = {
  type: "recording.report";

  timestamp: Timestamp;
  id: string;

  version: string;
  label: string;
  node_name: string;

  channel_id: string;
  session_id: string;
  session_metadata?: JSONValue;

  data: SessionWebhookRecordingReportData;
};

type SessionWebhookRecordingReportData = {
  channel_id: string;
  session_id: string;
  recording_id: string;
  recording_metadata?: JSONValue;
  split_only: boolean;
  split_duration?: number;
  created_at: number;
  expire_time?: number;
  expired_at?: number;
  file_path: string;
  filename: string;
  file_written: boolean;
  start_timestamp: Timestamp;
  stop_timestamp: Timestamp;
  format: RecordingFormat;
  archives: [SessionWebhookRecordingReportArchive];
  failed_archives: [SessionWebhookRecordingReportFailedArchive];
};

type SessionWebhookRecordingReportArchive = {
  label: string;
  node_name: string;
  client_id: string;
  bundle_id: string;
  connection_id: string;
  file_path?: string;
  filename?: string;
  metadata_file_path?: string;
  metadata_filename?: string;
  start_time_offset: number;
  start_timestamp: Timestamp;
  stop_time_offset: number;
  stop_timestamp: Timestamp;
  size?: number;
  split_last_index?: string;
};

type SessionWebhookRecordingReportFailedArchive = {
  label: string;
  node_name: string;
  client_id: string;
  bundle_id: string;
  connection_id: string;
};

セッションウェブフック (音声ストリーミング)

// セッションウェブフック音声ストリーミング開始リクエスト
type SessionWebhookAudioStreamingStartedRequest = {
  type: "audio-streaming.started";

  timestamp: Timestamp;
  id: string;

  version: string;
  label: string;
  node_name: string;

  // cluster = true の時のみ含まれる
  external_signaling_url?: string;

  channel_id: string;
  session_id: string;

  multistream: boolean;
  spotlight: boolean;

  created_time: UnixTime;
  created_timestamp: Timestamp;

  session_metadata?: JSONValue;

  data: AudioStreamingStartedData;
};

type AudioStreamingStartedData = {
  audio_streaming_auto: boolean;
  audio_streaming_started_timestamp: string;
};

// セッションウェブフック音声ストリーミング停止リクエスト
type SessionWebhookAudioStreamingStoppedRequest = {
  type: "audio-streaming.stopped";

  timestamp: string;
  id: string;

  version: string;
  label: string;
  node_name: string;

  // cluster = true の時のみ含まれる
  external_signaling_url?: string;

  channel_id: string;
  session_id: string;

  multistream: boolean;
  spotlight: boolean;

  created_time: UnixTime;
  created_timestamp: Timestamp;

  session_metadata?: JSONValue;

  data: AudioStreamingStoppedData;
};

type AudioStreamingStoppedData = {
  audio_streaming_auto: boolean;
  audio_streaming_started_timestamp: Timestamp;
  audio_streaming_stopped_timestamp: Timestamp;
};

イベントウェブフック

// イベントコネクション生成ウェブフックリクエスト
type EventWebhookConnectionCreatedRequest = {
  type: "connection.created";

  timestamp: Timestamp;
  id: string;

  log_written: boolean;

  version: string;
  label: string;
  node_name: string;

  role: Role;
  channel_id: string;
  session_id: string;
  client_id: string;
  bundle_id: string;
  connection_id: string;

  multistream: boolean;
  simulcast: boolean;
  simulcast_multicodec?: boolean;
  spotlight: boolean;

  event_metadata?: JSONValue;

  data: EventWebhookConnectionCreatedData;
};

// イベントコネクション生成ウェブフックデータ
type EventWebhookConnectionCreatedData = {
  minutes: number;

  audio: boolean;
  audio_codec_type?: AudioCodecType;
  audio_bit_rate?: number;

  video: boolean;
  video_codec_type?: VideoCodecType;
  video_bit_rate?: number;
  video_vp9_params?: VP9Params;
  video_av1_params?: AV1Params;
  video_h264_params?: H264Params;
  video_h265_params?: H265Params;

  recording_block: boolean;

  channel_connections: number;
  channel_sendrecv_connections: number;
  channel_sendonly_connections: number;
  channel_recvonly_connections: number;

  turn_transport_type: TurnTransportType;

  created_time: UnixTime;
  created_timestamp: Timestamp;

  ice_connection_state: IceConnectionState;

  total_received_bytes: number;
  total_sent_bytes: number;
};

// イベントコネクション更新ウェブフックリクエスト
type EventWebhookConnectionUpdatedRequest = {
  type: "connection.updated";

  timestamp: Timestamp;
  id: string;

  log_written: boolean;

  version: string;
  label: string;
  node_name: string;

  role: Role;
  channel_id: string;
  session_id: string;
  client_id: string;
  bundle_id: string;
  connection_id: string;

  multistream: boolean;
  simulcast: boolean;
  simulcast_multicodec?: boolean;
  spotlight: boolean;

  event_metadata?: JSONValue;

  data: EventWebhookConnectionUpdatedData;
};

// イベントコネクション更新ウェブフックデータ
type EventWebhookConnectionUpdatedData = {
  minutes: number;

  audio: boolean;
  audio_codec_type?: AudioCodecType;
  audio_bit_rate?: number;

  video: boolean;
  video_codec_type?: VideoCodecType;
  video_bit_rate?: number;
  video_vp9_params?: VP9Params;
  video_av1_params?: AV1Params;
  video_h264_params?: H264Params;
  video_h265_params?: H265Params;

  recording_block: boolean;

  channel_connections: number;
  channel_sendrecv_connections: number;
  channel_sendonly_connections: number;
  channel_recvonly_connections: number;

  turn_transport_type: TurnTransportType;

  created_time: UnixTime;
  created_timestamp: Timestamp;

  ice_connection_state: IceConnectionState;

  total_received_bytes: number;
  total_sent_bytes: number;
};

// イベントコネクション破棄ウェブフックリクエスト
type EventWebhookConnectionDestroyedRequest = {
  type: "connection.destroyed";

  timestamp: Timestamp;
  id: string;

  log_written: boolean;

  version: string;
  label: string;
  node_name: string;

  role: Role;
  channel_id: string;
  session_id: string;
  client_id: string;
  bundle_id: string;
  connection_id: string;

  multistream: boolean;
  simulcast: boolean;
  simulcast_multicodec?: boolean;
  spotlight: boolean;

  event_metadata?: JSONValue;

  data: EventWebhookConnectionDestroyedData;
};

type ConnectionDestroyedReason =
  | "normal"
  | "disconnected_api"
  | "session_destroyed"
  | "lifetime_expired";

// イベントコネクション破棄ウェブフックデータ
type EventWebhookConnectionDestroyedData = {
  minutes: number;

  audio: boolean;
  audio_codec_type?: AudioCodecType;
  audio_bit_rate?: number;

  video: boolean;
  video_codec_type?: VideoCodecType;
  video_bit_rate?: number;
  video_vp9_params?: VP9Params;
  video_av1_params?: AV1Params;
  video_h264_params?: H264Params;
  video_h265_params?: H265Params;

  recording_block: boolean;

  channel_connections: number;
  channel_sendrecv_connections: number;
  channel_sendonly_connections: number;
  channel_recvonly_connections: number;

  turn_transport_type: TurnTransportType;

  created_time: UnixTime;
  created_timestamp: Timestamp;

  destroyed_time: UnixTime;
  destroyed_timestamp: Timestamp;

  ice_connection_state: IceConnectionState;

  total_received_bytes: number;
  total_sent_bytes: number;

  reason?: ConnectionDestroyedReason;
  disconnect_api_reason?: string;
  type_disconnect_reason?: string;
};

// 2024.2.0 から認証成功後のみ送信されるようになりました
// そのため role / channel_id / client_id / bundle_id / connection_id は必須となりました
type EventWebhookConnectionFailedRequest = {
  type: "connection.failed";

  timestamp: Timestamp;
  id: string;

  log_written: boolean;

  version: string;
  label: string;
  node_name: string;

  role: Role;
  channel_id: string;
  client_id: string;
  bundle_id: string;
  connection_id: string;

  multistream: boolean;
  simulcast: boolean;
  spotlight: boolean;

  data: EventWebhookConnectionFailedData;
};

type EventWebhookConnectionFailedData = {
  message: string;

  channel_connections: number;
  channel_sendrecv_connections: number;
  channel_sendonly_connections: number;
  channel_recvonly_connections: number;

  total_received_bytes: number;
  total_sent_bytes: number;
};

type IceConnectionState = {
  total_checking_duration_ms: number;
  total_disconnected_duration_ms: number;
};

イベントウェブフック (録画)

type EventWebhookArchiveStartedRequest = {
  type: "archive.started";

  timestamp: Timestamp;
  id: string;

  log_written: boolean;

  version: string;
  label: string;
  node_name: string;

  channel_id: string;
  session_id: string;
  client_id: string;
  bundle_id: string;
  connection_id: string;

  event_metadata?: JSONValue;

  data: EventWebhookArchiveStartedData;
};

type EventWebhookArchiveStartedData = {
  recording_id: string;

  channel_id: string;
  session_id: string;
  client_id: string;
  bundle_id: string;
  connection_id: string;

  created_at: number;

  audio: boolean;
  audio_codec_type?: string;
  audio_bit_rate?: number;

  video: boolean;
  video_codec_type?: string;
  video_bit_rate?: number;
  video_vp9_params?: VP9Params;
  video_av1_params?: AV1Params;
  video_h264_params?: H264Params;

  start_time: UnixTime;
  start_time_offset: number;
  start_timestamp: Timestamp;

  format: RecordingFormat;
};

type EventWebhookArchiveAvailableRequest = {
  type: "archive.available";

  timestamp: Timestamp;
  id: string;

  log_written: boolean;

  version: string;
  label: string;
  node_name: string;

  channel_id: string;
  session_id: string;
  client_id: string;
  bundle_id: string;
  connection_id: string;

  event_metadata?: JSONValue;

  data: EventWebhookArchiveAvailableData;
};

type EventWebhookArchiveAvailableData = {
  recording_id: string;

  channel_id: string;
  session_id: string;
  client_id: string;
  bundle_id: string;
  connection_id: string;

  file_path: string;
  filename: string;

  metadata_file_path: string;
  metadata_filename: string;

  size: number;

  created_at: number;

  audio: boolean;
  audio_codec_type?: string;
  audio_bit_rate?: number;

  video: boolean;
  video_codec_type?: string;
  video_bit_rate?: number;
  video_height?: number;
  video_width?: number;
  video_vp9_params?: VP9Params;
  video_av1_params?: AV1Params;
  video_h264_params?: H264Params;

  start_time: UnixTime;
  start_time_offset: number;
  start_timestamp: Timestamp;

  stop_time: UnixTime;
  stop_time_offset: number;
  stop_timestamp: Timestamp;

  split_only: boolean;
  format: RecordingFormat;

  expire_time?: number;
  expired_at?: number;
  split_duration?: number;

  stats: JSONValue;
};

type EventWebhookSplitArchiveAvailableRequest = {
  type: "split-archive.available";

  id: string;
  timestamp: Timestamp;

  log_written: boolean;

  version: string;
  label: string;
  node_name: string;

  channel_id: string;
  session_id: string;
  client_id: string;
  bundle_id: string;
  connection_id: string;

  event_metadata?: JSONValue;

  data: EventWebhookSplitArchiveAvailableData;
};

type EventWebhookSplitArchiveAvailableData = {
  recording_id: string;

  channel_id: string;
  session_id: string;
  client_id: string;
  bundle_id: string;
  connection_id: string;

  split_index: string;

  file_path: string;
  filename: string;

  metadata_file_path: string;
  metadata_filename: string;

  size: number;

  created_at: number;

  audio: boolean;
  audio_codec_type?: string;
  audio_bit_rate?: number;

  video: boolean;
  video_codec_type?: string;
  video_bit_rate?: number;
  video_height?: number;
  video_width?: number;
  video_vp9_params?: VP9Params;
  video_av1_params?: AV1Params;
  video_h264_params?: H264Params;

  start_time: number;
  start_time_offset: number;
  start_timestamp: Timestamp;

  stop_time: UnixTime;
  stop_time_offset: number;
  stop_timestamp: Timestamp;

  split_only: boolean;
  format: RecordingFormat;

  expire_time?: number;
  expired_at?: number;
  split_duration?: number;

  stats: JSONValue;
};

type EventWebhookSplitArchiveEndRequest = {
  type: "split-archive.end";

  id: string;
  timestamp: Timestamp;

  log_written: boolean;

  version: string;
  label: string;
  node_name: string;

  channel_id: string;
  session_id: string;
  client_id: string;
  bundle_id: string;
  connection_id: string;

  event_metadata?: JSONValue;

  data: EventWebhookSplitArchiveEndData;
};

type EventWebhookSplitArchiveEndData = {
  split_last_index: string;

  recording_id: string;

  channel_id: string;
  session_id: string;
  client_id: string;
  bundle_id: string;
  connection_id: string;

  file_path: string;
  filename: string;

  audio: boolean;
  audio_codec_type?: string;
  audio_bit_rate?: number;

  video: Video;
  video_codec_type?: string;
  video_bit_rate?: number;
  video_vp9_params?: VP9Params;
  video_av1_params?: AV1Params;
  video_h264_params?: H264Params;

  start_time: UnixTime;
  start_time_offset: number;
  start_timestamp: Timestamp;

  stop_time: UnixTime;
  stop_time_offset: number;
  stop_timestamp: Timestamp;

  split_only: boolean;
  format: RecordingFormat;

  expire_time?: number;
  expired_at?: number;
  split_duration?: number;

  stats: JSONValue;
};

type EventWebhookArchiveFailedRequest = {
  type: "archive.failed";

  timestamp: Timestamp;
  id: string;

  log_written: boolean;

  version: string;
  label: string;
  node_name: string;

  channel_id: string;
  session_id: string;
  client_id: string;
  bundle_id: string;
  connection_id: string;

  event_metadata?: JSONValue;

  data: EventWebhookSplitArchiveFailedData;
};

type EventWebhookSplitArchiveFailedData = {
  recording_id: string;

  session_id: string;

  file_path?: string;
  filename?: string;

  split_index?: string;
  split_file_path?: string;
  split_filename?: string;

  audio: boolean;
  audio_codec_type?: string;
  audio_bit_rate?: number;

  video: boolean;
  video_codec_type?: string;
  video_bit_rate?: number;
  video_height?: number;
  video_width?: number;
  video_vp9_params?: VP9Params;
  video_av1_params?: AV1Params;
  video_h264_params?: H264Params;

  start_time: UnixTime;
  start_timestamp: Timestamp;

  stop_time: UnixTime;
  stop_timestamp: Timestamp;

  split: boolean;
  split_only: boolean;
  format: RecordingFormat;

  expire_time?: number;
  expired_at?: number;
  split_duration?: number;

  stats: JSONValue;
};

イベントウェブフック (レガシー録画)

type EventWebhookLegacyRecordingStartedRequest = {
  type: "recording.started";

  timestamp: Timestamp;
  id: string;

  log_written: boolean;

  version: string;
  label: string;
  node_name: string;

  channel_id: string;

  data: EventWebhookLegacyRecordingStartedData;
};

type EventWebhookLegacyRecordingStartedData = {
  channel_id: string;
  recording_id: string;
  metadata?: JSONValue;
  split_only: boolean;
  split_duration?: number;
  created_at: number;
  expire_time: number;
  expired_at: number;
  start_timestamp: Timestamp;
};

type EventWebhookLegacyRecordingReportRequest = {
  type: "recording.report";

  timestamp: Timestamp;
  id: string;

  log_written: boolean;

  version: string;
  label: string;
  node_name: string;

  channel_id: string;

  data: EventWebhookLegacyRecordingReportData;
};

type EventWebhookLegacyRecordingReportData = {
  channel_id: string;
  recording_id: string;
  metadata?: JSONValue;
  split_only: boolean;
  split_duration?: number;
  created_at: number;
  expire_time: number;
  expired_at: number;
  file_path: string;
  filename: string;
  file_written: boolean;
  start_timestamp: Timestamp;
  stop_timestamp: Timestamp;
  archives: [EventWebhookLegacyRecordingReportArchive];
  failed_archives: [EventWebhookLegacyRecordingReportFailedArchive];
};

type EventWebhookLegacyRecordingReportArchive = {
  label: string;
  node_name: string;
  client_id: string;
  bundle_id: string;
  connection_id: string;
  file_path?: string;
  filename?: string;
  metadata_file_path?: string;
  metadata_filename?: string;
  start_time_offset: number;
  start_timestamp: Timestamp;
  stop_time_offset: number;
  stop_timestamp: Timestamp;
  size?: number;
  split_last_index?: string;
};

type EventWebhookLegacyRecordingReportFailedArchive = {
  label: string;
  node_name: string;
  client_id: string;
  bundle_id: string;
  connection_id: string;
};

イベントウェブフック (スポットライト)

type EventWebhookSpotlightFocusedRequest = {
  type: "spotlight.focused";

  timestamp: Timestamp;
  id: string;

  log_written: boolean;

  version: string;
  label: string;
  node_name: string;

  channel_id: string;
  client_id: string;
  bundle_id: string;
  connection_id: string;

  spotlight_number: number;

  fixed: boolean;

  audio: boolean;
  video: boolean;
};

type EventWebhookSpotlightUnfocusedRequest = {
  type: "spotlight.unfocused";

  timestamp: Timestamp;
  id: string;

  log_written: boolean;

  version: string;
  label: string;
  node_name: string;

  channel_id: string;
  client_id: string;
  bundle_id: string;
  connection_id: string;

  spotlight_number: number;

  audio: boolean;
  video: boolean;
};

イベントウェブフック (音声ストリーミング失敗)

type EventWebhookAudioStreamingFailedRequest = {
  type: "audio-streaming.failed";

  timestamp: Timestamp;
  id: string;

  log_written: boolean;

  version: string;
  label: string;
  node_name: string;

  role: Role;

  channel_id: string;
  session_id: string;
  client_id: string;
  bundle_id: string;
  connection_id: string;

  multistream: boolean;
  simulcast: boolean;
  spotlight: boolean;

  data: {
    failed_reason: string;
  };
};

統計ウェブフック

// コネクション RTC 統計情報ウェブフックリクエスト
type StatsWebhookConnectionRtcRequest = {
  type: "connection.rtc";

  timestamp: string;
  id: string;

  log_written: boolean;

  version: string;
  label: string;
  node_name: string;

  role: Role;
  channel_id: string;
  session_id: string;
  client_id: string;
  bundle_id: string;
  connection_id: string;

  multistream: boolean;
  simulcast: boolean;
  spotlight: boolean;

  // https://www.w3.org/TR/webrtc-stats/
  stats?: RTCStatsReport[];
};

API

概要

API は Sora に対して HTTP 経由で実行できます。

用語

• object

  • JSON Object です

  • HTTPie では key:='{"spam": "egg"}' のように指定してください

API の種類

API

正式リリースされている API

実験的 API

仕様が確定していない API

詳細は 実験的 API をご確認ください。

非推奨 API

期限が来たら廃止される API

詳細は 非推奨 API をご確認ください。

廃止 API

廃止された API

詳細は 廃止 API をご確認ください。

テスト API

テストで利用する API

詳細は テスト API をご確認ください。

x-sora-target ヘッダー

API は DynamoDB や Route53 などの AWS API が独特な仕様なので紹介 を参考にしており、 x-sora-target というヘッダーを使って実行します。

• すべての API は POST を使用します

• すべての API の PATH は / です

• リクエストの Body には JSON を使用します

• レスポンスの Body には JSON を使用します

設定

api_port

API のポート番号を変更したい場合は sora.conf の api_port にて、 API のポート番号を設定してください。

デフォルトでは 3000 番を利用します。

api_port = 3000

api_loopback_address_only

API へのアクセスをループバックアドレスからのみに制限します。 本番環境では可能な限り有効にしてください。

api_loopback_address_only = true

api_cors_origin

警告

本番環境ではこの設定は有効にしないでください。

API をクロスドメインで使用したい場合に設定します。

api_cors_origin = http://127.0.0.1:5000

こうすることで、ブラウザで http://127.0.0.1:5000 から API を叩くことができるようになります。

HTTPie

ここでの例では HTTPie という Python のライブラリを使用しています。

🥧 HTTPie for Terminal — modern, user-friendly command-line HTTP client for the API era. JSON support, colors, sessions, downloads, plugins & more.

インストール

• Ubuntu は apt install httpie で入ります

• CentOS は yum install httpie で入ります

• macOS は brew install httpie または port install httpie で入ります

詳細は https://httpie.io/docs/cli/installation をご確認下さい。

シグナリング API

DisconnectChannel

x-sora-target:

Sora_20151104.DisconnectChannel

指定したチャネルの接続をすべて切断します。

キー	型
channel_id	string
reason (オプション)	object

reason に値を指定した場合、イベントウェブフック connection.destroyed の disconnect_api_reason に指定した値が入ってきます。

$ http POST 127.0.0.1:3000 \
    x-sora-target:Sora_20151104.DisconnectChannel \
    channel_id=sora \
    -vvv
POST / HTTP/1.1
Accept: application/json, */*;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 22
Content-Type: application/json
Host: 127.0.0.1:3000
User-Agent: HTTPie/2.4.0
x-sora-target: Sora_20151104.DisconnectChannel

{
    "channel_id": "sora"
}


HTTP/1.1 200 OK
access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
access-control-allow-methods: POST, OPTIONS
access-control-allow-origin: http://127.0.0.1:5000
access-control-max-age: 1000
content-length: 21
content-type: application/json
date: Wed, 07 Jul 2021 05:44:01 GMT
server: Cowboy

{
    "channel_id": "sora"
}

DisconnectClient

x-sora-target:

Sora_20151104.DisconnectClient

指定したクライアント ID の接続をすべて切断します。

キー	型
channel_id	string
client_id	string
reason (オプション)	object

reason に値を指定した場合、イベントウェブフック connection.destroyed の disconnect_api_reason に指定した値が入ってきます。

$ http POST 127.0.0.1:3000/ \
    x-sora-target:Sora_20151104.DisconnectClient \
    channel_id=sora \
    client_id=E2APPNQ9P97Q32V2ABW546SWW8 \
    -vvv
POST / HTTP/1.1
Accept: application/json, */*;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 65
Content-Type: application/json
Host: 127.0.0.1:3000
User-Agent: HTTPie/2.4.0
x-sora-target: Sora_20151104.DisconnectClient

{
    "channel_id": "sora",
    "client_id": "E2APPNQ9P97Q32V2ABW546SWW8"
}


HTTP/1.1 200 OK
access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
access-control-allow-methods: POST, OPTIONS
access-control-allow-origin: http://127.0.0.1:5000
access-control-max-age: 1000
content-length: 62
content-type: application/json
date: Wed, 07 Jul 2021 05:45:09 GMT
server: Cowboy

{
    "channel_id": "sora",
    "client_id": "E2APPNQ9P97Q32V2ABW546SWW8"
}

DisconnectConnection

x-sora-target:

Sora_20151104.DisconnectConnection

指定したコネクション ID の接続を切断します。

キー	型
channel_id	string
connection_id	string
reason (オプション)	object

reason に値を指定した場合、イベントウェブフック connection.destroyed の disconnect_api_reason に指定した値が入ってきます。

$ http POST 127.0.0.1:3000/ \
    x-sora-target:Sora_20151104.DisconnectConnection \
    channel_id=sora \
    connection_id=T34CDBMRJS1B5BVPF17RTBQA3C \
    -vvv
POST / HTTP/1.1
Accept: application/json, */*;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 69
Content-Type: application/json
Host: 127.0.0.1:3000
User-Agent: HTTPie/2.4.0
x-sora-target: Sora_20151104.DisconnectConnection

{
    "channel_id": "sora",
    "connection_id": "T34CDBMRJS1B5BVPF17RTBQA3C"
}


HTTP/1.1 200 OK
access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
access-control-allow-methods: POST, OPTIONS
access-control-allow-origin: http://127.0.0.1:5000
access-control-max-age: 1000
content-length: 66
content-type: application/json
date: Wed, 07 Jul 2021 05:59:41 GMT
server: Cowboy

{
    "channel_id": "sora",
    "connection_id": "T34CDBMRJS1B5BVPF17RTBQA3C"
}

DisconnectChannelByRole

x-sora-target:

Sora_20201120.DisconnectChannelByRole

指定したチャネルの指定したロールの接続を切断します。

キー	型
channel_id	string
role	string (sendrecv | sendonly | recvonly)
reason (オプション)	object

$ http POST 127.0.0.1:3000/ \
    x-sora-target:Sora_20201120.DisconnectChannelByRole \
    channel_id=sora \
    role=sendrecv \
    -vvv
 POST / HTTP/1.1
 Accept: application/json, */*;q=0.5
 Accept-Encoding: gzip, deflate
 Connection: keep-alive
 Content-Length: 42
 Content-Type: application/json
 Host: 127.0.0.1:3000
 User-Agent: HTTPie/2.2.0
 x-sora-target: Sora_20201120.DisconnectChannelByRole

 {
     "channel_id": "sora",
     "role": "sendrecv"
 }

 HTTP/1.1 200 OK
 access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
 access-control-allow-methods: POST, OPTIONS
 access-control-allow-origin: http://127.0.0.1:5000
 access-control-max-age: 1000
 content-length: 39
 content-type: application/json
 date: Thu, 03 Dec 2020 06:15:25 GMT
 server: Cowboy

 {
     "channel_id": "sora",
     "role": "sendrecv"
 }

ListConnections

x-sora-target:

Sora_20201013.ListConnections

すべての接続一覧を取得します。

キー	型	デフォルト
local (オプション)	boolean	true

local はクラスター機能利用時に、全てのノードの情報を取得するかどうかを指定します。

$ http POST 127.0.0.1:3000/ \
    x-sora-target:Sora_20201013.ListConnections \
    -vvv
POST / HTTP/1.1
Accept: */*
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 0
Host: 127.0.0.1:3000
User-Agent: HTTPie/2.2.0
x-sora-target: Sora_20201013.ListConnections



HTTP/1.1 200 OK
access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
access-control-allow-methods: POST, OPTIONS
access-control-allow-origin: http://127.0.0.1:5000
access-control-max-age: 1000
content-length: 908
content-type: application/json
date: Wed, 25 Nov 2020 09:25:07 GMT
server: Cowboy

[
    {
        "node_name": "[email protected]",
        "audio": {
            "codec_type": "OPUS"
        },
        "channel_id": "akane",
        "session_id": "JJJ5BFH7QN6DQBTKSS7JA8ZYQR",
        "client_id": "DV2Z3MSXC50M78Y11ETN3VZ360",
        "bundle_id": "DV2Z3MSXC50M78Y11ETN3VZ360",
        "connection_id": "DV2Z3MSXC50M78Y11ETN3VZ360",
        "created_time": 1734420116038137,
        "created_timestamp": "2024-12-17T07:21:56.038137Z",
        "event_metadata": {"spam": "egg"},
        "recording_block": false,
        "multistream": true,
        "role": "sendrecv",
        "simulcast": false,
        "spotlight": false,
        "video": {
            "bit_rate": 1000,
            "codec_type": "VP9",
            "vp9_params": { "profile_id": 0 }
        }
    },
    {
        "node_name": "[email protected]",
        "audio": {
            "codec_type": "OPUS"
        },
        "channel_id": "sora",
        "session_id": "FDYSGDVQ592CK5D4ZMC0W4XXDM",
        "client_id": "DKF93NH82X3BDB0CVKEH32JMVR",
        "bundle_id": "DKF93NH82X3BDB0CVKEH32JMVR",
        "connection_id": "DKF93NH82X3BDB0CVKEH32JMVR",
        "created_time": 1734420116038137,
        "created_timestamp": "2024-12-17T07:21:56.038137Z",
        "event_metadata": {"spam": "egg"},
        "recording_block": false,
        "multistream": true,
        "role": "sendrecv",
        "simulcast": false,
        "spotlight": false,
        "video": {
            "bit_rate": 1000,
            "codec_type": "VP9",
            "vp9_params": { "profile_id": 0 }
        }
    },
    {
        "node_name": "[email protected]",
        "audio": {
            "codec_type": "OPUS"
        },
        "channel_id": "sora",
        "session_id": "FDYSGDVQ592CK5D4ZMC0W4XXDM",
        "client_id": "W6725M370N2W301378Y5SFG01C",
        "bundle_id": "W6725M370N2W301378Y5SFG01C",
        "connection_id": "W6725M370N2W301378Y5SFG01C",
        "created_time": 1734420116038137,
        "created_timestamp": "2024-12-17T07:21:56.038137Z",
        "event_metadata": {"spam": "egg"},
        "recording_block": false,
        "multistream": true,
        "role": "sendrecv",
        "simulcast": false,
        "spotlight": false,
        "video": {
            "bit_rate": 1000,
            "codec_type": "VP9",
            "vp9_params": { "profile_id": 0 }
        }
    }
]

ListChannelConnections

x-sora-target:

Sora_20201013.ListChannelConnections

指定したチャネルの接続一覧を取得します。

キー	型
channel_id	string

$ http POST 127.0.0.1:3000/ \
    x-sora-target:Sora_20201013.ListChannelConnections \
    channel_id=sora \
    -vvv
POST / HTTP/1.1
Accept: application/json, */*;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 22
Content-Type: application/json
Host: 127.0.0.1:3000
User-Agent: HTTPie/2.2.0
x-sora-target: Sora_20201013.ListChannelConnections

{
    "channel_id": "sora"
}

HTTP/1.1 200 OK
access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
access-control-allow-methods: POST, OPTIONS
access-control-allow-origin: http://127.0.0.1:5000
access-control-max-age: 1000
content-length: 605
content-type: application/json
date: Wed, 25 Nov 2020 09:26:00 GMT
server: Cowboy

[
    {
        "node_name": "[email protected]",
        "audio": {
            "codec_type": "OPUS"
        },
        "channel_id": "sora",
        "session_id": "FDYSGDVQ592CK5D4ZMC0W4XXDM",
        "client_id": "DKF93NH82X3BDB0CVKEH32JMVR",
        "bundle_id": "DKF93NH82X3BDB0CVKEH32JMVR",
        "connection_id": "DKF93NH82X3BDB0CVKEH32JMVR",
        "created_time": 1734420116038137,
        "created_timestamp": "2024-12-17T07:21:56.038137Z",
        "event_metadata": {"spam": "egg"},
        "recording_block": false,
        "multistream": true,
        "role": "sendrecv",
        "simulcast": false,
        "spotlight": false,
        "video": {
            "bit_rate": 1000,
            "codec_type": "VP9",
            "vp9_params": { "profile_id": 0 }
        }
    },
    {
        "node_name": "[email protected]",
        "audio": {
            "codec_type": "OPUS"
        },
        "channel_id": "sora",
        "session_id": "FDYSGDVQ592CK5D4ZMC0W4XXDM",
        "client_id": "W6725M370N2W301378Y5SFG01C",
        "bundle_id": "W6725M370N2W301378Y5SFG01C",
        "connection_id": "W6725M370N2W301378Y5SFG01C",
        "created_time": 1734420116038137,
        "created_timestamp": "2024-12-17T07:21:56.038137Z",
        "event_metadata": {"spam": "egg"},
        "recording_block": false,
        "multistream": true,
        "role": "sendrecv",
        "simulcast": false,
        "spotlight": false,
        "video": {
            "bit_rate": 1000,
            "codec_type": "VP9",
            "vp9_params": { "profile_id": 0 }
        }
    }
]

コネクション API

RequestKeyFrame

x-sora-target:

Sora_20241218.RequestKeyFrame

指定したチャネルの接続に対してキーフレームを要求します。

キーフレーム要求を送ってからキーフレームが送られてくるまでは、 1 秒間隔で最大 5 回までリクエストを送信します。

channel_id や connection_id が存在しない場合はエラーとなります。

警告

この API は レガシーストリーム では利用できません。

キー	型
channel_id	string
connection_id	string

$ http POST 127.0.0.1:3000/ \
    x-sora-target:Sora_20241218.RequestKeyFrame \
    channel_id=sora \
    connection_id=KDBN2YD1A919V5BA2JX6TG2RP8 -vvv
POST / HTTP/1.1
Accept: application/json, */*;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 69
Content-Type: application/json
Host: 127.0.0.1:3000
User-Agent: HTTPie/2.4.0
x-sora-target: Sora_20241218.RequestKeyFrame

{
    "channel_id": "sora",
    "connection_id": "KP8VZZ321D0A90RSVJC4RMGJ08"
}


HTTP/1.1 200 OK
access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
access-control-allow-methods: POST, OPTIONS
access-control-allow-origin: http://127.0.0.1:5000
access-control-max-age: 1000
content-length: 10954
content-type: application/json
date: Tue, 30 Nov 2021 01:59:51 GMT
server: Cowboy

{
    "channel_id": "sora",
    "connection_id": "KP8VZZ321D0A90RSVJC4RMGJ08"
}

セッション API

TerminateSession

x-sora-target:

Sora_20230628.TerminateSession

指定したセッションを強制的に破棄させる API です、そのセッションに接続しているクライアントはすべて切断します。

この API は非同期のため、リクエストを受け付けた後に即座にレスポンスを返します。 セッション破棄の完了は session.destroyed で確認してください。

キー	型
channel_id	string
session_id (オプション)	string

• channel_id を指定して、セッションを終了させます

• session_id を追加で指定することができますが、 session_id が見つからない場合はエラーになります

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

$ http POST 127.0.0.1:3000/ x-sora-target:Sora_20230628.TerminateSession \
    channel_id=sora \
    session_id=JJJ5BFH7QN6DQBTKSS7JA8ZYQR \
    -vvv

POST / HTTP/1.1
Accept: application/json, */*
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 66
Content-Type: application/json
Host: 127.0.0.1:3000
User-Agent: HTTPie/2.6.0
x-sora-target: Sora_20230628.TerminateSession

{
    "channel_id": "sora",
    "session_id": "JJJ5BFH7QN6DQBTKSS7JA8ZYQR"
}


HTTP/1.1 200 OK
content-length: 43
content-type: application/json
date: Tue, 23 May 2023 09:59:06 GMT
server: Cowboy

{
    "session_id": "JJJ5BFH7QN6DQBTKSS7JA8ZYQR"
}

サイマルキャスト API

RequestRtpStream

x-sora-target:

Sora_20201005.RequestRtpStream

指定した視聴者の受信する RTP ストリームの rid をリクエストします。

キー	型
channel_id	string
recv_connection_id	string
send_connection_id (オプション)	string
rid	string (r0 | r1 | r2)

r1 までしか配信されていない場合に、r2 をリクエストした場合は r1 を受信し始めます。

$ http POST 127.0.0.1:3000/ \
    x-sora-target:Sora_20201005.RequestRtpStream \
    channel_id=sora \
    recv_connection_id=4EVK3MN5Z17GB62RE5TGD045ZM \
    send_connection_id=EKNQ103WRD4ZZ74B6TKRM9YK78 \
    rid=r1 \
    -vvv
POST / HTTP/1.1
Accept: application/json, */*;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 139
Content-Type: application/json
Host: 127.0.0.1:3000
User-Agent: HTTPie/2.2.0
x-sora-target: Sora_20201005.RequestRtpStream

{
    "channel_id": "sora",
    "recv_connection_id": "4EVK3MN5Z17GB62RE5TGD045ZM",
    "rid": "r1",
    "send_connection_id": "EKNQ103WRD4ZZ74B6TKRM9YK78"
}

HTTP/1.1 200 OK
access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
access-control-allow-methods: POST, OPTIONS
access-control-allow-origin: http://127.0.0.1:5000
access-control-max-age: 1000
content-length: 132
content-type: application/json
date: Wed, 25 Nov 2020 09:31:11 GMT
server: Cowboy

{
    "channel_id": "sora",
    "recv_connection_id": "4EVK3MN5Z17GB62RE5TGD045ZM",
    "rid": "r1",
    "send_connection_id": "EKNQ103WRD4ZZ74B6TKRM9YK78"
}

ResetRtpStream

x-sora-target:

Sora_20201005.ResetRtpStream

指定した視聴者の受信する RTP ストリームの rid をリセットします。

キー	型
channel_id	string
recv_connection_id	string
send_connection_id (オプション)	string

$ http POST 127.0.0.1:3000/ \
    x-sora-target:Sora_20201005.ResetRtpStream \
    channel_id=sora \
    recv_connection_id=4EVK3MN5Z17GB62RE5TGD045ZM \
    send_connection_id=EKNQ103WRD4ZZ74B6TKRM9YK78 \
    -vvv
POST / HTTP/1.1
Accept: application/json, */*;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 126
Content-Type: application/json
Host: 127.0.0.1:3000
User-Agent: HTTPie/2.2.0
x-sora-target: Sora_20201005.ResetRtpStream

{
    "channel_id": "sora",
    "recv_connection_id": "4EVK3MN5Z17GB62RE5TGD045ZM",
    "send_connection_id": "EKNQ103WRD4ZZ74B6TKRM9YK78"
}

HTTP/1.1 200 OK
access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
access-control-allow-methods: POST, OPTIONS
access-control-allow-origin: http://127.0.0.1:5000
access-control-max-age: 1000
content-length: 121
content-type: application/json
date: Wed, 25 Nov 2020 09:31:57 GMT
server: Cowboy

{
    "channel_id": "sora",
    "recv_connection_id": "4EVK3MN5Z17GB62RE5TGD045ZM",
    "send_connection_id": "EKNQ103WRD4ZZ74B6TKRM9YK78"
}

スポットライト API

FocusSpotlightFixed

x-sora-target:

Sora_20200807.FocusSpotlightFixed

指定した Connection ID のクライアントに常にフォーカスが当たるようにします。 これは UnfocusSpotlight API が呼ばれるまで当たり続けます。

キー	型
channel_id	string
connection_id	string

$ http POST 127.0.0.1:3000/ x-sora-target:Sora_20200807.FocusSpotlightFixed \
    channel_id=sora connection_id=7QSNT842FS0J9E6BZDBC2DRYY8 -vvv
POST / HTTP/1.1
Accept: application/json, */*
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 69
Content-Type: application/json
Host: 127.0.0.1:3000
User-Agent: HTTPie/2.0.0
x-sora-target: Sora_20200807.FocusSpotlightFixed

{
    "channel_id": "sora",
    "connection_id": "7QSNT842FS0J9E6BZDBC2DRYY8"
}

HTTP/1.1 200 OK
access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
access-control-allow-methods: POST, OPTIONS
access-control-allow-origin: http://127.0.0.1:5000
access-control-max-age: 1000
content-length: 66
content-type: application/json
date: Wed, 09 Sep 2020 08:27:57 GMT
server: Cowboy

{
    "channel_id": "sora",
    "connection_id": "7QSNT842FS0J9E6BZDBC2DRYY8"
}

FocusSpotlight

x-sora-target:

Sora_20200807.FocusSpotlight

指定した Connection ID のクライアントを強制的にフォーカスが当たった状態にします。

キー	型
channel_id	string
connection_id	string

$ http POST 127.0.0.1:3000/ x-sora-target:Sora_20200807.FocusSpotlight \
    channel_id=sora connection_id=74Z2G1JS7S67DE226T8R1H3YGW -vvv
POST / HTTP/1.1
Accept: application/json, */*
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 69
Content-Type: application/json
Host: 127.0.0.1:3000
User-Agent: HTTPie/2.0.0
x-sora-target: Sora_20200807.FocusSpotlight

{
    "channel_id": "sora",
    "connection_id": "74Z2G1JS7S67DE226T8R1H3YGW"
}

HTTP/1.1 200 OK
access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
access-control-allow-methods: POST, OPTIONS
access-control-allow-origin: http://127.0.0.1:5000
access-control-max-age: 1000
content-length: 66
content-type: application/json
date: Wed, 09 Sep 2020 08:33:54 GMT
server: Cowboy

{
    "channel_id": "sora",
    "connection_id": "74Z2G1JS7S67DE226T8R1H3YGW"
}

UnfocusSpotlight

x-sora-target:

Sora_20200807.UnfocusSpotlight

指定した Connection ID のフォーカスを外します。

この API は FocusSpotlightFixed でフォーカスを当て続けてているのを解除する場合にも利用します。

キー	型
channel_id	string
connection_id	string

$ http POST 127.0.0.1:3000/ x-sora-target:Sora_20200807.UnfocusSpotlight \
    channel_id=sora connection_id=74Z2G1JS7S67DE226T8R1H3YGW -vvv
POST / HTTP/1.1
Accept: application/json, */*
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 69
Content-Type: application/json
Host: 127.0.0.1:3000
User-Agent: HTTPie/2.0.0
x-sora-target: Sora_20200807.UnfocusSpotlight

{
    "channel_id": "sora",
    "connection_id": "74Z2G1JS7S67DE226T8R1H3YGW"
}

HTTP/1.1 200 OK
access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
access-control-allow-methods: POST, OPTIONS
access-control-allow-origin: http://127.0.0.1:5000
access-control-max-age: 1000
content-length: 66
content-type: application/json
date: Wed, 09 Sep 2020 08:34:56 GMT
server: Cowboy

{
    "channel_id": "sora",
    "connection_id": "74Z2G1JS7S67DE226T8R1H3YGW"
}

ChangeSpotlightNumber

x-sora-target:

Sora_20200807.ChangeSpotlightNumber

フォーカスする最大数を変更します。最小は 1 で最大は 8 です

この API でフォーカス最大数を変更した後に、type:connect で spotlight_number を指定するクライアントは、 変更後の値 を指定する必要があります。

キー	型
channel_id	string
spotlight_number	integer (1..8)

$ http POST 127.0.0.1:3000/ x-sora-target:Sora_20200807.ChangeSpotlightNumber \
    channel_id=sora spotlight_number:=1 -vvv
POST / HTTP/1.1
Accept: application/json, */*
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 45
Content-Type: application/json
Host: 127.0.0.1:3000
User-Agent: HTTPie/2.0.0
x-sora-target: Sora_20200807.ChangeSpotlightNumber

{
    "channel_id": "sora",
    "spotlight_number": 1
}

HTTP/1.1 200 OK
access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
access-control-allow-methods: POST, OPTIONS
access-control-allow-origin: http://127.0.0.1:5000
access-control-max-age: 1000
content-length: 42
content-type: application/json
date: Wed, 09 Sep 2020 08:35:36 GMT
server: Cowboy

{
    "channel_id": "sora",
    "spotlight_number": 1
}

RequestSpotlightRid

x-sora-target:

Sora_20211215.RequestSpotlightRid

スポットライトのフォーカス時とアンフォーカス時の rid を指定します。 これにより接続時に指定した spotlight_focurs_rid と spotlight_unfocus_rid の値を変更できます。

キー	型
channel_id	string
recv_connection_id	string
send_connection_id (オプション)	string
spotlight_focus_rid	string (none | r0 | r1 | r2)
spotlight_unfocus_rid	string (none | r0 | r1 | r2)

$ http POST 127.0.0.1:3000/ x-sora-target:Sora_20211215.RequestSpotlightRid \
    channel_id=sora \
    recv_connection_id=AD0ZWY8W492XV9RQGB40GX5C94 \
    spotlight_focus_rid=none \
    spotlight_unfocus_rid=none \
    -vvv
POST / HTTP/1.1
Accept: application/json, */*;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 138
Content-Type: application/json
Host: 127.0.0.1:3000
User-Agent: HTTPie/2.4.0
x-sora-target: Sora_20211215.RequestSpotlightRid

{
    "channel_id": "sora",
    "recv_connection_id": "AD0ZWY8W492XV9RQGB40GX5C94",
    "spotlight_focus_rid": "none",
    "spotlight_unfocus_rid": "none"
}


HTTP/1.1 200 OK
access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
access-control-allow-methods: POST, OPTIONS
access-control-allow-origin: http://127.0.0.1:5000
access-control-max-age: 1000
content-length: 131
content-type: application/json
date: Tue, 30 Nov 2021 02:20:44 GMT
server: Cowboy

{
    "channel_id": "sora",
    "recv_connection_id": "AD0ZWY8W492XV9RQGB40GX5C94",
    "spotlight_focus_rid": "none",
    "spotlight_unfocus_rid": "none"
}

ResetSpotlightRid

x-sora-target:

Sora_20211215.ResetSpotlightRid

スポットライトのフォーカス時とアンフォーカス時の rid を接続時に指定した値に戻します。

キー	型
channel_id	string
recv_connection_id	string
send_connection_id (オプション)	string

$ http POST 127.0.0.1:3000/ x-sora-target:Sora_20211215.ResetSpotlightRid \
    channel_id=sora \
    recv_connection_id=AD0ZWY8W492XV9RQGB40GX5C94 \
    -vvv
POST / HTTP/1.1
Accept: application/json, */*;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 74
Content-Type: application/json
Host: 127.0.0.1:3000
User-Agent: HTTPie/2.4.0
x-sora-target: Sora_20211215.ResetSpotlightRid

{
    "channel_id": "sora",
    "recv_connection_id": "AD0ZWY8W492XV9RQGB40GX5C94"
}


HTTP/1.1 200 OK
access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
access-control-allow-methods: POST, OPTIONS
access-control-allow-origin: http://127.0.0.1:5000
access-control-max-age: 1000
content-length: 71
content-type: application/json
date: Tue, 30 Nov 2021 02:22:17 GMT
server: Cowboy

{
    "channel_id": "sora",
    "recv_connection_id": "AD0ZWY8W492XV9RQGB40GX5C94"
}

BatchRequestSpotlightRid

x-sora-target:

Sora_20211215.BatchRequestSpotlightRid

スポットライトのフォーカス時とアンフォーカス時の rid を一括で変更します。

キー	型
channel_id	string
item_list	array

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

キー	型
recv_connection_id	string
send_connection_id	string
spotlight_focus_rid	string (none | r0 | r1 | r2)
spotlight_unfocus_rid	string (none | r0 | r1 | r2)

$ http POST 127.0.0.1:3000/ x-sora-target:Sora_20211215.BatchRequestSpotlightRid \
    channel_id=sora \
    item_list:='[{"recv_connection_id": "AD0ZWY8W492XV9RQGB40GX5C94", "send_connection_id": "RGEFFZM95S2XN0PC03XNMCRTB0", \
                  "spotlight_focus_rid": "none", "spotlight_unfocus_rid": "none"}, \
                 {"recv_connection_id": "AD0ZWY8W492XV9RQGB40GX5C94", "send_connection_id": "P9AFYE2BQN7JB93Q6GK0VYWGHM", \
                  "spotlight_focus_rid": "none", "spotlight_unfocus_rid": "none"}]' \
    -vvv
POST / HTTP/1.1
Accept: application/json, */*;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 377
Content-Type: application/json
Host: 127.0.0.1:3000
User-Agent: HTTPie/2.4.0
x-sora-target: Sora_20211215.BatchRequestSpotlightRid

{
    "channel_id": "sora",
    "item_list": [
        {
            "recv_connection_id": "AD0ZWY8W492XV9RQGB40GX5C94",
            "send_connection_id": "RGEFFZM95S2XN0PC03XNMCRTB0",
            "spotlight_focus_rid": "none",
            "spotlight_unfocus_rid": "none"
        },
        {
            "recv_connection_id": "AD0ZWY8W492XV9RQGB40GX5C94",
            "send_connection_id": "P9AFYE2BQN7JB93Q6GK0VYWGHM",
            "spotlight_focus_rid": "none",
            "spotlight_unfocus_rid": "none"
        }
    ]
}


HTTP/1.1 200 OK
access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
access-control-allow-methods: POST, OPTIONS
access-control-allow-origin: http://127.0.0.1:5000
access-control-max-age: 1000
content-length: 387
content-type: application/json
date: Tue, 30 Nov 2021 02:29:51 GMT
server: Cowboy

{
    "channel_id": "sora",
    "item_list": [
        {
            "recv_connection_id": "AD0ZWY8W492XV9RQGB40GX5C94",
            "result": "ok",
            "send_connection_id": "RGEFFZM95S2XN0PC03XNMCRTB0",
            "spotlight_focus_rid": "none",
            "spotlight_unfocus_rid": "none"
        },
        {
            "recv_connection_id": "AD0ZWY8W492XV9RQGB40GX5C94",
            "result": "ok",
            "send_connection_id": "P9AFYE2BQN7JB93Q6GK0VYWGHM",
            "spotlight_focus_rid": "none",
            "spotlight_unfocus_rid": "none"
        }
    ]
}

プッシュ API

シグナリングで使用している WebSocket や DataChannel を活用できる API です。 この機能を使うことでアプリケーション側でプッシュの仕組みを用意する必要がなくなります。

PushChannel

x-sora-target:

Sora_20160711.PushChannel

指定したチャネル全員にプッシュ通知を送る。

キー	型
channel_id	string
data	object

data には全員に通知する値 (JSON object) を指定してください。 クライアントには data に指定した値 (JSON object) が送られます。

$ http POST 127.0.0.1:3000/ \
    x-sora-target:Sora_20160711.PushChannel \
    channel_id=sora \
    data:="{\"spam\": \"egg\"}" \
    -vvv
POST / HTTP/1.1
Accept: application/json
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 47
Content-Type: application/json
Host: 127.0.0.1:3000
User-Agent: HTTPie/0.9.4
x-sora-target: Sora_20160711.PushChannel

{
    "channel_id": "sora",
    "data": {
        "spam": "egg"
    }
}

HTTP/1.1 200 OK
content-length: 37
content-type: application/json
date: Sun, 24 Jul 2016 06:26:21 GMT
server: Cowboy

{
    "data": {
        "spam": "egg"
    },
    "type": "push"
}

PushClient

x-sora-target:

Sora_20160711.PushClient

指定したチャネルのクライアントにプッシュ通知を送ります。

キー	型
channel_id	string
client_id	string
data	object

複数の接続に同一の client_id が指定されていた場合、複数の接続にプッシュ通知が送られます。

$ http POST 127.0.0.1:3000/ \
    x-sora-target:Sora_20160711.PushClient \
    channel_id=sora \
    client_id=C0YTCRZM715BKATBXWFPKTYGRM \
    data:="{\"spam\": \"egg\"}" \
    -vvv
POST / HTTP/1.1
Accept: application/json
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 100
Content-Type: application/json
Host: 127.0.0.1:3000
User-Agent: HTTPie/0.9.4
x-sora-target: Sora_20160711.PushClient

{
    "channel_id": "sora",
    "client_id": "C0YTCRZM715BKATBXWFPKTYGRM",
    "data": {
        "spam": "egg"
    }
}

HTTP/1.1 200 OK
content-length: 37
content-type: application/json
date: Sun, 24 Jul 2016 07:46:31 GMT
server: Cowboy

{
    "data": {
        "spam": "egg"
    },
    "type": "push"
}

PushConnection

x-sora-target:

Sora_20160711.PushConnection

指定したチャネルの接続にプッシュ通知を送ります。

キー	型
channel_id	string
connection_id	string
data	object

$ http POST 127.0.0.1:3000/ \
    x-sora-target:Sora_20160711.PushConnection \
    channel_id=sora \
    connection_id=C0YTCRZM715BKATBXWFPKTYGRM \
    data:="{\"spam\": \"egg\"}" \
    -vvv
POST / HTTP/1.1
Accept: application/json
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 100
Content-Type: application/json
Host: 127.0.0.1:3000
User-Agent: HTTPie/0.9.4
x-sora-target: Sora_20160711.PushConnection

{
    "channel_id": "sora",
    "connection_id": "C0YTCRZM715BKATBXWFPKTYGRM",
    "data": {
        "spam": "egg"
    }
}

HTTP/1.1 200 OK
content-length: 37
content-type: application/json
date: Sun, 24 Jul 2016 07:46:31 GMT
server: Cowboy

{
    "data": {
        "spam": "egg"
    },
    "type": "push"
}

PushChannelByRole

x-sora-target:

Sora_20201120.PushChannelByRole

指定したチャネルの指定したロールにプッシュ通知を送ります。

キー	型
channel_id	string
role	string (sendrecv | sendonly | recvonly)
data	object

$ http POST 127.0.0.1:3000/ \
    x-sora-target:Sora_20201120.PushChannelByRole \
    channel_id=sora \
    role=sendrecv \
    data:="{\"spam\": \"egg\"}" \
    -vvv
    POST / HTTP/1.1
    Accept: application/json, */*;q=0.5
    Accept-Encoding: gzip, deflate
    Connection: keep-alive
    Content-Length: 67
    Content-Type: application/json
    Host: 127.0.0.1:3000
    User-Agent: HTTPie/2.2.0
    x-sora-target: Sora_20201120.PushChannelByRole

    {
        "channel_id": "sora",
        "data": {
            "spam": "egg"
        },
        "role": "sendrecv"
    }

    HTTP/1.1 200 OK
    access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
    access-control-allow-methods: POST, OPTIONS
    access-control-allow-origin: http://127.0.0.1:5000
    access-control-max-age: 1000
    content-length: 37
    content-type: application/json
    date: Thu, 03 Dec 2020 06:16:16 GMT
    server: Cowboy

    {
        "data": {
            "spam": "egg"
        },
        "type": "push"
    }

録画 (セッション単位) API

録画されたファイルは sora.conf の archive_dir に指定したディレクトリに置かれます。

StartRecording

x-sora-target:

Sora_20231220.StartRecording

指定したチャネルの録画を開始します。

クラスター機能利用時には、クラスター内のどのノードで実行しても開始された録画情報はすべてのノードで共有されます。

キー	型
channel_id	string
expire_time (オプション)	integer
split_duration (オプション)	integer
split_only (オプション)	boolean
metadata (オプション)	JSONValue
format (オプション)	string

• expire_time を指定しない場合は未指定になります

  • expire_time を指定しない場合、録画の期限が無くなります

• expire_time を指定する範囲は 1 から 86400 までで、秒数を指定してください

  • 指定できる最大値はデフォルトで 86400 で recording_max_expire_time に指定した値で変わります

• split_only は true か false を指定して下さい。指定しない場合は false が指定されます

• split_only を true に指定する場合は split_duration を指定する必要があります

• split_duration を指定する範囲は 1 から 86400 までで、秒数を指定して下さい

  • 指定できる最大値はデフォルトで 86400 で、 recording_max_split_duration に指定した値で変わります

• metadata は recording.report ウェブフックやレポートファイルに recording_metadata として含まれるようになります。

• format は webm または mp4 を指定してください

  • format が未指定の場合は default_recording_format の値が利用されます

  • 映像コーデックが H.265 の場合 format に mp4 を指定しない場合、録画が行われません

一括録画を行いたい場合

• split_only を false に指定するか、未指定にしてください

分割録画を行いたい場合

• split_only を true に指定してください

• split_duration を指定してください

一括＆分割録画を行いたい場合

• sora.conf の recording_dual_output を true に指定してください

• split_only を false に指定するか、未指定にしてください

• split_duration を指定してください

expire_time が指定無し

$ http POST 127.0.0.1:3000/ \
    x-sora-target:Sora_20231220.StartRecording \
    channel_id=sora \
    -vvv
POST / HTTP/1.1
Accept: application/json, */*
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 41
Content-Type: application/json
Host: 127.0.0.1:3000
User-Agent: HTTPie/0.9.9
x-sora-target: Sora_20161101.StartRecording

{
    "channel_id": "sora"
}

HTTP/1.1 200 OK
access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
access-control-allow-methods: POST, OPTIONS
access-control-allow-origin: http://127.0.0.1:5000
access-control-max-age: 1000
content-length: 82
content-type: application/json
date: Wed, 19 Apr 2017 06:35:38 GMT
server: Cowboy

{
    "channel_id": "sora",
    "expire_time": 0,
    "session_id": "96D7CQDEMS5CHCKDX46REWWTX4",
    "recording_id": "C0YTCRZM715BKATBXWFPKTYGRM"
}

expire_time が 3600

$ http POST 127.0.0.1:3000/ \
    x-sora-target:Sora_20231220.StartRecording \
    channel_id=sora \
    expire_time:=3600 \
    -vvv
POST / HTTP/1.1
Accept: application/json, */*
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 43
Content-Type: application/json
Host: 127.0.0.1:3000
User-Agent: HTTPie/0.9.9
x-sora-target: Sora_20161101.StartRecording

{
    "channel_id": "sora",
    "expire_time": 3600
}

HTTP/1.1 200 OK
access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
access-control-allow-methods: POST, OPTIONS
access-control-allow-origin: http://127.0.0.1:5000
access-control-max-age: 1000
content-length: 84
content-type: application/json
date: Wed, 19 Apr 2017 06:37:08 GMT
server: Cowboy

{
    "channel_id": "sora",
    "expire_time": 3600,
    "session_id": "96D7CQDEMS5CHCKDX46REWWTX4",
    "recording_id": "C0YTCRZM715BKATBXWFPKTYGRM"
}

split_only が true

$ http POST 127.0.0.1:3000/ \
    x-sora-target:Sora_20231220.StartRecording \
    channel_id=sora \
    split_duration:=3600 \
    split_only:=true \
    -vvv

POST / HTTP/1.1
Accept: application/json, */*;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 84
Content-Type: application/json
Host: 127.0.0.1:3000
User-Agent: HTTPie/2.2.0
x-sora-target: Sora_20161101.StartRecording

{
    "channel_id": "sora",
    "split_duration": 3600,
    "split_only": true
}

HTTP/1.1 200 OK
access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
access-control-allow-methods: POST, OPTIONS
access-control-allow-origin: http://127.0.0.1:5000
access-control-max-age: 1000
content-length: 121
content-type: application/json
date: Fri, 04 Dec 2020 03:04:17 GMT
server: Cowboy

{
    "channel_id": "sora",
    "expire_time": 0,
    "session_id": "96D7CQDEMS5CHCKDX46REWWTX4",
    "recording_id": "MK4J54QBGS4ES0MCSZMF6C9M9M",
    "split_duration": 3600,
    "split_only": true
}

エラー

• "STARTED-RECORDING"

  • 指定したチャネル ID で、すでに録画が開始している

• "NOT-CLUSTER-MAJORITY"

  • クラスターで半数以下のグループに所属している

$ http POST 127.0.0.1:3000/ \
        x-sora-target:Sora_20231220.StartRecording \
        channel_id=sora \
        expire_time:=3600 \
        -vvv
POST / HTTP/1.1
Accept: application/json, */*
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 43
Content-Type: application/json
Host: 127.0.0.1:3000
User-Agent: HTTPie/0.9.9
x-sora-target: Sora_20161101.StartRecording

{
    "channel_id": "sora",
    "expire_time": 3600
}

HTTP/1.1 400 Bad Request
access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
access-control-allow-methods: POST, OPTIONS
access-control-allow-origin: http://127.0.0.1:5000
access-control-max-age: 1000
content-length: 34
content-type: application/json
date: Wed, 19 Apr 2017 06:44:58 GMT
server: Cowboy

{
    "error_type": "STARTED-RECORDING"
}

StopRecording

x-sora-target:

Sora_20231220.StopRecording

指定したチャネルの録画を停止します。

この API は非同期です。200 が返ってきた場合でも録画ファイルや録画メタデータファイルが生成されていることを保証しません。 イベントウェブフックの archive.available または recording.report の通知を利用してください。

キー	型
channel_id	string

$ http POST 127.0.0.1:3000/ \
    x-sora-target:Sora_20231220.StopRecording \
    channel_id=sora \
    -vvv
POST / HTTP/1.1
Accept: application/json
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 22
Content-Type: application/json
Host: 127.0.0.1:3000
User-Agent: HTTPie/0.9.4
x-sora-target: Sora_20231220.StopRecording

{
    "channel_id": "sora"
}

HTTP/1.1 200 OK
content-length: 21
content-type: application/json
date: Fri, 11 Nov 2016 14:29:14 GMT
server: Cowboy

{
    "channel_id": "sora",
    "session_id": "96D7CQDEMS5CHCKDX46REWWTX4",
    "recording_id": "C0YTCRZM715BKATBXWFPKTYGRM"
}

エラー

• "NOT-STARTED-RECORDING"

  • 指定したチャネルの録画が開始されていない

• "NOT-CLUSTER-MAJORITY"

  • クラスターで半数以下のグループに所属している

統計 API

統計項目一覧

説明が書いていないものは項目名そのままの内容になります

• timestamp

  • API を取得した時点の UTC 時間 RFC3339 形式 (マイクロ秒)

• channel_id

• session_id

• client_id

• bundle_id

• connection_id

• simulcast

  • r0

    • rtp

      • total_decrypt_skipped_srtp

      • total_received_rtp

      • total_received_rtp_byte_size

      • total_received_rtp_padding

      • total_received_rtp_padding_size

      • total_received_rtp_red

      • total_received_rtp_red_rtx

      • total_received_rtp_red_ulpfec

      • total_received_rtp_rtx

    • rtp_hdrext

      • total_received_rtp_hdrext_abs_send_time

      • total_received_rtp_hdrext_audio_level

      • total_received_rtp_hdrext_av1_rtp_sepc

      • total_received_rtp_hdrext_color_space

      • total_received_rtp_hdrext_inband_cn

      • total_received_rtp_hdrext_playout_delay

      • total_received_rtp_hdrext_sdes_mid

      • total_received_rtp_hdrext_sdes_repaired_rtp_stream_id

      • total_received_rtp_hdrext_sdes_rtp_stream_id

      • total_received_rtp_hdrext_toffset

      • total_received_rtp_hdrext_transport_wide_cc

      • total_received_rtp_hdrext_unknown

      • total_received_rtp_hdrext_video_content_type

      • total_received_rtp_hdrext_video_orientation

      • total_received_rtp_hdrext_video_timing

      • total_received_rtp_hdrext_video_composition_time

  • r1

    • r0 と同様

  • r2

    • r0 と同様

• spotlight

  • total_spotlight_focus_failed

  • total_spotlight_unfocus_audio_no_room

  • total_spotlight_unfocus_audio_out_packet

  • total_spotlight_unfocus_audio_publish

• dtls

  • total_received_dtls

    • 受信した DTLS パケットの総数

  • total_sent_dtls

    • 送信した DTLS パケットの総数

• network_status

  • unstable_level

    • API を取得した時点の不安定レベル

  • total_unstable_level0

    • 不安定レベル 0 の回数

  • total_unstable_level1

    • 不安定レベル 1 の回数

  • total_unstable_level2

    • 不安定レベル 2 の回数

  • total_unstable_level3

    • 不安定レベル 3 の回数

• ice_connection_state

  • total_connected_req

    • connected 状態での疎通確認用のリクエスト送信回数

  • total_connected_ack

    • connected 状態での疎通確認用の応答受信回数

  • total_checking_req

    • checking 状態での疎通確認用のリクエスト送信回数

  • total_checking_ack

    • checking 状態での疎通確認用の応答受信回数

  • total_disconnected_req

    • disconnected 状態での疎通確認用のリクエスト送信回数

  • total_disconnected_ack

    • disconnected 状態での疎通確認用の応答受信回数

  • total_connected_to_checking

    • connected 状態から checking 状態へ遷移した回数

  • total_checking_to_disconnected

    • checking 状態から disconnected 状態へ遷移した回数

  • total_disconnected_to_failed

    • disconnected 状態から failed 状態へ遷移した回数

  • total_checking_to_connected

    • checking 状態から connected 状態へ遷移した回数

  • total_disconnected_to_checking

    • disconnected 状態から checking 状態へ遷移した回数

  • total_checking_duration_ms

    • checking 状態であった時間の合計

  • total_disconnected_duration_ms

    • disconnected 状態であった時間の合計

• signaling

  • total_received_signaling_pong

  • total_sent_signaling_ping

• packet_loss_simulator

  • total_dropped_received_rtp

    • 受信したがパケロスシミュレータが落とした RTP パケットの総数

  • total_dropped_sent_rtp

    • 送信したがパケロスシミュレータが落とした RTP パケットの総数

  • total_dropped_received_data_channel

    • 受信したがパケロスシミュレータが落とした DataChannel パケットの総数

  • total_dropped_sent_data_channel

    • 送信したがパケロスシミュレータが落とした DataChannel パケットの総数

• rtp

  • total_received

  • total_received_byte_size

  • total_received_rtp

  • total_received_rtp_byte_size

  • total_received_rtp_red

  • total_received_rtp_red_rtx

  • total_received_rtp_red_ulpfec

  • total_received_rtp_rtx

  • total_received_sounding_rtp

  • total_sent

  • total_sent_byte_size

  • total_sent_rtp

  • total_sent_rtp_byte_size

  • total_decrypt_skipped_srtp

    • 復号をスキップした SRTP 総数

  • total_decrypt_skipped_video_srtp

    • 復号をスキップした映像 SRTP 総数

  • total_decrypt_skipped_audio_srtp

    • 復号をスキップした音声 SRTP 総数

  • total_received_srtp_invalid

  • total_received_rtp_padding

  • total_received_rtp_padding_size

  • total_received_key_frame

    • キーフレームを受信した総数

  • total_ulpfec_recovered

    • ULPFEC を利用して損失パケットを回復した総数

• rtp_hdrext

  • total_received_rtp_hdrext_abs_send_time

  • total_received_rtp_hdrext_audio_level

  • total_received_rtp_hdrext_av1_rtp_sepc

  • total_received_rtp_hdrext_color_space

  • total_received_rtp_hdrext_inband_cn

  • total_received_rtp_hdrext_playout_delay

  • total_received_rtp_hdrext_sdes_mid

  • total_received_rtp_hdrext_sdes_repaired_rtp_stream_id

  • total_received_rtp_hdrext_sdes_rtp_stream_id

  • total_received_rtp_hdrext_toffset

  • total_received_rtp_hdrext_transport_wide_cc

  • total_received_rtp_hdrext_unknown

  • total_received_rtp_hdrext_video_content_type

  • total_received_rtp_hdrext_video_orientation

  • total_received_rtp_hdrext_video_timing

  • total_received_rtp_hdrext_abs_capture_time

  • total_received_rtp_hdrext_video_composition_time

  • total_sent_rtp_hdrext_abs_send_time

  • total_sent_rtp_hdrext_audio_level

  • total_sent_rtp_hdrext_av1_rtp_sepc

  • total_sent_rtp_hdrext_color_space

  • total_sent_rtp_hdrext_inband_cn

  • total_sent_rtp_hdrext_playout_delay

  • total_sent_rtp_hdrext_sdes_mid

  • total_sent_rtp_hdrext_sdes_repaired_rtp_stream_id

  • total_sent_rtp_hdrext_sdes_rtp_stream_id

  • total_sent_rtp_hdrext_toffset

  • total_sent_rtp_hdrext_transport_wide_cc

  • total_sent_rtp_hdrext_unknown

  • total_sent_rtp_hdrext_video_content_type

  • total_sent_rtp_hdrext_video_orientation

  • total_sent_rtp_hdrext_video_timing

  • total_sent_rtp_hdrext_abs_capture_time

  • total_sent_rtp_hdrext_video_composition_time

• rtcp

  • total_generic_nack_cache_hit

    • 再送要求に答えた総数

  • total_generic_nack_cache_miss

    • 再送要求に答えられなかった総数

  • total_pli_trigger

    • 再送要求が限界に来たため全画面要求(PLI) を送信した総数

  • total_received_rtcp

  • total_received_rtcp_bye

  • total_received_rtcp_byte_size

  • total_received_rtcp_psfb_afb

  • total_received_rtcp_psfb_fir

  • total_received_rtcp_psfb_pli

  • total_received_rtcp_rr

  • total_received_rtcp_rtpfb_generic_nack

  • total_received_rtcp_rtpfb_tmmbn

  • total_received_rtcp_rtpfb_tmmbr

  • total_received_rtcp_rtpfb_transport_wide

  • total_received_rtcp_sdes

  • total_received_rtcp_sr

  • total_received_rtcp_unknown

  • total_received_rtcp_xr

  • total_sent_rtcp

  • total_sent_rtcp_bye

  • total_sent_rtcp_byte_size

  • total_sent_rtcp_psfb_afb

  • total_sent_rtcp_psfb_fir

  • total_sent_rtcp_psfb_pli

  • total_sent_rtcp_rr

  • total_sent_rtcp_rtpfb_generic_nack

  • total_sent_rtcp_rtpfb_tmmbn

  • total_sent_rtcp_rtpfb_tmmbr

  • total_sent_rtcp_rtpfb_transport_wide

  • total_sent_rtcp_sdes

  • total_sent_rtcp_sr

  • total_sent_rtcp_unknown

  • total_sent_rtcp_xr

• turn

  • total_received_allocate_request

  • total_received_binding_request

  • total_received_channel_bind_request

  • total_received_channel_data

  • total_received_create_permission_request

  • total_received_expired_channel_number

  • total_received_invalid_channel_data

  • total_received_refresh_request

  • total_received_send_indication

  • total_received_stun_invalid

  • total_received_stun_unknown

  • total_received_turn_binding_error

  • total_received_turn_binding_request

  • total_received_turn_binding_success

  • total_received_turn_invalid_stun

  • total_received_turn_unknown

  • total_received_turn_unknown_stun

  • total_received_unknown_channel_number

  • total_received_unknown_packet

  • total_sent_allocate_error

  • total_sent_allocate_success

  • total_sent_binding_error

  • total_sent_binding_success

  • total_sent_channel_bind_error

  • total_sent_channel_bind_success

  • total_sent_channel_data

  • total_sent_create_permission_error

  • total_sent_create_permission_success

  • total_sent_data_indication

  • total_sent_refresh_error

  • total_sent_refresh_success

  • total_sent_turn_binding_error

  • total_sent_turn_binding_request

  • total_sent_turn_binding_success

  • total_sent_turn_unknown

• data_channel

  • signaling

    • ordered

    • max_packet_life_time

    • max_retransmits

    • protocol

    • direction

    • compress

    • total_data_channel_abandon_message

    • total_data_channel_retransmit_message

    • total_data_channel_open_message

    • total_data_channel_ack_message

    • total_received_data_channel_message

    • total_received_data_channel_message_byte_size

    • total_sent_data_channel_message

    • total_sent_data_channel_message_byte_size

  • notify

    • signaling と同様

  • push

    • signaling と同様

  • stats

    • signaling と同様

  • # から始まるメッセージング用ラベル

    • signaling と同様

• sctp

  • total_received_sctp_zero_checksum

    • SCTP チェックサムを 0 で受信した総数

  • total_sent_sctp_zero_checksum

    • SCTP チェックサムを 0 で送信した総数

  • total_received_invalid_sctp

  • total_received_sctp

  • total_received_sctp_byte_size

  • total_received_sctp_chunk_abort

  • total_received_sctp_chunk_asconf

  • total_received_sctp_chunk_asconf_ack

  • total_received_sctp_chunk_auth

  • total_received_sctp_chunk_cookie_ack

  • total_received_sctp_chunk_cookie_echo

  • total_received_sctp_chunk_cwr

  • total_received_sctp_chunk_data

  • total_received_sctp_chunk_ecne

  • total_received_sctp_chunk_error

  • total_received_sctp_chunk_forward_tsn

  • total_received_sctp_chunk_heartbeat

  • total_received_sctp_chunk_heartbeat_ack

  • total_received_sctp_chunk_i_data

  • total_received_sctp_chunk_i_forward_tsn

  • total_received_sctp_chunk_init

  • total_received_sctp_chunk_init_ack

  • total_received_sctp_chunk_pad

  • total_received_sctp_chunk_reconfig

  • total_received_sctp_chunk_sack

  • total_received_sctp_chunk_shutdown

  • total_received_sctp_chunk_shutdown_ack

  • total_received_sctp_chunk_shutdown_complete

  • total_received_sctp_chunk_unknown

  • total_received_unknown_sctp

  • total_sent_sctp

  • total_sent_sctp_byte_size

  • total_sent_sctp_chunk_abort

  • total_sent_sctp_chunk_asconf

  • total_sent_sctp_chunk_asconf_ack

  • total_sent_sctp_chunk_auth

  • total_sent_sctp_chunk_cookie_ack

  • total_sent_sctp_chunk_cookie_echo

  • total_sent_sctp_chunk_cwr

  • total_sent_sctp_chunk_data

  • total_sent_sctp_chunk_ecne

  • total_sent_sctp_chunk_error

  • total_sent_sctp_chunk_forward_tsn

  • total_sent_sctp_chunk_heartbeat

  • total_sent_sctp_chunk_heartbeat_ack

  • total_sent_sctp_chunk_i_data

  • total_sent_sctp_chunk_i_forward_tsn

  • total_sent_sctp_chunk_init

  • total_sent_sctp_chunk_init_ack

  • total_sent_sctp_chunk_pad

  • total_sent_sctp_chunk_reconfig

  • total_sent_sctp_chunk_sack

  • total_sent_sctp_chunk_shutdown

  • total_sent_sctp_chunk_shutdown_ack

  • total_sent_sctp_chunk_shutdown_complete

  • total_sent_sctp_chunk_unknown

• cc

  • bwe_period

  • congestion_window

  • delay_based_estimated_bitrate

  • pacer_data_window

  • pacer_padding_window

  • round_trip_time

  • stable_target_bitrate

  • target_bitrate

GetStatsConnection

x-sora-target:

Sora_20170529.GetStatsConnection

指定した接続の統計情報を取得します。

キー	型
channel_id	string
connection_id	string

$ http POST 127.0.0.1:3000/ \
    x-sora-target:Sora_20170529.GetStatsConnection \
    channel_id=sora \
    connection_id=KDBN2YD1A919V5BA2JX6TG2RP8 -vvv
POST / HTTP/1.1
Accept: application/json, */*;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 69
Content-Type: application/json
Host: 127.0.0.1:3000
User-Agent: HTTPie/2.4.0
x-sora-target: Sora_20170529.GetStatsConnection

{
    "channel_id": "sora",
    "connection_id": "KP8VZZ321D0A90RSVJC4RMGJ08"
}


HTTP/1.1 200 OK
access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
access-control-allow-methods: POST, OPTIONS
access-control-allow-origin: http://127.0.0.1:5000
access-control-max-age: 1000
content-length: 10954
content-type: application/json
date: Tue, 30 Nov 2021 01:59:51 GMT
server: Cowboy

{
    "channel_id": "sora",
    "session_id": "FDYSGDVQ592CK5D4ZMC0W4XXDM",
    "client_id": "KP8VZZ321D0A90RSVJC4RMGJ08",
    "bundle_id": "KP8VZZ321D0A90RSVJC4RMGJ08",
    "connection_id": "KP8VZZ321D0A90RSVJC4RMGJ08",
    "cc": {
        "bwe_period": 0,
        "congestion_window": 0,
        "delay_based_estimated_bitrate": 0,
        "pacer_data_window": 0,
        "pacer_padding_window": 0,
        "round_trip_time": 0,
        "stable_target_bitrate": 0,
        "target_bitrate": 0
    },
    "data_channel": {
        "#test": {
            "compress": false,
            "direction": "sendrecv",
            "ordered": true,
            "protocol": "",
            "total_data_channel_abandon_message": 0,
            "total_data_channel_ack_message": 0,
            "total_data_channel_open_message": 0,
            "total_data_channel_retransmit_message": 0,
            "total_received_data_channel_message": 1,
            "total_received_data_channel_message_byte_size": 1,
            "total_sent_data_channel_message": 1,
            "total_sent_data_channel_message_byte_size": 17
        },
        "notify": {
            "compress": true,
            "direction": "recvonly",
            "ordered": true,
            "protocol": "",
            "total_data_channel_abandon_message": 0,
            "total_data_channel_ack_message": 0,
            "total_data_channel_open_message": 0,
            "total_data_channel_retransmit_message": 0,
            "total_received_data_channel_message": 1,
            "total_received_data_channel_message_byte_size": 1,
            "total_sent_data_channel_message": 8,
            "total_sent_data_channel_message_byte_size": 627
        },
        "push": {
            "compress": true,
            "direction": "recvonly",
            "ordered": true,
            "protocol": "",
            "total_data_channel_abandon_message": 0,
            "total_data_channel_ack_message": 0,
            "total_data_channel_open_message": 0,
            "total_data_channel_retransmit_message": 0,
            "total_received_data_channel_message": 1,
            "total_received_data_channel_message_byte_size": 1,
            "total_sent_data_channel_message": 1,
            "total_sent_data_channel_message_byte_size": 16
        },
        "signaling": {
            "compress": true,
            "direction": "sendrecv",
            "ordered": true,
            "protocol": "",
            "total_data_channel_abandon_message": 0,
            "total_data_channel_ack_message": 0,
            "total_data_channel_open_message": 0,
            "total_data_channel_retransmit_message": 0,
            "total_received_data_channel_message": 1,
            "total_received_data_channel_message_byte_size": 1,
            "total_sent_data_channel_message": 1,
            "total_sent_data_channel_message_byte_size": 21
        },
        "stats": {
            "compress": true,
            "direction": "sendrecv",
            "ordered": true,
            "protocol": "",
            "total_data_channel_abandon_message": 0,
            "total_data_channel_ack_message": 0,
            "total_data_channel_open_message": 0,
            "total_data_channel_retransmit_message": 0,
            "total_received_data_channel_message": 3,
            "total_received_data_channel_message_byte_size": 30078,
            "total_sent_data_channel_message": 3,
            "total_sent_data_channel_message_byte_size": 73
        }
    },
    "dtls": {
        "total_received_dtls": 36,
        "total_sent_dtls": 37
    },
    "packet_loss_simulator": {
        "total_dropped_received_data_channel": 2,
        "total_dropped_received_rtp": 0,
        "total_dropped_sent_data_channel": 2,
        "total_dropped_sent_rtp": 0
    },
    "rtcp": {
        "total_generic_nack_cache_hit": 4,
        "total_generic_nack_cache_miss": 0,
        "total_pli_trigger": 0,
        "total_received_rtcp": 375,
        "total_received_rtcp_bye": 0,
        "total_received_rtcp_byte_size": 33260,
        "total_received_rtcp_psfb_afb": 278,
        "total_received_rtcp_psfb_fir": 0,
        "total_received_rtcp_psfb_pli": 0,
        "total_received_rtcp_rr": 73,
        "total_received_rtcp_rtpfb_generic_nack": 4,
        "total_received_rtcp_rtpfb_tmmbn": 0,
        "total_received_rtcp_rtpfb_tmmbr": 0,
        "total_received_rtcp_rtpfb_transport_wide": 0,
        "total_received_rtcp_sdes": 298,
        "total_received_rtcp_sr": 298,
        "total_received_rtcp_unknown": 0,
        "total_received_rtcp_xr": 0,
        "total_sent_rtcp": 184,
        "total_sent_rtcp_bye": 0,
        "total_sent_rtcp_byte_size": 14812,
        "total_sent_rtcp_psfb_afb": 79,
        "total_sent_rtcp_psfb_fir": 0,
        "total_sent_rtcp_psfb_pli": 0,
        "total_sent_rtcp_rr": 91,
        "total_sent_rtcp_rtpfb_generic_nack": 0,
        "total_sent_rtcp_rtpfb_tmmbn": 0,
        "total_sent_rtcp_rtpfb_tmmbr": 0,
        "total_sent_rtcp_rtpfb_transport_wide": 0,
        "total_sent_rtcp_sdes": 93,
        "total_sent_rtcp_sr": 93,
        "total_sent_rtcp_unknown": 0,
        "total_sent_rtcp_xr": 0
    },
    "rtp": {
        "total_decrypt_skipped_audio_srtp": 717,
        "total_decrypt_skipped_srtp": 1599,
        "total_decrypt_skipped_video_srtp": 882,
        "total_received": 5706,
        "total_received_byte_size": 1879672,
        "total_received_rtp": 5331,
        "total_received_rtp_byte_size": 1846412,
        "total_received_key_frame": 0,
        "total_received_rtp_padding": 0,
        "total_received_rtp_padding_size": 0,
        "total_received_rtp_red": 0,
        "total_received_rtp_red_rtx": 0,
        "total_received_rtp_red_ulpfec": 0,
        "total_received_rtp_rtx": 79,
        "total_received_sounding_rtp": 0,
        "total_received_srtp_invalid": 0,
        "total_sent": 5548,
        "total_sent_byte_size": 2015913,
        "total_sent_rtp": 5364,
        "total_sent_rtp_byte_size": 2001101,
        "total_ulpfec_recovered": 0
    },
    "rtp_hdrext": {
        "total_received_rtp_hdrext_abs_send_time": 5331,
        "total_received_rtp_hdrext_audio_level": 3187,
        "total_received_rtp_hdrext_av1_rtp_sepc": 2144,
        "total_received_rtp_hdrext_color_space": 0,
        "total_received_rtp_hdrext_inband_cn": 0,
        "total_received_rtp_hdrext_playout_delay": 0,
        "total_received_rtp_hdrext_sdes_mid": 0,
        "total_received_rtp_hdrext_sdes_repaired_rtp_stream_id": 0,
        "total_received_rtp_hdrext_sdes_rtp_stream_id": 0,
        "total_received_rtp_hdrext_toffset": 0,
        "total_received_rtp_hdrext_transport_wide_cc": 0,
        "total_received_rtp_hdrext_unknown": 0,
        "total_received_rtp_hdrext_video_content_type": 0,
        "total_received_rtp_hdrext_video_orientation": 0,
        "total_received_rtp_hdrext_video_timing": 0,
        "total_sent_rtp_hdrext_abs_send_time": 0,
        "total_sent_rtp_hdrext_audio_level": 3188,
        "total_sent_rtp_hdrext_av1_rtp_sepc": 2176,
        "total_sent_rtp_hdrext_color_space": 0,
        "total_sent_rtp_hdrext_inband_cn": 0,
        "total_sent_rtp_hdrext_playout_delay": 0,
        "total_sent_rtp_hdrext_sdes_mid": 0,
        "total_sent_rtp_hdrext_sdes_repaired_rtp_stream_id": 0,
        "total_sent_rtp_hdrext_sdes_rtp_stream_id": 0,
        "total_sent_rtp_hdrext_toffset": 0,
        "total_sent_rtp_hdrext_transport_wide_cc": 0,
        "total_sent_rtp_hdrext_unknown": 0,
        "total_sent_rtp_hdrext_video_content_type": 0,
        "total_sent_rtp_hdrext_video_orientation": 0,
        "total_sent_rtp_hdrext_video_timing": 0
    },
    "sctp": {
        "total_pruned_sctp_data_chunk": 0,
        "total_received_invalid_sctp": 0,
        "total_received_sctp": 32,
        "total_received_sctp_byte_size": 8244,
        "total_received_sctp_chunk_abort": 0,
        "total_received_sctp_chunk_asconf": 0,
        "total_received_sctp_chunk_asconf_ack": 0,
        "total_received_sctp_chunk_auth": 0,
        "total_received_sctp_chunk_cookie_ack": 0,
        "total_received_sctp_chunk_cookie_echo": 1,
        "total_received_sctp_chunk_cwr": 0,
        "total_received_sctp_chunk_data": 14,
        "total_received_sctp_chunk_ecne": 0,
        "total_received_sctp_chunk_error": 0,
        "total_received_sctp_chunk_forward_tsn": 0,
        "total_received_sctp_chunk_heartbeat": 0,
        "total_received_sctp_chunk_heartbeat_ack": 2,
        "total_received_sctp_chunk_i_data": 0,
        "total_received_sctp_chunk_i_forward_tsn": 0,
        "total_received_sctp_chunk_init": 1,
        "total_received_sctp_chunk_init_ack": 0,
        "total_received_sctp_chunk_pad": 19,
        "total_received_sctp_chunk_reconfig": 0,
        "total_received_sctp_chunk_sack": 15,
        "total_received_sctp_chunk_shutdown": 0,
        "total_received_sctp_chunk_shutdown_ack": 0,
        "total_received_sctp_chunk_shutdown_complete": 0,
        "total_received_sctp_chunk_unknown": 0,
        "total_received_sctp_zero_checksum": 0,
        "total_received_unknown_sctp": 0,
        "total_sent_sctp": 37,
        "total_sent_sctp_byte_size": 2060,
        "total_sent_sctp_chunk_abort": 0,
        "total_sent_sctp_chunk_asconf": 0,
        "total_sent_sctp_chunk_asconf_ack": 0,
        "total_sent_sctp_chunk_auth": 0,
        "total_sent_sctp_chunk_cookie_ack": 1,
        "total_sent_sctp_chunk_cookie_echo": 0,
        "total_sent_sctp_chunk_cwr": 0,
        "total_sent_sctp_chunk_data": 19,
        "total_sent_sctp_chunk_ecne": 0,
        "total_sent_sctp_chunk_error": 0,
        "total_sent_sctp_chunk_forward_tsn": 0,
        "total_sent_sctp_chunk_heartbeat": 2,
        "total_sent_sctp_chunk_heartbeat_ack": 0,
        "total_sent_sctp_chunk_i_data": 0,
        "total_sent_sctp_chunk_i_forward_tsn": 0,
        "total_sent_sctp_chunk_init": 0,
        "total_sent_sctp_chunk_init_ack": 1,
        "total_sent_sctp_chunk_pad": 0,
        "total_sent_sctp_chunk_reconfig": 0,
        "total_sent_sctp_chunk_sack": 14,
        "total_sent_sctp_chunk_shutdown": 0,
        "total_sent_sctp_chunk_shutdown_ack": 0,
        "total_sent_sctp_chunk_shutdown_complete": 0,
        "total_sent_sctp_chunk_unknown": 0,
        "total_sent_sctp_zero_checksum": 0
    },
    "signaling": {
        "total_received_signaling_pong": 0,
        "total_sent_signaling_ping": 0
    },
    "simulcast": {
        "r0": {
            "rtp": {
                "total_decrypt_skipped_srtp": 0,
                "total_received_rtp": 0,
                "total_received_rtp_byte_size": 0,
                "total_received_rtp_padding": 0,
                "total_received_rtp_padding_size": 0,
                "total_received_rtp_red": 0,
                "total_received_rtp_red_rtx": 0,
                "total_received_rtp_red_ulpfec": 0,
                "total_received_rtp_rtx": 0
            },
            "rtp_hdrext": {
                "total_received_rtp_hdrext_abs_send_time": 0,
                "total_received_rtp_hdrext_audio_level": 0,
                "total_received_rtp_hdrext_av1_rtp_sepc": 0,
                "total_received_rtp_hdrext_color_space": 0,
                "total_received_rtp_hdrext_inband_cn": 0,
                "total_received_rtp_hdrext_playout_delay": 0,
                "total_received_rtp_hdrext_sdes_mid": 0,
                "total_received_rtp_hdrext_sdes_repaired_rtp_stream_id": 0,
                "total_received_rtp_hdrext_sdes_rtp_stream_id": 0,
                "total_received_rtp_hdrext_toffset": 0,
                "total_received_rtp_hdrext_transport_wide_cc": 0,
                "total_received_rtp_hdrext_unknown": 0,
                "total_received_rtp_hdrext_video_content_type": 0,
                "total_received_rtp_hdrext_video_orientation": 0,
                "total_received_rtp_hdrext_video_timing": 0
            }
        },
        "r1": {
            "rtp": {
                "total_decrypt_skipped_srtp": 0,
                "total_received_rtp": 0,
                "total_received_rtp_byte_size": 0,
                "total_received_rtp_padding": 0,
                "total_received_rtp_padding_size": 0,
                "total_received_rtp_red": 0,
                "total_received_rtp_red_rtx": 0,
                "total_received_rtp_red_ulpfec": 0,
                "total_received_rtp_rtx": 0
            },
            "rtp_hdrext": {
                "total_received_rtp_hdrext_abs_send_time": 0,
                "total_received_rtp_hdrext_audio_level": 0,
                "total_received_rtp_hdrext_av1_rtp_sepc": 0,
                "total_received_rtp_hdrext_color_space": 0,
                "total_received_rtp_hdrext_inband_cn": 0,
                "total_received_rtp_hdrext_playout_delay": 0,
                "total_received_rtp_hdrext_sdes_mid": 0,
                "total_received_rtp_hdrext_sdes_repaired_rtp_stream_id": 0,
                "total_received_rtp_hdrext_sdes_rtp_stream_id": 0,
                "total_received_rtp_hdrext_toffset": 0,
                "total_received_rtp_hdrext_transport_wide_cc": 0,
                "total_received_rtp_hdrext_unknown": 0,
                "total_received_rtp_hdrext_video_content_type": 0,
                "total_received_rtp_hdrext_video_orientation": 0,
                "total_received_rtp_hdrext_video_timing": 0
            }
        },
        "r2": {
            "rtp": {
                "total_decrypt_skipped_srtp": 0,
                "total_received_rtp": 0,
                "total_received_rtp_byte_size": 0,
                "total_received_rtp_padding": 0,
                "total_received_rtp_padding_size": 0,
                "total_received_rtp_red": 0,
                "total_received_rtp_red_rtx": 0,
                "total_received_rtp_red_ulpfec": 0,
                "total_received_rtp_rtx": 0
            },
            "rtp_hdrext": {
                "total_received_rtp_hdrext_abs_send_time": 0,
                "total_received_rtp_hdrext_audio_level": 0,
                "total_received_rtp_hdrext_av1_rtp_sepc": 0,
                "total_received_rtp_hdrext_color_space": 0,
                "total_received_rtp_hdrext_inband_cn": 0,
                "total_received_rtp_hdrext_playout_delay": 0,
                "total_received_rtp_hdrext_sdes_mid": 0,
                "total_received_rtp_hdrext_sdes_repaired_rtp_stream_id": 0,
                "total_received_rtp_hdrext_sdes_rtp_stream_id": 0,
                "total_received_rtp_hdrext_toffset": 0,
                "total_received_rtp_hdrext_transport_wide_cc": 0,
                "total_received_rtp_hdrext_unknown": 0,
                "total_received_rtp_hdrext_video_content_type": 0,
                "total_received_rtp_hdrext_video_orientation": 0,
                "total_received_rtp_hdrext_video_timing": 0
            }
        }
    },
    "spotlight": {
        "total_spotlight_focus_failed": 0,
        "total_spotlight_unfocus_audio_no_room": 0,
        "total_spotlight_unfocus_audio_out_packet": 0,
        "total_spotlight_unfocus_audio_publish": 0
    },
    "ice_connection_state": {
      "total_checking_ack": 1,
      "total_checking_duration_ms": 7,
      "total_checking_req": 1,
      "total_checking_to_connected": 1,
      "total_checking_to_disconnected": 0,
      "total_connected_ack": 12,
      "total_connected_req": 12,
      "total_connected_to_checking": 0,
      "total_disconnected_ack": 0,
      "total_disconnected_duration_ms": 0,
      "total_disconnected_req": 0,
      "total_disconnected_to_checking": 0,
      "total_disconnected_to_failed": 0
    },
    "network_status": {
      "unstable_level": 0,
      "total_unstable_level0": 2,
      "total_unstable_level1": 0,
      "total_unstable_level2": 0,
      "total_unstable_level3": 0
    },
    "timestamp": "2021-11-30T01:59:51.372062Z",
    "turn": {
        "total_received_allocate_request": 7,
        "total_received_binding_request": 0,
        "total_received_channel_bind_request": 1,
        "total_received_channel_data": 5802,
        "total_received_create_permission_request": 1,
        "total_received_expired_channel_number": 0,
        "total_received_invalid_channel_data": 0,
        "total_received_refresh_request": 4,
        "total_received_send_indication": 3,
        "total_received_stun_invalid": 0,
        "total_received_stun_unknown": 0,
        "total_received_turn_binding_error": 0,
        "total_received_turn_binding_request": 29,
        "total_received_turn_binding_success": 28,
        "total_received_turn_invalid_stun": 0,
        "total_received_turn_unknown": 0,
        "total_received_turn_unknown_stun": 0,
        "total_received_unknown_channel_number": 0,
        "total_received_unknown_packet": 0,
        "total_sent_allocate_error": 2,
        "total_sent_allocate_success": 2,
        "total_sent_binding_error": 0,
        "total_sent_binding_success": 0,
        "total_sent_channel_bind_error": 0,
        "total_sent_channel_bind_success": 1,
        "total_sent_channel_data": 5644,
        "total_sent_create_permission_error": 0,
        "total_sent_create_permission_success": 1,
        "total_sent_data_indication": 2,
        "total_sent_refresh_error": 0,
        "total_sent_refresh_success": 3,
        "total_sent_turn_binding_error": 0,
        "total_sent_turn_binding_request": 28,
        "total_sent_turn_binding_success": 1,
        "total_sent_turn_unknown": 0
    }
}

GetStatsClient

x-sora-target:

Sora_20170529.GetStatsClient

指定したクライアントの統計情報を取得します。

キー	型
channel_id	string
client_id	string

$ http POST 127.0.0.1:3000/ \
    x-sora-target:Sora_20170529.GetStatsClient \
    channel_id=sora \
    client_id=82TKXKK1M15C76KTF192WVDSVC \
    -vvv
POST / HTTP/1.1
Accept: application/json, */*;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 65
Content-Type: application/json
Host: 127.0.0.1:3000
User-Agent: HTTPie/2.4.0
x-sora-target: Sora_20170529.GetStatsClient

{
    "channel_id": "sora",
    "client_id": "spam"
}


HTTP/1.1 200 OK
access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
access-control-allow-methods: POST, OPTIONS
access-control-allow-origin: http://127.0.0.1:5000
access-control-max-age: 1000
content-length: 10656
content-type: application/json
date: Tue, 30 Nov 2021 02:02:33 GMT
server: Cowboy

[
    {
        "channel_id": "sora",
        "session_id": "FDYSGDVQ592CK5D4ZMC0W4XXDM",
        "client_id": "spam",
        "bundle_id": "DDG3V4NZPH04V02NKDMY97993W",
        "connection_id": "DDG3V4NZPH04V02NKDMY97993W",
        ...
    },
    {
        "channel_id": "sora",
        "session_id": "FDYSGDVQ592CK5D4ZMC0W4XXDM",
        "client_id": "spam",
        "bundle_id": "1RKMMEA10923N96N88S1GEKGYR",
        "connection_id": "1RKMMEA10923N96N88S1GEKGYR",
        ...
    }
]

GetStatsAllConnections

x-sora-target:

Sora_20171101.GetStatsAllConnections

すべての接続の統計情報を取得します。

キー	型	デフォルト
local (オプション)	boolean	true

local はクラスター機能利用時に、全てのノードの情報を取得するかどうかを指定します。

$ http POST 127.0.0.1:3000/ \
    x-sora-target:Sora_20171101.GetStatsAllConnections -vvv
POST / HTTP/1.1
Accept: */*
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 0
Host: 127.0.0.1:3000
User-Agent: HTTPie/2.4.0
x-sora-target: Sora_20171101.GetStatsAllConnections



HTTP/1.1 200 OK
access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
access-control-allow-methods: POST, OPTIONS
access-control-allow-origin: http://127.0.0.1:5000
access-control-max-age: 1000
content-length: 32059
content-type: application/json
date: Tue, 30 Nov 2021 02:06:00 GMT
server: Cowboy

[
    {
        "channel_id": "sora",
        "session_id": "FDYSGDVQ592CK5D4ZMC0W4XXDM",
        "client_id": "spam",
        "bundle_id": "DDG3V4NZPH04V02NKDMY97993W",
        "connection_id": "DDG3V4NZPH04V02NKDMY97993W",
        ...
    },
    {
        "channel_id": "sora",
        "session_id": "FDYSGDVQ592CK5D4ZMC0W4XXDM",
        "client_id": "spam",
        "bundle_id: "1RKMMEA10923N96N88S1GEKGYR",
        "connection_id": "1RKMMEA10923N96N88S1GEKGYR",
        ...
    },
    {
        "channel_id": "zakuro",
        "session_id": "JJJ5BFH7QN6DQBTKSS7JA8ZYQR",
        "client_id": "EYYX5FGZN17VB647HGYZ27K8MM",
        "bundle_id": "EYYX5FGZN17VB647HGYZ27K8MM",
        "connection_id": "EYYX5FGZN17VB647HGYZ27K8MM",
        ...
    }
]

ライセンス API

現在利用しているライセンス情報の取得や、新しいライセンスの適用を行うための API です。

GetLicense

x-sora-target:

Sora_20171218.GetLicense

現在利用しているライセンス情報を取得します。

重要

signature は表示されません

$ http POST 127.0.0.1:3000/ \
    x-sora-target:Sora_20171218.GetLicense -vvv
POST / HTTP/1.1
Accept: */*
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 0
Host: 127.0.0.1:3000
User-Agent: HTTPie/0.9.9
x-sora-target: Sora_20171218.GetLicense



HTTP/1.1 200 OK
access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
access-control-allow-methods: POST, OPTIONS
access-control-allow-origin: http://127.0.0.1:5000
access-control-max-age: 1000
content-length: 174
content-type: application/json
date: Fri, 05 Jan 2018 06:41:35 GMT
server: Cowboy

{
    "expired_at": "2023-03",
    "max_connections": 100,
    "product_name": "Sora",
    "serial_code": "123ABC-SRA-E001-202303-100",
    "type": "Experimental"
}

UpdateLicense

x-sora-target:

Sora_20171218.UpdateLicense

ライセンスを更新します。

sora.conf の license_file に設定したファイルを新規のライセンスとして読み込みます。 ライセンスが壊れていたり、見つからない場合はエラーになります。 いずれの場合も接続中のクライアントへの影響はありません。

重要

signature は表示されません

$ http POST 127.0.0.1:3000/ \
    x-sora-target:Sora_20171218.UpdateLicense -vvv
POST / HTTP/1.1
Accept: */*
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 0
Host: 127.0.0.1:3000
User-Agent: HTTPie/0.9.9
x-sora-target: Sora_20171218.UpdateLicense



HTTP/1.1 200 OK
access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
access-control-allow-methods: POST, OPTIONS
access-control-allow-origin: http://127.0.0.1:5000
access-control-max-age: 1000
content-length: 379
content-type: application/json
date: Fri, 05 Jan 2018 06:44:47 GMT
server: Cowboy

{
    "new_license": {
        "expired_at": "2023-03",
        "max_connections": 100,
        "product_name": "Sora",
        "serial_code": "123ABC-SRA-E001-202303-100",
        "type": "Experimental"
    },
    "old_license": {
        "expired_at": "2024-03",
        "max_connections": 100,
        "product_name": "Sora",
        "serial_code": "123ABC-SRA-E002-202403-100",
        "type": "Experimental"
    }
}

モード API

モードの詳細については モード機能 をご確認ください。

ChangeMode

x-sora-target:

Sora_20211215.ChangeMode

Sora のモードを変更します。

キー	型
mode	string (normal | block_new_session | block_new_connection)

mode はすべての新規コネクションを受け入れる normal 、新規セッションの受け入れを停止する block_new_session と新規コネクションの受け入れを停止する block_new_connection が指定できます。

$ http POST 127.0.0.1:3000/ \
    x-sora-target:Sora_20211215.ChangeMode \
    mode=block_new_connection \
    -vvv
POST / HTTP/1.1
Accept: application/json, */*
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 32
Content-Type: application/json
Host: 127.0.0.1:3000
User-Agent: HTTPie/1.0.3
x-sora-target: Sora_20211215.ChangeMode

{
    "mode": "block_new_connection"
}

HTTP/1.1 200 OK
access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
access-control-allow-methods: POST, OPTIONS
access-control-allow-origin: http://127.0.0.1:5000
access-control-max-age: 1000
content-length: 31
content-type: application/json
date: Tue, 16 Nov 2021 09:36:35 GMT
server: Cowboy

{
    "mode": "block_new_connection"
}

GetMode

x-sora-target:

Sora_20211215.GetMode

Sora のモードを取得します。

$ http POST 127.0.0.1:3000/ \
    x-sora-target:Sora_20211215.GetMode \
    -vvv
POST / HTTP/1.1
Accept: */*
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 0
Host: 127.0.0.1:3000
User-Agent: HTTPie/1.0.3
x-sora-target: Sora_20211215.GetMode



HTTP/1.1 200 OK
access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
access-control-allow-methods: POST, OPTIONS
access-control-allow-origin: http://127.0.0.1:5000
access-control-max-age: 1000
content-length: 17
content-type: application/json
date: Tue, 16 Nov 2021 09:35:26 GMT
server: Cowboy

{
    "mode": "normal"
}

転送フィルター API

転送フィルター API はチャネル単位やコネクション単位で音声や映像の転送をフィルターする機能です。

ListForwardingFilters

x-sora-target:

Sora_20230628.ListForwardingFilters

指定したチャネルについて、チャネル単位とコネクション単位両方の転送フィルターを表示します。 また、blocked オプションの指定により音声と映像のブロック状況を表示します。

キー	型
channel_id	string
blocked (オプション)	boolean

• blocked を指定しない場合は false が指定されます

• version が指定されていフィルターに対しては version 項目が追加されます

• metadata が指定されているフィルターに対しては metadata 項目が追加されます

$ http POST 127.0.0.1:3000/ \
    x-sora-target:Sora_20230628.ListForwardingFilters \
    channel_id=sora \
    blocked:=true \
    -vvv

POST / HTTP/1.1
Accept: application/json
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 39
Content-Type: application/json
Host: 127.0.0.1:3000
User-Agent: HTTPie/2.6.0
x-sora-target: Sora_20230628.ListForwardingFilters

{
   "channel_id": "sora",
   "blocked": true
}


HTTP/1.1 200 OK
content-length: 712
content-type: application/json
date: Fri, 16 Jun 2023 02:36:06 GMT
server: Cowboy

{
   "channel_forwarding_filters": [
     {
       "action": "block",
       "name": "default",
       "priority": 32767,
       "rules": [
           [
             {
                 "field": "kind",
                 "operator": "is_in",
                 "values": [
                   "video",
                   "audio"
                 ]
             }
           ]
       ]
     }
   ],
   "channel_forwarding_filter": {
      "action": "block",
      "name": "default",
      "priority": 32767,
      "rules": [
         [
            {
               "field": "kind",
               "operator": "is_in",
               "values": [
                  "video",
                  "audio"
               ]
            }
         ]
      ]
   },
   "connection_forwarding_filters": [
      {
         "action": "allow",
         "name": "default",
         "priority": 32767,
         "connection_id": "6V9VANDZZH71HCQGVKBWKJ8GS0",
         "rules": [
            [
               {
                  "field": "kind",
                  "operator": "is_in",
                  "values": [
                     "video"
                  ]
               }
            ]
         ]
      },
      {
         "action": "allow",
         "name": "default",
         "priority": 32767,
         "connection_id": "XEDQM589M520Z50KM7C6C5PRB0",
         "rules": [
            [
               {
                  "field": "kind",
                  "operator": "is_in",
                  "values": [
                     "audio"
                  ]
               }
            ]
         ]
      }
   ],
   "blocked": [
      {
         "destination_connection_id": "6V9VANDZZH71HCQGVKBWKJ8GS0",
         "kind": "audio",
         "source_connection_id_list": [
            "ASJDFJ1PF94JN6DV59JQZ1HNDR"
         ]
      },
      {
         "destination_connection_id": "XEDQM589M520Z50KM7C6C5PRB0",
         "kind": "video",
         "source_connection_id_list": [
            "ASJDFJ1PF94JN6DV59JQZ1HNDR",
            "6V9VANDZZH71HCQGVKBWKJ8GS0"
         ]
      }
   ]
}

レスポンス

レスポンスの内容は以下の通りです。転送フィルターについての詳細は 転送フィルタールールの仕様 をご確認ください。

• channel_forwarding_filters

  • 指定したチャネルに設定されているチャネル単位の転送フィルターをリストで表示します

• channel_forwarding_filter

  • 指定したチャネルに設定されているチャネル単位の転送フィルターを表示します

  • この設定は 2025 年 12 月リリース予定の Sora にて廃止します

• connection_forwarding_filters

  • 指定したチャネルに設定されているコネクション単位の転送フィルターを配列で表示します

• blocked

  • destination_connection_id

    • ブロックされている送信先のコネクション ID

  • kind

    • ブロックされているメディア (audio または video)

  • source_connection_id_list

    • ブロックされている送信元のコネクション ID の配列

CreateChannelForwardingFilter

x-sora-target:

Sora_20230628.CreateChannelForwardingFilter

指定したチャネルに対して転送フィルターを作成します。 チャネル単位での転送フィルター作成は 送信元からの音声や映像を送信先に転送するかどうか です。 送信先はチャネルに参加しているすべてのコネクションです。

指定した送信先だけにブロックをさせたい場合は CreateConnectionForwardingFilter を使用してください。

転送フィルターの指定方法についての詳細は 転送フィルタールールの仕様 をご確認ください。

キー	型
channel_id	string
action (オプション)	string (block | allow)
rules	array of object
version (オプション)	string
metadata (オプション)	JSONValue
name (オプション)	string (最大 255 バイト)
priority (オプション)	integer (0-32767)

• action の指定がない場合は block が指定されます

• name と priority を指定することができます

  • 複数の転送フィルターを指定する場合は name と priority を指定する必要があります

• rules は転送フィルターの対象を配列で指定します。 rules で指定する array of object の object の内容は以下の通りです

キー	型
field	string (connection_id | client_id | kind)
operator	string (is_in | is_not_in)
values	array of string

$ http POST 127.0.0.1:3000/ \
    x-sora-target:Sora_20230628.CreateChannelForwardingFilter \
    channel_id=sora \
    action=block \
    rules:='[
      [
        {"field": "connection_id", "operator": "is_in", "values": ["XEDQM589M520Z50KM7C6C5PRB0"]},
        {"field": "client_id", "operator": "is_not_in", "values": ["screen-share"]},
        {"field": "kind", "operator": "is_in", "values": ["video"]}
      ]
    ]' \
    -vvv

POST / HTTP/1.1
Accept: application/json, */*;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 283
Content-Type: application/json
Host: 127.0.0.1:3000
User-Agent: HTTPie/3.2.1
x-sora-target: Sora_20230628.CreateChannelForwardingFilter

{
  "action": "block",
  "channel_id": "sora",
  "rules": [
    [
      {
        "field": "connection_id",
        "operator": "is_in",
        "values": [
          "XEDQM589M520Z50KM7C6C5PRB0"
        ]
      },
      {
        "field": "client_id",
        "operator": "is_not_in",
        "values": [
          "screen-share"
        ]
      },
      {
        "field": "kind",
        "operator": "is_in",
        "values": [
          "video"
        ]
      }
    ]
  ]
}


HTTP/1.1 200 OK
access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
access-control-allow-methods: POST, OPTIONS
access-control-allow-origin: *
access-control-max-age: 1000
content-length: 261
content-type: application/json
date: Thu, 22 Jun 2023 07:28:35 GMT
server: Cowboy

{
  "action": "block",
  "channel_id": "sora",
  "rules": [
    [
      {
        "field": "connection_id",
        "operator": "is_in",
        "values": [
          "XEDQM589M520Z50KM7C6C5PRB0"
        ]
      },
      {
        "field": "client_id",
        "operator": "is_not_in",
        "values": [
          "screen-share"
        ]
      },
      {
        "field": "kind",
        "operator": "is_in",
        "values": [
          "video"
        ]
      }
    ]
  ]
}

UpdateChannelForwardingFilter

x-sora-target:

Sora_20230628.UpdateChannelForwardingFilter

指定したチャネルの転送フィルターの設定を、 rules と action の内容で置き換えます。

注意

この API を実行するには事前に指定したチャネル単位の転送フィルターが作成されている必要があります

キー	型
channel_id	string
action (オプション)	string (block | allow)
rules	array of object
expected_version (オプション)	string
desired_version (オプション)	string
metadata (オプション)	JSONValue
name (オプション)	string (最大 255 バイト)
priority (オプション)	integer (0-32767)

• action の指定がない場合は block が指定されます

• name と priority を指定することができます

  • 指定しない場合は name には default 、priority には 32767 が指定されます

  • name と priority のどちらかだけを指定することはできません

  • 複数の転送フィルターを指定する場合は name と priority を指定する必要があります

• rules は転送フィルターの対象を配列で指定します。 rules で指定する array of object の object の内容は以下の通りです

キー	型
field	string (connection_id | client_id | kind)
operator	string (is_in | is_not_in)
values	array of string

$ http POST 127.0.0.1:3000/ \
    x-sora-target:Sora_20230628.UpdateChannelForwardingFilter \
    channel_id=sora \
    action=block \
    rules:='[
      [
        {"field": "connection_id", "operator": "is_in", "values": ["XEDQM589M520Z50KM7C6C5PRB0"]},
        {"field": "client_id", "operator": "is_not_in", "values": ["screen-share"]},
        {"field": "kind", "operator": "is_in", "values": ["video"]}
      ]
    ]' \
    -vvv

POST / HTTP/1.1
Accept: application/json, */*;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 283
Content-Type: application/json
Host: 127.0.0.1:3000
User-Agent: HTTPie/3.2.2
x-sora-target: Sora_20230628.UpdateChannelForwardingFilter

{
   "action": "block",
   "channel_id": "sora",
   "rules": [
      [
         {
            "field": "connection_id",
            "operator": "is_in",
            "values": [
               "XEDQM589M520Z50KM7C6C5PRB0"
            ]
         },
         {
            "field": "client_id",
            "operator": "is_not_in",
            "values": [
               "screen-share"
            ]
         },
         {
            "field": "kind",
            "operator": "is_in",
            "values": [
               "video"
            ]
         }
      ]
   ]
}


HTTP/1.1 200 OK
access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
access-control-allow-methods: POST, OPTIONS
access-control-allow-origin: *
access-control-max-age: 1000
content-length: 261
content-type: application/json
date: Thu, 22 Jun 2023 07:40:11 GMT
server: Cowboy

{
   "action": "block",
   "channel_id": "sora",
   "rules": [
      [
         {
            "field": "connection_id",
            "operator": "is_in",
            "values": [
               "XEDQM589M520Z50KM7C6C5PRB0"
            ]
         },
         {
            "field": "client_id",
            "operator": "is_not_in",
            "values": [
               "screen-share"
            ]
         },
         {
            "field": "kind",
            "operator": "is_in",
            "values": [
               "video"
            ]
         }
      ]
   ]
}

DeleteChannelForwardingFilter

x-sora-target:

Sora_20230628.DeleteChannelForwardingFilter

指定したチャネルの転送フィルターの設定を削除します。

注意

この API を実行するには事前に指定したチャネル単位の転送フィルターが作成されている必要があります

キー	型
channel_id	string
name (オプション)	string (最大 255 バイト)

• name はマルチ転送フィルター機能が有効になっている場合に指定します

$ http POST 127.0.0.1:3000/ \
    x-sora-target:Sora_20230628.DeleteChannelForwardingFilter \
    channel_id=sora \
    -vvv

POST / HTTP/1.1
Accept: application/json, */*;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 22
Content-Type: application/json
Host: 127.0.0.1:3000
User-Agent: HTTPie/3.2.2
x-sora-target: Sora_20230628.DeleteChannelForwardingFilter

{
   "channel_id": "sora"
}


HTTP/1.1 200 OK
access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
access-control-allow-methods: POST, OPTIONS
access-control-allow-origin: *
access-control-max-age: 1000
content-length: 21
content-type: application/json
date: Thu, 22 Jun 2023 07:48:10 GMT
server: Cowboy

{
   "channel_id": "sora"
}

CreateConnectionForwardingFilter

x-sora-target:

Sora_20230628.CreateConnectionForwardingFilter

指定したチャネルの特定コネクションに対して転送フィルターを作成します。

コネクション単位での転送フィルター作成は 指定したコネクションに送信元からの音声や映像を送信先に転送するかどうか です。 指定した送信先だけブロックをしたい場合に利用します。

転送フィルターの指定方法についての詳細は 転送フィルタールールの仕様 をご確認ください。

キー	型
channel_id	string
connection_id	string
action (オプション)	string (block | allow)
rules	array of object
version (オプション)	string
metadata (オプション)	JSONValue
name (オプション)	string
priority (オプション)	integer

• action の指定がない場合は block が指定されます

• name と priority を指定することができます

  • name と priority のどちらかだけを指定することはできません

  • 複数の転送フィルターを指定する場合は name と priority を指定する必要があります

  • 指定しない場合は name には default 、priority には 32767 が指定されます

• rules は転送フィルターの対象を配列で指定します。 rules で指定する array of object の object の内容は以下の通りです

キー	型
field	string (connection_id | client_id | kind)
operator	string (is_in | is_not_in)
values	array of string

$ http POST 127.0.0.1:3000/ \
    x-sora-target:Sora_20230628.CreateConnectionForwardingFilter \
    channel_id=sora \
    connection_id=EQ13WT731S1EK452YRJVFGYAY8 \
    action=block \
    rules:='[
      [
        {"field": "connection_id", "operator": "is_in", "values": ["XEDQM589M520Z50KM7C6C5PRB0"]},
        {"field": "client_id", "operator": "is_not_in", "values": ["screen-share"]},
        {"field": "kind", "operator": "is_in", "values": ["video"]}
      ]
    ]' \
    -vvv

POST / HTTP/1.1
Accept: application/json, */*;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 330
Content-Type: application/json
Host: 127.0.0.1:3000
User-Agent: HTTPie/3.2.2
x-sora-target: Sora_20230628.CreateConnectionForwardingFilter

{
  "action": "block",
  "channel_id": "sora",
  "connection_id": "EQ13WT731S1EK452YRJVFGYAY8",
  "rules": [
    [
      {
        "field": "connection_id",
        "operator": "is_in",
        "values": [
          "XEDQM589M520Z50KM7C6C5PRB0"
        ]
      },
      {
        "field": "client_id",
        "operator": "is_not_in",
        "values": [
          "screen-share"
        ]
      },
      {
        "field": "kind",
        "operator": "is_in",
        "values": [
          "video"
        ]
      }
    ]
  ]
}


HTTP/1.1 200 OK
access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
access-control-allow-methods: POST, OPTIONS
access-control-allow-origin: *
access-control-max-age: 1000
content-length: 306
content-type: application/json
date: Thu, 22 Jun 2023 07:50:04 GMT
server: Cowboy

{
  "action": "block",
  "channel_id": "sora",
  "connection_id": "EQ13WT731S1EK452YRJVFGYAY8",
  "rules": [
    [
      {
        "field": "connection_id",
        "operator": "is_in",
        "values": [
          "XEDQM589M520Z50KM7C6C5PRB0"
        ]
      },
      {
        "field": "client_id",
        "operator": "is_not_in",
        "values": [
          "screen-share"
        ]
      },
      {
        "field": "kind",
        "operator": "is_in",
        "values": [
          "video"
        ]
      }
    ]
  ]
}

UpdateConnectionForwardingFilter

x-sora-target:

Sora_20230628.UpdateConnectionForwardingFilter

指定したチャネルの特定コネクションに対する転送フィルターの設定を、 rules と action の内容で置き換えます。

注意

この API を実行するには事前に指定したコネクション単位の転送フィルターが作成されている必要があります

キー	型
channel_id	string
connection_id	string
action (オプション)	string (block | allow)
rules	array of object
expected_version (オプション)	string
desired_version (オプション)	string
metadata (オプション)	JSONValue
name (オプション)	string (最大 255 バイト)
priority (オプション)	integer (0-32767)

• action の指定がない場合は block が指定されます

• name と priority を指定することができます

  • name と priority のどちらかだけを指定することはできません

• rules は転送フィルターの対象を配列で指定します。 rules で指定する array of object の object の内容は以下の通りです

キー	型
field	string (connection_id | client_id | kind)
operator	string (is_in | is_not_in)
values	array of string
name (オプション)	string (最大 255 バイト)
priority (オプション)	integer (0-32767)

$ http POST 127.0.0.1:3000/ \
    x-sora-target:Sora_20230628.UpdateConnectionForwardingFilter \
    channel_id=sora \
    connection_id=T9J5FM3NTH6JH4JKFGTSHB1BA0 \
    action=block \
    rules:='[
      [
        {"field": "connection_id", "operator": "is_in", "values": ["XEDQM589M520Z50KM7C6C5PRB0"]},
        {"field": "client_id", "operator": "is_not_in", "values": ["screen-share"]},
        {"field": "kind", "operator": "is_in", "values": ["video"]}
      ]
    ]' \
   -vvv

POST / HTTP/1.1
Accept: application/json, */*;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 330
Content-Type: application/json
Host: 127.0.0.1:3000
User-Agent: HTTPie/3.2.2
x-sora-target: Sora_20230628.UpdateConnectionForwardingFilter

{
  "action": "block",
  "channel_id": "sora",
  "connection_id": "EQ13WT731S1EK452YRJVFGYAY8",
  "rules": [
    [
      {
        "field": "connection_id",
        "operator": "is_in",
        "values": [
          "XEDQM589M520Z50KM7C6C5PRB0"
        ]
      },
      {
        "field": "client_id",
        "operator": "is_not_in",
        "values": [
          "screen-share"
        ]
      },
      {
        "field": "kind",
        "operator": "is_in",
        "values": [
          "video"
        ]
      }
    ]
  ]
}


HTTP/1.1 200 OK
access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
access-control-allow-methods: POST, OPTIONS
access-control-allow-origin: *
access-control-max-age: 1000
content-length: 306
content-type: application/json
date: Thu, 22 Jun 2023 07:54:29 GMT
server: Cowboy

{
  "action": "block",
  "channel_id": "sora",
  "connection_id": "EQ13WT731S1EK452YRJVFGYAY8",
  "rules": [
    [
      {
        "field": "connection_id",
        "operator": "is_in",
        "values": [
          "XEDQM589M520Z50KM7C6C5PRB0"
        ]
      },
      {
        "field": "client_id",
        "operator": "is_not_in",
        "values": [
          "screen-share"
        ]
      },
      {
        "field": "kind",
        "operator": "is_in",
        "values": [
          "video"
        ]
      }
    ]
  ]
}

DeleteConnectionForwardingFilter

x-sora-target:

Sora_20230628.DeleteConnectionForwardingFilter

指定したチャネルの特定コネクションの転送フィルターを削除します。

注意

この API を実行するには事前に指定したコネクション単位の転送フィルターが作成されている必要があります

キー	型
channel_id	string
connection_id	string
name (オプション)	string (最大 255 バイト)

• name はマルチ転送フィルター機能が有効になっている場合に指定します

$ http POST 127.0.0.1:3000/ \
    x-sora-target:Sora_20230628.DeleteConnectionForwardingFilter \
    channel_id=sora \
    connection_id=T9J5FM3NTH6JH4JKFGTSHB1BA0 \
    -vvv

POST / HTTP/1.1
Accept: application/json, */*;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 69
Content-Type: application/json
Host: 127.0.0.1:3000
User-Agent: HTTPie/3.2.2
x-sora-target: Sora_20230628.DeleteConnectionForwardingFilter

{
  "channel_id": "sora",
  "connection_id": "EQ13WT731S1EK452YRJVFGYAY8"
}


HTTP/1.1 200 OK
access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
access-control-allow-methods: POST, OPTIONS
access-control-allow-origin: *
access-control-max-age: 1000
content-length: 66
content-type: application/json
date: Thu, 22 Jun 2023 07:57:39 GMT
server: Cowboy

{
  "channel_id": "sora",
  "connection_id": "EQ13WT731S1EK452YRJVFGYAY8"
}

音声ストリーミング API

StartAudioStreaming

x-sora-target:

Sora_20221221.StartAudioStreaming

セッションが存在し、音声ストリーミングが開始していないチャネルに対して音声ストリーミングを開始します。

キー	型
channel_id	string

$ http POST 127.0.0.1:3000/ x-sora-target:Sora_20221221.StartAudioStreaming \
    channel_id=sora \
    -vvv
POST / HTTP/1.1
Accept: application/json, */*;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 22
Content-Type: application/json
Host: 127.0.0.1:3000
User-Agent: HTTPie/2.6.0
x-sora-target: Sora_20221221.StartAudioStreaming
{
    "channel_id": "sora"
}


HTTP/1.1 200 OK
content-length: 43
content-type: application/json
date: Thu, 15 Dec 2022 06:21:40 GMT
server: Cowboy
{
    "session_id": "MPXNY180M175Z69YY9FZFJ0QWR"
}

StopAudioStreaming

x-sora-target:

Sora_20221221.StopAudioStreaming

セッションが存在し、音声ストリーミングが開始しているチャネルに対して音声ストリーミングを停止します。

キー	型
channel_id	string

$ http POST 127.0.0.1:3000/ x-sora-target:Sora_20221221.StopAudioStreaming \
    channel_id=sora \
    -vvv
POST / HTTP/1.1
Accept: application/json, */*;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 22
Content-Type: application/json
Host: 127.0.0.1:3000
User-Agent: HTTPie/2.6.0
x-sora-target: Sora_20221221.StopAudioStreaming

{
    "channel_id": "sora"
}


HTTP/1.1 200 OK
content-length: 43
content-type: application/json
date: Thu, 15 Dec 2022 06:21:58 GMT
server: Cowboy

{
    "session_id": "MPXNY180M175Z69YY9FZFJ0QWR"
}

SubscribeAudioStreamingResultPush

x-sora-target:

Sora_20221221.SubscribeAudioStreamingResultPush

音声ストリーミングサーバーからの戻り値のプッシュ通知を指定した接続が購読するよう設定します。

キー	型
channel_id	string
connection_id	string

$ http POST 127.0.0.1:3000/ x-sora-target:Sora_20221221.SubscribeAudioStreamingResultPush \
    channel_id=sora \
    connection_id=AT10T0WHH94PHEM3M5F45QFGRW \
    -vvv
POST / HTTP/1.1
Accept: application/json, */*;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 69
Content-Type: application/json
Host: 127.0.0.1:3000
User-Agent: HTTPie/2.6.0
x-sora-target: Sora_20221221.SubscribeAudioStreamingResultPush

{
    "channel_id": "sora",
    "connection_id": "AT10T0WHH94PHEM3M5F45QFGRW"
}


HTTP/1.1 200 OK
content-length: 66
content-type: application/json
date: Thu, 15 Dec 2022 06:26:32 GMT
server: Cowboy

{
    "channel_id": "sora",
    "connection_id": "AT10T0WHH94PHEM3M5F45QFGRW"
}

UnsubscribeAudioStreamingResultPush

x-sora-target:

Sora_20221221.UnsubscribeAudioStreamingResultPush

音声ストリーミングサーバーからの戻り値のプッシュ通知を指定した接続が購読しないよう設定します。

キー	型
channel_id	string
connection_id	string

$ http POST 127.0.0.1:3000/ x-sora-target:Sora_20221221.UnsubscribeAudioStreamingResultPush \
    channel_id=sora \
    connection_id=4D83B8APHS4JX03C8SZ3176SBM \
    -vvv
POST / HTTP/1.1
Accept: application/json, */*;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 69
Content-Type: application/json
Host: 127.0.0.1:3000
User-Agent: HTTPie/2.6.0
x-sora-target: Sora_20221221.UnsubscribeAudioStreamingResultPush

{
    "channel_id": "sora",
    "connection_id": "4D83B8APHS4JX03C8SZ3176SBM"
}


HTTP/1.1 200 OK
content-length: 66
content-type: application/json
date: Thu, 15 Dec 2022 06:28:22 GMT
server: Cowboy

{
    "channel_id": "sora",
    "connection_id": "4D83B8APHS4JX03C8SZ3176SBM"
}

ListAudioStreamingResultPushState

x-sora-target:

Sora_20230628.ListAudioStreamingResultPushState

指定したチャネルのセッションのコネクション毎のサブスクライブの状態を表示します。

キー	型
channel_id	string

$ http POST 127.0.0.1:3000/ x-sora-target:Sora_20230628.ListAudioStreamingResultPushState \
    channel_id=sora \
    -vvv
POST / HTTP/1.1
Accept: application/json, */*;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 22
Content-Type: application/json
Host: 127.0.0.1:3000
User-Agent: HTTPie/2.6.0
x-sora-target: Sora_20230628.ListAudioStreamingResultPushState

{
    "channel_id": "sora"
}


HTTP/1.1 200 OK
content-length: 195
content-type: application/json
date: Thu, 18 May 2023 02:30:34 GMT
server: Cowboy

[
  {
    "connection_id": "B2JPGFZPMD3H973Y811MF8ZZ70",
    "subscribe": true
  },
  {
    "connection_id": "KT116Z11KX5Y547KA1V12HW8PG",
    "subscribe": false
  },
  {
    "connection_id": "A5GYXGRYAX6590M3AFH7F9Z2H4",
    "subscribe": false
  }
]

実験的 API

概要

実験的 API とは、今後のアップデートで互換性を保証しない API です。

将来的には正式版としてリリースするか、または非推奨となり廃止するかのどちらかです。

その他の API

注意

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

ChangeUpstreamVideoBitRate

x-sora-target:

Sora_20190327.ChangeUpstreamVideoBitRate

指定した接続のビットレートを動的に変更します。

この API は片方向とマルチストリームでのみ利用できます。

主に role が sendonly の 配信ビットレート を動的に変更し固定することを目的としている API です。

注釈

これは接続後に映像ビットレートを強制的に変更する唯一の仕組みです。

キー	型
channel_id	string
connection_id	string
bit_rate	integer (1 - 30000)

$ http POST 127.0.0.1:3000/ x-sora-target:Sora_20190327.ChangeUpstreamVideoBitRate \
    channel_id=sora \
    connection_id=HMRVPQEXJX03D3B3WE778SJGRC \
    bit_rate:=300 \
    -vvv
POST / HTTP/1.1
Accept: application/json, */*
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 96
Content-Type: application/json
Host: 127.0.0.1:3000
User-Agent: HTTPie/1.0.2
x-sora-target: Sora_20190327.ChangeUpstreamVideoBitRate

{
    "bit_rate": 300,
    "channel_id": "sora",
    "connection_id": "HMRVPQEXJX03D3B3WE778SJGRC"
}

HTTP/1.1 200 OK
access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
access-control-allow-methods: POST, OPTIONS
access-control-allow-origin: http://127.0.0.1:5000
access-control-max-age: 1000
content-length: 91
content-type: application/json
date: Wed, 27 Mar 2020 08:38:03 GMT
server: Cowboy

{
    "bit_rate": 300,
    "channel_id": "sora",
    "connection_id": "HMRVPQEXJX03D3B3WE778SJGRC"
}

セッション API

注意

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

GetSession

x-sora-target:

Sora_20231220.GetSession

指定したチャネルのセッションを表示する API です。

キー	型
channel_id	string
session_id (オプション)	string

戻り値の項目はセッションウェブフック session.updated と同様です。

$ http POST 127.0.0.1:3000/ x-sora-target:Sora_20231220.GetSession \
    channel_id=sora \
    -vvv
POST / HTTP/1.1
Accept: application/json, */*
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 66
Content-Type: application/json
Host: 127.0.0.1:3000
User-Agent: HTTPie/2.6.0
x-sora-target: Sora_202312020.GetSession

{
  "channel_id": "sora"
}


HTTP/1.1 200 OK
content-length: 43
content-type: application/json
date: Tue, 23 May 2023 09:59:06 GMT
server: Cowboy

{
  "label": "WebRTC SFU Sora",
  "node_name": "[email protected]",
  "version": "2023.2.0",
  "channel_id": "sora",
  "session_id": "JJJ5BFH7QN6DQBTKSS7JA8ZYQR",
  "session_metadata":  {"spam": "egg"},
  "created_time": 1638337454,
  "created_timestamp": "2021-12-01T05:44:14.523736Z",
  "multistream": true,
  "spotlight": false,
  "max_connections": 4,
  "total_connections": 4,
  "external_signaling_url": "wss://node-01.example.com/signaling",
  "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: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": "JXMYW6GPX54EH0HGA5X4130FBM",
      "bundle_id": "JXMYW6GPX54EH0HGA5X4130FBM",
      "connection_id": "JXMYW6GPX54EH0HGA5X4130FBM",
      "connection_created_timestamp": "2021-12-01T05:44:23.051704Z",
      "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:23.051704Z",
      "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 }
    }
  ]
}

クラスターが有効な場合

connections 項目が含まれなくなります。

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

録画機能 (セッション単位) が有効な場合

recording 項目が含まれるようになります。

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

{
  "label": "WebRTC SFU Sora",
  "node_name": "[email protected]",
  "version": "2023.2.0",
  "channel_id": "sora",
  "session_id": "JJJ5BFH7QN6DQBTKSS7JA8ZYQR",
  "session_metadata":  {"spam": "egg"},
  "created_time": 1638337454,
  "created_timestamp": "2021-12-01T05:44:14.523736Z",
  "multistream": true,
  "spotlight": false,
  "max_connections": 4,
  "total_connections": 4,
  "external_signaling_url": "wss://node-01.example.com/signaling",
  "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",
    "format": "mp4"
  }
}

ListSessions

x-sora-target:

Sora_20231220.ListSessions

Sora の全てのセッションを表示する API です。

• 録画機能 (セッション単位) が有効な場合は "recording" 項目が追加されます

$ http POST 127.0.0.1:3000/ x-sora-target:Sora_20231220.ListSessions \
    -vvv
POST / HTTP/1.1
Accept: application/json, */*
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 66
Content-Type: application/json
Host: 127.0.0.1:3000
User-Agent: HTTPie/2.6.0
x-sora-target: Sora_202312020.ListSessions


HTTP/1.1 200 OK
content-length: 43
content-type: application/json
date: Tue, 23 May 2023 09:59:06 GMT
server: Cowboy

[
  {
    "label": "WebRTC SFU Sora",
    "node_name": "[email protected]",
    "version": "2023.2.0",
    "channel_id": "sora",
    "session_id": "JJJ5BFH7QN6DQBTKSS7JA8ZYQR",
    "session_metadata":  {"spam": "egg"},
    "created_time": 1638337454,
    "created_timestamp": "2021-12-01T05:44:14.523736Z",
    "multistream": true,
    "spotlight": false,
    "max_connections": 4,
    "total_connections": 4,
    "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: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": "JXMYW6GPX54EH0HGA5X4130FBM",
        "bundle_id": "JXMYW6GPX54EH0HGA5X4130FBM",
        "connection_id": "JXMYW6GPX54EH0HGA5X4130FBM",
        "connection_created_timestamp": "2021-12-01T05:44:23.051704Z",
        "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:23.051704Z",
        "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 }
      }
    ]
  },
  {
    "label": "WebRTC SFU Sora",
    "node_name": "[email protected]",
    "version": "2023.2.0",
    "channel_id": "sora",
    "session_id": "JJJ5BFH7QN6DQBTKSS7JA8ZYQR",
    "session_metadata":  {"spam": "egg"},
    "created_time": 1638337454,
    "created_timestamp": "2021-12-01T05:44:14.523736Z",
    "multistream": true,
    "spotlight": false,
    "max_connections": 4,
    "total_connections": 4,
    "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: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": "JXMYW6GPX54EH0HGA5X4130FBM",
        "bundle_id": "JXMYW6GPX54EH0HGA5X4130FBM",
        "connection_id": "JXMYW6GPX54EH0HGA5X4130FBM",
        "connection_created_timestamp": "2021-12-01T05:44:23.051704Z",
        "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 }
      }
    ],
    "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",
      "format": "webm"
    }
  }
]

クラスターが有効な場合

connections 項目が含まれなくなります。

[
  {
    "label": "WebRTC SFU Sora",
    "node_name": "[email protected]",
    "version": "2023.2.0",
    "channel_id": "sora",
    "session_id": "JJJ5BFH7QN6DQBTKSS7JA8ZYQR",
    "session_metadata":  {"spam": "egg"},
    "created_time": 1638337454,
    "created_timestamp": "2021-12-01T05:44:14.523736Z",
    "multistream": true,
    "spotlight": false,
    "max_connections": 4,
    "total_connections": 4,
    "external_signaling_url": "wss://node-01.example.com/signaling"
  },
  {
    "label": "WebRTC SFU Sora",
    "node_name": "[email protected]",
    "version": "2023.2.0",
    "channel_id": "sora",
    "session_id": "JJJ5BFH7QN6DQBTKSS7JA8ZYQR",
    "session_metadata":  {"spam": "egg"},
    "created_time": 1638337454,
    "created_timestamp": "2021-12-01T05:44:14.523736Z",
    "multistream": true,
    "spotlight": false,
    "max_connections": 4,
    "total_connections": 4,
    "external_signaling_url": "wss://node-01.example.com/signaling",
    "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",
      "format": "webm"
    }
  }
]

シグナリング API

注意

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

ListChannels

x-sora-target:

Sora_20201013.ListChannels

すべてのチャネル一覧を取得します。

キー	型	デフォルト
local (オプション)	boolean	true

local はクラスター機能利用時に、全てのノードの情報を取得するかどうかを指定します。

$ http POST 127.0.0.1:3000/ \
    x-sora-target:Sora_20201013.ListChannels \
    -vvv
POST / HTTP/1.1
Accept: */*
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 0
Host: 127.0.0.1:3000
User-Agent: HTTPie/2.2.0
x-sora-target: Sora_20201013.ListChannels



HTTP/1.1 200 OK
access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
access-control-allow-methods: POST, OPTIONS
access-control-allow-origin: http://127.0.0.1:5000
access-control-max-age: 1000
content-length: 120
content-type: application/json
date: Thu, 26 Nov 2020 04:16:17 GMT
server: Cowboy

[
    {
        "channel_id": "sora",
        "multistream": true,
        "spotlight": false
    },
    {
        "channel_id": "akane",
        "multistream": true,
        "spotlight": false
    }
]

RTP 転送 API

注意

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

指定したチャネル ID の配信している映像または音声の RTP を指定した IP アドレスとポートに送信します。

注意

• サイマルキャストの映像配信には対応していません

StartForwardingRtp

x-sora-target:

Sora_20170814.StartForwardingRtp

指定したチャネルの RTP の転送を開始します。

キー	型
channel_id	string
connection_id (オプション)	string
ip_address	string
audio_port	integer
video_port	integer

マルチストリームの音声や映像を転送する場合は connection_id を指定してください。

$ http POST 127.0.0.1:3000/ \
    x-sora-target:Sora_20170814.StartForwardingRtp \
    channel_id=sora \
    ip_address=127.0.0.1 \
    audio_port:=60001 \
    video_port:=60003 \
    -vvv

POST / HTTP/1.1
Accept: application/json
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 93
Content-Type: application/json
Host: 127.0.0.1:3000
User-Agent: HTTPie/0.9.2
x-sora-target: Sora_20170814.StartForwardingRtp

{
    "audio_port": 60001,
    "channel_id": "sora",
    "ip_address": "127.0.0.1",
    "video_port": 60003
}

HTTP/1.1 200 OK
access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
access-control-allow-methods: POST, OPTIONS
access-control-allow-origin: http://127.0.0.1:5000
access-control-max-age: 1000
content-length: 262
content-type: application/json
date: Wed, 30 Aug 2017 02:08:50 GMT
server: Cowboy

{
    "sdp": "v=0\r\no=- 0 0 IN IP4 0.0.0.0\r\ns=-\r\nt=0 0\r\nm=audio 60001 RTP/SAVPF 109\r\nc=IN IP4 127.0.0.1\r\na=rtpmap:109 opus/48000/2\r\nm=video 60003 RTP/SAVPF 120\r\nc=IN IP4 127.0.0.1\r\na=rtpmap:120 VP9/90000\r\na=fmtp:120 max-fs=12288;max-fr=60\r\n"
}

StopForwardingRtp

x-sora-target:

Sora_20170814.StopForwardingRtp

指定したチャネルの RTP の転送を停止します。

キー	型
channel_id	string
connection_id (オプション)	string

マルチストリームの音声や映像の転送を停止する場合は connection_id を指定してください。

$ http POST 127.0.0.1:3000/ \
    x-sora-target:Sora_20170814.StopForwardingRtp \
    channel_id=sora \
    -vvv

POST / HTTP/1.1
Accept: application/json, */*
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 22
Content-Type: application/json
Host: 127.0.0.1:3000
User-Agent: HTTPie/0.9.9
x-sora-target: Sora_20170814.StopForwardingRtp

{
    "channel_id": "sora"
}

HTTP/1.1 200 OK
access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
access-control-allow-methods: POST, OPTIONS
access-control-allow-origin: http://127.0.0.1:5000
access-control-max-age: 1000
content-length: 21
content-type: application/json
date: Fri, 25 Aug 2017 13:32:48 GMT
server: Cowboy

{
    "channel_id": "sora"
}

シグナリング通知メタデータ拡張 API

注意

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

ListSignalingNotifyMetadata

x-sora-target:

Sora_20201124.ListSignalingNotifyMetadata

指定したチャネルのすべての接続のメタデータをリストで返します。リストの中には connection_id と bundle_id と client_id と metadata をキーとしたオブジェクトがリストで入ってきます。順番保証はしません。

キー	型
channel_id	string

$ http POST 127.0.0.1:3000/ \
    x-sora-target:Sora_20201124.ListSignalingNotifyMetadata \
    channel_id=sora \
    -vvv
POST / HTTP/1.1
Accept: application/json, */*;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 22
Content-Type: application/json
Host: 127.0.0.1:3000
User-Agent: HTTPie/2.2.0
x-sora-target: Sora_20201124.ListSignalingNotifyMetadata

{
    "channel_id": "sora"
}

HTTP/1.1 200 OK
access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
access-control-allow-methods: POST, OPTIONS
access-control-allow-origin: http://127.0.0.1:5000
access-control-max-age: 1000
content-length: 111
content-type: application/json
date: Thu, 26 Nov 2020 03:45:25 GMT
server: Cowboy

[
    {
        "client_id": "V3Q452QQBD5TQ6ZQDMTEDKA07C",
        "bundle_id": "V3Q452QQBD5TQ6ZQDMTEDKA07C",
        "connection_id": "V3Q452QQBD5TQ6ZQDMTEDKA07C",
        "metadata": {
            "abc": 10
        }
    }
]

GetSignalingNotifyMetadata

x-sora-target:

Sora_20201124.GetSignalingNotifyMetadata

指定した接続のメタデータを取得します。

キー	型
channel_id	string
connection_id	string

$ http POST 127.0.0.1:3000/ \
    x-sora-target:Sora_20201124.GetSignalingNotifyMetadata \
    channel_id=sora \
    connection_id=0FQE5EA5YN3FS13P01QZ1JG8R0 \
    -vvv
POST / HTTP/1.1
Accept: application/json, */*;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 69
Content-Type: application/json
Host: 127.0.0.1:3000
User-Agent: HTTPie/2.2.0
x-sora-target: Sora_20201124.GetSignalingNotifyMetadata

{
    "channel_id": "sora",
    "connection_id": "0FQE5EA5YN3FS13P01QZ1JG8R0"
}

HTTP/1.1 200 OK
access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
access-control-allow-methods: POST, OPTIONS
access-control-allow-origin: http://127.0.0.1:5000
access-control-max-age: 1000
content-length: 13
content-type: application/json
date: Thu, 26 Nov 2020 03:48:44 GMT
server: Cowboy

{
    "abc": "efg"
}

PutSignalingNotifyMetadata

x-sora-target:

Sora_20201124.PutSignalingNotifyMetadata

指定した接続のメタデータを作成します。

キー	型
channel_id	string
connection_id	string
metadata	object
push (オプション)	boolean

指定した接続のメタデータを作成します。メタデータがすでにあった場合は更新します。 追加したあとのメタデータが値として返ってきます。

$ http POST 127.0.0.1:3000/ \
    x-sora-target:Sora_20201124.PutSignalingNotifyMetadata \
    channel_id=sora \
    connection_id=0FQE5EA5YN3FS13P01QZ1JG8R0 \
    metadata:='{"abc": "efg"}' \
    push:=true \
    -vvv
POST / HTTP/1.1
Accept: application/json, */*;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 97
Content-Type: application/json
Host: 127.0.0.1:3000
User-Agent: HTTPie/2.2.0
x-sora-target: Sora_20201124.PutSignalingNotifyMetadata

{
    "channel_id": "sora",
    "connection_id": "0FQE5EA5YN3FS13P01QZ1JG8R0",
    "metadata": {
        "abc": "efg"
    },
    "push": true
}

HTTP/1.1 200 OK
access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
access-control-allow-methods: POST, OPTIONS
access-control-allow-origin: http://127.0.0.1:5000
access-control-max-age: 1000
content-length: 13
content-type: application/json
date: Thu, 26 Nov 2020 03:47:52 GMT
server: Cowboy

{
    "abc": "efg"
}

push を有効にした場合は、そのチャネルのすべてのクライアントに以下のようなプッシュ通知が送られます。

{
    "type": "push",
    "data": {
        "action": "PutMetadata",
        "connection_id": "0FQE5EA5YN3FS13P01QZ1JG8R0",
        "metadata": {"abc": "efg"},
        "type": "signaling_notify_metadata_ext"
    }
}

• action

  • "PutMetadata" 固定

• connection_id

  • シグナリング通知メタデータの項目が変更された接続の ID

• metadata

  • 作成、または更新したメタデータ

DeleteSignalingNotifyMetadata

x-sora-target:

Sora_20201124.DeleteSignalingNotifyMetadata

指定した接続のメタデータを削除します。

キー	型
channel_id	string
connection_id	string
push (オプション)	boolean

指定した接続のメタデータを削除します。メタデータが空だったとしてもエラーにはなりません。 削除される まえ のメタデータが値として返ってきます。

$ http POST 127.0.0.1:3000/ \
    x-sora-target:Sora_20201124.DeleteSignalingNotifyMetadata \
    channel_id=sora \
    connection_id=0FQE5EA5YN3FS13P01QZ1JG8R0 \
    push:=true \
    -vvv
POST / HTTP/1.1
Accept: application/json, */*;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 69
Content-Type: application/json
Host: 127.0.0.1:3000
User-Agent: HTTPie/2.2.0
x-sora-target: Sora_20201124.DeleteSignalingNotifyMetadata

{
    "channel_id": "sora",
    "connection_id": "0FQE5EA5YN3FS13P01QZ1JG8R0",
    "push": true
}

HTTP/1.1 200 OK
access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
access-control-allow-methods: POST, OPTIONS
access-control-allow-origin: http://127.0.0.1:5000
access-control-max-age: 1000
content-length: 13
content-type: application/json
date: Thu, 26 Nov 2020 03:51:48 GMT
server: Cowboy

{
    "abc": "efg"
}

push を有効にした場合は、そのチャネルのすべてのクライアントに以下のようなプッシュ通知が送られます。

{
    "type": "push",
    "data": {
        "action": "DeleteMetadata",
        "connection_id": "0FQE5EA5YN3FS13P01QZ1JG8R0",
        "metadata": {"abc": "efg"},
        "type": "signaling_notify_metadata_ext"
    }
}

• action

  • "DeleteMetadata" 固定

• connection_id

  • シグナリング通知メタデータの項目が変更された接続の ID

• metadata

  • 削除したメタデータ

PutSignalingNotifyMetadataItem

x-sora-target:

Sora_20201124.PutSignalingNotifyMetadataItem

指定した接続のメタデータ項目を作成または更新します。

キー	型
channel_id	string
connection_id	string
key	string
value	json
push (オプション)	boolean

key/value で指定したメタデータ項目を追加します。その項目が既にあった場合は更新します。 追加したあとのメタデータが値として返ってきます。

$ http POST 127.0.0.1:3000/ \
    x-sora-target:Sora_20201124.PutSignalingNotifyMetadataItem \
    channel_id=sora \
    connection_id=0FQE5EA5YN3FS13P01QZ1JG8R0 \
    key=abc \
    value=efg \
    push:=true \
    -vvv
POST / HTTP/1.1
Accept: application/json, */*;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 99
Content-Type: application/json
Host: 127.0.0.1:3000
User-Agent: HTTPie/2.2.0
x-sora-target: Sora_20201124.PutSignalingNotifyMetadataItem

{
    "channel_id": "sora",
    "connection_id": "0FQE5EA5YN3FS13P01QZ1JG8R0",
    "key": "abc",
    "value": "efg",
    "push": true
}

HTTP/1.1 200 OK
access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
access-control-allow-methods: POST, OPTIONS
access-control-allow-origin: http://127.0.0.1:5000
access-control-max-age: 1000
content-length: 13
content-type: application/json
date: Thu, 26 Nov 2020 03:51:48 GMT
server: Cowboy

{
    "abc": "efg"
}

push を有効にした場合は、そのチャネルのすべてのクライアントに以下のようなプッシュ通知が送られます。

{
    "type": "push",
    "data": {
        "action": "PutMetadataItem",
        "connection_id": "0FQE5EA5YN3FS13P01QZ1JG8R0",
        "key": "abc",
        "value": "efg",
        "type": "signaling_notify_metadata_ext"
    }
}

• action

  • "PutMetadataItem" 固定

• connection_id

  • シグナリング通知メタデータの項目が変更された接続の ID

• key

  • シグナリング通知メタデータの項目が変更されたキー

• value

  • シグナリング通知メタデータの項目が変更されたバリュー

DeleteSignalingNotifyMetadataItem

x-sora-target:

Sora_20201124.DeleteSignalingNotifyMetadataItem

指定した接続のメタデータ項目を削除します。

キー	型
channel_id	string
connection_id	string
key	string
push (オプション)	boolean

key で指定したメタデータ項目を削除します。その項目がなかったとしてもエラーにはなりません。 削除された あと のメタデータが値として返ってきます。

もしその項目がなかった場合は現状のメタデータが値として返ってきます。

$ http POST 127.0.0.1:3000/ \
    x-sora-target:Sora_20201124.DeleteSignalingNotifyMetadataItem \
    channel_id=sora \
    connection_id=0FQE5EA5YN3FS13P01QZ1JG8R0 \
    key=abc \
    push:=true \
    -vvv
POST / HTTP/1.1
Accept: application/json, */*;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 97
Content-Type: application/json
Host: 127.0.0.1:3000
User-Agent: HTTPie/2.2.0
x-sora-target: Sora_20201124.DeleteSignalingNotifyMetadataItem

{
    "channel_id": "sora",
    "connection_id": "0FQE5EA5YN3FS13P01QZ1JG8R0",
    "key": "abc",
    "push": true
}

HTTP/1.1 200 OK
access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
access-control-allow-methods: POST, OPTIONS
access-control-allow-origin: http://127.0.0.1:5000
access-control-max-age: 1000
content-length: 2
content-type: application/json
date: Thu, 26 Nov 2020 03:54:50 GMT
server: Cowboy

{}

push を有効にした場合は、そのチャネルのすべてのクライアントに以下のようなプッシュ通知が送られます。

{
    "type": "push",
    "data": {
        "action": "DeleteMetadataItem",
        "connection_id": "0FQE5EA5YN3FS13P01QZ1JG8R0",
        "key": "abc",
        "type": "signaling_notify_metadata_ext"
    }
}

• action

  • "DeleteMetadataItem" 固定

• connection_id

  • シグナリング通知メタデータの項目が変更された接続の ID

• key

  • シグナリング通知メタデータの項目が変更されたキー

RTP ストリーム停止/再開 API

危険

この API は非推奨です。2025 年 12 月リリース予定の Sora にて廃止します。 今後は 転送フィルター をご利用ください。

PauseRtpStream

現時点では映像のみを停止します

x-sora-target:

Sora_20200401.PauseRtpStream

指定した接続からのストリームを停止します。

この API はマルチストリーム、サイマルキャスト、スポットライトで利用できます。

キー	型
channel_id	string
recv_connection_id	string
send_connection_id	string

• recv_connection_id

  • RTP ストリームの受信を停止する接続の connection_id を指定します

• send_connection_id

  • 受信を停止する RTP ストリームを配信している接続の connection_id を指定します

映像自体は Sora までは届いていますが、実際の配信が一時停止されるという仕組みになっています。

$ http POST 127.0.0.1:3000/ x-sora-target:Sora_20200401.PauseRtpStream \
      channel_id=sora \
      recv_connection_id=VTGYC92AZX6M72K860BPREFTMC \
      send_connection_id=3X0W1C23KS1TQAAYMKA9TXJS4G \
      -vvv
POST / HTTP/1.1
Accept: application/json, */*
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 121
Content-Type: application/json
Host: 127.0.0.1:3000
User-Agent: HTTPie/2.0.0
x-sora-target: Sora_20200401.PauseRtpStream

{
    "channel_id": "sora",
    "recv_connection_id": "VTGYC92AZX6M72K860BPREFTMC",
    "send_connection_id": "3X0W1C23KS1TQAAYMKA9TXJS4G"
}

HTTP/1.1 200 OK
access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
access-control-allow-methods: POST, OPTIONS
access-control-allow-origin: http://127.0.0.1:5000
access-control-max-age: 1000
content-length: 121
content-type: application/json
date: Thu, 16 Apr 2020 02:06:39 GMT
server: Cowboy

{
    "channel_id": "sora",
    "recv_connection_id": "VTGYC92AZX6M72K860BPREFTMC",
    "send_connection_id": "3X0W1C23KS1TQAAYMKA9TXJS4G"
}

ResumeRtpStream

x-sora-target:

Sora_20200401.ResumeRtpStream

指定した接続からのストリームを再開します。

この API はマルチストリーム、サイマルキャスト、スポットライトで利用できます。

キー	型
channel_id	string
recv_connection_id	string
send_connection_id	string

• recv_connection_id

  • RTP ストリームの受信を再開する接続の connection_id を指定します

• send_connection_id

  • 受信を停止している RTP ストリームを配信している接続の connection_id を指定します

$ http POST 127.0.0.1:3000/ x-sora-target:Sora_20200401.ResumeRtpStream \
      channel_id=sora \
      recv_connection_id=VTGYC92AZX6M72K860BPREFTMC \
      send_connection_id=3X0W1C23KS1TQAAYMKA9TXJS4G \
      -vvv
POST / HTTP/1.1
Accept: application/json, */*
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 121
Content-Type: application/json
Host: 127.0.0.1:3000
User-Agent: HTTPie/2.0.0
x-sora-target: Sora_20200401.ResumeRtpStream

{
    "channel_id": "sora",
    "recv_connection_id": "VTGYC92AZX6M72K860BPREFTMC",
    "send_connection_id": "3X0W1C23KS1TQAAYMKA9TXJS4G"
}

HTTP/1.1 200 OK
access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
access-control-allow-methods: POST, OPTIONS
access-control-allow-origin: http://127.0.0.1:5000
access-control-max-age: 1000
content-length: 121
content-type: application/json
date: Thu, 16 Apr 2020 02:07:27 GMT
server: Cowboy

{
    "channel_id": "sora",
    "recv_connection_id": "VTGYC92AZX6M72K860BPREFTMC",
    "send_connection_id": "3X0W1C23KS1TQAAYMKA9TXJS4G"
}

ListPauseRtpStreams

x-sora-target:

Sora_20200401.ListPauseRtpStreams

指定したチャネルの停止しているストリーム一覧を返します。

キー	型
channel_id	string

$ http POST 127.0.0.1:3000/ x-sora-target:Sora_20200401.ListPauseRtpStreams \
    channel_id=sora \
    -vvv
POST / HTTP/1.1
Accept: application/json, */*
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 22
Content-Type: application/json
Host: 127.0.0.1:3000
User-Agent: HTTPie/2.0.0
x-sora-target: Sora_20200401.ListPauseRtpStreams

{
    "channel_id": "sora"
}

HTTP/1.1 200 OK
access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
access-control-allow-methods: POST, OPTIONS
access-control-allow-origin: http://127.0.0.1:5000
access-control-max-age: 1000
content-length: 111
content-type: application/json
date: Thu, 09 Apr 2020 07:10:18 GMT
server: Cowboy

[
    {
        "channel_id": "sora",
        "recv_connection_id": "G8AN156DSD3DBBN4P15VJ74QRW",
        "role": "sendrecv",
        "send_connection_id": "47YZ3NYNRN2CS5MW2W8V28W6QW"
    }
]

統計 API

注意

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

GetStatsReport

x-sora-target:

Sora_20171010.GetStatsReport

Sora が起動している間の Sora 全体の統計情報を取得できます。 この統計情報は Sora を止めたり再起動したりすることでクリアされますので注意してください。

レスポンス項目

• version

  • sora のバージョン

• total_connection_created

  • 現在までの接続が作成された数

• total_connection_updated

  • 現在までの接続が更新された数

• total_connection_destroyed

  • 現在までの接続が破棄された数

• total_session_created

  • 現在までのセッションが作成された数

• total_session_destroyed

  • 現在までのセッションが破棄された数

• total_successful_connections

  • 現在までの接続が成功した数

• total_ongoing_connections

  • 現在接続している数

• total_failed_connections

  • 現在までの接続が失敗した数

• total_duration_sec

  • 現在までの合計接続時間 (秒)

• total_turn_udp_connections

  • 現在までの TURN-UDP での接続数

• total_turn_tcp_connections

  • 現在までの TURN-TCP または TURN-TLS での接続数

• total_received_invalid_turn_tcp_packet

  • 現在までの TURN-TCP でパースできないパケットが送られてきた数

• total_auth_webhook_allowed

  • 認証ウェブフックで許可された数

• total_auth_webhook_denied

  • 認証ウェブフックで拒否された数

• total_successful_auth_webhook

  • 認証ウェブフックが成功した数

• total_failed_auth_webhook

  • 認証ウェブフックが失敗した数

• total_successful_session_webhook

  • セッションウェブフックが成功した数

• total_failed_session_webhook

  • セッションウェブフックが失敗した数

• total_ignored_session_webhook

  • 無視されたセッションウェブフックの合計数

• total_successful_event_webhook

  • イベントウェブフックが成功した数

• total_failed_event_webhook

  • イベントウェブフックが失敗した数

• total_ignored_event_webhook

  • 無視されたイベントウェブフックの合計数

• total_successful_stats_webhook

  • 統計ウェブフックが成功した数

• total_failed_stats_webhook

  • 統計ウェブフックが失敗した数

• total_ignored_stats_webhook

  • 無視された統計ウェブフックの合計数

• average_duration_sec

  • 平均接続時間 (秒)

• average_setup_time_msec

  • 平均セットアップ時間 (ミリ秒)

  • セットアップ時間とはシグナリング接続開始から WebRTC が確立するまでにかかった時間です

• total_received_srtp

  • 受信した SRTP パケットの数

• total_received_srtp_byte_size

  • 受信した SRTP パケットのバイト数

• total_sent_srtp

  • 送信した SRTP パケットの数

• total_sent_srtp_byte_size

  • 送信した SRTP パケットのバイト数

  • Sora は暗号化したパケットは必ず送信します

• total_decrypted_srtp

  • 復号した SRTP パケットの数

  • Sora は誰も視聴していない音声や映像パケットを復号しません

• total_decrypted_srtp_byte_size

  • 復号した SRTP パケットのバイト数

• total_received_sctp

  • 受信した SCTP パケットの数

• total_received_sctp_byte_size

  • 受信した SCTP パケットのバイト数

• total_sent_sctp

  • 送信した SCTP パケットの数

• total_sent_sctp_byte_size

  • 送信した SCTP パケットのバイト数

• cluster

  • 現時点ではクラスター機能で採用している Raft Consensus Algorithm の情報です

  • raft_commit_index

    • Raft ノードが最後にコミットしたログのインデックス番号

  • raft_state

    • Raft ノードの現在の状態

  • raft_term

    • Raft ノードの現在の term

• cluster_relay

  • この統計データは厳密なデータではないため、参考程度にご利用ください

  • クラスターリレー機能が有効な場合この項目が追加されます

  • node_name

    • 対象ノード名

  • total_sent_byte_size

    • 対象ノードへリレー機能で送信したバイト数

  • total_received_byte_size

    • 対象ノードからリレー機能で受信したバイト数

  • total_sent

    • 対象ノードからリレー機能で送信したパケット数

  • total_received

    • 対象ノードからリレー機能で受信したパケット数

  • 対象ノードが削除された場合でも再起動されるまでは統計情報は残ります

ウェブフックの成功は 2xx 系が戻ってきておりかつ、JSON がある場合は JSON のパースに失敗しない場合です。 それ以外は失敗としています。

$ http POST 127.0.0.1:3000/ \
    x-sora-target:Sora_20171010.GetStatsReport \
    -vvv

POST / HTTP/1.1
Accept: */*
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 0
Host: 127.0.0.1:3000
User-Agent: HTTPie/3.2.2
x-sora-target: Sora_20171010.GetStatsReport



HTTP/1.1 200 OK
access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
access-control-allow-methods: POST, OPTIONS
access-control-allow-origin: http://127.0.0.1:5000
access-control-max-age: 1000
content-length: 172
content-type: application/json
date: Thu, 28 Mar 2024 05:24:12 GMT
server: Cowboy

{
    "average_duration_sec": 1450,
    "average_setup_time_msec": 879,
    "cluster": {
        "raft_commit_index": 28,
        "raft_state": "follower",
        "raft_term": 1
    },
    "cluster_relay": [
      {
        "node_name": "[email protected]",
        "total_sent_byte_size": 218930594,
        "total_received_byte_size": 219464372,
        "total_received": 264902,
        "total_sent": 265732
      },
      {
        "node_name": "[email protected]",
        "total_sent_byte_size": 218930594,
        "total_received_byte_size": 219794924,
        "total_received": 264782,
        "total_sent": 265732
      }
    ],
    "total_auth_webhook_allowed": 3,
    "total_auth_webhook_denied": 0,
    "total_connection_created": 3,
    "total_connection_destroyed": 2,
    "total_connection_updated": 48,
    "total_decrypted_srtp": 1792302,
    "total_decrypted_srtp_byte_size": 1533468254,
    "total_duration_sec": 2901,
    "total_failed_auth_webhook": 0,
    "total_failed_connections": 0,
    "total_failed_event_webhook": 0,
    "total_failed_session_webhook": 0,
    "total_failed_stats_webhook": 0,
    "total_ignored_event_webhook": 0,
    "total_ignored_session_webhook": 0,
    "total_ignored_stats_webhook": 0,
    "total_ongoing_connections": 1,
    "total_received_invalid_turn_tcp_packet": 38,
    "total_received_sctp": 0,
    "total_received_sctp_byte_size": 0,
    "total_received_srtp": 2640526,
    "total_received_srtp_byte_size": 2385140500,
    "total_sent_sctp": 0,
    "total_sent_sctp_byte_size": 0,
    "total_sent_srtp": 1369704,
    "total_sent_srtp_byte_size": 475699779,
    "total_session_created": 3,
    "total_session_destroyed": 2,
    "total_successful_auth_webhook": 3,
    "total_successful_connections": 3,
    "total_successful_event_webhook": 60,
    "total_successful_session_webhook": 5,
    "total_successful_stats_webhook": 5,
    "total_turn_tcp_connections": 0,
    "total_turn_udp_connections": 3,
    "version": "2024.1.0"
}

RTC 統計情報 API

注意

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

統計情報更新のタイミングについて

この統計情報は、クライアントからシグナリングで送信されてくる統計情報の最新の値を返します。 デフォルトでは WebSocket と DataChannel 経由のどちらも 60 秒間隔で更新されます。

間隔は以下で変更できます。

• websocket_stats_timer_interval

• data_channel_stats_timer_interval

ListRtcStats

x-sora-target:

Sora_20211215.ListRtcStats

すべてのユーザーエージェント統計情報の一覧を取得します。

キー	型	デフォルト
local (オプション)	boolean	true

local はクラスター機能利用時に、全てのノードの情報を取得するかどうかを指定します。

$ http POST 127.0.0.1:3000/ x-sora-target:Sora_20211215.ListRtcStats -vvv
POST / HTTP/1.1
Accept: */*
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 0
Host: 127.0.0.1:3000
User-Agent: HTTPie/2.4.0
x-sora-target: Sora_20211215.ListRtcStats



HTTP/1.1 200 OK
access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
access-control-allow-methods: POST, OPTIONS
access-control-allow-origin: http://127.0.0.1:5000
access-control-max-age: 1000
content-length: 30262
content-type: application/json
date: Sat, 13 Nov 2021 13:05:51 GMT
server: Cowboy

[
    {
        "channel_id": "sora",
        "connection_id": "FNRGZ8VFSN3R98DK7NBA38MFNR",
        "timestamp": "2021-11-13T13:05:33.264Z",
        "rtc_stats": [
            {
                "audioLevel": 0,
                "id": "RTCAudioSource_1",
                "kind": "audio",
                "timestamp": 1636808733258.573,
                "totalAudioEnergy": 0,
                "totalSamplesDuration": 90.08000000000918,
                "trackIdentifier": "222a181f-d0fe-4434-b7a1-a8e05e3abbb4",
                "type": "media-source"
            }, ...
        ]
    },
    {
        "channel_id": "zakuro",
        "connection_id": "X019KW3ZT95WZ6T15S6HHTM59C",
        "timestamp": "2021-11-13T13:05:44.044Z",
        "rtc_stats": [
            {
                "audioLevel": 0,
                "id": "RTCAudioSource_1",
                "kind": "audio",
                "timestamp": 1636808744029.488,
                "totalAudioEnergy": 0,
                "totalSamplesDuration": 31.070000000002057,
                "trackIdentifier": "9a84b996-d3ab-4cea-8131-04f96232dde5",
                "type": "media-source"
            }, ...
        ]
    }
]

ListChannelRtcStats

x-sora-target:

Sora_20211215.ListChannelRtcStats

指定したチャネルのユーザーエージェント統計情報の一覧を取得します。

キー	型
channel_id	string

$ http POST 127.0.0.1:3000/ x-sora-target:Sora_20211215.ListChannelRtcStats \
    channel_id=sora \
    -vvv
POST / HTTP/1.1
Accept: application/json, */*;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 22
Content-Type: application/json
Host: 127.0.0.1:3000
User-Agent: HTTPie/2.4.0
x-sora-target: Sora_20211215.ListChannelRtcStats

{
    "channel_id": "sora"
}


HTTP/1.1 200 OK
access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
access-control-allow-methods: POST, OPTIONS
access-control-allow-origin: http://127.0.0.1:5000
access-control-max-age: 1000
content-length: 30368
content-type: application/json
date: Sat, 13 Nov 2021 13:10:35 GMT
server: Cowboy

[
    {
        "channel_id": "sora",
        "connection_id": "1BW6V4P6A14MZ0W2HHXV3M8MCW",
        "timestamp": "2021-11-13T13:10:25.736Z",
        "rtc_stats": [
            {
                "audioLevel": 0,
                "id": "RTCAudioSource_1",
                "kind": "audio",
                "timestamp": 1636809025720.942,
                "totalAudioEnergy": 0,
                "totalSamplesDuration": 90.08000000000918,
                "trackIdentifier": "58c7f808-5b7f-4283-8816-0ac1f7d75387",
                "type": "media-source"
            }, ...
        ]
    },
    {
        "channel_id": "sora",
        "connection_id": "VDH8HN6X6S4MZF2FCQJF3Z4M8G",
        "timestamp": "2021-11-13T13:10:30.643Z",
        "rtc_stats": [
            {
                "audioLevel": 0,
                "id": "RTCAudioSource_1",
                "kind": "audio",
                "timestamp": 1636809030622.809,
                "totalAudioEnergy": 0,
                "totalSamplesDuration": 91.08000000000968,
                "trackIdentifier": "e6d3182d-706c-445f-9a91-c5951d55e000",
                "type": "media-source"
            }, ...
        ]
    }
]

GetRtcStats

x-sora-target:

Sora_20211215.GetRtcStats

指定した接続のユーザーエージェント統計情報を取得します。

キー	型
channel_id	string
connection_id	string

$ http POST 127.0.0.1:3000/ x-sora-target:Sora_20211215.GetRtcStats \
    channel_id=sora \
    connection_id=VDH8HN6X6S4MZF2FCQJF3Z4M8G \
    -vvv
POST / HTTP/1.1
Accept: application/json, */*;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 69
Content-Type: application/json
Host: 127.0.0.1:3000
User-Agent: HTTPie/2.4.0
x-sora-target: Sora_20211215.GetRtcStats

{
    "channel_id": "sora",
    "connection_id": "VDH8HN6X6S4MZF2FCQJF3Z4M8G"
}


HTTP/1.1 200 OK
access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
access-control-allow-methods: POST, OPTIONS
access-control-allow-origin: http://127.0.0.1:5000
access-control-max-age: 1000
content-length: 15181
content-type: application/json
date: Sat, 13 Nov 2021 13:11:46 GMT
server: Cowboy

{
    "channel_id": "sora",
    "connection_id": "VDH8HN6X6S4MZF2FCQJF3Z4M8G",
    "rtc_stats": [
        {
            "audioLevel": 0,
            "id": "RTCAudioSource_1",
            "kind": "audio",
            "timestamp": 1636809090624.392,
            "totalAudioEnergy": 0,
            "totalSamplesDuration": 151.08000000000757,
            "trackIdentifier": "e6d3182d-706c-445f-9a91-c5951d55e000",
            "type": "media-source"
        }, ...
    ],
    "timestamp": "2021-11-13T13:11:30.647Z"
}

非推奨 API

概要

非推奨 API は廃止日が設定されている API です。

基本的には以下のルールで廃止をしますが、例外はあります。不明点がある場合はサポートまでご連絡下さい。

• API が非推奨 API になった場合、代替 API がない場合は廃止までにすくなくとも 1 年以上の期間を設けます

• API が非推奨 API になった場合、代替 API がある場合は廃止までにすくなくとも 6 ヶ月以上の期間を設けます

レガシー録画 API

注意

レガシー録画機能 API は 2025 年 12 月リリースの Sora にて廃止します。 今後は 録画機能 (セッション単位) API をご利用ください。

ユーザーエージェント API

注意

ユーザーエージェント統計 API は 2025 年 6 月リリースの Sora にて廃止します。 今後は RTC 統計 API をご利用ください。

レガシー録画 API

注意

レガシー録画機能 API は 2025 年 12 月リリースの Sora にて廃止します。 今後は 録画機能 (セッション単位) API をご利用ください。

重要

レガシー録画機能と録画機能 (セッション単位) はチャネル単位で異なる仕組みを同時に利用できます。 例えば、channel_id a ではレガシー録画機能、channel_id b では録画機能（セッション単位）のように利用する事ができます。

録画されたファイルは sora.conf の archive_dir に指定したディレクトリに置かれます。

StartRecording

x-sora-target:

Sora_20161101.StartRecording

指定したチャネルの録画を開始します。

クラスター機能利用時には、クラスター内のどのノードで実行しても開始された録画情報はすべてのノードで共有されます。

キー	型
channel_id	string
expire_time	integer
split_duration (オプション)	integer
split_only (オプション)	boolean
metadata (オプション)	JSONValue

• expire_time の範囲は 0 から 86400 までで、秒数を指定してください

  • expire_time を 0 に指定した場合、録画の期限が無くなります

  • 指定できる最大値はデフォルトで 86400 で recording_max_expire_time に指定した値で変わります

• split_only は true か false を指定して下さい。指定しない場合は false が指定されます

• split_only を true に指定する場合は expire_time は 0 を指定する必要があります

• split_only を true に指定する場合は split_duration を指定する必要があります

• split_duration を指定する範囲は 1 から 86400 までで、秒数を指定して下さい

  • 指定できる最大値はデフォルトで 86400 で、 recording_max_split_duration に指定した値で変わります

• この metadata は recording.report ウェブフックやレポートファイルに含まれるようになります。

expire_time が 0

$ http POST 127.0.0.1:3000/ \
    x-sora-target:Sora_20161101.StartRecording \
    channel_id=sora \
    expire_time:=0 \
    -vvv
POST / HTTP/1.1
Accept: application/json, */*
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 41
Content-Type: application/json
Host: 127.0.0.1:3000
User-Agent: HTTPie/0.9.9
x-sora-target: Sora_20161101.StartRecording

{
    "channel_id": "sora",
    "expire_time": 0
}

HTTP/1.1 200 OK
access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
access-control-allow-methods: POST, OPTIONS
access-control-allow-origin: http://127.0.0.1:5000
access-control-max-age: 1000
content-length: 82
content-type: application/json
date: Wed, 19 Apr 2017 06:35:38 GMT
server: Cowboy

{
    "channel_id": "sora",
    "expire_time": 0,
    "recording_id": "C0YTCRZM715BKATBXWFPKTYGRM"
}

expire_time が 3600

$ http POST 127.0.0.1:3000/ \
    x-sora-target:Sora_20161101.StartRecording \
    channel_id=sora \
    expire_time:=3600 \
    -vvv
POST / HTTP/1.1
Accept: application/json, */*
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 43
Content-Type: application/json
Host: 127.0.0.1:3000
User-Agent: HTTPie/0.9.9
x-sora-target: Sora_20161101.StartRecording

{
    "channel_id": "sora",
    "expire_time": 3600
}

HTTP/1.1 200 OK
access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
access-control-allow-methods: POST, OPTIONS
access-control-allow-origin: http://127.0.0.1:5000
access-control-max-age: 1000
content-length: 84
content-type: application/json
date: Wed, 19 Apr 2017 06:37:08 GMT
server: Cowboy

{
    "channel_id": "sora",
    "expire_time": 3600,
    "recording_id": "C0YTCRZM715BKATBXWFPKTYGRM"
}

split_only が true

$ http POST 127.0.0.1:3000/ \
    x-sora-target:Sora_20161101.StartRecording \
    channel_id=sora \
    expire_time:=0 \
    split_duration:=3600 \
    split_only:=true \
    -vvv

POST / HTTP/1.1
Accept: application/json, */*;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 84
Content-Type: application/json
Host: 127.0.0.1:3000
User-Agent: HTTPie/2.2.0
x-sora-target: Sora_20161101.StartRecording

{
    "channel_id": "sora",
    "expire_time": 0,
    "split_duration": 3600,
    "split_only": true
}

HTTP/1.1 200 OK
access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
access-control-allow-methods: POST, OPTIONS
access-control-allow-origin: http://127.0.0.1:5000
access-control-max-age: 1000
content-length: 121
content-type: application/json
date: Fri, 04 Dec 2020 03:04:17 GMT
server: Cowboy

{
    "channel_id": "sora",
    "expire_time": 0,
    "recording_id": "MK4J54QBGS4ES0MCSZMF6C9M9M",
    "split_duration": 3600,
    "split_only": true
}

エラー

• "STARTED-RECORDING"

  • 指定したチャネル ID で、すでに録画が開始している

  $ http POST 127.0.0.1:3000/ \
          x-sora-target:Sora_20161101.StartRecording \
          channel_id=sora \
          expire_time:=3600 \
          -vvv
  POST / HTTP/1.1
  Accept: application/json, */*
  Accept-Encoding: gzip, deflate
  Connection: keep-alive
  Content-Length: 43
  Content-Type: application/json
  Host: 127.0.0.1:3000
  User-Agent: HTTPie/0.9.9
  x-sora-target: Sora_20161101.StartRecording
  
  {
      "channel_id": "sora",
      "expire_time": 3600
  }
  
  HTTP/1.1 400 Bad Request
  access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
  access-control-allow-methods: POST, OPTIONS
  access-control-allow-origin: http://127.0.0.1:5000
  access-control-max-age: 1000
  content-length: 34
  content-type: application/json
  date: Wed, 19 Apr 2017 06:44:58 GMT
  server: Cowboy
  
  {
      "error_type": "STARTED-RECORDING"
  }
  

• "NOT-CLUSTER-MAJORITY"

  • クラスターで過半数以下のグループに所属している

StopRecording

x-sora-target:

Sora_20161101.StopRecording

指定したチャネルの録画を停止します。

この API は非同期です。200 が返ってきた場合でも録画ファイルや録画メタデータファイルが生成されていることを保証しません。 イベントウェブフックの archive.available または recording.report の通知を利用してください。

キー	型
channel_id	string

$ http POST 127.0.0.1:3000/ \
    x-sora-target:Sora_20161101.StopRecording \
    channel_id=sora \
    -vvv
POST / HTTP/1.1
Accept: application/json
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 22
Content-Type: application/json
Host: 127.0.0.1:3000
User-Agent: HTTPie/0.9.4
x-sora-target: Sora_20161101.StopRecording

{
    "channel_id": "sora"
}

HTTP/1.1 200 OK
content-length: 21
content-type: application/json
date: Fri, 11 Nov 2016 14:29:14 GMT
server: Cowboy

{
    "channel_id": "sora"
}

エラー

• "NOT-STARTED-RECORDING"

  • 指定したチャネルの録画が開始されていない

• "NOT-CLUSTER-MAJORITY"

  • クラスターで過半数以下のグループに所属している

GetStartedRecording

x-sora-target:

Sora_20161101.GetStartedRecording

録画が有効かどうかを確認します。

キー	型
channel_id	string

$ http POST 127.0.0.1:3000/ \
    x-sora-target:Sora_20161101.GetStartedRecording \
    channel_id=sora \
    -vvv
POST / HTTP/1.1
Accept: application/json
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 22
Content-Type: application/json
Host: 127.0.0.1:3000
User-Agent: HTTPie/0.9.4
x-sora-target: Sora_20161101.GetStartedRecording

{
    "channel_id": "sora"
}

HTTP/1.1 200 OK
content-length: 88
content-type: application/json
date: Sat, 19 Nov 2016 13:03:24 GMT
server: Cowboy

{
    "channel_id": "sora",
    "expire_time": 3600,
    "expired_at": 1479563964,
    "created_at": 1479560364
}

エラー

• "NOT-STARTED-RECORDING"

  • 指定したチャネルの録画が開始されていない

  $ http POST 127.0.0.1:3000/ \
      x-sora-target:Sora_20161101.GetStartedRecording \
      channel_id=sora \
      -vvv
  POST / HTTP/1.1
  Accept: application/json
  Accept-Encoding: gzip, deflate
  Connection: keep-alive
  Content-Length: 22
  Content-Type: application/json
  Host: 127.0.0.1:3000
  User-Agent: HTTPie/0.9.4
  x-sora-target: Sora_20161101.GetStartedRecording
  
  {
      "channel_id": "sora"
  }
  
  HTTP/1.1 400 Bad Request
  content-length: 38
  content-type: application/json
  date: Sat, 19 Nov 2016 13:03:53 GMT
  server: Cowboy
  
  {
      "error_type": "NOT-STARTED-RECORDING"
  }
  

• "NOT-CLUSTER-MAJORITY"

  • クラスターで過半数以下のグループに所属している

ListStartedRecording

x-sora-target:

Sora_20161101.ListStartedRecording

録画が行われているチャネル一覧を取得します。

クラスター機能利用時には、クラスター内のどのノードで実行しても、クラスター内で有効な録画の一覧を取得できます。

$ http POST 127.0.0.1:3000/ \
    "x-sora-target:Sora_20161101.ListStartedRecording" \
    -vvv
POST / HTTP/1.1
Accept: */*
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 0
Host: 127.0.0.1:3000
User-Agent: HTTPie/2.4.0
x-sora-target: Sora_20161101.ListStartedRecording



HTTP/1.1 200 OK
access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
access-control-allow-methods: POST, OPTIONS
access-control-allow-origin: http://127.0.0.1:5000
access-control-max-age: 1000
content-length: 307
content-type: application/json
date: Tue, 30 Nov 2021 01:13:10 GMT
server: Cowboy

[
    {
        "channel_id": "sora",
        "created_at": 1638234656,
        "expire_time": 3600,
        "expired_at": 1638238256,
        "recording_id": "WWZ61PT4GS03F80F39MCPVSEQR",
        "split_only": false
    },
    {
        "channel_id": "zakuro",
        "created_at": 1638234654,
        "expire_time": 3600,
        "expired_at": 1638238254,
        "recording_id": "Z60BJP5YDN4PD0D7RGM4TFEE48",
        "split_only": false
    }
]

エラー

• "NOT-CLUSTER-MAJORITY"

  • クラスターで過半数以下のグループに所属している

ListArchiving

x-sora-target:

Sora_20161101.ListArchiving

現在録画中の状態を取得します。

注釈

クラスター機能利用時であっても、API を実行したノードで録画中の状態のみを取得します。 クラスター内で録画中のすべてを取得したい場合はすべてのノードに ListArchiving API を実行する必要があります。

$ http POST 127.0.0.1:3000/ \
    x-sora-target:Sora_20161101.ListArchiving \
    -vvv
POST / HTTP/1.1
Accept: */*
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 0
Host: 127.0.0.1:3000
User-Agent: HTTPie/1.0.2
x-sora-target: Sora_20161101.ListArchiving



HTTP/1.1 200 OK
access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
access-control-allow-methods: POST, OPTIONS
access-control-allow-origin: http://127.0.0.1:5000
access-control-max-age: 1000
content-length: 218
content-type: application/json
date: Mon, 15 Apr 2019 08:39:20 GMT
server: Cowboy

[
    {
        "audio": {
            "codec_type": "OPUS"
        },
        "channel_id": "sora",
        "client_id": "C0YTCRZM715BKATBXWFPKTYGRM",
        "bundle_id": "C0YTCRZM715BKATBXWFPKTYGRM",
        "connection_id": "C0YTCRZM715BKATBXWFPKTYGRM",
        "seconds": 146,
        "video": {
            "bit_rate": 1000,
            "codec_type": "VP9",
            "vp9_params": { "profile_id": 0 }
        }
    }
]

• seconds は録画を開始してからの経過時間(秒)です

• video が設定されていない場合は "video": false という値が入ってきます

• audio が設定されていない場合は "audio": false という値が入ってきます

ユーザーエージェント統計情報 API

注意

この API は 2025 年 6 月リリース予定の Sora にて廃止します。

注意

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

統計情報更新のタイミングについて

この統計情報は、クライアントからシグナリングで送信されてくる統計情報の最新の値を返します。 WebSocket と DataChannel 経由のどちらもデフォルトでは 60 秒間隔で更新されます。

間隔は以下で変更できます。

• websocket_stats_timer_interval

• data_channel_stats_timer_interval

ListUserAgentStats

x-sora-target:

Sora_20211215.ListUserAgentStats

すべてのユーザーエージェント統計情報の一覧を取得します。

キー	型	デフォルト
local (オプション)	boolean	true

local はクラスター機能利用時に、全てのノードの情報を取得するかどうかを指定します。

$ http POST 127.0.0.1:3000/ x-sora-target:Sora_20211215.ListUserAgentStats -vvv
POST / HTTP/1.1
Accept: */*
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 0
Host: 127.0.0.1:3000
User-Agent: HTTPie/2.4.0
x-sora-target: Sora_20211215.ListUserAgentStats



HTTP/1.1 200 OK
access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
access-control-allow-methods: POST, OPTIONS
access-control-allow-origin: http://127.0.0.1:5000
access-control-max-age: 1000
content-length: 30262
content-type: application/json
date: Sat, 13 Nov 2021 13:05:51 GMT
server: Cowboy

[
    {
        "channel_id": "sora",
        "connection_id": "FNRGZ8VFSN3R98DK7NBA38MFNR",
        "timestamp": "2021-11-13T13:05:33.264Z",
        "user_agent_stats": [
            {
                "audioLevel": 0,
                "id": "RTCAudioSource_1",
                "kind": "audio",
                "timestamp": 1636808733258.573,
                "totalAudioEnergy": 0,
                "totalSamplesDuration": 90.08000000000918,
                "trackIdentifier": "222a181f-d0fe-4434-b7a1-a8e05e3abbb4",
                "type": "media-source"
            }, ...
        ]
    },
    {
        "channel_id": "zakuro",
        "connection_id": "X019KW3ZT95WZ6T15S6HHTM59C",
        "timestamp": "2021-11-13T13:05:44.044Z",
        "user_agent_stats": [
            {
                "audioLevel": 0,
                "id": "RTCAudioSource_1",
                "kind": "audio",
                "timestamp": 1636808744029.488,
                "totalAudioEnergy": 0,
                "totalSamplesDuration": 31.070000000002057,
                "trackIdentifier": "9a84b996-d3ab-4cea-8131-04f96232dde5",
                "type": "media-source"
            }, ...
        ]
    }
]

ListChannelUserAgentStats

x-sora-target:

Sora_20211215.ListChannelUserAgentStats

指定したチャネルのユーザーエージェント統計情報の一覧を取得します。

キー	型
channel_id	string

$ http POST 127.0.0.1:3000/ x-sora-target:Sora_20211215.ListChannelUserAgentStats \
    channel_id=sora \
    -vvv
POST / HTTP/1.1
Accept: application/json, */*;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 22
Content-Type: application/json
Host: 127.0.0.1:3000
User-Agent: HTTPie/2.4.0
x-sora-target: Sora_20211215.ListChannelUserAgentStats

{
    "channel_id": "sora"
}


HTTP/1.1 200 OK
access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
access-control-allow-methods: POST, OPTIONS
access-control-allow-origin: http://127.0.0.1:5000
access-control-max-age: 1000
content-length: 30368
content-type: application/json
date: Sat, 13 Nov 2021 13:10:35 GMT
server: Cowboy

[
    {
        "channel_id": "sora",
        "connection_id": "1BW6V4P6A14MZ0W2HHXV3M8MCW",
        "timestamp": "2021-11-13T13:10:25.736Z",
        "user_agent_stats": [
            {
                "audioLevel": 0,
                "id": "RTCAudioSource_1",
                "kind": "audio",
                "timestamp": 1636809025720.942,
                "totalAudioEnergy": 0,
                "totalSamplesDuration": 90.08000000000918,
                "trackIdentifier": "58c7f808-5b7f-4283-8816-0ac1f7d75387",
                "type": "media-source"
            }, ...
        ]
    },
    {
        "channel_id": "sora",
        "connection_id": "VDH8HN6X6S4MZF2FCQJF3Z4M8G",
        "timestamp": "2021-11-13T13:10:30.643Z",
        "user_agent_stats": [
            {
                "audioLevel": 0,
                "id": "RTCAudioSource_1",
                "kind": "audio",
                "timestamp": 1636809030622.809,
                "totalAudioEnergy": 0,
                "totalSamplesDuration": 91.08000000000968,
                "trackIdentifier": "e6d3182d-706c-445f-9a91-c5951d55e000",
                "type": "media-source"
            }, ...
        ]
    }
]

GetUserAgentStats

x-sora-target:

Sora_20211215.GetUserAgentStats

指定した接続のユーザーエージェント統計情報を取得します。

キー	型
channel_id	string
connection_id	string

$ http POST 127.0.0.1:3000/ x-sora-target:Sora_20211215.GetUserAgentStats \
    channel_id=sora \
    connection_id=VDH8HN6X6S4MZF2FCQJF3Z4M8G \
    -vvv
POST / HTTP/1.1
Accept: application/json, */*;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 69
Content-Type: application/json
Host: 127.0.0.1:3000
User-Agent: HTTPie/2.4.0
x-sora-target: Sora_20211215.GetUserAgentStats

{
    "channel_id": "sora",
    "connection_id": "VDH8HN6X6S4MZF2FCQJF3Z4M8G"
}


HTTP/1.1 200 OK
access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
access-control-allow-methods: POST, OPTIONS
access-control-allow-origin: http://127.0.0.1:5000
access-control-max-age: 1000
content-length: 15181
content-type: application/json
date: Sat, 13 Nov 2021 13:11:46 GMT
server: Cowboy

{
    "channel_id": "sora",
    "connection_id": "VDH8HN6X6S4MZF2FCQJF3Z4M8G",
    "user_agent_stats": [
        {
            "audioLevel": 0,
            "id": "RTCAudioSource_1",
            "kind": "audio",
            "timestamp": 1636809090624.392,
            "totalAudioEnergy": 0,
            "totalSamplesDuration": 151.08000000000757,
            "trackIdentifier": "e6d3182d-706c-445f-9a91-c5951d55e000",
            "type": "media-source"
        }, ...
    ],
    "timestamp": "2021-11-13T13:11:30.647Z"
}

廃止 API

概要

廃止 API とはすでに廃止された API です。

廃止クラスター API

JoinCluster

危険

この API は廃止しました。

全く同じ機能をもつ RegisterClusterNode API を利用してください。

廃止:

2024 年 12 月リリースの Sora にて廃止

x-sora-target:

Sora_20211215.JoinCluster

指定したクラスターノードに参加します。

参加したいクラスターに属するノードのいずれかを contact_node_name で指定してください。 クラスターに属していれば、どのノードでもかまいません。

• 参加したいクラスターがすでに初期化されている必要があります。

• クラスターに参加するためには、参加したいクラスターの過半数のノードが正常に稼働している必要があります

注釈

新規にクラスターを作成する場合には、まず InitCluster API を使用してください。

キー	型
contact_node_name	string

$ http POST 127.0.0.1:3000/ x-sora-target:Sora_20211215.JoinCluster \
    contact_node_name=[email protected] \
    -vvv
POST / HTTP/1.1
Accept: application/json, */*
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 42
Content-Type: application/json
Host: 127.0.0.1:3000
User-Agent: HTTPie/1.0.3
x-sora-target: Sora_20211215.JoinCluster

{
    "contact_node_name": "[email protected]"
}

HTTP/1.1 200 OK
access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
access-control-allow-methods: POST, OPTIONS
access-control-allow-origin: http://127.0.0.1:5000
access-control-max-age: 1000
content-length: 116
content-type: application/json
date: Tue, 16 Nov 2021 09:28:11 GMT
server: Cowboy

{
    "node_name_list": [
        "[email protected]",
        "[email protected]",
        "[email protected]",
        "[email protected]",
        "[email protected]"
    ]
}

廃止 シグナリング API

ListAllConnections

危険

この API は廃止しました。

廃止:

2021 年 12 月リリースの Sora にて廃止

代替 API:

Sora_20201013.ListConnections

x-sora-target:

Sora_20151104.ListAllConnections

すべての接続一覧を取得します。

レスポンス項目

リスト

• role

• channel_id

• client_id

• connection_id

• multistream

• simulcast

• spotlight

$ http POST 127.0.0.1:3000/ \
    x-sora-target:Sora_20151104.ListAllConnections \
    -vvv
POST / HTTP/1.1
Accept: */*
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 0
Host: 127.0.0.1:3000
User-Agent: HTTPie/2.0.0
x-sora-target: Sora_20151104.ListAllConnections



HTTP/1.1 200 OK
access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
access-control-allow-methods: POST, OPTIONS
access-control-allow-origin: http://127.0.0.1:5000
access-control-max-age: 1000
content-length: 542
content-type: application/json
date: Fri, 12 Jun 2020 06:38:55 GMT
server: Cowboy

[
    {
        "channel_id": "sora",
        "client_id": "6DXMKHX8Q106K9YKN693C2D69C",
        "connection_id": "6DXMKHX8Q106K9YKN693C2D69C",
        "multistream": true,
        "role": "sendrecv",
        "simulcast": true,
        "spotlight": false
    },
    {
        "channel_id": "sora",
        "client_id": "QR3H6TYEA907B2HRDF6KCBGWYG",
        "connection_id": "QR3H6TYEA907B2HRDF6KCBGWYG",
        "multistream": true,
        "role": "sendrecv",
        "simulcast": true,
        "spotlight": false
    },
    {
        "channel_id": "sora1",
        "client_id": "K3VJGRFG614SV4RRF74QDEYHVC",
        "connection_id": "K3VJGRFG614SV4RRF74QDEYHVC",
        "multistream": true,
        "role": "sendrecv",
        "simulcast": true,
        "spotlight": false
    }
]

ListChannelClients

危険

この API は廃止しました。

廃止:

2021 年 12 月リリースの Sora にて廃止

代替 API:

Sora_20201013.ListChannelConnections

x-sora-target:

Sora_20170814.ListChannelClients

指定したチャネルのクライアント情報を取得します。

キー	型
channel_id	string

レスポンス項目

リスト

• role

• multistream

• channel_id

• client_id

• connection_id

• audio

• video

• minutes

  • 分単位での接続経過時間

• event_metadata

  • 認証時に認証サーバーから指定した event_metadata

$ http POST 127.0.0.1:3000/ \
    x-sora-target:Sora_20170814.ListChannelClients \
    channel_id=sora \
    -vvv
POST / HTTP/1.1
Accept: application/json, */*
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 22
Content-Type: application/json
Host: 127.0.0.1:3000
User-Agent: HTTPie/2.0.0
x-sora-target: Sora_20170814.ListChannelClients

{
    "channel_id": "sora"
}

HTTP/1.1 200 OK
access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
access-control-allow-methods: POST, OPTIONS
access-control-allow-origin: http://127.0.0.1:5000
access-control-max-age: 1000
content-length: 465
content-type: application/json
date: Fri, 12 Jun 2020 06:39:57 GMT
server: Cowboy

[
    {
        "audio": {
            "codec_type": "OPUS"
        },
        "channel_id": "sora",
        "client_id": "6DXMKHX8Q106K9YKN693C2D69C",
        "connection_id": "6DXMKHX8Q106K9YKN693C2D69C",
        "minutes": 2,
        "multistream": true,
        "role": "sendrecv",
        "video": {
            "bit_rate": 3000,
            "codec_type": "VP8"
        }
    },
    {
        "audio": {
            "codec_type": "OPUS"
        },
        "channel_id": "sora",
        "client_id": "QR3H6TYEA907B2HRDF6KCBGWYG",
        "connection_id": "QR3H6TYEA907B2HRDF6KCBGWYG",
        "minutes": 2,
        "multistream": true,
        "role": "sendrecv",
        "video": {
            "bit_rate": 3000,
            "codec_type": "VP8"
        }
    }
]

DisconnectChannelUpstream

危険

この API は廃止しました。

廃止:

2021 年 6 月リリースの Sora にて廃止

代替 API:

20201013.DisconnectChannelByRole

x-sora-target:

Sora_20151104.DisconnectChannelUpstream

指定したチャネルすべての配信者の接続を切断します。

キー	型
channel_id	string
reason (オプション)	object

reason に値を指定した場合、イベントウェブフック connection.destroyed の reason に指定した値が入ってきます。

$ http POST 127.0.0.1:3000 \
    x-sora-target:Sora_20151104.DisconnectChannelUpstream \
    channel_id=sora \
    -vvv
POST / HTTP/1.1
Accept: application/json
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 22
Content-Type: application/json
Host: 127.0.0.1:3000
User-Agent: HTTPie/0.9.3
x-sora-target: Sora_20151104.DisconnectChannelUpstream

{
    "channel_id": "sora"
}

HTTP/1.1 200 OK
content-length: 0
content-type: application/json
date: Sun, 24 Jul 2016 06:04:53 GMT
server: Cowboy

DisconnectChannelDownstream

危険

この API は廃止しました。

廃止:

2021 年 6 月リリースの Sora にて廃止

代替 API:

20201013.DisconnectChannelByRole

x-sora-target:

Sora_20151104.DisconnectChannelDownstream

指定したチャネルすべての視聴者の接続を切断します。

キー	型
channel_id	string
reason (オプション)	object

reason に値を指定した場合、イベントウェブフック connection.destroyed の reason に指定した値が入ってきます。

$ http POST 127.0.0.1:3000 \
    x-sora-target:Sora_20151104.DisconnectChannelDownstream \
    channel_id=sora \
    -vvv
POST / HTTP/1.1
Accept: application/json
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 22
Content-Type: application/json
Host: 127.0.0.1:3000
User-Agent: HTTPie/0.9.3
x-sora-target: Sora_20151104.DisconnectChannelDownstream

{
    "channel_id": "sora"
}

HTTP/1.1 200 OK
content-length: 0
content-type: application/json
date: Sun, 24 Jul 2016 06:04:53 GMT
server: Cowboy

Disconnect

危険

この API は廃止しました。

警告

sora.conf にて allow_client_id_assignment を true にしていた場合はこの API は利用できません

廃止:

2021 年 6 月リリースの Sora にて廃止

代替 API:

Sora_20151104.DisconnectClient

x-sora-target:

Sora_20151104.Disconnect

指定したクライアント ID の接続を切断する

キー	型
channel_id	string
client_id	string
reason (オプション)	object

reason に値を指定した場合、イベントウェブフック connection.destroyed の reason に指定した値が入ってきます。

$ http POST 127.0.0.1:3000/ \
    x-sora-target:Sora_20151104.Disconnect \
    channel_id=sora \
    client_id=HMRVPQEXJX03D3B3WE778SJGRC \
    -vvv
POST / HTTP/1.1
Accept: application/json
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 75
Content-Type: application/json
Host: 127.0.0.1:3000
User-Agent: HTTPie/0.9.3
x-sora-target: Sora_20151104.Disconnect

{
    "channel_id": "sora",
    "client_id": "HMRVPQEXJX03D3B3WE778SJGRC"
}

HTTP/1.1 200 OK
content-length: 0
content-type: application/json
date: Sun, 29 May 2020 05:13:20 GMT
server: Cowboy

ListConnections

危険

この API は廃止しました。

廃止:

2021 年 6 月リリースの Sora にて廃止

代替 API:

Sora_20201013.ListChannelConnections

x-sora-target:

Sora_20151104.ListConnections

指定したチャネルの接続一覧を取得します。

キー	型
channel_id	string

$ http POST 127.0.0.1:3000/ \
    x-sora-target:Sora_20151104.ListConnections \
    channel_id=sora \
    -vvv
POST / HTTP/1.1
Accept: application/json, */*
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 22
Content-Type: application/json
Host: 127.0.0.1:3000
User-Agent: HTTPie/2.0.0
x-sora-target: Sora_20151104.ListConnections

{
    "channel_id": "sora"
}

HTTP/1.1 200 OK
access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
access-control-allow-methods: POST, OPTIONS
access-control-allow-origin: http://127.0.0.1:5000
access-control-max-age: 1000
content-length: 361
content-type: application/json
date: Fri, 12 Jun 2020 06:37:58 GMT
server: Cowboy

[
    {
        "channel_id": "sora",
        "client_id": "6DXMKHX8Q106K9YKN693C2D69C",
        "connection_id": "6DXMKHX8Q106K9YKN693C2D69C",
        "multistream": true,
        "role": "sendrecv",
        "simulcast": true,
        "spotlight": false
    },
    {
        "channel_id": "sora",
        "client_id": "QR3H6TYEA907B2HRDF6KCBGWYG",
        "connection_id": "QR3H6TYEA907B2HRDF6KCBGWYG",
        "multistream": true,
        "role": "sendrecv",
        "simulcast": true,
        "spotlight": false
    }
]

廃止 サイマルキャスト API

ChangeSimulcastQuality

危険

この API は廃止しました。

廃止:

2021 年 6 月リリースの Sora にて廃止

代替 API:

Sora_20201005.RequestRtpStream

x-sora-target:

Sora_20180820.ChangeSimulcastQuality

指定した参加者の視聴する映像の画質を変更する

キー	型
channel_id	string
connection_id	string
stream_id (オプション)	string
quality	string (high | middle | low)

$ http POST 127.0.0.1:3000/ \
    x-sora-target:Sora_20180820.ChangeSimulcastQuality \
    channel_id=sora \
    connection_id=KD9N57E2RN5T1BDEA7S7SH038M \
    quality=high \
    -vvv
POST / HTTP/1.1
Accept: application/json, */*
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 98
Content-Type: application/json
Host: 127.0.0.1:3000
User-Agent: HTTPie/1.0.2
x-sora-target: Sora_20180820.ChangeSimulcastQuality

{
    "channel_id": "sora",
    "connection_id": "KD9N57E2RN5T1BDEA7S7SH038M",
    "quality": "high"
}

HTTP/1.1 200 OK
access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
access-control-allow-methods: POST, OPTIONS
access-control-allow-origin: http://127.0.0.1:5000
access-control-max-age: 1000
content-length: 93
content-type: application/json
date: Thu, 04 Apr 2019 05:36:44 GMT
server: Cowboy

{
    "channel_id": "sora",
    "connection_id": "KD9N57E2RN5T1BDEA7S7SH038M",
    "quality": "high"
}

廃止 統計 API

GetStats

危険

この API は廃止しました。

警告

sora.conf にて allow_client_id_assignment を true にしていた場合はこの API は利用できません

廃止:

2021 年 6 月リリースの Sora にて廃止

x-sora-target:

Sora_20170529.GetStats

指定したクライアントの統計情報を取得します。

キー	型
channel_id	string
client_id	string

$ http POST 127.0.0.1:3000/ \
    x-sora-target:Sora_20170529.GetStats \
    channel_id=sora \
    client_id=WZXPMM6K8113K83VB8G9XZDTFW -vvv

POST / HTTP/1.1
Accept: application/json, */*
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 65
Content-Type: application/json
Host: 127.0.0.1:3000
User-Agent: HTTPie/2.0.0
x-sora-target: Sora_20170529.GetStats

{
    "channel_id": "sora",
    "client_id": "WZXPMM6K8113K83VB8G9XZDTFW"
}

HTTP/1.1 200 OK
access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
access-control-allow-methods: POST, OPTIONS
access-control-allow-origin: http://127.0.0.1:5000
access-control-max-age: 1000
content-length: 2770
content-type: application/json
date: Tue, 09 Jun 2020 05:42:39 GMT
server: Cowboy

{
    "channel_id": "sora",
    "client_id": "WZXPMM6K8113K83VB8G9XZDTFW",
    "connection_id": "WZXPMM6K8113K83VB8G9XZDTFW",
    "dtls": {
        "total_received_dtls": 2,
        "total_sent_dtls": 2
    },
    "network_status": {
        "unstable_level": 0
    },
    "packet_loss_simulator": {
        "total_dropped_received_rtp": 0,
        "total_dropped_sent_rtp": 0
    },
    "rtp": {
        "total_generic_nack_cache_hit": 0,
        "total_generic_nack_cache_miss": 0,
        "total_pli_trigger": 0,
        "total_received": 1105,
        "total_received_byte_size": 845972,
        "total_received_rtcp": 20,
        "total_received_rtcp_bye": 0,
        "total_received_rtcp_byte_size": 1304,
        "total_received_rtcp_psfb_afb": 0,
        "total_received_rtcp_psfb_fir": 0,
        "total_received_rtcp_psfb_pli": 0,
        "total_received_rtcp_rr": 2,
        "total_received_rtcp_rtpfb_generic_nack": 0,
        "total_received_rtcp_rtpfb_tmmbn": 0,
        "total_received_rtcp_rtpfb_tmmbr": 0,
        "total_received_rtcp_rtpfb_transport_wide": 0,
        "total_received_rtcp_sdes": 18,
        "total_received_rtcp_sr": 18,
        "total_received_rtcp_unknown": 0,
        "total_received_rtcp_xr": 0,
        "total_received_rtp": 1085,
        "total_received_rtp_byte_size": 844668,
        "total_received_rtp_red": 0,
        "total_received_rtp_red_rtx": 0,
        "total_received_rtp_red_ulpfec": 0,
        "total_received_rtp_rtx": 0,
        "total_sent": 9,
        "total_sent_byte_size": 606,
        "total_sent_rtcp": 9,
        "total_sent_rtcp_bye": 0,
        "total_sent_rtcp_byte_size": 606,
        "total_sent_rtcp_psfb_afb": 8,
        "total_sent_rtcp_psfb_fir": 0,
        "total_sent_rtcp_psfb_pli": 0,
        "total_sent_rtcp_rr": 9,
        "total_sent_rtcp_rtpfb_generic_nack": 0,
        "total_sent_rtcp_rtpfb_tmmbn": 0,
        "total_sent_rtcp_rtpfb_tmmbr": 0,
        "total_sent_rtcp_rtpfb_transport_wide": 0,
        "total_sent_rtcp_sdes": 0,
        "total_sent_rtcp_sr": 0,
        "total_sent_rtcp_unknown": 0,
        "total_sent_rtcp_xr": 0,
        "total_sent_rtp": 0,
        "total_sent_rtp_byte_size": 0
    },
    "timestamp": "2020-06-09T05:42:40Z",
    "turn": {
        "total_received_allocate_request": 11,
        "total_received_binding_request": 0,
        "total_received_channel_bind_request": 1,
        "total_received_channel_data": 1113,
        "total_received_create_permission_request": 2,
        "total_received_expired_channel_number": 0,
        "total_received_refresh_request": 0,
        "total_received_send_indication": 7,
        "total_received_turn_binding_error": 0,
        "total_received_turn_binding_request": 7,
        "total_received_turn_binding_success": 6,
        "total_received_turn_invalid_stun": 0,
        "total_received_turn_unknown": 0,
        "total_received_turn_unknown_stun": 0,
        "total_received_unknown_channel_number": 0,
        "total_sent_allocate_error": 7,
        "total_sent_allocate_success": 2,
        "total_sent_binding_error": 0,
        "total_sent_binding_success": 0,
        "total_sent_channel_bind_error": 0,
        "total_sent_channel_bind_success": 1,
        "total_sent_channel_data": 19,
        "total_sent_create_permission_error": 0,
        "total_sent_create_permission_success": 2,
        "total_sent_data_indication": 5,
        "total_sent_refresh_error": 0,
        "total_sent_refresh_success": 0,
        "total_sent_turn_binding_error": 0,
        "total_sent_turn_binding_request": 6,
        "total_sent_turn_binding_success": 2,
        "total_sent_turn_unknown": 0
    }
}

廃止 プッシュ API

PushUpstream

危険

この API は廃止しました。

廃止:

2021 年 6 月リリースの Sora にて廃止

代替 API:

Sora_20201120.PushChannelByRole

x-sora-target:

Sora_20160711.PushUpstream

指定したチャネルの配信クライアントにプッシュ通知を送ります。

キー	型
channel_id	string
data	object

$ http POST 127.0.0.1:3000/ \
    x-sora-target:Sora_20160711.PushUpstream \
    channel_id=sora \
    data:="{\"spam\": \"egg\"}" \
    -vvv
POST / HTTP/1.1
Accept: application/json
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 47
Content-Type: application/json
Host: 127.0.0.1:3000
User-Agent: HTTPie/0.9.4
x-sora-target: Sora_20160711.PushUpstream

{
    "channel_id": "sora",
    "data": {
        "spam": "egg"
    }
}

HTTP/1.1 200 OK
t-length: 37
content-type: application/json
date: Sun, 24 Jul 2016 06:29:08 GMT
server: Cowboy

{
    "data": {
        "spam": "egg"
    },
    "type": "push"
}

PushDownstream

危険

この API は廃止しました。

廃止:

2021 年 6 月リリースの Sora にて廃止

代替 API:

Sora_20201120.PushChannelByRole

x-sora-target:

Sora_20160711.PushDownstream

指定したチャネルの視聴クライアントにプッシュ通知を送ります。

キー	型
channel_id	string
data	object

$ http POST 127.0.0.1:3000/ \
    x-sora-target:Sora_20160711.PushDownstream \
    channel_id=sora \
    data:="{\"spam\": \"egg\"}" \
    -vvv
POST / HTTP/1.1
Accept: application/json
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 47
Content-Type: application/json
Host: 127.0.0.1:3000
User-Agent: HTTPie/0.9.4
x-sora-target: Sora_20160711.PushDownstream

{
    "channel_id": "sora",
    "data": {
        "spam": "egg"
    }
}

HTTP/1.1 200 OK
content-length: 37
content-type: application/json
date: Sun, 24 Jul 2016 06:29:20 GMT
server: Cowboy

{
    "data": {
        "spam": "egg"
    },
    "type": "push"
}

廃止 リモート統計情報 API

統計情報更新のタイミングについて

この統計情報は、シグナリングで死活監視用の Pong メッセージに含まれてくるクライアント統計情報の最新の値を返します。

Ping メッセージは 5 秒間隔で Sora から送られるため、ネットワークが正常であれば Pong メッセージが返ってくるのは 5 秒間隔となります。 そのため、統計情報は 5 秒間隔で更新されます。

GetAllRemoteStats

危険

この API は廃止しました。

廃止:

2022 年 6 月リリースの Sora にて廃止

代替 API:

Sora_20211215.ListUserAgentStats

x-sora-target:

Sora_20200225.GetAllRemoteStats

すべてのリモート統計情報を取得する。

$ http POST 127.0.0.1:3000/ x-sora-target:Sora_20200225.GetAllRemoteStats -vvv
POST / HTTP/1.1
Accept: */*
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 0
Host: 127.0.0.1:3000
User-Agent: HTTPie/2.0.0
x-sora-target: Sora_20200225.GetAllRemoteStats



HTTP/1.1 200 OK
access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
access-control-allow-methods: POST, OPTIONS
access-control-allow-origin: http://127.0.0.1:5000
access-control-max-age: 1000
content-length: 9444
content-type: application/json
date: Thu, 09 Apr 2020 07:31:33 GMT
server: Cowboy

[
    {
        "channel_id": "sora",
        "connection_id": "HMRVPQEXJX03D3B3WE778SJGRC",
        "remote_stats": [
            {
                "audioLevel": 0,
                "id": "RTCAudioSource_1",
                "kind": "audio",
                "timestamp": 1586417492054.487,
                "totalAudioEnergy": 0,
                "totalSamplesDuration": 24.930000000001098,
                "trackIdentifier": "8de161d9-c93f-4c8a-ab0e-c4cb1ed45543",
                "type": "media-source"
            }, ...
        ],
        "timestamp": "2020-04-09T07:31:32.056Z"
    }
]

GetChannelRemoteStats

危険

この API は廃止しました。

廃止:

2022 年 6 月リリースの Sora にて廃止

代替 API:

Sora_20211215.ListChannelUserAgentStats

x-sora-target:

Sora_20200225.GetChannelRemoteStats

指定したチャネルのリモート統計情報を取得する。

キー	型
channel_id	string

$ http POST 127.0.0.1:3000/ x-sora-target:Sora_20200225.GetChannelRemoteStats \
    channel_id=sora \
    -vvv
POST / HTTP/1.1
Accept: application/json, */*
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 22
Content-Type: application/json
Host: 127.0.0.1:3000
User-Agent: HTTPie/2.0.0
x-sora-target: Sora_20200225.GetChannelRemoteStats

{
    "channel_id": "sora"
}

HTTP/1.1 200 OK
access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
access-control-allow-methods: POST, OPTIONS
access-control-allow-origin: http://127.0.0.1:5000
access-control-max-age: 1000
content-length: 9479
content-type: application/json
date: Thu, 09 Apr 2020 07:32:36 GMT
server: Cowboy

[
    {
        "channel_id": "sora",
        "connection_id": "HMRVPQEXJX03D3B3WE778SJGRC",
        "remote_stats": [
            {
                "audioLevel": 0,
                "id": "RTCAudioSource_1",
                "kind": "audio",
                "timestamp": 1586417557067.526,
                "totalAudioEnergy": 0,
                "totalSamplesDuration": 89.95000000000911,
                "trackIdentifier": "8de161d9-c93f-4c8a-ab0e-c4cb1ed45543",
                "type": "media-source"
            }, ...
        ],
        "timestamp": "2020-04-09T07:32:37.069Z"
    }
]

GetConnectionRemoteStats

危険

この API は廃止しました。

廃止:

2022 年 6 月リリースの Sora にて廃止

代替 API:

Sora_20211215.GetUserAgentStats

x-sora-target:

Sora_20200225.GetConnectionRemoteStats

指定した接続のリモート統計情報を取得する。

キー	型
channel_id	string
connection_id	string

$ http POST 127.0.0.1:3000/ x-sora-target:Sora_20200225.GetConnectionRemoteStats \
    channel_id=sora \
    connection_id=HMRVPQEXJX03D3B3WE778SJGRC \
    -vvv
POST / HTTP/1.1
Accept: application/json, */*
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 69
Content-Type: application/json
Host: 127.0.0.1:3000
User-Agent: HTTPie/2.0.0
x-sora-target: Sora_20200225.GetConnectionRemoteStats

{
    "channel_id": "sora",
    "connection_id": "HMRVPQEXJX03D3B3WE778SJGRC"
}

HTTP/1.1 200 OK
access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
access-control-allow-methods: POST, OPTIONS
access-control-allow-origin: http://127.0.0.1:5000
access-control-max-age: 1000
content-length: 9473
content-type: application/json
date: Thu, 09 Apr 2020 07:33:41 GMT
server: Cowboy

{
    "channel_id": "sora",
    "connection_id": "HMRVPQEXJX03D3B3WE778SJGRC",
    "stats": [
        {
            "audioLevel": 0,
            "id": "RTCAudioSource_1",
            "kind": "audio",
            "timestamp": 1586417622080.464,
            "totalAudioEnergy": 0,
            "totalSamplesDuration": 154.96000000000404,
            "trackIdentifier": "8de161d9-c93f-4c8a-ab0e-c4cb1ed45543",
            "type": "media-source"
        }, ...
    ],
    "timestamp": "2020-04-09T07:33:42.081Z"
}

廃止 スポットライト API

CastSpotlight

危険

この API は廃止しました。

廃止:

2021 年 12 月リリースの Sora にて廃止

x-sora-target:

Sora_20180404.CastSpotlight

指定した参加者を強制的に画面に表示する。

キー	型
channel_id	string
connection_id	string

$ http POST 127.0.0.1:3000/ x-sora-target:Sora_20180404.CastSpotlight \
                            channel_id=sora \
                            connection_id=KD9N57E2RN5T1BDEA7S7SH038M \
                            -vvv
POST / HTTP/1.1
Accept: application/json, */*
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 75
Content-Type: application/json
Host: 127.0.0.1:3000
User-Agent: HTTPie/0.9.9
x-sora-target: Sora_20180404.CastSpotlight

{
    "channel_id": "sora",
    "connection_id": "KD9N57E2RN5T1BDEA7S7SH038M"
}

HTTP/1.1 200 OK
access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
access-control-allow-methods: POST, OPTIONS
access-control-allow-origin: http://127.0.0.1:5000
access-control-max-age: 1000
content-length: 72
content-type: application/json
date: Fri, 27 Apr 2018 02:01:35 GMT
server: Cowboy

{
    "channel_id": "sora",
    "connection_id": "KD9N57E2RN5T1BDEA7S7SH038M"
}

CastAlwaysSpotlight

危険

この API は廃止しました。

廃止:

2021 年 12 月リリースの Sora にて廃止

x-sora-target:

Sora_20180404.CastAlwaysSpotlight

指定した参加者を常に画面に表示します。

キー	型
channel_id	string
connection_id	string
spotlight_id (オプション)	string

spotlight_id を指定しない場合はどこかのスポットライトに入ります。

$ http POST 127.0.0.1:3000/ x-sora-target:Sora_20180404.CastAlwaysSpotlight \
                            channel_id=sora \
                            connection_id=KD9N57E2RN5T1BDEA7S7SH038M \
                            spotlight_id=spotlight-1 \
                            -vvv
POST / HTTP/1.1
Accept: application/json, */*
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 106
Content-Type: application/json
Host: 127.0.0.1:3000
User-Agent: HTTPie/0.9.9
x-sora-target: Sora_20180404.CastAlwaysSpotlight

{
    "channel_id": "sora",
    "connection_id": "af9103b1-2412-4a3c-88b2-cc4d84114d98",
    "spotlight_id": "spotlight-1"
}

HTTP/1.1 200 OK
access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
access-control-allow-methods: POST, OPTIONS
access-control-allow-origin: http://127.0.0.1:5000
access-control-max-age: 1000
content-length: 101
content-type: application/json
date: Wed, 25 Apr 2018 07:11:30 GMT
server: Cowboy

{
    "channel_id": "sora",
    "connection_id": "KD9N57E2RN5T1BDEA7S7SH038M",
    "spotlight_id": "spotlight-1"
}

CancelSpotlight

危険

この API は廃止しました。

廃止:

2021 年 12 月リリースの Sora にて廃止

x-sora-target:

Sora_20180404.CancelSpotlight

指定した参加者を常に画面に表示する状態を解除します。

キー	型
channel_id	string
connection_id	string

$ http POST 127.0.0.1:3000/ x-sora-target:Sora_20180404.CancelSpotlight \
                            channel_id=sora \
                            connection_id=KD9N57E2RN5T1BDEA7S7SH038M \
                            -vvv
POST / HTTP/1.1
Accept: application/json, */*
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 75
Content-Type: application/json
Host: 127.0.0.1:3000
User-Agent: HTTPie/0.9.9
x-sora-target: Sora_20180404.CancelSpotlight

{
    "channel_id": "sora",
    "connection_id": "KD9N57E2RN5T1BDEA7S7SH038M"
}

HTTP/1.1 200 OK
access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
access-control-allow-methods: POST, OPTIONS
access-control-allow-origin: http://127.0.0.1:5000
access-control-max-age: 1000
content-length: 72
content-type: application/json
date: Wed, 25 Apr 2018 07:12:01 GMT
server: Cowboy

{
    "channel_id": "sora",
    "connection_id": "KD9N57E2RN5T1BDEA7S7SH038M"
}

DowngradeSpotlightBitRate

危険

この API は廃止しました。

廃止:

2021 年 12 月リリースの Sora にて廃止

x-sora-target:

Sora_20181023.DowngradeSpotlightBitRate

指定したスポットライトチャネルのビットレートを下げる。

キー	型
channel_id	string

現時点ではどの程度下げるかどうかは指定できません。

$ http POST 127.0.0.1:3000/ \
    x-sora-target:Sora_20181023.DowngradeSpotlightBitRate \
    channel_id=sora \
    -vvv

ResetSpotlightBitRate

危険

この API は廃止しました。

廃止:

2021 年 12 月リリースの Sora にて廃止

x-sora-target:

Sora_20181023.ResetSpotlightBitRate

指定したスポットライトチャネルのビットレートを戻します。

キー	型
channel_id	string

$ http POST 127.0.0.1:3000/ \
    x-sora-target:Sora_20181023.ResetSpotlightBitRate \
    channel_id=sora \
    -vvv

RequestSpotlightQuality

危険

この API は廃止しました。

廃止:

2020 年 12 月リリースの Sora にて廃止

代替 API:

Sora_20201005.RequestRtpStream

x-sora-target:

Sora_20200807.RequestSpotlightQuality

指定した参加者の受信している映像ストリームのクオリティを変更します。

スポットライトのフォーカスとは別に、画質を受信ストリームすべて、またはストリームごと変更できます。 現時点では low か middle のみ指定できます。

キー	型
channel_id	string
connection_id	string
stream_id (オプション)	string
quality	string (low / middle / high)

$ http POST 127.0.0.1:3000/ x-sora-target:Sora_20200807.RequestSpotlightQuality \
    channel_id=sora connection_id=DRPBMP6FEH49S5CSB04EDSTQ38 quality=low -vvv
POST / HTTP/1.1
Accept: application/json, */*
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 87
Content-Type: application/json
Host: 127.0.0.1:3000
User-Agent: HTTPie/2.0.0
x-sora-target: Sora_20200807.RequestSpotlightQuality

{
    "channel_id": "sora",
    "connection_id": "DRPBMP6FEH49S5CSB04EDSTQ38",
    "quality": "low"
}

HTTP/1.1 200 OK
access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
access-control-allow-methods: POST, OPTIONS
access-control-allow-origin: http://127.0.0.1:5000
access-control-max-age: 1000
content-length: 82
content-type: application/json
date: Wed, 09 Sep 2020 08:47:49 GMT
server: Cowboy

{
    "channel_id": "sora",
    "connection_id": "DRPBMP6FEH49S5CSB04EDSTQ38",
    "quality": "low"
}

ResetSpotlightQuality

危険

この API は廃止しました。

廃止:

2020 年 12 月リリースの Sora にて廃止

代替 API:

Sora_20201005.ResetRtpStream

x-sora-target:

Sora_20200807.ResetSpotlightQuality

指定した参加者の受信している映像ストリームのクオリティをリセットします。 RequestSpotlightQuality で変更された画質をリセットします。

キー	型
channel_id	string
connection_id	string
stream_id (オプション)	string

$ http POST 127.0.0.1:3000/ x-sora-target:Sora_20200807.ResetSpotlightQuality \
    channel_id=sora connection_id=DRPBMP6FEH49S5CSB04EDSTQ38 -vvv
POST / HTTP/1.1
Accept: application/json, */*
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 69
Content-Type: application/json
Host: 127.0.0.1:3000
User-Agent: HTTPie/2.0.0
x-sora-target: Sora_20200807.ResetSpotlightQuality

{
    "channel_id": "sora",
    "connection_id": "DRPBMP6FEH49S5CSB04EDSTQ38"
}

HTTP/1.1 200 OK
access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
access-control-allow-methods: POST, OPTIONS
access-control-allow-origin: http://127.0.0.1:5000
access-control-max-age: 1000
content-length: 66
content-type: application/json
date: Wed, 09 Sep 2020 08:48:35 GMT
server: Cowboy

{
    "channel_id": "sora",
    "connection_id": "DRPBMP6FEH49S5CSB04EDSTQ38"
}

テスト API

注意

テスト API はテスト目的のためだけに利用してください

概要

テスト API は意図的に発生させるのが難しい状況を API 経由で発生させるための API です。

注意

• テスト API は利便性を最優先にするため破壊的変更を積極的に行います

GenerateCrashLog

x-sora-target:

Sora_20380119.GenerateCrashLog

意図的に Sora のクラッシュログを発生させます。クラッシュログの監視のテストなどに利用してください。

この API はかならずステータスコード 500 を返します。

キー	型
info	object

$ http POST 127.0.0.1:3000/ x-sora-target:Sora_20380119.GenerateCrashLog \
    info:='{"spam": "egg"}' \
    -vvv

FailArchive

x-sora-target:

Sora_20380119.FailArchive

意図的に Sora の録画を失敗させます。 archive.failed ウェブフックを意図的に出力させたい場合に利用してください。

テストの利便性を考えランダムな値である connection_id ではなく、固定値として設定できる client_id を指定できるようにしています。

client_id は指定しなければ connection_id が設定されるので、 client_id を指定しない場合、 client_id に connection_id を指定しても動作します。

キー	型
channel_id	string
client_id	string

$ http POST 127.0.0.1:3000/ x-sora-target:Sora_20380119.FailArchive \
    channel_id=sora \
    client_id=test \
    -vvv

SendSignalingNotify

x-sora-target:

Sora_20380119.SendSignalingNotify

指定した内容のシグナリング通知として送信します。シグナリング通知のテストなどに利用してください。

• 指定したチャネルの参加者全員に json に指定した値がそのまま通知されます

• クラスター機能を利用していた場合、API を実行したノードでのみ通知されます

キー	型
channel_id	string
json	object

$ http POST 127.0.0.1:3000/ x-sora-target:Sora_20380119.SendSignalingNotify \
    channel_id=sora \
    json:='{"type": "notify", "event_type": "audio-streaming-failed"}' \
    -vvv

LockIceConnectionState

x-sora-target:

Sora_20380119.LockIceConnectionState

ICE コネクションステートの状態を指定した状態に変更しロックします。ICE コネクションステートのテストなどに利用してください。

一度でもこの API で状態を変更した場合は、ICE コネクションステート機能は機能しなくなりますので注意してください。 ただし状態を変更した際のシグナリング通知は通知されます。

キー	型
channel_id	string
connection_id	string
state_name	connected | checking | disconnected

$ http POST 127.0.0.1:3000/ x-sora-target:Sora_20380119.LockIceConnectionState \
    channel_id=sora \
    connection_id=6V9VANDZZH71HCQGVKBWKJ8GS0 \
    state_name=checking \
    -vvv

クラスター機能

概要

これは複数の Sora でクラスターを構成し、冗長化、負荷分散を行うための仕組みです。

ひとつのチャネル ID をクラスターに参加している複数の Sora で共有することができます。 そのため、Sora をクラスターに追加で参加させることで 1 チャネル単位での配信をスケールアウトさせることができます。

ここではクラスター機能ついて説明しています。

• クラスター機能を動かしてみる場合は クラスター機能のチュートリアル をご確認ください

• クラスター機能の運用については クラスター機能の運用 をご確認ください

• クラスター機能利用時の録画については クラスター機能での録画機能 をご確認ください

用語

ノード

クラスターに参加している Sora

レギュラーノード

クラスター構成を維持するノード

テンポラリーノード

クラスター構成を維持しないノード、ノードを停止すると強制的にクラスターから消去される

リレー

ノード間で音声、映像、データを転送すること

アフィニティ

同一セッションの接続を同一ノードに集約すること

クライアントへの複数シグナリング設定

Sora SDK にシグナリング URL を複数指定することで、いずれかの ノードが正常に動作していれば Sora に繋がります。

注釈

最低 3 つ、レギュラーノードのシグナリング URL を渡す事を推奨しています。

リレー機能

注意

リレー機能を利用する場合は事前にサポートまでご連絡ください

警告

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

重要

リレー機能を利用するには 最大ノード数ライセンス が必要になります。

注意

リレー機能を利用する際、ノード間通信には同一データセンター内のプライベートネットワークを利用してください。

Sora クラスターはリレーという仕組みで、 クラスターに参加しているノード同士で、クライアントの音声や映像、データを共有します。

例えば 3 ノードのクラスターがある場合、 すでに接続しているクライアントがいるノードとは異なるノードにクライアントが接続した場合、 Sora はその異なるノードにすでに接続しているクライアントの音声や映像、データをリレーします。

この機能を利用することで 1 チャネルでのスケールアウトを実現できるようになります。

リレー機能はクラスター機能が有効な場合に利用できます。

リレー機能はデフォルトで有効になっています。 無効にしたい場合は sora.conf の cluster_relay を変更してください。

cluster_relay = false

リレー発生のタイミング

リレー機能利用時、リレーが発生するタイミングは別ノードに同一チャネルへ参加しているクライアントがいる場合のみです。

同一ノードのみの場合は他のノードへのリレーは発生しません。

リレー終了のタイミング

一度リレーが発生した場合、セッションが破棄されるまではリレーが破棄されることは基本的にありません。

メッセージングのリレー

リレー機能は音声と映像だけでなく、メッセージもリレーを行います。そのため、リレー機能ではメッセージング機能も利用できます。

最大ノード数ライセンス

リレー機能は 最大ノード数ライセンス が必要になります。もし 最大ノード数ライセンス を利用せずに、 sora.conf の cluster_relay を true にした場合、リレー機能は無効になります。

接続したノードが最大同時接続数に達していた場合

もし接続したノードがライセンスの最大同時接続数に達している場合は、 余裕のある別ノードへのリダイレクトを試みます。

リレー機能時に利用できない機能

• RTP ストリーム停止/再開 API

アフィニティ機能

重要

アフィニティ機能を利用するには 最大ノード数ライセンス が必要になります。

Sora クラスターはリレー機能利用時に、同一セッションの接続を同一ノードに集約するアフィニティ機能を提供します。

同一セッションへの接続を同一ノードに集約することでレイテンシーを低減し、より低遅延な通信を実現できます。

アフィニティ機能はデフォルトで有効になっています 無効にしたい場合は sora.conf の default_cluster_affinity を変更してください

default_cluster_affinity = false

アフィニティはクラスター単位でのデフォルト値以外に、コネクション単位で指定することもできます。

コネクション単位の指定は sora.conf の default_cluster_affinity の値を上書きします この仕組みを利用することで特定のコネクションだけアフィニティを行わず、最初に接続したノードで WebRTC の確立を試みることができるようになります。

注釈

リレー機能を検証したい場合は sora.conf の default_cluster_affinity を false に設定してください。

接続したノードが最大同時接続数に達していた場合

もし接続したノードがライセンスの最大同時接続数に達している場合は、 余裕のある別ノードへのリダイレクトを試みます。

コネクション単位でのアフィニティ指定

認証ウェブフックの認証成功時の払い出しで cluster_affinity を指定することができます。

  {
.    "allowed": true,
     "cluster_affinity": "<boolean>"
  }

"cluster_affinity": true を指定した場合は、接続したノードがセッションを集約しているノードでなければ、 "type": "redirect" をクライアントへ返し、集約しているノードへの再接続を要求します。

"cluster_affinity": false を指定した場合は、ノードへの集約を行わず、接続したノードでの WebRTC 確立を試みます。

クラスターアフィニティ利用時の 1 ノードセッション同時接続数基準値指定

注意

この設定を利用する場合は事前にサポートまでご相談ください

接続したノードのセッション単位での同時接続数が sora.conf の cluster_affinity_threshold で指定した基準値を超えていた場合、 他のノードへのリダイレクトを試みるようになります。

全てのノードで基準値を超えた場合は、ノード単位での同時接続数が最も少ないノードにリダイレクトを試みます。

この設定はチューニング向けのため、基本的にはデフォルトから変更する必要はありません。

cluster_affinity_threshold = 20

リレー機能利用時の認証について

リレー機能を利用している場合、認証成功時の払い出しでアフィニティを判断するため、 接続したノードで必ず認証を行います。

アフィニティが有効な場合は、別ノードへのリダイレクトが発生する場合があります。 その場合は別ノードでも認証が行われます。

アフィニティが無効な場合でも、接続を行ったノードがライセンスの上限に達していた場合で、 クラスター全体ではまだライセンスの上限に達していない場合は別ノードへのリダイレクトが発生します。 その場合は別ノードでも認証が行われます。

詳細は クラスターリレー機能利用時に認証が 2 回行われる場合がある をご確認ください。`

テンポラリーノード機能

重要

テンポラリーノード機能を利用するには 最大ノード数ライセンス が必要になります。

テンポラリーノードはクラスター構成を維持するためのノードとして認識されず、 ノードを停止すると強制的にクラスターから消去されます。

そのため、クラスターを気軽にスケールアウト/スケールインさせることができます。

注意点としてテンポラリーノードが何ノード稼働していたとしても、 生存しているレギュラーノードが過半数を下回った場合、クラスターは利用できなくなります。

設定

sora.conf で cluster_temporary_node を true に設定することでテンポラリーノードとして扱われます。

cluster_temporary_node = true

登録

クラスターへの登録はレギュラーノードと同様 RegisterClusterNode API を利用してください。

テンポラリーノードはノードを停止したタイミングで、クラスターから強制的に消去されます。 そのため、再度クラスターに登録するには RegisterClusterNode API を利用して登録してください。

消去

テンポラリーノードはクラスターを維持するためのノードとして認識されず、 ノードを停止することでクラスターから強制的に消去されます。

そのためノード離脱時に PurgeClusterNode API でノードを消去する必要はありません。

ネットワーク障害時

テンポラリーノードがネットワーク障害でクラスターから切断されたとしても、 ノードを停止しなければ自動でクラスターに復帰します。

ノード障害時

テンポラリーノードが何かしらの障害で停止した場合は、必ず登録が必要です。

注意

• テンポラリーノードを利用するには 最大ノード数ライセンス が必要です

• テンポラリーノードはクラスター構成を維持するためのノードとしては認識されません

• テンポラリーノードに障害が発生してもライセンスで決められた最大同時接続数の合計を維持する機能による接続数の維持は行われません

• テンポラリーノードはクラスターへの登録には RegisterClusterNode API を利用してください

• テンポラリーノードは停止時にクラスターから消去されます

• テンポラリーノードを再起動した場合、クラスターには自動で参加しません。再度 :ref:20211215.RegisterClusterNode API を利用して登録してください

• テンポラリーノードだけでクラスターを構築する事はできません

• テンポラリーノードは PurgeClusterNode API でノードを消去することはできません

• テンポラリーノードは InitCluster API で初期化することはできません

シグナリングのリダイレクト機能

重要

Sora の SDK を利用している場合は、 基本的にここに書かれているリダイレクトの細かい仕様を把握する必要はありません。

"type": "connect" を送った際、認証処理前と認証処理後に、 {"type": "redirect", "location": "wss://sora1.example.com/signaling"} が Sora から送られてくる場合があります。

この場合は、送られてきた location の URL にシグナリング URL を切り替えて再度 type: connect を行ってください。 その際は {type: connect, redirect: true} のように redirect: true を追加情報として入れてください。

接続したノードが最大同時接続数に達していた場合

• リレー機能が無効な場合、チャネルのセッションが接続したノードに生成されている場合は接続に失敗します

• リレー機能が無効な場合、チャネルのセッションが接続したノードに生成されていない場合、余裕のあるノードへリダイレクトを試みます

• リレー機能が有効な場合、余裕のあるノードへリダイレクトを試みます

リダイレクト機能によるノード選択

リレー機能有効かつアフィニティ機能有効時

アフィニティ機能が有効な場合はできるだけ同一セッションを同一ノードに集約します。

すでに、そのチャネル ID がクラスター内部で利用されている場合は、 そのチャネル ID のセッションが存在するノードへ接続先の割り当てを試みます。

また、そのチャネル ID がクラスター内部で利用されているが、 そのチャネル ID のセッションが存在するノードのセッション単位の同時接続数が、 cluster_affinity_threshold の基準値を超えていた場合は、 他のノードへの割り当てを試みます。

ちなみに、全てのノードで cluster_affinity_threshold の基準値を超えた場合は、 一番余裕のあるノードへの割り当てを試みます。

割り当てられたノードの同時接続数がライセンスの上限に達していた場合、 一番余裕のあるノードへの割り当てを試みます。

リレー機能有効かつアフィニティ機能無効時

すでに、そのチャネル ID がクラスター内部で利用されている場合でも、 接続したノードへの割り当てを試みます。

接続したノードが同時接続数のライセンスの上限に達成していた場合、 一番余裕のあるノードへの割り当てを試みます。

リレー機能無効時

すでに、そのチャネル ID がクラスター内部で利用されている場合は、 そのチャネル ID のセッション ID が存在するノードへ割り当てを試みます。

ただし、そのノードの同時接続数がライセンスの上限に達していた場合、 接続に失敗します。

ロードバランス機能

クラスターを構築しているノードの中で ライセンスの最大同時接続数 を 現在の同時接続数 で引いた値が一番小さいノードに、チャネル ID の新規セッションを割り当てます。 この値がすべて同じ場合は、接続しに行ったノード自身が新規チャネル ID のセッションを担当します。

また、接続したノードがライセンスの最大同時接続数に達していた場合、 他のノードへのリダイレクトを試みます。

アフィニティ機能を無効にしている場合

アフィニティ機能を無効にしている場合は接続を試みたノードに接続し、リダイレクトは一切発生しません。 ただし、ライセンスの最大同時接続数を超えていた場合、他のノードへのリダイレクトを試みます。

HTTP API のリダイレクト機能

チャネル ID を指定する HTTP API を利用する場合、リダイレクトが発生することがあります。 指定されたチャネル ID を他ノードが担当している場合に、ステータスコード 307 (Temporary Redirect)の HTTP 応答により、クライアントにそのノードへのリダイレクトを要求します。

ステータスコード 307 の HTTP 応答受信時の処理は、HTTP のクライアントとして使用するツールやライブラリにより異なります。 必要に応じて、リダイレクト応答の Location ヘッダーへアクセスを継続するようにしてください。

HTTPie の場合は --follow を指定することで、リダイレクト先への再要求を行います。

クラスターへの登録

クラスターへノードを登録する機能です。 既存のクラスターに登録する際に、クラスターに登録させるノードで RegisterClusterNode API を実行します。

また、そのノードが一度でもクラスターに参加したことがある場合は、クラスターへの参加を自動で試みます。

クラスター自動復旧

クラスターで利用しているネットワークに障害が発生した際には、個々のノードはクラスターを構成する他のノードへの接続を試みて、復旧処理を行います。

ネットワーク分断時の接続受け付けの停止

ネットワーク分断時には Sora のノード間で通信ができずに、クラスター内の情報の整合性が取れなくなる可能性があります。 この情報の不整合を回避するために、Sora は自分がクラスター内の半数以下のグループに属した場合には、既存の接続を切断し、 さらに新規接続の受け付けも停止します。

特定ノードへの新規チャネル ID の割り当て停止

モード機能 の 新規セッションブロックモード または 新規コネクションブロックモード になっている場合は、 そのノードに対して新規チャネル ID の割り当てを行いません。

ライセンスで決められた最大同時接続数の合計を維持する機能

重要

ライセンスで決められた最大同時接続数の合計を維持する機能を利用するには 最大ノード数ライセンス が必要になります。

クラスターを構築している場合、特定のノードがハードウェア障害などで利用できなくなった場合、 残りのノードで障害が発生したレギュラーノードの同時接続数を引き継ぎます。

例えば 100 同時接続のレギュラーノードを 3 つでクラスターを構築している場合、 1 つのレギュラーノードに障害が発生した場合は 2 つのノードで 300 同時接続を維持できます。

割り当ては 1 つのノードが 150 までの同時接続数を許容できるようになります。

障害が発生したレギュラーノードが復旧したとしても 100 を超えている接続を切断することはありません。 ただし 1 ノードの最大同時接続数の 100 までに戻ります。

切り上げ

レギュラーノードが 3 ノード、テンポラリーノードが 1 ノードあり、 それぞれが 100 同時接続数をできる場合、 レギュラーノードが 1 ノード障害が発生した場合、残りの 3 ノードがそれぞれ +34 同時接続数を一時的に引き継ぎます。

残りのノード数で割った結果の小数点以下は切り上げます。

テンポラリーノード利用時の注意

この機能はテンポラリーノードには適用されません。

例えばレギュラーノードが 3 ノード、テンポラリーノードが 1 ノードあり、 それぞれが 100 同時接続数をできる場合、テンポラリーノードが 1 ノード障害が発生したとしても、 テンポラリノードの同時接続数分を維持することはありません。

レギュラーノード 1 ノードに障害が発生した場合、テンポラリーノードは同時接続数分の維持を行います。

設定

クラスター機能を利用するには以下の設定を行ってください。

• cluster

• node_name

• external_signaling_url

• external_api_url

cluster

必須設定

クラスター機能を利用する場合、 sora.conf にて cluster を true を設定する必要があります。

デフォルトでは cluster は有効になっていません。

重要

cluster = true にして Sora を起動した場合、 Sora は InitCluster API を実行するか、クラスターに参加して過半数のグループになったタイミングでのみ利用可能になります。

cluster = true

node_name

必須設定

クラスター機能を利用する際のノード名を指定して下さい。

この名前はクラスター内のノードの識別に使われます。 具体的には、クラスターノード間の通信相手の特定や、 RegisterClusterNode API、 PurgeClusterNode API で指定する名前として利用します。

重要

node_name はクラスター内のすべてのノードでユニークである必要があります

ノード名の @ の前には、正規表現 [0-9A-Za-z_\\-]+ にマッチする任意の文字列を指定してください。 また @ の後ろには、他のノードからアクセス可能なこのノードのドメイン名（FQDN）や、IP アドレスを指定してください。

@ の後ろにホスト名（"." を含まない文字列）のみを指定すると、ノード間で通信が行えなくなってしまいますので、ご注意ください。

# ドメイン名を指定する例
node_name = [email protected]

# IP アドレスを指定する例
node_name = [email protected]

external_signaling_url

必須設定

sora.conf にてシグナリングの URL を指定して下さい。 この URL はクラスター機能を利用した際に "type": "redirect" の "location" の値として払い出されます。

external_signaling_url = wss://node1.example.com/signaling

例えば、上記の設定の場合は、シグナリングのリダイレクトが必要な際に Sora から {"type": "redirect", "location": "wss://node1.example.com/signaling"} として払い出されます。

external_api_url

必須設定

sora.conf にて API の URL を指定して下さい。 この URL はクラスター機能を利用した際に、API を適切なノードに HTTP 307 でリダイレクトさせる場合の HTTP の location ヘッダーの値として払い出されます。

この URL は外部に公開する必要はなく、プライベートなアドレスでも問題ありません。

# IP アドレスを指定する例
external_api_url = http://192.0.2.10:3000/

# ドメイン名を指定する例
external_api_url = https://node1.example.com/api

cluster_relay

重要

クラスターリレー機能を利用する場合は 最大ノード数ライセンス が必要になります。

クラスターリレー機能を利用する場合、 sora.conf にて cluster を true を設定する必要があります。

cluster_relay のデフォルトは true になっています。

cluster = true

default_cluster_affinity

重要

クラスターアフィニティ機能を利用する場合は 最大ノード数ライセンス が必要になります。

クラスターリレー機能でアフィニティ機能を利用する場合、 sora.conf にて cluster と cluster_relay を true を設定する必要があります。

default_cluster_affinity のデフォルトは true になっています。

default_cluster_affinity = true

cluster_affinity_threshold

クラスターリレー機能でアフィニティ機能で、他のノードへのリレーが発生する 1 ノード 1 セッションあたりの同時接続数を指定します。チューニング目的の設定となります。

• 片方向で大規模廃止であれば 100 などの大きめの設定をお勧めします

• 双方向で 1 チャネルで最大 5 接続までなら 5 を設定することをお勧めします

cluster_affinity_threshold = 5

cluster_listen_{min,max}_port

sora.conf にてクラスター情報の同期に利用する TCP の受信ポートの範囲を指定してください。

デフォルトでは 49010 - 49020 が指定されています。

cluster_listen_min_port = 49010
cluster_listen_max_port = 49020

API

クラスター初期化 API

クラスターを構築するときは、まずクラスターの初期化を行います。

重要

クラスターの初期化はクラスターを初めて構築する際と、クラスターが破綻した際に行う必要があります。

クラスターの初期化を実行する場合は 20221221.InitCluster API をクラスター構築するいずれかのノードで実行します。 node_name_list にはクラスターを構成するノードを、 20221221.InitCluster API を実行するノードを含め指定してください。

API の詳細は InitCluster API をご確認ください。

$ http POST 127.0.0.1:3000/ x-sora-target:Sora_20221221.InitCluster \
    node_name_list:='["[email protected]", "[email protected]", "[email protected]"]' \
    -vvv
POST / HTTP/1.1
Accept: application/json, */*;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 83
Content-Type: application/json
Host: 127.0.0.1:3000
User-Agent: HTTPie/3.2.2
x-sora-target: Sora_20221221.InitCluster

{
    "node_name_list": [
        "[email protected]",
        "[email protected]",
        "[email protected]"
    ]
}


HTTP/1.1 200 OK
access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
access-control-allow-methods: POST, OPTIONS
access-control-allow-origin: *
access-control-max-age: 1000
content-length: 80
content-type: application/json
date: Wed, 06 Dec 2023 06:52:47 GMT
server: Cowboy

{
    "node_name_list": [
        "[email protected]",
        "[email protected]",
        "[email protected]"
    ]
}

重要

クラスターのノードが恒久的に破損し、クラスターを構成するノードが半数以下になった場合には、 全てのノードが接続を受け付けなくなるため、クラスターの再構築手順に従って、 再度クラスターの初期化を行う必要があります。

詳しくは クラスター破綻からの再構築手順 を参照してください。

クラスター登録 API

初期化後のクラスターにノードを追加するときは、すでにクラスターに参加しているノードを指定して、登録するノードに API を実行します。

API の詳細は RegisterClusterNode API をご確認ください。

下記は、既存クラスター内の node-01@192.0.2.5 ノードを contact_node_name に指定して、新規に登録するノードで RegisterClusterNode APIを実行しています。

$ http POST 127.0.0.1:3000/ x-sora-target:Sora_20211215.RegisterClusterNode \
    contact_node_name=[email protected]
HTTP/1.1 200 OK
content-length: 80
content-type: application/json
date: Tue, 16 Nov 2021 08:42:25 GMT
server: Cowboy

{
    "node_name_list": [
        "[email protected]",
        "[email protected]",
        "[email protected]"
    ]
}

クラスターノード完全消去 API

あるノードが障害で再度の参加が難しい、またはスケールインのためにノード破棄する場合は、 破棄するノードを停止後に PurgeClusterNode API を利用して、そのノード情報を完全消去してください。

20220629.PurgeClusterNode API は、クラスターに参加している破棄するノード以外のどのノードでもかまわないので 1 回だけ実行します。 この API で完全消去した結果はクラスター内部で共有されます。

警告

PurgeClusterNode API はクラスターからノードを完全に消去するための API です。 再度参加するノードに対しては基本的に使用しないでください。 この API を含めた運用の手順は クラスター機能運用 をご確認ください。

詳細は PurgeClusterNode API をご確認ください。

$ http POST 127.0.0.1:3000/ x-sora-target:Sora_20220629.PurgeClusterNode \
    target_node_name=[email protected]
HTTP/1.1 200 OK
access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
access-control-allow-methods: POST, OPTIONS
access-control-allow-origin: *
access-control-max-age: 1000
content-length: 40
content-type: application/json
date: Wed, 06 Dec 2023 07:16:06 GMT
server: Cowboy

{
    "target_node_name": "[email protected]"
}

クラスターノード一覧 API

詳細は ListClusterNodes API をご確認ください。

$ http POST 127.0.0.1:3000/ x-sora-target:Sora_20211215.ListClusterNodes
HTTP/1.1 200 OK
content-length: 1006
content-type: application/json
date: Tue, 16 Nov 2021 08:36:25 GMT
server: Cowboy

[
    {
        "external_api_url": "http://192.0.2.5:3000/",
        "license_max_connections": 600,
        "license_max_nodes": 10,
        "license_serial_code": "ABCDEF-SRA-E001-203801-400",
        "license_type": "Experimental",
        "node_name": "[email protected]",
        "connected": true,
        "mode": "normal",
        "external_signaling_url": "wss://node-01.example.com/signaling",
        "version": "2023.2.0"
    },
    {
        "external_api_url": "http://192.0.2.7:3000/",
        "license_max_connections": 600,
        "license_max_nodes": 10,
        "license_serial_code": "ABCDEF-SRA-E002-203801-400",
        "license_type": "Experimental",
        "node_name": "[email protected]",
        "connected": true,
        "mode": "normal",
        "external_signaling_url": "wss://node-02.example.com/signaling",
        "version": "2023.2.0"
    },
    {
        "external_api_url": "http://192.0.2.8:3000/",
        "license_max_connections": 600,
        "license_max_nodes": 10,
        "license_serial_code": "ABCDEF-SRA-E003-203801-500",
        "license_type": "Experimental",
        "node_name": "[email protected]",
        "connected": true,
        "mode": "normal",
        "external_signaling_url": "wss://node-03.example.com/signaling",
        "version": "2023.2.0"
    }
]

クラスターチャネル割り当て一覧 API

詳細は ListClusterChannels API をご確認ください。

$ http POST 127.0.0.1:3000/ x-sora-target:Sora_20211215.ListClusterChannels
HTTP/1.1 200 OK
content-length: 461
content-type: application/json
date: Tue, 16 Nov 2021 08:42:25 GMT
server: Cowboy

[
    {
        "channel_id": "sora",
        "owners": [
           {
               "node_name": "[email protected]",
               "connected": true
           }
        ]
    },
    {
        "channel_id": "lemon",
        "owners": [
           {
               "node_name": "[email protected]",
               "connected": true
           }
        ]
    },
    {
        "channel_id": "hisui",
        "owners": [
           {
               "node_name": "[email protected]",
               "connected": true
           }
        ]
    },
    {
        "channel_id": "zakuro",
        "owners": [
           {
               "node_name": "[email protected]",
               "connected": true
           }
        ]
    }
]

接続時の挙動

リレーあり / アフィニティあり

• 新規セッションでの接続

  • 一番空いてるノードへリダイレクト

• 既存セッションへの接続

  • 既にセッションがあるノードへリダイレクト

• 新規セッションでの接続 (接続したノードの同時接続数がライセンス上限に達している場合)

  • 一番空いてるノードへリダイレクト

• 既存セッションへの接続 (接続したノードの同時接続数がライセンス上限に達している場合)

  • 一番空いてるノードへリダイレクト

リレーあり / アフィニティなし

• 新規セッションでの接続

  • 接続したノードを選択

• 既存セッションへの接続

  • 接続したノードを選択

• 新規セッションでの接続 (接続したノードの同時接続数がライセンス上限に達している場合)

  • 一番空いてるノードへリダイレクト

• 既存セッションへの接続 (接続したノードの同時接続数がライセンス上限に達している場合)

  • 一番空いてるノードへリダイレクト

リレーなし

• 新規セッションでの接続

  • 一番空いてるノードへリダイレクト

• 既存セッションへの接続

  • 既にセッションがあるノードへリダイレクト

  • 既にセッションがあるノードがライセンス上限に達していた場合、接続失敗

• 新規セッションでの接続 (接続したノードの同時接続数がライセンス上限に達している場合)

  • 一番空いてるノードへリダイレクト

• 既存セッションへの接続 (接続したノードの同時接続数がライセンス上限に達している場合)

  • 既にセッションがあるノードへリダイレクト

  • 既にセッションがあるノードがライセンス上限に達していた場合、接続失敗

クラスターなし

• 新規セッションでの接続

  • 接続したノードを選択

• 既存セッションへの接続

  • 接続したノードを選択

• 新規セッションでの接続 (接続したノードの同時接続数がライセンス上限に達している場合)

  • 接続失敗

• 既存セッションへの接続 (接続したノードの同時接続数がライセンス上限に達している場合)

  • 接続失敗

リレーの終了とアフィニティ機能

リレー機能を利用した場合、一度リレーがノード間で発生すると、セッションが破棄されるまでリレーが行われます。 ノードへの接続数が 0 になったとしてもリレーが発生します。これは Sora の仕様です。

アフィニティ機能を有効にした状態であれば、基本的に同一セッションのコネクションは同一ノードに割り当てられます。 もし別ノードにリレーが発生したとしても、そのリレーが発生したノードに割り当てるようになります。

アフィニティ機能を無効にして、接続を各ノードに分散させた場合は、 リレーが発生したノードで、接続数が 0 になったとしてもリレーが行われ続けますが、これは仕様です。

シーケンス図

注釈

3 ノードのクラスターですが Sora3 を省略しています

リレー機能かつアフィニティ機能が有効

• アフィニティ機能により寄せが発生し、リダイレクトを試みる場合がある

• アフィニティ機能は認証成功時の払い出しで判断するため必ず認証は行う

• リダイレクトが発生した場合は、リダイレクト先のノードでも認証を行う

        sequenceDiagram
    participant C1 as クライアント1
    participant C2 as クライアント2
    participant S1 as Sora1
    participant S2 as Sora2
    participant A as アプリケーションサーバー
    C1->>S1: "type": "connect"
    S1->>+A: 認証ウェブフック
    A-->>-S1: 200 OK<br>"allowed": true<br>"cluster_affinity": true
    S1->>+A: セッションウェブフック<br />"type": "session.created"
    A-->>-S1: 200 OK
    S1->>C1: "type": "offer"
    C1->>S1: "type": "answer"
    note over C1, S1: WebRTC 接続
    S1->>+A: イベントウェブフック<br />"type": "connection.created"
    A-->>-S1: 200 OK
    C2->>S2: "type": "connect"
    S2->>+A: 認証ウェブフック
    A-->>-S2: 200 OK<br>"allowed": true<br>"cluster_affinity": true
    note left of S2: アフィニティ機能により Sora2 へリダイレクト
    S2->>C2: "type": "type": "redirect"
    C2->>S1: "type": "connect", "redirect": true
    S2->>+A: 認証ウェブフック
    A-->>-S1: 200 OK<br />{"allowed": true}
    S1->>C2: "type": "offer"
    C2->>S1: "type": "answer"
    note over C2, S1: WebRTC 確立
    S1->>+A: イベントウェブフック<br />"type": "connection.created"
    A-->>-S1: 200 OK
    

リレー機能が有効だが、アフィニティ機能が無効

• アフィニティ機能による寄せが発生しない

        sequenceDiagram
    participant C1 as クライアント1
    participant C2 as クライアント2
    participant S1 as Sora1
    participant S2 as Sora2
    participant A as アプリケーションサーバー
    C1->>S1: "type": "connect"
    S1->>+A: 認証ウェブフック
    A-->>-S1: 200 OK<br>"allowed": true<br>"cluster_affinity": false
    S1->>+A: セッションウェブフック<br />"type": "session.created"
    A-->>-S1: 200 OK
    S1->>C1: "type": "offer"
    C1->>S1: "type": "answer"
    note over C1, S1: WebRTC 接続
    S1->>+A: イベントウェブフック<br />"type": "connection.created"
    A-->>-S1: 200 OK
    C2->>S2: "type": "connect"
    S2->>+A: 認証ウェブフック
    A-->>-S2: 200 OK<br>"allowed": true<br>"cluster_affinity": false
    S2->>C2: "type": "offer"
    C2->>S2: "type": "answer"
    note over C2, S2: WebRTC 確立
    S2->>+A: イベントウェブフック<br />"type": "connection.created"
    A-->>-S2: 200 OK
    

リレー機能が有効で接続したノードがライセンスの上限

        sequenceDiagram
    participant C1 as クライアント1
    participant S1 as Sora1
    participant S2 as Sora2
    participant A as アプリケーションサーバー
    note over S1: ライセンス余裕なし
    C1->>S1: "type": "connect"
    S1->>+A: 認証ウェブフック
    A-->>-S1: 200 OK<br>"allowed": true<br>"cluster_affinity": false
    note over S1: ライセンス余裕なし
    S1->>C1: "type": "redirect", "location": "wss://sora2..."
    C1->>S2: "type": "connect", "redirect": true
    S2->>+A: 認証ウェブフック
    A-->>-S2: 200 OK<br>"allowed": true<br>"cluster_affinity": false
    note over S2: ライセンス余裕あり
    S2->>+A: セッションウェブフック<br />"type": "session.created"
    A-->>-S2: 200 OK
    S2->>C1: "type": "offer"
    C1->>S2: "type": "answer"
    note over C1, S2: WebRTC 確立
    S2->>+A: イベントウェブフック<br />"type": "connection.created"
    A-->>-S2: 200 OK
    

リレー機能を利用しない場合

• 他のノードが余裕がある場合、新規セッションの場合はリダイレクトを試みる

        sequenceDiagram
    participant C as クライアント
    participant S1 as Sora1
    participant S2 as Sora2
    participant A as アプリケーションサーバー
    C->>S1: "type": "connect"
    note over S1: このノードは同時接続が多かったので、<br>Sora2 へリダイレクト提案
    S1->>C: "type": "redirect"
    C->>S2: "type": "connect", "redirect": true
    S2->>+A: 認証ウェブフック
    A-->>-S2: 200 OK<br />{"allowed": true}
    S2->>C: "type": "offer"
    C->>S2: "type": "answer"
    note over C, A: WebRTC 確立
    S2->>+A: イベントウェブフック<br />"type": "connection.created"
    A-->>-S2: 200 OK
    

クラスター機能チュートリアル

注意

クラスター機能を利用する場合は事前にサポートまでご連絡ください

警告

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

概要

このチュートリアルでは、Sora のクラスター機能をひととおり使ってみるところまでを説明します。

前提

クラスター特有ではない Sora の設定や起動方法、シグナリングで使用する nginx の設定等については チュートリアル を参照してください。

ライセンス

ノード数分のライセンスが必要になります。

Sora 3 台でクラスターを構築する場合は通常のライセンスが 3 つ、もしくは 3 ノード以上に対応した 最大ノード数ライセンス が 1 つ必要です。

注釈

クラスターを構築する場合はリレー機能やライセンスで決められた最大同時接続数の合計を維持する機能が利用できる 最大ノード数ライセンス の利用をお勧めします。

リレー機能

どのノードに繫いでも同一チャネルに接続できるようになるリレー機能を利用する場合は、 最大ノード数ライセンス を利用する必要があります。

最大ノード数ライセンス を利用している場合、リレー機能はデフォルトで有効です。

アフィニティ機能

リレー機能を利用した際でも、できるだけ同一セッションは同一ノードへ接続することで、 ノード間の通信を最小限に抑えるアフィニティ機能を利用する場合は、 最大ノード数ライセンス を利用する必要があります。

最大ノード数ライセンス を利用している場合、アフィニティ機能はデフォルトで有効です。

ライセンスで決められた最大同時接続数の合計を維持する機能

クラスターのノードで障害が発生した際、 他のノードが同時接続数を引き受けるライセンスで決められた最大同時接続数の合計を維持する機能は、 最大ノード数ライセンス を利用する必要があります。

最大ノード数ライセンス を利用している場合、ライセンスで決められた最大同時接続数の合計を維持する機能はデフォルトで有効です。

テンポラリーノード機能

クラスター機能を利用した際に、クラスターの維持を目的とせず、 一時的なスケールアウトを目的にノードを追加するテンポラリーノード機能を利用する場合は、 最大ノード数ライセンス を利用する必要があります。

クラスターの構築

まず、ここでは 3 ノードの Sora クラスターを構築する手順を示します。

それぞれのノードのノード名は sora1@192.0.2.101, sora2@192.0.2.102, sora3@192.0.2.103 とします。

重要

ノード名（node_name） はクラスター内のすべてのノードのそれぞれがユニークである必要があります

external_api_url は HTTP API を叩いたノードにはそのセッションが存在しない場合に、 別のノードに転送するために location ヘッダーに指定する設定する URL です。 そのためプライベートなアドレスでも問題ありません。

注釈

クラスターを構築する際、クラスター間の通信に使うネットワークは、 可能な限りプライベートネットワークを利用してください。

クラスター間の通信には各ノードの node_name で指定した @ 以下の IP アドレスまたはドメイン名を使用します。

ここでのクラスター構築では、3 台のサーバーがそれぞれ TCP/IP で通信できる状態になっていること、 そして Sora の tar.gz が展開されて bin/sora が実行できるようになっていることを前提としています。

1. クラスター間の通信に必要な TCP のポートをすべて開放します

   • TCP 4369

     • ポート番号の変更はできません、必ずこのポートを開放してください

   • TCP 49010-49020

     • sora.conf にて変更できますがデフォルトをお勧めします

2. 最初のノード(sora1@192.0.2.101)の sora.conf にクラスターの設定をします

   node_name = [email protected]
   cluster = true
   external_signaling_url = wss://sora-node1.example.com/signaling
   external_api_url = http://192.0.2.101:3000/
   

3. 最初のノード(sora1@192.0.2.101)の Sora を bin/sora daemon で起動します

4. 次のノード(sora2@192.0.2.102)の sora.conf も最初のノードと同様にクラスターの設定をします

   node_name = [email protected]
   cluster = true
   external_signaling_url = wss://sora-node2.example.com/signaling
   external_api_url = http://192.0.2.102:3000/
   

5. 次のノード(sora2@192.0.2.102)の Sora を bin/sora daemon で起動します

6. 最後のノード(sora3@192.0.2.103)の sora.conf にもクラスターの設定をします

   node_name = [email protected]
   cluster = true
   external_signaling_url = wss://sora-node3.example.com/signaling
   external_api_url = http://192.0.2.103:3000/
   

7. 最後のノード(sora3@192.0.2.103)の Sora を bin/sora daemon で起動します

8. 最初のノード(sora1@192.0.2.101)の Sora に InitCluster APIを実行し、3 ノードのクラスターとして初期化します

   $ http POST 127.0.0.1:3001/ x-sora-target:Sora_20221221.InitCluster \
       node_name_list:='["[email protected]", "[email protected]", "[email protected]"]'
   

9. 最初のノード(sora1@192.0.2.101)の Sora に ListClusterNodes APIを実行し、ノード一覧を取得します

   $ http POST 127.0.0.1:3001/ x-sora-target:Sora_20211215.ListClusterNodes
   

結果として、 sora1@192.0.2.101 から sora3@192.0.2.103 の 3 ノードの一覧が取得できれば、クラスターの構築は完了です。

クラスター構築のトラブルシューティング

クラスター構築時に躓きやすいポイントと確認事項を示します。

• ノード間通信ができない場合

  • Sora はノード間通信を行うため、ファイアウォールの開放が必要です

  • クラスター構成情報ファイル にあるとおりに、EPMD と sora の Listen ポートの開放を確認してください

• ライセンス違反のエラーが出る場合

  • 最大ノード数ライセンス ではないライセンスを使っている場合には、すべてのノードで 異なるライセンスが設定されている必要があります

  • 最大ノード数ライセンス のライセンスを使っている場合には、指定されたノード数まで 同じライセンスを利用できます

  • 最大ノード数ライセンス とそうではないライセンスを混在させて利用することはできません

• RegisterClusterNode API 実行時に CONTACT-NODE-NOT-INITIALIZED エラーが出る場合

  • 未初期化のノードを contact_node_name に指定した場合に発生します

  • contact_node_name に指定するノードは InitCluster で初期化したノードか、 RegisterClusterNode API でクラスターに参加したノードを指定する必要があります

クラスター操作

上記のクラスターの構築の手順で、クラスターの構築と初期化が完了していることを前提とします。

クラスターのノード一覧の取得

構築済みのクラスター内のノード名 sora1@192.0.2.101、 sora2@192.0.2.102、 sora3@192.0.2.103 のいずれかで ListClusterNodes API を実行して、 クラスター内のノード一覧を取得します。

$ http POST 127.0.0.1:3000/ x-sora-target:Sora_20211215.ListClusterNodes
HTTP/1.1 200 OK
access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
access-control-allow-methods: POST, OPTIONS
access-control-allow-origin: *
access-control-max-age: 1000
content-length: 1057
content-type: application/json
date: Fri, 08 Dec 2023 07:51:19 GMT
server: Cowboy

[
    {
        "connected": true,
        "external_api_url": "https://sora-node1.example.com/api",
        "external_signaling_url": "wss://sora-node1.example.com/signaling",
        "license_max_connections": 100,
        "license_max_nodes": 3,
        "license_serial_code": "DOC123-SRA-E002-201303-N3-100",
        "license_type": "Experimental",
        "mode": "normal",
        "node_name": "[email protected]",
        "temporary_node": false,
        "version": "2024.1.0"
    },
    {
        "connected": true,
        "external_api_url": "https://sora-node2.example.com/api",
        "external_signaling_url": "wss://sora-node2.example.com/signaling",
        "license_max_connections": 100,
        "license_max_nodes": 3,
        "license_serial_code": "DOC123-SRA-E002-201303-N3-100",
        "license_type": "Experimental",
        "mode": "normal",
        "node_name": "[email protected]",
        "temporary_node": false,
        "version": "2024.1.0"
    },
    {
        "connected": true,
        "external_api_url": "https://sora-node3.example.com/api",
        "external_signaling_url": "wss://sora-node3.example.com/signaling",
        "license_max_connections": 100,
        "license_max_nodes": 3,
        "license_serial_code": "DOC123-SRA-E002-201303-N3-100",
        "license_type": "Experimental",
        "mode": "normal",
        "node_name": "[email protected]",
        "temporary_node": false,
        "version": "2024.1.0"
    }
]

クラスターチャネル割り当て一覧の取得

接続済みのチャネルのノードへの割り当てを確認するために、ListClusterChannels API を実行します。

まず、構築済みのクラスターに複数のチャネルで接続しておきます。

次に、クラスター内のいずれかのノードで ListClusterChannels API を実行して、クラスターのチャネル割り当ての一覧を取得し、チャネルと割り当てられているノードを確認します。

$ http POST 127.0.0.1:3000/ x-sora-target:Sora_20211215.ListClusterChannels
HTTP/1.1 200 OK
access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
access-control-allow-methods: POST, OPTIONS
access-control-allow-origin: *
access-control-max-age: 1000
content-length: 342
content-type: application/json
date: Mon, 11 Dec 2023 03:53:49 GMT
server: Cowboy

[
    {
        "channel_id": "hisui",
        "owners": [
            {
                "connected": true,
                "node_name": "[email protected]"
            }
        ]
    },
    {
        "channel_id": "kohaku",
        "owners": [
            {
                "connected": true,
                "node_name": "[email protected]"
            }
        ]
    },
    {
        "channel_id": "sora",
        "owners": [
            {
                "connected": true,
                "node_name": "[email protected]"
            }
        ]
    },
    {
        "channel_id": "zakuro",
        "owners": [
            {
                "connected": true,
                "node_name": "[email protected]"
            }
        ]
    }
]

クラスターからノードを消去する

構築済みのクラスター内からノードを消去してみます。

ここでは、ノード名 sora1@192.0.2.101、 sora2@192.0.2.102、 sora3@192.0.2.103 の 3 ノードで構築されているクラスターから、 sora3@192.0.2.103 のノードを消去します。

ノードの消去には PurgeClusterNode API を使用します。

初めに、 sora3@192.0.2.103 の Sora を bin/sora stop で停止します。

次に、 sora3@192.0.2.103 ノードの data/ ディレクトリを削除します。

sora1@192.0.2.101 のノードで ListClusterNodes API を実行して、 sora3@192.02.103 のノードについて "connected": false になっていることを確認します。

$ http POST 127.0.0.1:3000/ x-sora-target:Sora_20211215.ListClusterNodes
HTTP/1.1 200 OK
access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
access-control-allow-methods: POST, OPTIONS
access-control-allow-origin: *
access-control-max-age: 1000
content-length: 704
content-type: application/json
date: Fri, 08 Dec 2023 08:06:39 GMT
server: Cowboy

[
    {
        "connected": true,
        "external_api_url": "https://sora-node1.example.com/api",
        "external_signaling_url": "wss://sora-node1.example.com/signaling",
        "license_max_connections": 100,
        "license_max_nodes": 3,
        "license_serial_code": "DOC123-SRA-E002-201303-N3-100",
        "mode": "normal",
        "node_name": "[email protected]",
        "temporary_node": false,
        "version": "2024.1.0"
    },
    {
        "connected": true,
        "external_api_url": "https://sora-node2.example.com/api",
        "external_signaling_url": "wss://sora-node2.example.com/signaling",
        "license_max_connections": 100,
        "license_max_nodes": 3,
        "license_serial_code": "DOC123-SRA-E002-201303-N3-100",
        "license_type": "Experimental",
        "mode": "normal",
        "node_name": "[email protected]",
        "temporary_node": false,
        "version": "2024.1.0"
    },
    {
        "connected": false,
        "license_max_connections": 100,
        "license_max_nodes": 3,
        "license_serial_code": "DOC123-SRA-E002-201303-N3-100",
        "license_type": "Experimental",
        "node_name": "[email protected]",
        "temporary_node": false
    }
]

クラスターから sora3@192.0.2.103 ノードの情報を消去するために、 sora1@192.0.2.101 または sora2@192.0.2.102 ノードのいずれかで PurgeClusterNode API を実行します。 この API を実行する際の target_node_name には消去するノード名を指定します。 今回指定するノード名は、 sora3@192.0.2.103 です。

$ http POST 127.0.0.1:3000/ x-sora-target:Sora_20220629.PurgeClusterNode target_node_name=[email protected]
HTTP/1.1 200 OK
access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
access-control-allow-methods: POST, OPTIONS
access-control-allow-origin: *
access-control-max-age: 1000
content-length: 40
content-type: application/json
date: Mon, 11 Dec 2023 02:03:09 GMT
server: Cowboy

{
    "target_node_name": "[email protected]"
}

再度 sora1@192.0.2.101 のノードで ListClusterNodes API を実行して、 クラスターのノードから sora3@192.02.103 のノードが見えなくなっていることを確認します。

$ http POST 127.0.0.1:3000/ x-sora-target:Sora_20211215.ListClusterNodes
HTTP/1.1 200 OK
access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
access-control-allow-methods: POST, OPTIONS
access-control-allow-origin: *
access-control-max-age: 1000
content-length: 704
content-type: application/json
date: Fri, 08 Dec 2023 08:06:39 GMT
server: Cowboy

[
    {
        "connected": true,
        "external_api_url": "https://sora-node1.example.com/api",
        "external_signaling_url": "wss://sora-node1.example.com/signaling",
        "license_max_connections": 100,
        "license_max_nodes": 3,
        "license_serial_code": "DOC123-SRA-E002-201303-N3-100",
        "mode": "normal",
        "node_name": "[email protected]",
        "temporary_node": false,
        "version": "2024.1.0"
    },
    {
        "connected": true,
        "external_api_url": "https://sora-node2.example.com/api",
        "external_signaling_url": "wss://sora-node2.example.com/signaling",
        "license_max_connections": 100,
        "license_max_nodes": 3,
        "license_serial_code": "DOC123-SRA-E002-201303-N3-100",
        "license_type": "Experimental",
        "mode": "normal",
        "node_name": "[email protected]",
        "temporary_node": false,
        "version": "2024.1.0"
    }
]

クラスターにノードを追加する

構築済みのクラスターにノードを追加してみます。

ノード名 sora1@192.0.2.101、 sora2@192.0.2.102 の 2 ノードで構築されているクラスターへ、 API を使用して sora4@192.0.2.104 ノードを追加します。

ノードの追加には RegisterClusterNode API を使用します。

クラスターに sora4@192.0.2.104 ノードを追加するために、 sora4@192.0.2.104 ノードで RegisterClusterNode API を実行します。 この API を実行する際の contact_node_name には既存のクラスターのノード名を指定します。

今回指定するノード名は、 sora1@192.0.2.101 または sora2@192.0.2.102 のいずれかです。

$ http POST 127.0.0.1:3000/ x-sora-target:Sora_20211215.RegisterClusterNode contact_node_name=[email protected]
HTTP/1.1 200 OK
content-length: 80
content-type: application/json
date: Mon, 11 Dec 2023 02:33:35 GMT
server: Cowboy

{
    "node_name_list": [
        "[email protected]",
        "[email protected]",
        "[email protected]"
    ]
}

ListClusterNodes API を使用して、クラスターに追加されていることを確認します。

$ http POST 127.0.0.1:3000/ x-sora-target:Sora_20211215.ListClusterNodes
HTTP/1.1 200 OK
content-length: 1057
content-type: application/json
date: Mon, 11 Dec 2023 02:34:04 GMT
server: Cowboy

[
    {
        "connected": true,
        "external_api_url": "https://sora-node1.example.com/api",
        "external_signaling_url": "wss://sora-node1.example.com/signaling",
        "license_max_connections": 100,
        "license_max_nodes": 3,
        "license_serial_code": "DOC123-SRA-E002-201303-N3-100",
        "license_type": "Experimental",
        "mode": "normal",
        "node_name": "[email protected]",
        "temporary_node": false,
        "version": "2024.1.0"
    },
    {
        "connected": true,
        "external_api_url": "https://sora-node2.example.com/api",
        "external_signaling_url": "wss://sora-node2.example.com/signaling",
        "license_max_connections": 100,
        "license_max_nodes": 3,
        "license_serial_code": "DOC123-SRA-E002-201303-N3-100",
        "license_type": "Experimental",
        "mode": "normal",
        "node_name": "[email protected]",
        "temporary_node": false,
        "version": "2024.1.0"
    },
    {
        "connected": true,
        "external_api_url": "https://sora-node4.example.com/api",
        "external_signaling_url": "wss://sora-node4.example.com/signaling",
        "license_max_connections": 100,
        "license_max_nodes": 3,
        "license_serial_code": "DOC123-SRA-E002-201303-N3-100",
        "license_type": "Experimental",
        "mode": "normal",
        "node_name": "[email protected]",
        "temporary_node": false,
        "version": "2024.1.0"
    }
]

クラスター機能運用

注意

クラスター機能を利用する場合は事前にサポートまでご連絡ください

警告

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

不明点がある場合はサポートまでお問い合わせください。

クラスター利用時のファイル操作に問題が発生した場合

クラスター機能を利用している際に、ファイル操作に問題が発生した場合、 そのノードは 新規コネクションブロックモード へ移行します。

ファイル操作とはログ出力だったり、録画ファイルアーカイブ出力だったりです。

この状態が発生した場合、 ディスク破損、ディスク容量不足、パーミッション間違いなど、 致命的な問題が発生している可能性が高いため、ノードを停止し、問題の解決を行ってください。

問題があるノードを破棄する場合

レギュラーノードの場合は、 必ず PurgeClusterNode API を利用して対象のノードを消去し、新しいノードを追加してください。

テンポラリノードの場合は、そのまま破棄して問題ありません。

クラスターのレギュラーノード数

最低ノード数

Sora は最低 3 レギュラーノードのクラスターを構築してください。

• 1 レギュラーノードで構築されたクラスターはクラスターを構築していないのと同様です

• 2 レギュラーノードで構築されたクラスターは片方のノードが停止すると、正常なノードも過半数の条件を満たさなくなるため接続を受け付けなくなってしまいます

ノード数

3 レギュラーノードの次は 5 レギュラーノードのクラスターを構築してください。 4 レギュラーノードは 2 レギュラーノードがダウンした時点でクラスターが利用できなくなるため、3 レギュラーノードと可用性が変わらないためです。

5 レギュラーノード以上は、特に制限はありません。

クラスターのテンポラリーノード数

テンポラリーノードはレギュラーノードと違いクラスターの維持に影響しないため、最低ノード数の制限はありません。

最大ノード数

クラスターを構築するノードの最大数は 100 ノードを想定しています。 これ以上のノード数を検討されている場合はサポートまでご連絡ください。

クラスター利用時のライセンス

クラスターの 1 ノードにつき 1 ライセンスが必要になります。 3 台のノードでクラスターを構築する場合は 3 ライセンスが必要になります。

最大ノード数ライセンス

最大ノード数ライセンス を利用することで、同一ライセンスを複数ノードで利用できるようになります。

クラスターを利用する場合は 最大ノード数ライセンス を利用することを推奨します。

最大ノード数ライセンス への切り替えはサポートまでご連絡ください。

最大ノード数ライセンスのみで利用できる機能

クラスター機能のいくつかの機能は 最大ノード数ライセンス が必要になります。

• リレー機能

• リレー機能利用時のアフィニティ機能

• ライセンスで決められた最大同時接続数の合計を維持する機能

• テンポラリーノード機能

重要

最大ノード数ライセンス を利用せずに sora.conf でリレー機能やアフィニティ機能を有効にしても起動はできます。 ただし sora.jsonl に警告ログが出力されます。

ポートの開放

以下のポートを クラスターを組むその他のノードにのみ に対して開放して下さい。

危険

絶対にパブリックインターネットへの公開はしないでください。

• epmd（Erlang Port Mapper Daemon）で利用する TCP ポート

  • 4369

• ノード間通信に利用する TCP ポート

  • 49010 - 49020

  • sora.conf の cluster_listen_{min,max}_port にて範囲を指定できます

ノード間通信

Sora のノード間通信は TCP/IP を利用しています 。 そのため、安定したプライベートネットワークの利用を強く推奨します。

もし、マルチクラウドなどでノード間通信がパブリックネットワークを利用したクラスターを構築する場合は、 輻輳が発生する可能性があります。

そのため、特別な理由がない限りはプライベートネットワークを利用してください。

リレー機能利用時のノード間通信

Sora クラスターリレー機能利用時のノード間通信では、大量のネットワーク帯域を消費します。 そのためリレー機能を利用する場合は 可能な限り 同一データセンター内のプライベートネットワークを利用してください。

ノード間通信の暗号化

Sora のノード間通信は 暗号化されておりません 。 そのため、安全なプライベートネットワークの利用を推奨します。

もし、マルチクラウドなどでノード間通信がパブリックネットワークを利用したクラスターを構築する場合は、 ノード間の通信を暗号化する必要があります。その場合は Tailscale などの利用をお勧めします。

Tailscale · Best VPN Service for Secure Networks

参考までに、下記は弊社の Tailscale 利用事例です。

ベアメタルサーバーを利用したクラウドサービスで発生する課題を Tailscale で解決する · Tailscale

リレー機能利用時

重要

リレー機能を利用する際に、マルチクラウドでの利用は非推奨です。

リレー機能利用時にはノード間通信が大量に発生する場合があるため、暗号化に多くの CPU リソースを消費します。 そのため、プライベートネットワークを利用し、ノード間通信には暗号化を行わないことを推奨します。

テンポラリーノード機能の利用

3 ノードや 5 ノードのレギュラーノードで構築したクラスターを拡張する場合は、 テンポラリーノード機能の利用を検討してください。

テンポラリーノードは、クラスター維持に影響しないノードで、気軽に追加・削除できるノードです。

特にリレー機能利用時には、スケールアウト/スケールインが気軽に行えるようになるため、 レギュラーノードとテンポラリーノードを組み合わせてクラスターを構築することを推奨します。

クラスターからの一時的な離脱

モード切り替え API を利用し、 新規セッションブロックモード または 新規コネクションブロックモード に切り替えます。 その後、すべての接続がいなくなったタイミングでノードを終了してください。

一時的に離脱したノードは、再起動するとそのままクラスターに参加して動作します。

一時的に離脱したノードを含めるクラスターノード一覧

ListClusterNodes API では現在クラスターに登録している全てのノードの一覧が返ります。

注釈

結果に一時的に離脱したレギュラーノードを含めない場合には、 include_all_known_nodes に false を指定して API を実行します。

クラスターからレギュラーノード情報の完全消去

重要

恒久的にレギュラーノードを破棄する場合には、必ず、この作業を行ってください。

特定のレギュラーノードで障害が起きた後、復旧が難しい場合は PurgeClusterNode API を利用して、 クラスターに参加しているレギュラーノードから、障害が起きたレギュラーノードの情報を完全消去してください。

また、スケールインのためにレギュラーノードを破棄する場合も同様に PurgeClusterNode API を 利用して、破棄したレギュラーノードの情報を完全消去してください。

この作業はクラスターの新鮮さを保つために必要な作業となります。 この作業を行わないと存在していないレギュラーノードが残り続けることで過半数かどうかの判断を誤る場合があります。

警告

PurgeClusterNode API はクラスターからレギュラーノードを完全に消去するための API です。 近い将来に再び参加するレギュラーノードに対しては基本的に使用しないでください。

クラスターのローリングアップデート

重要

ローリングアップデートは並列で行うのではなく必ず 1 台ずつ行ってください。

1. アップデート対象のノードを ChangeMode API で 新規セッションブロックモード または 新規コネクションブロックモード に切り替えます

   • 必要があれば ListChannels API と DisconnectChannel API を利用して既存接続を切断します

2. すべての接続がなくなったら Sora を停止させます

3. 新しいバージョンの Sora へ入れ替えます

4. 新しいバージョンの Sora を起動します

5. ListClusterNodes API で新しいバージョンの Sora がクラスターに参加できているかを確認します

警告

自動でクラスターに参加する処理がエラーになる可能性もあるため、 ListClusterNodes API で新しいバージョンの Sora がクラスターに参加できているかを必ず確認してください。 確認せずに他ノードのローリングアップデートを行った場合、クラスターに参加できていないままのノードが出てしまう 可能性があります。 さらに、複数のノードが参加できずに過半数を割ってしまうと、クラスターがまったく稼働しなくなる可能性もあります。

上の手順を 1 ノードごとに繰り返してください。

アップデート対象のノードがローリングアップデートに成功したかどうかを確認する方法

ヘルスチェック機能 の /.ok を利用してください。

200 OK が返ってくればアップデートに成功し、クラスターへの再参加に成功しています。

成功を確認した後、 より詳細な状態が知りたい場合は ListClusterNodes API を実行してクラスターの状態を確認してください。

ローリングアップデート時に一時的に CLUSTER-NOT-INITIALIZED になる場合

アップデート対象のノードのアップデート後に ListClusterNodes API を実行した際に、 CLUSTER-NOT-INITIALIZED が返ってくる場合がありますが、これは一時的な状態です。

そのため、少し待って ListClusterNodes API を再度実行してください。

ローリングアップデートに成功したかどうかには ヘルスチェック機能 の /.ok を利用してください。

クラスターのローリングアップデート中の挙動

リレー機能の無効化

クラスターをローリングアップデートの最中に、 クラスターに複数のバージョンが混在するノードが存在する場合、 リレー機能は同一バージョン同士でしか行えません。

そのため、アフィニティ機能が無効な場合でも別ノードへのリダイレクトを試みる場合があります。

一部 API の local に false を指定することができない

クラスターをローリングアップデートの最中に、 クラスターに複数バージョンが混在するノードが存在する場合、 以下 API に local に false を指定することができません。

• ListConnections API

• ListChannels API

• GetStatsAllConnections API

• ListRtcStats API

• ListUserAgentStats API

Sora のバージョンダウン

クラスターのローリングアップデート の仕組みを使って、Sora のバージョンを下げることはできません。

そのため、クラスターのアップデート後に何らかの問題が発生し、 以前のバージョンに戻したい場合には、クラスターの再構築を行う必要があります。

再構築の際には、事前に全ノードを停止し、 data/ ディレクトリを削除した上で、 以前のバージョンの Sora を使用してクラスターの構築を行ってください。

Sora のローリングアップデート失敗

クラスターのローリングアップデート に失敗した場合は、クラスターの再構築が必要になります。

再構築の際には、事前に全ノードを停止し、 data/ ディレクトリを削除した上で、 新しいバージョンの Sora を使用してクラスターの再構築を行ってください。

ローリングアップデートの失敗判断

• 一定時間待っても ListClusterNodes API の戻り値のノード数が一致しない場合

• 一定時間待っても ListClusterNodes API の戻り値が CLUSTER-NOT-MAJORITY を返してくる場合

クラスター破綻からの再構築手順

クラスターのうち、過半数のノードが停止した場合、クラスターのすべてのノードは接続を受け付けなくなります。 この状態からでも、停止したノードを再開させ、過半数のノードが正常に戻ったタイミングで、接続を受け付け始めます。 その場合は、ここで書かれている手順は必要ありません。

ただし、停止したノードがディスク障害などで data/ ディレクトリを失ってしまったときや、使っていた IP アドレスが使えなくなってしまうなどの理由で、再開できないこともあります。

ここでは、3 ノードクラスターを組んでいたものの、うち 2 つのサーバーがディスク障害で data/ ディレクトリを失った状態からの再構築手順を示します。

注釈

data/ ディレクトリを失ってしまうと、「未初期化」状態になるため、再度クラスターへの参加手順が必要です。

注釈

node_name に IP アドレスを使う場合、IP アドレスが変わると node_name も変える必要があります。 その際は data/ ディレクトリを削除する必要があります。

• まずすべての Sora プロセスを停止状態にします

• ディスク障害がおきたサーバーでは

  • Sora をインストールしなおします

  • 必要に応じて sora.conf 設定を行います

• ディスク障害がおきなかったサーバーでは

  • data/ ディレクトリを削除します

  • これを忘れると正しい再構築ができません、必ず削除してください

• ここまでで、完全にまっさらの Sora クラスターを構築する準備ができたことになります

• すべてのノードを起動します

• InitCluster API を発行し、クラスターを初期化します

以上の手順で、あたらしい 3 ノードのクラスターが動き始めます。

ノード名変更手順

sora.conf の node_name を変更する際の手順を示します。

この手順は、例えば Sora が動作するサーバーの IP アドレスが変わり、 node_name の IP アドレス部分を 変更する場合に必要になります。

• 対象のノードを停止します

• data/ ディレクトリを削除します

  • これを忘れるとノード名変更が正しく実行できません、必ず削除してください

• クラスターの起動しているノードのいずれかに対し、 PurgeClusterNode API を発行し、 対象のノードをクラスターから削除します

• sora.conf の node_name を変更します

• 対象のノードを起動します

• RegisterClusterNode API でクラスターにあらたに登録します

警告

この手順では、 data/ ディレクトリの削除を含むため、対象のノードは「未初期化」状態になります。 複数のノードの名前変更が必要な場合には、1 ノードずつこの手順を実行することを推奨します。 1 ノードの変更のたびに、 ListClusterNodes を使ってクラスターに正しく 参加したことを確認して次のノードの手順に取り掛かってください。

ロードバランサーの導入

注意

ロードバランサーを導入する場合は事前にサポートまでご連絡ください。

クラスター機能を利用した場合は、シグナリング URL に対してロードバランサーが利用できます。

ただし、ロードバランス自体は Sora が行うため、 ロードバランサーの導入はシグナリング URL の 1 本化が目的となります。

• ロードバランサーは WebSocket に対応している必要があります

• ロードバランサーで TLS 終端はせず TLS で Sora へ接続する必要があります

• Sora はロードバランサー経由以外にクライアントと直接接続できる必要があります

  • これはリダイレクトが発生し、ロードバランサーを経由せずに接続する可能性があるためです

• Sora の WebSocket 通信は 30 秒に 1 回通信を発生させるため、ロードバランサーのタイムアウトは 30 秒以上にする必要があります

        sequenceDiagram
    participant C as クライアント
    participant LB as ロードバランサー
    participant S1 as Sora1
    participant S2 as Sora2
    participant A as アプリケーションサーバー
    C->>LB: wss://sora.example.com/signaling
    LB->>S1: wss://0001.sora.example.com/signaling
    note over B,S1: WebSocket 確立
    C->>+LB: "type": "connect"
    LB->>+S1: "type": "connect"
    S1-->>-LB: "type": "redirect"<br>"location": "wss://0002.sora.example.com/signaling"
    LB->>-C: "type": "redirect"<br>"location": "wss://0002.sora.example.com/signaling"
    note over B,S1: WebSocket 切断
    C->>S2: wss://0002.sora.example.com/signaling
    note over B,S1: WebSocket 確立
    C->>+S2: "type": "connect"
    S2->>+A: 認証ウェブフック
    A-->>-S2: "allowed": true
    S2->>-C: "type": "offer"
    C->>S2: "type": "answer"
    note over B,S2: WebRTC 確立
    

もしシグナリング URL の 1 本化を検討している方で、不明点がある場合はサポートまでご連絡ください。

ログの出力

クラスターに関するログは log/cluster.jsonl に生成されます。

ログの詳細については ログファイル をご確認ください。

クラスター構成情報ファイル

危険

このファイルは Sora が内部で利用するためのファイルのため、指示がある場合以外は触らないでください。

Sora でクラスターを利用する場合、クラスター参加後のノード情報を永続化するためのファイルを data/ ディレクトリ以下に生成します。

Sora のバージョンアップ時

Sora をバージョンアップする際には data/ ディレクトリをコピーを行わないでください。 このファイルが無い場合、 Sora の起動の際に生成されます。

クラスターからのレギュラーノードの完全消去について

クラスターからレギュラーノードを完全に消去させる場合は bin/sora stop で停止させた後に、 クラスターを構成してる実行中のノードのいずれかに対して、 消去するノードのノード名を target_node_name に指定して PurgeClusterNode API を実行します。

警告

PurgeClusterNode API はクラスターからレギュラーノードを完全に消去するための API です。 再度参加するレギュラーノードに対しては基本的に使用しないでください。

PurgeClusterNode API で完全消去したレギュラーノードの再度の参加

警告

PurgeClusterNode API はクラスターからレギュラーノードを完全に消去するための API です。 通常は、再度参加するレギュラーノードに対しては使用しないでください。 ここの説明は、長期間に渡ってクラスターに参加できないため、苦肉の策として PurgeClusterNode API を使った場合の説明です。

警告

PurgeClusterNode APIでクラスターから消去したレギュラーノードは、 以下に示す手順を経ずに再起動してはいけません。

クラスターからレギュラーノードを完全消去した場合、そのまま再度参加をすることはできません。 再度クラスターに参加する場合は data/ ディレクトリを削除する必要があります。

PurgeClusterNode API を実行して、さらにそのレギュラーノードの data/ ディレクトリを削除した場合、 そのレギュラーノードは完全に新規のレギュラーノードとして取り扱われます。

この状態になったレギュラーノードは新規レギュラーノードですので、 RegisterClusterNode API を利用してクラスターに登録できます。

クラスターから消去されたレギュラーノードを別クラスターに参加させたい場合

あるクラスター A に参加していたレギュラーノードを、A から削除して別のクラスター B に参加させたい状況を考えます。

警告

PurgeClusterNode API はクラスターからレギュラーノードを完全に消去するための API です。 現在参加しているクラスターで再利用するレギュラーノードに対しては使用しないでください。 Sora が稼働するサーバーを再利用して、別のクラスター B に参加する新規レギュラーノードが欲しい場合には、 Sora リリースの tar.gz を展開して、まっさらな状態からの新規レギュラーノード構築を推奨します。 ここの説明は、どうしても既存の tar.gz 展開ディレクトリを再利用したい場合の説明です。

PurgeClusterNode API で消去されたレギュラーノードは data/ ディレクトリ内のデータに以前参加していたクラスター A のノード群を覚えています。

そのため、再利用する場合には data/ ディレクトリを削除して、クラスター A に関する情報を無くす必要があります。

警告

以上の手順を踏まずに別クラスター B に参加させようとすると、最悪の場合には A と B がひとつになった クラスターになってしまう場合があります。

上記の手順の後は Sora を起動し、クラスター参加の手順に従って、レギュラーノードをクラスターに参加させます。

ネットワーク障害やノード障害

Sora のクラスター機能はネットワーク障害やノード障害が発生した際に、 自動で新規接続の受け付けの停止とそこからの復旧を試みます。

発生しうる問題と新規接続の受け付け停止

ネットワーク障害等が発生した場合には、 Sora のレギュラーノード間で通信ができず、クラスター内の情報の整合性が取れなくなる可能性があります。

たとえば、5 レギュラーノードのクラスターが 3 レギュラーノードからなるグループ A と 残りの 2 レギュラーノードからなるグループ B の 2 グループに分断されるということが起こりえます。 それぞれのグループ内では通信ができるものの、他グループへの通信ができないという状態です。

この状態ですべてのレギュラーノードが接続を受け付けると、同じチャネル ID を指定していても、 あるクライアントはグループ A に繋がり、別のクライアントは グルーブ B につながる可能性があり、 それぞれのクライアント間で音声と映像が届かなくなります。

このような状況を防止するため、Sora は自分が半数以下のグループに属した場合に、新規接続の受け付けを停止します。 また、レギュラーノード数が半数以下のクラスターに参加しているレギュラーノードは、接続中のすべての接続を切断し、その後は接続を受け入れません。

その後、クラスター自動復旧機能により、通信できるレギュラーノードが過半数のグループとなった場合には、自動で新規接続の受け付けを再開します。

全ノードが半数以下のグループに所属した場合の挙動

ネットワーク障害等が発生したことで、いずれのグループも通信できるレギュラーノードが半数以下になった場合、 どこグループでも新規接続はまったく受け付けられない状態になります。

この状態でも Sora は、永続化しておいたレギュラーノード一覧を利用し自動でクラスターの復旧を試みます。 そして、クラスターが復旧して過半数のグループができた場合は新規接続が可能になります。

クラスター機能録画

クラスターにおける録画機能

レガシー録画機能 と 録画(セッション単位)機能 はクラスター機能でも利用できます。

録画(セッション単位)機能

録画(セッション単位)機能はどのノードで録画を開始しても、セッション存在するノードで録画が行われます。 これはリレー機能を使い複数のノードにセッションがまたがっていても同様です。

全てのノードでセッションが破棄されたタイミングで録画も終了します。

レガシー録画機能

レガシー録画機能はどのノードで録画を開始しても、 録画開始時に指定したチャネル名であれば、全てのノードで録画が行われます。

警告

全てのノードでセッションが破棄されても、 録画の期限が切れるか、StopRecording API が呼ばれるまで録画は続きます。

録画ファイルの出力ノード

archive-<connection_id>.json, archive-<connection_id>.webm の録画ファイルは、接続を担当するノードで 出力されます。

次のような場合には同一の recording_id に属する録画ファイルが、 複数ノードにまたがって出力されることがありますのでご注意ください。

1. 録画機能(セッション単位) でチャネル ID を指定して録画開始

2. ノード A に指定したチャネル ID の接続が来てしばらくして切断、録画ファイルがノード A に作られる

3. ノード A が停止

4. ノード B に指定したチャネル ID に接続が来てしばらくして切断、録画ファイルがノード B に作られる

report-<recording_id>.json ファイルの出力ノード

あるチャネルに対して、 StopRecording API を実行した場合には録画が終了し、 report-<recording_id>.json ファイルが出力されます。

このファイルの出力ノードは次のとおりです。

• そのチャネルに接続したクライアントがひとつもなかった場合はどのノードで出力されるかは未定です

  • ただし、クラスター内のいずれかのノードで出力されます

• そのチャネルに接続中のクライアントがいる場合は、チャネルの担当ノードで出力されます

• そのチャネルに接続したクライアントが過去にいた場合は 2 パターンがありえます

  • クライアントが接続したノードが生存し続けている場合はそのノードで出力されます

  • ノードが落ちている、または停止した後に再起動した場合にはどのノードで出力されるかは未定です

    • ただし、クラスター内のいずれかのノードで出力されます

report-<recording_id>.json ファイルが一時的に出力されない場合

全ノードが半数以下に所属した場合には report-<recording_id>.json ファイルが出力されません。

5 ノードのクラスターがあるとして、いくつか例を示します。

• ネットワーク障害が発生し、2 + 2 + 1 に分断された場合

• ノード障害(運用での停止も含む)が発生し、3 ノードが停止した場合

• ノード障害で 1 ノードが停止した状態でネットワーク障害が発生し、 2 + 2 に分断された場合

このあとに分断が解消し、過半数のグループができたあとに StopRecording API を 実行すると report-<recording_id>.json ファイルが出力されます。

report-<recording_id>.json ファイルの archives の内容と実際に出力される録画ファイルが一致しない場合

録画中のノードがクラスターから分離された場合に report-<recording_id>.json ファイルの archives に全ての録画ファイルが含まれないケースがあります。

録画中のノードがクラスターから分離された場合は別のノードが report-<recording_id>.json ファイルを出力しますが、クラスター分離前に共有された録画情報の内容で出力し、 分離直後に作成された録画ファイルは含まれないためです。

クラスター API

InitCluster

x-sora-target:

Sora_20221221.InitCluster

クラスターを初期化する際に実行する必要がある API です。

クラスター初期化時に、参加させるいずれかのノードに対して行ってください。

node_name_list にはクラスターに参加するノードのリストを指定してください。 API が成功すると、そのリストのノードで構成されるクラスターが構築されます。

Tip

InitCluster API の実行はひとつのクラスターにつき一度だけ必要です。 InitCluster API 後に、そのクラスターにノードを追加する場合には RegisterClusterNode API を使います。

InitCluster API が次に必要になるのはクラスターが破綻した場合です。 詳細は クラスター破綻からの再構築手順 を参照してください。

キー	型
node_name_list	array of string

$ http POST 127.0.0.1:3000/ x-sora-target:Sora_20221221.InitCluster \
    node_name_list:='["[email protected]", "[email protected]", "[email protected]"]'

RegisterClusterNode

x-sora-target:

Sora_20211215.RegisterClusterNode

指定したクラスターにノードを登録します。

登録したいクラスターに属するノードのいずれかを contact_node_name で指定してください。 クラスターに属していれば、どのノードでもかまいません。

• 登録したいクラスターがすでに初期化されている必要があります。

• クラスターに登録するためには、登録したいクラスターの過半数のノードが正常に稼働している必要があります

注釈

新規にクラスターを作成する場合には、まず InitCluster API を使用してください。

キー	型
contact_node_name	string

$ http POST 127.0.0.1:3000/ x-sora-target:Sora_20211215.RegisterClusterNode \
    contact_node_name=[email protected] \
    -vvv
POST / HTTP/1.1
Accept: application/json, */*
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 42
Content-Type: application/json
Host: 127.0.0.1:3000
User-Agent: HTTPie/1.0.3
x-sora-target: Sora_20211215.RegisterClusterNode

{
    "contact_node_name": "[email protected]"
}

HTTP/1.1 200 OK
access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
access-control-allow-methods: POST, OPTIONS
access-control-allow-origin: http://127.0.0.1:5000
access-control-max-age: 1000
content-length: 116
content-type: application/json
date: Tue, 16 Nov 2021 09:28:11 GMT
server: Cowboy

{
    "node_name_list": [
        "[email protected]",
        "[email protected]",
        "[email protected]",
        "[email protected]",
        "[email protected]"
    ]
}

ListClusterNodes

x-sora-target:

Sora_20211215.ListClusterNodes

クラスターのノード一覧を表示します。

一時的に離脱しているノードの場合は connected が false になります。

出力対象のノードが離脱中、またはノードの情報取得に失敗した場合には以下の項目は出力されません。

• external_api_url

• external_signaling_url

• version

• mode

レスポンス JSON

キー	型	内容
external_api_url	string	sora.conf の external_api_url
license_max_nodes	integer	ライセンスの最大ノード数
license_max_connections	integer	ライセンスの最大同時接続数
license_serial_code	string	ライセンスのシリアルコード
license_type	string	ライセンスのタイプ
node_name	string	sora.conf の node_name
error	string	API 実行ノードと正常に接続はできているが、情報の取得に失敗した際のエラー理由
connected	boolean	API 実行ノードと正常に接続できているかどうか
external_signaling_url	string	sora.conf の external_signaling_url
temporary_node	boolean	テンポラリーノードかどうか
version	string	Sora のバージョン
mode	string	モード (normal / block_new_session / block_new_connection)

$ http POST 127.0.0.1:3000/ \
    x-sora-target:Sora_20211215.ListClusterNodes \
    -vvv
POST / HTTP/1.1
Accept: */*
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 0
Host: 127.0.0.1:3000
User-Agent: HTTPie/1.0.3
x-sora-target: Sora_20211215.ListClusterNodes



HTTP/1.1 200 OK
access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
access-control-allow-methods: POST, OPTIONS
access-control-allow-origin: http://127.0.0.1:5000
access-control-max-age: 1000
content-length: 1554
content-type: application/json
date: Tue, 16 Nov 2021 09:22:16 GMT
server: Cowboy

[
    {
        "external_api_url": "http://192.0.2.5:3000/",
        "license_max_connections": 500,
        "license_max_nodes": 10,
        "license_serial_code": "ABCDEF-SRA-E001-203801-N3-100",
        "license_type": "Experimental",
        "node_name": "[email protected]",
        "mode": "normal",
        "connected": true,
        "external_signaling_url": "wss://node-01.example.com/signaling",
        "version": "2024.1.0",
        "temporary_node": false
    },
    {
        "api_url": "http://192.0.2.7:3000/",
        "license_max_connections": 500,
        "license_max_nodes": 10,
        "license_serial_code": "ABCDEF-SRA-E002-203801-N3-100",
        "license_type": "Experimental",
        "node_name": "[email protected]",
        "mode": "normal",
        "connected": true,
        "external_signaling_url": "wss://node-02.example.com/signaling",
        "version": "2024.1.0",
        "temporary_node": false
    },
    {
        "license_max_connections": 500,
        "license_max_nodes": 10,
        "license_serial_code": "ABCDEF-SRA-E003-203801-N3-100",
        "license_type": "Experimental",
        "node_name": "[email protected]",
        "connected": false,
        "temporary_node": false
    },
    {
        "error": "{error,{erpc,timeout}}",
        "license_max_connections": 500,
        "license_max_nodes": 10,
        "license_serial_code": "ABCDEF-SRA-E004-203801-N3-100",
        "license_type": "Experimental",
        "node_name": "[email protected]",
        "connected": false,
        "temporary_node": false
    }
]

ListClusterChannels

x-sora-target:

Sora_20211215.ListClusterChannels

クラスターチャネル割り当て一覧を表示します。

キー	型	内容
channel_id	string	チャネル ID
owners	string	担当ノード

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

キー	型	内容
node_name	string	ノード名
connected	boolean	担当ノードが API 実行ノードと正常に接続できているかどうか

$ http POST 127.0.0.1:3000/ \
    x-sora-target:Sora_20211215.ListClusterChannels \
    -vvv
POST / HTTP/1.1
Accept: */*
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 0
Host: 127.0.0.1:3000
User-Agent: HTTPie/1.0.3
x-sora-target: Sora_20211215.ListClusterChannels



HTTP/1.1 200 OK
access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
access-control-allow-methods: POST, OPTIONS
access-control-allow-origin: http://127.0.0.1:5000
access-control-max-age: 1000
content-length: 341
content-type: application/json
date: Tue, 16 Nov 2021 08:42:25 GMT
server: Cowboy

[
    {
        "channel_id": "sora",
        "owners": [
           {
               "node_name": "[email protected]",
               "connected": true
           }
        ]
    },
    {
        "channel_id": "lemon",
        "owners": [
           {
               "node_name": "[email protected]",
               "connected": true
           }
        ]
    },
    {
        "channel_id": "hisui",
        "owners": [
           {
               "node_name": "[email protected]",
               "connected": true
           }
        ]
    },
    {
        "channel_id": "zakuro",
        "owners": [
           {
               "node_name": "[email protected]",
               "connected": true
           }
        ]
    }
]

PurgeClusterNode

x-sora-target:

Sora_20220629.PurgeClusterNode

復旧がすぐには難しい障害が発生したノードや、縮退し再参加する予定が無いノードの情報をクラスターから完全に消去します。

この API は 1 クラスターにつき 1 回実行すればすべての参加ノードから指定したノード情報が完全に消去されます。

• この API の実行時には、消去対象のノードは停止している必要があります

• この API が正常に完了するためには、過半数のノードが正常に稼働している必要があります

• API を実行するノードは、クラスターに参加していて、正常に稼働しているノードであればどのノードでもかまいません

警告

PurgeClusterNode API はクラスターからノードを完全に消去するための API です。 再参加するノードに対しては基本的に使用しないでください。 この API を含めた運用の手順は クラスター機能運用 をご確認ください。

キー	型
target_node_name	string

$ http POST 127.0.0.1:3000/ x-sora-target:Sora_20220629.PurgeClusterNode \
    target_node_name=[email protected] \
    -vvv
POST / HTTP/1.1
Accept: application/json, */*;q=0.5
Accept-Encoding: gzip, deflate, br
Connection: keep-alive
Content-Length: 39
Content-Type: application/json
Host: 127.0.0.1:3000
User-Agent: HTTPie/3.2.1
x-sora-target: Sora_20220629.PurgeClusterNode

{
    "target_node_name": "[email protected]"
}


HTTP/1.1 200 OK
access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
access-control-allow-methods: POST, OPTIONS
access-control-allow-origin: http://127.0.0.1:3000
access-control-max-age: 1000
content-length: 38
content-type: application/json
date: Sun, 12 Jun 2022 03:13:42 GMT
server: Cowboy

{
    "target_node_name": "[email protected]"
}

$ http POST 127.0.0.1:3001/ x-sora-target:Sora_20220629.PurgeClusterNode \
    target_node_name=[email protected] \
        -vvv
POST / HTTP/1.1
Accept: application/json, */*;q=0.5
Accept-Encoding: gzip, deflate, br
Connection: keep-alive
Content-Length: 39
Content-Type: application/json
Host: 127.0.0.1:3000
User-Agent: HTTPie/3.2.1
x-sora-target: Sora_20220629.PurgeClusterNode

{
    "target_node_name": "[email protected]"
}


HTTP/1.1 400 Bad Request
access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
access-control-allow-methods: POST, OPTIONS
access-control-allow-origin: http://127.0.0.1:3000
access-control-max-age: 1000
content-length: 79
content-type: application/json
date: Sun, 12 Jun 2022 03:13:29 GMT
server: Cowboy

{
    "error_reason": {
        "target_node": "[email protected]"
    },
    "error_type": "NODE-IS-ALIVE"
}

開発者ツール

概要

時雨堂がオープンソースとして開発している Sora DevTools を Sora に組み込んで利用できるようにしています。

目的

• Sora の機能を試してもらう

• Sora を利用したアプリケーションの開発中に機能を確認する

• Sora で何か問題が発生した場合に再現を行ってもらう

設定

警告

商用環境ではこの設定は利用せず、開発環境でのみ有効にしてください。

sora.conf にて devtools を true にすることで利用できるようになります。

devtools = true

オープンソース版

重要

オープンソース版 Sora DevTools はサポート対象外です。 サポートを受ける場合は必ず Sora に組み込まれている開発ツール機能を利用して下さい。

Sora に組み込まれている開発者ツールはオープンソースとして GitHub にて Apache License 2.0 で公開されています。

shiguredo/sora-devtools: Sora DevTools

サポートについて

オープンソースの Sora DevTools は Sora のサポートには含まれません。

Discord

https://discord.gg/shiguredo

Discord にてコミュニティを運営しています。 なにか質問したい場合は Discord サーバーへ参加してください。

開発者ツールについての質問やバグ報告は Discord の #sora-tool-faq チャンネルにお願いします。

マルチストリーム機能

概要

重要

Sora ではデフォルトでマルチストリームを利用します。

マルチストリームとは一つのコネクションの中で複数の映像や音声を動的に追加したり削除したりする仕組みです。 この機能を利用することで、複数のコネクションを管理せずに複数の映像や音声、データのやりとりが利用できます。

制限

• 配信側は音声 1 トラック、映像 1 トラック固定です

• 動的に配信側のトラックを追加したりするマルチトラックには対応していません

シグナリング仕様

重要

Sora の SDK を利用する場合は、ここに書かれているシグナリングの仕様を把握する必要は基本的にありません。

マルチストリームを利用する場合は、ユーザーが参加や離脱をするたびに SDP を交換する必要があります。

"type": "connect"

マルチストリームはデフォルトで有効になっています。

{
  "type": "connect",
  "role": "sendrecv",
  "channel_id": "sora"
}

"type": "re-offer"

{
  "type": "re-offer",
  "sdp": ".."
}

"type": "re-answer"

"type": "re-offer" が送られてきた場合、 クライアントから Sora へ送るメッセージは "type": "re-answer" を送る必要があります。

{
  "type": "re-answer",
  "sdp": ".."
}

role

マルチストリームでは role に sendrecv と sendonly と recvonly を指定できます。

• sendrecv は配信と視聴を行います

• sendonly は配信のみを行います

• recvonly は視聴のみを行います

マルチストリームにおける映像ビットレート自動シェアリング機能

重要

ビットレート自動シェアリング機能はデフォルトで有効になっています。

音声のビットレートには影響しません

マルチストリームでは複数の映像を大量に受信するため、 配信側の映像ビットレートを、参加している配信者全員でシェアする機能がデフォルトで有効になっています。

そのため、マルチストリームにおける video の bit_rate は、 非マルチストリームの bit_rate とは扱いが異なります。

例えば、 bit_rate を 1200 と指定した場合、 2 人で配信している場合はそれぞれ配信に 600 kbps ずつ使用します。 ここに 1 人が加わり 3 人になると、 1 人 400 kbps ずつ使用して配信するようになります。

また、ここに 5 人が加わり、合計で 8 人になると、 1 人 150 kbps ずつ使用して配信するようになります。

配信の合計のビットレートを指定するのが video の bit_rate です。

同じチャネルに参加している人が異なる bit_rate を指定した場合

2 人が同じチャネルに参加している状態で、1 人は映像のビットレートを 500 、もう 1 人は 1000 を指定して接続しているとします。 その場合、Sora では 500 を指定した人は配信に 250 kbps を使用し、 1000 を指定した人は配信に 500 kbps を使用します。

ビットレート自動シェアリング機能が適用されない条件

マルチストリームにおいても、以下の条件ではシェアされず、 bit_rate で指定した値を使います。

• スポットライトの場合

• サイマルキャストの場合

無効にする場合

sora.conf の multistream_auto_sharing_video_bit_rate を false に指定することで無効にできます。

注釈

設定を無効にした状態で、高いビットレートの配信者が増えていく場合、 クライアント側の転送量が増え、さらにデコードの負荷も高くなってしまいます。 そのため配信が安定的にできなくなり、結果的にクライアント側で配信ビットレートを下げるといった挙動が発生します。

参加者が増えた場合でも高いビットレートを維持したいという状況ではない限りは設定を無効にすることは推奨しません。

シーケンス図

        sequenceDiagram
    autonumber
    participant C1 as クライアント1
    participant C2 as クライアント2
    participant S as Sora
    note over C1,S: クライアント1 認証成功
    S->>+C1: "type": "offer"
    C1->>-S: "type": "answer"
    note over C1,S: クライアント1 WebRTC 確立
    S->>C1: シグナリング通知<br/>クライアント1<br/>"type": "connection.created"
    note over C1,S: クライアント2 認証成功
    S->>+C2: "type": "offer"
    C2->>-S: "type": "answer"
    S->>+C1: "type": "re-offer"
    C1->>-S: "type": "re-answer"
    note over C1,S: クライアント2 WebRTC 確立
    par
        S->>C2: シグナリング通知<br/>クライアント1<br/>"type": "connection.created"
    and

        S->>C1: シグナリング通知<br/>クライアント2<br/>"type": "connection.created"
    end
    C2->>S: "type": "disconnect"
    S->>C2: WebSocket Close
    S->>C1: シグナリング通知<br/>クライアント2<br/>"type": "connection.destroyed"
    

サイマルキャスト機能

概要

サイマルキャスト (Simulcast) は、配信時に 1 つの RTCPeerConnection から複数種類のエンコードした映像を配信する技術です。

映像を配信する際、 Sora に対して、 1 つの RTCPeerConnection で複数種類のエンコードした映像を送信することにより、 受信者がどの映像を受信するかを選択できるようになります。

注意

現時点でのサイマルキャストの仕様

2024 年 12 月 時点で libwebrtc を利用したサイマルキャストで出力されるストリームの本数は解像度とビットレートに依存しています。

VP8 / AV1 / H264

解像度とビットレートとストリーム数の関係

解像度	ビットレート	ストリーム数
1920x1080	5000 kbps	3
1280x720	2500 kbps	3
960x540	1200 kbps	3
640x360	700 kbps	2
480x270	450 kbps	2
320x180	200 kbps	1

VP9 / H265

解像度とビットレートとストリーム数の関係

解像度	ビットレート	ストリーム数
1920x1080	3367 kbps	3
1280x720	1524 kbps	3
960x540	879 kbps	3
640x360	420 kbps	2
480x270	257 kbps	1
320x180	142 kbps	1
240x135	101 kbps	1

libwebrtc の仕様

この値は libwebrtc にハードコードされています。 VP8 (AV1/H264) と VP9(H265) で異なります。

// These tables describe from which resolution we can use how many
// simulcast layers at what bitrates (maximum, target, and minimum).
// Important!! Keep this table from high resolution to low resolution.
constexpr const SimulcastFormat kSimulcastFormatsVP8[] = {
    {1920, 1080, 3, webrtc::DataRate::KilobitsPerSec(5000),
    webrtc::DataRate::KilobitsPerSec(4000),
    webrtc::DataRate::KilobitsPerSec(800)},
    {1280, 720, 3, webrtc::DataRate::KilobitsPerSec(2500),
    webrtc::DataRate::KilobitsPerSec(2500),
    webrtc::DataRate::KilobitsPerSec(600)},
    {960, 540, 3, webrtc::DataRate::KilobitsPerSec(1200),
    webrtc::DataRate::KilobitsPerSec(1200),
    webrtc::DataRate::KilobitsPerSec(350)},
    {640, 360, 2, webrtc::DataRate::KilobitsPerSec(700),
    webrtc::DataRate::KilobitsPerSec(500),
    webrtc::DataRate::KilobitsPerSec(150)},
    {480, 270, 2, webrtc::DataRate::KilobitsPerSec(450),
    webrtc::DataRate::KilobitsPerSec(350),
    webrtc::DataRate::KilobitsPerSec(150)},
    {320, 180, 1, webrtc::DataRate::KilobitsPerSec(200),
    webrtc::DataRate::KilobitsPerSec(150),
    webrtc::DataRate::KilobitsPerSec(30)},
    // As the resolution goes down, interpolate the target and max bitrates down
    // towards zero. The min bitrate is still limited at 30 kbps and the target
    // and the max will be capped from below accordingly.
    {0, 0, 1, webrtc::DataRate::KilobitsPerSec(0),
    webrtc::DataRate::KilobitsPerSec(0),
    webrtc::DataRate::KilobitsPerSec(30)}};

// These tables describe from which resolution we can use how many
// simulcast layers at what bitrates (maximum, target, and minimum).
// Important!! Keep this table from high resolution to low resolution.
constexpr const SimulcastFormat kSimulcastFormatsVP9[] = {
    {1920, 1080, 3, webrtc::DataRate::KilobitsPerSec(3367),
    webrtc::DataRate::KilobitsPerSec(3367),
    webrtc::DataRate::KilobitsPerSec(769)},
    {1280, 720, 3, webrtc::DataRate::KilobitsPerSec(1524),
    webrtc::DataRate::KilobitsPerSec(1524),
    webrtc::DataRate::KilobitsPerSec(481)},
    {960, 540, 3, webrtc::DataRate::KilobitsPerSec(879),
    webrtc::DataRate::KilobitsPerSec(879),
    webrtc::DataRate::KilobitsPerSec(337)},
    {640, 360, 2, webrtc::DataRate::KilobitsPerSec(420),
    webrtc::DataRate::KilobitsPerSec(420),
    webrtc::DataRate::KilobitsPerSec(193)},
    {480, 270, 2, webrtc::DataRate::KilobitsPerSec(257),
    webrtc::DataRate::KilobitsPerSec(257),
    webrtc::DataRate::KilobitsPerSec(121)},
    {320, 180, 1, webrtc::DataRate::KilobitsPerSec(142),
    webrtc::DataRate::KilobitsPerSec(142),
    webrtc::DataRate::KilobitsPerSec(49)},
    {240, 135, 1, webrtc::DataRate::KilobitsPerSec(101),
    webrtc::DataRate::KilobitsPerSec(101),
    webrtc::DataRate::KilobitsPerSec(30)},
    // As the resolution goes down, interpolate the target and max bitrates down
    // towards zero. The min bitrate is still limited at 30 kbps and the target
    // and the max will be capped from below accordingly.
    {0, 0, 1, webrtc::DataRate::KilobitsPerSec(0),
    webrtc::DataRate::KilobitsPerSec(0),
    webrtc::DataRate::KilobitsPerSec(30)}};

// TODO(crbugs.com/41480904): For now this table is just a copy from VP9, and
// needs to be tuned for H.265.
// These tables describe from which resolution we can use how many simulcast
// layers at what bitrates (maximum, target, and minimum).
// Important!! Keep this table from high resolution to low resolution.
constexpr const SimulcastFormat kSimulcastFormatsH265[] = {
    {1920, 1080, 3, webrtc::DataRate::KilobitsPerSec(3367),
    webrtc::DataRate::KilobitsPerSec(3367),
    webrtc::DataRate::KilobitsPerSec(769)},
    {1280, 720, 3, webrtc::DataRate::KilobitsPerSec(1524),
    webrtc::DataRate::KilobitsPerSec(1524),
    webrtc::DataRate::KilobitsPerSec(481)},
    {960, 540, 3, webrtc::DataRate::KilobitsPerSec(879),
    webrtc::DataRate::KilobitsPerSec(879),
    webrtc::DataRate::KilobitsPerSec(337)},
    {640, 360, 2, webrtc::DataRate::KilobitsPerSec(420),
    webrtc::DataRate::KilobitsPerSec(420),
    webrtc::DataRate::KilobitsPerSec(193)},
    {480, 270, 2, webrtc::DataRate::KilobitsPerSec(257),
    webrtc::DataRate::KilobitsPerSec(257),
    webrtc::DataRate::KilobitsPerSec(121)},
    {320, 180, 1, webrtc::DataRate::KilobitsPerSec(142),
    webrtc::DataRate::KilobitsPerSec(142),
    webrtc::DataRate::KilobitsPerSec(30)},
    {240, 135, 1, webrtc::DataRate::KilobitsPerSec(101),
    webrtc::DataRate::KilobitsPerSec(101),
    webrtc::DataRate::KilobitsPerSec(30)},
    // As the resolution goes down, interpolate the target and max bitrates down
    // towards zero. The min bitrate is still limited at 30 kbps and the target
    // and the max will be capped from below accordingly.
    {0, 0, 1, webrtc::DataRate::KilobitsPerSec(0),
    webrtc::DataRate::KilobitsPerSec(0),
    webrtc::DataRate::KilobitsPerSec(30)}};

https://source.chromium.org/chromium/chromium/src/+/main:third_party/webrtc/video/config/simulcast.cc

SDK 対応状況

最新版の JavaScript SDKでは、配信と視聴ともに VP8 と VP9 と AV1 と H.264 と H.265 に対応済みです。

最新版の iOS SDK, Android SDK, Unity SDK, C++ SDK は VP8 と VP9 と AV1 と H.264 に対応済みです。

配信ブラウザの対応状況

配信側は Chrome と Edge と Safari の最新バージョンに対応しています。

警告

Firefox は配信に対応していません。

視聴ブラウザの対応状況

視聴側は Chrome と Safari と Firefox と Edge の最新バージョンに対応しています。

警告

Firefox は AV1 に対応していません。

映像コーデック

配信時に利用できる映像コーデックは VP8 と VP9 と AV1 と H.264 と H.265 です。

VP9 と AV1 でのサイマルキャスト

VP9 や AV1 でサイマルキャストを行う場合、ブラウザでは配信側が Chrome 113 / Edge 113 以降である必要があります。 また設定では scalabilityMode と scaleResolutionDownBy または scaleResolutionDownTo のどちらかの 2 つを設定する必要があります。

詳細は scalabilityMode を参照してください。

H.265 でのサイマルキャスト

H.265 でサイマルキャストを行う場合、 ブラウザでは配信側が Safari 18.0 以降を利用する必要があり、 視聴側も同様に Safari 18.0 以降を利用する必要があります。

非対応機能

以下は今後対応予定です

• ULPFEC 機能には対応していません

映像の優先度

サイマルキャストでは 1 つのクライアントからの同じ映像を複数のエンコードで配信できます。

Sora では 1 つのクライアントから最大 3 種類のエンコードで映像を受信する仕組みが入っています。 この 3 種類の映像のそれぞれに r0 / r1 / r2 の 3 つの値を定義しています。 この値は rid と呼ばれています。

配信継続の優先度は r0 > r1 > r2 です。

例えば、回線が不安定だったりマシンの負荷が高かった場合、rid が r2 の映像の配信が最初に停止します。 さらに配信状況が悪化した場合は rid が r1 の映像の配信が停止します。 r0 の映像は必ず配信されます。

映像の種類のデフォルト

Sora ではサイマルキャストで配信する映像の種類にデフォルト値を設定しています。

[
  {"rid": "r0", "active": true, "scalabilityMode": "L1T1", "scaleResolutionDownBy": 4.0},
  {"rid": "r1", "active": true, "scalabilityMode": "L1T1", "scaleResolutionDownBy": 2.0},
  {"rid": "r2", "active": true, "scalabilityMode": "L1T1", "scaleResolutionDownBy": 1.0}
]

r0

rid が r0 の場合は通常の解像度から解像度 (一辺) が 1/4 の映像になるように設定されています。

r1

rid が r1 の場合は通常の解像度から解像度 (一辺) が 1/2 の映像になるように設定されています。

r2

rid が r2 の場合は通常の解像度のままの映像に設定されています。

映像のエンコーディングパラメーターのカスタマイズ

Sora ではサイマルキャストでの映像のエンコーディングパラメーターを自由に設定できます。

• sora.conf のファイルで指定することで全体のサイマルキャストのエンコーディングパラメーターが指定できます

• 認証成功時に simulcast_encodings で払い出すことで個別にサイマルキャストのエンコーディングパラメーターが指定できます

sora.conf でファイル指定

sora.conf にて simulcast_encodings_file で JSON を指定してください。

simulcast_encodings_file = etc/simulcast_encodings.json

sora.conf で指定する JSON ファイルの記述方法

[
  {"rid": "r0", "active": true, "scaleResolutionDownBy": 2.0, "maxFramerate": 5.0},
  {"rid": "r1", "active": true, "scaleResolutionDownBy": 2.0, "maxFramerate": 20.0},
  {"rid": "r2", "active": true, "scaleResolutionDownBy": 1.0, "maxFramerate": 30.0}
]

認証成功時に simulcast_encodings で払い出す記述方法

{
  "allowed": true,
  "simulcast_encodings": [
    {"rid": "r0", "active": true, "scaleResolutionDownBy": 2.0, "maxFramerate": 5.0},
    {"rid": "r1", "active": true, "scaleResolutionDownBy": 2.0, "maxFramerate": 20.0},
    {"rid": "r2", "active": true, "scaleResolutionDownBy": 1.0, "maxFramerate": 30.0}
  ]
}

カスタマイズの設定

• rid

  • 必須

  • string (r0 / r1 / r2)

  • https://www.w3.org/TR/webrtc/#dom-rtcrtpcodingparameters-rid

• active

  • このエンコーディングパラメーターを有効にします

  • オプション

  • boolean

  • https://www.w3.org/TR/webrtc/#dom-rtcrtpencodingparameters-active

• scaleResolutionDownBy

  • オプション

  • 1 以上の number (float または integer)

  • https://www.w3.org/TR/webrtc/#dom-rtcrtpencodingparameters-scaleresolutiondownby

• maxBitrate

  • オプション

  • 最大ビットレートを指定する

  • 0 以上の integer

  • https://www.w3.org/TR/webrtc/#dom-rtcrtpencodingparameters-maxbitrate

• maxFramerate

  • オプション

  • 最大フレームレートを指定する

  • 0 以上の number (float または integer)

  • https://www.w3.org/TR/webrtc/#dom-rtcrtpencodingparameters-maxframerate

• scaleResolutionDownTo

  • この設定は Chrome 131 / Edge 131 以降でしか利用できません

  • オプション

  • {"maxHeight": 1080, "maxWidth": 1920} のような JSON Object

  • maxHeight と maxWidth は 0 よりも大きい整数

  • scaleResolutionDownBy よりも優先されます

  • maxHeight と maxWidth の両方が指定されている場合に有効です

  • https://chromestatus.com/feature/5206373705711616

  • https://w3c.github.io/webrtc-extensions/#dom-rtcrtpencodingparameters-scaleresolutiondownto

• adaptivePtime

  • この設定は Chrome でしか利用できません

  • オプション

  • boolean

  • https://w3c.github.io/webrtc-extensions/#dom-rtcrtpencodingparameters-adaptiveptime

• scalabilityMode

  • この設定は Chrome / Edge でしか利用できません

  • オプション

  • string

  • https://chromestatus.com/feature/5769626174619648

  • https://www.w3.org/TR/webrtc-svc/#dom-rtcrtpencodingparameters-scalabilitymode

active: false の挙動

r1 の active を false にカスタマイズしている配信で r1 を受信をリクエストした場合、r0 が配信されます。

[
  {"rid": "r0", "active": true},
  {"rid": "r1", "active": false},
  {"rid": "r2", "active": true}
]

r0 の active を false にカスタマイズしている配信で r0 を受信をリクエストした場合、r1 が配信されます。

[
  {"rid": "r0", "active": false},
  {"rid": "r1", "active": true},
  {"rid": "r2", "active": true}
]

r0 と r1 の active を false にカスタマイズしている配信で r0 を受信をリクエストした場合、r2 が配信されます。

[
  {"rid": "r0", "active": false},
  {"rid": "r1", "active": false},
  {"rid": "r2", "active": true}
]

scalabilityMode

この設定は Chrome / Edge M113 以降でのみ有効です

注釈

PSA: VP9/AV1 simulcast support in M113

VP9 または AV1 でサイマルキャストを利用する場合の条件として、 scalabilityMode と scaleResolutionDownBy または scaleResolutionDownTo のどちらかをすべての rid に対して設定する必要があります。

サイマルキャスト利用時に scalabilityMode に設定可能な値は L1T1 、 L1T2 、 L1T3 のみです。

デフォルトでは L1T1 が指定されています。特に理由がなければ L1T1 を利用してください。

重要

AV1 でサイマルキャストやスポットライトを利用し、録画をする場合は L1T1 を利用してください。 L1T1 以外では正常に録画がされません。

例

[
  {"rid": "r0", "active": true, "scaleResolutionDownBy": 4.0, "scalabilityMode": "L1T3"},
  {"rid": "r1", "active": true, "scaleResolutionDownBy": 2.0, "scalabilityMode": "L1T3"},
  {"rid": "r2", "active": true, "scaleResolutionDownBy": 1.0, "scalabilityMode": "L1T3"}
]

配信側の利用方法

シグナリング開始時に指定できます。

シグナリング開始時

シグナリングの "type": "connect" 時に "simulcast": true を指定することで、有効になります。 映像コーデックは VP8 または H264 を選択してください。

{
  "type": "connect":,
  "role": "sendonly",
  "channel_id": "sora",
  "video": {"codec_type": "VP8"},
  "simulcast": true
}

視聴側の利用方法

シグナリング開始時に指定できます。

シグナリング開始時

• シグナリング "type": "connect" 時に "simulcast": true を指定することで、有効になります

• simulcast_rid には r0 / r1 / r2 が指定できます

  • simulcast_rid を指定しない場合は r0 が指定されます

  • この値は サイマルキャストで配信されている映像を受信する際のデフォルト値 です

  • この値は sora.conf の default_simulcast_rid で変更できます

• 映像コーデックは VP8 または H264 を選択してください

{
  "type": "connect":,
  "role": "recvonly",
  "channel_id": "sora",
  "video": {"codec_type": "VP8"},
  "simulcast": true,
  "simulcast_rid": "r2"
}

視聴側のストリームの変更 API

詳細は サイマルキャスト API をご確認ください

シーケンス図

        sequenceDiagram
    participant C1 as クライアント1
    participant S as WebRTC SFU Sora
    participant C2 as クライアント2
    C1->>S: "type": "connect",<br/>"role": "sendonly",<br/>"simulcast":"true"
    note over C1, S: クライアント1 WebRTC 確立
    C2->>S: "type": "connect",<br/>"role": "recvonly",<br/>"simulcast":"true",<br/>"simulcast_rid": "r1"
    note over C2, S: クライアント2 WebRTC 確立
    par
        C1-)S: 映像<br>rid: r0
    and
        C1-)S: 映像<br>rid: r1
        S-)C2: 映像<br>rid: r1
    and
        C1-)S: 映像<br>rid: r2
    end
    

サイマルキャストマルチコーデック機能

注意

この機能を利用する場合は事前にサポートまでご連絡ください

警告

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

概要

サイマルキャストマルチコーデックは、複数のコーデックを同時に使用して、サイマルキャストを実現する仕組みです。

注意

この機能は実験的機能として提供しており、かつブラウザ側の実装が未定のため、 将来的に仕様が大きく変更する可能性があります。それを踏まえてご利用ください。

不明点がある場合はサポートまでお問い合わせください。

制限

ブラウザでの配信

重要

2024 年 12 月 現在、ブラウザでサイマルキャストマルチコーデック機能を利用することはできません。

ブラウザでの視聴

一部ブラウザでサイマルキャストマルチコーデックで配信された映像を視聴することはできます。 視聴時のコーデック切り替えにも対応しています。

動作が確認できているブラウザは Chrome と Edge と Safari Technology Preview です。 それ以外のブラウザでは正常に動作しない可能性があります。

録画機能の利用

将来的に対応予定です

サイマルキャストマルチコーデックが有効なクライアントでは録画機能を利用することはできません。

映像コーデック指定の無視

サイマルキャストマルチコーデックを指定した場合、 クライアントや認証時の払い出しでのコーデック指定は無視されます。

利用方法

サイマルキャストマルチコーデックを利用する

sora.conf で simulcast_multicodec を有効にする

サイマルキャストマルチコーデック機能を利用するには sora.conf で simulcast_multicodec を true に設定します。

simulcast_multicodec = true

シグナリング接続時に "simulcast": true と "simulcast_multicodec": true を指定する

マルチコーデックサイマルキャストを利用するにはシグナリング接続時に "simulcast": true と "simulcast_multicodec": true を指定します。

この際、 "video": {"codec_type": "VP8"} などのコーデック指定は無視されます。

{
  "type": "connect",
  "role": "sendrecv",
  "channel_id": "sora",
  "simulcast": true,
  "simulcast_multicodec": true
}

サイマルキャストマルチコーデックのデフォルト値

サイマルキャストマルチコーデック用のコーデックには以下のデフォルト値が設定されています。

[
  {"rid": "r0", "codec_type": "AV1", "codec_params": {"profile": 0}},
  {"rid": "r1", "codec_type": "AV1", "codec_params": {"profile": 0}},
  {"rid": "r2", "codec_type": "H264", "codec_params": {"profile_level_id": "42e02a"}}
]

サイマルキャストマルチコーデックのデフォルト値を変更する

sora.conf の simulcast_codecs_file でサイマルキャストマルチコーデックで利用するコーデックのデフォルトを指定することができます。

simulcast_codecs_file = etc/simulcast_codecs.json

[
  {"rid": "r0", "codec_type": "H264", "codec_params": {"profile_level_id": "42e02a"}},
  {"rid": "r1", "codec_type": "H264", "codec_params": {"profile_level_id": "42e02a"}},
  {"rid": "r2", "codec_type": "H265"}
]

認証成功時の払い出しで指定する

サイマルキャストマルチコーデックを利用する場合 simulcast と simulcast_multicodec を認証成功時に払い出すことができます。

{
  "allowed": true,
  "simulcast": true,
  "simulcast_multicodec": true
}

r0 と r1 に H264 、r2 に H265 を利用する場合の例です。

{
  "allowed": true,
  "simulcast": true,
  "simulcast_multicodec": true,
  "simulcast_codecs": [
    {"rid": "r0", "codec_type": "H264", "codec_params": {"profile_level_id": "42e02a"}},
    {"rid": "r1", "codec_type": "H264", "codec_params": {"profile_level_id": "42e02a"}},
    {"rid": "r2", "codec_type": "H265"}
  ]
}

simulcast_encodings の指定

サイマルキャストマルチコーデックのサイマルキャストエンコード部分は simulcast_encodings のデフォルト値を利用します。

そのため、サイマルキャストマルチコーデック向けに simulcast_encodings を指定したい場合は、 認証成功時に払い出す必要があります。

{
  "allowed": true,
  "simulcast": true,
  "simulcast_multicodec": true,
  "simulcast_encodings": [
    {"rid": "r0", "active": true, "scaleResolutionDownBy": 4.0, "maxFramerate": 10.0},
    {"rid": "r1", "active": true, "scaleResolutionDownBy": 1.0, "maxFramerate": 30.0},
    {"rid": "r2", "active": true, "scaleResolutionDownBy": 1.0, "maxFramerate": 30.0}
  ],
  "simulcast_codecs": [
    {"rid": "r0", "codec_type": "H264", "codec_params": {"profile_level_id": "42e02a"}},
    {"rid": "r1", "codec_type": "H264", "codec_params": {"profile_level_id": "42e02a"}},
    {"rid": "r2", "codec_type": "H265"}
  ]
}

type: offer 時に払い出される内容

simulcast_encodings と simulcast_codecs に指定された値から、 W3C WebRTC 準拠の RTCRtpEncodingParameters を生成し、 "type": "offer" の "encodings" として追加します。

"codec" については W3C WebRTC RTCRtpCodecParameters と W3C WebRTC Extension RTCRtpEncodingParameters に準拠しています。

{
  "type": "offer",
  "simulcast": true,
  "simulcast_multicodec": true,
  "encodings": [
    {
      "rid": "r0",
      "active": true,
      "scaleResolutionDownBy": 4.0,
      "maxFramerate": 10.0,
      "codec": {
        "mimeType": "video/H264",
        "clockRate": 90000,
        "sdpFmtpLine": "level-asymmetry-allowed=1;packetization-mode=1;profile-level-id=42e02a"
      }
    },
    {
      "rid": "r1",
      "active": true,
      "scaleResolutionDownBy": 1.0,
      "maxFramerate": 30.0,
      "codec": {
        "mimeType": "video/H264",
        "clockRate": 90000,
        "sdpFmtpLine": "level-asymmetry-allowed=1;packetization-mode=1;profile-level-id=42e02a"
      }
    },
    {
      "rid": "r2",
      "active": true,
      "scaleResolutionDownBy": 1.0,
      "maxFramerate": 30.0,
      "codec": {
        "mimeType": "video/H265",
        "clockRate": 90000,
        "sdpFmtpLine": "profile-id=1;level-id=93"
      }
    }
  ]
}

スポットライト機能

概要

WebRTC SFU サーバーを利用して 20 名で会議を行う場合、各参加者は自分以外の 19 名分の音声と映像を常に受信し続ける必要があります。 また、WebRTC SFU サーバーも、常に 20 名分の音声や映像を受信し、配信し続ける必要があります。

ところが実際は 20 名の会議であっても、ひとつのトピックに対して発言している人はせいぜい 2 名から 3 名です。 また、映像も常に参加者全員のものを高画質で配信しなくとも、その時点でアクティブに発言している人の映像がクリアであれば十分というケースも多いです。

この スポットライト機能 を利用すると、発言していない大多数の参加者の音声は配信せず、低画質の映像のみを配信できます。ある参加者が発言し始めると、自動でその参加者の音声の配信を開始し、さらにあらかじめ設定した秒数が経過すると、映像の画質も自動で高画質に切り替えることができます。

この仕組を使うことで、クライアントやサーバーの負荷を抑えながら大人数で会議できるようになります。

この機能は、発言している参加者のみの音声と高画質の映像が配信されることから、スポットライトが当たるイメージに見立てて、スポットライト機能と名付けています。

仕組み

開始前に、フォーカスする人数を決めます。 フォーカスする人数とは、会議の参加者のうち、最大何人分の映像を高画質で配信するかの数です。

ここではフォーカスする人数を 1 人とします。

この機能を利用した場合は、発言していない参加者の映像は低画質で配信され、音声は配信されません。

最初に A さんが発言し始めると、 A さんの映像が高画質になって配信されます。

次に B さんが発言すると、 B さんの映像が高画質になって配信されます。 このタイミングで A さんの映像は低画質になります。

その後は同じように、直近で発言した 1 人分の映像が高画質で配信され、音声も配信されます。 それ以外の参加者の映像は低画質で配信され、音声は配信されません。

このように、高画質で配信する人数を限定することで、クライアントやサーバーの負荷を抑えながら大人数での会議が実現できます。

ただし、上記のような自動切り替えでは、参加者の映像が頻繁に入れ替わると逆に負荷が高くなってしまいます。 それを抑えるため、Sora では、参加者が発言し始めるとまずは音声だけを配信し始め、映像の切り替えはしばらく時間が経ってから行うことができます。

この時、映像が切り替わる前に、先に音声を配信することをフォーカスなし音声配信と呼びます。 これにより、映像の切り替わりの有無に関わらず、短い発言、あいづちなども配信し、スムーズな会話を成立させられます。

また、音声よりも遅れて映像を切り替えることを遅延フォーカスと呼びます。 映像の切り替えを遅延させることにより、ちょっとした雑音や短い発言のたびに映像が切り替わることを抑制できます。

これらのフォーカスなし音声配信や遅延フォーカス機能を利用すれば、スポットライト機能でフォーカスする人数は 1 〜 2 人で十分です。多くても 3 人です。

注意

スポットライト機能はサイマルキャスト機能を活用した機能です

デフォルトであれば解像度が VGA 以上のサイズであれば 2 つの画質の映像を配信します。

• 高画質

  • 解像度の縮小比が 1 で 30 fps

• 低画質

  • 解像度の縮小比が 4 で 5 fps

Chrome 、 Edge 、 Safari で動作します

現時点では Chrome と Edge と Safari の最新版に対応しています。

注釈

Firefox ではサイマルキャスト機能ができないため、 Firefox を利用する場合はサイマルキャスト機能を無効にして接続する必要があります。

詳細は サイマルキャスト機能を無効にして接続する をご確認ください。

マルチストリームのサイマルキャストとの違い

マルチストリームのサイマルキャストを利用する場合、 受信する映像の種類を切り替えるには RequestRtpStream API を利用する必要があります。

スポットライトはこの API の切り替え部分を Sora が自動で判断します。判断には参加者の音量を利用します。

例えば、音量が閾値を下回った場合は rid は r0 、閾値を超えた場合は rid は r1 のように、他の参加者が受信する映像の rid を切り替えます。

• マルチストリームの詳細は マルチストリーム機能 をご確認ください

• サイマルキャストの詳細は サイマルキャスト機能 をご確認ください

SDK 対応状況

• 最新版の JavaScript SDK

  • 対応済みです

• 最新版の iOS SDK

  • 対応済みです

• 最新版の Android SDK

  • 対応済みです

• 最新版の Unity SDK

  • 対応済みです

• 最新版の C++ SDK

  • 対応済みです

スポットライト利用時の映像の種類のデフォルト

Sora ではスポットライトで配信する映像の種類にデフォルト値を設定しています。

[
  {"rid": "r0", "active": true, "scalabilityMode": "L1T3", "maxFramerate":  5.0, "scaleResolutionDownBy": 4.0},
  {"rid": "r1", "active": true, "scalabilityMode": "L1T3", "maxFramerate": 30.0, "scaleResolutionDownBy": 1.0},
  {"rid": "r2", "active": false}
]

r0

rid が r0 の場合は通常の解像度から解像度(一辺) が 1/4 で、 フレームレートが 5 になるようなエンコードがされるように設定されています。

r1

rid が r1 の場合は通常の解像度のままで、 フレームレートが 30 でエンコードがされるように設定されています。

r2

rid が r2 の場合はエンコードがされないように設定されています。

スポットライト利用時の映像のエンコーディングパラメーターのカスタマイズ

Sora ではスポットライトでの映像のエンコーディングパラメーターを自由に設定できます。

• sora.conf のファイルで指定することで全体のスポットライトのエンコーディングパラメーターが指定できます

• 認証成功時に spotlight_encodings で払い出すことで個別にスポットライトのエンコーディングパラメーターが指定できます

sora.conf でファイル指定

sora.conf にて スポットライトの場合は spotlight_encodings_file で JSON ファイルを指定してください。

spotlight_encodings_file = etc/spotlight_encodings.json

sora.conf で指定する JSON ファイルの記述方法

[
  {"rid": "r0", "active": true, "scaleResolutionDownBy": 4.0, "maxFramerate": 5.0},
  {"rid": "r1", "active": true, "scaleResolutionDownBy": 1.0, "maxFramerate": 10.0},
  {"rid": "r2", "active": true, "scaleResolutionDownBy": 1.0, "maxFramerate": 30.0}
]

認証成功時に spotlight_encodings で払い出す記述方法

{
  "allowed": true,
  "spotlight_encodings": [
    {"rid": "r0", "active": true, "scaleResolutionDownBy": 2.0, "maxFramerate": 5.0},
    {"rid": "r1", "active": true, "scaleResolutionDownBy": 2.0, "maxFramerate": 20.0},
    {"rid": "r2", "active": true, "scaleResolutionDownBy": 1.0, "maxFramerate": 30.0}
  ]
}

カスタマイズの設定

• rid

  • 必須

  • string (r0 / r1 / r2)

  • https://www.w3.org/TR/webrtc/#dom-rtcrtpcodingparameters-rid

• active

  • このエンコーディングパラメーターを有効にします

  • オプション

  • boolean

  • https://www.w3.org/TR/webrtc/#dom-rtcrtpencodingparameters-active

• scaleResolutionDownBy

  • オプション

  • 1 以上の number (float または integer)

  • https://www.w3.org/TR/webrtc/#dom-rtcrtpencodingparameters-scaleresolutiondownby

• maxBitrate

  • オプション

  • 最大ビットレートを指定する

  • 0 以上の integer

  • https://www.w3.org/TR/webrtc/#dom-rtcrtpencodingparameters-maxbitrate

• maxFramerate

  • オプション

  • 最大フレームレートを指定する

  • 0 以上の number (float または integer)

  • https://w3c.github.io/webrtc-extensions/#dom-rtcrtpencodingparameters-maxframerate

• adaptivePtime

  • この設定は Chrome でしか利用できません

  • オプション

  • boolean

  • https://w3c.github.io/webrtc-extensions/#dom-rtcrtpencodingparameters-adaptiveptime

• scalabilityMode

  • この設定は Chrome でしか利用できません

  • オプション

  • string

  • https://www.w3.org/TR/webrtc-svc/#dom-rtcrtpencodingparameters-scalabilitymode

  • 詳細は scalabilityMode を参照してください

フォーカスする配信数

フォーカスする配信数はチャネル ID ごとに 1 から 8 までのいずれかを選択できます。 同一チャネル ID へ接続しているクライアント全てが同じ値を指定する必要があります。

デフォルトのフォーカス数は 1 です。

sora.conf の default_spotlight_number でデフォルトの値を変更することができます。

注釈

遅延フォーカスやフォーカスなしでの音声配信を有効にしていればフォーカス数は 1 で十分です。

フォーカスする配信数を途中で変更するには ChangeSpotlightNumber API を利用してください。

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

警告

この機能は非推奨です。 セッションウェブフック session.created の払い出しを利用してください。

シグナリング接続時に spotlight_number を指定することで、フォーカスする配信数を指定することができます。

そのチャネルのセッションが存在しない状態で、一番最初に接続したクライアントの spotlight_number が適用されます。 未指定であれば sora.conf の default_spotlight_number の値が適用されます。

この値は default_spotlight_number の値を上書きします。

認証成功時の払い出しの指定

警告

この機能は非推奨です。 セッションウェブフック session.created の払い出しを利用してください。

認証ウェブフック成功時の払い出しに spotlight_number を指定することで、フォーカスする配信数を指定することができます。

この値は default_spotlight_number やシグナリング接続時の値を上書きします。

セッション生成時の払い出し指定

セッションウェブフック session.created の払い出しに spotlight_number を指定することで、 フォーカスする配信数を指定することができます。

この値は default_spotlight_number やシグナリング接続時、認証成功時の払い出しの値を上書きします。

遅延フォーカス

ちょっとした物音でフォーカスをしないようにするため、フォーカスを遅延させる機能です。 この機能を有効にした場合、フォーカスされる場合に一定時間以上、音が出続けている必要があります。

default_spotlight_delayed_focus

sora.conf で遅延フォーカスを有効にするかどうかを指定してください。デフォルトで true です。

default_spotlight_delayed_focus_interval

sora.conf でフォーカスを遅延させる時間を指定してください。デフォルトは 2000 ms です。

遅延アンフォーカス

スポットライトの数が少ないときに、フォーカスの奪い合いが発生しないように、フォーカスが発生してからアンフォーカスするまで遅延させる機能です。

default_spotlight_focus_min_interval

sora.conf でフォーカスしてからアンフォーカスされるまでの最低時間間隔を指定します。デフォルトは 2000 ms です。

フォーカスなし音声配信

フォーカスがない状態でも音声を配信するかを指定する機能です。 この機能を有効にすると、フォーカスが他の配信者にとられても音声を配信し続けます。

配信するレートの上限も指定できます。

default_spotlight_unfocus_audio

sora.conf でフォーカスなし音声を有効にするかどうかを指定してください。デフォルトで true です。

default_spotlight_unfocus_audio_rate_limit

sora.conf でフォーカスなし音声を配信する上限レートを指定してください。デフォルトは 2 です。

レートの単位は 1 音声ストリーム = 50 packets / s です。

自動アンフォーカス

無音状態が一定時間続くとフォーカスを自動で外す機能です。この機能を利用するとフォーカス数が 0 になることもあります。

クライアントが受信するパケット、Sora が配信するパケットを減らすことができます。

default_spotlight_auto_unfocus

sora.conf で音がない場合に自動でアンフォーカスするかどうかを指定してください。デフォルトは true です。

default_spotlight_auto_unfocus_interval

sora.conf で自動でアンフォーカスする無音時間を指定してください。デフォルトは 10 s です。

サイマルキャスト機能を無効にして接続する

注釈

サイマルキャストを無効にして接続すると常にフォーカスされ続けます。

スポットライト機能でサイマルキャスト機能を無効にして利用できます。

無効にする場合はシグナリング接続時または認証成功時に "simulcast": "false" を指定する必要があります。

サイマルキャスト機能を無効にしてスポットライトを利用した場合、 そのクライアントは常にフォーカスされている状態となります。 そのため spotlight_focus_rid や spotlight_unfocus_rid の影響も受けません。

サイマルキャスト機能を無効にした利用は、 画面共有やサイマルキャストが利用できないクライアントでの利用を想定しています。

シグナリング

• シグナリングの "type": "connect" で spotlight を true に設定してください

  • これは必須です

• シグナリングの "type": "connect" で simulcast を設定してください

  • これはオプションです

  • サイマルキャストを無効にする場合は サイマルキャスト機能を無効にして接続する をご確認ください

• シグナリングの "type": "connect" で spotlight_number で 1..8 の値を指定してください

  • 1 から 3 の間がお勧めです

  • これはオプションです

その他の項目は シグナリング を参照ください。以下に シグナリング "type": "connect" の例を示します。

"type": "connect"

simulcast: false

サイマルキャスト無効。

{
  "type": "connect",
  "channel_id": "sora",
  "role": "sendrecv",
  "spotlight": true,
  "simulcast": false,
  "video": {
    "codec_type": "VP8",
    "bit_rate": 800
  }
}

spotlight_number

重要

spotlight_number は同一セッションで同じ値を指定する必要があります。

spotlight_number はセッションウェブフック session.created の戻り値で指定することをお勧めします。

フォーカス数はデフォルトの 1

{
  "type": "connect",
  "channel_id": "sora",
  "role": "sendrecv",
  "spotlight": true,
  "simulcast": true,
  "video": {
    "codec_type": "VP8",
    "bit_rate": 800
  }
}

フォーカス数は指定した値の 5

{
  "type": "connect",
  "channel_id": "sora",
  "role": "sendrecv",
  "spotlight": true,
  "spotlight_number": 5,
  "simulcast": true,
  "video": {
    "codec_type": "VP8",
    "bit_rate": 800
  }
}

spotlight_focus_rid / spotlight_unfocus_rid

シグナリング接続時、認証成功時にフォーカスした場合とフォーカスしていない場合に受信する映像の rid を接続ごとに指定できます。

例えば、映像は特に受け取らなくていい場合は、両方の設定で none を指定することで参加者全員の映像を受信しなくなります。

また、話している人は rid は r1 で受信し、それ以外は受信しない (rid に none を指定) といった設定もできます。

{
  "type": "connect",
  "channel_id": "sora",
  "role": "sendrecv",
  "spotlight": true,
  "spotlight_focus_rid": "r0",
  "spotlight_unfocus_rid": "none",
  "simulcast": true,
  "video": {
    "codec_type": "VP8",
    "bit_rate": 800
  }
}

sora.conf で default_spotlight_focus_rid と default_spotlight_unfocus_rid を指定することで、個別ではなくサーバー全体の設定もできます。

シグナリング通知

シグナリング通知の詳細は スポットライト機能のシグナリング通知 をご確認ください。

フォーカスされたタイミングとフォーカスが外れたタイミングでシグナリング通知をクライアントに送ります。 クライアントはこの通知を利用することで、配信が切り替わったことを知ることができるようになります。

セッションウェブフック

セッションウェブフック session.created の払い出しで spotlight_number を指定することができます。 この値はセッション単位で適用され、シグナリング接続時や認証成功時の払い出しの値を上書きします。

この spotlight_number の値を変更するには ChangeSpotlightNumber API を利用してください。

イベントウェブフック

フォーカスされたタイミングとフォーカスが外れたタイミングでウェブフックリクエストが送信されます。

sora.conf の ignore_spotlight_changed_webhook で指定できます。 デフォルトではイベントウェブフックのリクエスト送信は無効になっています。

• spotlight.focused イベントウェブフック

• spotlight.unfocused イベントウェブフック

API

API の詳細は スポットライト API をご確認ください。

• FocusSpotlightFixed API

  • 特定のクライアントにフォーカスし続ける API

• FocusSpotlight API

  • 特定のクライアントにフォーカスする API

• UnfocusSpotlight API

  • 特定のクライアントからアンフォーカスする API

• ChangeSpotlightNumber API

  • フォーカスする数を変更する API

• RequestSpotlightRid API

  • 特定のクライアントのフォーカス/アンフォーカス時の rid を変更する API

• ResetSpotlightRid API

  • 特定のクライアントのフォーカス/アンフォーカス時の rid をリセットする API

• BatchRequestSpotlightRid API

  • フォーカス/アンフォーカス時の rid を一括で変更する API

シーケンス図

        sequenceDiagram
    participant C1 as クライアント1
    participant S as WebRTC SFU Sora
    participant C2 as クライアント2
    C1->>S: "type": "connect",<br/>"role": "sendrecv"<br/>"spotlight": true,<br/>"simulcast": true
    note over C1,S: クライアント1 WebRTC 確立
    par
        C1-)S: 映像<br/>rid: r0
    and
        C1-)S: 映像<br/>rid: r1
    end
    C2->>S: "type": "connect",<br/>"role": "sendrecv"<br/>"spotlight": true,<br/>"simulcast": true
    note over C2,S: クライアント2 WebRTC 確立
    par
        C2-)S: 映像<br/>rid: r0
    and
        C2-)S: 映像<br/>rid: r1
    end
    par
        S-)C2: クライアント1映像<br/>rid: r0
    and
        S-)C1: クライアント2映像<br/>rid: r0
    end
    note over C1: クライアント1が話し始める
    S-)C2: クライアント1音声
    note over C1: しゃべり初めて 2 秒経過
    note right of S: r0 の代わりに r1 映像を配信
    S-)C2: クライアント1映像<br/>rid: r1
    

OBS Studio WHIP 対応機能

概要

OBS Studio が対応している WHIP を利用した WebRTC 配信に対応しています。

ここでは Sora や OBS の WHIP 仕様について説明します。

注意

• OBS の WHIP 実装の仕様を正としており RFC の WHIP 仕様とは異なる可能性があります

• 現時点では Sora SDK は WHIP へ対応していません

• 現時点では WHIP を利用した接続の統計ウェブフックの送信には対応していません

WHIP クライアントのお問い合わせについて

WHIP クライアントに関する質問などの報告は Discord の利用をお願いします。

URL:

https://discord.gg/shiguredo

Sora の WHIP クライアントについての質問やバグ報告は Discord の #sora-sdk-faq チャンネルにお願いします。

WHIP とは何か

参考

WebRTC-HTTP ingestion protocol (WHIP)

WHIP は WebRTC-HTTP ingestion protocol の略で、 WebRTC では標準化されていないシグナリングをブロードキャスト/ストリーミング系の配信ツール向けに規定した規格です。

WHIP は仕様を小さくして、実装を簡単にすることで配信ツールが取り込みやすくしています。

クライアントが HTTP POST で Offer SDP を送信して、Answer SDP を受け取るというシンプルなシグナリング規格です。

OBS 30.0.0 にて WebRTC/WHIP が正式にサポートされました。

最新版は以下からダウンロードができます。

https://obsproject.com/download

WHIP のシーケンス図

        sequenceDiagram
  participant OBS as OBS
  participant WE as WHIP Endpoint
  participant MS as Media Server
  participant WS as WHIP Resource
  OBS->>+WE: HTTP POST (SDP Offer)
  WE-->>-OBS: HTTP 201 Created (SDP Answer)
  note over OBS,MS: WebRTC Connection
  OBS->>+WS: HTTP DELETE
  WS->>-OBS: HTTP 200 OK
    

Sora の WHIP のシーケンス図

Sora では WHIP エンドポイント、WHIP リソース、メディアサーバーすべてを Sora が担当します。

        sequenceDiagram
   participant OBS as OBS
   participant S as Sora
   participant A as App
   OBS->>+S: HTTP POST (SDP Offer)
   S->>+A: 認証ウェブフック
   A-->>-S: 200 OK<br>allowed : true
   S-->>-OBS: HTTP 201 Created (SDP Answer)
   note over OBS,S: WebRTC Connection
   S->>+A: イベントウェブフック<br>connection.created
   A-->>-S: 200 OK
   OBS->>+S: HTTP DELETE
   S->>+A: イベントウェブフック<br>connection.destroyed
   A-->>-S: 200 OK
   S->>-OBS: HTTP 200 OK
    

OBS の WHIP 対応について

警告

OBS の WHIP 対応については Discord https://discord.gg/shiguredo の #sora-sdk-faq にてご相談ください。

2024 年 12 月 時点での OBS では WHIP 対応では輻輳制御が実装されていません。 これは OBS の WHIP 対応するために利用している libdatachannel が輻輳制御に対応していないためです。

そのため、回線が不安定になったとしても、ビットレートを下げたりするといったことは行いません。

サイマルキャスト対応

Pull-Request:

https://github.com/obsproject/obs-studio/pull/10885

今後 OBS で対応される予定です。 Sora では 2024 年 12 月リリース予定の Sora にて対応予定です。

OBS 以外の WHIP クライアントへの対応について

重要

Sora の WHIP 実装は OBS の WHIP 対応のみをサポートしています。 それ以外のクライアントの WHIP 実装には対応していません。

新しい WHIP クライアントへの対応は有償での優先実装として対応を検討できますので、 対応希望の WHIP クライアントと優先実装については、サポートまでメールにてご連絡ください。

• ブラウザ

• GStreamer

• FFmpeg

Sora での利用方法

sora.conf にて whip を true に指定してください。

whip = true

Bearer トークンを利用した認証機能を利用する場合

sora.conf にて whip_bearer_token_metadata_key を指定してください。

whip_bearer_token_metadata_key = whip_access_token

例えば、 access_token という文字列をした場合、 WHIP 接続時、認証ウェブフックに "metadata": {"access_token": "<bearer_token>""} が入ってきます。 whip_token を指定した場合は "metadata": {"whip_token": "<bearer_token>""} が入ってきます。

whip_bearer_token_metadata_key が未指定の場合は、 Bearer トークンが WHIP 接続時に送られてきたとしても Sora は無視して、 metadata も生成しません。

OBS での WHIP 利用方法

OBS での利用方法は以下の通りです。

1. サービスに WHIP を選ぶ

2. サーバーに Sora が提供する WHIP エンドポイント URL を指定する

   • デフォルトでは http://127.0.0.1:5000/whip/<channel_id>

3. Bearer トークンには好きな文字列を指定する

   • Sora の認証ウェブフックの項目 whip_bearer_token_metadata_key で指定した値をキーとして、 "metadata": {"<whip_bearer_token_metadata_key>": "<bearer_token>""} が認証サーバーに送信されます

切断方法

Location ヘッダーに入ってくるリソースエンドポイント URL に DELETE リクエストを送ることで切断できます。

OBS は配信終了することで切断リクエストを送りますので、意識する必要はありません。

Sora の OBS (WHIP) の挙動

• Sora は WHIP エンドポイント URL を提供します

  • デフォルトでは http://127.0.0.1:5000/whip/<channel_id> です

• Sora の WHIP エンドポイントからの配信は、マルチストリームかつ配信のみ(sendonly)として扱われます

• Sora の WHIP エンドポイントを利用した配信では、シグナリング通知は現時点では利用できません

• Sora の WHIP リソース URL は WHIP エンドポイントのレスポンスに含まれる Location ヘッダーにて払い出されます

WHIP エンドポイント URL

Sora の OBS (WHIP) 対応は "multistream": true, "role": "sendonly" として機能します。

チャネル ID の指定

OBS ではリクエスト時に JSON でチャネル ID を指定することができません。そのため WHIP エンドポイント URL に channel_id を含めて指定します。 channel_id に URL に利用できない文字が含まれている場合は URL エンコードしてください。

HTTP POST https://sora.example.com/whip/<channel_id>

channel_id が sora の WHIP エンドポイント URL 例:

https://sora.example.com/whip/sora

WHIP エンドポイントへの HTTP リクエストに対するレスポンスコードは 201 Created です。

WHIP リソース URL

Sora では WHIP リソースエンドポイントは Location ヘッダーに含まれています。

以下は切断する例です。

HTTP DELETE https://sora.example.com/whip-resource/<channel_id>/<secret>

以下は Trickle ICE を利用する例です。

HTTP PATCH https://sora.example.com/whip-resource/<channel_id>/<secret>

<secret> は 32 バイトのランダムな値を base32 でエンコードした文字列です。

WHIP リソース URL 例:

https://sora.example.com/whip-resource/sora/QBF6AFDWZGWM97BNS5YCBSXM54M01D0TFQ48MC9Z3ZJG8YPRQ1Z0

注釈

OBS に Bearer トークンを指定した場合は、WHIP リソースエンドポイント URL にも Bearer トークンは送られます

認証仕様

WHIP では認証に Bearer トークンを指定することができます。

OBS でも認証情報に Bearer トークンを指定できます。

Sora は sora.conf で whip_bearer_token_metadata_key に文字列を指定していた場合、 OBS の HTTP POST 時に Authentication ヘッダーで送られてきた Bearer トークンを、 認証ウェブフックの metadata に {"<whip_bearer_token_metadata_key>": "<bearer_token>"} を設定して認証サーバーに送信します。

Sora 自体は Bearer トークンのチェックやデコードなどは行いません。これらは認証ウェブフックのリクエストを受信した認証サーバーが行う必要があります。

ウェブフック仕様

whip

true が入ってきます。

ignore_disconnect_websocket

false が入ってきます。

metadata

sora.conf にて whip_bearer_token_metadata_key に指定した文字列をキーとして metadata に入ってきます。

whip_bearer_token_metadata_key = whip_bearer_token

もし文字列を whip_bearer_token にしていた場合は、 "metadata": {"whip_bearer_token": "<bearer-token>"} が送られてきます。

OBS 側に設定した Bearer Token の値がそのまま入ってきます。

multistream

true が入ってきます。

role

sendonly が入ってきます。

channel_id

WHIP エンドポイント URL に渡した値が利用されます。

注釈

URL デコード済みの値が入ります

client_id

WHIP エンドポイント URL にクエリ文字列として client_id=<client_id> を指定した場合、その値が利用されます。

注釈

URL デコード済みの値が入ります

bundle_id

WHIP エンドポイント URL にクエリ文字列として bundle_id=<bundle_id> を指定した場合、その値が利用されます。

注釈

URL デコード済みの値が入ります

spotlight

WHIP エンドポイント URL にクエリ文字列として spotlight=<boolean> を指定した場合、その値が利用されます。

既知の問題として spotlight = true を指定して接続した場合、音声がそのままでは配信されません。 FocusSpotlightFixed API を利用して OBS の接続にフォーカスを当てる必要があります。

詳細は 既知の問題 - OBS 対応機能 を参照してください。

注釈

URL デコード済みの値が入ります

audio / video

OBS 側で指定した値を利用します。 OBS では音声は Opus のみ、映像は H.264 と H.265 と AV1 が利用できます。

• audio: true

• audio_codec_type: "OPUS"

• video: true

• video_codec_type: "H264" | "AV1"

OBS 利用時にはビットレートの指定できないため、 Sora のデフォルトの値が入ってきますが、 OBS の WHIP 実装では SDP での最大ビットレートを無視します。 そのため OBS 側で設定したビットレートで配信が行われます。

注釈

H.265 は OBS 30.2 から利用できます

simulcast

注意

現時点では OBS の WHIP 対応はサイマルキャストに未対応です。OBS 側の対応待ちです。

現時点では false が入ってきます。

sora_client

OBS WHIP で User-Agent として送られてくる情報を sora_client に含めています。

"sora_client": {
  "raw": "Mozilla/5.0 (OBS-Studio/30.1.0; Mac OS X; ja-JP)",
  "type": "OBS-Studio-WHIP",
  "version": "30.1.0",
  "environment": "environment":"Mozilla/5.0 (OBS-Studio/30.1.0; Mac OS X; ja-JP)"
},

その他

• e2ee: false

• spotlight: false

• data_channel_signaling: false

• ignore_disconnect_webhook: false

• turn_transport_type: udp

  • OBS 30.2 での TURN 対応は TURN-UDP のみのため tcp になる事はありません

認証ウェブフック成功時の払い出し

基本的には OBS で指定した値がそのまま利用されますので、 以下の値以外は指定することはお勧めしません。

• client_id

• bundle_id

• event_metadata

• recording_block

• signaling_notify_metadata

• connection_lifetime

• cluster_affinity

• playout_delay_min_delay

• playout_delay_max_delay

• rtp_packet_loss_simulator_incoming

クラスター利用時の認証ウェブフックの挙動

クラスター利用時に、 WHIP で接続したノードではないノードに接続を振り分ける場合、 Sora は認証情報を担当ノードに Proxy を行います。

接続は接続したノードで行われますが、認証ウェブフックは担当ノードから送信されます。 その後 WebRTC 接続確立は担当ノードと行います。

シーケンス図

        sequenceDiagram
   participant O as OBS (WHIP)
   participant S1 as Sora 1
   participant S2 as Sora 2
   participant A as App
   O->>+S1: HTTP POST<br>https://sora-02.example.com/whip/sora<br>Offer SDP
   Note over S1: 担当ノードは Sora 2
   S1->>+S2: ノード間通信で認証処理を Proxy
   S2->>+A: 認証ウェブフック<br>"channel_id": "sora"<br>"multistream": true<br>"role": "sendonly"
   A-->>-S2: "allowed": true
   S2-->>-S1: Sora 2 の IP アドレス
   S1-->>-O: HTTP 201 Created<br>Answer SDP<br>Candidate: Sora 2 IP アドレス
   note over O,S2: WebRTC 確立
   S1->>+A: イベントウェブフック<br>"connection.created"
   A-->>-S2: HTTP 200 OK
   O-)S2: SRTP
   O-)S2: SRTP
   O->>+S2: HTTP DELETE<br>https://sora-02.example.com/whip/sora/<secret>
   S2-->>-O: HTTP 200 OK
   note over O,S2: WebRTC 終了
    

TURN の利用

sora.conf で whip_turn を有効にすることで Sora は WHIP 利用時に Link ヘッダーに TURN URLs を払い出します。

Sora の仕様として TURN を有効にした場合は TURN のみの通信 を行います、 そのため TURN に対応していない OBS は利用できなくなります。

OBS の TURN 機能

OBS 30.2 で TURN に対応しました。

OBS で WebRTC を実現している libdatachannel が利用している ICE ライブラリの libjuice は、 TURN-UDP のみに対応しています。 そのため TURN-TCP や TURN-TLS には対応していません。

録画利用時の注意

• OBS WHIP で H.264 を利用している場合、 x264 以外を利用することを推奨します

クラスター利用時の挙動

whip_turn を false にした場合の挙動

クラスター利用時に接続したノードが指定した channel_id の担当ノードでは無い場合、 担当ノードの IP アドレスを Answer SDP に含めます。

whip_turn を true にした場合の挙動

クラスター利用時に、接続したノードが指定した channel_id の担当ノードでは無い場合、 担当ノードの TURN URLs を Link ヘッダーにて払い出します。

シーケンス図

単独

        sequenceDiagram
    participant O as OBS
    participant S as Sora
    participant A as App
    O->>+S: HTTP POST https://sora.example.com/whip/<channel_id><br>Offer SDP
    S->>+A: 認証ウェブフック<br><br>"channel_id": "<channel_id>""multistream": true<br>"role": "sendonly"
    A-->>-S: "allowed": true
    S-->>-O: HTTP 201 Created<br>Answer SDP
    Note left of S: このタイミングで Link ヘッダーで、<br>TURN URLs を払い出す
    note over O,S: ICE 確立
    note over O,S: DTLS 確立
    note over O,S: WebRTC 確立
    S->>+A: イベントウェブフック<br>"connection.created"
    A-->>-S: HTTP 200 OK
    O-)S: SRTP
    O-)S: SRTP
    O->>+S: HTTP DELETE https://sora.example.com/whip/<channel_id>/<secret>
    S-->>-O: HTTP 200 OK
    note over O,S: WebRTC 終了
    

クラスターかつロードバランサー

クラスターを利用する場合、OBS に設定する WHIP エンドポイントはロードバランサーが提供するエンドポイントをお勧めしています。

このシーケンス図では Sora が 2 ノードになっていますが、最低 3 ノード必要です。

        sequenceDiagram
   participant O as OBS (WHIP)
   participant B as ブラウザ
   participant LB as LB
   participant S1 as Sora 1
   participant S2 as Sora 2
   participant A as App
   par
      B-xS1: WSS<br>https://node1.sora.example.com/signaling
   and
      B->>S2: WSS<br>https://node2.sora.example.com/signaling<br>
      note over B,S2: WebSocket 確立
   end
   B->>S2: WSS "type": "connect"
   S2->>+A: 認証ウェブフック<br>"channel_id": "sora"<br>"multistream": true<br>"role": "recvonly"
   A-->>-S2: "allowed": true
   S2-)B: "type": "offer"
   B-)S2: "type": "answer"
   note over B,S2: WebRTC 確立
   O->>+LB: HTTP POST<br>https://sora.example.com/whip/sora<br>Offer SDP
   LB->>+S1: HTTP POST<br>https://node2.sora.example.com/whip/sora<br>Offer SDP
   S1->>+S2: 担当ノードに内部通信で処理を Proxy
   S2->>+A: 認証ウェブフック<br>"channel_id": "sora"<br>"multistream": true<br>"role": "sendonly"
   A-->>-S2: "allowed": true
   %% S2-->>-S1: Sora 2 の IP アドレス または TURN URLs
   S2-->>-S1: Sora 2 の IP アドレス
   S1-->>-LB: HTTP 201 Created<br>Answer SDP
   LB-->>-O: HTTP 201 Created<br>Answer SDP
   %% Note left of S2: このタイミングで Link ヘッダーで、<br>TURN URLs を払い出す
   note over O,S2: WebRTC 確立
   S1->>+A: イベントウェブフック<br>"connection.created"
   A-->>-S2: HTTP 200 OK
   O-)S2: SRTP
   S2-)B: SRTP
   O-)S2: SRTP
   S2-)B: SRTP
   O->>+S2: HTTP DELETE<br>https://node2.sora.example.com/whip/sora/<secret>
   S2-->>-O: HTTP 200 OK
   note over O,S2: WebRTC 終了
    

OBS Studio WHEP 対応機能

注意

この機能を利用する場合は事前にサポートまでご連絡ください

警告

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

概要

OBS Studio が対応を予定している WHEP を利用したメディアソースに対応しています。

ここでは Sora や OBS の WHEP 仕様について説明します。

注意

• OBS の WHEP 実装の仕様を正としており RFC ドラフトの WHEP 仕様とは異なる可能性があります

• 現時点では Sora SDK は WHEP へ対応していません

• OBS の WHEP 実装では Opus と H.264 の組み合わせでのみ利用できます

• 現時点では WHEP を利用した接続の統計ウェブフックの送信には対応していません

WHEP クライアントのお問い合わせについて

WHEP クライアントに関する質問などの報告は Discord の利用をお願いします。

URL:

https://discord.gg/shiguredo

Sora の WHEP クライアントについての質問やバグ報告は Discord の #sora-sdk-faq チャンネルにお願いします。

WHEP とは何か

参考

WebRTC-HTTP Egress Protocol (WHEP)

WHEP は WebRTC-HTTP Egress Protocol の略で、 WebRTC では標準化されていないシグナリングをブロードキャスト/ストリーミング系のツール向けに規定した規格です。

WHEP は仕様を小さくして、実装を簡単にすることで配信ツールが取り込みやすくしています。

クライアントが HTTP POST で Offer SDP を送信して、Answer SDP を受け取るというシンプルなシグナリング規格です。

将来的に OBS で WebRTC/WHEP がサポートされる予定です。

WHEP のシーケンス図

        sequenceDiagram
  participant OBS as OBS
  participant WE as WHEP Endpoint
  participant MS as Media Server
  participant WS as WHEP Resource
  OBS->>+WE: HTTP POST (SDP Offer)
  WE-->>-OBS: HTTP 201 Created (SDP Answer)
  note over OBS,MS: WebRTC Connection
  OBS->>+WS: HTTP DELETE
  WS->>-OBS: HTTP 200 OK
    

Sora の WHEP のシーケンス図

Sora では WHEP エンドポイント、 WHEP リソース、メディアサーバーすべてを Sora が担当します。

        sequenceDiagram
   participant OBS as OBS
   participant S as Sora
   participant A as App
   OBS->>+S: HTTP POST (SDP Offer)
   S->>+A: 認証ウェブフック
   A-->>-S: 200 OK<br>allowed : true
   S-->>-OBS: HTTP 201 Created (SDP Answer)
   note over OBS,S: WebRTC Connection
   S->>+A: イベントウェブフック<br>connection.created
   A-->>-S: 200 OK
   OBS->>+S: HTTP DELETE
   S->>+A: イベントウェブフック<br>connection.destroyed
   A-->>-S: 200 OK
   S->>-OBS: HTTP 200 OK
    

OBS の WHEP 対応について

警告

OBS の WHEP 対応については Discord https://discord.gg/shiguredo の #sora-sdk-faq にてご相談ください。

OBS 30.2.0 では WHEP に対応していません。

以下の Pull-Request がマージされ、正式リリースされることで WHEP に対応予定です。 https://github.com/obsproject/obs-studio/pull/10353

WHEP は WHEP ソース として利用できるようになります。

OBS 以外の WHEP クライアントへの対応について

重要

Sora の WHEP 実装は OBS の WHEP 対応のみをサポートしています。 それ以外のクライアントの WHEP 実装には対応していません。

新しい WHEP クライアントへの対応は有償での優先実装として対応を検討できますので、 対応希望の WHEP クライアントと優先実装については、サポートまでメールにてご連絡ください。

• ブラウザ

• GStreamer

• FFmpeg

Sora での利用方法

WHEP

sora.conf にて whep を true に指定してください。

whep = true

Bearer トークンを利用した認証機能を利用する場合

sora.conf にて whep_bearer_token_metadata_key を指定してください。

whep_bearer_token_metadata_key = whep_access_token

例えば、 access_token という文字列をした場合、 WHEP 接続時、認証ウェブフックに "metadata": {"access_token": "<bearer_token>""} が入ってきます。 whep_token を指定した場合は "metadata": {"whep_token": "<bearer_token>""} が入ってきます。

whep_bearer_token_metadata_key が未指定の場合は、 Bearer トークンが WHIP/WHEP 接続時に送られてきたとしても Sora は無視して、 metadata も生成しません。

OBS での WHEP 利用方法

OBS での利用方法は以下の通りです。

1. シーンのソースに WHEP ソースを追加する

2. WHEP ソースに Sora が提供する WHEP エンドポイント URL を指定する

   • デフォルトでは http://127.0.0.1:5000/whep/<channel_id>

3. Bearer トークンには好きな文字列を指定する

   • Sora の認証ウェブフックの項目 whep_bearer_token_metadata_key で指定した値をキーとして、 "metadata": {"<whep_bearer_token_metadata_key>": "<bearer_token>""} が認証サーバーに送信されます

切断方法

Location ヘッダーに入ってくるリソースエンドポイント URL に DELETE リクエストを送ることで切断できます。

OBS は配信終了することで切断リクエストを送りますので、意識する必要はありません。

Sora の OBS (WHEP) の挙動

• Sora は WHEP エンドポイント URL を提供します

  • デフォルトでは http://127.0.0.1:5000/whep/<channel_id> です

• Sora の WHEP エンドポイントからの配信は、マルチストリームかつ視聴のみ(recvonly)として扱われます

• Sora の WHEP エンドポイントを利用した配信では、シグナリング通知は現時点では利用できません

• Sora の WHEP リソース URL は WHEP エンドポイントのレスポンスに含まれる Location ヘッダーにて払い出されます

• 同一チャネルに複数の配信が存在する場合、 WHEP での接続を認証前に接続を拒否します

• 同一チャネルに複数の配信始まった場合、 WHEP での接続を切断します

WHEP エンドポイント URL

Sora の OBS (WHEP) 対応は "multistream": true, "role": "recvonly" として機能します。

チャネル ID の指定

OBS ではリクエスト時に JSON でチャネル ID を指定することができません。そのため WHEP エンドポイント URL に channel_id を含めて指定します。 channel_id に URL に利用できない文字が含まれている場合は URL エンコードしてください。

HTTP POST https://sora.example.com/whep/<channel_id>

channel_id が sora の WHEP エンドポイント URL 例:

https://sora.example.com/whep/sora

WHEP エンドポイントへの HTTP リクエストに対するレスポンスコードは 201 Created です。

WHEP リソース URL

Sora では WHEP リソースエンドポイントは Location ヘッダーに含まれています。

以下は切断する例です。

HTTP DELETE https://sora.example.com/whep-resource/<channel_id>/<secret>

以下は Trickle ICE を利用する例です。

HTTP PATCH https://sora.example.com/whep-resource/<channel_id>/<secret>

<secret> は 32 バイトのランダムな値を base32 でエンコードした文字列です。

WHEP リソース URL 例:

https://sora.example.com/whep-resource/sora/QBF6AFDWZGWM97BNS5YCBSXM54M01D0TFQ48MC9Z3ZJG8YPRQ1Z0

注釈

OBS に Bearer トークンを指定した場合は、WHEP リソースエンドポイント URL にも Bearer トークンは送られます

認証仕様

WHEP では認証に Bearer トークンを指定することができます。

OBS でも認証情報に Bearer トークンを指定できます。

Sora は sora.conf で whep_bearer_token_metadata_key に文字列を指定していた場合、 OBS の HTTP POST 時に Authentication ヘッダーで送られてきた Bearer トークンを、 認証ウェブフックの metadata に {"<whep_bearer_token_metadata_key>": "<bearer_token>"} を設定して認証サーバーに送信します。

Sora 自体は Bearer トークンのチェックやデコードなどは行いません。これらは認証ウェブフックのリクエストを受信した認証サーバーが行う必要があります。

認証成功時の払い出し

WHEP では以下の項目が利用できます。

• client_id

• bundle_id

• event_metadata

• connection_lifetime

• playout_delay_min_delay

• playout_delay_max_delay

• turn_tcp_only

  • ただし 2024 年 12 月 現在では OBS WHEP は TURN に対応しておらず、 TURN-TCP にも対応していません

• turn_tls_only

  • ただし 2024 年 12 月 現在では OBS WHEP は TURN に対応しておらず、 TURN-TLS にも対応していません

ウェブフック仕様

whep

true が入ってきます。

ignore_disconnect_websocket

false が入ってきます。

metadata

sora.conf にて whep_bearer_token_metadata_key に指定した文字列をキーとして metadata に入ってきます。

whep_bearer_token_metadata_key = whep_bearer_token

もし文字列を whep_bearer_token にしていた場合は、 "metadata": {"whep_bearer_token": "<bearer-token>"} が送られてきます。

OBS 側に設定した Bearer Token の値がそのまま入ってきます。

multistream

true が入ってきます。

role

recvonly が入ってきます。

channel_id

WHEP エンドポイント URL に渡した値が利用されます。

注釈

URL デコード済みの値が入ります

client_id

WHEP エンドポイント URL にクエリ文字列として client_id=<client_id> を指定した場合、その値が利用されます。

注釈

URL デコード済みの値が入ります

bundle_id

WHEP エンドポイント URL にクエリ文字列として bundle_id=<bundle_id> を指定した場合、その値が利用されます。

注釈

URL デコード済みの値が入ります

spotlight

WHEP エンドポイント URL にクエリ文字列として spotlight=<boolean> を指定した場合、その値が利用されます。

注釈

URL デコード済みの値が入ります

audio / video

OBS 側で指定した値を利用します。 OBS では音声は Opus のみ、映像は H.264 が利用できます。

• audio: true

• audio_codec_type: "OPUS"

• video: true

• video_codec_type: "H264"

simulcast

false が入ってきます。

sora_client

OBS WHEP で User-Agent として送られてくる情報を sora_client に含めています。

"sora_client": {
  "raw": "Mozilla/5.0 (OBS-Studio/30.1.0; Mac OS X; ja-JP)",
  "type": "OBS-Studio-WHEP",
  "version": "30.1.0",
  "environment": "environment":"Mozilla/5.0 (OBS-Studio/30.1.0; Mac OS X; ja-JP)"
},

その他

• e2ee: false

• spotlight: false

• data_channel_signaling: false

• ignore_disconnect_webhook: false

• turn_transport_type: udp

  • TURN が利用不可能な WHEP 実装の場合は udp が割り当てられます

  • TURN が利用可能な WHEP 実装の場合は udp または tcp が適切に割り当てられます

TURN の利用

WHIP と同様の挙動です。 TURN の利用 をご確認ください。

クラスター利用時の挙動

WHIP と同様の挙動です。 クラスター利用時の挙動 をご確認ください。

シーケンス図

シングルノード

        sequenceDiagram
   participant WHIP as WHIP
   participant WHEP as WHEP
   participant S as Sora
   participant A as App
   note over WHIP, S: WebRTC 確立
   WHEP->>+S: HTTP POST https://sora.example.com/whep/<channel_id><br>Offer SDP
   S->>+A: 認証ウェブフック<br><br>"channel_id": "<channel_id>"<br>"multistream": true<br>"role": "recvonly"
   A-->>-S: "allowed": true
   S-->>-WHEP: HTTP 201 Created<br>Answer SDP

   Note left of S: このタイミングで Link ヘッダーで、<br>TURN URLs を払い出す

   note over WHEP,S: ICE 確立
   note over WHEP,S: DTLS 確立
   note over WHEP,S: WebRTC 確立

   S->>+A: イベントウェブフック<br>"connection.created"
   A-->>-S: HTTP 200 OK

   S-)WHEP: SRTP
   S-)WHEP: SRTP

   WHEP->>+S: HTTP DELETE https://sora.example.com/whep/<channel_id>/<secret>
   S-->>-WHEP: HTTP 200 OK

   note over WHEP,S: WebRTC 終了
    

TURN 機能

Sora は TURN 機能が組み込まれています。そのため TURN サーバーを別途立てる必要はありません。

推奨設定

一番接続率が高くなる設定は以下の通りです。

• TURN-TCP を 443 番ポートで待ち受け

• TURN-TLS を 443 番ポートで待ち受け

上記設定をしたい場合は TURN-TLS、TURN-TCP、シグナリングで 443 番ポートを使用する をご確認ください。

TURN はすべて同時に試される

TURN の経路を決定するのはクライアント側の実装に依存します

基本的に TURN 利用時には TURN-UDP と TURN-TCP と TURN-TLS をすべて同時に試みて、 確立が早かった経路を利用する仕組みが多いです。

ブラウザの TURN 対応状況

Chrome、Firefox、Edge、Safari は TURN-UDP / TURN-TCP / TURN-TLS に対応しています。

注意

Firefox では TURN の urls を 5 個より多く送るとエラーがコンソールに表示されます。

設定

Sora はデフォルトで TURN 機能が有効になっています

sora.conf

## TURN 機能を有効にするかどうかを指定してください
# turn = false

## TURN 機能で利用するレルムを指定してください
# turn_realm = sora-turn.example.com

## TURN 機能で TURN URL 払い出し機能で利用する FQDN (最後の . なし)を指定してください
# turn_fqdn = sora-turn.example.com

## TURN 機能で TURN-TCP を有効にするかどうかを指定してください
# turn_tcp = false

## TURN 機能で TURN-TCP を有効にした際に利用するポート番号を指定してください
# turn_tcp_listen_port = 3478

## TURN 機能で TURN-TCP URL 払い出し時のポート番号を指定してください
# turn_tcp_port = 3478

## TURN 機能で TURN-TLS URL 払い出し機能を有効にするかどうかを指定してください
## オプションでデフォルトは false です
# turn_tls = true

## TURN 機能で TURN-TLS URL 払い出し機能で利用する FQDN (最後の . なし)を指定してください
## turn_tls_fqdn は turn_fqdn の値を上書きします
# turn_tls_fqdn = sora-turn.example.com

## TURN 機能で TURN-TLS URL 払い出し機能を有効にした際に利用するポート番号を指定してください
# turn_tls_port = 5349

設定の優先順位

TURN が有効な場合 Sora が TURN 用の URL を生成する優先順位が存在します。

1. 認証時に外部サーバーから払い出される ipv4_address が採用されます

   • sora.conf で ipv6 が true の場合は払い出された ipv6_address も採用されます

2. 外部サーバーから ipv4_address が払い出されなかった場合は sora.conf の ipv4_address が採用されます

   • sora.conf で ipv6 が true の場合は sora.conf の ipv6_address も採用されます

3. TURN-TLS を有効にしている場合、外部サーバーから払い出される turn_tls_fqdn が払い出されなかった場合は sora.conf の turn_tls_fqdn が採用されます。 さらに turn_tls_fqdn が指定されてない場合は turn_fqdn が採用されます。

設定例 1

sora.conf

ipv4_address = 192.0.2.10

ipv6 = false

turn = true
turn_realm = sora-turn.example.com
turn_fqdn = sora-turn.example.com

turn_tcp = true
turn_tcp_listen_port = 3478
turn_tcp_port = 3478

turn_tls = true
turn_tls_fqdn = sora-turn.example.com
turn_tls_port = 5349

外部サーバーから払い出された turn_tls_fqdn が "sora-turn.example.com" の場合、払い出される TURN の urls は 3 つです。 UDP のポートは動的に決まるためここでは 54321 としています。

• turn:sora-turn.example.com:54321?transport=udp

• turn:sora-turn.example.com:3478?transport=tcp

• turns:sora-turn.example.com:5349?transport=tcp

設定例 2

• sora.conf

  • すべてデフォルト

  • 収集された IP アドレスは 192.0.2.10 と 192.0.2.20

• 外部サーバーから払い出し

  • なし

  • sora.conf の auth_webhook_url がコメントアウトされている

この場合、払い出される TURN の urls は 4 つです。 UDP のポートは動的に決まるためここでは 54321 としています。

• turn:192.0.2.10:54321?transport=udp

• turn:192.0.2.10:3478?transport=tcp

• turn:192.0.2.20:54321?transport=udp

• turn:192.0.2.20:3478?transport=tcp

内蔵 TURN 機能のメリット

• Sora との通信経路を強制的に TURN 経由に固定することで、効率よく接続の確立が行えます

  • "type": "candidate" を待つ必要がなく、 Answer さえ受け取ってしまえば接続の確立まで進めます

• 接続ごとに TURN に使用する Username や Credential を意識する必要がなくなります

• TURN-TCP や TURN-TLS 機能を使用することで UDP が使用できない環境でも WebRTC を利用できるようになります

Sora の TURN 機能

• TURN-UDP での TURN 機能

  • 動的なポートでの TURN-UDP にのみ対応しています

• TURN-TCP での TURN 機能

• TURN-TLS での TURN URL 払い出し機能

  • nginx の利用を前提とした機能です

• ワンタイムな Username や Credential、TURN の URL の自動払い出し

  • Sora がすべて自動で行ってくれます

  • Sora は TURN 機能に必要な Username や Credential をクライアントごとにワンタイムで生成します

• TURN-UDP / TURN-TCP の IPv6 対応

  • TURN で払い出す urls も IPv6 に対応します

  • TURN-TLS での IPv6 対応については nginx 依存となります

• TURN-TCP の Proxy Protocol 対応

  • nginx などを利用したリバースプロキシが前段にいて Proxy Protocol を利用する場合でも対応ができます

Sora の TURN-TCP 機能

• デフォルトでは有効になっていますので、無効にしたい場合は sora.conf の turn_tcp を false に指定してください

• TURN-TCP で受信するポート番号を指定したい場合は sora.conf の turn_tcp_listen_port を 3478 に指定してください

• TURN-TCP の設定で払い出すポート番号を指定したい場合は sora.conf の turn_tcp_port を 443 に指定してください

Sora の TURN-TLS URL 払い出し機能

Sora では TURN-TLS 機能は直接提供していません。 TLS の終端には nginx を利用します。 つまり nginx 側で TURN-TLS の TLS を終端して、 TURN-TCP として Sora に投げてもらいます。

重要

必ず turn_tcp の設定を有効にしてください

デフォルトでは無効になっていますので、有効にしたい場合は sora.conf で turn_tls を true に指定してください。

TURN-TLS で使用するポート番号を指定したい場合は sora.conf で turn_tls_port を 5349 のように指定してください。

さらに TURN-TLS では使用する場合はかならず証明書の FQDN を指定する必要があります。 sora-turn.example.com の証明書を使用する場合は sora.conf で turn_tls_fqdn を sora-turn.example.com のように指定してください。

詳細は TURN-TLS、TURN-TCP、シグナリングで 443 番ポートを使用する をご確認ください。

Sora の TURN IPv6 対応

IPv6 のアドレスが使用できる場合、クライアントに送られる TURN UDP/TCP サーバー機能も IPv6 で提供します。

TURN-TCP / TURN-TLS の検証

sora.conf の turn_tcp_only を true や turn_tls_only を true に設定することで強制的に TURN-TCP や TURN-TLS を利用できるようになります。

こちらは、あくまで検証のみで利用していただくことを想定している機能です。そのため有効にしている場合は sora.jsonl に warning メッセージが出力されます。

Sora TURN 機能の制限

Sora の TURN 機能には一部制限があります。

• TURN で使用される UDP のポート番号の固定ができない

  • TURN のポート番号は個々のクライアントに対して動的に生成されるため、固定できません。

この課題を解決したい場合は、 Sora の TURN 機能を無効にして、別途 TURN サーバーを立てる必要があります。 ただし、別途 TURN サーバーを立てることは推奨していません。

外部の TURN サーバーを使用する場合

警告

Sora の内蔵 TURN サーバーを無効にして外部の TURN サーバーを利用するのは非推奨です、もし利用したい場合はサポートまでご連絡ください

TURN 機能を使う場合の注意点

重要

弊社が提供している Sora の SDK を利用する場合は、 SDK 側で TURN 機能に対応しているため、対応は不要です

TURN 機能を使用する場合、 Sora はシグナリングの "type": "offer" メッセージを、WebSocket 経由でクライアントに送信します。 送信した JSON 形式のメッセージの "config" 項目に、 TURN 接続に必要な情報が含まれています。

この config を、 PeerConnection を new する際の引数に指定してください。

// ws_url は Sora のシグナリング API の URL を指定する
ws = new WebSocket(ws_url);
// WebSocket 経由で送られてきたメッセージのコールバックを指定する
ws.onmessage = onMessage;

function onMessage(event) {
    const message = JSON.parse(event.data);
    if (message.type == 'offer') {
        // TURN 機能を有効にした場合は offer メッセージの config に TURN で使用する情報が入っています
        const config = message.config;

        // 途中から省略しています
        RTCPeerConnection.generateCertificate({ name: "ECDSA", namedCurve: "P-256" })
            .then(function(certificate) {
                config.certificates = [certificate];
                // ここで RTCPeerConnection を生成する際の config に送られてきた config を指定してください
                peerConnection = new RTCPeerConnection(config);

この Sora から Offer として送られてくる config には、常に接続を TURN 経由で行う仕組みが入っています。

• urls に記載される URL の IP アドレスは sora.conf の ipv4_address に設定した値になります

• urls に記載される URL のポート番号は Sora が動的に生成したポートの値になります

• username と credential は Sora の TURN 機能が動的に生成したワンタイムな値が使用されます

// offer メッセージの config のサンプルです
config = {
  "iceTransportPolicy": "relay",
  // urls は Sora が動的に生成したポートを使用した URL が入ります
  "iceServers": [{"urls": ["turn:sora-turn.example.com:3478?transport=udp",
                           "turn:sora-turn.example.com:3478?transport=tcp",
                           "turns:sora-turn.example.com:5349?transport=tcp"],
                  "username": "one-time-username",
                  "credential": "one-time-credential"}]
};

シーケンス図

TURN への接続は同時に試す

TURN-UDP のポートは動的に決まります。

        sequenceDiagram
    autonumber
    participant C as クライアント
    participant nginx
    participant S as Sora
    C->>nginx: "type": "connect" over WSS
    note right of nginx: TLS 終端
    nginx->>S: "type": "connect" over WS
    S->>nginx: "type": "offer" over WS
    nginx->>C: "type": "offer" over WSS
    C->>nginx: "type": "answer" over WSS
    note right of nginx: TLS 終端
    nginx->>S: "type": "answer" over WS
    par
        C->>S: TURN-UDP Allocate-Request port=52520
    and
        C->>nginx: TURN-TCP Allocate-Request port=443
        nginx->>S: TURN-TCP Allocate-Request port=3478
    and
        C->>nginx: TURN-TLS Allocate-Request port=443
        note right of nginx: TLS 終端
        nginx->>S: TURN-TCP Allocate-Request port=3478
    end
    S->>C: TURN-UDP Allocate-Success
    C->>+S: TURN-UDP Permission-Request port=52520
    S-->>-C: TURN-UDP Permission-Success
    C->>+S: TURN-UDP Channel-Request port=52520
    S-->>-C: TURN-UDP Channel-Success
    C->>S: DTLS ClientHello over TURN port=52520
    

録画機能 (セッション単位)

レガシー録画機能から録画機能(セッション単位)への移行

レガシー録画機能から新しい録画機能 (セッション単位) への移行 を確認してください。

概要

Sora では、配信している映像や音声を録画、録音して保存できます。 配信されている映像をできるかぎりそのまま保存するため、CPU リソースを最小限に抑えることができます。 出力される録画ファイルは MP4 または WebM 形式です。映像のみの録画、音声のみの録音にも対応しています。

録画時には一切トランスコードを行っていません。配信された映像や音声をそのままに記録します。

用語

単一録画ファイル

切断または StopRecording API が実行されるか、録画期限が切れるか、セッションが破棄された場合に一つのファイルとして出力される動画ファイル

分割録画ファイル

split_duration で指定した時間ごとに区切られ分割されて出力される動画ファイル

録画ファイルの出力

録画ファイルの出力には 3 パターンあります。

単一録画ファイルのみ出力

• split_only が未指定、または false に設定されている

• split_duration が未指定

• expire_time は指定されていてもよい

上記を満たした場合、1 接続で 1 つ録画ファイルが出力されます。

分割録画ファイルのみ出力

• split_only が true に指定されている

• split_duration が指定されている

• expire_time は指定されていてもよい

上記を満たした場合、分割された録画ファイルのみが出力されます。

単一録画ファイルと分割録画ファイルの両方が出力

• sora.conf で recording_dual_output が true に指定されている

• split_only が未指定、または false に指定されている

• split_duration が指定されている

• expire_time は指定されていてもよい

上記を満たした場合、 1 接続で 1 つの録画ファイルと分割された録画ファイルの両方が出力されます。

イベントウェブフックも単一録画、分割録画、両方のイベントウェブフックリクエストが送信されます。

録画ファイルの出力形式

WebM と MP4 の 2 種類があります。

デフォルト設定

sora.conf で default_recording_format を指定することで、 録画ファイルのデフォルト出力形式を指定できます。

未指定の場合は WebM 形式で出力します。

MP4

MP4 形式を推奨します

Sora 2024.2.0 から対応しました。

H.265 の録画は MP4 形式のみ対応しています。

WebM

Google が開発した動画フォーマットです。

H.265 コーデックには非対応です。

制限

コーデック

録画 (録音) は、映像コーデックに VP8 と VP9 と AV1 と H.264 と H.265 、また音声コーデックに Opus を選択した場合のみ利用できます。

警告

• H.265 の録画は MP4 形式のみ対応しています

• B フレームの録画には非対応です

• VP8 とOpus の組み合わせの MP4 形式は Firefox で再生できません

解像度

WebRTC では配信側の CPU リソースが不足した場合や、 回線の品質が悪化した場合に解像度を動的に変更します。 そのため録画したデータの途中で解像度が低くなる可能性があります。

音声や映像のクライアント側でのトラック削除

クライアント側でシグナリング接続時に音声や映像を有効にした状態で、 クライアント側で音声トラック、または映像トラックのどちらかを削除した場合でも録画は行われます。 さらに追加して戻した形であれば録画側も戻ります。

ただし、音声と映像両方のトラックを削除した場合は正常に録画が行われません。

マルチストリーム機能での録画

対応しています。

サイマルキャスト機能での録画

対応しています。

サイマルキャストを利用している際の録画は 一番優先度が低い ストリーム、すなわちデフォルトでは最も高い画質の映像を録画します。

詳細はサイマルキャストの 映像の優先度 をご確認下さい。

スポットライト機能での録画

対応しています。

サイマルキャストを利用している際の録画は 一番優先度が低い ストリーム、すなわちデフォルトでは最も高い画質の映像を録画します。

詳細はサイマルキャストの 映像の優先度 をご確認下さい。

キーフレーム要求間隔

録画機能利用時の Sora からのキーフレーム要求間隔は以下の通りです。

• WebM 形式の場合 20 秒固定

• MP4 形式の場合 default_recording_mp4_pli_interval で指定した秒数 (デフォルトは 20 秒)

録画時のキーフレーム要求間隔を変更したい場合は、MP4 形式の録画を行ってください。

分割録画ファイルの録画時間

分割録画ファイルの時間はキーフレームの到着タイミングにより前後するため、 split_duration に指定した時間から前後することがあります。

無変換録画

WebRTC 経由で流れてきている映像や音声を変換せず、 そのまま録画するファイルの形式に組み立て直してファイルを保存します。 そのため、CPU リソースを最小限に抑えられます。 ブラウザでの録画など、通常の録画は変換が入るため CPU に多くの負荷がかかります。

変換を行わないため、録画を終了した数秒後には録画したファイルを取得できます。

解像度は送られてきた映像の最大値を録画ファイルの解像度として使用します。

録画の開始と終了について

Sora の録画機能は 明示的にチャネルの録画を停止するか、 チャネルの録画開始から指定した期限が過ぎるか、 チャネルのセッションが破棄されるまでは、 そのチャネルでの配信を自動で録画する といった機能になります。

コネクション単位の録画ブロックについて

認証成功時に "recording_block": true を払い出すことでコネクション単位で録画をブロックし、録画ファイルの出力を行わないようにすることができます。

録画ブロックは認証成功時の払い出し時のみ指定ができます。それ以外では指定できません。 そのため、録画ブロックの途中解除はできません。

コネクションごとの録画ブロックの設定状況は ListConnections API の recording_block または ListChannelConnections の recording_block で確認できます。

シーケンス図

        sequenceDiagram
    autonumber
    participant C as クライアント
    participant S as Sora
    participant A as アプリケーションサーバー
    C->>+S: "type": "connect"
    S->>+A: 認証ウェブフック
    A-->>-S: 200 OK<br>"recording_block": true
    S-->>-C: "type": "offer"
    C->>S: "type": "answer"
    note over C,A: WebRTC 確立
    S->>+A: セッションウェブフック: "session.created"
    A-->>-S: 200 OK<br>"recording": true
    note over C,A: 録画開始
    S->>+A: セッションウェブフック<br/>"type": "recording.started"
    A-->>-S: 200 OK
    note over C,A: 録画ブロックしているため "archive.started" が飛ばない<br>さらに録画ファイルは出力されない
    

sora.conf の設定による録画指定制限

録画ファイルが大きくならないように、sora.conf の指定で録画開始時のオプションを制限することができます。

設定の詳細は以下をご確認ください。

• recording_max_expire_time

• recording_max_split_duration

• recording_expire_time_required

• recording_dual_output

MP4 形式のキーフレーム要求間隔の変更

録画時には一定間隔で Sora からクライアントへキーフレーム要求 (PLI) を送ります。

WebM 形式ではキーフレームの間隔が最大でも 31 秒までという制約がありましたが、 MP4 形式ではこの制約がなくなりました。

そのため、 MP4 形式ではこの間隔を default_recording_mp4_pli_interval で変更する事ができます。

デフォルトは 20 s で、最小が 1 s で、最大が 240 s です。

設定例

default_recording_mp4_pli_interval = 100 s

録画情報の API 経由での取得

録画情報を取得するには セッション API を利用します。

指定したセッションの録画情報を取得する

GetSession API を利用することで、指定したセッションの録画状態を取得することができます。

録画が開始されているセッションは recording 項目が存在します。

{
  "label": "WebRTC SFU Sora",
  "node_name": "[email protected]",
  "version": "2024.1.0",
  "channel_id": "sora",
  "session_id": "JJJ5BFH7QN6DQBTKSS7JA8ZYQR",
  "session_metadata":  {"spam": "egg"},
  "created_time": 1638337454,
  "created_timestamp": "2021-12-01T05:44:14.523736Z",
  "multistream": true,
  "spotlight": false,
  "max_connections": 4,
  "total_connections": 4,
  "external_signaling_url": "wss://node-01.example.com/signaling",
  "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",
    "format": "mp4"
  }
}

全てのセッションの録画情報を取得する

ListSessions API を利用することで、全てのセッションの録画状態を取得することができます。

録画が開始されているセッションは recording 項目が存在します。

[
  {
    "label": "WebRTC SFU Sora",
    "node_name": "[email protected]",
    "version": "2024.1.0",
    "channel_id": "sora",
    "session_id": "JJJ5BFH7QN6DQBTKSS7JA8ZYQR",
    "session_metadata":  {"spam": "egg"},
    "created_time": 1638337454,
    "created_timestamp": "2021-12-01T05:44:14.523736Z",
    "multistream": true,
    "spotlight": false,
    "max_connections": 4,
    "total_connections": 4,
    "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: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": "JXMYW6GPX54EH0HGA5X4130FBM",
        "bundle_id": "JXMYW6GPX54EH0HGA5X4130FBM",
        "connection_id": "JXMYW6GPX54EH0HGA5X4130FBM",
        "connection_created_timestamp": "2021-12-01T05:44:23.051704Z",
        "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 },
      }
    ],
    "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",
      "format": "mp4"
    }
  }
]

録画関連イベントのウェブフックについて

session.created ウェブフック

注意

sora.conf の設定による録画指定制限 を行っていた場合、制限に該当する指定を行っている場合は録画が開始されません。

払い出し時に以下の項目が指定できます。

• recording

  • boolean

  • そのセッションでの録画を開始するかどうかを指定します

  • オプション

• recording_expire_time

  • integer

  • そのセッションでの録画期限を指定します

  • デフォルト値は未定義で、期限なしです

  • 指定する場合 0 より大きな値を指定してください

  • 単位は秒です

  • オプション

• recording_split_only

  • boolean

  • そのセッションでの録画を分割のみにするかを指定します

  • デフォルト値は false で、分割を行いません

  • オプション

• recording_split_duration

  • integer

  • そのセッションでの録画を分割する場合の分割時間を指定します

  • recording_split_only が true の場合は指定が必須です

  • オプション

• recording_metadata

  • JSONValue

  • そのセッションでの録画メタデータを指定します

  • オプション

• recording_format

  • string

  • そのセッションでの録画ファイルのフォーマットを指定します

  • webm と mp4 が指定できます

  • オプション

recording.started セッションウェブフック

注釈

レガシー録画ではイベントウェブフックでしたが、セッションウェブフックに変更されています

録画開始 API が実行されたタイミングで recording.started リクエストを送信します。

詳しくは recording.started をご確認ください。

recording.report セッションウェブフック

録画終了 API が実行されたか、 録画の期限が切れたか、 セッションが破棄されたタイミングで recording.report リクエストを送信します。

注釈

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

詳しくは recording.report をご確認ください。

archive.started ウェブフック

録画ファイルを保存しはじめたタイミングで archive.started リクエストを送信します。

詳しくは archive.started をご確認ください。

archive.available イベントウェブフック

単一録画ファイルが出力されたタイミングで archive.available リクエストを送信します。

詳しくは archive.available をご確認ください。

split-archive.available イベントウェブフック

録画ファイル分割出力機能を有効にした場合、 分割された録画ファイルが出力されたタイミングで split-archive.available リクエストを送信します。

詳しくは split-archive.available をご確認ください。

split-archive.end イベントウェブフック

録画ファイル分割出力機能を有効にした場合、 分割された録画が終了したタイミングで split-archive.end リクエストを送信します。

詳しくは split-archive.end をご確認ください。

archive.failed イベントウェブフック

録画ファイルの保存に失敗した場合、 archive.failed リクエストを送信します。

詳しくは archive.failed をご確認ください。

単一録画ファイル出力のみ

単一録画ファイル出力のみの場合は sora.conf の archive_dir に指定したディレクトリに recording_id 名のディレクトリ以下にファイルが出力されます。

recording_id は録画開始 API を実行したときに戻ってくる値で、 Base32 でエンコードされた UUIDv4 となります。

ディレクトリ構造:

├── archive
│   ├── 1CS9QJ0XPN4C76HBGBN6MGMK5M
│   │   ├── archive-A4756MXP914ZB265E92JE3ZMWC.json
│   │   ├── archive-A4756MXP914ZB265E92JE3ZMWC.mp4
│   │   ├── archive-H2NDA2YCGH7S1E9CVMFMXMA34R.json
│   │   ├── archive-H2NDA2YCGH7S1E9CVMFMXMA34R.mp4
│   │   ├── archive-PBVZQQN3JS3MQF8XHVFXDMCEEC.json
│   │   ├── archive-PBVZQQN3JS3MQF8XHVFXDMCEEC.mp4
│   │   └── report-1CS9QJ0XPN4C76HBGBN6MGMK5M.json
│   └── CZZ8A8KZB16A1DF5PKERBHGFNR
│       ├── archive-3B7AFF8ZRX6VNEYV40B35Z9S2C.json
│       ├── archive-3B7AFF8ZRX6VNEYV40B35Z9S2C.mp4
│       ├── archive-DGSN3TC0E91RSCZT5KVPRWCDHR.json
│       ├── archive-DGSN3TC0E91RSCZT5KVPRWCDHR.mp4
│       └── report-CZZ8A8KZB16A1DF5PKERBHGFNR.json

注意

archive_dir と archive_tmp_dir は違うディレクトリを指定して下さい

archive-<connection_id>

単一録画ファイル

単一録画ファイルは <recording_id>/archvie-<connection_id>.{mp4,webm} に WebM または MP4 形式で出力されます。

単一録画メタデータファイル

単一録画メタデータファイルは <recording_id>/archive-<connection_id>.json に JSON 形式で出力されます。

メタデータファイルには WebM または MP4 ファイルがいつ出力され、どんな形式なのか、開始時刻や終了時刻などの情報が含まれています。

• start_timestamp

  • この録画が開始した時刻を RFC 3339 (UTC) で表しています

• stop_timestamp

  • この録画が終了した時刻を RFC 3339 (UTC) で表しています

• start_time

  • この録画が開始された時刻を UNIX 時間で表しています

• stop_time

  • この録画が終了した時刻を UNIX 時間で表しています

stats は省略しています

{
  "audio": true,
  "audio_codec_type": "OPUS",
  "channel_id": "sora",
  "session_id": "JA8FB89ZJS1H9CV5GN3NCT5RA0",
  "client_id": "GK2R6PSDYX68VDQPRX4FVVFN8W",
  "bundle_id": "GK2R6PSDYX68VDQPRX4FVVFN8W",
  "connection_id": "GK2R6PSDYX68VDQPRX4FVVFN8W",
  "created_at": 1615524156,
  "file_path": "/path/to/sora/archive/WHEJ888HQ55KDCFE3TZ4VPFQHR/archive-GK2R6PSDYX68VDQPRX4FVVFN8W.mp4",
  "filename": "WHEJ888HQ55KDCFE3TZ4VPFQHR/archive-GK2R6PSDYX68VDQPRX4FVVFN8W.mp4",
  "metadata_file_path": "/path/to/sora/archive/WHEJ888HQ55KDCFE3TZ4VPFQHR/archive-GK2R6PSDYX68VDQPRX4FVVFN8W.json",
  "metadata_filename": "WHEJ888HQ55KDCFE3TZ4VPFQHR/archive-GK2R6PSDYX68VDQPRX4FVVFN8W.json",
  "recording_id": "WHEJ888HQ55KDCFE3TZ4VPFQHR",
  "size": 0,
  "start_time": 1615524137,
  "start_time_offset": 7,
  "start_timestamp": "2021-03-12T04:42:17.455668Z",
  "stats": {},
  "stop_time": 1615524154,
  "stop_time_offset": 24,
  "stop_timestamp": "2021-03-12T04:42:34.094375Z",
  "label": "WebRTC SFU Sora",
  "node_name": "[email protected]",
  "event_metadata": {"spam": "egg"},
  "video": true,
  "video_bit_rate": 1000,
  "video_codec_type": "VP9",
  "video_vp9_params": {
    "profile_id": 0
  },
  "video_height": 480,
  "video_width": 640,
  "format": "mp4"
}

report-<recording_id>

録画終了時に、それまでにそのセッションで録画したファイル一覧が記載されているレポートファイルが JSON 形式で出力されます。 録画終了は StopRecording API を使用して指定したチャネルに対する録画を停止するか、 録画の期限が切れるか、セッションが破棄されるかの 3 つのパターンがあります。

このファイルは主にマルチストリームや途中で切れてしまった場合などを考慮しており、 録画ファイルのグルーピングを目的としたファイルです。

ファイルは <recording_id>/report-<recording_id>.json に出力されます。

• トップレベルの start_timestamp

  • StartRecording API を受け付た時刻を RFC 3339 (UTC) で表しています

• トップレベルの stop_timestamp

  • StopRecording API を受け付た時刻か、 StartRecording API で 設定された期限の時刻を RFC 3339 (UTC) で表しています

• archives 内の start_time_offset

  • StartRecording API を叩いてから何秒経過した後にこの録画が開始したかを表しています

• archives 内の stop_time_offset

  • StartRecording API を叩いてから何秒経過した後にこの録画が終了したかを表しています

{
  "archives": [
    {
      "client_id": "GK2R6PSDYX68VDQPRX4FVVFN8W",
      "bundle_id": "GK2R6PSDYX68VDQPRX4FVVFN8W",
      "connection_id": "GK2R6PSDYX68VDQPRX4FVVFN8W",
      "file_path": "/path/to/sora/archive/WHEJ888HQ55KDCFE3TZ4VPFQHR/archive-GK2R6PSDYX68VDQPRX4FVVFN8W.mp4",
      "filename": "WHEJ888HQ55KDCFE3TZ4VPFQHR/archive-GK2R6PSDYX68VDQPRX4FVVFN8W.mp4",
      "metadata_file_path": "/path/to/sora/archive/WHEJ888HQ55KDCFE3TZ4VPFQHR/archive-GK2R6PSDYX68VDQPRX4FVVFN8W.json",
      "metadata_filename": "WHEJ888HQ55KDCFE3TZ4VPFQHR/archive-GK2R6PSDYX68VDQPRX4FVVFN8W.json",
      "size": 0,
      "start_time_offset": 0,
      "start_timestamp": "2021-03-12T04:42:17.455668Z",
      "stop_time_offset": 17,
      "stop_timestamp": "2021-03-12T04:42:34.094375Z",
      "label": "WebRTC SFU Sora",
      "node_name": "[email protected]"
    }
  ],
  "channel_id": "sora",
  "created_at": 1615524137,
  "expire_time": 3600,
  "expired_at": 1615527737,
  "file_path": "/path/to/sora/archive/WHEJ888HQ55KDCFE3TZ4VPFQHR/report-WHEJ888HQ55KDCFE3TZ4VPFQHR.json",
  "filename": "WHEJ888HQ55KDCFE3TZ4VPFQHR/report-WHEJ888HQ55KDCFE3TZ4VPFQHR.json",
  "recording_metadata": {"spam": "egg"},
  "recording_id": "WHEJ888HQ55KDCFE3TZ4VPFQHR",
  "split_only": false,
  "start_timestamp": "2021-03-12T04:42:17.455668Z",
  "stop_timestamp": "2021-03-12T04:42:34.094375Z",
  "format": "mp4"
}

分割録画ファイル出力のみ

Sora では StartRecording API 実行時に split_only: true と split_duration の 2 つを指定することで、 録画ファイルを指定した間隔で出力する機能を提供しています。

重要

分割の最小単位はキーフレームから次のキーフレームまでです。例えば split_duration を 1 秒に設定した場合は、1 秒経過後に次のキーフレームが来たタイミングで分割出力されます。

録画が完了したファイルは sora.conf の archive_dir に指定したディレクトリに recording_id 名のディレクトリ以下にファイルが出力されます。

recording_id は StartRecording API を実行したときに戻ってくる値です。

録画ファイル分割出力のみを行う

録画開始 API 実行時に split_only: true と split_duration の 2 つを指定することで、 録画ファイル分割出力 のみ を行うことが可能になります。

ディレクトリ構造:

├── archive
│   ├── 1CS9QJ0XPN4C76HBGBN6MGMK5M
│   │   ├── split-archive-end-A4756MXP914ZB265E92JE3ZMWC.json
│   │   ├── split-archive-A4756MXP914ZB265E92JE3ZMWC_0001.json
│   │   ├── split-archive-A4756MXP914ZB265E92JE3ZMWC_0001.mp4
│   │   ├── split-archive-A4756MXP914ZB265E92JE3ZMWC_0002.json
│   │   ├── split-archive-A4756MXP914ZB265E92JE3ZMWC_0002.mp4
│   │   ├── split-archive-A4756MXP914ZB265E92JE3ZMWC_0003.json
│   │   ├── split-archive-A4756MXP914ZB265E92JE3ZMWC_0003.mp4
│   │   ├── split-archive-A4756MXP914ZB265E92JE3ZMWC_0003.json
│   │   ├── split-archive-A4756MXP914ZB265E92JE3ZMWC_0003.mp4
│   │   └── report-1CS9QJ0XPN4C76HBGBN6MGMK5M.json
│   └── CZZ8A8KZB16A1DF5PKERBHGFNR
│       ├── split-archive-end-3B7AFF8ZRX6VNEYV40B35Z9S2C.json
│       ├── split-archive-end-DGSN3TC0E91RSCZT5KVPRWCDHR.json
│       ├── split-archive-3B7AFF8ZRX6VNEYV40B35Z9S2C_0001.json
│       ├── split-archive-3B7AFF8ZRX6VNEYV40B35Z9S2C_0001.mp4
│       ├── split-archive-DGSN3TC0E91RSCZT5KVPRWCDHR_0001.json
│       ├── split-archive-DGSN3TC0E91RSCZT5KVPRWCDHR_0001.mp4
│       ├── split-archive-DGSN3TC0E91RSCZT5KVPRWCDHR_0002.json
│       ├── split-archive-DGSN3TC0E91RSCZT5KVPRWCDHR_0002.mp4
│       └── report-CZZ8A8KZB16A1DF5PKERBHGFNR.json

split-archive-<connection_id>_<split_index>

分割録画ファイル

分割録画ファイルは <recording_id>/split-archvie-<connection_id>_<split_index>.{mp4,webm} に WebM または MP4 形式で出力されます。

分割録画メタデータファイル

分割録画メタデータファイルは <recording_id>/split-archive-<connection_id>_<split_index>.json に JSON 形式で出力されます。

• split_index

  • ファイル名につくインデックスです

  • 0001 から始まり 9999 の後は 10000 となります

stats は省略しています

{
  "audio": true,
  "audio_codec_type": "OPUS",
  "recording_id": "CZZ8A8KZB16A1DF5PKERBHGFNR",
  "file_path": "/path/to/sora/archive/CZZ8A8KZB16A1DF5PKERBHGFNR/split-archive-3B7AFF8ZRX6VNEYV40B35Z9S2C_001.mp4",
  "filename": "CZZ8A8KZB16A1DF5PKERBHGFNR/split-archive-3B7AFF8ZRX6VNEYV40B35Z9S2C_001.mp4",
  "metadata_file_path": "/path/to/sora/split-archive/CZZ8A8KZB16A1DF5PKERBHGFNR/archive-3B7AFF8ZRX6VNEYV40B35Z9S2C_001.json",
  "metadata_filename": "CZZ8A8KZB16A1DF5PKERBHGFNR/split-archive-3B7AFF8ZRX6VNEYV40B35Z9S2C_001.json",
  "channel_id": "sora",
  "session_id": "JA8FB89ZJS1H9CV5GN3NCT5RA0",
  "client_id": "3B7AFF8ZRX6VNEYV40B35Z9S2C",
  "bundle_id": "3B7AFF8ZRX6VNEYV40B35Z9S2C",
  "connection_id": "3B7AFF8ZRX6VNEYV40B35Z9S2C",
  "split_index": "0001",
  "created_at": 1604656364,
  "size": 823263,
  "start_time": 1604656354,
  "start_time_offset": 4,
  "start_timestamp": "2020-11-06T09:52:34.696758Z",
  "stats": {},
  "stop_time": 1604656364,
  "stop_time_offset": 14,
  "stop_timestamp": "2020-11-06T09:52:44.493179Z",
  "label": "WebRTC SFU Sora",
  "node_name": "[email protected]",
  "event_metadata": {"spam": "egg"},
  "video": true,
  "video_bit_rate": 1000,
  "video_codec_type": "VP9",
  "video_vp9_params": {
    "profile_id": 0
  },
  "video_height": 480,
  "video_width": 640,
  "format": "mp4"
}

split-archive-end-<connection_id>

分割録画終了メタデータファイル

分割録画終了メタデータファイルは <recording_id>/split-archive-end-<connection_id>.json に JSON 形式で出力されます。

stats は省略しています

{
  "audio": true,
  "audio_codec_type": "OPUS",
  "split_last_index": "0042",
  "recording_id": "CZZ8A8KZB16A1DF5PKERBHGFNR",
  "file_path": "/path/to/sora/archive/CZZ8A8KZB16A1DF5PKERBHGFNR/split-archive-end-3B7AFF8ZRX6VNEYV40B35Z9S2C.json",
  "filename": "CZZ8A8KZB16A1DF5PKERBHGFNR/split-archive-end-3B7AFF8ZRX6VNEYV40B35Z9S2C.json",
  "channel_id": "sora",
  "session_id": "JA8FB89ZJS1H9CV5GN3NCT5RA0",
  "client_id": "3B7AFF8ZRX6VNEYV40B35Z9S2C",
  "bundle_id": "3B7AFF8ZRX6VNEYV40B35Z9S2C",
  "connection_id": "3B7AFF8ZRX6VNEYV40B35Z9S2C",
  "start_time": 1604656354,
  "start_time_offset": 4,
  "start_timestamp": "2020-11-06T09:52:34.696758Z",
  "stats": {},
  "stop_time": 1604656364,
  "stop_time_offset": 14,
  "stop_timestamp": "2020-11-06T09:52:44.493179Z",
  "label": "WebRTC SFU Sora",
  "node_name": "[email protected]",
  "event_metadata": {"spam": "egg"},
  "video": true,
  "video_bit_rate": 1000,
  "video_codec_type": "VP9",
  "video_vp9_params": {
    "profile_id": 0
  },
  "format": "mp4"
}

録画ファイル分割出力終了時

コネクション単位での録画が終了したタイミングでイベントウェブフックリクエスト split-archive.end がリクエスト送信されます。

詳細は split-archive.end をご確認ください。

report-<recording_id>

録画終了時に、それまでにそのチャネルで録画したファイル一覧が記載されているレポートファイルが JSON 形式で出力されます。 録画終了は StopRecording API を使用して指定したチャネルに対する録画を停止するか、 録画の期限が切れるか、セッションが破棄されるかの 3 つのパターンがあります。

このファイルは主にマルチストリームや途中で切れてしまった場合などを考慮しており、 録画ファイルのグルーピングを目的としたファイルです。

ファイルは <recording_id>/report-<recording_id>.json に出力されます。

分割録画ファイル出力のみの場合は archives には connection_id や client_id といった接続情報と、 分割録画ファイルの最後のインデックス番号のみが含まれます。

• トップレベルの start_timestamp

  • StartRecording API を受け付た時刻を RFC 3339 (UTC) で表しています

• トップレベルの stop_timestamp

  • StopRecording API を受け付た時刻か、 StartRecording API で 設定された期限の時刻を RFC 3339 (UTC) で表しています

• archives 内の start_time_offset

  • StartRecording API を叩いてから何秒経過した後にこの録画が開始したかを表しています

• archives 内の stop_time_offset

  • StartRecording API を叩いてから何秒経過した後にこの録画が終了したかを表しています

{
  "archives": [
    {
      "client_id": "GK2R6PSDYX68VDQPRX4FVVFN8W",
      "bundle_id": "GK2R6PSDYX68VDQPRX4FVVFN8W",
      "connection_id": "GK2R6PSDYX68VDQPRX4FVVFN8W",
      "split_last_index": "0042"
      "start_time_offset": 4,
      "start_timestamp": "2020-11-06T09:52:34.696758Z",
      "stop_time_offset": 14,
      "stop_timestamp": "2020-11-06T09:52:44.493179Z",
      "label": "WebRTC SFU Sora",
      "node_name": "[email protected]"
    }
  ],
  "channel_id": "sora",
  "created_at": 1615524137,
  "expire_time": 3600,
  "expired_at": 1615527737,
  "file_path": "/path/to/sora/archive/WHEJ888HQ55KDCFE3TZ4VPFQHR/report-GK2R6PSDYX68VDQPRX4FVVFN8W.json",
  "filename": "WHEJ888HQ55KDCFE3TZ4VPFQHR/report-GK2R6PSDYX68VDQPRX4FVVFN8W.json",
  "recording_id": "WHEJ888HQ55KDCFE3TZ4VPFQHR",
  "split_duration": 3600,
  "split_only": false,
  "recording_metadata": {"spam": "egg"},
  "start_timestamp": "2020-11-06T09:52:34.696758Z",
  "stop_timestamp": "2020-11-06T09:52:44.493179Z",
  "format": "mp4"
}

単一録画ファイルと分割録画ファイル

StartRecording API 実行時に split_only を有効にしない限り、 単一ファイルと分割ファイルの二つが出力されます。 単一録画ファイルと分割録画ファイルのいいところ取りですが、その分ストレージの容量も 2 倍消費します。

出力されるファイルは単一と分割のファイルが混ざった形式になります。

ディレクトリ構造:

├── archive
│   ├── 1CS9QJ0XPN4C76HBGBN6MGMK5M
│   │   ├── split-archive-end-A4756MXP914ZB265E92JE3ZMWC.json
│   │   ├── split-archive-A4756MXP914ZB265E92JE3ZMWC_0001.json
│   │   ├── split-archive-A4756MXP914ZB265E92JE3ZMWC_0001.mp4
│   │   ├── split-archive-A4756MXP914ZB265E92JE3ZMWC_0002.json
│   │   ├── split-archive-A4756MXP914ZB265E92JE3ZMWC_0002.mp4
│   │   ├── split-archive-A4756MXP914ZB265E92JE3ZMWC_0003.json
│   │   ├── split-archive-A4756MXP914ZB265E92JE3ZMWC_0003.mp4
│   │   ├── split-archive-A4756MXP914ZB265E92JE3ZMWC_0004.json
│   │   ├── split-archive-A4756MXP914ZB265E92JE3ZMWC_0004.mp4
│   │   ├── archive-A4756MXP914ZB265E92JE3ZMWC.json
│   │   ├── archive-A4756MXP914ZB265E92JE3ZMWC.mp4
│   │   └── report-1CS9QJ0XPN4C76HBGBN6MGMK5M.json
│   └── CZZ8A8KZB16A1DF5PKERBHGFNR
│       ├── split-archive-end-3B7AFF8ZRX6VNEYV40B35Z9S2C.json
│       ├── split-archive-3B7AFF8ZRX6VNEYV40B35Z9S2C_0001.json
│       ├── split-archive-3B7AFF8ZRX6VNEYV40B35Z9S2C_0001.mp4
│       ├── split-archive-end-DGSN3TC0E91RSCZT5KVPRWCDHR.json
│       ├── split-archive-DGSN3TC0E91RSCZT5KVPRWCDHR_0001.json
│       ├── split-archive-DGSN3TC0E91RSCZT5KVPRWCDHR_0001.mp4
│       ├── split-archive-DGSN3TC0E91RSCZT5KVPRWCDHR_0002.json
│       ├── split-archive-DGSN3TC0E91RSCZT5KVPRWCDHR_0002.mp4
│       ├── archive-3B7AFF8ZRX6VNEYV40B35Z9S2C.json
│       ├── archive-3B7AFF8ZRX6VNEYV40B35Z9S2C.mp4
│       ├── archive-DGSN3TC0E91RSCZT5KVPRWCDHR.json
│       ├── archive-DGSN3TC0E91RSCZT5KVPRWCDHR.mp4
│       └── report-CZZ8A8KZB16A1DF5PKERBHGFNR.json

report-<recording_id>

出力される report ファイルは単一と分割が混ざった形式になります。

• トップレベルの start_timestamp

  • StartRecording API を受け付た時刻を RFC 3339 (UTC) で表しています

• トップレベルの stop_timestamp

  • StopRecording API を受け付た時刻か、 StartRecording API で 設定された期限の時刻を RFC 3339 (UTC) で表しています

• archives 内の start_time_offset

  • StartRecording API を叩いてから何秒経過した後にこの録画が開始したかを表しています

• archives 内の stop_time_offset

  • StartRecording API を叩いてから何秒経過した後にこの録画が終了したかを表しています

{
  "archives": [
    {
      "client_id": "GK2R6PSDYX68VDQPRX4FVVFN8W",
      "bundle_id": "GK2R6PSDYX68VDQPRX4FVVFN8W",
      "connection_id": "GK2R6PSDYX68VDQPRX4FVVFN8W",

      "file_path": "/path/to/sora/archive/WHEJ888HQ55KDCFE3TZ4VPFQHR/archive-GK2R6PSDYX68VDQPRX4FVVFN8W.mp4",
      "filename": "WHEJ888HQ55KDCFE3TZ4VPFQHR/archive-GK2R6PSDYX68VDQPRX4FVVFN8W.mp4",
      "metadata_file_path": "/path/to/sora/archive/WHEJ888HQ55KDCFE3TZ4VPFQHR/archive-GK2R6PSDYX68VDQPRX4FVVFN8W.json",
      "metadata_filename": "WHEJ888HQ55KDCFE3TZ4VPFQHR/archive-GK2R6PSDYX68VDQPRX4FVVFN8W.json",
      "size": 0,
      "start_time_offset": 0,
      "start_timestamp": "2021-03-12T04:42:17.455668Z",
      "stop_time_offset": 17,
      "stop_timestamp": "2021-03-12T04:42:34.094375Z",

      "split_last_index": "0042",
      "label": "WebRTC SFU Sora",
      "node_name": "[email protected]"
    }
  ],
  "channel_id": "sora",
  "created_at": 1615524137,
  "expire_time": 3600,
  "expired_at": 1615527737,
  "file_path": "/path/to/sora/archive/WHEJ888HQ55KDCFE3TZ4VPFQHR/report-WHEJ888HQ55KDCFE3TZ4VPFQHR.json",
  "filename": "WHEJ888HQ55KDCFE3TZ4VPFQHR/report-WHEJ888HQ55KDCFE3TZ4VPFQHR.json",
  "recording_id": "WHEJ888HQ55KDCFE3TZ4VPFQHR",
  "label": "WebRTC SFU Sora",
  "node_name": "[email protected]",
  "split_duration": 3600,
  "split_only": false,
  "recording_metadata": {"spam": "egg"},
  "start_timestamp": "2021-03-12T04:42:17.455668Z",
  "stop_timestamp": "2021-03-12T04:42:34.094375Z",
  "format": "mp4"
}

録画ファイル出力失敗時の録画一時ファイル

何らかの理由で録画ファイル出力が失敗した場合、 archive_tmp_dir で指定したディレクトリに録画一時ファイルが削除されずに残ります。そのため、定期的な削除が必要です。

この録画一時ファイルは WebM または MP4 形式のためそのまま再生できます。

シグナリング通知

シグナリング通知で録画開始と終了を通知できます。

詳細は 録画のシグナリング通知 をご確認ください。

録画ファイル合成ツール

マルチストリームを録画した場合はそれぞれの接続に対して録画ファイルが出力されます。このそれぞれ分かれた録画ファイルを合成して一つにするツールをオープンソースとして公開しています。

詳細は WebRTC 録画合成ツール Hisui をご確認ください。

録画ファイルアップロードツール

録画ファイルを S3 または S3 互換オブジェクトストレージにアップロードするツールをオープンソースとして公開しています。

詳細は Sora Archive Uploader をご確認ください

試してみる

Sora では録画機能を試すための開発ツールを提供しています。 開発ツール を参照の上、開発ツールを有効にしてください。

ここでは Sora が立っているサーバーは example.com としています。

録画開始

録画を開始するにはセッションウェブフックで "recording": true を払い出すか録画開始 StartRecording API を叩く必要があります。

ここでは API を叩いて録画を開始してみましょう。

録画を開始するにはセッションが存在する必要があるため、API を叩く前にクライアントの接続を行い、セッションを作成してください。

$ http POST example.com:3000/ \
    x-sora-target:Sora_20231220.StartRecording \
    channel_id=sora -vvv

その後 https://example.com/sendonly.html を開き、 connect ボタンを押して配信を開始します。

切断またはチャネルの録画終了、もしくはチャネルの録画期限が来たタイミングでクライアント単位の録画は終了します。

セッションが破棄されたタイミングで録画は終了します。

録画終了

録画を終了するには全ての参加者が離脱し、セッションが破棄されるか、 API を叩く必要があります。

ここでは API を叩いて録画を終了してみましょう。

$ http POST example.com:3000/ \
    x-sora-target:Sora_20231220.StopRecording \
    channel_id=sora -vvv

その後 archive/ ディレクトリに WebM または MP4 形式のファイルが出力されます。 Chrome または Firefox にドラッグアンドドロップして、動作を確認してください。

シーケンス図

録画 API

        sequenceDiagram
    autonumber
    participant C as クライアント
    participant S as Sora
    participant A as アプリケーションサーバー
    note over C,A: 認証成功
    S->>+A: セッションウェブフック: "session.created"
    A-->>-S: 200 OK
    S->>+C: "type": "offer"
    C->>-S: "type": "answer"
    note over C,A: WebRTC 確立
    S->>+A: イベントウェブフック: "connection.created"
    A-->>-S: 200 OK
    A->>+S: HTTP API StartRecording
    S-->>-A: 200 OK
    note over C,A: 録画開始
    S->>+A: セッションウェブフック<br/>"type": "recording.started"
    A-->>-S: 200 OK
    S->>+A: イベントウェブフック<br/>"type": "archive.started"
    A-->>-S: 200 OK
    A->>+S: HTTP API StopRecording
    S-->>-A: 200 OK
    note over C,A: 録画終了
    S->>+A: イベントウェブフック<br/>"type": "archive.available"
    A-->>-S: 200 OK
    S->>+A: セッションウェブフック<br/>"type": "recording.report"
    A-->>-S: 200 OK
    

セッションウェブフック "recording": true で録画開始

        sequenceDiagram
    autonumber
    participant C as クライアント
    participant S as Sora
    participant A as アプリケーションサーバー
    note over C,A: 認証成功
    S->>+A: セッションウェブフック: "session.created"
    A-->>-S: 200 OK<br>"recording": true
    note over C,A: 録画開始
    S->>+A: セッションウェブフック<br/>"type": "recording.started"
    A-->>-S: 200 OK
    S->>+C: "type": "offer"
    C->>-S: "type": "answer"
    note over C,A: WebRTC 確立
    S->>+A: イベントウェブフック: "connection.created"
    A-->>-S: 200 OK
    S->>+A: イベントウェブフック<br/>"type": "archive.started"
    A-->>-S: 200 OK
    

録画期限切れ

        sequenceDiagram
    autonumber
    participant C as クライアント
    participant S as Sora
    participant A as アプリケーションサーバー
    note over C,A: 認証成功
    S->>+A: セッションウェブフック: "session.created"
    A-->>-S: 200 OK<br>"recording": true,<br>"recoding_expire_time": 3600
    note over C,A: 録画開始
    S->>+A: セッションウェブフック<br/>"type": "recording.started"
    A-->>-S: 200 OK
    S->>+C: "type": "offer"
    C->>-S: "type": "answer"
    note over C,A: WebRTC 確立
    S->>+A: イベントウェブフック: "connection.created"
    A-->>-S: 200 OK
    S->>+A: イベントウェブフック<br/>"type": "archive.started"
    A-->>-S: 200 OK
    note over C,A: 期限切れにより録画終了
    S->>+A: イベントウェブフック<br/>"type": "archive.available"
    A-->>-S: 200 OK
    S->>+A: セッションウェブフック<br/>"type": "recording.report"
    A-->>-S: 200 OK
    

クライアント切断

        sequenceDiagram
    autonumber
    participant C as クライアント
    participant S as Sora
    participant A as アプリケーションサーバー
    note over C,A: 認証成功
    S->>+A: セッションウェブフック: "session.created"
    A-->>-S: 200 OK<br>"recording": true
    note over C,A: 録画開始
    S->>+A: セッションウェブフック<br/>"type": "recording.started"
    A-->>-S: 200 OK
    S->>+C: "type": "offer"
    C->>-S: "type": "answer"
    note over C,A: WebRTC 確立
    S->>+A: イベントウェブフック: "connection.created"
    A-->>-S: 200 OK
    S->>+A: イベントウェブフック<br/>"type": "archive.started"
    A-->>-S: 200 OK
    C->>S: "type": "disconnect"
    S->>+A: イベントウェブフック<br/>"type" :"connection.destroyed"
    A-->-S: 200 OK
    S->>C: WebSocket Close
    note over C,A: クライアント切断に伴いクライアントの録画終了
    S->>+A: イベントウェブフック<br/>"type": "archive.available"
    A-->>-S: 200 OK
    

セッション破棄

        sequenceDiagram
    autonumber
    participant C as クライアント
    participant S as Sora
    participant A as アプリケーションサーバー
    note over C,A: 認証成功
    note over C,A: セッション生成
    S->>+A: セッションウェブフック: "session.created"
    A-->>-S: 200 OK<br>"recording": true
    note over C,A: 録画開始
    S->>+A: セッションウェブフック<br/>"type": "recording.started"
    A-->>-S: 200 OK
    S->>+C: "type": "offer"
    C->>-S: "type": "answer"
    note over C,A: WebRTC 確立
    S->>+A: イベントウェブフック: "connection.created"
    A-->>-S: 200 OK
    S->>+A: イベントウェブフック<br/>"type": "archive.started"
    A-->>-S: 200 OK
    C->>S: "type": "disconnect"
    S->>+A: イベントウェブフック<br/>"type" :"connection.destroyed"
    A-->-S: 200 OK
    S->>C: WebSocket Close
    note over C,A: クライアント切断に伴いクライアントの録画終了
    S->>+A: イベントウェブフック<br/>"type": "archive.available"
    A-->>-S: 200 OK
    note over C,A: セッション破棄
    S->>+A: セッションウェブフック: "session.destroyed"
    A-->>-S: 200 OK
    note over C,A: セッション破棄に伴いセッションの録画終了
    S->>+A: セッションウェブフック: "recording.report"
    A-->>-S: 200 OK
    

レガシー録画機能

注意

レガシー録画機能は 2025 年 12 月リリースの Sora にて廃止します。 今後は 録画機能 (セッション単位) をご利用ください。

注意

レガシー録画機能は MP4 形式でのファイル出力に対応していません。 MP4 形式でのファイル出力を利用する場合は 録画機能 (セッション単位) をご利用ください。

重要

レガシー録画機能と録画機能 (セッション単位) はチャネル単位で異なる仕組みを同時に利用できます。 例えば、channel_id a ではレガシー録画機能、channel_id b では録画機能（セッション単位）のように利用する事ができます。

概要

Sora では、配信している映像や音声を録画、録音して保存できます。 配信されている映像をできるかぎりそのまま保存するため、CPU リソースを最小限に抑えることができます。 出力される録画ファイルは WebM 形式です。映像のみの録画、音声のみの録音にも対応しています。

録画時には一切トランスコードを行っていません。配信された映像や音声をそのままに記録します。

用語

単一録画ファイル

切断または StopRecording API の実行、または録画期限が切れた場合に一つのファイルとして出力される動画ファイル

分割録画ファイル

split_duration で指定した時間ごとに区切られ分割されて出力される動画ファイル

録画ファイルの出力

録画ファイルの出力には 3 パターンあります。

単一録画ファイルのみ出力

• split_duration を指定していない

上記を満たした場合、1 接続で 1 つ録画ファイルが出力されます。

分割録画ファイルのみ出力

• split_duration が指定されている

• expire_time が 0 に指定されている

• split_only が true に指定されている

上記を満たした場合、分割された録画ファイルのみが出力されます。

単一録画ファイルと分割録画ファイルの両方が出力

• sora.conf で recording_dual_output が true に指定されている

• split_duration が指定されている

上記を満たした場合、 1 接続で 1 つの録画ファイルと分割された録画ファイルの両方が出力されます。

イベントウェブフックも単一録画、分割録画、両方のイベントウェブフックリクエストが送信されます。

制限

コーデック

録画 (録音) は、映像コーデックに VP8 と VP9 と H.264 と AV1 、また音声コーデックに Opus を選択した場合のみ利用できます。

警告

• H.265 の録画には非対応です

• B フレームの録画には非対応です

解像度

WebRTC では配信側の CPU リソースが不足した場合や、 回線の品質が悪化した場合に解像度を動的に変更します。 そのため録画したデータの途中で解像度が低くなる可能性があります。

音声や映像のクライアント側でのトラック削除

クライアント側でシグナリング接続時に音声や映像を有効にした状態で、 クライアント側で音声トラック、または映像トラックのどちらかを削除した場合でも録画は行われます。 さらに追加して戻した形であれば録画側も戻ります。

ただし、音声と映像両方のトラックを削除した場合は正常に録画が行われません。

マルチストリーム機能での録画

対応しています。

サイマルキャスト機能での録画

対応しています。

サイマルキャストを利用している際の録画は 一番優先度が低い ストリーム、すなわちデフォルトでは最も高い画質の映像を録画します。

詳細はサイマルキャストの 映像の優先度 をご確認下さい。

スポットライト機能での録画

対応しています。

サイマルキャストを利用している際の録画は 一番優先度が低い ストリーム、すなわちデフォルトでは最も高い画質の映像を録画します。

詳細はサイマルキャストの 映像の優先度 をご確認下さい。

キーフレーム要求間隔

録画機能利用時の Sora からのキーフレーム要求間隔は 20 秒に固定されています。 そのため、分割録画の最小時間は 20 秒 + split_duration に指定した秒数となります。

もし録画時のキーフレーム要求間隔を変更したい場合は、サポートまでご連絡ください。

無変換録画

WebRTC 経由で流れてきている映像や音声を変換せず、 そのまま録画するファイルの形式に組み立て直してファイルを保存します。 そのため、CPU リソースを最小限に抑えられます。 ブラウザでの録画など、通常の録画は変換が入るため CPU に多くの負荷がかかります。

変換を行わないため、録画を終了した数秒後には録画したファイルを取得できます。

解像度は送られてきた映像の最大値を録画ファイルの解像度として使用します。

録画の開始と終了について

Sora の録画機能は 明示的にチャネルの録画を停止するか、 チャネルの録画開始から指定した期限が過ぎるまでは、 そのチャネルでの配信を自動で録画する といった機能になります。

sora.conf の設定による録画指定制限について

録画ファイルが大きくならないように、sora.conf の指定で録画開始時のオプションを制限することができます。

設定の詳細は以下をご確認ください。

• recording_max_expire_time

• recording_max_split_duration

• recording_expire_time_required

• recording_dual_output

録画関連イベントのウェブフックについて

recording.started イベントウェブフック

録画開始 API が実行されたタイミングで recording.started リクエストを送信します。

詳しくは recording.started をご確認ください。

recording.report イベントウェブフック

録画終了 API が実行されたか、 録画の期限が切れたタイミングで recording.report リクエストを送信します。

詳しくは recording.report をご確認ください。

archive.started ウェブフック

録画ファイルを保存しはじめたタイミングで archive.started リクエストを送信します。

詳しくは archive.started をご確認ください。

archive.available イベントウェブフック

単一録画ファイルが出力されたタイミングで archive.available リクエストを送信します。

詳しくは archive.available をご確認ください。

split-archive.available イベントウェブフック

録画ファイル分割出力機能を有効にした場合、 分割された録画ファイルが出力されたタイミングで split-archive.available リクエストを送信します。

詳しくは split-archive.available をご確認ください。

split-archive.end イベントウェブフック

録画ファイル分割出力機能を有効にした場合、 分割された録画が終了したタイミングで split-archive.end リクエストを送信します。

詳しくは split-archive.end をご確認ください。

archive.failed イベントウェブフック

録画ファイルの保存に失敗した場合、 archive.failed リクエストを送信します。

詳しくは archive.failed をご確認ください。

単一録画ファイル出力のみ

単一録画ファイル出力のみの場合は sora.conf の archive_dir に指定したディレクトリに recording_id 名のディレクトリ以下にファイルが出力されます。

recording_id は録画開始 API を実行したときに戻ってくる値で、 Base32 でエンコードされた UUIDv4 となります。

ディレクトリ構造:

├── archive
│   ├── 1CS9QJ0XPN4C76HBGBN6MGMK5M
│   │   ├── archive-A4756MXP914ZB265E92JE3ZMWC.json
│   │   ├── archive-A4756MXP914ZB265E92JE3ZMWC.webm
│   │   ├── archive-H2NDA2YCGH7S1E9CVMFMXMA34R.json
│   │   ├── archive-H2NDA2YCGH7S1E9CVMFMXMA34R.webm
│   │   ├── archive-PBVZQQN3JS3MQF8XHVFXDMCEEC.json
│   │   ├── archive-PBVZQQN3JS3MQF8XHVFXDMCEEC.webm
│   │   └── report-1CS9QJ0XPN4C76HBGBN6MGMK5M.json
│   └── CZZ8A8KZB16A1DF5PKERBHGFNR
│       ├── archive-3B7AFF8ZRX6VNEYV40B35Z9S2C.json
│       ├── archive-3B7AFF8ZRX6VNEYV40B35Z9S2C.webm
│       ├── archive-DGSN3TC0E91RSCZT5KVPRWCDHR.json
│       ├── archive-DGSN3TC0E91RSCZT5KVPRWCDHR.webm
│       └── report-CZZ8A8KZB16A1DF5PKERBHGFNR.json

注意

archive_dir と archive_tmp_dir は違うディレクトリを指定して下さい

archive-<connection_id>

単一録画ファイル

単一録画ファイルは <recording_id>/archvie-<connection_id>.webm に WebM 形式で出力されます。

単一録画メタデータファイル

単一録画メタデータファイルは <recording_id>/archive-<connection_id>.json に JSON 形式で出力されます。

メタデータファイルには WebM ファイルがいつ出力され、どんな形式なのか、開始時刻や終了時刻などの情報が含まれています。

• start_timestamp

  • この録画が開始された時刻を RFC 3339 (UTC) で表しています

• stop_timestamp

  • この録画が終了した時刻を RFC 3339 (UTC) で表しています

• start_time

  • この録画が開始された時刻を UNIX 時間で表しています

• stop_time

  • この録画が終了した時刻を UNIX 時間で表しています

stats は省略しています

{
  "audio": true,
  "audio_codec_type": "OPUS",
  "channel_id": "sora",
  "session_id": "JA8FB89ZJS1H9CV5GN3NCT5RA0",
  "client_id": "GK2R6PSDYX68VDQPRX4FVVFN8W",
  "bundle_id": "GK2R6PSDYX68VDQPRX4FVVFN8W",
  "connection_id": "GK2R6PSDYX68VDQPRX4FVVFN8W",
  "created_at": 1615524156,
  "file_path": "/path/to/sora/archive/WHEJ888HQ55KDCFE3TZ4VPFQHR/archive-GK2R6PSDYX68VDQPRX4FVVFN8W.webm",
  "filename": "WHEJ888HQ55KDCFE3TZ4VPFQHR/archive-GK2R6PSDYX68VDQPRX4FVVFN8W.webm",
  "metadata_file_path": "/path/to/sora/archive/WHEJ888HQ55KDCFE3TZ4VPFQHR/archive-GK2R6PSDYX68VDQPRX4FVVFN8W.json",
  "metadata_filename": "WHEJ888HQ55KDCFE3TZ4VPFQHR/archive-GK2R6PSDYX68VDQPRX4FVVFN8W.json",
  "recording_id": "WHEJ888HQ55KDCFE3TZ4VPFQHR",
  "size": 0,
  "start_time": 1615524137,
  "start_time_offset": 7,
  "start_timestamp": "2021-03-12T04:42:17.455668Z",
  "stats": {},
  "stop_time": 1615524154,
  "stop_time_offset": 24,
  "stop_timestamp": "2021-03-12T04:42:34.094375Z",
  "label": "WebRTC SFU Sora",
  "node_name": "[email protected]",
  "event_metadata": {"spam": "egg"},
  "video": true,
  "video_bit_rate": 1000,
  "video_codec_type": "VP9",
  "video_vp9_params": {
    "profile_id": 0
  },
  "video_height": 480,
  "video_width": 640,
  "format": "mp4"
}

report-<recording_id>

録画終了時に、それまでにそのチャネルで録画したファイル一覧が記載されているレポートファイルが JSON 形式で出力されます。 録画終了は StopRecording API を使用して指定したチャネルに対する録画を停止するか、 録画の期限が切れた場合のふたつのパターンがあります。

このファイルは主にマルチストリームや途中で切れてしまった場合などを考慮しており、 録画ファイルのグルーピングを目的としたファイルです。

ファイルは <recording_id>/report-<recording_id>.json に出力されます。

• トップレベルの start_timestamp

  • StartRecording API を受け付た時刻を RFC 3339 (UTC) で表しています

• トップレベルの stop_timestamp

  • StopRecording API を受け付た時刻か、 StartRecording API で 設定された期限の時刻を RFC 3339 (UTC) で表しています

• archives 内の start_time_offset

  • StartRecording API を叩いてから何秒経過した後にこの録画が開始したかを表しています

• archives 内の stop_time_offset

  • StartRecording API を叩いてから何秒経過した後にこの録画が終了したかを表しています

{
  "archives": [
    {
      "client_id": "GK2R6PSDYX68VDQPRX4FVVFN8W",
      "bundle_id": "GK2R6PSDYX68VDQPRX4FVVFN8W",
      "connection_id": "GK2R6PSDYX68VDQPRX4FVVFN8W",
      "file_path": "/path/to/sora/archive/WHEJ888HQ55KDCFE3TZ4VPFQHR/archive-GK2R6PSDYX68VDQPRX4FVVFN8W.webm",
      "filename": "WHEJ888HQ55KDCFE3TZ4VPFQHR/archive-GK2R6PSDYX68VDQPRX4FVVFN8W.webm",
      "metadata_file_path": "/path/to/sora/archive/WHEJ888HQ55KDCFE3TZ4VPFQHR/archive-GK2R6PSDYX68VDQPRX4FVVFN8W.json",
      "metadata_filename": "WHEJ888HQ55KDCFE3TZ4VPFQHR/archive-GK2R6PSDYX68VDQPRX4FVVFN8W.json",
      "size": 0,
      "start_time_offset": 0,
      "start_timestamp": "2021-03-12T04:42:17.455668Z",
      "stop_time_offset": 17,
      "stop_timestamp": "2021-03-12T04:42:34.094375Z",
      "label": "WebRTC SFU Sora",
      "node_name": "[email protected]"
    }
  ],
  "channel_id": "sora",
  "created_at": 1615524137,
  "expire_time": 3600,
  "expired_at": 1615527737,
  "file_path": "/path/to/sora/archive/WHEJ888HQ55KDCFE3TZ4VPFQHR/report-WHEJ888HQ55KDCFE3TZ4VPFQHR.json",
  "filename": "WHEJ888HQ55KDCFE3TZ4VPFQHR/report-WHEJ888HQ55KDCFE3TZ4VPFQHR.json",
  "metadata": {"spam": "egg"},
  "recording_id": "WHEJ888HQ55KDCFE3TZ4VPFQHR",
  "split_only": false,
  "start_timestamp": "2021-03-12T04:42:17.455668Z",
  "stop_timestamp": "2021-03-12T04:42:34.094375Z"
}

分割録画ファイル出力のみ

Sora では StartRecording API 実行時に split_duration と split_only: true と expire_time: 0 の 3 つを指定することで、 録画ファイルを指定した間隔で出力する機能を提供しています。

重要

分割の最小単位はキーフレームから次のキーフレームまでです。例えば split_duration を 1 秒に設定した場合は、1 秒経過後に次のキーフレームが来たタイミングで分割出力されます。

録画が完了したファイルは sora.conf の archive_dir に指定したディレクトリに recording_id 名のディレクトリ以下にファイルが出力されます。

recording_id は StartRecording API を実行したときに戻ってくる値です。

録画ファイル分割出力のみを行う

録画開始 API 実行時に split_duration と split_only: true と expire_time: 0 の 3 つを指定することで、 録画ファイル分割出力 のみ を行うことが可能になります。

ディレクトリ構造:

├── archive
│   ├── 1CS9QJ0XPN4C76HBGBN6MGMK5M
│   │   ├── split-archive-end-A4756MXP914ZB265E92JE3ZMWC.json
│   │   ├── split-archive-A4756MXP914ZB265E92JE3ZMWC_0001.json
│   │   ├── split-archive-A4756MXP914ZB265E92JE3ZMWC_0001.webm
│   │   ├── split-archive-A4756MXP914ZB265E92JE3ZMWC_0002.json
│   │   ├── split-archive-A4756MXP914ZB265E92JE3ZMWC_0002.webm
│   │   ├── split-archive-A4756MXP914ZB265E92JE3ZMWC_0003.json
│   │   ├── split-archive-A4756MXP914ZB265E92JE3ZMWC_0003.webm
│   │   ├── split-archive-A4756MXP914ZB265E92JE3ZMWC_0003.json
│   │   ├── split-archive-A4756MXP914ZB265E92JE3ZMWC_0003.webm
│   │   └── report-1CS9QJ0XPN4C76HBGBN6MGMK5M.json
│   └── CZZ8A8KZB16A1DF5PKERBHGFNR
│       ├── split-archive-end-3B7AFF8ZRX6VNEYV40B35Z9S2C.json
│       ├── split-archive-end-DGSN3TC0E91RSCZT5KVPRWCDHR.json
│       ├── split-archive-3B7AFF8ZRX6VNEYV40B35Z9S2C_0001.json
│       ├── split-archive-3B7AFF8ZRX6VNEYV40B35Z9S2C_0001.webm
│       ├── split-archive-DGSN3TC0E91RSCZT5KVPRWCDHR_0001.json
│       ├── split-archive-DGSN3TC0E91RSCZT5KVPRWCDHR_0001.webm
│       ├── split-archive-DGSN3TC0E91RSCZT5KVPRWCDHR_0002.json
│       ├── split-archive-DGSN3TC0E91RSCZT5KVPRWCDHR_0002.webm
│       └── report-CZZ8A8KZB16A1DF5PKERBHGFNR.json

split-archive-<connection_id>_<split_index>

分割録画ファイル

分割録画ファイルは <recording_id>/split-archvie-<connection_id>_<split_index>.webm に WebM 形式で出力されます。

分割録画メタデータファイル

分割録画メタデータファイルは <recording_id>/split-archive-<connection_id>_<split_index>.json に JSON 形式で出力されます。

• split_index

  • ファイル名につくインデックスです

  • 0001 から始まり 9999 の後は 10000 となります

stats は省略しています

{
  "audio": true,
  "audio_codec_type": "OPUS",
  "recording_id": "CZZ8A8KZB16A1DF5PKERBHGFNR",
  "file_path": "/path/to/sora/archive/CZZ8A8KZB16A1DF5PKERBHGFNR/split-archive-3B7AFF8ZRX6VNEYV40B35Z9S2C_001.webm",
  "filename": "CZZ8A8KZB16A1DF5PKERBHGFNR/split-archive-3B7AFF8ZRX6VNEYV40B35Z9S2C_001.webm",
  "metadata_file_path": "/path/to/sora/split-archive/CZZ8A8KZB16A1DF5PKERBHGFNR/archive-3B7AFF8ZRX6VNEYV40B35Z9S2C_001.json",
  "metadata_filename": "CZZ8A8KZB16A1DF5PKERBHGFNR/split-archive-3B7AFF8ZRX6VNEYV40B35Z9S2C_001.json",
  "channel_id": "sora",
  "session_id": "JA8FB89ZJS1H9CV5GN3NCT5RA0",
  "client_id": "3B7AFF8ZRX6VNEYV40B35Z9S2C",
  "bundle_id": "3B7AFF8ZRX6VNEYV40B35Z9S2C",
  "connection_id": "3B7AFF8ZRX6VNEYV40B35Z9S2C",
  "split_index": "0001",
  "created_at": 1604656364,
  "size": 823263,
  "start_time": 1604656354,
  "start_time_offset": 4,
  "start_timestamp": "2020-11-06T09:52:34.696758Z",
  "stats": {},
  "stop_time": 1604656364,
  "stop_time_offset": 14,
  "stop_timestamp": "2020-11-06T09:52:44.493179Z",
  "label": "WebRTC SFU Sora",
  "node_name": "[email protected]",
  "event_metadata": {"spam": "egg"},
  "video": true,
  "video_bit_rate": 1000,
  "video_codec_type": "VP9",
  "video_vp9_params": {
    "profile_id": 0
  },
  "video_height": 480,
  "video_width": 640,
  "format": "mp4"
}

split-archive-end-<connection_id>

分割録画終了メタデータファイル

分割録画終了メタデータファイルは <recording_id>/split-archive-end-<connection_id>.json に JSON 形式で出力されます。

stats は省略しています

{
  "audio": true,
  "audio_codec_type": "OPUS",
  "split_last_index": "0042",
  "recording_id": "CZZ8A8KZB16A1DF5PKERBHGFNR",
  "file_path": "/path/to/sora/archive/CZZ8A8KZB16A1DF5PKERBHGFNR/split-archive-end-3B7AFF8ZRX6VNEYV40B35Z9S2C.json",
  "filename": "CZZ8A8KZB16A1DF5PKERBHGFNR/split-archive-end-3B7AFF8ZRX6VNEYV40B35Z9S2C.json",
  "channel_id": "sora",
  "session_id": "JA8FB89ZJS1H9CV5GN3NCT5RA0",
  "client_id": "3B7AFF8ZRX6VNEYV40B35Z9S2C",
  "bundle_id": "3B7AFF8ZRX6VNEYV40B35Z9S2C",
  "connection_id": "3B7AFF8ZRX6VNEYV40B35Z9S2C",
  "start_time": 1604656354,
  "start_time_offset": 4,
  "start_timestamp": "2020-11-06T09:52:34.696758Z",
  "stats": {},
  "stop_time": 1604656364,
  "stop_time_offset": 14,
  "stop_timestamp": "2020-11-06T09:52:44.493179Z",
  "label": "WebRTC SFU Sora",
  "node_name": "[email protected]",
  "event_metadata": {"spam": "egg"},
  "video": true,
  "video_bit_rate": 1000,
  "video_codec_type": "VP9",
  "video_vp9_params": {
    "profile_id": 0
  },
  "video_height": 480,
  "video_width": 640,
  "format": "mp4"
}

録画ファイル分割出力終了時

接続単位での録画が終了したタイミングでイベントウェブフックリクエスト split-archive.end がリクエスト送信されます。

詳細は split-archive.end をご確認ください。

report-<recording_id>

録画終了時に、それまでにそのチャネルで録画したファイル一覧が記載されているレポートファイルが JSON 形式で出力されます。 録画終了は StopRecording API を使用して指定したチャネルに対する録画を停止するか、 録画の期限が切れた場合のふたつのパターンがあります。

このファイルは主にマルチストリームや途中で切れてしまった場合などを考慮しており、 録画ファイルのグルーピングを目的としたファイルです。

ファイルは <recording_id>/report-<recording_id>.json に出力されます。

分割録画ファイル出力のみの場合は archives には connection_id や client_id といった接続情報と、 分割録画ファイルの最後のインデックス番号のみが含まれます。

• トップレベルの start_timestamp

  • StartRecording API を受け付た時刻を RFC 3339 (UTC) で表しています

• トップレベルの stop_timestamp

  • StopRecording API を受け付た時刻か、 StartRecording API で 設定された期限の時刻を RFC 3339 (UTC) で表しています

• archives 内の start_time_offset

  • StartRecording API を叩いてから何秒経過した後にこの録画が開始したかを表しています

• archives 内の stop_time_offset

  • StartRecording API を叩いてから何秒経過した後にこの録画が終了したかを表しています

{
  "archives": [
    {
      "client_id": "GK2R6PSDYX68VDQPRX4FVVFN8W",
      "bundle_id": "GK2R6PSDYX68VDQPRX4FVVFN8W",
      "connection_id": "GK2R6PSDYX68VDQPRX4FVVFN8W",
      "split_last_index": "0042"
      "start_time_offset": 4,
      "start_timestamp": "2020-11-06T09:52:34.696758Z",
      "stop_time_offset": 14,
      "stop_timestamp": "2020-11-06T09:52:44.493179Z",
      "label": "WebRTC SFU Sora",
      "node_name": "[email protected]"
    }
  ],
  "channel_id": "sora",
  "created_at": 1615524137,
  "expire_time": 3600,
  "expired_at": 1615527737,
  "file_path": "/path/to/sora/archive/WHEJ888HQ55KDCFE3TZ4VPFQHR/report-GK2R6PSDYX68VDQPRX4FVVFN8W.json",
  "filename": "WHEJ888HQ55KDCFE3TZ4VPFQHR/report-GK2R6PSDYX68VDQPRX4FVVFN8W.json",
  "recording_id": "WHEJ888HQ55KDCFE3TZ4VPFQHR",
  "split_duration": 3600,
  "split_only": false,
  "metadata": {"spam": "egg"},
  "start_timestamp": "2020-11-06T09:52:34.696758Z",
  "stop_timestamp": "2020-11-06T09:52:44.493179Z"
}

単一録画ファイルと分割録画ファイル

StartRecording API 実行時に split_only を有効にしない限り、 単一ファイルと分割ファイルの二つが出力されます。 単一録画ファイルと分割録画ファイルのいいところ取りですが、その分ストレージの容量も 2 倍消費します。

出力されるファイルは単一と分割のファイルが混ざった形式になります。

ディレクトリ構造:

├── archive
│   ├── 1CS9QJ0XPN4C76HBGBN6MGMK5M
│   │   ├── split-archive-end-A4756MXP914ZB265E92JE3ZMWC.json
│   │   ├── split-archive-A4756MXP914ZB265E92JE3ZMWC_0001.json
│   │   ├── split-archive-A4756MXP914ZB265E92JE3ZMWC_0001.webm
│   │   ├── split-archive-A4756MXP914ZB265E92JE3ZMWC_0002.json
│   │   ├── split-archive-A4756MXP914ZB265E92JE3ZMWC_0002.webm
│   │   ├── split-archive-A4756MXP914ZB265E92JE3ZMWC_0003.json
│   │   ├── split-archive-A4756MXP914ZB265E92JE3ZMWC_0003.webm
│   │   ├── split-archive-A4756MXP914ZB265E92JE3ZMWC_0003.json
│   │   ├── split-archive-A4756MXP914ZB265E92JE3ZMWC_0003.webm
│   │   ├── archive-A4756MXP914ZB265E92JE3ZMWC.json
│   │   ├── archive-A4756MXP914ZB265E92JE3ZMWC.webm
│   │   └── report-1CS9QJ0XPN4C76HBGBN6MGMK5M.json
│   └── CZZ8A8KZB16A1DF5PKERBHGFNR
│       ├── split-archive-end-3B7AFF8ZRX6VNEYV40B35Z9S2C.json
│       ├── split-archive-3B7AFF8ZRX6VNEYV40B35Z9S2C_0001.json
│       ├── split-archive-3B7AFF8ZRX6VNEYV40B35Z9S2C_0001.webm
│       ├── split-archive-end-DGSN3TC0E91RSCZT5KVPRWCDHR.json
│       ├── split-archive-DGSN3TC0E91RSCZT5KVPRWCDHR_0001.json
│       ├── split-archive-DGSN3TC0E91RSCZT5KVPRWCDHR_0001.webm
│       ├── split-archive-DGSN3TC0E91RSCZT5KVPRWCDHR_0002.json
│       ├── split-archive-DGSN3TC0E91RSCZT5KVPRWCDHR_0002.webm
│       ├── archive-3B7AFF8ZRX6VNEYV40B35Z9S2C.json
│       ├── archive-3B7AFF8ZRX6VNEYV40B35Z9S2C.webm
│       ├── archive-DGSN3TC0E91RSCZT5KVPRWCDHR.json
│       ├── archive-DGSN3TC0E91RSCZT5KVPRWCDHR.webm
│       └── report-CZZ8A8KZB16A1DF5PKERBHGFNR.json

report-<recording_id>

出力される report ファイルは単一と分割が混ざった形式になります。

• トップレベルの start_timestamp

  • StartRecording API を受け付た時刻を RFC 3339 (UTC) で表しています

• トップレベルの stop_timestamp

  • StopRecording API を受け付た時刻か、 StartRecording API で 設定された期限の時刻を RFC 3339 (UTC) で表しています

• archives 内の start_time_offset

  • StartRecording API を叩いてから何秒経過した後にこの録画が開始したかを表しています

• archives 内の stop_time_offset

  • StartRecording API を叩いてから何秒経過した後にこの録画が終了したかを表しています

{
  "archives": [
    {
      "client_id": "GK2R6PSDYX68VDQPRX4FVVFN8W",
      "bundle_id": "GK2R6PSDYX68VDQPRX4FVVFN8W",
      "connection_id": "GK2R6PSDYX68VDQPRX4FVVFN8W",

      "file_path": "/path/to/sora/archive/WHEJ888HQ55KDCFE3TZ4VPFQHR/archive-GK2R6PSDYX68VDQPRX4FVVFN8W.webm",
      "filename": "WHEJ888HQ55KDCFE3TZ4VPFQHR/archive-GK2R6PSDYX68VDQPRX4FVVFN8W.webm",
      "metadata_file_path": "/path/to/sora/archive/WHEJ888HQ55KDCFE3TZ4VPFQHR/archive-GK2R6PSDYX68VDQPRX4FVVFN8W.json",
      "metadata_filename": "WHEJ888HQ55KDCFE3TZ4VPFQHR/archive-GK2R6PSDYX68VDQPRX4FVVFN8W.json",
      "size": 0,
      "start_time_offset": 0,
      "start_timestamp": "2021-03-12T04:42:17.455668Z",
      "stop_time_offset": 17,
      "stop_timestamp": "2021-03-12T04:42:34.094375Z",

      "split_last_index": "0042",
      "label": "WebRTC SFU Sora",
      "node_name": "[email protected]"
    }
  ],
  "channel_id": "sora",
  "created_at": 1615524137,
  "expire_time": 3600,
  "expired_at": 1615527737,
  "file_path": "/path/to/sora/archive/WHEJ888HQ55KDCFE3TZ4VPFQHR/report-WHEJ888HQ55KDCFE3TZ4VPFQHR.json",
  "filename": "WHEJ888HQ55KDCFE3TZ4VPFQHR/report-WHEJ888HQ55KDCFE3TZ4VPFQHR.json",
  "recording_id": "WHEJ888HQ55KDCFE3TZ4VPFQHR",
  "label": "WebRTC SFU Sora",
  "node_name": "[email protected]",
  "split_duration": 3600,
  "split_only": false,
  "metadata": {"spam": "egg"},
  "start_timestamp": "2021-03-12T04:42:17.455668Z",
  "stop_timestamp": "2021-03-12T04:42:34.094375Z"
}

録画ファイル出力失敗時の録画一時ファイル

何らかの理由で録画ファイル出力が失敗した場合、 archive_tmp_dir で指定したディレクトリに録画一時ファイルが削除されずに残ります。そのため、定期的な削除が必要です。

この録画一時ファイルは WebM 形式のためそのまま再生できます。

シグナリング通知

シグナリング通知で録画開始と終了を通知できます。

詳細は 録画のシグナリング通知 をご確認ください。

録画ファイル合成ツール

マルチストリームを録画した場合はそれぞれの接続に対して録画ファイルが出力されます。このそれぞれ分かれた録画ファイルを合成して一つにするツールをオープンソースとして公開しています。

詳細は WebRTC 録画合成ツール Hisui をご確認ください。

試してみる

Sora では録画機能を試すための開発ツールを提供しています。 開発ツール を参照の上、開発ツールを有効にしてください。

ここでは Sora が立っているサーバーは example.com としています。

チャネルの録画開始

API を叩いて録画を開始してください。

httpie:

$ http POST example.com:3000/ \
    x-sora-target:Sora_20161101.StartRecording \
    channel_id=sora \
    expire_time:=3600 -vvv

その後 https://example.com/sendonly.html を開き、 connect ボタンを押して配信を開始します。

切断またはチャネルの録画終了、もしくはチャネルの録画期限が来たタイミングでクライアントの録画は終了します。

チャネルの録画終了

チャネルの録画を終了するには API を叩く必要があります。

httpie:

$ http POST example.com:3000/ \
    x-sora-target:Sora_20161101.StopRecording \
    channel_id=sora -vvv

その後 archive/ ディレクトリに webm 形式のファイルが出力されます。 Chrome または Firefox にドラッグアンドドロップして、動作を確認してください。

録画関連ファイルアップローダー

重要

このツールはサポート対象外です

時雨堂では、録画関連ファイルを Amazon S3 、または S3 互換オブジェクトストレージにアップロードするツールを OSS として Apache License 2.0 で公開しています。

これは、Sora のクラウド版である Sora Cloud で利用している仕組みを 切り出したものです。

shiguredo/sora-archive-uploader: Sora Archive Uploader

シーケンス図

StopRecording API

        sequenceDiagram
    autonumber
    participant C as クライアント
    participant S as Sora
    participant A as アプリケーションサーバー
    note over C,A: 認証成功
    S->>+C: "type": "offer"
    C->>-S: "type": "answer"
    note over C,A: WebRTC 確立
    A->>+S: HTTP API StartRecording
    S-->>-A: 200 OK
    S->>+A: イベントウェブフック<br/>"type": "recording.started"
    A-->>-S: 200 OK
    note over C,A: 録画中
    S->>+A: イベントウェブフック<br/>"type": "archive.started"
    A-->>-S: 200 OK
    A->>+S: HTTP API StopRecording
    S-->>-A: 200 OK
    note over C,A: 録画終了
    S->>+A: イベントウェブフック<br/>"type": "archive.available"
    A-->>-S: 200 OK
    S->>+A: イベントウェブフック<br/>"type": "recording.report"
    A-->>-S: 200 OK
    

録画期限切れ

        sequenceDiagram
    autonumber
    participant C as クライアント
    participant S as Sora
    participant A as アプリケーションサーバー
    note over C,A: 認証成功
    S->>+C: "type": "offer"
    C->>-S: "type": "answer"
    note over C,A: WebRTC 確立
    A->>+S: HTTP API StartRecording
    S-->>-A: 200 OK
    S->>+A: イベントウェブフック<br/>"type": "recording.started"
    A-->>-S: 200 OK
    note over C,A: 録画中
    S->>+A: イベントウェブフック<br/>"type": "archive.started"
    A-->>-S: 200 OK
    note over C,A: 期限切れにより録画終了
    S->>+A: イベントウェブフック<br/>"type": "archive.available"
    A-->>-S: 200 OK
    S->>+A: イベントウェブフック<br/>"type": "recording.report"
    A-->>-S: 200 OK
    

クライアント切断

        sequenceDiagram
    autonumber
    participant C as クライアント
    participant S as Sora
    participant A as アプリケーションサーバー
    note over C,A: 認証成功
    S->>+C: "type": "offer"
    C->>-S: "type": "answer"
    note over C,A: WebRTC 確立
    A->>+S: HTTP API StartRecording
    S-->>-A: 200 OK
    S->>+A: イベントウェブフック<br/>"type": "recording.started"
    A-->>-S: 200 OK
    note over C,A: 録画中
    S->>+A: イベントウェブフック<br/>"type": "archive.started"
    A-->>-S: 200 OK
    C->>S: "type": "disconnect"
    S->>+A: イベントウェブフック<br/>"type" :"connection.destroyed"
    A-->-S: 200 OK
    S->>C: WebSocket Close
    note over C,A: クライアント切断により録画終了
    S->>+A: イベントウェブフック<br/>"type": "archive.available"
    A-->>-S: 200 OK
    S->>+A: イベントウェブフック<br/>"type": "recording.report"
    A-->>-S: 200 OK
    

リアルタイムメッセージング機能

概要

リアルタイムメッセージング機能は DataChannel の互換性を維持しつつ、 超低遅延で同じチャネル参加者へメッセージを送る仕組みです。

注意

• リアルタイムメッセージング機能を利用するためには、 data_channel_signaling が有効になっている必要があります

• リアルタイムメッセージング機能は DataChannel プロトコル互換性を維持しつつ Sora 独自の仕組みを追加しています

制限

メッセージサイズ制限

注意

1 回のメッセージで送れる値には制限がありますのでご注意ください。

詳しくは DataChannel シグナリングの 推奨メッセージサイズ をご確認ください

SDK 対応状況

• 最新版の JavaScript SDK

  • 対応済みです

• 最新版の iOS SDK

  • 対応済みです

• 最新版の Android SDK

  • 対応済みです

• 最新版の Unity SDK

  • 対応済みです

• 最新版の C++ SDK

  • 対応済みです

• 最新版の Python SDK

  • 対応済みです

• 最新版の C SDK

  • 対応済みです

DataChannel を利用したリアルタイムメッセージング機能を有効にする

DataChannel を利用したリアルタイムメッセージングを利用する場合、 DataChannel シグナリングが有効になっている必要があります。

その上で sora.conf にて data_channel_messaging を true に指定してください。

利用する場合は "type": "connect" 時に data_channels を指定してください。

リアルタイムメッセージング用 DataChannel の作成

重要

DataChannel を利用したリアルタイムメッセージングを利用する場合は、DataChannel シグナリングが有効になっている必要があります

Sora では、Sora がシグナリングで使用する DataChannel 以外にも、リアルタイムメッセージング用の DataChannel を作成できます。

利用する場合は "type": "connect" 時に定義するか、認証成功時の払い出しで定義する必要があります。

Sora のリアルタイムメッセージング用 DataChannel は、DataChannel の属性である label を定義する際に # から始める必要があります。

data_channels 仕様

重要

メッセージは 送信者以外 の同一 label 、かつ、 direction が sendrecv または recvonly のクライアントに送信されます。

label

メッセージのラベルを指定します。先頭に # が付いている必要があります。

• label は # を含めて 32 文字まで指定できます

• label には小文字大文字のアルファベットと - (ハイフン) しか利用できません

  • # の次の文字に - は指定できません

  • ^#[a-zA-Z0-9][a-zA-Z0-9-]{1,30}$

• 1 接続においてラベルは最大で 1024 まで指定できます

compress

メッセージを zlib にて圧縮するかどうかを指定します。

• compress が true の場合、圧縮/展開に zlib.deflate を利用します

  • 圧縮方式を変更することはできません

direction

メッセージの方向を指定します。

• direction には sendrecv / sendonly / recvonly が設定できます

  • sendrecv 時に 自分が送ったメッセージ は自分には送られてきません

クライアントからみた方向になります。

• sendrecv が設定されたラベルは送受信で利用できます

• sendonly が設定されたラベルは送信のみが利用できます

• recvonly が設定されたラベルは受信のみが利用できます

ordered

順序保証を行うかどうか指定します。デフォルトでは true に設定され、順序保証を行います。

max_retransmits

注意

max_retransmits と max_packet_life_time はどちらかしか指定できません。

最大再送回数を指定します。デフォルトでは未指定で、無制限に再送します。

max_packet_life_time

注意

max_retransmits と max_packet_life_time はどちらかしか指定できません。

最大再送時間をミリ秒で指定します。デフォルトでは未指定で、無制限に再送します。

header

メッセージングにヘッダーを追加します。ヘッダーは Sora 側で付与します。

• header は direction が sendrecv または recvonly の場合に指定できます

• header を指定したメッセージの受信者にヘッダーが付与されるようになります

• header はオプションです

• header のデフォルトは [] です

• header には {"type": "sender_connection_id"} を指定できます

  • sender_connection_id はメッセージングの送信元の connection_id です

  • 先頭 26 バイトが sender_connection_id になります

• クライアントから Sora が受信するメッセージ

  • [message (variable length)]

• Sora から header を指定したクライアントへ送信するメッセージ

  • [sender_connection_id (26 bytes)][message (variable length)]

"data_channels": [
  {
    "label": "#spam",
    "max_packet_life_time": 5000,
    "ordered": true,
    "protocol": "efg",
    "compress": false,
    "direction": "recvonly",
    "header": [{"type": "sender_connection_id"}]
  },
  {
    "label": "#egg",
    "max_retransmits": 0,
    "ordered": false,
    "protocol": "abc",
    "compress": false,
    "direction": "recvonly"
  }
]

JavaScript SDK 利用時の注意

• max_retransmits は maxRetransmits に変更してください

• max_packet_life_time は maxPacketLifeTime に変更してください

"type": "connect" 時の "data_channels"

注釈

protocol は特に指定する必要はありません。

項目名	型	必須 / オプション	デフォルト	備考
label	string	必須		^#[a-zA-Z0-9][a-zA-Z0-9-]{1,30}$
direction	string	必須		"sendrecv" / "sendonly" / "recvonly"
ordered	boolean	オプション	true
max_packet_life_time	integer	オプション	未指定
max_retransmits	integer	オプション	未指定
protocol	string	オプション	""
compress	boolean	オプション	false
header	array[object]	オプション	[]	"sender_connection_id"

注意

Sora JS SDK や Sora DevTools で max_packet_life_time と max_retransmits を指定する場合は maxPacketLifeTime と maxRetransmits となります。

{
  "type": "connect",
  "data_channels": [
    {
      "label": "#spam",
      "max_packet_life_time": 5000,
      "ordered": true,
      "protocol": "efg",
      "compress": false,
      "direction": "recvonly",
      "header": [{"type": "sender_connection_id"}]
    },
    {
      "label": "#egg",
      "max_retransmits": 0,
      "ordered": false,
      "protocol": "abc",
      "compress": false,
      "direction": "recvonly"
    }
  ]
}

認証成功時の戻り値

認証ウェブフックの認証成功時に data_channels を指定できます。

{
  "allowed": true,
  "data_channels": [
    {
      "label": "#spam",
      "max_packet_life_time": 5000,
      "ordered": true,
      "protocol": "efg",
      "compress": false,
      "direction": "recvonly",
      "header": [{"type": "sender_connection_id"}]
    },
    {
      "label": "#egg",
      "max_retransmits": 0,
      "ordered": false,
      "protocol": "abc",
      "compress": false,
      "direction": "recvonly"
    }
  ]
}

"type": "offer" 時の "data_channels"

注釈

Sora SDK を利用する場合はこれを意識する必要はありません。

接続時か認証成功時に指定された data_channels は {"type": "offer"} に含まれます。

{
  "type": "offer",
  "data_channels": [
    {
      "label": "signaling",
      "ordered": true,
      "protocol": "signaling",
      "compress": true,
      "direction": "sendrecv"
    },
    {
      "label": "notify",
      "ordered": true,
      "protocol": "notify",
      "compress": true,
      "direction": "recvonly"
    },
    {
      "label": "push",
      "ordered": true,
      "protocol": "push",
      "compress": true,
      "direction": "recvonly"
    },
    {
      "label": "stats",
      "ordered": true,
      "max_retransmits": 1,
      "protocol": "stats",
      "compress": true,
      "direction": "sendrecv"
    },
    {
      "label": "#spam",
      "max_packet_life_time": 5000,
      "ordered": true,
      "protocol": "efg",
      "compress": false,
      "direction": "recvonly",
      // header の長さが type: offer 時の data_channels には含まれるようになります
      "header": [{"type": "sender_connection_id", "length": 26}]
    },
    {
      "label": "#egg",
      "max_retransmits": 0,
      "ordered": false,
      "protocol": "abc",
      "compress": false,
      "direction": "recvonly"
    }
  ]
}

DataChannel を利用したメッセージングのみで接続する

DataChannel を利用したメッセージングのみを有効にするには以下を満たす必要があります。

注釈

role は sendrecv / sendonly / recvonly のどれでも問題ありませんが、 sendrecv / recvonly の場合、相手から送られてきた音声や映像を受信しますので、sendonly で接続することをお勧めします。

• sora.conf の default_data_channel_signaling を true にする

• sora.conf の data_channel_messaging_only を true にする

• sora.conf の data_channel_messaging を true にする

• "type": "connect" 時に audio を false にする

  • 認証成功時の払い出しでも可

• "type": "connect" 時に video を false にする

  • 認証成功時の払い出しでも可

• "type": "connect" 時に data_channels を指定する

  • 認証成功時の払い出しでも可

• "type": "connect" 時に data_channel_signaling を true にする

  • 認証成功時の払い出しでも可

これで 音声や映像を送らず DataChannel を利用したメッセージングのみを利用できるようになります。

シーケンス図

シンプル

1. クライアント 1 が label: spam, direction: sendrecv と、 label: #egg, direction: sendonly でメッセージング利用開始

   {
     "type": "connect",
     "data_channels": [
       {"label": "#spam", "direction": "sendrecv"},
       {"label": "#egg": "direction": "sendonly"}
     ]
   }
   

2. クライアント 2 が label: #spam, direction: recvonly でメッセージング利用開始

   {
     "type": "connect",
     "data_channels": [
       {"label": "#spam", "direction": "recvonly"}
     ]
   }
   

3. クライアント 1 が label: #spam へメッセージ "abc" を送信

4. クライアント 2 が Sora から label: #spam へのメッセージ "abc" を受信

5. クライアント 1 が label: #egg へメッセージ "xyz" を送信

   • 誰も受け取る人がいない

6. クライアント 3 が label: #spam, direction: sendrecv でメッセージング利用開始

   {
     "type": "connect",
     "data_channels": [
       {"label": "#spam", "direction": "sendrecv"}
     ]
   }
   

7. クライアント 1 が Sora へ label: #spam のメッセージ "123" を送信

8. クライアント 2 が Sora から label: #spam のメッセージ "123" を受信

9. クライアント 3 が Sora から label: #spam のメッセージ "123" を受信

        sequenceDiagram
    autonumber

    participant C1 as クライアント1
    participant C2 as クライアント2
    participant C3 as クライアント3
    participant S as Sora

    C1->>S: "type": "connect"
    note over C1,S: クライアント1 WebRTC 確立
    C2->>S: "type": "connect"
    note over C2,S: クライアント2 WebRTC 確立
    C1-)S: label: #35;spam "abc" send
    S-)C2: label: #35;spam "abc" send
    C3->>S: "type": "connect"
    note over C3,S: クライアント3 WebRTC 確立
    C1-)S: label: #35;spam "xyz" send
    S-)C2: label: #35;spam "xyz" send
    S-)C3: label: #35;spam "xyz" send
    

ICE コネクションステート機能

概要

ICE コネクションステート機能は Sora に ICE コネクションによる状態管理を持たせた機能です。

前提

この機能はクライアント側が意識する必要はありません。

挙動

Sora は WebRTC が確立した後に TURN 上で ICE コネクションステートを更新し続けます。 ステートの更新には STUN Binding-Request と STUN Binding-Success を利用します。

• Sora は 2.5 秒間隔で STUN Binding-Request をクライアントへ送ります

  • STUN Binding-Success が 2.5 秒以内に一度も返ってこない場合、状態を connected から checking へ遷移します

• 状態が checking へ遷移した場合、 Sora は 1 秒間隔で STUN Binding-Request をクライアントへ送ります

  • STUN Binding-Success が 5 秒以内に一度も返ってこない場合、状態を checking から disconnected へ遷移します

  • この 5 秒は sora.conf にて ice_connection_state_disconnected_timeout で変更できます

• 状態が disconnected に遷移した場合、 Sora は 50 ミリ秒間隔で STUN Binding-Request をクライアントへ送ります

  • STUN Binding-Success が 10 秒以内に一度も返ってこない場合、状態を disconnected から failed へ遷移します

  • この 10 秒は sora.conf にて ice_connection_state_failed_timeout で変更できます

  • このタイミングで sora.jsonl に warning として ICE-CONNECTION-STATE-DISCONNECTED が出力されます

• 状態が failed に遷移した場合、Sora はクライアントの接続を切断します

  • このタイミングで sora.jsonl に error として ICE-CONNECTION-STATE-FAILED が出力されます

設定

ICE コネクションステート機能は無効にすることはできません。

ただし、切断や失敗までの判定時間を sora.conf にてデフォルト値から変更できます。

ice_connection_state_disconnected_timeout

この値は Sora が ICE コネクションステートを disconnected へと遷移する際にクライアントからの応答を待つ時間です。

デフォルトでは 5 s が設定されています。

詳細は ice_connection_state_disconnected_timeout をご確認ください。

ice_connection_state_failed_timeout

この値は Sora が ICE コネクションステートを failed へと遷移する際にクライアントからの応答を待つ時間です。

デフォルトでは 10 s が設定されています。

詳細は ice_connection_state_failed_timeout をご確認ください。

シグナリング通知

警告

この機能は実験的機能です。

シグナリング通知経由で、それぞれのクライアントの ICE コネクションステートの変更を送信する機能です。

この機能を有効にするには sora.conf の signaling_notify_ice_connection_state を true に設定してください。

機能を有効にした場合、ICE コネクションの状態変更時に、自分を含むチャネル参加者全員に対して、 シグナリング通知 ice-connection-state.changed が送信されるようになります。

さらに connection.created の data に ice_connection_state が含まれるようになり、 既にチャネルに参加しているクライアントの ice_connection_state を取得できるようになります。

認証成功時の signaling_notify_ice_connection_state の払い出し

シグナリング通知 ice-connection-state.changed を送信するかどうかは、 signaling_notify_ice_connection_state の値が採用されますが、 認証成功時の払い出しに signaling_notify_ice_connection_state を指定することで変更する事ができます。

注釈

signaling_notify_ice_connection_state を false に設定したとしても、 認証成功時の払い出しに signaling_notify_ice_connection_state を true で指定した場合は、 シグナリング通知 ice-connection-state.changed が送信されます。

シグナリング通知 ice-connection-state.changed

自分が接続した時は connection.created のシグナリング通知の後に、 シグナリング通知 ice-connection-state.changed が送信されます。

以下の 4 つのタイミングで通知がチャネルに参加している他のコネクションへ送信されます。

1. connected から checking になった時

   • ice-connection-state.changed で current_state に checking 、 previous_state に connected が入ります

2. checking から connected になった時

   • ice-connection-state.changed で current_state に connected 、 previous_state に checking が入ります

3. checking から disconnected になった時

   • ice-connection-state.changed で current_state に disconnected 、 previous_state に checking が入ります

4. disconnected から checking になった時

   • ice-connection-state.changed で current_state に checking 、 previous_state に disconnected が入ります

{
  "connection_id": "JA0H99CB490C9EEV8AAVBNSBWG",
  "timestamp": "2024-10-15T01:04:50.039752Z",
  "type": "notify",
  "event_type": "ice-connection-state.changed",
  "current_state": "connected",
  "previous_state": "checking"
}

connection.created の data の ice_connection_state

シグナリング通知 connection.created の data に ice_connection_state が含まれるようにするには、 sora.conf の signaling_notify_ice_connection_state を true に設定する必要があります。

{
  // 色々省略
  "connection_id": "ZE6QPYMF1N4473AN1AH5KY6T3C",
  "data": [
    {
      "connection_id": "JA0H99CB490C9EEV8AAVBNSBWG",
      "timestamp": "2024-10-15T01:04:50.036927Z",
      "bundle_id": "JA0H99CB490C9EEV8AAVBNSBWG",
      "client_id": "JA0H99CB490C9EEV8AAVBNSBWG",
      // 既存参加者の ice_connection_state が含まれる
      "ice_connection_state": "connected"
    }
  ],
  "timestamp": "2024-10-15T01:05:17.317571Z",
  "type": "notify",
  "session_id": "HC3DTTQH1946DC9HYKAE2AAHS8",
  "role": "sendrecv",
  "event_type": "connection.created",
}

ウェブフック

コネクションの状態が checking と disconnected だった合計時間をイベントウェブフックで取得できます。

• 取得可能なイベントウェブフック

  • connection.created

  • connection.updated

  • connection.destroyed

• data.ice_connection_state.total_checking_duration_ms に checking だった合計時間(ミリ秒)の合計が入ります

• data.ice_connection_state.total_disconnected_duration_ms に disconnected だった合計時間(ミリ秒)の合計が入ります

{
  // 色々省略してます
  "type": "connection.destroyed",
  "channel_id": "sora",
  "connection_id": "GS4Q8PQ5PS3EXC30T6PM2R7Y20",
  "timestamp": "2023-08-16T05:42:13.970729Z",
  "bundle_id": "GS4Q8PQ5PS3EXC30T6PM2R7Y20",
  "client_id": "GS4Q8PQ5PS3EXC30T6PM2R7Y20",
  "data": {
    "ice_connection_state": {
      "total_checking_duration_ms": 5002,
      "total_disconnected_duration_ms": 10002
    }
  }
}

テスト

ICE コネクションステートのテストをしたい場合は LockIceConnectionState API を利用してください。

ステート図

重要

図のタイムアウト値はデフォルト値を採用しています。

        stateDiagram
    New --> Checking
    Checking --> Connected: 応答あり
    Checking --> Disconnected: 5 秒間応答なし
    Disconnected --> Failed: 10 秒間応答なし
    Connected --> Checking: 2.5 秒応答なし
    Disconnected --> Checking: 応答あり
    Connected --> Closed: 正常終了
    

シーケンス図

重要

図のタイムアウト値はデフォルト値を採用しています。

connected

正常な接続状態である connected を継続しているシーケンス図です。

        sequenceDiagram
    participant C as クライアント
    participant S as Sora
    note over C,S: WebRTC 確立
    note over S: ICE State connected
    S->>+C: STUN Binding-Request
    C-->>-S: STUN Binding-Success
    note left of S: 2.5 秒経過
    S->>+C: STUN Binding-Request
    C-->>-S: STUN Binding-Success
    note left of S: 2.5 秒経過
    S->>+C: STUN Binding-Request
    C-->>-S: STUN Binding-Success
    

connected -> checking

正常な接続状態である connected から一時的に反応が無く checking 状態へ切り替わるシーケンス図です。

        sequenceDiagram
    participant C as クライアント
    participant S as Sora
    note over C,S: WebRTC 確立
    note over S: ICE State connected
    S->>C: STUN Binding-Request
    note left of S: 2.5 秒経過したが反応がない
    note over S: ICE State checking
    S->>C: STUN Binding-Request
    note left of S: 1.0 秒経過
    S->>C: STUN Binding-Request
    note left of S: 1.0 秒経過
    S->>C: STUN Binding-Request
    

checking -> disconnected

一時的に反応が無い checking の状態が続いたため、 切断判断をするために短い間隔で疎通パケットを送信する disconnected 状態へ切り替わるシーケンス図です。

        sequenceDiagram
    participant C as クライアント
    participant S as Sora
    note over C,S: WebRTC 確立
    note over S: ICE State connected
    S->>C: STUN Binding-Request
    note left of S: 2.5 秒経過したが反応がない
    note over S: ICE State checking
    S->>C: STUN Binding-Request
    note left of S: 1.0 秒間隔で 5 秒間送り続けてるが反応がない
    note over S: ICE State disconnected
    S->>C: STUN Binding-Request
    note left of S: 50 ミリ秒
    S->>C: STUN Binding-Request
    

disconnected -> failed

切断判断をするため短い間隔で疎通パケットを送り続けたが、反応が無かったため failed へと切り替わるシーケンス図です。

        sequenceDiagram
    participant C as クライアント
    participant S as Sora
    note over C,S: WebRTC 確立
    note over S: ICE State connected
    S->>C: STUN Binding-Request
    note left of S: 2.5 秒経過したが反応がない
    note over S: ICE State checking
    S->>C: STUN Binding-Request
    note left of S: 1 秒間隔で 5 秒間送り続けてるが反応がない
    note over S: ICE State disconnected
    S->>C: STUN Binding-Request
    note left of S: 50 ミリ秒間隔で 10 秒間送り続けてるが反応がない
    note over S: ICE State failed
    note left of S: S はクライアントを切断したと見なし切断処理を行う
    

disconnected -> checking -> connected

一定時間、不通になっていたため状態が disconnected になっていましたが、 checking を経て connected まで状態が戻るシーケンス図です。

        sequenceDiagram
    participant C as クライアント
    participant S as Sora
    note over C,S: WebRTC 確立
    note over S: ICE State connected
    S->>C: STUN Binding-Request
    note left of S: 2.5 秒経過したが反応がない
    note over S: ICE State checking
    S->>C: STUN Binding-Request
    note left of S: 1 秒間隔で 5 秒間送り続けてるが反応がない
    note over S: ICE State disconnected
    S->>C: STUN Binding-Request
    note left of S: 50 ミリ秒間隔で 10 秒間送り続ける
    C-->>S: STUN Binding-Success
    note over S: ICE State checking
    S->>C: STUN Binding-Request
    note left of S: 1 秒間隔で 5 秒間送り続ける
    C-->>S: STUN Binding-Success
    note over S: ICE State connected
    S->>C: STUN Binding-Request
    note left of S: 2.5 秒間隔で送り続ける
    C-->>S: STUN Binding-Success
    

モード機能

概要

モード機能 は、指定されているモードごとに Sora の挙動を変更する機能です。

目的

Sora 自体は認証の機能を持っていないため、メンテナンス時に一時的に接続をブロックするといった仕組みがありません。 接続をブロックする場合は、認証サーバー側で処理をすることになり不便でした。

そこで、Sora 側にモード機能を持たせることで、モードを切り替えることで接続を気軽にブロックできる機能を追加します。

モード

ノーマルモード

このモードは何もせず、すべての新規接続を受け入れます。

新規コネクションブロックモード

このモードは新規の接続をブロックします。すでに接続しているコネクションはそのままです。

新規セッションブロックモード

このモードは新規セッションの作成をブロックします。すでに接続しているセッションやコネクションはそのままです。

そのためセッション(チャネルに 1 人以上接続しているアクティブな状態)が存在する場合は接続できますが、セッションが存在しない場合は新規の接続をブロックします。

ウェブフック

session.vanished

注意

この機能は 2025 年 6 月リリース予定の Sora にて廃止します

重要

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

このウェブフックは、新規コネクションブロック、または新規セッションブロックモード時にすべてのセッションが破棄されたタイミングで送信されます。

{
  "type": "session.vanished",
}

API

ChangeMode API

モード変更 API です。指定するモードには 3 種類あります。

• normal

• block_new_session

• block_new_connection

$ http POST 127.0.0.1:3000 x-sora-target:Sora_20211215.ChangeMode mode=block_new_session -vvv
POST / HTTP/1.1
Accept: application/json, */*;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 29
Content-Type: application/json
Host: 127.0.0.1:3000
User-Agent: HTTPie/2.3.0
x-sora-target: Sora_20211215.ChangeMode

{
    "mode": "block_new_session"
}


HTTP/1.1 200 OK
access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
access-control-allow-methods: POST, OPTIONS
access-control-allow-origin: http://127.0.0.1:5000
access-control-max-age: 1000
content-length: 28
content-type: application/json
date: Wed, 06 Oct 2021 10:42:35 GMT
server: Cowboy

{
    "mode": "block_new_session"
}

$ http POST 127.0.0.1:3000 x-sora-target:Sora_20211215.ChangeMode mode=block_new_connection -vvv
POST / HTTP/1.1
Accept: application/json, */*;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 32
Content-Type: application/json
Host: 127.0.0.1:3000
User-Agent: HTTPie/2.3.0
x-sora-target: Sora_20211215.ChangeMode

{
    "mode": "block_new_connection"
}


HTTP/1.1 200 OK
access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
access-control-allow-methods: POST, OPTIONS
access-control-allow-origin: http://127.0.0.1:5000
access-control-max-age: 1000
content-length: 31
content-type: application/json
date: Wed, 06 Oct 2021 10:44:05 GMT
server: Cowboy

{
    "mode": "block_new_connection"
}

詳細は ChangeMode をご確認ください。

GetMode API

モード取得 API です。

$ http POST 127.0.0.1:3000 x-sora-target:Sora_20211215.GetMode -vvv
POST / HTTP/1.1
Accept: */*
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 0
Host: 127.0.0.1:3000
User-Agent: HTTPie/2.3.0
x-sora-target: Sora_20211215.GetMode



HTTP/1.1 200 OK
access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
access-control-allow-methods: POST, OPTIONS
access-control-allow-origin: http://127.0.0.1:5000
access-control-max-age: 1000
content-length: 17
content-type: application/json
date: Wed, 06 Oct 2021 10:42:19 GMT
server: Cowboy

{
    "mode": "normal"
}

詳細は GetMode をご確認ください。

クラスター機能

チャネル ID のノード割り当て

クラスター機能を利用した場合、 mode が 新規セッションブロックモード または 新規コネクションブロックモード のノードに対して、 新規のチャネル ID を割り当てません。

シーケンス図

block_new_connection

        sequenceDiagram
    participant C1 as クライアント1
    participant C2 as クライアント2
    participant S as Sora
    participant A as アプリケーションサーバー
    note over S: Sora 起動
    note over S: モード: normal
    C1->>S: "type": "connect"
    note over C1,S: クライアント1 WebRTC 確立

    A->>S: ChangeMode API<br/>mode=block_new_connection
    note over S: モード: block_new_connection
    break 接続失敗
        C2->>S: "type": "connect"
    end

    A->>S: ChangeMode API<br/>mode=normal
    note over S: モード: normal
    C2->>S: "type": "connect"
    note over C2,S: クライアント2 WebRTC 確立
    

block_new_session

        sequenceDiagram
    participant C1 as クライアント1
    participant C2 as クライアント2
    participant C3 as クライアント3
    participant S as Sora
    participant A as アプリケーションサーバー
    note over S: Sora 起動
    note over S: モード: normal
    C1->>S: "type": "connect"<br/>channel_id=spam
    note over C1,S: クライアント1 WebRTC 確立

    A->>S: ChangeMode API<br/>mode=block_new_session
    note over S: モード: block_new_session
    break 接続失敗
        C2->>S: "type": "connect"<br/>channel_id=ham
    end
    C3->>S: "type": "connect"<br/>channel_id=spam
    note over C3,S: クライアント3 WebRTC 確立
    

ヘルスチェック機能

概要

Sora にはヘルスチェック機能を搭載しています。

URL は固定で /.ok で、ポート番号はシグナリングに利用するポートでデフォルトは 5000 番です。 ポート番号を変更する場合は sora.conf の signaling_port を変更してください。

確認

$ http GET http://192.0.2.1:5000/.ok

単体利用時

問題が無ければ 200 OK が返ります。

クラスター利用時

200

• 問題が無ければ 200 OK が返ります

• ローリングアップデート時にアップデートに成功しクラスターへの参加が成功してれば 200 OK が返ります

503

• ノードがクラスターに参加していない場合 503 Service Unavailable が返ります

• block_new_connection モード時に 503 Service Unavailable が返ります

メディア配信ワーカー機能

概要

メディア配信ワーカー機能は Sora の内部で音声や映像を配信するワーカーを複数用意することで、 1 チャネルで高ビットレートの映像をより多くのクライアントに配信することをできるようにする機能です。

この機能を検討する基準

1 チャネルで複数クライアントへ配信する際、1 チャネルで 100 Mbps 以上の帯域を利用する際に検討してください。

注意

この設定は基本的にチューニングの部類に入ります。そのため、サポートまでお気軽にご相談ください。

設定

media_publish_worker_number

sora.conf の media_publish_worker_number に音声や映像の 1 配信に利用するメディア配信ワーカー数を指定してください。

• デフォルトの配信ワーカー数は 1 です

• 同時に 100 クライアント以上へ配信する場合はまず 10 を設定することを推奨します

• ワーカー数が 10 であれば 1 チャネル 1000 クライアント以上の配信がができるようになります

• 最小は 1 で、最大は 500 です

ワーカー数の設定を 10 以上で検討している場合はまずサポートにご相談ください。

仕組み

注釈

Sora の内部的な話のため、基本的に利用者は意識する必要はありません。

Sora では 1 クライアントが他のクライアントに音声や映像を配信する際、 1 つのワーカーが担当しています。この部分を複数ワーカーにすることで、 他のクライアントに配信する際の負荷を分散することができます。

たとえば 1 チャネルで 1000 クライアントに配信する場合、1 つのワーカーが 1000 クライアントに配信するのではなく、 10 個のワーカーが 100 クライアントずつに配信するようになります。

シーケンス図

配信ワーカー 1

視聴者側への配信が直列。

        sequenceDiagram
   participant Pub as 配信者
   participant S as Sora
   participant Sub1 as 視聴者1
   participant Sub2 as 視聴者2
   Pub-)S: 音声と映像
   S-)Sub1: 音声と映像
   S-)Sub2: 音声と映像
    

配信ワーカー複数

視聴者側への配信が並列化される。

        sequenceDiagram
   participant Pub as 配信者
   participant S as Sora
   participant Sub1 as 視聴者1
   participant Sub2 as 視聴者2
   Pub-)S: 音声と映像
   note right of S: 並列で配信
   par
      S-)Sub1: 音声と映像
   and
      S-)Sub2: 音声と映像
   end
    

音声ストリーミング機能

概要

Sora に WebRTC で送られてきた音声を、接続ごとに HTTP/2 で外部へ出力し、外部から受信した結果をクライアントへプッシュで通知する機能です。

注意

OBS (WHIP) 機能利用時の Opus の設定

OBS の Opus のビットレートがデフォルトの場合は正常に動作しない場合があります。 その場合はビットレートを 128 kbps まで下げて見てください。

IPv6 非対応

現時点で、音声ストリーミングは IPv6 を利用できません。

音声ストリーミングの送信単位

音声ストリーミングを audio_streaming_url へ送信するのは、 コネクション単位であり、セッション単位ではありません。

HTTP/2

• 音声ストリーミングゲートウェイは HTTP/2 に対応している必要があります

• h2c と h2 の両方に対応しています

• http:// から始めると h2c を利用します

• https:// から始めると h2 を利用します

マルチストリームでのみ利用可能

音声ストリーミング機能はマルチストリームを有効にした状態でのみ利用できます。

音声ストリーミングの配信

音声ストリーミング機能はセッション単位で有効になります。

実際に音声ストリーミングで音声が外部に配信されるのは、 role が sendrecv または sendonly、かつ audio が true になっている場合のみ有効になります。

注釈

外部から受信した結果はロールなどは関係なく、サブスクライブしているすべてのクライアントが受信できます。

音声ストリーミングのヘッダー

音声ストリーミング機能において、HTTP/2 経由で送信する音声パケットに Sora 側でヘッダーを追加する機能です。

sora.conf の audio_streaming_header を true に設定するとヘッダーが追加されます。

        ---
title: "音声ストリーミングヘッダーフォーマット"
---
packet-beta
0-63: "Timestamp"
64-127: "SeqNum"
128-159: "Length"
    

• Timestamp は音声パケット送信時の UTC 時間マイクロ秒の整数です

  • RTP のタイムスタンプとは異なります

  • 64 ビット符号なし整数です

• SequenceNumber は音声パケットのシーケンス番号で、 1 から始まります

  • RTP のシーケンス番号とは異なります

  • 64 ビット符号なし整数です

• Length はヘッダーを除いた音声パケットの長さです

  • 32 ビット符号なし整数です

言語コードの指定

音声ストリーミングを利用する場合、 言語コードを指定する必要があります。

シグナリング接続時、または認証成功時の払い出しで {"audio_streaming_language_code": "ja-JP"} のように指定してください。 指定するのは 文字列であればなんでもかまいません 。Sora 自体は言語コードには関与しません。あくまでただの文字列として扱います。

注意

言語コードが指定されていない接続は、音声ストリーミングが開始している場合でも音声ストリーミングを行いません。 言語コードは音声を解析するにあたり必要になるためこのような仕様になっています。

セッションウェブフック経由での開始

音声ストリーミングはセッション単位で開始、終了します。

セッション生成時から音声ストリーミングを開始したい場合、 セッションウェブフックの戻り値に {"audio_streaming": true} を指定することで音声ストリーミングが開始します。

そのセッションに参加してきた言語コードが指定されているクライアントはすべて音声ストリーミングが行われます。

セッション破棄時の音声ストリーミング終了

チャネルのセッションが破棄したタイミングで音声ストリーミングは終了します。

API 経由での開始と終了

セッションの途中で音声ストリーミングを開始する場合は StartAudioStreaming API を利用する必要があります。

また、セッションの途中で音声ストリーミングを終了する場合は StopAudioStreaming API を利用する必要があります。

自動開始/停止機能

サブスクライブ中のコネクション数が 1 つ以上に増えたとき、自動的に音声ストリーミングが開始します。 逆に、サブスクライブ中のコネクション数が 0 になったときには、音声ストリーミングが自動的に停止します。

この機能を有効にすることで、サブスクライブが 0 の時は音声ストリーミングを行わなくなり、 転送量などを抑えることができます。

以下の方法でこの機能を有効にできます:

• セッションウェブフックの session.created 時の払い出しで {"audio_streaming": true, "audio_streaming_auto": true} を指定した場合

注意

この機能が有効化されているときには、 StartAudioStreaming API と StopAudioStreaming API は利用できません。

この機能を停止するにはセッションを破棄する必要があります。 API を使用してセッションを破棄する場合には、 TerminateSession API を利用してください。

リトライ条件

Sora は音声ストリーミングゲートウェイへの接続が失敗した際、リトライを行います。

リトライを行うには audio_streaming_max_retries と audio_streaming_retry_interval に 0 以外の値を指定してある必要があります。

リトライを行う

• 音声ストリーミングゲートウェイへ接続ができなかった場合

• 音声ストリーミングゲートウェイへ接続時に 5xx 系のステータスコードが返された場合

リトライを行わない

• 接続時に 4xx 系が送られてきた場合

• 接続後に "type": "error" が送られてきた場合

audio_streaming 関連の払い出し設定の組み合わせによる動作

音声ストリーミングゲートウェイへの接続

セッションウェブフックの session.created 時に払い出した、 audio_streaming, audio_streaming_auto の組み合わせ毎の 配信者接続時 の音声ストリーミングゲートウェイへの接続の有無は下記の通りです。

audio_streaming の指定	audio_streaming_auto の指定	subscribe 数	音声ストリーミングゲートウェイへの接続
true	true [1]	0	無し
true	true [1]	1 以上	有り
true	false	0	有り [2]
true	false	1 以上	有り [2]
true	指定なし	0	有り [2]
true	指定なし	1 以上	有り [2]
false	false	0	無し
false	false	1 以上	無し [3]
false	指定なし	0	無し [3]
false	指定なし	1 以上	無し [3]
指定なし	false	0	無し
指定なし	false	1 以上	無し [3]
指定なし	指定なし	0	無し [3]
指定なし	指定なし	1 以上	無し [3]

[1] (1,2)

audio_streaming_auto に true を指定する場合には、audio_streaming にも true を指定する必要があります

[2] (1,2,3,4)

音声ストリーミングゲートウェイへの接続有無はサブスクライブの数に依存しません

[3] (1,2,3,4,5,6)

接続には StartAudioStreaminga API の実行が必要です

注意

audio_streaming_auto に true を指定したにもかかわらず、audio_streaming を指定しないか、または false を指定した場合は、不正な組み合わせのため audio_streaming_auto、audio_streaming の指定は無視されます

クライアントへの解析結果の送信

セッションウェブフックの session.created 時に払い出した、 audio_streaming, audio_streaming_auto の組み合わせ毎の subscribe しているクライアントへの解析結果の送信有無は下記の通りです。

audio_streaming の指定	audio_streaming_auto の指定	subscribe 数	クライアントへの解析結果の送信
true	true [4]	0	無し
true	true [4]	1 以上	有り
true	false	0	無し
true	false	1 以上	有り
true	指定なし	0	無し
true	指定なし	1 以上	有り
false	false	0	無し
false	false	1 以上	無し
false	指定なし	0	無し
false	指定なし	1 以上	無し
指定なし	false	0	無し
指定なし	false	1 以上	無し
指定なし	指定なし	0	無し
指定なし	指定なし	1 以上	無し

[4] (1,2)

audio_streaming_auto に true を指定する場合には、audio_streaming にも true を指定する必要があります

注意

audio_streaming_auto に true を指定したにもかかわらず、audio_streaming を指定しないか、または false を指定した場合は、不正な組み合わせのため audio_streaming_auto、audio_streaming の指定は無視されます

1 コネクション 1 HTTP/2 コネクション

音声ストリーミングが開始している状態でそのチャネルに新規クライアントが参加すると、 audio_streaming_url 宛てに新しく HTTP/2 コネクションが張られ、 クライアントから送られてきた Opus のバイナリデータがそのまま送られます。

HTTP/2 コネクションを張る際のヘッダーには以下の値が入ります。

• sora-channel-id

  • クライアントのチャネル ID

• sora-connection-id

  • クライアントのコネクション ID

• sora-audio-streaming-language-code

  • クライアントの言語コード

プッシュ通知経由での戻り値の通知

シグナリングのプッシュ通知経由で外部サーバーからの戻り値を通知します。

{
    "type": "push",
    "data": {
        "type": "audio_streaming_result",
        "connection_id": "<connection_id>",
        "result": "レスポンスがそのまま含まれる"
    }
}

ウェブフック

音声ストリーミングの開始、終了時にウェブフックを通知します。

このウェブフックはデフォルト無効です。

もし利用する場合は sora.conf の ignore_audio_streaming_webhook を false にして通知を有効にしてください。

audio-streaming.started

• セッションで音声ストリーミングが開始した場合に通知されます

• 自動開始/停止が有効の場合は "audio_streaming_auto": true が入ってきます

• 音声ストリーミングを開始した時間が "audio_streaming_started_timestamp" に入ってきます

• このウェブフックはかならず session.created よりも後に送信されます

{
  "data": {
    "audio_streaming_auto": false,
    "audio_streaming_started_timestamp": "2023-05-01T08:23:58.489262Z"
  },
  "id": "VWGZ8NK2C55XBCGQ54SECK7J08",
  "label": "WebRTC SFU Sora",
  "timestamp": "2023-05-01T08:24:20.757279Z",
  "type": "audio-streaming.started",
  "version": "2023.2.0",
  "max_connections": 1,
  "node_name": "[email protected]",
  "session_id": "DYPX8R6F4D11ZEG6XCX6N8EEWM",
  "channel_id": "sora",
  "multistream": true,
  "spotlight": false,
  "created_time": 1682929437,
  "total_connections": 1,
  "created_timestamp": "2023-05-01T08:23:57.274844Z"
}

audio-streaming.stopped

• セッションで音声ストリーミング停止した場合に通知されます

• 自動開始/停止が有効な場合は "audio_streaming_auto": true が入ってきます

• 音声ストリーミングを開始した時間が "audio_streaming_started_timestamp" に入ってきます

• 音声ストリーミングを停止した時間が "audio_streaming_stopped_timestamp" に入ってきます

• このウェブフックはかならず session.destroyed よりも前に送信されます

{
  "data": {
    "audio_streaming_auto": false,
    "audio_streaming_started_timestamp": "2023-05-01T08:23:58.489262Z",
    "audio_streaming_stopped_timestamp": "2023-05-01T08:24:20.756785Z"
  },
  "id": "VWGZ8NK2C55XBCGQ54SECK7J08",
  "label": "WebRTC SFU Sora",
  "timestamp": "2023-05-01T08:24:20.757279Z",
  "type": "audio-streaming.stopped",
  "version": "2023.2.0",
  "max_connections": 1,
  "node_name": "[email protected]",
  "session_id": "DYPX8R6F4D11ZEG6XCX6N8EEWM",
  "channel_id": "sora",
  "multistream": true,
  "spotlight": false,
  "created_time": 1682929437,
  "total_connections": 1,
  "created_timestamp": "2023-05-01T08:23:57.274844Z"
}

audio-streaming.failed

重要

このウェブフックは イベントウェブフック として送信されます。

このウェブフックは、Sora が接続する音声ストリーミングゲートウェイが利用するサービスに不具合があったことを、Sora に伝える仕組みです。

• sora.conf の audio_streaming_max_retries が 0 では無い場合に有効になります

• sora.conf の ignore_audio_streaming_failed_webhook が false の場合にウェブフックが送られるようになります

  • true にした場合でも event_webhook.jsonl にログは出力されます

リトライが発生する場合は最大リトライ数を超えている場合に、以下の状況でウェブフックが送信されます。

• 音声ストリーミングゲートウェイに接続した際 5xx 系のエラーが返ってきた場合に送信します

• 音声ストリーミングゲートウェイに接続した際 4xx 系のエラーが返ってきた場合に送信します

• 音声ストリーミングゲートウェイから "type": "error" が返ってきた場合に送信します

• 音声ストリーミングゲートウェイへの接続確立がタイムアウト以外で失敗した場合に送信します

音声ストリーミングを再開したい場合は、再接続をしてください。

音声ストリーミングゲートウェイへの接続がタイムアウトになった場合にはウェブフックは送信されません。

注釈

音声ストリーミングゲートウェイへの接続は HTTP/2 で行われます。 そのため接続の途中で問題が起きた場合は HTTP ステータスコードを受け取ることはできません。 その代わりに音声ストリーミングゲートウェイが送ってくる "type": "error" メッセージでエラーを検知します。

{
  "data": {
    "failed_reason": "<string>"
  },
  "id": "VWGZ8NK2C55XBCGQ54SECK7J08",
  "label": "WebRTC SFU Sora",
  "timestamp": "2023-05-01T08:24:20.757279Z",
  "type": "audio-streaming.failed",
  "role": "sendrecv",
  "version": "2024.1.0",
  "node_name": "[email protected]",
  "client_id": "B2JPGFZPMD3H973Y811MF8ZZ70",
  "connection_id": "B2JPGFZPMD3H973Y811MF8ZZ70",
  "bundle_id": "B2JPGFZPMD3H973Y811MF8ZZ70",
  "session_id": "DYPX8R6F4D11ZEG6XCX6N8EEWM",
  "channel_id": "sora",
  "multistream": true,
  "simulcast": false,
  "spotlight": false,
  "log_written": true
}

シグナリング通知経由で audio-streaming.failed をクライアントへ通知する

このシグナリング通知は、Sora が接続する音声ストリーミングゲートウェイが利用するサービスに不具合があったことを、 そのチャネルに参加している全てのクライアントへ通知する仕組みです。

sora.conf にて signaling_notify_audio_streaming_failed に true を指定した場合、 audio_streaming_url への接続を諦めた際、セッションに参加している全てのコネクションにシグナリング通知 audio-streaming.failed を送信します。

この設定はデフォルトで false です。

{
  "type": "notify",
  "event_type": "audio-streaming.failed",
  "failed_connection_id": "<connection_id>"
}

設定

audio_streaming_url

デフォルト:

指定なし

音声ストリーミングゲートウェイの URL を指定してください。 音声ストリーミングゲートウェイは HTTP/2 に対応している必要があります。

https または http から始まる URL を指定してください。

詳細は audio_streaming_url をご確認ください。

audio_streaming_max_retries

デフォルト:

0

範囲:

0..10

音声ストリーミングゲートウェイへの接続が失敗した場合の最大リトライ回数を指定してください。

詳細は audio_streaming_max_retries をご確認ください。

audio_streaming_retry_interval

デフォルト:

5 s

範囲:

0..60 s

音声ストリーミングゲートウェイへの接続が失敗した場合のリトライ間隔を指定してください。

詳細は audio_streaming_retry_interval をご確認ください。

default_audio_streaming_result_push

デフォルト:

true

音声ストリーミングゲートウェイからのレスポンスをシグナリングプッシュ通知で送ることをデフォルトで行うかを指定してください。

詳細は default_audio_streaming_result_push をご確認ください。

default_audio_streaming_language_code

デフォルト:

指定なし

音声ストリーミングゲートウェイ接続時に HTTP ヘッダー sora-audio-steraming-language-code にデフォルトで含める文字列を指定してください。

詳細は default_audio_streaming_language_code をご確認ください。

audio_streaming_tls_fullchain_file

デフォルト:

指定なし

音声ストリーミングゲートウェイとの通信に HTTPS で mTLS を利用するための設定です。 中間証明書を含む PEM 形式 のクライアント証明書のパスを設定して下さい。

詳細は audio_streaming_tls_fullchain_file をご確認ください。

audio_streaming_tls_privkey_file

デフォルト:

指定なし

音声ストリーミングゲートウェイとの通信に HTTPS で mTLS を利用するための設定です。 PEM 形式のクライアント証明書秘密鍵のパスを設定して下さい。

詳細は audio_streaming_tls_privkey_file をご確認ください。

audio_streaming_tls_verify_cacert_file

デフォルト:

指定なし

音声ストリーミングゲートウェイとの通信に HTTPS を利用する際に、 サーバー証明書のチェックを行う PEM 形式の CA ファイルのパスを設定して下さい。

詳細は audio_streaming_tls_verify_cacert_file をご確認ください。

注釈

CA 証明書を指定しない場合、OS 組み込みの証明書を利用します。詳細は ウェブフックリクエストなどの送信先サーバー証明書の検証に利用する OS 組み込みのルート CA 証明書について をご確認ください。

API

StartAudioStreaming API

セッションが存在し、音声ストリーミングが開始していないチャネルに対して音声ストリーミングを開始します。

詳細は StartAudioStreaming をご確認ください。

注釈

この API は audio_streaming_auto が true の場合は利用できません。

StopAudioStreaming API

セッションが存在し、音声ストリーミングが開始しているチャネルに対して音声ストリーミングを停止します。

注釈

音声ストリーミングを終了すると、すべての接続のサブスクライブしている状態は初期化され、デフォルトの値に戻ります。

詳細は StopAudioStreaming をご確認ください。

注釈

この API は audio_streaming_auto が true の場合は利用できません。

SubscribeAudioStreamingResultPush API

指定した接続が、音声ストリーミングゲートウェイからの戻り値のプッシュ通知をサブスクライブするよう設定します。

詳細は SubscribeAudioStreamingResultPush をご確認ください。

注釈

デフォルトの値は sora.conf の default_audio_streaming_result_push が適用されます。

UnsubscribeAudioStreamingResultPush API

指定した接続が、音声ストリーミングゲートウェイからの戻り値のプッシュ通知をサブスクライブしないよう設定します。

注釈

デフォルトの値は sora.conf の default_audio_streaming_result_push が適用されます。

詳細は UnsubscribeAudioStreamingResultPush をご確認ください。

ListAudioStreamingResultPushState API

指定したチャネルのセッションのコネクション毎のサブスクライブの状態を確認します。

[
  {
    "connection_id": "B2JPGFZPMD3H973Y811MF8ZZ70",
    "subscribe": true
  },
  {
    "connection_id": "KT116Z11KX5Y547KA1V12HW8PG",
    "subscribe": false
  },
  {
    "connection_id": "A5GYXGRYAX6590M3AFH7F9Z2H4",
    "subscribe": false
  }
]

詳細は ListAudioStreamingResultPushState をご確認ください。

Audio Streaming Gateway Suzu

重要

Audio Streaming Gateway Suzu は Sora サポートの対象外です

shiguredo/suzu: Audio Streaming Gateway Suzu

Sora から HTTP/2 経由で送られてくるヘッダーや Opus 音声データを Ogg 形式に変換して、 音声からテキストに変換するサービスへ送信し、サービスから受信した解析結果を Sora に返すゲートウェイです。

時雨堂が開発し、 OSS として公開しています。

対応サービス

• Amazon Transcribe

• Google Cloud Speech-to-Text

シーケンス図

Suzu + AWS Transcribe

        sequenceDiagram
    autonumber
    participant C as クライアント
    participant S as Sora
    participant Suzu
    participant AWS Transcribe
    C->>S: SRTP
    C->>S: SRTP
    C->>S: SRTP
    note over C, AWS Transcribe: StartAudioStreaming API 実行
    C->>S: SRTP
    S->>Suzu: Opus over HTTP/2
    Suzu->>AWS Transcribe: Ogg over HTTP/2
    C->>S: SRTP
    S->>Suzu: Opus over HTTP/2
    Suzu->>AWS Transcribe: Ogg over HTTP/2
    C->>S: SRTP
    S->>Suzu: Opus over HTTP/2
    Suzu->>AWS Transcribe: Ogg over HTTP/2
    AWS Transcribe->>Suzu: JSON over HTTP/2
    Suzu->>S: JSON over HTTP/2
    S->>C: シグナリングプッシュ通知
    

自動開始/停止

        sequenceDiagram
  autonumber
  participant C as クライアント
  participant S as Sora
  participant A as アプリケーションサーバー
  participant Suzu
  S->>+A: セッションウェブフック<br>session.created
  A-->>-S: "audio_streaming": true<br>"audio_streaming_auto": true
  C->>S: SRTP
  C->>S: SRTP
  C->>S: SRTP
  A-->>+S: SubscribeAudioStreamingResultPush API 実行
  S->>-A: 200 OK
  note right of S: Subscribe しているCが 1 になった
  S->>+A: セッションウェブフック<br>audio-streaming.started
  A-->>-S: 200 OK
  note over S, Suzu: Suzu への HTTP/2 コネクション接続
  C->>S: SRTP
  S->>Suzu: Opus over HTTP/2
  C->>S: SRTP
  S->>Suzu: Opus over HTTP/2
  Suzu->>S: JSON over HTTP/2
  S->>C: シグナリングプッシュ通知
  C->>S: SRTP
  S->>Suzu: Opus over HTTP/2
      A-->>+S: UnsubscribeAudioStreamingResultPush API 実行
  S->>-A: 200 OK
  note right of S: Subscribe しているクライアントが 0 になった
  note over S, Suzu: Suzu への HTTP/2 コネクション切断
  C->>S: SRTP
    

転送フィルター機能

注釈

転送とは Sora がクライアントから受信した音声や映像を他のクライアントに送信することを意味します。

概要

転送フィルター機能は、Sora 側でクライアントへ転送する音声や映像のパケットをフィルターする機能です。

目的

転送フィルター機能を使うことで、Sora から音声や映像のパケットをクライアントへ転送しなくなるため、 クライアントやサーバー側の負荷を減らすことができます。

また、接続直後に音声や映像を転送しなくすることもできます。 そのため、何らかのアクションを取ってから音声と映像を流し始めることができるようになります。

注意

利用可能なロール

この機能は role が sendrecv または recvonly の場合にのみ利用できます。

データチャネルを利用したメッセージング

データチャネルを利用したメッセージング機能は転送フィルター機能の対象外です。

機能

注釈

チャネル単位、コネクション単位でフィルターが設定できます。

• 転送フィルターのルール指定は、チャネル単位、コネクション単位で指定できます

• 転送フィルターのルールにはコネクション ID とクライアント ID と種類 (音声、映像) が指定できます

• 転送フィルタールール に指定するコネクション ID は 音声や映像の 送信元の コネクション ID です。

• 転送フィルタールール に指定するクライアント ID は 音声や映像の 送信元の クライアント ID です。

• シグナリング指定時や認証成功時に そのコネクションに対するフィルター を指定できます

• 転送フィルター更新時に転送フィルターのバージョンを確認し、一致した場合のみ更新することができます

• 転送フィルターにメタデータを持たせることができます

転送フィルタールールの仕様

シグナリング、認証成功時の払い出し、セッション払い出し、API で共通のフィルタールールについて説明します。

フィルターは AND と OR が指定できます。ルールはリストとオブジェクトを利用して設定します。

重要

転送フィルターのルールでは転送先のコネクション ID やクライアント ID を指定することはできません。 指定できるのは Sora に音声や映像を送信しているコネクションやクライアントの ID のみです。

チャネル単位でフィルターを設定する

CreateChannelForwardingFilter API またはセッション生成時の払い出しを利用することで、 指定したチャネルに参加している すべてのコネクションへ音声や映像を送信するかどうか を設定できます。

コネクション単位でフィルター設定する

CreateConnectionForwardingFilter API 、シグナリング接続時の指定、または認証成功時の払い出しを利用することで、 指定したチャネルの 指定したコネクションへ音声や映像を送信するかどうか を設定できます。

特定のコネクションに対してあるコネクションの映像を送りたくないなどが可能になります。

1 チャネルや 1 コネクションに複数の転送フィルターを設定する

複数のフィルターを設定したい場合は マルチ転送フィルター機能 をご確認ください。

OR と AND

トップレベルリストは OR を表しており、リストのリストでは AND を表しています。

[[rule_1], [rule_2, rule_3]]

この場合は (rule_1 OR (rule_2 AND rule_3)) という転送フィルタールールが適用されます。

[[rule_1, rule_2]]

この場合は (rule_1 AND rule_2) という転送フィルタールールが適用されます。

警告

[[[rule_1, rule_2], [rule_3]], [rule_5]] のような 3 階層のルールは定義できません。 転送フィルターのルールで利用できるリストの階層は 2 階層までとなります。

action について

転送フィルターには action を指定できます。

アクションには block と allow が指定できます。

• block を指定した場合は、 rules にマッチした条件でのみ転送をブロックします

• allow を指定した場合は、 rules にマッチした条件でのみ転送を許可します

デフォルトでは block になります。

重要

block と allow では allow が優先されます。

• チャネルで block 、コネクションで allow が指定されていた場合、コネクションの allow のみが適用されます

• チャネルで allow 、コネクションで block が指定されていた場合、チャネルの allow のみが適用されます

• チャネルで allow 、コネクションで allow が指定されていた場合、両方の allow が適用されます

ケース 1

チャネル単位の転送フィルターでは映像を block にして設定している状態で、 ある接続の転送フィルターでは映像を allow に設定した場合、 その接続では allow の転送フィルターだけが有効になり、その接続に映像が転送されます。

ケース 2

チャネル単位の転送フィルターでは映像を allow にして設定している状態で、 ある接続の転送フィルターでは音声を allow に設定した場合、 その接続には音声と映像が転送がされます。

version について

転送フィルターに文字列でバージョンを version 項目で指定することができます。これはオプションです。

転送フィルター作成時に version を指定した場合、 転送フィルターを更新するには expected_version と desired_version を指定する必要があります。

expected_version は更新する転送フィルターの version を指定します。 転送フィルターのバージョンが異なった場合、転送フィルターの更新は失敗します。

転送フィルターのバージョンが一致した場合、転送フィルターの更新は成功します、 desired_version の値が、新しい version の値となります。

version を利用する事で転送フィルターを並列で実行されても期待した値に変更することができるようになります。

metadata について

転送フィルターにはメタデータを metadata 項目を指定することができます。これはオプションです。

転送フィルター作成、または更新時に metadata に JSON 値を指定することができます。 この metadata は転送フィルターの挙動には影響せず、転送フィルターの情報を自由に書き込める項目です。

metadata を利用する事で転送フィルターに関する情報を自由に管理することができるようになります。

rules の書き方

すべての項目は必須です

• field

  • フィールドには connection_id と client_id と kind が指定できます

  • connection_id

    • フィルターの対象となる音声や映像の 送信元の コネクション ID を指定してください

  • client_id

    • フィルターの対象となる音声や映像の 送信元の クライアント ID を指定してください

  • kind

    • フィルターに音声や映像を指定できます

• operator

  • オペレーターには is_in と is_not_in が指定できます

  • is_in

    • values に指定されたリストに含まれる値にマッチしている場合は転送フィルターの対象とする

  • is_not_in

    • values に指定されたリストに含まれる値にマッチしていない場合は転送フィルターの対象とする

• values

  • バリューにはかならず文字列のリスト ["string", ...] を指定してください

  • field に合った値を指定してください

  • field が kind の場合は "audio" または "video" を指定してください

{
  "action": "block",
  "rules": [
    // チャネルに接続しているすべてのクライアントへ connection_id "S8YEN0TSE13JDC2991NG4XZ150" からの音声と映像をブロックし転送しない
    // また
    // チャネルに接続しているすべてのクライアントへ client_id が "screen-share" の音声をブロックし転送しない
    [
      {
        "field": "connection_id",
        "operator": "is_in",
        "values": ["S8YEN0TSE13JDC2991NG4XZ150"]
      }
    ],
    [
      {
        "field": "client_id",
        "operator": "is_in",
        "values": ["screen-share"]
      },
      {
        "field": "kind",
        "operator": "is_in",
        "values": ["audio"]
      }
    ]
  ]
}

field に connection_id を指定した場合

kind を指定しなくても audio と video がブロックされます。

{
  "action": "block",
  "rules": [
    // チャネルに接続しているすべてのコネクションへ connection_id "S8YEN0TSE13JDC2991NG4XZ150" からの音声と映像をブロックし転送しない
    [
      {
        "field": "connection_id",
        "operator": "is_in",
        "values": ["S8YEN0TSE13JDC2991NG4XZ150"]
      }
    ]
  ]
}

送信元の指定をせずすべての音声と映像をブロックする

kind を指定することで送信元の指定がないフィルターを作成できます。 音声と映像の両方をブロックするので values に audio と video 両方を指定しています。

{
  "action": "block",
  "rules": [
    // チャネルに接続しているすべてのコネクションに対して音声と映像をブロックし転送しない
    [
      {
        "field": "kind",
        "operator": "is_in",
        "values": ["audio", "video"]
      }
    ]
  ]
}

フィルタールールの適用

• チャネル単位でのフィルター

  • 転送フィルターのルールにマッチした条件で、すべてのコネクションに対して転送するかどうか

• コネクション単位でのフィルター

  • 転送フィルターのルールでマッチした条件で、指定した connection_id に対して転送するかどうか

• フィルターの優先度

  • チャネル単位でフィルターとコネクション単位でのフィルターに優先度はない

  • 優先度は allow と block にだけあり allow が優先される

転送フィルター共通 API の仕様

ListForwardingFilters API

指定したチャネルのチャネルとコネクション両方の転送フィルターを確認できます。

• channel_id

  • string

  • 必須

• blocked

  • boolean

  • オプション

  • ブロック状況を表示するかどうかを指定します

$ http POST 127.0.0.1:3000/ \
    x-sora-target:Sora_20230628.ListForwardingFilters \
    channel_id=sora \
    blocked:=true \
    -vvv

{
  "channel_forwarding_filters": [
    {
      "action": "block",
      "rules": [
        [{"field": "kind", "operator": "is_in", "values": ["audio", "video"]}]
      ]
    }
  ]
  "channel_forwarding_filter": {
    "action": "block",
    "rules": [
      [{"field": "kind", "operator": "is_in", "values": ["audio", "video"]}]
    ]
  },
  "connection_forwarding_filters": [
    {
      "connection_id": "9PZ98RZV1H3RSEZ82SBBC289F8",
      "action": "allow",
      "rules": [
        [{"field": "kind", "operator": "is_in", "values": ["audio"]}]
      ]
    },
    {
      "connection_id": "8QA9YX7ZJX3150ZJ87874TBFMG",
      "action": "allow",
      "rules": [
        [{"field": "kind", "operator": "is_in", "values": ["audio"]}]
      ]
    }
  ],
  "blocked": [
    {
      "destination_connection_id": "9PZ98RZV1H3RSEZ82SBBC289F8",
      "source_connection_id_list": [
        "2VJPS671HH1EH3HNY13SXHS5RG"
      ],
      "kind": "audio"
    },
    {
      "destination_connection_id": "9PZ98RZV1H3RSEZ82SBBC289F8",
      "source_connection_id_list": [
        "2VJPS671HH1EH3HNY13SXHS5RG",
        "C4D50FG8Q16BF4YCTT0V8YGSXM"
      ],
      "kind": "video"
    }
  ]
}

チャネル単位の転送フィルター API の仕様

CreateChannelForwardingFilter API

指定したチャネルに対して Sora の転送フィルターを作成する API です。

• channel_id

  • string

  • 必須

• rules

  • [[object, ...], [object, ...]]

  • 必須

  • 転送フィルターのルールを指定します

• action

  • string

  • オプション

  • block または allow

  • デフォルトは block

• version

  • string

  • オプション

  • 転送フィルターのバージョンを指定します

• metadata

  • JSONValue

  • オプション

  • 転送フィルターのメタデータを指定します

• name

  • string (最大 255 バイト)

  • オプション

  • 転送フィルターの名前を指定します

• priority

  • integer (0-32767)

  • オプション

  • 転送フィルターの優先度を指定します

$ http POST 127.0.0.1:3000/ \
    x-sora-target:Sora_20230628.CreateChannelForwardingFilter \
    channel_id=sora \
    rules:='[
      [
        {"field": "client_id", "operator": "is_in", "values": ["screen-share"]},
        {"field": "kind", "operator": "is_in", "values": ["video"]}
      ]
    ]' \
    -vvv

UpdateChannelForwardingFilter API

指定したチャネルの転送フィルターを更新します。

• channel_id

  • string

  • 必須

• rules

  • [[object, ...], [object, ...]]

  • 必須

  • 転送フィルターのルールを指定します

• action

  • string

  • オプション

  • block または allow

  • デフォルトは block

• expected_version

  • string

  • オプション

  • 転送フィルターの期待するバージョンを指定します

• desired_version

  • string

  • オプション

  • 転送フィルターの更新成功後のバージョンを指定します

• metadata

  • JSONValue

  • オプション

  • 転送フィルターのメタデータを指定します

• name

  • string (最大 255 バイト)

  • オプション

  • 転送フィルターの名前を指定します

• priority

  • integer (0-32767)

  • オプション

  • 転送フィルターの優先度を指定します

$ http POST 127.0.0.1:3000/ \
    x-sora-target:Sora_20230628.UpdateChannelForwardingFilter \
    channel_id=sora \
    rules:='[
      [
        {"field": "connection_id", "operator": "is_in", "values": ["RAV7EG7Z693NDCZFGGXZS7WBRC"]}
      ],
      [
        {"field": "client_id", "operator": "is_in", "values": ["screen-share"]},
        {"field": "kind", "operator": "is_in", "values": ["video"]}
      ]
    ]' \
    -vvv

DeleteChannelForwardingFilter API

指定したチャネルの転送フィルターを削除します。

• channel_id

  • string

  • 必須

• name

  • string (最大 255 バイト)

  • オプション

  • 転送フィルターの名前を指定します

$ http POST 127.0.0.1:3000/ \
    x-sora-target:Sora_20230628.DeleteChannelForwardingFilter \
    channel_id=sora \
    -vvv

コネクション単位の転送フィルター API の仕様

CreateConnectionForwardingFilter API

指定したチャネルの特定のコネクションの転送フィルターを作成します。

• channel_id

  • string

  • 必須

• connection_id

  • string

  • 必須

• rules

  • [[object, ...], [object, ...]]

  • 必須

  • 転送フィルターのルールを指定します

• action

  • string

  • オプション

  • block または allow

  • デフォルトは block

• version

  • string

  • オプション

  • 転送フィルターのバージョンを指定します

• metadata

  • JSONValue

  • オプション

  • 転送フィルターのメタデータを指定します

• name

  • string (最大 255 バイト)

  • オプション

  • 転送フィルターの名前を指定します

• priority

  • integer (0-32767)

  • オプション

  • 転送フィルターの優先度を指定します

$ http POST 127.0.0.1:3000/ \
    x-sora-target:Sora_20230628.CreateConnectionForwardingFilter \
    channel_id=sora \
    connection_id=T9J5FM3NTH6JH4JKFGTSHB1BA0 \
    rules:='[
      [
        {"field": "client_id", "operator": "is_in", "values": ["screen-share"]},
        {"field": "kind", "operator": "is_in", "values": ["video"]}
      ]
    ]' \
    -vvv

UpdateConnectionForwardingFilter API

指定したチャネルの特定のコネクションの転送フィルターを更新します。

• channel_id

  • string

  • 必須

• connection_id

  • string

  • 必須

• rules

  • [[object, ...], [object, ...]]

  • 必須

  • 転送フィルターのルールを指定します

• action

  • string

  • オプション

  • block または allow

  • デフォルトは block

• expected_version

  • string

  • オプション

  • 転送フィルターの期待するバージョンを指定します

• desired_version

  • string

  • オプション

  • 転送フィルターの更新成功後のバージョンを指定します

• metadata

  • JSONValue

  • オプション

  • 転送フィルターのメタデータを指定します

• name

  • string (最大 255 バイト)

  • オプション

  • 転送フィルターの名前を指定します

• priority

  • integer (0-32767)

  • オプション

  • 転送フィルターの優先度を指定します

$ http POST 127.0.0.1:3000/ \
    x-sora-target:Sora_20230628.UpdateConnectionForwardingFilter \
    channel_id=sora \
    connection_id=T9J5FM3NTH6JH4JKFGTSHB1BA0 \
    rules:='[
      [
        {"field": "connection_id", "operator": "is_in", "values": ["RX1GD666HD53F3M36PB7KEZMBR"]},
        {"field": "kind", "operator": "is_in", "values": ["video"]}
      ]
    ]' \
    -vvv

DeleteConnectionForwardingFilter API

指定したチャネルの特定のコネクションの転送フィルターを削除します。

• channel_id

  • string

  • 必須

• connection_id

  • string

  • 必須

• name

  • string (最大 255 バイト)

  • オプション

  • 転送フィルターの名前を指定します

$ http POST 127.0.0.1:3000/ \
    x-sora-target:Sora_20230628.DeleteConnectionForwardingFilter \
    channel_id=sora \
    connection_id=T9J5FM3NTH6JH4JKFGTSHB1BA0 \
    -vvv

セッション生成時のチャネル単位転送フィルター仕様

セッション生成時に転送フィルターを指定することができます。

重要

セッション生成時の払い出しで転送フィルターがエラーになった場合、接続に失敗します。

以下はセッション接続時には音声しか転送しないフィルター例です。

{
  "forwarding_filters": [
    {
      "action": "allow",
      "rules": [
        [
        {"field": "kind", "operator": "is_in", "values": ["audio"]}
        ]
      ]
    }
  ]
}

• version や metadata も指定できます

• name や priority も指定できます

注釈

セッション生成時に転送フィルターを指定した場合、 API 経由で変更するには UpdateChannelForwardingFilter API を利用する必要があります。

2025 年 12 月リリース予定の Sora にて廃止する forwarding_filter

• forwarding_filter は 2025 年 12 月リリース予定の Sora にて廃止します

• forwarding_filter は forwarding_filters と両方指定した場合は forwarding_filters が優先されます

• forwarding_filters は配列です

• version や metadata も指定できます

• name や priority も指定できます

{
  "forwarding_filter": {
    "action": "allow",
    "name": "audio-only",
    "priority": 128,
    "rules": [
      [
       {"field": "kind", "operator": "is_in", "values": ["audio"]}
      ]
    ]
  }
}

シグナリング時のコネクション単位転送フィルター仕様

シグナリング接続時に コネクション単位での転送フィルター を指定することができます。

この転送フィルターは接続したコネクションにのみ影響します。

重要

シグナリング接続時に転送フィルターを指定する場合は sora.conf にて、 signaling_forwarding_filters を true に設定する必要があります。

以下は接続時に映像を転送せずに音声だけを自分に転送するフィルター例です。

{
  "type": "connect",
  "role": "sendrecv",
  "channel_id": "sora",
  "forwarding_filters": [
    {
      "action": "allow",
      "rules": [
        [
         {"field": "kind", "operator": "is_in", "values": ["audio"]}
        ]
      ]
    }
  ]
}

注釈

シグナリング時に転送フィルターを指定した場合、 API 経由で変更するには UpdateConnectionForwardingFilter API を利用する必要があります。

2025 年 12 月リリース予定の Sora にて廃止する forwarding_filter

{
  "type": "connect",
  "role": "sendrecv",
  "channel_id": "sora",
  "forwarding_filter": {
    "action": "allow",
    "name": "audio-only",
    "priority": 128,
    "rules": [
      [
       {"field": "kind", "operator": "is_in", "values": ["audio"]}
      ]
    ]
  }
}

認証成功時払い出し時のコネクション単位転送フィルターの仕様

認証成功時に、コネクション単位の転送フィルターを指定することができます。

重要

認証成功時の払い出しの転送フィルターがエラーになった場合、接続に失敗します。

以下は映像を転送せずに音声だけをそのコネクションに転送するフィルター例です。

{
  "allowed": true,
  "forwarding_filters": [
    {
      "action": "allow",
      "rules": [
        [
         {"field": "kind", "operator": "is_in", "values": ["audio"]}
        ]
      ]
    }
  ]
}

version や metadata も指定できます。

注釈

認証成功払い出し時に転送フィルターを作成した場合、 API 経由で変更するには UpdateConnectionForwardingFilter API を利用する必要があります。

2025 年 12 月リリース予定の Sora にて廃止する forwarding_filter

{
  "allowed": true,
  "forwarding_filter": {
    "action": "allow",
    "name": "audio-only",
    "priority": 128,
    "rules": [
      [
       {"field": "kind", "operator": "is_in", "values": ["audio"]}
      ]
    ]
  }
}

シグナリング通知

転送フィルターを作成、更新、削除したタイミングで、 転送フィルターによって転送されていないかどうかを、シグナリング経由で通知します。

転送フィルターが影響する範囲にのみ通知されます。

通知は送信側と受信側の両方に送られます。

• destination は映像または音声の送信先です

• source は映像または音声の送信元です

• destination_connection_id は映像または音声の送信先の connection_id です

• souce_connection_id は映像または音声の送信元の connection_id です

forwarding.blocked

転送フィルターによりブロックが有効になったタイミングで送信側と受信側に通知されます。

以下の通知は、 source_connection_id の送信元から destination_connection_id の送信先へ送信した音声をブロックすることを表しています。

{
  "type": "notify",
  "kind": "audio",
  "event_type": "forwarding.blocked",
  "destination_connection_id": "14P91M6B5526928T14WGPW9H6G",
  "source_connection_id": "GHRNJAQ40S15KCF3MZF0N7QS8R"
}

forwarding.allowed

転送フィルターによりブロックが解除されたタイミングで送信側と受信側に通知されます。

以下の通知は、 source_connection_id の送信元から destination_connection_id の送信先へ送信した音声のブロックが解除されたことを表しています。

{
  "type": "notify",
  "kind": "audio",
  "event_type": "forwarding.allowed",
  "destination_connection_id": "14P91M6B5526928T14WGPW9H6G",
  "source_connection_id": "GHRNJAQ40S15KCF3MZF0N7QS8R"
}

フィルター例

特定のクライアントにだけ音声と映像を転送しない

CreateConnectionForwardingFilter API で音声と映像を転送したくないクライアントに対してフィルターを設定してください

connection_id=T9J5FM3NTH6JH4JKFGTSHB1BA0 のクライアントに音声と映像を転送しないフィルターの設定例

  $ http POST 127.0.0.1:3000/ \
      x-sora-target:Sora_20230628.CreateConnectionForwardingFilter \
      channel_id=sora \
      connection_id=T9J5FM3NTH6JH4JKFGTSHB1BA0 \
      action=block \
      rules:='[
        [
          {"field": "kind", "operator": "is_in", "values": ["audio", "video"]}
        ]
      ]' \
      -vvv

このフィルターは指定したコネクションに転送するパケットのフィルターを設定しています。 kind で audio と video が is_in に設定されており、 すべてのクライアントから Sora に送信されてくる audio と video を指定したクライアントに転送しなくなります。

特定の connection_id の送信元以外の音声や映像を転送しない

CreateChannelForwardingFilter API で音声と映像の転送を許可する送信元のコネクション ID を指定してください。

connection_id=S8YEN0TSE13JDC2991NG4XZ150 以外からの音声と映像を転送しないフィルターの設定例

  $ http POST 127.0.0.1:3000/ \
      x-sora-target:Sora_20230628.CreateChannelForwardingFilter \
      channel_id=sora \
      action=block \
      rules:='[
        [
          {"field": "connection_id", "operator": "is_not_in", "values": ["S8YEN0TSE13JDC2991NG4XZ150"]}
        ]
      ]' \
      -vvv

このフィルターでは指定したチャネルに転送するパケットのフィルターを設定しています。 operator に is_not_in を指定することで指定したコネクション ID の送信元以外からのパケットの送信をブロックします。

全体をブロックしているが、一時的に特定の connection_id の送信先だけには全クライアントの音声と映像を転送する

CreateChannelForwardingFilter API で音声と映像の転送をブロックしてください。

音声と映像を転送しないフィルターの設定例

  $ http POST 127.0.0.1:3000/ \
      x-sora-target:Sora_20230628.CreateChannelForwardingFilter \
      channel_id=sora \
      action=block \
      rules:='[
        [
          {"field": "kind", "operator": "is_in", "values": ["audio", "video"]}
        ]
      ]' \
      -vvv

CreateConnectionForwardingFilter API で一時的にブロックしない送信先の connection_id を指定してください。 ポイントはコネクション単位で action に allow を指定します。 allow は block を上書きします。

connection_id=T9J5FM3NTH6JH4JKFGTSHB1BA0 のクライアントに音声と映像を転送するフィルターの設定例

  $ http POST 127.0.0.1:3000/ \
      x-sora-target:Sora_20230628.CreateConnectionForwardingFilter \
      channel_id=sora \
      connection_id=T9J5FM3NTH6JH4JKFGTSHB1BA0 \
      action=allow \
      rules:='[
        [
          {"field": "kind", "operator": "is_in", "values": ["audio", "video"]}
        ]
      ]' \
      -vvv

これで全体をブロックした状態で、指定した connection_id の送信先にだけ音声や映像が転送されます。

FAQ

チャネルとコネクションの転送フィルターはどちらが優先されますか？

チャネルとコネクションで優先度は特にありません。

ただしアクションの allow が優先されます。 チャネルのアクションが block でコネクションのアクションが allow で、 同じコネクション ID を指定した場合は allow が優先されます。

転送フィルターでブロックされたときの挙動を教えてください

Sora は転送フィルターでブロックされた音声や映像パケットをクライアントに転送しません。 そのため受信側ではパケットが「何も送られてこない」という状態になります。

転送フィルターが更新、または削除や allow で転送される状態になるとパケットの転送を開始します。

1 チャネルや 1 コネクションに複数の転送フィルターを指定できますか？

指定できます。 マルチ転送フィルター機能 をご確認ください。

転送フィルターを有効にした場合は ontrack は SDK 側で発火しますか？

発火します。転送フィルターはあくまで 本来転送する音声や映像を Sora でフィルターする機能 のため、 SDK 側の ontrack 自体は発火します。

フィルターでブロックされたりブロック解除されたタイミングをクライアント側で知ることはできますか？

Sora はシグナリング通知経由でブロック/ブロック解除されたタイミングで通知します。 これはブロックされた送信側と受信側両方に通知が飛びます。

シーケンス図

チャネル単位のブロック例

        sequenceDiagram
    autonumber
    participant C1 as クライアント1
    participant C2 as クライアント2
    participant C3 as クライアント3
    participant S as Sora
    participant A as アプリケーションサーバー
    note over C1,S: クライアント1: WebRTC 確立
    note over C2,S: クライアント2: WebRTC 確立
    par
        C1-)S: SRTP
        S-)C1: SRTP (C2)
    and
        C2-)S: SRTP
        S-)C2: SRTP (C1)
    and
        A->>+S: CreateChannelForwardingFilter<br>channel_id=sora<br>block,kind(audio,video)
        S-->>-A: 200 OK
        note right of S: 音声と映像をこのチャネル内で転送しない
    end
    note over C1,S: ブロックフィルターで転送がブロックされる
    par
        C1-)S: SRTP
    and
        C2-)S: SRTP
    and
        note over C3,S: クライアント3: WebRTC 確立
    end
    par
        C1-)S: SRTP
    and
        C2-)S: SRTP
    and
        C3-)S: SRTP
    end
        A->>+S: DeleteChannelForwardingFilter<br>channel_id=sora
        S-->>-A: 200 OK
    note over C1,S: ブロックフィルターが削除された
    par
        C1-)S: SRTP
        S-)C1: SRTP (C2)
        S-)C1: SRTP (C3)
    and
        C2-)S: SRTP
        S-)C2: SRTP (C1)
        S-)C2: SRTP (C3)
    and
        C3-)S: SRTP
        S-)C3: SRTP (C2)
        S-)C3: SRTP (C1)
    end
    note over C1,S: 音声と映像の転送がブロックされなくなった
    

チャネルフィルターとコネクションフィルター組み合わせ例

• 音声と映像がブロックされる

• connection_id 1 にだけ映像が転送される

        sequenceDiagram
   autonumber
   participant C1 as クライアント1<br>connection_id: 1
   participant C2 as クライアント2<br>connection_id: 2
   participant S as Sora
   participant A as アプリケーションサーバー
   note over C1,S: クライアント1: WebRTC 確立
   note over C2,S: クライアント2: WebRTC 確立
   par
     C1-)S: SRTP (音声)
     S-)C2: SRTP (音声)
   and
       C1-)S: SRTP (映像)
     S-)C2: SRTP (映像)
   and
       C2-)S: SRTP (音声)
       S-)C1: SRTP (音声)
   and
       C2-)S: SRTP (映像)
       S-)C1: SRTP (映像)
   and
       note right of S: 音声と映像をこのチャネル内で転送しない
       A->>+S: CreateChannelForwardingFilter<br>channel_id=sora<br>block,kind(audio,video)
       S-->>-A: 200 OK
       note right of S: 映像を connection_id=1 にだけ転送する
       A->>+S: CreateConnectionForwardingFilter<br>channel_id=sora<br>connection_id: 1<br>allow,kind(video)
       S-->>-A: 200 OK
   end
   note over C1,S: チャネル単位フィルターで音声と映像の転送がブロックされる
   note over C1,S: コネクション単位フィルターで映像の転送が connection_id: 1 には許可される
   par
       note right of S: ブロックされる
       C1-)S: SRTP (音声)
   and
       note right of S: ブロックされる
       C1-)S: SRTP (映像)
   and
       note right of S: ブロックされる
       C2-)S: SRTP (音声)
   and
       C2-)S: SRTP (映像)
       note right of S: 許可されているので転送する
       S-)C1: SRTP (映像)
   end
       A->>+S: DeleteConnectionForwardingFilter<br>channel_id=sora<br>connection_id: 1
       S-->>-A: 200 OK
   note over C1,S: コネクション単位のフィルターが削除された
   par
       C1-)S: SRTP (音声)
   and
       C1-)S: SRTP (映像)
   and
       C2-)S: SRTP (音声)
   and
       C2-)S: SRTP (映像)
   end
   note over C1,S: 全員が音声と映像の転送がブロックされている
    

version を利用した変更保証

並列に転送フィルター更新 API が叩かれてもバージョンチェックをすることで更新結果を保証する。

        sequenceDiagram
    participant S as Sora
    participant A as アプリケーションサーバー
    par
        A->>+S: UpdateChannelForwardingFilters API<br>{"expect_version": "spam", "desire_version": "ham", ...}
        S-->>-A: 200 OK
        note over A: 更新成功
    and
        A->>+S: UpdateChannelForwardingFilters API<br>{"expect_version": "spam", "desire_version": "beacon", ...}
        S-->>-A: 400 Bad Request<br>{"message": "INVALID-VERSION", "version": "ham"}
        note over A: 更新失敗
    end
    

マルチ転送フィルター機能

注意

この機能を利用する場合は事前にサポートまでご連絡ください

警告

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

概要

マルチ転送フィルター機能は、転送フィルターに名前 (name) と優先度 (priority) を指定することで、 1 チャネルや 1 コネクションに複数の転送フィルターを設定できる機能です。

認証接続時と認証成功時/セッション生成時の払い出しの注意点

• forwarding_filter は非推奨となります

• forwarding_filter は 2025 年 12 月リリース予定の Sora にて廃止します

• forwarding_filter と forwarding_filters の両方を指定した場合 forwarding_filters が優先されます

• forwarding_filter でも name と priority を指定できます

• forwarding_filters で name が重複した場合はエラーになります

• forwarding_filters で name と priority が未指定の場合は default と 32767 として扱われます

  • ただし未指定が複数ある場合は name の default が重複としていると判断されエラーになります

仕様

• マルチ転送フィルターは 1 チャネルや 1 コネクションに対して複数の転送フィルターを設定できる機能です

• 複数の転送フィルターを設定する場合は、 name と priority を指定して転送フィルターを追加します

  • name は既に設定済の転送フィルターと重複することはできません

  • name と priority のどちらかだけを指定することはできません

• 転送フィルターは転送を判定するタイミングで、指定されている全ての転送フィルターを判定します

  • ただし判定するタイミングで、優先度が高いものから判定します

• 転送フィルター追加時に名前 (name) と優先度 (priority) を指定することができます

• 転送フィルター更新時に名前 (name) と優先度 (priority) を指定することができます

• 転送フィルター削除時に名前 (name) を指定して削除することができます

• 名前は任意の文字列 (最大 255 バイト) が指定できます

• 名前は重複できません

  • channel_id または connection_id 単位でユニークな名前が必要

  • 名前が重複している場合はエラーになります

• 優先度は 0-32767 (16#7FFF) の間で指定してください

• 優先度が一番高いのは 0 で、数値が大きいほど優先度が低くなります

• 優先度は重複できます

  • 優先度が同じ場合は allow が優先されます

  • block のみの場合は OR で判定します

  • allow のみの場合は OR で判定します

  • block / block / allow なら allow のみで判定します

• name と priority を指定しない場合はデフォルト値が設定されます

  • name は "default" です

  • priority は 32767 です

性能

1 チャネルや 1 コネクションに対して数千などのフィルターを設定しない限り、性能が劣化することはありません。

認証成功時の払い出し

forwarding_filters: [
   {
      "name": "client-id-carol-allow",
      "priority": 0,
      "action": "allow",
      "rules": [
         [
            {
               "field": "client_id",
               "operator": "is_in",
               "values": [
                  "carol"
               ]
            }
         ]
      ]
   },
   {
      "name": "default",
      "priority": 32767,
      "action": "block",
      "rules": [
         [
            {
               "field": "kind",
               "operator": "is_in",
               "values": [
                  "audio",
                  "video"
               ]
            }
         ]
      ]
   }
]

セッション生成時の払い出し

forwarding_filters: [
   {
      "action": "block",
      "name": "client-id-alice-block",
      "priority": 0,
      "rules": [
         [
            {
               "field": "client_id",
               "operator": "is_in",
               "values": [
                  "alice"
               ]
            }
         ]
      ]
   },
   {
      "action": "block",
      "name": "client-id-bob-block",
      "priority": 0,
      "rules": [
         [
            {
               "field": "client_id",
               "operator": "is_in",
               "values": [
                  "bob"
               ]
            }
         ]
      ]
   },
   {
      "action": "block",
      "name": "default",
      "priority": 32767,
      "rules": [
         [
            {
               "field": "kind",
               "operator": "is_in",
               "values": [
                  "audio"
               ]
            }
         ]
      ]
   }
]

プレイアウト遅延機能

注意

この機能を利用する場合は事前にサポートまでご連絡ください

警告

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

概要

プレイアウト遅延機能は映像フレームを視聴側がどれくらい早く再生する必要があるかどうかを WebRTC SFU Sora 側から指定する仕組みです。

WebRTC はレイテンシーを優先する仕組みですが、 プレイアウト遅延機能を利用することで、再生までの間にバッファを持たせる事ができるようになります。 これにより、映像の安定性を向上させることができます。また、リップシンクなどを諦めてとにかく映像の低遅延化を優先する事もできるようになります。

注意

この機能はベストエフォートです。視聴側は、可能な限り配信側が指定した範囲内に収まるように映像を再生するように努力しますが、 ネットワークの状況によっては、指定した範囲外で再生されることがあります。

仕組み

この機能は プレイアウト遅延を制御するための RTP ヘッダー拡張 を利用して実現しています。

ただし、 プレイアウト遅延を制御するための RTP ヘッダー拡張 は本来、 P2P 利用時に配信側が視聴側に対して再生遅延量を一定の範囲内に制限できるようにするための機能であり、フレームをどのくらいの速さでレンダリングする必要があるかについての送信者の意図を受信者に伝えることを目的としています。

そのため、 WebRTC SFU Sora のプレイアウト遅延機能は本来の プレイアウト遅延を制御するための RTP ヘッダー拡張 利用目的とは異なります。

注意

プレイアウト遅延機能はロールによって適用される範囲が異なります。

sendrecv

受信するストリーム全てに適用されます。

sendonly

適用されません。

recvonly

受信するストリーム全てに適用されます。

設定

プレイアウト遅延では視聴側の再生遅延の最小値と最大値を指定できます。 指定できる範囲は 0 ミリ秒から 40950 ミリ秒の間です。

利用方法

プレイアウト遅延機能は rtp_hdrext_playout_delay が true である必要があります。 rtp_hdrext_playout_delay はデフォルトで true です。

sora.conf でのデフォルト値での指定

全ての接続のデフォルト値を指定したい場合、 sora.conf にて default_playout_delay_min_delay と default_playout_delay_max_delay を指定してください。

認証成功時の指定

もしコネクション単位でプレイアウト遅延を指定したい場合、 認証成功時に playout_delay_min_delay と playout_delay_max_delay を指定してください。

詳細は playout_delay_min_delay と playout_delay_max_delay の払い出し をご確認ください。

設定例

実際には環境に合わせて調整してください

オーディオのないリモートデスクトップ

min_delay:

0 ms

max_delay:

0 ms

リモートデスクトップはできるだけ早く再生したいことが多いため、 プレイアウト遅延を 0 に設定することをお勧めします。

注釈

とにかく低遅延で映像を表示したい場合の設定です。

ミーティング

双方向

min_delay:

100 ms

max_delay:

200 ms

ミーティングは少しの遅延が存在しても、問題ない場合が多いため、100 ミリ秒の遅延を設定することをお勧めします。

ビデオストリーミング

min_delay:

400 ms

max_delay:

1000 ms

一方向のビデオストリーミングでは、低遅延で配信しつつも、映像が止まったり乱れたりする事を防ぐために、 400 ミリ秒の遅延を設定することをお勧めします。

統計エクスポーター機能

注意

ユーザーエージェント統計 API は 2025 年 6 月リリースの Sora にて廃止します 代わりに 統計ウェブフック機能 をご利用ください。

注意

この機能を利用する場合は事前にサポートまでご連絡ください

警告

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

概要

Sora 経由で統計情報コレクターに向けて統計情報をエクスポートする機能です。

注意

IPv6 非対応

現時点で、統計エクスポーターは IPv6 を利用できません。

HTTP/2

• 統計コレクターサーバーは HTTP/2 に対応している必要があります

• h2c と h2 の両方に対応しています

• http:// から始めると h2c を利用します

• https:// から始めると h2 を利用します

WebRTC Stats Collector Kohaku

URL:

https://github.com/shiguredo/kohaku

Kohaku は統計エクスポーター対応の統計コレクターです。

設定

stats_collector_url

統計情報を収集するコレクターの URL を指定します。 HTTP または HTTPS の URL が指定できます。

stats_collector_url = http://192.0.2.10:5890/collector

default_stats_exporter

stats_collector_url が指定されていた場合、デフォルトでは統計情報をコレクターに送信します。 もし、統計情報の送信を接続毎に行いたい場合、この設定を false にし、 統計情報を送信したい接続の認証成功時に "stats_exporter": true を払い出すようにしてください。

default_stats_exporter = false

stats_exporter_number

統計情報を出力するエクスポーターの数を指定できます。 基本的にはデフォルトの 5 で足りますが、同時接続数が多い場合は変更をお勧めします。

stats_exporter_number = 5

stats_exporter_tls_fullchain_file

mTLS を利用するための設定で、中間証明書を含むクライアント証明書を PEM 形式で設定して下さい。

stats_exporter_tls_fullchain_file = /path/to/fullchain.pem

stats_exporter_tls_privkey_file

統計コレクターサーバーと mTLS を利用するための設定で、クライアント証明書の秘密鍵を PEM 形式で設定して下さい。

重要

秘密鍵にパスフレーズが設定されている場合はエラーとなります

stats_exporter_tls_privkey_file = /path/to/privkey.pem

stats_exporter_tls_verify_cacert_file

注釈

CA 証明書を指定しない場合、OS 組み込みの証明書を利用します。詳細は ウェブフックリクエストなどの送信先サーバー証明書の検証に利用する OS 組み込みのルート CA 証明書について をご確認ください。

統計コレクターサーバーとの通信に HTTPS を利用した際、サーバー証明書のチェックを行う CA ファイルを PEM 形式で設定して下さい。

stats_exporter_tls_verify_cacert_file = /path/to/server_cacert.pem

エクスポーター

統計情報をコレクターに対して送ります。

共通

• type

  • 統計情報の種類情報が入ります

• node_name

  • Sora のノード名が入ります

  • クラスター機能を利用していない場合は sora@127.0.0.1 です

• version

  • Sora のバージョンが入ります

• label

  • sora.conf に設定された label が入ります

• timestamp

  • Sora が stats を送る直前の時間 RFC3339 形式の (UTC) が入ります

HTTP ヘッダー

注釈

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

注意

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

統計エクスポーターの HTTP ヘッダー に sora-stats-exporter-type と x-sora-stats-exporter-type というヘッダー名で統計エクスポーターのタイプが入ってきます。

type が connection.user-agent の場合は sora-stats-exporter-type: connection.user-agent と x-sora-stats-exporter-type: connection.user-agent のように値が入ってきます。

type: connection.user-agent

クライアントから送られてくるユーザーエージェント統計情報です。

ユーザーエージェント統計情報は W3C の Identifiers for WebRTC's Statistics API に準拠している必要があります。

• type

  • connection.user-agent

• channel_id

  • チャネル ID が入ります

• role

• session_id

  • セッション ID が入ります

• client_id

• connection_id

• multistream

• simulcast

• spotlight

• stats

{
  "channel_id": "sora",
  "session_id": "78K3N8E5M551XEKEWR8QN77PHW",
  "client_id": "NCD5EF3ME900ZDJ3SE27Y6AB6R",
  "connection_id": "NCD5EF3ME900ZDJ3SE27Y6AB6R",
  "id": "N6W0DBF6A957B01BKNJJR1HC04",
  "label": "WebRTC SFU Sora",
  "multistream": true,
  "spotlight": false,
  "simulcast": true,
  "stats": [
    {
      "id": "RTCAudioSource_5",
      "kind": "audio",
      "timestamp": 1629449091306.655,
      "type": "media-source",
      "audioLevel": 0.02237006744590594,
      "totalAudioEnergy": 0.15581033797981153,
      "totalSamplesDuration": 5.089999999999936,
      "trackIdentifier": "922dd031-8a4f-4122-9687-ce094fa11ee2"
    }, ...
  ],
  "timestamp": "2021-08-20T08:44:51.308778Z",
  "type": "connection.user-agent",
  "node_name": "[email protected]",
  "version": "2023.2.0"
}

type: connection.sora

現時点ではまだ対応していません

Sora にため込んでいる統計情報です。

type の頻度指定

変化が無かったり変化の少ない stats を送る頻度を減らしています。 デフォルト 600 秒間隔にしています。

type: connection.user-agent

送信頻度を抑えている Stats Type。

• codec

  • Sora の場合、初期値から変更される項目が無いため

• local-candidate

  • Sora の場合、初期値から変更される項目が無いため

• remote-candidate

  • Sora の場合、初期値から変更される項目が無いため

• certificate

  • Sora の場合、初期値から変更される項目が無いため

• peer-connection

  • Sora の場合、初期値から変更される項目が無いため

• track

  • DEPRECATED 項目のため

• stream

  • DEPRECATED 項目のため

シーケンス図

DataChannel シグナリング利用時

        sequenceDiagram
    autonumber
    participant C as クライアント
    participant S as Sora
    participant kohaku as Stats Collector Kohaku
    participant tsdb as TimescaleDB
    note over C,tsdb: WebRTC 確立
    C--)S: Stats over DataChannel
    S->>+kohaku: Stats over HTTP/2
    kohaku->>+tsdb: Insert Stats
    tsdb-->>-kohaku: Ack
    kohaku-->>-S: 200 OK
    

Sora JavaScript (TypeScript) SDK

概要

URL:

https://github.com/shiguredo/sora-js-sdk

Sora JavaScript SDK は Sora を JavaScript から使用するための仕組みです。

サンプル

URL:

https://github.com/shiguredo/sora-js-sdk-examples

ドキュメント

ドキュメントは https://sora-js-sdk.shiguredo.jp/ にて提供しています。

ライセンス

Sora JavaScript SDK は Apache License, Version 2.0 で公開しています。

サポートについて

Sora JavaScript SDK に関する質問・要望・バグなどの報告は Discord の利用をお願いします。

Sora のライセンス契約の有無に関わらず、応答時間と問題の解決を保証しませんのでご了承ください。 ただし、明らかなバグに関しては優先的に対応させていただきます。

Sora JavaScript SDK に対する有償のサポートについては提供しておりません。

Discord

URL:

https://discord.gg/shiguredo

Discord にてコミュニティを運営しています。 なにか質問したい場合は Discord サーバーへ参加してください。

Sora JavaScript SDK については #sora-sdk-faq で sora-javascript-sdk タグを指定してご利用ください。

Sora iOS (Swift) SDK

概要

URL:

https://github.com/shiguredo/sora-ios-sdk

Sora iOS SDK は Sora を iOS から使用するための仕組みです。

ドキュメント

ドキュメントは https://sora-ios-sdk.shiguredo.jp/ にて提供しています。

サンプル

• WebRTC SFU Sora iOS SDK クイックスタート

• WebRTC SFU Sora iOS SDK サンプル集

ライセンス

Sora iOS SDK は Apache License, Version 2.0 で公開しています。

サポートについて

Sora iOS SDK に関する質問・要望・バグなどの報告は Discord の利用をお願いします。

Sora のライセンス契約の有無に関わらず、応答時間と問題の解決を保証しませんのでご了承ください。 ただし、明らかなバグに関しては優先的に対応させていただきます。

Sora iOS SDK に対する有償のサポートについては提供しておりません。

Discord

URL:

https://discord.gg/shiguredo

Discord にてコミュニティを運営しています。 なにか質問したい場合は Discord サーバーへ参加してください。

Sora iOS SDK については #sora-sdk-faq で sora-ios-sdk タグを指定してご利用ください。

NAT64/DNS64 対応

前提

Supporting IPv6 DNS64/NAT64 Networks

Apple IPv6 審査対応として NAT64/DNS64 への対応が必要になります。

iOS SDK は NAT64/DNS64 へ対応しています。ただ WebRTF SFU Sora 側を NAT64/DNS64 へ対応するためには設定を追加する必要があります。

WebRTC SFU Sora の設定

sora.conf の turn を true にして、 turn_fqdn に FQDN を設定してください。それだけで対応は完了です。

turn_fqdn = sora.example.com

Sora Android (Kotlin) SDK

概要

URL:

https://github.com/shiguredo/sora-android-sdk

Sora Android SDK は Sora を Android から使用するための仕組みです。

ドキュメント

ドキュメントは https://sora-android-sdk.shiguredo.jp/ にて提供しています。

サンプル

• WebRTC SFU Sora Android SDK クイックスタート

• WebRTC SFU Sora Android SDK サンプル集

ライセンス

Sora Android SDK は Apache License, Version 2.0 で公開しています。

サポートについて

Sora Android SDK に関する質問・要望・バグなどの報告は Discord の利用をお願いします。

Sora のライセンス契約の有無に関わらず、応答時間と問題の解決を保証しませんのでご了承ください。 ただし、明らかなバグに関しては優先的に対応させていただきます。

Sora Android SDK に対する有償のサポートについては提供しておりません。

Discord

URL:

https://discord.gg/shiguredo

Discord にてコミュニティを運営しています。 なにか質問したい場合は Discord サーバーへ参加してください。

Sora Android SDK については #sora-sdk-faq で sora-android-sdk タグを指定してご利用ください。

Sora Unity (C++) SDK

概要

URL:

https://github.com/shiguredo/sora-unity-sdk

Sora Unity SDK は Sora を Unity から使用するための仕組みです。

ドキュメント

ドキュメントは https://sora-unity-sdk.shiguredo.jp/ にて提供しています。

ライセンス

Sora Unity SDK は Apache License, Version 2.0 で公開しています。

サンプル

shiguredo/sora-unity-sdk-samples: WebRTC SFU Sora Unity SDK サンプル集

サポートについて

Sora Unity SDK に関する質問・要望・バグなどの報告は Discord の利用をお願いします。

Sora のライセンス契約の有無に関わらず、応答時間と問題の解決を保証しませんのでご了承ください。 ただし、明らかなバグに関しては優先的に対応させていただきます。

Sora Unity SDK に対する有償のサポートについては提供しておりません。

Discord

URL:

https://discord.gg/shiguredo

Discord にてコミュニティを運営しています。 なにか質問したい場合は Discord サーバーへ参加してください。

Sora Unity SDK については #sora-sdk-faq で sora-unity-sdk タグを指定してご利用ください。

Sora C++ SDK

概要

URL:

https://github.com/shiguredo/sora-cpp-sdk

Sora C++ SDK は Sora を C++ から使用するための仕組みです。

特徴

• Windows / macOS / Linux / iOS / Android といったプラットフォームに対応しています

• それぞれのプラットフォーム向けのハードウェアエンコーダー / デコーダーに対応しています

詳細は Sora C++ SDK をご確認ください。

サンプル

URL:

https://github.com/shiguredo/sora-cpp-sdk/tree/develop/examples

ライセンス

Sora C++ SDK は Apache License, Version 2.0 で公開しています。

サポートについて

Sora C++ SDK に関する質問・要望・バグなどの報告は Discord の利用をお願いします。

Sora のライセンス契約の有無に関わらず、応答時間と問題の解決を保証しませんのでご了承ください。 ただし、明らかなバグに関しては優先的に対応させていただきます。

Sora C++ SDK に対する有償のサポートについては提供しておりません。

Discord

URL:

https://discord.gg/shiguredo

Discord にてコミュニティを運営しています。 なにか質問したい場合は Discord サーバーへ参加してください。

Sora C++ SDK については #sora-sdk-faq で sora-cpp-sdk タグを指定してご利用ください。

Sora Python (C++) SDK

概要

URL:

https://github.com/shiguredo/sora-python-sdk

Sora Python SDK は Sora を Python から使用するための仕組みです。

特徴

• Sora C++ Python SDK をベースにしています

• Windows / macOS / Linux といったプラットフォームに対応しています

• それぞれのプラットフォーム向けのハードウェアエンコーダー / デコーダーに対応しています

サンプル

https://github.com/shiguredo/sora-python-sdk-examples にサンプルがあります。

ドキュメント

ドキュメントは https://sora-python-sdk.shiguredo.jp/ にて提供しています。

ライセンス

Sora Python SDK は Apache License, Version 2.0 で公開しています。

サポートについて

Sora Python SDK に関する質問・要望・バグなどの報告は Discord の利用をお願いします。

Sora のライセンス契約の有無に関わらず、応答時間と問題の解決を保証しませんのでご了承ください。 ただし、明らかなバグに関しては優先的に対応させていただきます。

Sora Python SDK に対する有償のサポートについては提供しておりません。

Discord

URL:

https://discord.gg/shiguredo

Discord にてコミュニティを運営しています。 なにか質問したい場合は Discord サーバーへ参加してください。

Sora Python SDK については #sora-sdk-faq で sora-python-sdk タグを指定してご利用ください。

Sora C (C++) SDK

概要

URL:

https://github.com/shiguredo/sora-c-sdk

Sora C SDK は Sora を C から使用するための仕組みです。

特徴

• macOS / Linux といったプラットフォームに対応しています

• それぞれのプラットフォーム向けのハードウェアエンコーダー / デコーダーに対応しています

• 他の SDK と異なり libwebrtc を利用せず、 libdatachannel を利用しているためバイナリサイズ、フットプリントが抑えられています

• リリース周期を長めにすることを目標にしています

詳細は Sora C SDK をご確認ください。

ライセンス

Sora C SDK は Apache License, Version 2.0 で公開しています。

サポートについて

Sora C SDK に関する質問・要望・バグなどの報告は Discord の利用をお願いします。

Sora のライセンス契約の有無に関わらず、応答時間と問題の解決を保証しませんのでご了承ください。 ただし、明らかなバグに関しては優先的に対応させていただきます。

Sora C SDK に対する有償のサポートについては提供しておりません。

Discord

URL:

https://discord.gg/shiguredo

Discord にてコミュニティを運営しています。 なにか質問したい場合は Discord サーバーへ参加してください。

Sora C SDK については #sora-sdk-faq で sora-c-sdk タグを指定してご利用ください。

WebRTC 負荷試験ツール Zakuro

概要

shiguredo/zakuro: WebRTC Load Testing Tool Zakuro

WebRTC は、要求するビットレートや利用するネットワーク、送信者の数、受信者の数によって負荷が変わります。 弊社では、 Sora のサーバーサイジング向けに Sora 専用の WebRTC 負荷試験ツールを公開しています。

ライセンス

Zakuro は Apache License, Version 2.0 で公開しています。

サポートについて

Zakuro のサポートやアドバイスは提供していません。

Discord

URL:

https://discord.gg/shiguredo

Discord にてコミュニティを運営しています。 なにか質問したい場合は Discord サーバーへ参加してください。

Zakuro のチャンネルは #zakuro です。

WebRTC 録画合成ツール Hisui

概要

shiguredo/hisui: Recording Composition Tool Hisui

Sora が生成する録画ファイルを合成するツールを公開しています。

ライセンス

Hisui は Apache License, Version 2.0 で公開しています。

サポートについて

Hisui のサポートやアドバイスは提供していません。

Discord

URL:

https://discord.gg/shiguredo

Discord にてコミュニティを運営しています。 なにか質問したい場合は Discord サーバーへ参加してください。

Hisui のチャンネルは #hisui です。

WebRTC 統計コレクター Kohaku

概要

shiguredo/kohaku: WebRTC Stats Collector Kohaku

WebRTC クライアントの統計情報を収集することで様々な問題を解決しやすくなります。 弊社では、 Sora 経由でクライアントの統計情報を取得できるようにする WebRTC 統計コレクターを公開しています。

ライセンス

Kohaku は Apache License, Version 2.0 で公開しています。

サポートについて

Kohaku のサポートやアドバイスは提供していません。

Discord

https://discord.gg/shiguredo

Discord にてコミュニティを運営しています。 なにか質問したい場合は Discord サーバーへ参加してください。

Kohaku のチャンネルは #kohaku です。

音声ストリーミングゲートウェイ Suzu

概要

shiguredo/suzu: Audio Streaming Gateway Suzu

Sora が出力する音声ストリーミングを音声解析サービスに転送するツールを公開しています。

ライセンス

Suzu は Apache License, Version 2.0 で公開しています。

サポートについて

Suzu のサポートやアドバイスは提供していません。

Discord

https://discord.gg/shiguredo

Discord にてコミュニティを運営しています。 なにか質問したい場合は Discord サーバーへ参加してください。

Suzu のチャンネルは #suzu です。

Sora Archive Uploader

概要

shiguredo/sora-archive-uploader: Sora Archive Uploader

Sora Archive Uploader は Sora の出力する録画ファイルを S3 または S3 互換のオブジェクトストレージに、アップロードするツールです。 Systemd timer などで定期的に実行することで、録画ファイルを自動的にアップロードすることができます。

問題になりがちな録画ファイルのアップロードに利用する帯域を制限する事ができます。

ライセンス

Sora Archive Uploader は Apache License, Version 2.0 で公開しています。

サポートについて

Sora Archive Uploader のサポートやアドバイスは提供していません。

Discord

URL:

https://discord.gg/shiguredo

Discord にてコミュニティを運営しています。 なにか質問したい場合は Discord サーバーへ参加してください。

Sora Archive Uploader についての質問やバグ報告は Discord の #sora-tool-faq チャンネルにお願いします。

Sora Exporter

概要

shiguredo/sora_exporter: Prometheus exporter for WebRTC SFU Sora metrics.

Sora Exporter は Sora の GetStatsReport API を Prometheus 形式に変換してくれる prometheus エージェントです。

ライセンス

Sora Exporter は Apache License, Version 2.0 で公開しています。

サポートについて

Sora Exporter のサポートやアドバイスは提供していません。

Discord

URL:

https://discord.gg/shiguredo

Discord にてコミュニティを運営しています。 なにか質問したい場合は Discord サーバーへ参加してください。

Sora Exporter についての質問やバグ報告は Discord の #sora-tool-faq チャンネルにお願いします。

Media Processors

概要

shiguredo/media-processors: Media Processors

仮想背景やノイズ抑制といったメディア処理をブラウザで簡単に行えるようにするためのライブラリです。

ライセンス

Media Processors は Apache License, Version 2.0 で公開しています。

サポートについて

Media Processors のサポートやアドバイスは提供していません。

Discord

URL:

https://discord.gg/shiguredo

Discord にてコミュニティを運営しています。 なにか質問したい場合は Discord サーバーへ参加してください。

Media Processors のチャンネルは #media-processors です。

libwebrtc 音声処理

注意

この資料の正確性を保証しません。

重要

この資料についての問い合わせは Sora のサポート範囲には含まれません。

この資料は libwebrtc M99 (4844) 時点の資料です。

libwebrtcでの音声処理全般（前提知識）

ソースコード

• 音声処理関連は webrtc/modules/audio_processing/ 以下にまとまっている

音声フレーム

• 音声フレームは AudioBuffer クラスに格納されて渡ってくる

• サンプリングレートは 16khz or 32kHz or 48kHz のいずれか

• 1 フレームには 10ms 分のサンプルが格納されている:

  • 16kHz なら 160 個

  • 32kHz なら 320 個

  • 48kHz なら 480 個

• 基本的には、 AudioBuffer::SplitIntoFrequencyBands() を使ってフレームを周波数帯域毎のバンドに分割した上で、各バンドに対して音声処理が適用される

  • 何分割されるかは、サンプリングレートによって変わり、ひとつのバンド内のサンプル数は 160 になるようになっている

  • つまり、

    • 16kHz なら一分割 (分割なし）

    • 32kHz なら二分割 (low, high)

    • 48kHz なら三分割 (low, middle, high)

  • 処理適用後は、 AudioBuffer::MergeFrequencyBands() ですべてのバンドが結合され、通常の音声フレームの形式に戻される

音声フレームの処理タイミング

• 音声処理の対象となる音声フレームは audio_processing_impl.cc の中で処理されることになる

• 各音声フレームの処理タイミングには、音声ストリームの「入口」と「出口」の 2 つがある

  • 前者の場合には AudioProcessingImpl::ProcessCaptureStreamLocked() 内で処理が適用される

    • 大半の音声処理はここで実行される

  • 後者の場合には AudioProcessingImpl::ProcessRenderStreamLocked() 内で処理が適用される

    • ほとんどの音声処理は、こちら側では何も行わない

    • エコーキャンセルでは「実際に出力される音声フレームのバッファリング」といった軽い処理が実施される

• なお、これはローカルストリームについての話であり、 WebRTC のようにネットワークを跨いだストリームの「入口（送信側）」と「出口（受信側）」の話とは独立している

  • libwebrtc の音声処理の API としては送信側ストリームと受信側ストリームのどちらにも適用できる

  • ただし、このドキュメントで扱うような処理は、一般に、送信側ストリームに適用されることが多い

各音声処理の適用順序

音声処理の主な適用箇所となる AudioProcessingImpl::ProcessCaptureStreamLocked() メソッド内での、各音声処理の適用順序を記載する。

なお、実際に音声データの更新まで行われる場合には [処理] 、（原則として）データ収集のみの場合には [分析] と記載としている。

また、それぞれの音声処理は、設定や構成によってスキップされることがある。

適用順序:

1. [処理] ハイパスフィルタ（設定次第で後ろの箇所に移動）

2. [処理] 前回の AGC の結果を受けての、入力音声データの音量レベル調整

3. [分析] エコーキャンセル

4. [分析] AGC マネージャ

5. [処理] バンド分割

6. [処理] ハイパスフィルタ

7. [分析] AGC

8. [処理] エコーキャンセル

9. [分析] ノイズ抑制

10. [処理] ノイズ抑制

11. [処理] モバイル版エコーキャンセル

12. [処理] AGC マネージャ

13. [処理] AGC

14. [処理] バンド統合

15. [処理] トランジェント抑制 ※ コメントで「AGC の前後のどちらが良いのかは要調査」との記載がある

16. [処理] AGC2

以下では、具体的な例として Chromium での Android および iOS の場合に適用される処理と、その順序を記載する。 ソースコードとしては media/webrtc/helpers.cc の CreateWebRtcAudioProcessingModule() および ConfigAutomaticGainControl() 関数でこれらの構成が決定されている。

なお、ハイパスフィルタやノイズ抑制、エコーキャンセル、AGC の有効・無効はユーザが利用時に指定できるが、それらはすべて有効になっているものとする。 また、実験的なフィールドトライアルの機能はすべて無効になっているものとする。

Android の場合の適用順序

1. [処理] ハイパスフィルタ

2. [処理] バンド分割

3. [分析] AGC

4. [分析] ノイズ抑制

5. [処理] ノイズ抑制

6. [処理] モバイル版エコーキャンセル

7. [処理] AGC

8. [処理] バンド統合

なお AGC のモードは kFixedDigital となっている（モードの意味については AGC の節を参照）。

iOS の場合の適用順序

1. [処理] ハイパスフィルタ

2. [分析] エコーキャンセル

3. [処理] バンド分割

4. [分析] AGC

5. [処理] エコーキャンセル

6. [分析] ノイズ抑制

   • 入力音声データ（ capture_buffer ）ではなく、 エコーキャンセル処理の結果得られた liear_aec_buffer を分析対象とする

7. [処理] ノイズ抑制

8. [処理] AGC

9. [処理] バンド統合

なお AGC のモードは kAdaptiveAnalog となっている。

ハイパスフィルタ

音声の低周波成分をカットする処理

概要

• HighPassFiler::Process() によって行われる

• アルゴリズムは BiQuadFilter (双2次フィルタ) の "Direct form 1"

• 計算量としては「各音声フレーム内の各サンプルを走査して、数回の算術演算（加算と乗算）を適用する」という極めて軽いもの

補足

• 音声フレームの各チャネルは独立して処理される

• HighPassFiler::Process() に渡すフラグによって「音声フレーム全体」ないし「一番下のバンドだけ」に処理が適用されるかどうかが切り替わる

  • デフォルトはおそらく前者

  • 後者の場合には、周波数成分の高いバンドへの処理はスキップされて、オリジナルのデータがそのまま使われる（ハイパスなのでこれでも問題はない）

• フィルタの実装は CascadedBiQuadFilter クラス

  • "Cascaded"とあるようにフィルタを複数回適用できるようなインタフェースになっているけれど、今回の用途では、各音声フレームの各チャネルに対して、常に 1 回だけ適用される

  • フィルタの係数は high_pass_filter.cc#21 で定義されている

• フィルタのイメージとしては 双2次フィルタ (Biquad Filter) の周波数特性（振幅・位相）の一覧 の記事も参考になる

ノイズ抑制

音声フレーム内の雑音を抑制するための処理

主に定常的な雑音に対して効果を発揮する

概要

• NoiseSuppressor::Analyze() および NoiseSuppressor::Process() によってノイズ抑制が行われる

• Analyze と Process が分かれているのは、他の音声処理（e.g., エコーキャンセル）の影響を受けずに、ノイズ抑制用に必要な情報の収集を行えるようにするため

NoiseSuppressor::Analyze() での処理:

• ここでは 音声フレーム中に含まれるノイズ（スペクトル）の分析 が行われる

• ノイズスペクトルの判定には NoiseEstimator クラスが使用される

  • アルゴリズムは "quantile noise estimation"

    • ざっくりと言えば「ある時間範囲内の音声フレームのスペクトルを、各周波数成分単位でソートして、そのquantile (e.g, 50%タイル)以下のものをノイズと判定する」というもの

    • 対象とするノイズが「定常的なもの」であるという仮定があるので、突発的に発生したような雑音は苦手

    • libwebrtcでの実装と完全に一致している訳ではないが "Quantile based noise estimation for spectral subtraction and Wiener filtering" の論文が参考になる

• また、 NoiseEstimator の結果のノイズスペクトルは「スペクトルの各周波数成分のスピーチ確率」によって調整される

  • ざっくりと言えば「ある周波数成分にスピーチ（人の声）が含まれている確率が高い場合には、前回音声フレームのノイズ推定結果を重視し、そうではない場合は今回のものを重視する」といった重み付けが行われる

    • NoiseEstimator::PostUpdate()

  • スピーチ確率の推定は SpeechProbabilityEstimator クラスによって行われる

    • その際には、まず音声フレームのスペクトルやS/N比を入力としてシグナルモデル ( SignalModel ) を構築する

    • その後、そのモデルに含まれる各特徴量 (e.g., spectral_flatness, lrt (likelihood ratio test)) を使って、スペクトル内の角周波数成分のスピーチ確率が算出される

    • 用語としては "Features for voice activity detection: a comparative analysis" の記事などが参考となる

NoiseSuppressor::Process() での処理:

• ここでは Analyze で得られたノイズスペクトルを使って ノイズを除去するためのフィルタの構築およびその適用 が実施される

• フィルタには Wiener filter (Wikipedia) が使用される (WienerFilter クラス)

• その他細々とした色々な処理が行われているけれど、それらについては後続の「補足」を参照のこと

計算量

• FFT（およびその逆変換）が 2 回適用されている

  • O(N log N)

    • N は 256

    • ノイズ抑制の際には「現在の音声フレーム（バンド単位で160サンプル）」の前方に「前回の音声フレームの末尾部分(96サンプル)」を結合した上で処理が行われるため、 N の値はその合算となる

  • Analyze と Process のそれぞれで音声フレームはスペクトルに変換して処理されるので、その前後で FFT (とその逆変換）が走る

• また、音声フレーム全体を走査するような O(N) の処理が十数回程度実施されている（回数はあくまでも感覚値）

ノイズ抑制によって発生する（理論上の）遅延

• 6ms

• NoiseSuppressor::Process() では、入力音声フレーム内の 4/10 のデータだけが出力フレームに反映されて、残りは次回の処理時まで遅らせられる

  • 上述の通り音声フレームの長さは 10 ms で、その内の 6/10 の出力が次回まで遅らせられるので 6 ms と遅延となる

  • 一部データの出力を遅らせているのは、おそらくフレームの繋ぎ目部分の音声をスムーズにするため

    • Analyze の際にも「前回の入力フレームの末尾（遅延）部分」と「今回の入力フレーム」を結合した上で分析が行われる

補足

マルチチャネルの扱い

• NoiseSuppressor::Analyze() では、各チャネルが独立に処理される

• NoiseSuppressor::Process() では、各チャネルのフィルタの値（ゲイン）が集約される

  • NoiseSuppressor::AggregateWienerFilters()

  • やっていることとしては、各周波数成分について、チャネル間で一番小さなフィルタの値を採用しているだけ

マルチバンドの扱い

• 音声フレーム で触れたように、入力音声フレームのサンプリングレートが 32 kHz 以上の場合は、フレームが周波数帯域（バンド）によって分割されて、バンド単位で処理されることになる

• NoiseSuppressor::Analyze() では、一番低帯域のバンドのみを使って分析が行われる

• NoiseSuppressor::Process() では、一番低帯域のバンドのみにノイズ抑制処理が適用される

  • それよりも大きなバンドについては、ノイズ抑制は行わずに、ローバンドの抑制結果に応じた、全体の音量調整のみを実施する

  • コード的には upper_band_gain というスカラ値 ( float )を、音声フレームに対してひとつ算出し、それをフレーム内の各サンプルに乗算している

    • noise_suppressor.cc#519

FFT用の窓関数

• ハニングとフラットのハイブリッドが使用される

  • ApplyFilterBankWindow()

処理のスキップ

• 音声フレームのローバンドが、値が 0 のサンプルしか含んでいない場合には NoiseSuppressor::Analyze() でのノイズスペクトルの分析および更新はスキップされる

  • このケース（無音）で各種統計値を更新してしまうと、無音ではなくなった後のしばらくは、音声データのすべてが「スピーチ（ノイズ無し）」と判定されてしまうため

• 音声フレームが実際に使われることがない場合（ capture_output_used_ == false ）は、 NoiseSuppressor::Process() はフィルタの更新はするが、適用は行わない

  • フィルタの情報は、 NoiseSuppressor::Analyze() 呼び出しでも参照されているので、フィルタ更新までは必要

各種オプション

• libwebrtcには noise_suppression.level というオプションがあり、それによってノイズ抑制時の各処理で使用されるパラメーターが変化する

• 値は kLow or kModerate or kHigh or kVeryHigh

• 詳細は、以下のメソッドを参照のこと

  • AudioProcessingImpl::InitializeNoiseSuppressor()

  • SuppressionParams::SuppressionParams()

モバイル版エコーキャンセル

モバイル端末向けの軽量なエコーキャンセル処理

コード中では "AECM (acoustic echo control for mobile)" と呼称されている

概要

• AECM では、音声データの 入力時（capture） と 出力時（render） のそれぞれで処理が実行される

  • 用語としては「入力側（の音声フレーム）は nearend 」、「出力側（の音声フレーム）は farend 」と呼ばれる

• 全体の流れとしては、以下のようになる:

  1. [出力時] 実際に出力される音声フレームをバッファ（履歴）に保持しておく

  2. [入力時] 入力音声フレーム内のエコー部分に対応する出力済み音声フレームを特定する（遅延推定）

  3. [入力時] 上の遅延情報を用いて、エコー除去フィルタを適用する（ざっくりと言えば、入力音声から、対応する過去の出力音声成分を引く）

• AECM 向けのAPIを提供しているのは EchoControlMobileImpl クラス

  • 内部的には echo_control_mobile.h および aecm_core.h に存在する WebRtcAecm_* 関数群によって、実際の処理が実装されている

音声出力時の処理 (AudioProcessingImpl::ProcessRenderStreamLocked())

基本的には「実際に出力される音声フレームのコピーを、後続の入力時処理の際に参照できるようにバッファに保存」しているだけとなる

主な登場人物は、以下の 2 つ:

• EchoControlMobileImpl::PackRenderAudioBuffer() 関数

  • 出力音声フレームを AudioProcessingImpl クラスが管理している一時バッファに書き込む

  • モノラルチャネル かつ サンプリングレートが 16 kHz の場合には、単純なデータコピーとなる

  • マルチチャネル あるいは マルチバンド (サンプリングレートが 16 kHz 以上） の場合には、プラスアルファの処理が加わるので 補足 の節を参照のこと

• EchoControlMobileImpl::ProcessRenderAudio() メソッド

  • EchoControlMobileImpl が管理するリングバッファに EchoControlMobileImpl::PackRenderAudioBuffer() の結果を書き込むだけ

音声入力時の処理 (AudioProcessingImpl::ProcessCaptureStreamLocked())

関数の呼び出し階層としては、以下のようになっている:

- EchoControlMobileImpl::ProcessCaptureAudio()  # AudioProcessingImpl::ProcessCaptureStreamLocked()から呼び出されるメソッド
  - WebRtcAecm_Process()
    - WebRtcAecm_EstBufDelay()  # ここで推定した遅延情報はデバッグ用途でしか使用されていない
    - WebRtcAecm_ProcessFrame()
      - WebRtcAecm_BufferFarFrame()
      - WebRtcAecm_FetchFarFrame()
      - WebRtcAecm_ProcessBlock()  # 主要な処理はこの関数内で実施される
        - WebRtcAecm_UpdateFarHistory()
        - WebRtc_AddFarSpectrumFix()
        - WebRtc_DelayEstimatorProcessFix()
        - WebRtcAecm_AlignedFarend()
        - WebRtcAecm_CalcEnergies()
        - WebRtcAecm_CalcStepSize()
        - WebRtcAecm_UpdateChannel()
        - WebRtcAecm_CalcSuppressionGain()
        - ComfortNoise()

重要なのは WebRtcAecm_ProcessBlock() で、それより上の関数群は、基本的にはバッファ管理しか行っていないので、今回はあまり気にする必要はない。

WebRtcAecm_ProcessBlock() 関数のシグネチャは次の通り:

int WebRtcAecm_ProcessBlock(AecmCore* aecm,

                            // farend の音声フレーム (64 サンプル)
                            const int16_t* farend,

                            // nearend の音声フレーム (64 サンプル)
                            const int16_t* nearendNoisy,

                            // nearendNoisy から雑音を除いたもの
                            // 今回の用途では常に NULL になるので無視して良い
                            const int16_t* nearendClean,

                            // nearendNoisy に対してエコーキャンセルを適用した結果の格納先
                            // 今回の用途では nearendNoisy と同じポインタが使用される
                            int16_t* output)

WebRtcAecm_ProcessBlock() 関数の処理の大まかな流れは以下の通り:

1. farend 引数および nearendNoisy 引数に FFT を適用して周波数スペクトルに変換する ( TimeTofrequencyDomain() )

2. farend 引数の周波数スペクトルを aecm 引数が管理している履歴 (リングバッファ) に追記する ( WebRtcAecm_UpdateFarHistory() )

3. 上の履歴と nearendNoisy 引数の周波数スペクトルを照会して、出力音声（エコー）が入力音声に含まれるまでの遅延を推定する

   • WebRtc_AddFarSpectrumFix() および WebRtc_DelayEstimatorProcessFix()

   • この部分の詳細は 遅延推定 を参照

4. 推定遅延に対応する出力音声フレーム（スペクトル）を取得する ( WebRtc_AlignedFarend() )

   • これによって、現在の入力音声フレーム と そのエコー成分に対応する出力音声フレーム が得られたので、以後の処理ではこの 2 つのフレーム（のスペクトル）が使用される

5. エコーキャンセル用のフィルタ構築の前段として aecm が管理しているエコー音声チャネルを更新する

   • チャネル更新には NLMS というアルゴリズムを使用 ( Wikipedia: Normalizecd least squares filter (NLMS) )

   • 関連する関数は WebRtcAecm_CalcEnergies() と WebRtcAecm_CalcStepSize() 、 WebRtcAecm_UpdateChannel()

   • この部分の詳細は チャネル更新 を参照

6. 入力音声フレーム（スペクトル）にフィルタを適用して、エコー部分を除去する

   • フィルタには Wiener filter (Wikipedia) を使用

   • 基本的には「入力フレームから、ひとつ上で求めたエコーチャネル成分を除去する」イメージ

   • フィルタの強弱を調整するために WebRtcAecm_CalcSuppressionGain() でゲイン値（重み）が計算される

     • 入力とエコーのエナジーの差分をもとに、無音、ダブルトーク、等の簡易的な状況判定を行い、それに応じてゲイン値を決定

   • NLP (non-linear processor) でフィルタの値がさらに調整される

     • 外れ値の処理（大き過ぎる or 小さ過ぎるフィルタの値を 1 or 0 に丸める）等がここで行われる

7. コンフォートノイズを生成（ ComfortNoise() ）

   • オプショナルで、入力音声フレームにコンフォートノイズ（背景ノイズ）を生成する

   • デフォルトは無効

   • ノイズキャンセルの他の箇所の処理とはほぼ独立している

8. 処理適用後の入力音声フレーム（スペクトル）に逆FFTを適用して、時間波形に戻す

遅延推定

出力音声が入力音声に含まれるまでの遅延の推定は WebRtc_AddFarSpectrumFix() および WebRtc_DelayEstimatorProcessFix() で行われている:

• WebRtc_AddFarSpectrumFix(): 出力音声フレーム (farend) の形式変換と履歴への追加

  1. uint16_t[64] の形式で保持されている現在の出力音声フレーム（スペクトル）の中央部分を取り出して uint32_t （32 要素のビット配列）に変換する

     • 各周波数成分のこれまでの平均値を別途保持しており、それに比べて大きいなら 1 、小さいなら 0 となる

  2. 上のビット配列を、履歴配列の先頭に挿入する

     • 配列の要素数は 100 で、各要素は時系列順に並んでいる

     • 履歴配列の位置（インデックス）が遅延値に対応する（i.e., 先頭なら遅延なしで、末尾なら 400 ms 程度）

• WebRtc_DelayEstimatorProcessFix(): 遅延推定

  1. 現在の入力音声フレーム（スペクトル）を、上と同様の方法で uint32_t に変換する

  2. nearendの変換後のビット配列 と farendの履歴の各要素 の一致度を計測する

     • イメージ的には bitcount(nearend xor history[i]) といった処理で、値が小さいほど、より一致度が高いことを示す

  3. 別途管理している 履歴の各位置（= 遅延）での一致度の平均 を更新する

  4. 一致度の平均が最も高い位置を遅延のベスト候補とする

  5. その候補を採用できる条件が揃っている場合には、その遅延値を採用し、そうではない場合には前回の遅延値を使用する

     • e.g., ベスト候補とワースト候補の差が小さい場合には、不安定な状況だと判断して見送る

     • 条件の詳細については WebRtc_ProcessBinarySpectrum() のコードを参照のこと

チャネル更新

チャネル更新は WebRtcAecm_UpdateChannel() および、その前段の WebRtcAecm_CalcEnergies() と WebRtcAecm_CalcStepSize() によって実施される

これらの関数によって AecmCore 構造体が管理しているエコー音声用のチャネル情報が更新される

1. まずは、出力音声フレームのVADレベル（フラグ）を推定し、もしこれが 0 (エナジーが低く無音に近い) なら後続の処理はスキップする ( WebRtcAecm_CalcEnergies() )

2. 次に WebRtcAecm_CalcStepSize() で、 NLMS のステップサイズパラメーターである mu を計算する

3. 最後は WebRtcAecm_UpdateChannel() で、 NLMS を使ってエコーチャネルを更新する

• AecmCore は、毎フレームで更新される channelAdapt と、それよりは安定した channelStored をフィールドとして保持している

  • これらは出力音声フレーム（スペクトル）からエコー音声フレーム（スペクトル）を算出するための重み配列のようなもの (イメージとしては nearend_echo[i] = farend[i] * channelXXX[i])

• 入出力フレーム（スペクトル) の情報を使って、 channelAdapt を更新

• 十分なエナジーのフレームが一定数 (20個) 続いたら、 channelAdapt で channelStored の置換を試みる

  • channelAdapt と channelStored のそれぞれを用いて計算した「エコー音声フレームのエナジー」と「対応する入力音声フレームのエナジー」の差分（絶対値）を求める

  • その差分の20フレーム分の合計値が channelAdapt を使った場合の方が小さければ、より適切なものだと判断して channelStored を置換する (逆の場合には channelAdapt が置換される)

• 後続の処理では channelStored の値が使用される

バッファリングによる遅延

• 呼び出し階層の上と下で対象とする音声フレームのサンプル数は異なっている

  • 上の方（ EchoControlMobileImpl::ProcessCaptureAudio() ）では 160 サンプル（10ms分）

  • 下の方（ WebRtcAecm_ProcessBlock() ）では 64 サンプル

• そのため入力音声フレームは、まずリングバッファに追記され、 WebRtcAecm_ProcessBlock() 呼び出しの際には、そこから 64 サンプルずつ取り出されて処理されることになる

• その際にキリが悪かったサンプル群は次回の入力音声処理時に持ち越されることになるので、 32 サンプル分（2ms分）の遅延が発生する

計算量特性

典型的には、一つの音声フレームを処理する際には、以下の関数群が1回ずつ呼び出されることになる:

• EchoControlMobileImpl::PackRenderAudioBuffer()

• EchoControlMobileImpl::ProcessRenderAudio()

• EchoControlMobileImpl::ProcessCaptureAudio()

それぞれに対して、以下の処理が、チャネル数の二乗分だけ繰り返されることになる（ マルチチャネルの扱い ）:

• EchoControlMobileImpl::PackRenderAudioBuffer() および EchoControlMobileImpl::ProcessRenderAudio()

  • 一フレーム分のメモリコピー

• EchoControlMobileImpl::ProcessCaptureAudio()

  • 一フレーム分の FFT と 逆FFT

  • フレーム単位のメモリコピーやループを十数回～数十回

注意: 一フレームに含まれる具体的なサンプル数は、関数によって 160 あるいは 64 と変動するが、ここでは簡単のためにそれらの違いは考慮しないものとする

補足

マルチチャネルの扱い

• 各チャネルは、一番下のレイヤー（ WebRtcAecm_ProcessBlock() ）では独立して処理される

• 上のレイヤー（ EchoControlMobileImpl::ProcessCaptureAudio() ）では、以下のような処理される

  • 入力音声フレームのチャネル数 の他に、 出力音声フレームのチャネル数 の概念がある

    • 後者はソースコード中では reverse_channel と呼称されている

    • EchoControlMobileImpl クラスの初期化時には、 WebRtcAecm_ProcessBlock() に渡される Aecm 構造値インスタンスは 入力音声フレームチャネル数 * 出力音声フレームチャネル数 個だけ生成される（おそらく典型的にはチャネル数の二乗となる）

  • 入力音声フレームの各チャネルの処理は、イメージとしては次のようになる（ EchoControlMobileImpl::ProcessCaptureAudio()#L173 ）

    1. 入力音声フレームから該当チャネル部分のデータを取得する (nearend)

    2. 出力音声フレームの各チャネルデータ（farend）に対して for ループを回す（ EchoControlMobileImpl::ProcessCaptureAudio()#L198 ）

       • nearend と farend を引数として WebRtcAecm_Process() 経由で WebRtcAecm_ProcessBlock() を呼び出す

       • 次のイテレーションに進む前に nearend のデータは、ノイズキャンセル結果で置換される

  • つまりざっくりと言えば、チャネル数に対する二重ループを回して、各入力チャネルから各出力チャネルのエコー成分を順々に取り除いている感じとなる

マルチバンドの扱い

• マルチバンド自体については 音声フレーム を参照

• 音声フレームがマルチバンドに分割された際には、一番下のバンドのみが処理され、残りのバンドについては 0 で埋められる（ローパス）

  • EchoControlMobileImpl::ProcessCaptureAudio()#L216

各種オプション

• ルーティングモードの指定 ( RoutingMode )

  • kQuietEarpieceOrHeadset, kEarpiece, kLoudEarpiece, kSpeakerphone, kLoudSpeakerphone の中から選べる

  • この値によって、エコーキャンセル処理時の各種パラメーターが変化する

  • デフォルト値は kSpeakerphone

• NLP の ON/OFF ( AecmCore::nlpFlag 、デフォルトは有効)

• コンフォートノイズの ON/OFF ( EchoControlMobileImpl::comfort_noise_enabled_ 、デフォルトは無効)

オートゲインコントロール（AGC）

出力音量レベルを適切な範囲内で一定に保つための処理

libwebrtc には「無印の AGC (ないし AGC1）」と「AGC2」が存在するが、ここでは前者を扱っている（後者については補足節を参照のこと）

概要

• libwebrtc で、入力音声フレームに AGC を適用する際の論理的な流れは、以下のようになっている:

  1. 適切な入力音量レベルを推定（e.g., 入力音声フレームでクリッピングが発生しているならレベルを下げる）

  2. 上で求めた適切な音量レベルに基づいて、音声フレームの全体音量レベルを変更

  3. 音声フレーム内での音量の均一化

• また、一番上の階層での構成要素としては、以下の 3 つのクラスが存在する:

  • GainControlImpl: 上述の三つの処理のすべてを担当できるクラス（後述のモードに応じて、一部処理を他のクラスに委譲する）

  • AgcManagerDirect: 「適切な音量レベルの推定」に特化した処理を担当するクラス（オプショナル）

  • CaptureLevelAdjuster: 「全体音量レベルの変更」に特化した処理を担当するクラス（オプショナル）

• これらのクラスの使い分けは GainControlImpl に指定される三つのモードによって説明できる:

  • モードは AudioProcessing::GainController1::Mode 列挙型によって定義され、 kAdaptiveAnalog 、 kAdaptiveDigital 、 kFixedDigital のいずれかとなる

  • kAdaptiveAnalog の場合:

    • このモードでは「アナログ（マイク）音量が制御できる」という想定のもとでゲインコントールが行われる

      • "Adaptive" は「適切な音量レベル推定」と、それに応じた「全体音量レベルの変更」が行われることを示す

    • この場合は GainControlImpl が「適切な音量レベルの推定」と「フレーム内での音量均一化」の両方を実施する

    • CaptureLevelAdjuster が有効な場合には、 このクラスが「全体音量レベルの変更」（適切な音量レベルの反映）を行う

      • CaptureLevelAdjuster は、入力マイクの音量調整の挙動をエミューレートするためのクラス

    • CaptureLevelAdjuster が無効な場合には、入力音量レベルの調整は libwebrtc の音声処理機能の利用側の責任となる

      • AudioProcessing::recommended_stream_analog_level() メソッドで、期待される音量レベルは取得できる

  • kAdaptiveDigital の場合:

    • このモードでは「アナログ（マイク）音量は制御できない」という想定のもとでゲインコントールが行われる

    • GainControlImpl の役割は、基本的には kAdaptiveAnalog の場合と同様だが、「全体音量レベルの変更」まで一緒に行ってしまう点が異なる

      • アナログ音量調整を利用側に任せることができないので、自分で入力音声フレームに手を入れて、音量調整をしてしまう

      • そのため GainControlImpl が一番多くのことを行うモードとなる

  • kFixedDigital の場合:

    • このモードでは GainControlImpl は「適切な音量レベルの推定」と「全体音量レベルの変更」に関する処理を行わなくなる

      • 「フレーム内での音量均一化」のみを担当

    • 「適切な音量レベルの推定」に関しては、 AgcManagerDirect が代わりに担当する（有効になっている場合）

      • AgcManagerDirect と GainControlImpl を併用する場合は、常にこのモードとなる

    • 「全体音量レベルの変更」に関しては、 kAdaptiveAnalog の場合と同様（ CaptureLevelAdjuster が有効ならそれが使用され、無効なら利用者責任）

    • なお列挙的のコメントを意訳すると「組み込みデバイスなどで、入力音量レベルが予測できる（i.e., 事前に適切なゲインが判明している）場合には、全体音量レベル推定および変更処理そのものを省略できる」とのこと

• 今回は簡単のために、基本的には、以下の構成を想定して説明を行うこととする:

  • GainControlImpl に指定されるモードは kFixedDigital

  • AgcManagerDirect は有効

  • CaptureLevelAdjuster は無効（このクラスの役割は「物理マイク音量のエミューレート」で、厳密には AGC とは独立した処理であるため）

• GainControlImpl と AgcManagerDirect は、それぞれ Analyze と Process フェーズが存在する

  • 前者は、他の音声処理が適用される前に実施されて、（極力）生の入力音声フレームから、各種情報が収集される

  • 音声フレーム処理の入り口となる AudioProcessingImpl::ProcessCaptureStreamLocked() メソッドの中では、以下の順番で適用されている:

    1. AgcManagerDirect の Analyze （ AgcManagerDirect::AnalyzePreProcess() メソッド）

    2. GainControlImpl の Analyze （ GainControlImpl::AnalyzeCaptureAudio() メソッド）

    3. AgcManagerDirect の Process （ AgcManagerDirect::Process() メソッド）

    4. GainControlImpl の Process （ GainControlImpl::ProcessCaptureAudio() メソッド）

• 以降のサブセクションでは、上記のメソッドそれぞれの詳細について記載する

AgcManagerDirect の Analyze （ AgcManagerDirect::AnalyzePreProcess() メソッド）

このメソッドが行なっていることは、主に以下の 2 つ:

1. 入力音声フレームのクリッピング判定

   • クリッピング判定 = 大音量領域での音声の欠損が発生するかどうか (c.f. Audio Clipping (Wikipedia))

   • クリッピングが発生する場合には、入力音量レベルを下げる必要がある

     • 上述の通り、実際に音量レベルを変更するのは、このクラスの呼び出し側の責務（ AgcManagerDirect は適切なレベルを推定するのみ）

2. 「代表チャネル」を更新する

   • 「代表チャネル」は、ゲインコントロールの際の基準となるチャネル

   • 「適切な音量レベルの推定」はチャネル毎に独立して行われるが、実際に音量調整をする際には、代表チャネルの値が使用される

   • 代表チャネルは AgcManagerDirect::AnalyzePreProcess() メソッドによって選択される

     • 実装的には、単純に「適切な音量レベル」が一番小さなチャネルを選択しているだけ

このメソッドの大半はクリッピング関連処理に費やされている。

また、オプショナルな構成要素として ClippingPredictor クラスが存在する。 これが有効となっている場合には「現在のフレームにクリッピングが存在するかどうか」の判定だけでなく、 「近い将来に発生しそうかどうか」の予測まで行われるようになる。 ただし、今回は簡単のために、このクラスの詳細は割愛し、無効となっているものと想定する。

クリッピング判定処理の流れは次の通り:

1. 入力音声フレームで、値が上端ないし下端に達しているサンプルの割合を計算（ AgcManagerDirect::ComputeClippedRatio() ）

   • これが規定値（デフォルトでは一割）を超えている場合には「クリッピング有り」と判定される

2. 「クリッピング有り」判定、かつ、前回の判定から一定時間（デフォルトでは 3 秒）経過している場合には、以下を実施する:

   • 各チャネルに対して MonoAgc::HandleClipping() を呼び出す

   • MonoAgc は、各チャネルに対して独立に「適切な音量レベルの推定」処理を適用するためのクラス

   • MonoAgc::HandleClipping() の中では（ざっくり言えば）推定適切音量レベルの定数分の減少が行われる

GainControlImpl の Analyze （ GainControlImpl::AnalyzeCaptureAudio() メソッド）

このメソッドの中では主に、以下が実施される:

• 入力音声フレームのエナジーなどの統計情報の取得（モードが kFixedDigital 以外の場合）

  • 取得した値は Process フェーズで利用される

• 入力音声フレームの「全体音量レベルの変更」（モードが kAdaptiveDigital の場合）

モード毎に適用される処理の概要は以下の通り:

• kAdaptiveAnalog の場合:

  • 以下の処理を行う WebRtcAgc_AddMic() 関数をチャネル毎に適用:

    1. 入力音量レベルが小さすぎる場合には、入力フレームの各サンプルに一律のゲイン値を適用して調整（増幅）

       • 一フレームで適用されるゲイン値には上限がり、複数フレームを跨いで徐々に大きくすることで、ターゲット音量に近づけていく

    2. 入力フレームのバンド 0 部分を数 ms 間隔に区切って、それぞれのエナジーとエンベロープ（ Envelope (Wikipedia) ）を計算

    3. 最後に WebRtcAgc_ProcessVad() 関数を使って、入力音声フレームにスピーチが含まれているかどうかの情報を取得

       • VAD 判定自体は簡易的なもの

       • ざっくりと言えば「現在のフレームのエナジー」と「長期的なエナジーの統計（平均と標準偏差）」を比較して、前者が十分に高ければ「ボイスが含まれている」と判定

• kAdaptiveDigital の場合:

  • 以下の処理を行う WebRtcAgc_VirtualMic() 関数をチャネル毎に適用:

    1. 入力音声フレームのバンド 0 を対象として、エナジーを計算して lowLevelSignal かどうかを判定

    2. 入力音量フレームの音量レベルが「適切な音量レベル」に合うように、一律のゲイン値を適用する（全体音量を上げる or 下げる）

       • 「全体音量レベルの変更」を行なっている箇所

       • 調整結果に応じて「現在の入力音声レベル」の値も修正する

       • 「適切な音量レベル」を求めること自体は Process フェーズで行われる

    3. 最後に WebRtcAgc_AddMic() 関数を呼び出す

       • つまり前処理を除けば kAdaptiveAnalog と同じとなる

• kFixedDigital の場合:

  • 特に何も行わない

AgcManagerDirect の Process （ AgcManagerDirect::Process() メソッド）

このメソッドでは、主に以下が行われる:

• 「適切な全体音量レベル」の推定

• 「 後続の GainControlImpl クラスの Process フェーズで使用されるゲイン値（"compression gain"）」の算出

大まかな処理の流れは次の通り:

1. 入力音声フレームのバンド 0 に対して Agc::Process() メソッドを呼び出す

   • 内部ではまず VoiceActivityDetector::ProcessChunk() を使って、細かいチャンク単位（数ms単位）でのボイス確率と RMS を求めている

     • RMS は "Root Mean Square" の略で、音圧に近い指標

   • その後、その二つの値を LoudnessHistogram::Update() を使って、ヒストグラムに格納している（RMS に対応するボイス確立を保持）

2. 上の結果を使って MonoAgc::UpdateGain() メソッドで「適切な音量レベル」を更新する

   • RMS のヒストグラムから、現在の loudness を求め、それをターゲットとする loudness と比較する

   • 現在とターゲットの loudness の差から、デジタルゲインコントールのゲイン値（対象となる調整量）を求める

   • デジタルゲインコントールで調整できる範囲を超えている場合には、その超過分を（物理マイク or エミューレートマイクでの）アナログ調整でカバーするために「適切な音量レベル」の値を更新する

3. 次に MonoAgc::UpdateCompressor() で「デジタルゲインコントロールで使用されるゲイン値」を更新する

   • 一つ上で求めたデジタルゲインコントロールのゲイン値をそのまま適用すると、音量が急変してしまう可能性があるので、徐々にターゲットに近づくように、ゲイン値を調整する

   • 調整後のゲイン値は GainControlImpl::set_compression_gain_db() 経由でデジタルゲインコントロールに渡される

     • ただし現在の実装では WebRTC-UseLegacyDigitalGainApplier フラグが有効になっていないと、この値は使用されない（のであまり気にしなくても良い）

4. 最後は、Analyze フェーズと同様に AgcManagerDirect::AggregateChannelLevels() メソッドを用いた代表チャネルが選出される

GainControlImpl の Process （ GainControlImpl::ProcessCaptureAudio() メソッド）

このメソッドでは、主に以下が行われる:

• 「入力音声フレーム内の音量の均一化」

  • 参考までに analog_processing.h ファイル内のコメントでは、この処理は次のように説明されている

    It applies a fixed gain through most of the input level range, and compresses (gradually reduces gain with increasing level) the input signal at higher levels.

• 「適切な入力音声レベル」の推定（モードが kFixedDigital 以外の場合）

大まかな処理の流れは次の通り:

1. WebRtcAgc_Analyze() 関数を呼び出して「適用するゲイン配列」と「適切な入力音声レベル」を計算

   • 内部的には WebRtcAgc_ComputeDigitalGains() 関数と WebRtcAgc_ProcessAnalog() 関数を使用している

   • WebRtcAgc_ComputeDigitalGains() 関数は「適用するゲイン配列」を求める

     • ゲイン配列は 11 要素: 音声フレームの 1ms 毎のゲイン値（10個） + 次のフレームの冒頭部分のゲイン値（1個）

     • この関数は、入力音声フレームの VAD や各区間（1ms単位）のエナジーの情報を使って、それぞれの区間に適用するゲイン値を求める

   • WebRtcAgc_ProcessAnalog() では「適切な入力音声レベル」を求めている（音声フレームの更新は、ここでは行わない）

     • かなり色々なヒューリスティックを用いて、期待されるアナログ音量レベルを決定しているので、詳細は実装を参照のこと

       • 入力音声フレームの saturation や VAD を判定したり、 etc

     • なお、この関数は以下のいずれかの条件に該当する場合には呼び出されない:

       • モードが kFixedDigital

         • GainControlImpl が感知する範囲では「入力音声レベルの変更」が行われないため、「適切な入力音声レベル」を求めることが不要なため

       • モードが kAdaptiveDigital かつ Analyze フェーズで求めた lowLevelSignal フラグが真

         • lowLevelSignal の判定箇所には "digital AGC will not adapt to low-level signals" という記載があるので、それをチェックしているものと思われる

2. ゲイン配列の適用

   • ApplyDigitalGain() 関数を用いて、上で求めたゲイン配列を入力音声フレームに適用する

   • 基本的には、入力音声フレームの各サンプルにゲイン値を掛けているだけの単純な関数

   • 1ms 区間の区切りで不自然にならないように、ゲイン値を徐々に調整していく、などの補助的な処理がいくつか入っている

3. 「適切な入力音声レベル」の更新（モードが kAdaptiveAnalog の場合のみ）

   • アナログマイク（ないしエミューレートされたマイク）による音量変更用に、チャネル毎に求めた「適切な入力音声レベル」から代表値を選択する

   • 行なっていることとしては、上述の AgcManagerDirect::AggregateChannelLevels() と同様（最小値を選択しているだけ）

補足

マルチチャネルの扱い

• 基本的には各チャネルは独立して扱われる（特に分析系の処理では）

• ただし、最終的に音量調整を行う際には、一番音量レベルが小さいチャネルを代表チャネルとして、それを基準として処理が適用される

マルチバンドの扱い

• 以下の処理は、入力音声フレームがマルチバンドに分割される前に適用される:

  • CaptureLevelAdjuster による入力音声フレームの音量調整

  • AgcManagerDirect の Analyze （ AgcManagerDirect::AnalyzePreProcess() メソッド）

• 入力音声フレームの分析・情報収集の際には、バンド 0 が対象となることが多い

バッファリングによる遅延

バッファリングを行なっていないので、それに伴う遅延も特になし

計算量特性

他の音声処理の多くと同様の傾向:

• 入力音声フレームの走査やコピーが十数回から数十回程度行われる

• 他の音声処理の多くとは異なり FFT を行なっていないのは特徴的

AGC2 について

ここで取り上げているのは AGC1 （ないし無印の AGC ）と呼ばれるもので、 libwebrtc にはそれとは別に AGC2 も存在する （ GainController2 クラス）。

AGC1 と AGC2 は排他的なものではなく、両方を併用することも可能な模様。 例えば、 audio_processing.h ファイルに掲載されている example コードには、以下のような記載があり、両方が有効化されている:

AudioProcessing::Config config;
// ..省略..

// AGC1 を有効化
config.gain_controller1.enabled = true;
config.gain_controller1.mode =
AudioProcessing::Config::GainController1::kAdaptiveAnalog;
config.gain_controller1.analog_level_minimum = 0;
config.gain_controller1.analog_level_maximum = 255;

// AGC2 を有効化
config.gain_controller2.enabled = true;

また Chromium （利用側）の media/webrtc/helpers.cc ファイルにある ConfigureAutomaticGainControl() 関数で ゲインコントロールを設定している箇所を見ても AGC1 と AGC2 が併用されるようなコードとなっている。 ただし AGC2 については features::kWebRtcAnalogAgcClippingControl というフラグが有効になっている場合にのみ利用され、 AGC1 と異なり単体で使われることはない。

各種オプション

• 一番挙動に大きな影響を与えるのは、おそらく AudioProcessing::GainController1::Mode の値

• それ以外にもパラメーターはたくさんあるがここでは割愛

  • 設定できる項目については AudioProcessing::GainController1 構造体にまとまっている

libwebrtc リップシンク

注意

この資料の正確性を保証しません。

重要

この資料についての問い合わせは Sora のサポート範囲には含まれません。

この資料は libwebrtc M99 (4844) 時点の資料です。

ここでは libwebrtc でのリップシンク処理（映像および音声ストリームのタイムスタンプ同期処理）について記載しています。

概要

• 同期処理は、主に以下の 3 つのパートで構成される:

  1. 映像・音声ストリームから同期用の情報（主にパケットのタイムスタンプ）を取得部分

  2. 映像・音声ストリームを同期するために必要な遅延時間の計算部分

     • 片方が遅れている場合には、進んでいる方のストリームに対して遅延を課してタイミングを合わせるイメージ

  3. 上で求めた同期用の遅延時間のストリームへの反映部分

• RtpStreamsSynchronizer がこのような同期処理のハブとなるクラス

  • 上述の 1 と 3 については、映像・音声ストリームと情報のやり取りが必要になるが、それは Syncable という抽象クラスを通して行われる

    • 映像では VideoReceiveStream2 が、音声では AudioReceiveStream が、 Syncable の実装クラスとなる

    • RtpStreamsSynchronizer はこれらのインスタンスをメンバ変数として保持しており、必要に応じてストリームの情報を取得したり、同期結果（必要な遅延）を伝えたりする

  • また RtpStreamsSynchronizer は StreamSynchronization というクラスのインスタンスも保持している

    • こちらは実際のストリームとは切り離された、同期処理用の計算部分を担っているクラス（上述の 2 を担当）

  • RtpStreamsSynchronizer は RtpStreamsSynchronizer::UpdateDelay() メソッドを定期的（一秒毎）に呼び出し、その中で上の 1..3 の処理を実施している

以降では、上の三つのパートのそれぞれについて記載していく。

詳細

同期用の情報取得

RtpStreamsSynchronizer クラスは Syncable::GetInfo() メソッドを経由して、同期に必要な各種情報を取得する。

Syncable::GetInfo() メソッドは、以下の定義の Syncable::Info 構造体を返す:

struct Info {
  // 最後に RTP パケットを受信した時のシステム時刻
  int64_t latest_receive_time_ms = 0;

  // 最後に受信した RTP パケットのタイムスタンプ
  uint32_t latest_received_capture_timestamp = 0;

  // RTCP Sender Report パケットから取得した情報
  uint32_t capture_time_ntp_secs = 0;  // NTP 時刻の秒部分
  uint32_t capture_time_ntp_frac = 0;  // NTP 時刻の秒未満部分
  uint32_t capture_time_source_clock = 0;  // RTP タイムスタンプ

  // ストリームの現在の遅延時間
  //
  // 正確ではないが、イメージとしては「`RtpStreamsSynchronizer`が前回に求めた遅延時間（を反映した値）」が近い
  int current_delay_ms = 0;
};

概要部分に記載の通り、映像と音声では Syncable の実装クラスは別々だが、どちらも似たような方法で RTP / RTCP パケット受信時の情報をほぼそのまま使って、この構造体に必要な情報を埋めている。

current_delay_ms だけは若干特殊だが、ここではこの値の求め方の詳細は割愛する。

同期に必要な遅延の計算

映像ストリームと音声ストリームのタイムスタンプの同期は「片方がもう片方に対して、どの程度遅延しているか」ということを求めることで行われる。

この遅延計算を担当しているのは RtpStreamsSynchronizer::UpdateDelay() メソッドで、流れは以下のようになっている:

1. 前節に記載の Syncable::GetInfo() を使って、映像と音声のそれぞれで Syncable::Info 構造体を取得する

2. Syncable::Info を使って、映像および音声用の StreamSynchronization::Measurements メンバ変数を更新する

   • StreamSynchronization::Measurements は「RTP タイムスタンプの NTP ドメインへの変換」を行うためのクラス

   • このクラスは RtpToNtpEstimator というクラスのインスタンスを保持している

     • RtpToNtpEstimator::UpdateMeasurements() は Syncable::Info の RTCP Sender Report (SR) 関連の情報を受け取り、それらを 20 個分保持している

     • RtpToNtpEstimator::Estimate() では、その履歴情報を使って（線形回帰で）求めたパラメーターを用いて、 RTP タイムスタンプから NTP タイムスタンプへの変換を行う

3. 更新された映像および音声用の StreamSynchronization::Measurements を引数にして StreamSynchronization::ComputeRelativeDelay() メソッドを呼び出す

   • このメソッドは「音声ストリームが映像ストリームに対して、どの程度遅れているか（or 進んでいるか）」を結果として返す

4. 次に StreamSynchronization::ComputeDelays() を呼び出して「ストリームを同期するために映像と音声のそれぞれをどの程度遅延させるべきか」を計算する

5. 最後は Syncable::SetMinimumPlayoutDelay() を用いて、計算した同期用の遅延値を映像と音声ストリームのそれぞれに反映する

   • このメソッドの詳細については、次の節を参照

ComputeRelativeDelay() と ComputeDelays() の詳細

StreamSynchronization::ComputeRelativeDelay() のシグネチャは以下のようになっている:

bool StreamSynchronization::ComputeRelativeDelay(
    const Measurements& audio_measurement,  // 音声用の StreamSynchronization::Measurements
    const Measurements& video_measurement,  // 映像用の StreamSynchronization::Measurements
    int* relative_delay_ms) // 音声を基準にした、映像の遅延時間（音声の方が遅れている場合には負の値になる）

メソッド内で行われていることは単純で次の通り:

• RtpToNtpEstimator::Estimate() メソッドを使って、最後に受信した RTP パケットのタイムスタンプを NTP ドメインに変換する（映像と音声のそれぞれ）

• 次の式で relative_delay_ms の値を計算する:

  • (映像パケット受信システム時刻 - 音声パケット受信システム時刻) - (映像パケット NTP 時刻 - 音声パケット NTP 時刻)

StreamSynchronization::ComputeDelays() の方はもう少し複雑で、シグネチャは以下のようになっている:

bool StreamSynchronization::ComputeDelays(
    int relative_delay_ms,            // 上で求めた`relative_delay_ms`の値（i.e., 音声に対する映像の遅延時間）
    int current_audio_delay_ms,       // 音声の現在の遅延時間 (`Info.current_delay_ms`）
    int* total_audio_delay_target_ms, // 音声用の同期用遅延時間（初期値は 0）
    int* total_video_delay_target_ms) // 映像用の同期用遅延時間（初期値は映像の現在の遅延時間=`Info.current_delay_ms`）

この関数は、大まかには以下のようなことを行なっている:

1. 映像の現在の遅延 - 音声の現在の遅延 + relative_delay_ms という式で映像と音声の遅延のズレを算出

   • この結果は、過去四回分が保持されており、以降ではその平均値が使用される

2. 上の結果が 30 ms 未満なら、許容範囲ということで、ここで処理は終了

   • 次節に記載の同期用遅延の反映処理もスキップされる

3. 急激な遅延調整を防ぐために、上で求めた「ズレの平均値」の値を調整する

   • 二で割った後に、±80 ms の範囲に収まるようにmin/max を取る

   • 結果は diff_ms という変数に格納する

4. diff_ms が正の場合:

   • 映像の方が遅れている（遅延時間が長い）ので 映像の遅延を減らす か 音声の遅延を増やす 必要がある

   • 別途設定された「基準となるターゲット遅延時間」よりも映像の遅延時間が長い場合には、映像の遅延時間を diff_ms 分だけ減らす

     • かつ、音声の遅延時間を「基準となるターゲット遅延時間」にリセットする

     • 注釈:

       • 「基準となるターゲット遅延時間」は StreamSynchronization::SetTargetBufferingDelay() メソッドによって設定される

       • ただし通常はデフォルト値である 0 が使用されるように見える

   • 「基準となるターゲット遅延時間」よりも映像の遅延時間が短い場合には、音声の遅延時間を diff_ms 分だけ増やす

     • かつ、映像の遅延時間を「基準となるターゲット遅延時間」にリセットする

5. diff_ms が負の場合:

   • 音声の方が遅れている（遅延時間が長い）ので 音声の遅延を減らす か 映像の遅延を増やす 必要がある

   • 映像と音声が逆転している以外はひとつ前のステップで行なっていることと同じなので、詳細は割愛する

6. ここまでで計算した映像の遅延時間が「基準となるターゲット遅延時間」を超えている場合には、その値を結果に採用する

   • そうではない場合には、前回の映像遅延時間をそのまま採用する

   • なお、遅延時間は 10 秒を超えないように min を取る

   • この値が total_video_delay_target_ms に格納されて呼び出し元に伝えられる

7. 映像で前回の遅延時間が採用されなかった場合には、音声の方の遅延時間を更新する

   • 一度のメソッド呼び出しで更新されるの映像か音声のどちらか一つの遅延時間のみ

   • それ以外は映像の場合の処理と同様

   • この値が total_audio_delay_target_ms に格納されて呼び出し元に伝えられる

同期用遅延の反映

前節で計算された「映像と音声を同期させるために必要なそれぞれの遅延時間」は Syncable::SetMinimumPlayoutDelay() メソッドを通して、 それぞれのストリームに伝達され処理されることになる。

以降では、映像と音声のそれぞれについて、サブセクションに分けて概要を記載していく。

なお、メソッド名に含まれる "PlayoutDelay" という用語については、以下のドキュメントも参考になる:

• https://webrtc.googlesource.com/src/+/refs/heads/main/docs/native-code/rtp-hdrext/playout-delay/README.md

映像の場合

• 映像の Syncable 実装は VideoReceiveStream2 クラスで行われているので VideoReceiveStream2::SetMinimumPlayoutDelay() メソッドがエントリポイントとなる

  • このメソッドの内部では（細々とした調整処理を経て） VCMTiming::set_min_playout_delay() にターゲット遅延値が渡される

  • 映像の遅延関連処理はこの VCMTiming クラスに集約されている

    • 同期用の遅延以外にも jitter, render, composition, etc の遅延がこのクラスで管理されている

• 上述の VCMTiming インスタンスへの参照は、 VideoReceiveStream2 以外にも複数箇所で共有されている

  • その内の一つが FrameBufferProxy であり、同期遅延の反映処理は、このクラスで行われている

  • FrameBufferProxy は設定によっていくつか別のクラスに処理を委譲することになる

    • 例えば FrameBuffer2Proxy が使われる場合には、 VCMTiming への参照は、さらに FrameBuffer クラスに渡されて、処理されることになる

    • 以降では、この FrameBuffer での挙動を見ていく

• VCMTiming に保持された同期用の遅延時間は、以下のメソッドの中で参照されている:

  • VCMTiming::TargetVideoDelay():「同期用遅延時間」と「jitter, decode, render 遅延の合計時間」を比較し、大きい方を返すメソッド

  • VCMTiming::RenderTime(): 「フレームのタイムスタンプ」を入力として受け取り、それを描画すべきタイムスタンプを返すメソッド

    • その際に「現在の遅延時間」を加味するが、その現在値が同期用の遅延時間の範囲内に収まるように min/max を取っている

  • VCMTiming::MaxWaitingTime(): 「デコーダに次のフレームを渡すまでの待機時間」を計算するメソッド

    • 同期用の遅延時間が 0 の場合（かつ、その他の条件が整った場合）には、特別な計算が実施される

  • この中の最初の二つのメソッドは FrameBuffer::GetNextFrame() メソッド、最後の一つは FrameBuffer::FindNextFrame() の中で使用されている

• FrameBuffer::FindNextFrame() は「次にデコードするフレーム」と「デコードまでの待機時間」を決定するためのメソッド

  • この中で VCMTiming::RenderTime() を使ってフレームの描画時刻が決定される（まだ未定だった場合）

  • その次に VCMTiming::MaxWaitingTime() を呼び出して、そのフレームをデコーダに渡すまでの待機時間が決定される

    • もしその待機時間が負数（正確には -5ms 未満）だった場合には、そのフレームはドロップされる

• FrameBuffer::GetNextFrame() は上で準備したフレームを、デコード時間になったら、実際に取得するメソッド

  • 対象フレームの描画時刻は FrameHasBadRenderTiming() 関数を使ってチェックされる

    • このメソッドに VCMTiming::TargetVideoDelay() の値も渡される

    • ざっくり言えば、タイムスタンプの値が負数だったり、遅延時間が 10 秒を超えている場合に "Bad" と判定される

    • その場合には VCMTiming::reset() を呼び出して状態をリセットした上で、再度 VCMTiming::RenderTime() を使って描画時刻が計算される

音声の場合

• 音声の Syncable 実装は AudioReceiveStream クラスで行われているので AudioReceiveStream::SetMinimumPlayoutDelay() メソッドがエントリポイントとなる

  • その後、以下のメソッド群の呼び出し通じて値が（ほぼそのまま）伝播する:

    1. ChannelReceiveInterface::SetMinimumPlayoutDelay()

    2. AcmReceiver::SetMinimumDelay()

    3. NetEq::SetMinimumDelay()

    4. NetEqController::SetMinimumDelay()

    5. DelayManager::SetMinimumDelay()

• DelayManager::SetMinimumDelay() に渡された遅延時間は DelayManager::Update() メソッドの中で参照される

  • これは「RTP パケットのタイムスタンプ」を入力に受け取り、内部の統計情報等を更新した上で、パケットの遅延時間を返すメソッド

  • このメソッド呼び出し時には、他のクラスから参照される「ターゲット遅延時間」の値も更新される

    • このターゲット遅延時間の値は DelayManager::TargetDelayMs() 経由で取得できる

    • DelayManager::TargetDelayMs() の返り値と DelayManager::SetMinimumDelay() に渡された値は、必ずしも一致する訳ではない

      • ただし、大枠を理解する上では「おおむね同じもの」と考えてしまってもそこまで問題はない

• DelayManager::TargetDelayMs() は DecisionLogic クラスの色々な箇所で呼び出されている

  • その中でも DecisionLogic::GetDecision() がおそらく一番重要

  • DecisionLogic::GetDecision() は最後に受け取ったパケットやジッタバッファの情報を使って、次に行うべき操作を指示する NetEq::Operation 列挙型を返す

  • 操作決定の際には DelayManager::TargetDelayMs() の値も考慮し、それに応じて Operation::kAccelerate (再生時間を早める） や Operation::kExpand (再生時間を遅らせる）を指示してペース調整が行われる

  • なお NetEq クラスについては以下のリンクも参考になる:

    • https://chromium.googlesource.com/external/webrtc/+/master/modules/audio_coding/neteq/g3doc/index.md

libwebrtc ペーサー

注意

この資料の正確性を保証しません。

重要

この資料についての問い合わせは Sora のサポート範囲には含まれません。

この資料は libwebrtc M104 (5112) 時点の資料です。

このドキュメントでは libwebrtc でのペーサーの処理について記載しています。 ペーサーは「RTP パケットの送信ペースを調整し、指定されたビットレート要求を満たすようにする」役目を担っているコンポーネントです。

なおペーサー関連の話の大枠については、libwebrtc のリポジトリで提供されている Paced Sending というドキュメントによくまとまっているので、 理解を深めるためには、そちらに先に目を通しておくことをお勧めします。

注釈

今回取り上げているクラスは、2022 年 7 月現在でも継続的に修正が行われています。 そのため、今後の libwebrtc のバージョン更新に伴い、処理内容が変わる可能性は十分にあり得ます。

概要

• ペーサー関連のコードは webrtc/src/modules/pacing/ ディレクトリ以下にまとまっている

• その中でペース調整ロジックを提供している中心的なクラスは PacingController:

  • 新規に送信される RTP パケットは PacingController::EnqueuePacket() に渡され、一度キューイングされる

  • その後、 PacingController::ProcessPackets() 呼び出しタイミングで、指定されたターゲットビットレート要求を満たすペースで実際のパケット送信が行われる

  • ターゲットビットレートは PacingController::SetPacingRates() によって、このクラスの外から指定される

• PacingController のペース制御アルゴリズムは リーキーバケット に基づいている

  • リーキーバケットとは「穴の空いたバケツ」のこと

  • このアルゴリズムでは、水の流量（= パケットの送信ペース）は、バケツ内の水の容量（= キュー内のパケットの合計サイズ）には左右されず、その穴の大きさ（= 指定ビットレート）によって制御されることになる

  • PacingController は「送信済みパケットサイズ」および「経過時間」、「ターゲットビットレート」をもとに「バジェット（現在の送信可能サイズ）」を計算し、その範囲内でパケットの送信を行う

• デフォルトでは、音声パケットはペース調整の対象外となっており、常に即座に送信される

• RTP パケットには、その種類に応じた優先度が設定されている:

  • バジェットに余裕ができた際には、優先度が高いパケットから先にキューから取り出されて送信される

    • 優先度が同じパケットを含む複数のストリームがある場合にはラウンドロビン

  • パケットの種類に応じた優先度は以下の通り:

    1. 音声パケット

    2. 再送パケット

    3. 映像ないし FEC パケット

    4. パディングパケット（キープアライブや後述のプローブ用途で使用される）

  • この優先順位（と音声の特別扱い）に照らし合わせて、ペーサーの役割を端的に表現するなら「映像の送信によって、音声の送信が阻害されないようにすること」とも言える

• PacingController と関係がある主要なクラスとしては以下のものがある:

  • PacingController が利用するクラス:

    • BitrateProber:

      • 帯域推定などを補佐するためのクラス

      • 送信パケットが少な過ぎると帯域推定の信頼度が下がるので、プローブ用のパディングパケットを、ペース調整の範囲内で挿入する役目を持つ

    • RoundRobinPacketQueue:

      • 送信パケットを一時的に格納するためのキュー

      • このドキュメントの範囲内では、単なる優先順位付きキュー、とみなしてしまって問題ない

      • PacingController::PacketQueue インタフェースの実装クラス

    • PacketRouter:

      • PacingController が実際にパケット送信を行う際のインタフェースを規定する PacingController::PacketSender の実装クラス

      • このインタフェースは、パケット送信に加えて、FEC パケットやパディングパケットの生成メソッドも定義している

  • PacingController を利用するクラス:

    • TaskQueuePacedSender:

      • PacingController の API ラップして pacing モジュール外から呼び出すためのインタフェースを提供する

      • PacingController::ProcessPackets() の呼び出しタイミングを決定するのもこのクラス

    • RtpTransportControllerSend:

      • 帯域推定や輻輳制御を行うクラスが検知したネットワーク状態の変更を PacingController に伝えるためのハブとなるクラス

      • PacingController::SetPacingRates() などを（ TaskQueuePacedSender を経由して） 呼び出す

• PacingController がやらないこと:

  • ネットワークの状態（帯域や輻輳）の推定

    • 送信ペース調整の際には、これらの状態を考慮はするが、推定自体は外部に任せている

      • PacingController はあくまでも、指定されたペースは正しいものとして、それを遵守するのが役割

    • この辺りは帯域推定や輻輳制御を専門に行うクラスの責務であり、本ドキュメントの対象外となる

  • 送信キューが詰まった場合のパケットドロップ

    • 指定されたターゲット送信ビットレートが、実際に送信されるパケット群に対して小さ過ぎる場合（帯域推定が誤っている場合など）には、キューの消化ペースが追いつかなくなる

    • そのような場合でも PacingController はパケットドロップは行わず、（時間は掛かっても）すべてのパケットの送信を試みる

    • ただし、キューが詰まっている場合には、指定されたターゲット送信ビットレートを超過したペースでのパケット送信が許容されるようになる

以降では PacingController および関連するクラスの実装やアルゴリズムの詳細を取り上げていく。

なお、フィールドトライアルやオプションによって挙動が変わる機能については、簡単のためにデフォルトの構成に準拠して記述を行なっている （末尾の「構成オプション」節も参照）。

詳細

PacingController クラスの詳細

ペース調整ロジックの中心を担う PacingController の主要なメソッドについて説明していく。

PacingController::SetPacingRates()

PacingController に「パケットの送信ペース（ターゲットビットレート）」を第一引数で指示するためのメソッド。

また第二引数で「パディングパケットの送信レート」を指定することもでき、これが 0 より大きい場合には、 送信ペースに余裕がある場合は、パディングパケットが常に送信されることになる。

PacingController の各処理では、ここで指示された送信ペースが厳守されることになる。 ペース調整は、イメージとしては 経過時間 * 送信ペース - これまでの送信量 = バジェット として、そのバジェットに収まる分だけのパケット送信を許可する形となっている。 この式を見て分かる通り、基本的には「時間経過分だけバジェットが増えて、パケット送信分だけ減る（かつ、プラスの場合にだけ送信できる）」という単純なもの。 なお、実際のコードでは「バジェット（＝ 余裕分）」ではなく「 dept （= 不足分）」として実装されているが、符号の向きが異なるだけで、意味するところはどちらもほぼ同じ。

ただし、いくつか例外もある:

• （デフォルトでは）音声パケットは、送信ペース管理の対象外（常にすぐ送信可能、また、送信分もバジェットから引かれない）

• キューが詰まっている場合には、要素が延々と増えていくことを防止するために、送信ペースを（指示されたものよりも）増加させる

  • 詳細は PacingController::MaybeUpdateMediaRateDueToLongQueue() を参照

• PacingController::SetSendBurstInterval() によってバースト送信が許可されている場合には、一時的に送信ペースを超過することがある

  • ただし、これによって消費されるバジェットの合計が増える訳ではない

なお、本メソッドの呼び出し側に関しては「 PacingController の利用側クラスや呼び出しタイミング」節を参照。

PacingController::EnqueuePacket()

送信対象の RTP パケット（ RtpPacketToSend ）を受け取り、それをキューに追加するメソッド。 キューイングされたパケットは PacingController::ProcessPackets() の呼び出し時に、 （ペース調整を満たしたタイミングで）実際に送信される。

メソッドの処理の流れは以下の通り:

1. BitRateProber::OnIncomingPacket() を呼び出して、プローバに送信対象パケットのサイズを教える

   • プローブ関連処理の詳細は「 BitrateProber クラスの詳細」の節を参照

2. キューが空だった場合には、現在時刻を基点にして、バジェットを再計算する:

   • 処理としては UpdateBudgetWithElapsedTime(UpdateTimeAndGetElapsed(現在時刻)); が呼ばれるイメージ:

     • UpdateTimeAndGetElapsed() で、最終処理時刻を現在時刻に設定（返り値が前回の処理時刻からの経過時間）

     • UpdateBudgetWithElapsedTime() で、経過時間を元に送信バジェットを更新する

   • この二つのメソッドの組み合わせは PacingController 内の色々なところで登場する頻出パターン

   • それぞれのメソッドの詳細については、後続のサブセクションを参照

3. キュー（ PacingController::PacketQueue の実装クラス）に RTP パケットを追加

4. キューの要素が増えたので PacingController::MaybeUpdateMediaRateDueToLongQueue() を呼び出して、必要なら送信ペースを増加する（キュー詰まり解消用）

なおユーザが直接生成した RTP パケットだけではなく、 PacingController::ProcessPackets() 呼び出し時に生成される 以下のパケットも、一度キューを経由して送信され、ペース調整の対象となる:

• FEC 用のパケット

• プローブ用のパディングパケット

PacingController::ProcessPackets()

キューに格納されているパケット群を PacingController::SetPacingRates() で指定されたペース制約を満たす範囲で送信するメソッド。 その他に、キープアライブやプローブ用のパディングパケットの送信を行なったりもする。

処理の流れ:

1. PacingController::ShouldSendKeepalive() を呼び出して、キープアライブ用のパディングパケットの送信が必要かどうかを判定する

   • PacingController::ShouldSendKeepalive() は大まかには「500ms 以上パケットが送信されていない場合」に、キープアライブが必要と判定する

   • 必要と判定されたら、ペイロードサイズが 1 のパディングパケットが送信される（この場合は PacingController::EnqueuePacket() は経由しない）

2. PacingController::Pause() 呼び出しによって、送信処理が一時停止中になっている場合には、ここで終了

3. PacingController::NextSendTime() で、パケットの次回送信時刻を取得する

   • もし現在時刻が送信時刻に到達していない場合（i.e., 送信バジェット枯渇中）には、ここで終了

4. UpdateTimeAndGetElapsed(次回送信時刻) を呼び出して、「前回の処理実施時刻」から「次回送信時刻」までの経過時間を取得する

   • NOTE: バジェットに余裕がある場合には、次回送信時刻は、現在時刻よりも前になることがある

   • 経過時刻が 0 秒以上なら PacingController::UpdateBudgetWithElapsedTime() を呼び出して、バジェットを更新する（経過時間分だけ送れる量が増える）

5. プローブ中の場合には BitrateProber::RecommendedMinProbeSize() を呼び出して「プローブに必要な送信データサイズ」を取得する

6. 以降で、キュー内のパケットの送信ループ処理に入る

   • 各イテレーションの冒頭では PacingController::GetPendingPacket() によって、次に送信するパケットがキューから取り出される

   • ただし、送信バジェットが枯渇している場合などは、キューに要素が存在しても null が返されることがある（詳細は後述）

   • 「次に送信するパケットがあるかどうか」で処理が分岐する

7. [送信パケットがない場合] 必要に応じて、プローブ用のパディングパケットをキューに追加する

   1. PacingController::PaddingToAdd() でパディングパケットのサイズを計算する

      • パディングパケットの送信が不要な場合には 0 が返され、ここで送信ループを抜ける

   2. PacingController::PacketSender::GeneratePadding() で上記のサイズのパディングパケットを生成する

   3. PacingController::EnqueuePacket() を呼び出して、パディングパケットをキューに追加する

   4. 送信ループの次のイテレーションに進む

8. [送信パケットがある場合] RTP パケットを実際に送信する

   1. PacingController::PacketSender::SendPacket() を呼び出して、パケットを送信する

   2. FEC パケットがある場合には PacingController::PacketSender::FetchFec() で取得して、キューに追加する

   3. PacingController::OnPacketSent() メソッドを呼び出して、（主に）以下を行う

      • 最終送信時刻の更新

      • PacingController::UpdateBudgetWithSentData() を呼び出してバジェットを更新（送信分だけバジェットを減らす）

   4. ループ内で送信したパケットのサイズ合計を更新する

   5. プローブ中の場合には、その合計サイズが「プローブに必要な送信データサイズ」を超過しているかどうかをチェックする

      • 超過している場合には、ここでループを抜ける

      • プローブ中の場合は、一度に送信するデータサイズが、少な過ぎても多過ぎても良くない

   6. PacingController::NextSendTime() を呼び出して、パケットの次回送信時刻を取得する

      • 次回送信時刻が「現在時刻を超えている（バジェットが枯渇した）」かつ「プローブ中ではない」場合には、ここでループを抜ける

   7. UpdateBudgetWithElapsedTime(UpdateTimeAndGetElapsed(次回送信時刻)) を呼び出して、次のイテレーションに備えてバジェットを更新する

9. 送信ループを抜けた後は、プローブ中なら BitRateProber::ProbeSent() を呼び出して、今回送信したデータサイズ合計を BitrateProber に伝える

10. 最後に PacingController::MaybeUpdateMediaRateDueToLongQueue() を呼び出して、以降の送信ペースの調整を行う

PacingController::NextSendTime()

パケットの次の送信時刻を決定するためのメソッド。

バジェットが枯渇している場合には、それが回復する予定時刻を返す。 反対にバジェットに余裕がある場合には、現在より前の時刻が返されることがある。

決定の際の流れは以下の通り:

1. PacingController::Pause() が呼ばれており、一時停止中なら「次のキープアライブ時刻」を返す

   • 「次のキープアライブ時刻」は 最後の送信時刻 + 500ms

2. プローブ中の場合には BitrateProber::NextProbeTime() に次回時刻の決定を委譲する

3. 送信キューの先頭が音声パケットの場合には、そのパケットをキューに追加した時刻（つまり過去）を返す

   • 音声パケットは、デフォルトではペース調整の対象外なので、即座に送信される

   • 音声パケットがペース調整の対象に含まれる構成の場合には、この部分の処理はスキップされる

4. 「輻輳発生中」ないし「まだ PacingController::EnqueuePacket() が一度も呼び出されていない」場合には「次のキープアライブ時刻」を返す

   • 「輻輳発生中」かどうかは PacingController::SetCongested() によって、外部から PacingController に伝えられる

   • 輻輳時には、音声パケットやキープアライブ用パディングパケットを除いて、パケット送信は抑制される

5. キューに要素がある場合には、

   1. 負債 / 送信ペース で負債が解消するまで（= 次にパケットが送信可能になるまで）に掛かる時間を求める

      • 「負債」は、バジェットを超過して送信したパケットの合計サイズ（超過しておらずバジェットに余裕がある場合には負数になる）

   2. その時間分を「最後の送信時刻」に加算し、それを次回の送信時刻とする

6. キューが空の場合には、

   • 「 PacingController::SetPacingRates() でパディングパケットの送信レートが指定されている」場合は、そのレートに合わせて次回の送信時刻を決定する

   • それ以外の場合には、「次のキープアライブ時刻」を次回送信時刻とする

PacingController::PaddingToAdd()

プローブやその他の目的で使用するパディングパケットのサイズを決定するメソッド。

決定方法:

• 送信キューが空ではないなら、パディングサイズは 0 （パディングではなく実際のパケットを送るべきなので）

• 輻輳中ならパディングサイズは 0 （ネットワークに負荷をかけたくない）

• PacingController::EnqueuePacket() が一度も呼び出されていないなら、パディングサイズは 0 （パディングパケットを生成しても、適切なタイムスタンプを振ることができない）

• プローブ中の場合には プローブに必要なバイト数 - これまでに送信したバイト数 をパディングサイズとする

• PacingController::SetPacingRates() で「パディングパケットの送信レート」が指定されている場合には レート * 5ms を返す

  -ただし、パディング用のバジェットに余裕がある場合のみ

PacingController::MaybeUpdateMediaRateDueToLongQueue()

送信キューへの操作（要素追加や削除）があった場合に呼び出されるメソッド。

SetPacingRates() で指定された送信ペース（ターゲットビットレート）に対して、 EnqueuePacket() で追加されるペースが多過ぎると、キューが詰まって延々と要素数が増えてしまう。 それに対処するために、送信ペースの調整（増加）を行うのがこのメソッドの役割。

処理の流れ:

1. 最初に送信ペースを PacingController::SetPacingRates() で指定された値にリセットする

2. キューにあるパケットの「サイズ合計」を求める

   • もし 0 ならここで終了（指定された送信ペースをそのまま使う）

3. キュー内の各要素の平均滞在時間（エンキューされてから、実際に送信されるまでの平均時間）を求める

4. 「キューが空になるまでの期待時間」を 2 秒 - 平均滞在時間 で求める（0 以下になる場合には 1ms にする）

   • 「2 秒」の部分は PacingController::SetQueueTimeLimit() で変更できる

   • 「キューが空になるまでの期待時間」は、「キュー内の最後のパケットの遅延を 2 秒以下にするために使える残り時間」とも言える

5. サイズ合計 / キューが空になるまでの期待時間 で、その期待時間を達成するために必要な送信ペースを求める

   • 求めた送信ペースが PacingController::SetPacingRates() よりも大きい場合には、（指定のペースではなく）そちらを採用する

PacingController::UpdateTimeAndGetElapsed()

基本的には「現在時刻」を引数にとって、それと「最終処理時刻」との差分（経過時間）を計算して返すメソッド。

処理の流れ:

1. 「最終処理時刻」よりも前の時刻が「現在時刻」として指定された場合には、このメソッドは 0 秒を経過時間として返す

   • 「現在時刻」には PacingController::NextSendTime() が返した時刻が渡ってくることがあるため、過去の時刻になることもある

2. 現在時刻 - 最終処理時刻 で経過時間を求める

3. もし経過時刻が 2 秒を超えている場合には、2 秒に丸める

4. 「最終処理時刻」を「現在時刻」の値で更新して、経過時間を呼び出し元に返す

PacingController::UpdateBudgetWithElapsedTime() および PacingController::UpdateBudgetWithSentData()

バジェットの増減を行うための単純なメソッド群:

• PacingController::UpdateBudgetWithElapsedTime() は経過時間を引数に取り 経過時間 * 送信ペース の分だけバジェットを増やす

• PacingController::UpdateBudgetWithSentData() は送信したパケットサイズを引数に取り、その分だけバジェットを減らす

BitrateProber クラスの詳細

• BitrateProber は「送信帯域の推定（プローブ）用に追加で送信するパディングパケット」のサイズや送信タイミングを決定するためのクラス

• プローブ処理は BitrateProber::CreateProbeCluster() 呼び出しにより開始され、プローブに必要な期間やパケット送信回数を超えたら終了する

  • この一回のプローブ処理のまとまりは「クラスター」と呼ばれる

  • クラスターは BitrateProber::CreateProbeCluster() 呼び出し毎に新しく生成され、FIFO キューの末尾に追加される

  • 一度に処理されるのはキューの先頭のクラスターのみ

• BitrateProber には ProbingState で表現される以下のような状態遷移がある:

  • ProbingState::kDisabled:

    • プローブ処理が無効な構成の場合には、常にこの状態となる

  • ProbingState::kInactive:

    • この状態になるのは、

      • BitrateProber のインスタンス生成直後、ないし、

      • BitrateProber::CreateProbeCluster() によってクラスターが生成されたが、まだプローブ処理が開始されていない場合

    • 基本的には、新しいパケットが PacingController のキューに積まれた段階で ProbingState::kActive に遷移する

  • ProbingState::kActive:

    • プローブ処理の実施中を示す状態（ PacingController と協調して、適宜パディングパケットが送信される）

    • すべてのクラスターでのプローブ処理が完了した時点で ProbingState::kSuspended に遷移する

  • ProbingState::kSuspended:

    • すべてのクラスターでのプローブ処理が完了して待機中の状態

    • 次の BitrateProber::CreateProbeCluster() 呼び出しによって ProbingState::kInactive に遷移する

• プローブ処理は常時実行されるものではなく、通信相手との接続直後やネットワーク状況の変更に応じて実施される

以降では BitrateProber の主要メソッドについて説明していく。

BitrateProber::CreateProbeCluster()

新しいクラスターを生成するためのメソッド。

処理の流れは以下の通り:

• 古いクラスターがキューに残っている場合には削除

  • 作成から五秒以上経過しているクラスターは、古いと判定される

• 引数で指定された以下の情報をもとに、新しいクラスターを生成する:

  • ターゲット送信ビットレート

  • プローブ用のパケット送信回数

  • プローブ用に送信するパケットサイズの合計

    • この値は ターゲット送信ビットレート * プローブ期間（デフォルトでは 15ms） によって算出される

• 生成したクラスターをキューの末尾に追加

• BitrateProber の状態を kInactive にする

  • 次の BitrateProber::OnIncomingPacket() 呼び出しによってプローブが開始される

  • 既に kActive の場合には何もしない）

BitrateProber::OnIncomingPacket()

• PacingController::EnqueuePacket() の中で、追加対象パケットのサイズを引数として、呼び出されるメソッド

• 「現在が kInactive 」かつ「クラスターキューが空ではない」かつ「パケットサイズが十分に大きい場合」に kActive 状態に遷移する

  • 「パケットサイズが十分に大きい場合」== 「パケットサイズが min(200, RecommendedMinProbeSize()) 以上」

BitrateProber::RecommendedMinProbeSize()

• 一度に送信するプローブ用のデータサイズの推奨（最低）値を返すメソッド

  • 送信量がこれより少ないとプローブの結果の信頼度が下がるので、不足分は（ PacingController によって）パディングパケットで補填される

• 計算式: 2 * ターゲット送信ビットレート * 1ms

BitrateProber::NextProbeTime()

• プローブ用のパケット送信を次に行うべき時刻を返すメソッド

• 状態が kActive ではない場合には Timestamp::PlusInfinity() が返される

• kActive （かつクラスターキューが空ではない）場合には BitrateProber::CalculateNextProbeTime() によって事前に計算されていた、次回プローブ時刻、を返す

private なメソッドである BitrateProber::CalculateNextProbeTime() は BitrateProber::ProbeSent() の中で呼び出され、 以下のようにして次回プローブ時刻を決定する:

• 計算式: クラスターでの送信開始時刻 + (クラスターで送信済みのサイズ合計 / ターゲットビットレート)

  • 「送信開始時刻」はクラスターの生成時刻とは異なり、初めて実際にパケットが送信された時刻

• クラスター生成時に指定されたターゲットビットレート通りの送信ペースになるように設定された単純な式

• ターゲットビットレートに対して「送信量が多い場合には未来の時刻」になり、逆に「送信量が少ない場合には過去の時刻」になる

BitrateProber::ProbeSent()

PacingController::ProcessPackets() の中で「実際に送信された合計パケットサイズ」を引数に取り呼び出されるメソッド。

処理の流れは以下の通り（キュー内の先頭のクラスターに対して適用される）:

• このクラスターでのパケット送信が初の場合には「送信開始時刻」を現在時刻に設定する

• 「送信済みバイト数合計」に、今回の送信分を加算する

• 「プローブ（用のデータ送信）回数」をインクリメントする

• BitrateProber::CalculateNextProbeTime() を呼び出して、次のプローブ時刻を決定する

• 以下の両方の条件を満たす場合には、プローブ処理を終えたものと判断し、クラスターをキューから除去する:

  • 「送信済みバイト数合計」が BitrateProber::CreateProbeCluster() で指定された規定値を超過した

  • 「プローブ回数」が BitrateProber::CreateProbeCluster() で指定された規定値を超過した

• クラスターキューが空になった場合には、 BitrateProber の状態を kSuspended に遷移する

BitrateProber::CurrentCluster()

現在のプローブ処理を行なっているクラスターを返すメソッド。

基本的にはキューの先頭要素を返すだけだが、細々とした条件や処理がある。

• BitrateProber の状態が kActive ではない場合には null を返す（クラスター生成直後は kInactive である可能性がある）

• 「次のプローブ時刻（cf. BitrateProber::CalculateNextProbeTime() ）」が現在時刻に対して 10ms よりも前の場合には「そのクラスターには深刻な遅延が発生している」と判断する:

  • そのクラスターはキューから除去して、次のクラスターを返す

  • キューが空の場合には、状態を kSuspended に遷移した上で null を返す

PacingController の利用側クラスや呼び出しタイミング

• PacingController の各メソッドは直接外部から触られる訳ではなく TaskQueuePacedSender が（ほぼ）同名のメソッドをラップして提供している

  • EnqueuePackets(), SetPacingRates(), SetCongested(), Pause(), Resume(), CreateProbeClusters(), etc

  • ただし PacingController::ProcessPackets() に対応する TaskQueuePacedSender::MaybeProcessPackets() は外部に公開されていない

    • TaskQueuePacedSender::MaybeProcessPackets() は上述の各ラッパー関数の最後で呼び出される形となっている

    • このメソッドは PacingController::NextSendTime() の結果などを考慮し、適宜 PacingController::ProcessPackets() を呼び出す役目を担っている

• TaskQueuePacedSender が（ラップして）公開しているメソッド群を呼び出すのは、

  • EnqueuePackets() は、映像／音声を処理しているモジュールによって使用される

  • SetPacingRates(), SetCongested(), createProbeClusters(), Pause(), Resume() といったネットワークの帯域や状態に関連するメソッドは RtpTransportControllerSend クラスから呼び出される:

• さらにこれらのメソッドは RtpTransportControllerSend クラスから呼び出される:

  • RtpTransportControllerSend::PostUpdates()

    • NetworkControlInterface の実装クラスの各メソッド呼び出し後に、その結果（ NetworkControlUpdate 構造体）を引数として呼び出されるメソッド

    • NetworkControlUpdate 構造体には PacerConfig や PacerClusterConfig, TargetTransferRate といったペーサーに関係するフィールドが含まれている

      • これらのフィールドに変更があった場合には TaskQueuePacedSender の SetCongested(), SetPacingRates(), createProbeClusters() などのメソッドが呼び出される

      • これによって NetworkControlInterface を実装している輻輳制御や帯域推定を行なっているクラスが得たフィードバックが PacingController に伝わることになる

  • RtpTransportControllerSend::OnNetworkAvailability():

    • ネットワークの利用可能性が変わった時に呼び出されるコールバックメソッド

    • TaskQueuePacedSender の Pause() および Resume() が必要に応じて呼び出される（ネットワークが利用不可になったなら前者、利用可能になったなら後者）

ペーサーによって発生し得る遅延

おそらく以下のようなケースが考えられる:

• PacingController::SetPacingRates() で指定されたターゲットビットレートが小さ過ぎる場合:

  • PacingController は一度キューに入ったパケットを破棄しない

  • そのため PacingController::EnqueuePacket() で追加されるパケットのサイズ（ペース）が、そもそもそのターゲットビットレート内で送信できる量を超えている場合には、キューが詰まり、遅延も増加していく

  • ただし、キュー内に存在するパケットの待機時間の平均値が 2 秒を超えそうな場合には、一時的に送信ビットレートを上げて、キューに無限に要素が増えないようにしようとする

  • 2 秒はデフォルト値で PacingController::SetQueueTimeLimit() を使うことで変更が可能

• 映像パケットのサイズの振れ幅が大きい場合:

  • PacingController が採用しているリーキーバケットアルゴリズムでは、一度に送信できるサイズに上限がある

  • そのため「極端にサイズが大きい映像の I フレームを定期的に送信」といった場合には、全体としては余裕があって、その I フレームパケットの送信がペース調整されて一度に行えず、遅延が発生する可能性がある

  • これが問題となる場合には PacingController::SetSendBurstInterval() といったメソッドで、ある程度のバースト送信を許容するようにできるので、これで緩和できる可能性がある

構成オプション

フィールドトライアルやメソッド呼び出しなどによって挙動を以下のように変更することが可能（注意: 網羅的ではない）:

• プローブ処理の無効化

• 音声パケットをペース調整処理に含める（e.g. バジェットが不足している場合には即座に送信しない、バジェット計算の際に送信済み音声パケットサイズを考慮する）

• 送信済みサイズの決定の際に、RTP / TCP / IP のヘッダー部分を考慮するかどうか（デフォルトでは RTP のペイロードサイズのみが使われる）

• ある程度のバースト送信を許容する ( PacingController::SetSendBurstInterval() )

  • 利用できる送信帯域の総容量が増える訳ではないが、一時的に大きなパケット（e.g., 映像の I フレーム）が来た場合に、それを一気に送信できるようになる

• 送信キューの実装として RoundRobinPacketQueue の代わりに PrioritizedPacketQueue を使用する

libwebrtc ミキサーのストリーム数上限

注意

この資料の正確性を保証しません。

重要

この資料についての問い合わせは Sora のサポート範囲には含まれません。

この資料は libwebrtc M105 (5195) 時点の資料です。

このドキュメントでは libwebrtc での音声ミキサーの処理ストリームの上限について記載しています。

音声ミキサーは、複数の入力音声ストリームがある場合に、それらをまとめて一本のストリームとして出力する機能です。

処理対象となる入力ストリーム数の上限値

ミキサーの処理対象となる入力ストリーム数の上限は kDefaultNumberOfMixedAudioSources 定数によって定義されており、 値は 3 となっています。

この上限は AudioMixerImpl::Create() メソッドの引数に別の値を指定することで変更できます。

処理対象入力ストリームの選択方法

ミキサーの処理対象となる入力ストリームの選択は AudioMixerImpl::GetAudioFromSources() メソッドで行われます。

選択手順の概要は以下の通りです:

1. すべての入力音声ストリームを集める

2. それらを ShouldMixBefore() 関数を使ってソートする

   • この関数は音声ストリーム同士の音量を比較し、音の大きい方が前に配置されるようにする

3. ソート結果の先頭から上限値に達するまでストリームを選択する

   • ただし、ミュート状態のストリームは常に対象外となる

処理対象入力ストリームが入れ替わった場合の挙動

処理対象となる入力ストリーム一覧は、各ストリームの音量やミュート状態の変化、 あるいはストリーム自体の増減によって変化します。

その際に、処理対象に新しく追加されたストリームの最初の音声フレームは、ゲイン（各サンプルに乗算される重み） を調整することで、徐々に音が大きくなっていくように処理されています。 具体的には libwebrtc での音声フレームは 10ms 区切りとなっていますが、 そのフレーム内の先頭サンプルでは 0.0 （無音）から初めて、末尾サンプルでは 1.0 となるように、 段階的にゲインを増やすという処理が適用されます。 これらの処理は RampAndUpdateGain() メソッドや Ramp() 関数によって実装されています。

なお RampAndUpdateGain() メソッド自体は、ストリームが対象から外れた場合（この場合はゲインが 1.0 から 0.0 に減少していく）も考慮された実装となっています。 ただし、このメソッドの呼び出しもとの実装的に、初回追加時にのみゲイン調整が行われます （一度対象から外れた後に再度追加された場合もゲイン処理の適用外となります）。

Microsoft Edge の WebRTC について

概要

2024 年 12 月 時点で Microsoft Edge 124 を使用して確認しています。

Download New Microsoft Edge Browser | Microsoft

現状

Chrome とほぼ同様の仕様で、特に問題なく動作します。

Edge 121 から AV1 もサポートされています。

Apple Safari の WebRTC について

概要

2024 年 12 月 時点で Safari 18.1 を使用して確認しています。

注意点

• 音声が含まれているまたは音声のみの配信の場合 iOS の Safari では自動再生されません

  • これは iOS の Safari の仕様のため、今のところ回避の方法はありません

  • macOS の Safari の場合も設定を有効にしないと同様です

• Certificate Management API に非対応です

  • ECDSA P256 使えません

• ontrack を利用してください

• 映像コーデック VP9 は対応していますが、古い iPhone では動作しなかったりします

• getUserMedia を利用するには HTTPS が必須です

  • 開発モードで HTTPS 必須を無効にできます

iOS の Chrome や Firefox について

iOS の Chrome や Firefox は WKWebView を利用しています。 WKWebView は iOS 14.3 にて getUserMedia に対応しました。

iOS Safari で画面共有について

iOS Safari には画面共有用の getDisplayMedia API が実装されていません。 そのため、画面共有を利用するにはネイティブアプリケーションを利用する必要があります。

2024 年 12 月 時点ですべてのモバイルブラウザが getDisplayMedia API には対応していません。

MediaDevices.getDisplayMedia() - Web APIs | MDN

録画機能音ズレ問題

Safari や Safari Technology Preview では録画機能利用時に replaceTrack などを利用して MediaStreamTrack を削除し、 一定時間経過後に新しく追加した際、音声パケットに関連するタイムスタンプと NTP タイムスタンプが正しく出力されない問題あります。

この問題により Safari や Safari Technology Preview では録音/録画したファイルにて音ズレが発生してしまいます。

この問題はブラウザ側のバグであり、現在のところ回避策はありません。

WebRTC Encoded Transform API が利用できる

Safari では WebRTC Encoded Transform API が利用できます。

H.265 (HEVC)

Safari 18.0 から HEVC (H.265) がデフォルトで有効になりました。

Safari 18.0 Release Notes | Apple Developer Documentation

VP9 Profile 2

ドキュメントに記載はありませんが、Safari 18.0 より VP9 Profile 2 がデフォルトで有効になりました。

実験的機能

注意

Safari や Safari Technology Preview (Safari TP) では実験的機能の挙動が異なります

WebRTC AV1

Safari や Safari Technology Preview (Safari TP) 最新版では開発メニューで有効にすることで WebRTC AV1 が利用できます。

nginx

注意

nginx の設定に関する質問については Sora のサポート範囲外となります。

この設定はある程度の nginx や証明書の知識が必要になります

概要

Sora のシグナリングを暗号化する場合に何かしらのサーバーを立てる必要があります。

ここでは nginx での設定例を紹介しています。

設定例

nginx.conf の http ディレクティブに include を使用した場合の設定例です。

ssl_* 関連の設定は済んでいる前提とします。

server {

        listen 443 ssl default_server;

        index index.html;

        server_name sora.example.com;

        # Sora のシグナリング に Proxy します
        location = /signaling {
                proxy_pass http://127.0.0.1:5000;
                proxy_http_version 1.1;
                proxy_set_header Upgrade $http_upgrade;
                proxy_set_header Connection "upgrade";
        }

        # Sora の HTTP API に Proxy します
        # 本番環境では認証などの機能を利用してください
        location /api {
                proxy_pass http://127.0.0.1:3000/;
        }

        # Sora の開発ツールに Proxy します
        # 本番環境では不要です
        location / {
                proxy_pass http://127.0.0.1:5000;
        }
}

TURN を含んだ設定

TURN 関連は 本番稼働に向けて にある資料を確認してください。

TURN-TLS、TURN-TCP、シグナリングで 443 番ポートを使用する

HLS 配信

重要

このドキュメントに書かれている FFmpeg に関する事柄についてはサポート対象外ですのでご注意ください

警告

このドキュメントはとても古いため参考程度にしてください

概要

Sora の RTP 転送 API と FFmpeg を利用することで、HTTP Live Streaming（以下 HLS）で配信できます。

検証したバージョン

警告

このドキュメントで確認している FFmpeg のバージョンはかなり古いため参考程度にしてください

FFmpeg のバージョン:

3.3.3

配信例

下記の例では、RTP 転送 API の応答で送られてきた SDP を FFmpeg に読み込ませることで、 Sora から送られてきた RTP パケットを受信して H.264／MP3 の TS ファイルで出力しています。

配信時は、この時同時に作成／更新されているプレイリスト（m3u8 ファイル）を TS ファイルと一緒に Web サーバーで公開します。

変換例:

#!/bin/bash

CHANNEL_ID=sora
CONNECTION_ID=WHSSBG91XS7NXEVYY0F51YFEEW
VIDEO_PORT=60001
# VIDEO_PORT + 1 は RTCP の待ち受けで使用されるため空けておく
# また、AUDIO_PORT + 1 も RTCP の待ち受けで使用される
AUDIO_PORT=$(( $VIDEO_PORT + 2 ))

VIDEO_CODEC=libx264
AUDIO_CODEC=libmp3lame
QUEUE_SIZE=4000


start_forwarding_rtp() {
  data=$( jq -n -c --arg channel_id $CHANNEL_ID  --arg connection_id $CONNECTION_ID \
                   --argjson video_port $VIDEO_PORT \
                   --argjson audio_port $AUDIO_PORT \
                   '{"channel_id":$channel_id, "connection_id":$connection_id, "ip_address":"127.0.0.1", "video_port":$video_port, "audio_port":$audio_port}' )
  http POST 127.0.0.1:3000 \
       x-sora-target:Sora_20170814.StartForwardingRtp \
       <<< $data
}

json=$( start_forwarding_rtp )
sdp=$( echo $json | jq -r .sdp )

echo "$sdp" | ffmpeg  \
  -loglevel fatal \
  -protocol_whitelist file,rtp,udp,pipe \
  -i pipe:0 \
  -c:v $VIDEO_CODEC \
  -c:a $AUDIO_CODEC \
  -map 0 \
  -flags -global_header \
  -max_muxing_queue_size $QUEUE_SIZE \
  -f hls \
  -hls_segment_type mpegts \
  -hls_flags append_list \
  -hls_list_size 0 \
  -hls_segment_filename index%d.ts \
  index.m3u8

ブラウザにアクセスさせる HTML の video タグにはプレイリストを指定します。

例:

<html>
  <head>
    <title>HLS</title>
  </head>
  <body>
    <div>
      <video src="index.m3u8" controls />
    </div>
  <body>
</html>

お勧めのカメラとスピーカーフォン

カメラ

ロジクールが安定して、画質も良いです。

Logicool

色々種類が出ていますが、予算があれば StreamCam をおすすめします。

• ロジクールStreamCam - フルHDストリーミング ウェブカメラ

予算がそこまで無い場合は C922n をおすすめします。

• C922n PRO HDストリーム ウェブカメラ

スピーカーフォン

予算に余裕があれば YAMAHA をおすすめします。

YAMAHA

会議室に置くなら YVC-330 で、自宅で利用するなら YVC-200 が良いです。

• YVC-200 特長

  • 1-4 人向け

• YVC-330 特長

  • 4-6 人向け

• YVC-1000 特長

  • 8-40 人向け

オープンソースライセンス

WebRTC SFU Sora で利用しているオープンソースのライセンス一覧

Apache License 2.0

URL:

https://opensource.org/license/apache-2-0/

• erlang/otp

• openssl/openssl

• uwiger/gproc

• rabbitmq/ra

• rabbitmq/gen-batch-server

• rabbitmq/aten

• rabbitmq/seshat

• shiguredo/jsone

• shiguredo/jesse

• shiguredo/swidden

• shiguredo/kvconf

• shiguredo/base32_clockwork

• shiguredo/sora-devtools

ISC License

URL:

https://opensource.org/license/isc-license-txt/

• ninenines/cowboy

• ninenines/cowlib

• ninenines/ranch

• ninenines/gun

その他のライセンス

ferd/recon: Collection of functions and scripts to debug Erlang in production.:

Copyright (c) 2012-2024, Fred Hebert
All rights reserved.

Redistribution and use in source and binary forms, with or without modification,
are permitted provided that the following conditions are met:

Redistributions of source code must retain the above copyright notice, this
list of conditions and the following disclaimer.

Redistributions in binary form must reproduce the above copyright notice, this
list of conditions and the following disclaimer in the documentation and/or
other materials provided with the distribution.

Neither the name of the copyright holder nor the names of its contributors may
be used to endorse or promote products derived from this software without
specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

古いリリースノート

UPDATE

後方互換性がある変更

ADD

後方互換性がある追加

CHANGE

後方互換性のない変更

FIX

バグ修正

重要

変更、廃止された一部機能のリンクは無効になっています。

2024.1.3

バグフィックスアップデート

リリース:

2024 年 8 月 9 日

変更履歴

• [FIX] 証明書の署名アルゴリズムに SHA1 が利用されている場合でも、許容するように変更しました

• [FIX] クラスター機能利用時に、アフィニティが有効な場合でもまれにリレーが発生する場合がある問題を修正しました

• [FIX] 転送フィルター機能利用時に、シグナリング通知の送信がまれに失敗する場合がある問題を修正しました

• [FIX] イベントウェブフックやシグナリング通知の connection.created のチャネル接続数の値が、まれに実際の値よりも小さくなる場合がある問題を修正しました

• [FIX] 録画機能利用時に、RTP のシーケンス番号が等しいが RTP ヘッダー拡張 abs-capture-time の値が異なるパケットが短期間に複数送られて来た場合に録画が失敗してしまう問題を修正しました

• [FIX] 録画機能利用時に、一部の端末で RTP ヘッダー拡張 abs-capture-time に意図しない値が含まれると録画が失敗してしまう事があるため、 rtp_hdrext_abs_capture_time のデフォルトを false に変更しました

  • 詳細については Chrome/Edge の不具合による録画機能利用時の音ズレ問題について をご確認ください

2024.1.1

バグフィックスアップデート

リリース:

2024 年 7 月 1 日

変更履歴

• [FIX] 録画機能利用時、パケットのタイムスタンプに異常がある場合に発生する問題を修正しました

2024.1.0

メジャーアップデート

リリース:

2024 年 6 月 26 日

ハイライト

• クラスターリレー機能を追加しました

  • いずれのノードからでも同一のチャネルに接続できるようになりました

• クラスターアフィニティ機能を追加しました

  • リレー機能利用時に、特定のノードに同一セッションの接続を集約する仕組みを追加しました

  • この機能によりノード間通信を極力発生させないようにすることができます

• ライセンスの同時接続数の合計を維持する機能を追加しました

  • ノードに障害が発生したとしても、クラスター全体の同時接続数を維持できるようになりました

• テンポラリーノード機能を追加しました

  • クラスターの維持に影響しないノードを手軽に削除できるようになりました

• OBS WHEP に対応しました

  • OBS の WHEP ソース機能を利用し Sora から映像を取得できるようになりました

  • 2024 年 12 月 現在、OBS 安定版では WHEP に対応していません

• OBS WHIP/WHEP の TURN に対応しました

  • 2024 年 12 月 現在、OBS 安定版では TURN に対応していません

• OBS WHIP/WHEP の H.265 (HEVC) に対応しました

  • 2024 年 12 月 現在、OBS 安定版では H.265 に対応していません

• セッションとコネクションが破棄される時間を指定できるライフタイム機能を追加しました

  • セッションやコネクションで指定した時間が経過すると自動的に破棄されるようになりました

• 複数のコーデックで、複数の画質が同時に配信できるサイマルキャストマルチコーデック機能を追加しました

  • 2024 年 12 月 現在、ブラウザでは利用できません

• 音声トラックを削除した後に、再度音声トラックを追加した際に正常に録音されない問題に対応しました

  • Chrome/Edge の不具合により、今まで音声がずれて録画されてしまっていた問題を解決しました

  • Safari でも同様の不具合を確認していますが、本対応では解決できていません

正式版

今回のリリースで以下の機能は実験的機能から正式版になりました。

• モード機能

• 転送フィルター機能

• 音声ストリーミング機能

• 録画ブロック機能の払い出し

• SDP 再利用機能

  • recycle_media_section

廃止情報

• CentOS 7 向けパッケージの提供を終了しました

• モード機能のイニシャルモードを廃止しました

• 認証成功時に払い出す h264_profile_level_id を廃止しました

  • 代わりに "video_h264_params": {"profile_level_id": "<profile-level-id>"} を使用してください

• sora.conf から default_h264_profile_level_id を廃止しました

  • 代わりに default_h264_param_profile_level_id を使用してください

• 実験的機能として提供していた sora.conf の rtp_publish_worker_number を廃止しました

  • 代わりに media_publish_worker_number を使用してください

• 実験的機能として提供していた Lyra を廃止しました

  • Opus 1.5 で Lyra 同様の低ビットレートが利用可能になったこと、Lyra が 2 年間更新がないことが廃止の理由です

• sora.conf の contact_node_name_list を廃止しました

  • 今後は RegisterClusterNode API を利用してください

• sora.conf の cluster_auto_connect を廃止しました

  • クラスター機能の自動での再接続は常に有効になります

非推奨情報

• Ubuntu 20.04 の提供を Sora 2024.1.x 系をもって終了します

  • Ubuntu 20.04 は 2025 年 4 月にサポートが終了します

• multistream: false で利用するレガシーストリームを非推奨にしました

  • multistream: false は 2025 年 6 月リリース予定の Sora で廃止します

  • マルチストリームを利用してください

    • レガシーストリーム(非マルチストリーム)機能からマルチストリーム機能への移行

• JoinCluster API を非推奨にしました

  • JoinCluster API は 2024 年 12 月リリース予定の Sora で廃止します

  • RegisterClusterNode API を利用してください

• ListClusterNodes API の include_all_known_nodes 指定を非推奨にしました

  • include_all_known_nodes は 2024 年 12 月リリース予定の Sora で廃止します

  • 廃止後は include_all_known_nodes が常に true として動作するようになります

• 統計エクスポーター機能を非推奨にしました

  • 統計エクスポーター機能は 2025 年 6 月リリース予定の Sora で廃止します

  • 統計ウェブフック を利用してください

• ユーザエージェント統計を非推奨にしました

  • ユーザエージェント統計は 2025 年 6 月リリース予定の Sora で廃止します

  • RTC 統計情報を利用してください

• ユーザエージェント統計 API を非推奨にしました

  • ユーザエージェント統計 API は 2025 年 6 月リリース予定の Sora で廃止します

  • RTC 統計情報 API を利用してください

破壊的変更

• クラッシュを意図的に発生させるテスト用 Sora_20221221.GenerateCrashLog API を Sora_20380119.GenerateCrashLog に変更しました

• イベントウェブフック connection.destroyed の reason に含まれる値を変更しました

  • 2023.2.x までは disconnect_api_reason と同じ、または disconnect_api_reason が無ければ null が含まれていました

  • 2024.1.x からは normal / disconnected_api / session_destroyed / lifetime_expired が含まれるようになります

  • 2023.2.x までの設定を維持する移行用の設定 legacy_event_webhook_connection_destroyed_reason を追加しています

    • この移行用の設定 legacy_event_webhook_connection_destroyed_reason は 2024 年 12 月リリース予定の Sora にて廃止します

• 統計 API の RTP ヘッダー拡張の項目名のプレフィックスを rtp_hdr_ext から rtp_hdrext へ変更しました

• TerminateSession API を非同期に変更しました

  • セッション破棄の確認は session.destroyed ウェブフックを利用してください

• ライセンスチェックのタイミングを変更しました

  • 今までは WebSocket 接続時にライセンスチェックを行っていましたが、 "type": "connect" 時にチェックを行うように変更しました

    • WHIP と WHEP については変更はありません

  • 詳細についてはサポートまでお問い合わせください

変更履歴

• [CHANGE] シグナリング "type": "disconnect" 時に指定できる reason の最大値を 128 バイトに制限しました

• [CHANGE] TerminateSession API を非同期に変更しました

  • セッション破棄の確認は session.destroyed ウェブフックを利用してください

• [CHANGE] 統計 API の RTP ヘッダー拡張の項目名のプレフィックスを rtp_hdr_ext から rtp_hdrext へ変更しました

• [CHANGE] モード機能のイニシャルモードを廃止しました

• [CHANGE] 最大帯域幅指定で利用する SDP を b=TIAS と b=AS から b=TIAS のみに変更しました

• [CHANGE] 帯域推定で利用する REMB で送信するビットレートを b=TIAS のみに変更したのに合わせて音声ビットレートを含めないようにしました

• [CHANGE] 音声コーデック Lyra への対応を廃止しました

• [CHANGE] SDP の msid の appdata を UUIDv4 を BASE32 でエンコードした値から、 connection_id に メディアの種類を追加した値に変更しました

  • RFC 8830 WebRTC MediaStream Identification in the Session Description Protocol

  • この変更により MediaStreamTrack の id から connection_id を取得できるようになりました

  • この変更により WebRTC 統計情報の inbound-rtp の trackIdentifier から connection_id を取得できるようになりました

  • Firefox では利用できません

• [UPDATE] 開発ツール を最新版に更新しました

• [ADD] Ubuntu 24.04 x86_64 と arm64 版のパッケージ提供を開始しました

• [ADD] connection.jsonl にコネクションを破棄した理由 destroyed_reason を追加しました

  • destroyed_reason には normal / disconnected_api / session_destroyed / lifetime_expired が含まれます

• [ADD] sora.conf に VP9 利用時に RTP ヘッダー拡張 dependency_descriptor を払い出す rtp_hdrext_dependency_descriptor_vp9 を追加しました

  • デフォルトは false です

  • この設定を true した場合 Firefox で VP9 が利用できなくなります

• [ADD] ListConnections API と ListChannelConnections API の戻り値に recording_block 項目を追加しました

• [FIX] メッセージングオンリー機能利用時に multistream: true の指定を不要にしました

テスト機能

• [CHANGE] クラッシュを意図的に発生させるテスト用 Sora_20221221.GenerateCrashLog API のバージョンを変更し Sora_20380119.GenerateCrashLog API に変更しました

  • 今後、テスト API はバージョンが全て 20380119 に固定されます

• [ADD] シグナリング通知を送信するテスト用 SendSignalingNotify API を追加しました

スポットライト機能

• [ADD] スポットライト機能利用時に、セッションウェブフック session.updated と session.destroyed に spotlight_number 項目が含まれるようにしました

• [ADD] セッションウェブフック session.created 時に spotlight_number を払い出せるようにしました

  • spotlight_number には 1 から 8 までの値を指定できます

  • セッションウェブフックで spotlight_number を払い出した場合、シグナリング接続時や認証成功時の払い出しの spotlight_number と異なる場合はエラーとなります。

  • シグナリング時と認証成功時の spotlight_number 指定は非推奨になりました

• [FIX] スポットライト機能利用時に同一セッションで spotlight_number が同時接続数 0 の場合にシグナリング接続時、または認証成功時払い出しで変更できてしまう問題を修正しました

  • セッション破棄までは ChangeSpotlightNumber API 以外ではスポットライト数を変更できないように修正しました

• [FIX] スポットライト機能利用時に multistream: true の指定を不要にしました

レガシーストリームを非推奨化

今まで multistream: false で利用していた、レガシーストリーム(非マルチストリーム)を非推奨にしました。 レガシーストリームは 2025 年 6 月に廃止します。

• [CHANGE] sora.conf にレガシーストリームを有効にする legacy_stream を追加しました

  • デフォルトは false です

  • レガシーストリームを利用する場合は true に設定してください

詳細は レガシーストリーム(非マルチストリーム)機能からマルチストリーム機能への移行 をご確認ください。

ウェブフック機能

• [ADD] sora.conf に認証ウェブフック失敗時に auth_webhook.jsonl にのみログを出力する legacy_auth_webhook_log を追加しました

  • 2023.2.x までの挙動を維持する設定です

  • この設定は 2024 年 12 月リリース予定の Sora にて廃止します

  • デフォルトは false です

  • この設定を false にした場合、認証ウェブフックが失敗した際には auth_webhook_error.jsonl にログを出力します

    • auth_webhook.jsonl にはログを出力しません

  • この設定を true にした場合、認証ウェブフックが失敗した際には 2023.2.x までと同様に auth_webhook.jsonl にログを出力します

    • auth_webhook_error.jsonl にはログを出力しません

• [ADD] sora.conf にウェブフックの接続確立タイムアウト時間を指定する webhook_connect_timeout を追加しました

  • 今までは固定の 600 s としていましたが、設定を追加するにあたりデフォルトを 30 s と変更しました

  • 範囲は 1 s から 600 s です

• [ADD] 認証ウェブフックリクエストに Accept ヘッダーを追加しました

  • Accept ヘッダーに application/json が含まれます

• [ADD] セッションウェブフックリクエストに Accept ヘッダーを追加しました

  • Accept ヘッダーに application/json が含まれます

• [FIX] 認証ウェブフックでステータスコード 2XX で空ボディを受け取った際の不具合を修正しました

• [FIX] 認証ウェブフックにシグナリング接続時の転送フィルターが含まれていない問題を修正しました

セッションウェブフック機能

• [ADD] セッションウェブフック session.created の戻り値が正常では無い場合、エラーとしてセッションを破棄して、セッションウェブフック session.destroyed を送信する設定の session_created_response_validate_warning_as_error を sora.conf に追加しました

  • デフォルトは false です

  • false の場合はバリデーションに失敗した場合、デフォルト値が採用されそのまま処理は継続します

  • true の場合はバリデーションに失敗した場合、エラーとしてセッションを破棄します

    • セッションウェブフック session.destroyed の reason には validate_error が含まれます

• [ADD] セッションウェブフック session.created のウェブフック処理中に問題が発生した際に session.destroyed の reason に webhook_error が含まれるようになりました

• [ADD] セッションウェブフックがエラーになった理由を、 session_webhook_error.jsonl ログに reason として出力するようにしました

• [FIX] セッションウェブフックの戻り値の JSON が不正な場合に、センシティブデータの処理をしていた問題を修正しました

• [FIX] セッションウェブフックの戻り値が JSON オブジェクトではない場合に処理が失敗していた問題を修正しました

録画アーカイブイベントウェブフック機能

• [ADD] 録画アーカイブ失敗時のウェブフック archive.failed に split と split_only と split_index を含むようにしました

• [FIX] 分割録画にもかかわらず、録画アーカイブ失敗時のウェブフック archive.failed に分割録画ファイルが含まれない問題を修正しました

  • 一括と分割録画の両方が有効な場合、 filename と file_path と split_filename と split_file_path が含まれるようになります

  • 分割録画が有効な場合、 split_filename と split_file_path が含まれるようになります

  • 分割録画のみの場合、 filename と file_path は含まれなくなります

• [ADD] テスト向け API として録画失敗を意図的に起こす FailArchive API を追加しました

  • 録画が実行されている指定した client_id の録画を失敗させます

  • イベントウェブフックの録画失敗ウェブフック archive.failed を意図的に発生させることができます

イベントウェブフック connection.destroyed の reason の破壊的変更

• [CHANGE] イベントウェブフック connection.destroyed に含まれる reason の変更を行いました

  • 今までは disconnect_api_reason と同様、コネクション切断系 API で指定した reason 値、または未指定の場合は null が含まれていましたが、 今回の変更で normal / disconnected_api / session_destroyed / lifetime_expired のいずれかが含まれるようになりました

  • normal は通常のコネクション破棄

  • disconnected_api はコネクション切断系 API でコネクション破棄

  • session_destroyed はセッションライフタイムによりセッションの期限が切れた、または TerminateSession API によってセッション強制破棄されたことでのコネクション破棄

  • lifetime_expired はコネクションライフタイムによりコネクションの期限が切れたことによるコネクション破棄

• [ADD] sora.conf にイベントウェブフック connection.destroyed に含まれる reason の値を、 disconnect_api_reason に含まれる値と同じにする移行用の設定 legacy_event_webhook_connection_destroyed_reason を追加しました

  • デフォルトは false です

  • 設定を true にした場合、 disconnect_api_reason の項目が無い場合は null が含まれます

    • また、コネクションライフタイム機能で切断したか際の判断ができなくなります

  • この設定は 2024 年 12 月リリース予定の Sora にて廃止します

録画機能音ズレ問題の改善

この問題の改善はレガシー録画、セッション録画の両方で行っています。

Chrome / Edge 側のバグにより、録画機能利用時に replaceTrack などを利用して MediaStreamTrack を削除し、 一定時間経過後に新しく MediaStreamTrack を追加した際に、音声パケットに関連するタイムスタンプと NTP タイムスタンプが正しく出力されない問題あります。

この問題により Chrome / Edge では録音/録画したファイルにて音ズレが発生してしまう場合がありました。

今回、新しく利用できるようになった RTP ヘッダー拡張 abs-capture-timestamp を利用する事で、 音声タイムスタンプを実際の値に推測する機能を導入することでこの問題に対応しました。

この問題は Safari / Safari Technology Preview では RTP ヘッダー拡張 abs-capture-timestamp が音声パケットに含まれてこないため、 改善することができません。

• [CHANGE] rtp_hdrext_abs_capture_time のデフォルトを true に変更しました

• [FIX] RTP ヘッダー拡張録画機能の音声タイムスタンプの推測機能を利用し、Chromium ベースのブラウザで録音/録画を行った際、音ズレが発生する問題を修正しました

  • abs-capture-time が利用できない場合は今まで通り音ズレが発生する場合があります

OBS WHIP対応

これは実験的機能です

• [CHANGE] ウェブフックの sora_client に含まれる type を OBS-Studio から OBS-Studio-WHIP に変更しました

  "sora_client": {
    "raw": "Mozilla/5.0 (OBS-Studio/30.1.0; Mac OS X; ja-JP)",
    "type": "OBS-Studio-WHIP",
    "version": "30.1.0",
    "environment": "environment":"Mozilla/5.0 (OBS-Studio/30.1.0; Mac OS X; ja-JP)"
  },
  

• [ADD] sora.conf に OBS WHIP で TURN を利用する whip_turn を追加しました

  • この設定は OBS が正式に TURN へ対応したタイミングで廃止します

• [ADD] OBS WHIP/WHEP で将来的に必須になる rtcp-mux-only に対応しました

  • https://datatracker.ietf.org/doc/html/draft-ietf-wish-whip#name-sdp-bundle

  • https://datatracker.ietf.org/doc/html/rfc9143

  • https://datatracker.ietf.org/doc/html/rfc8858

• [ADD] OBS WHIP で H.265 (HEVC) に対応しました

  • OBS 30.1 ではまだ WHIP での H.265 はサポートされていません

OBS WHEP 対応

これは実験的機能です

OBS での WebRTC/WHEP に対応しました。WebRTC で送られてくる音声と映像を WHEP ソースとして利用する事ができます。

• [ADD] OBS WHEP に対応しました

  • Opus と H.264 の組み合わせのみ利用できます

  • WHEP での接続は複数の配信が発生したタイミングで切断されます

  • WHEP での接続は複数の配信が存在するチャネルには接続できません

  • OBS 30.1 ではまだ WHEP に対応していません

• [ADD] sora.conf に OBS (WHEP) を有効にする whep を追加しました

  • デフォルトは false です

  • https://datatracker.ietf.org/doc/html/draft-ietf-wish-whep

• [ADD] sora.conf に OBS WHEP の Bearer トークンを認証ウェブフックの metadata に対応させるキーを指定する whep_bearer_token_metadata_key を追加しました

  • OBS WHEP からの接続についても Bearer トークンを利用した認証機能が利用できます

  • デフォルトは未指定です

• [ADD] WHEP 向けエンドポイント URL https://example.com/whep/<channel-id> を追加しました

• [ADD] WHEP 向けリソース URL https://example.com/whep-resource/<channel-id>/<secret> を追加しました

  • PATCH と DELETE メソッドに対応しています

• [ADD] WHEP を利用した際、認証ウェブフックに whep: true を追加しました

  • WHEP を利用していない接続の場合はこの項目は含まれません

• [ADD] OBS WHEP で User-Agent として送られてくる情報を sora_client としてウェブフックで送信するようにしました

  • "raw": "Mozilla/5.0 (OBS-Studio/31.0.0; Mac OS X; ja-JP)"

  • "type": "OBS-Studio-WHEP"

  • "environment": "environment":"Mozilla/5.0 (OBS-Studio/31.0.0; Mac OS X; ja-JP)"

  • "version": "31.0.0"

• [ADD] sora.conf に OBS WHEP で TURN を利用する whep_turn を追加しました

  • この設定は OBS が正式に TURN へ対応したタイミングで廃止します

詳細は OBS (WHEP) 対応機能 をご確認ください。

クラスター機能

これは実験的機能です

• [UPDATE] ListClusterNodes API にライセンス情報を追加しました

  • license_type

  • license_serial_code

  • license_max_connections

• [UPDATE] ListClusterNodes API にエラー情報を追加しました

  • ノードに接続ができなかった場合、そのノード情報に error を含めるようにしました

• [CHANGE] 最大ノード数ライセンスと通常ライセンスが同一クラスターで混在できなくなりました

• [CHANGE] sora.conf の contact_node_name_list を廃止しました

  • 今後は RegisterClusterNode API を利用してください

• [CHANGE] sora.conf の cluster_auto_reconnect を廃止しました

  • クラスター機能の自動での再接続は常に有効になります

• [CHANGE] JoinCluster API の名前だけを変更した RegisterClusterNode API を追加しました

  • RegisterClusterNode API は JoinCluster API とまったく同じ動作をします

  • JoinCluster API は 2024 年 12 月にリリース予定の Sora で廃止します

• [ADD] クラスター利用時に以下の API でクラスター全体の結果を返せる仕組みを追加しました

  • API に local を追加し false を指定した場合はクラスター全体の結果を返します

  • local のデフォルトは true です

  • ListConnections API

  • ListChannels API

  • GetStatsAllConnections API

  • ListRtcStats API

  • ListUserAgentStats API

  • クラスターのローリングアップデート中に local=false は利用できません

• [FIX] InitCluster API で指定するノードが全て同一バージョンでは無い場合、エラーを返すように修正しました

クラスターテンポラリーノード機能

これは実験的機能です

クラスターの維持に影響しない一時的なノードを追加できるようになりました。 テンポラリーノードを利用する事でスケールアウト/スケールインが容易になります。

• [ADD] sora.conf にテンポラリーノードとして利用する cluster_temporary_node を追加しました

  • デフォルトは false です

  • この設定は cluster が true の時のみ有効です

  • この機能は 最大ノード数ライセンス のみ有効です

    • 最大ノード数ライセンス を利用していない場合は cluster_temporary_node が true の場合、起動できません

  • テンポラリーノードはクラスター構成を維持するためのノードとしては認識されません

  • テンポラリーノードに障害が発生してもライセンスで決められた最大同時接続数の合計を維持する機能による接続数の維持は行われません

  • テンポラリーノードはクラスターへの登録には RegisterClusterNode API を利用してください

  • テンポラリーノードは停止時にクラスターから消去されます

  • テンポラリーノードを再起動した場合、クラスターには自動で参加しません。再度 RegisterClusterNode API を利用して登録してください

  • テンポラリーノードだけでクラスターを構築する事はできません

  • テンポラリーノードは PurgeClusterNode API でノードを消去することはできません

  • テンポラリーノードは InitCluster API で初期化することはできません

  • テンポラリーノードはクラスターの全てのノードが 2024.1.0 以降である必要があります

• [UPDATE] ListClusterNodes API に temporary_node: <boolean> 項目を追加しました

詳細は テンポラリーノード機能 をご確認ください。

ライセンスで決められた最大同時接続数の合計を維持する機能

これは実験的機能です

クラスターのノードが離脱した際に、合計接続数を残りのノードで維持する機能を追加しました。

• [ADD] クラスターでライセンスの同時接続数の合計を維持する機能を追加しました

  • この機能は cluster が true の場合にのみ有効です

  • この機能は 最大ノード数ライセンス のみ有効です

  • 同時接続数が 100 の 3 ノードのクラスターで動作させた場合に、 1 ノードが離脱した際、残りの 2 ノードが最大同時接続数が 150 に一時的に引き上げられ、合計での接続数を維持します その後、障害が発生していたノードが復旧した歳には、最大同時接続数は 100 に戻ります 100 を超えている接続は切断されたりはしません

詳細は ライセンスで決められた最大同時接続数の合計を維持する機能 をご確認ください。

クラスターリレー機能

これは実験的機能です

クラスター利用時に、複数のノードから同一チャネルに参加できる仕組みを追加しました。

• [ADD] sora.conf にクラスター利用時に複数ノードから同一チャネルに接続できる機能を実現する cluster_relay の設定を追加しました

  • この機能は cluster が true の場合にのみ利用できます

  • デフォルトで true が設定されています

  • クラスターリレー機能は 最大ノード数ライセンス のみで利用できます

    • 最大ノード数ライセンス を利用していない場合は cluster_relay が true になっていても、リレー機能は利用できません

  • クラスターリレー機能は "multistream": false では利用できません

  • リレー機能はクラスターの全てのノードが 2024.1.0 以降である必要があります

  • 詳細は リレー機能 をご確認ください

• [ADD] GetStatsReport API にクラスターリレー機能の統計情報を追加しました

  • この統計データは厳密なデータではないため、参考程度にご利用ください

  • ノードが削除された場合でも再起動するまでは統計情報は残り続けます

  • cluster_relay

    • [{"node_name": "sora-01@192.0.2.100", "total_sent_byte_size": 5000, "total_received_byte_size": 5000, ...]

  • node_name

    • 対象ノード名

  • total_sent_byte_size

    • 対象ノードへリレー機能で送信したバイト数の合計

  • total_received_byte_size

    • 対象ノードからリレー機能で受信したバイト数の合計

  • total_sent

    • 対象ノードからリレー機能で送信したパケット数の合計

  • total_received

    • 対象ノードからリレー機能で受信したパケット数の合計

• [CHANGE] リレー機能利用時には認証が 2 回発生する場合があります

  • 詳細は クラスターリレー機能利用時に認証が 2 回行われる場合がある をご確認ください

• [CHANGE] リレー機能利用時には multistream と spotlight が既存セッションと異なる場合の挙動 の挙動が変わり、接続数が 0 の場合に multistream と spotlight の指定が既存セッションと異なる場合でもセッションが破棄されなくなります

  • この挙動は 2024 年 12 月リリースの Sora にてリレー機能を利用しない場合でも反映される予定です

詳細は リレー機能 をご確認ください。

クラスターリレー機能利用時のアフィニティ機能

これは実験的機能です

クラスターリレー機能利用時に一定の同時接続数まで特定のノードに同一セッションの接続を集約する機能を追加しました。

• [ADD] sora.conf にリレー機能を利用する際に、アフィニティ機能(同一セッションへの接続を同一ノードに寄せる) かどうかを指定する default_cluster_affinity の設定を追加しました

  • デフォルトで true が設定されています

  • この機能は sora.conf の cluster が true の場合にのみ利用できます

  • この機能は sora.conf の cluster_relay が true の場合にのみ利用できます

    • 最大ノード数ライセンス を利用していない場合は sora.conf の cluster_relay が true になっていても、リレー機能やアフィニティ機能は利用できません

  • true の場合は一定数の接続までは特定のノードに接続を集約します

    • 同時接続数がライセンス最大値の場合はリダイレクトが発生します

  • false を指定すると、可能な限りリダイレクトをせずにそのノードでリレーが行われます

    • 同時接続数がライセンス最大値の場合はリダイレクトが発生します

• [ADD] sora.conf にアフィニティを行う 1 ノード、1 セッションあたりの最大同時接続数を指定する cluster_affinity_threshold を追加しました

  • デフォルトは 10 です

  • 1 ノード、1 セッションあたりの同時接続数が cluster_affinity_threshold 未満のノードがあれば、同じノードに新規接続が割り振られます

• [ADD] 認証成功時の払い出しで cluster_affinity の払い出し を払い出すことでコネクション単位でのアフィニティ機能を利用するかどうかを指定できる機能を追加しました

  • 払い出しをしない場合は sora.conf の default_cluster_affinity の値が利用されます

音声ストリーミング

音声ストリーミング機能のエラー処理を充実させました。

• [ADD] audio_streaming_url に接続ができない場合、再接続を試みる機能を追加しました

• [ADD] audio_streaming_url への接続を諦める機能を追加しました

  • 接続を諦めた場合、再接続を試みるには一度クライアントを切断する必要があります

• [ADD] audio_streaming_url に接続ができない場合、再接続を試みる回数を指定する audio_streaming_max_retries を追加しました

  • 最大リトライ回数まで再接続を試みても接続ができない場合は接続を諦めます

  • デフォルトは 0 です

  • 0 にした場合は常に再接続を試みます

  • 0..10 の間で指定できます

• [ADD] audio_streaming_url に接続ができない場合、再接続を試みる間隔を指定する audio_streaming_retry_interval を追加しました

  • デフォルトは 5 s です

  • 0 にした場合は音声パケットが送られてきたタイミングで再接続を試みます

  • 0..60 s の間で指定できます

• [ADD] audio_streaming_url からステータスコード 5xx が返ってきた場合、再接続を試みる機能を追加しました

  • 最大リトライ回数まで再接続を試みても接続ができない場合は接続を諦めます

  • 再接続の回数は audio_streaming_max_retries を利用します

  • 再接続の間隔は audio_streaming_retry_interval を利用します

• [ADD] audio_streaming_url への接続を諦めた際、イベントウェブフック audio-streaming.failed を送信する機能を追加しました

  • 諦めるのはコネクション単位のため、イベントウェブフックを送信します

  • このウェブフックは ignore_audio_streaming_webhook の影響は受けません

• [ADD] イベントウェブフック audio-streaming.failed を送信しない設定 ignore_audio_streaming_failed_webhook を追加しました

  • デフォルトは true です

  • true にした場合は audio-streaming.failed イベントウェブフックを送信しません

• [ADD] audio_streaming_url から "type": "error" が含まれる JSON が送られてきた際、音声ストリーミングサーバーへの接続を諦める機能を追加しました

• [ADD] audio_streaming_url への接続を諦めた際、セッションに参加している全てのコネクションにシグナリング通知 audio-streaming.failed を送信する機能を追加しました

  • デフォルトは false です

  • signaling_notify_audio_streaming_failed を true にすることで有効になります

• [FIX] 音声ストリーミング audio-streaming.started のウェブフック処理中にエラーになった場合、セッションが破棄されてしまう問題を修正しました

統計ウェブフック機能

実験的機能です

統計エクスポーター に変わる、 統計ウェブフック機能 を追加しました。

• [ADD] sora.conf に統計ウェブフックの送信先を指定する stats_webhook_url を追加しました

• [ADD] sora.conf に統計ウェブフックログを出力するかどうかを指定する stats_webhook_log を追加しました

  • デフォルト false です

  • デフォルトではログを出力しません。ログを出力したい場合は true に設定してください

• [ADD] sora.conf に統計ウェブフック type: connection.rtc を無視するかどうかを指定する ignore_connection_rtc_webhook を追加しました

  • デフォルト false です

• [ADD] sora.conf に stats_webhook_worker_number を追加しました

• [ADD] 統計ウェブフックにクライアントの RTC 統計情報を送信する type: connection.rtc を追加しました

  • これは統計エクスポーターの "type": "connection.user-agent" と同じデータをウェブフックとしてリクエストを送信します

  • 統計エクスポーターでは HTTP/2 を利用して送信していましたが、統計ウェブフックは HTTP/1.1 で送信します

• [ADD] GetStatsReport API に統計ウェブフックの成功数の項目 total_successful_stats_webhook を追加しました

• [ADD] GetStatsReport API に統計ウェブフックの失敗数の項目 total_failed_stats_webhook を追加しました

詳細は 統計ウェブフック機能 をご確認ください。

RTC 統計 (ユーザエージェント機能)

統計ウェブフック機能追加に伴い、ユーザーエージェント統計から RTC 統計へ名前を変更します。 ユーザエージェント機能は 2025 年 6 月リリース予定の Sora で廃止します。

• [ADD] sora.conf に RTC 統計機能をデフォルトを指定する default_rtc_stats を追加しました

  • デフォルトは true です

  • true の場合、 Sora はクライアントへ RTC 統計の送信を要求します

• [ADD] 認証成功時の払い出しに rtc_stats の払い出し を追加しました

  • 未指定の場合は default_rtc_stats の値が利用されます

• [ADD] ListRtcStats API を追加しました

• [ADD] ListChannelRtcStats API を追加しました

• [ADD] GetRtcStats API を追加しました

• [ADD] 実験的機能として sora.conf に rtc_stats_log を追加しました

  • デフォルトで false です

  • rtc_stats 項目個別に rtc_stats.jsonl にログを出力します

• [FIX] ユーザーエージェント統計情報の認証成功時払い出し指定が無視されていた問題を修正しました

• [FIX] ユーザーエージェント統計情報の GetUserAgentStats の戻り値の stats を user_agent_stats に修正しました

セッションライフタイム機能

実験的機能です

セッションに対してライフタイム (破棄されるまでの時間) を設定する機能を追加しました。

• [ADD] セッションのライフタイムをセッションウェブフック session.created の戻り値で session_lifetime を指定できるようになりました

  • 秒 で指定してください

  • 最大 2,592,000 秒 (30 日) まで指定できます

  • セッション生成後に変更することはできません

  • session_lifetime が未指定の場合は 無制限 です

  • session.destroyed の reason に lifetime_expired が入ります

  • connection.destroyed の reason に session_destroyed が入ります

  • セッションのライフタイムが終了すると、セッションが破棄され切断します

  • セッションのライフタイムが終了すると、セッションウェブフック session.destroyed が送信されます

コネクションライフタイム機能

実験的機能です

コネクションに対してライフタイム (破棄されるまでの時間) を設定する機能を追加しました。

• [ADD] コネクションのライフタイムを認証ウェブフックの払い出しで connection_lifetime の払い出し を指定できるようになりました

  • 秒 で指定してください

  • 最大 2,592,000 秒 (30 日) まで指定できます

  • コネクション生成後に変更することはできません

  • connection_lifetime が未指定の場合は 無制限 です

  • connection.destroyed の reason に lifetime_expired が入ります

  • コネクションのライフタイムが終了すると、コネクションが破棄され切断します

  • コネクションのライフタイムが終了すると、コネクションウェブフック connection.destroyed が送信されます

  • コネクションのライフタイムよりセッションのライフタイムが優先されます

サイマルキャストマルチコーデック機能

実験的機能です

一つのサイマルキャストで複数のコーデックを利用する事ができる、サイマルキャストマルチコーデックを追加しました。

• [ADD] 複数の映像コーデックを同時に配信するサイマルキャストマルチコーデック機能に対応しました

  • サイマルキャストマルチコーデックの配信に対応した SDK のみで利用できます

    • 2024 年 12 月 時点で以下の SDK が実験的に対応しています

    • Sora C SDK

    • Sora C++ SDK

  • ブラウザを利用した場合、サイマルキャストマルチコーデック機能を利用して配信することはできません、視聴側は利用できます

• [ADD] sora.conf にてサイマルキャストコーデック機能を有効にするするかどうかを指定する simulcast_multicodec を追加しました

  • デフォルトは false です

  • simulcast_multicodec を true に設定するとサイマルキャストマルチコーデック機能が利用可能になります

• [ADD] シグナリング接続時に "simulcast_multicodec" 項目を追加しました

  • "simulcast_multicodec": true を指定する際には "simulcast": true を指定する必要があります

• [ADD] 認証ウェブフックに "simulcast_multicodec" 項目を追加しました

  • simulcast が true かつ simulcast_multicodec が true の時のみ含まれます

• [ADD] 認証成功時の払い出しで simulcast_multicodec を払い出した場合、サイマルキャストマルチコーデックを利用できるようになりました

  • sora.conf にて simulcast_multicodec が true に指定されている必要があります

  • "simulcast": true が指定されている必要があります

• [ADD] 認証成功時の払い出しで simulcast_codecs を指定できるようになりました

• [ADD] sora.conf にてサイマルキャストのデフォルトコーデックを設定する simulcast_codecs_file を指定できるようになりました

• [ADD] イベントウェブフック connection.{created, updated, destroyed} に simulcast_multicodec 項目を追加しました

  • simulcast が true かつ simulcast_multicodec が true の時のみ含まれます

• [ADD] コネクションログに simulcast_multicodec 項目を追加しました

  • 項目は必ず含まれます

• [ADD] "type": "offer" 時に simulcast_multicodec 項目を追加しました

  • 項目は必ず含まれます

詳細は サイマルキャストマルチコーデック をご確認ください。

H.264/H.265 B-frame 対応

実験的機能です

実験的機能として H.264 と H.265 の B-frame 向けの RTP ヘッダー拡張 に対応しました。

B-frame 向けの RTP ヘッダー拡張に対応している場合、 H.264/H.265 で B-frame を利用した配信/視聴が行えるようになります。

B フレームの録画には対応していません。

• [ADD] H.264 と H.264 で B-frame を利用する RTP ヘッダー拡張に対応しました

• [ADD] sora.conf に H.264 で B-frame を利用するかどうかを指定する h264_b_frame を追加しました

  • デフォルトは false です

• [ADD] sora.conf に H.265 で B-frame を利用するかどうかを指定する h265_b_frame を追加しました

  • デフォルトは false です

• [ADD] シグナリング type: connect 時に H.264 で B-frame を利用するかどうかを指定する h264_params: {"b_frame": true} を追加しました

  • デフォルトは false です

  • sora.conf にて h264_b_frame が true に指定されている必要があります

  • sora.conf にて signaling_h264_params が true に指定されている必要があります

• [ADD] シグナリング type: connect 時に H.265 で B-frame を利用するかどうかを指定する h265_params: {"b_frame": true} を追加しました

  • デフォルトは false です

  • sora.conf にて h265_b_frame が true に指定されている必要があります

  • sora.conf にて signaling_h265_params が true に指定されている必要があります

• [ADD] ウェブフックの video_h264_params に b_frame を追加しました

  • sora.conf の h264_b_frame が true に指定されていない場合は b_frame は含まれません

• [ADD] ウェブフックの video_h265_params に b_frame を追加しました

  • sora.conf の h264_b_frame が true に指定されていない場合は b_frame は含まれません

• [ADD] 認証成功時の払い出しで video_h264_params に b_frame を追加しました

  • デフォルトは false です

  • 接続時や払い出し時に未指定の場合はデフォルトの false が利用されます

• [ADD] 認証成功時の払い出しで video_h265_params に b_frame を追加しました

  • デフォルトは false です

  • 接続時や払い出し時に未指定の場合はデフォルトの false が利用されます

プレイアウト遅延機能

実験的機能です

プレイアウト遅延機能を追加しました。

プレイアウト遅延機能を利用することでフレームをどれくらい速くレンダリングする必要があるかを配信毎に指定できます。

• [CHANGE] sora.conf の RTP ヘッダー拡張 playout-delay を利用するかどうかを指定する rtp_hdrext_playout_delay のデフォルトを true に変更しました

• [ADD] sora.conf にプレイアウト遅延の最小値のデフォルトを指定する default_playout_delay_min_delay を追加しました

• [ADD] sora.conf にプレイアウト遅延の最大値のデフォルトを指定する default_playout_delay_max_delay を追加しました

• [ADD] 認証成功時の払い出しでプレイアウト遅延の最小値を指定する playout_delay_min_delay を追加しました

  • playout_delay_max_delay も一緒に指定する必要があります

• [ADD] 認証成功時の払い出しでプレイアウト遅延の最大値を指定する playout_delay_max_delay を追加しました

  • playout_delay_min_delay も一緒に指定する必要があります

詳細は プレイアウト遅延機能 をご確認ください。

メディア配信ワーカー

実験的機能です

配信ワーカー機能をメディア配信ワーカー機能に変更しました。

• [UPDATE] スポットライト機能をメディア配信ワーカーで利用できるようになりました

• [CHANGE] sora.conf の rtp_publish_worker_number を media_publish_worker_number に変更しました

WebSocket シグナリング時の HTTP ヘッダーを認証ウェブフックにコピーする機能

実験的機能です

• [ADD] sora.conf に WebSocket シグナリング接続時の HTTP ヘッダーを認証ウェブフックのヘッダーにコピーする copy_websocket_signaling_header_names を追加しました

  • デフォルトは未指定です

  • 大文字小文字は区別されません

  • copy_websocket_signaling_header_names = X-Forwarded-For, X-Real-IP, Tracestate のように指定してください

• [ADD] 認証ウェブフックログ auth_webhook.jsonl に copy_headers 項目を追加しました

  • 認証ウェブフックにコピーされたヘッダーを出力します

2023.2.7

バグフィックスアップデート

リリース:

2024-04-24

• [FIX] レガシー録画機能または録画機能(セッション単位)利用時の録画停止処理中に、新規コネクションが参加した際に、そのコネクションが切断されるまで、録画停止処理が完了しない問題を修正しました

• [FIX] レガシー録画機能にて録画停止処理中に録画の開始および StopRecording API 実行した際 RECORDING-INTERNAL-ERROR が返されていたのを STOPPING-RECORDING を返すように修正しました

• [FIX] クラスター有効時に、ごく稀にノード起動に失敗することがある問題を修正しました

2023.2.5

ホットフィックスアップデート

リリース:

2024-03-08

• [FIX] 録画機能で録画中、出力済の分割録画ファイルのファイルディスクリプタを掴み続ける問題を修正しました

2023.2.4

ホットフィックスアップデート

重要

このリリースはクラスターをご利用いただいているお客様にのみ提供しております。

リリース:

2024-02-27

• [FIX] クラスター利用時にでリーダーノードがダウンした場合に、他のノードのセッションも終了してしまう問題を修正しました

2023.2.3

バグフィックスアップデート

リリース:

2024-02-07

• [FIX] "multistream": false を指定して接続した場合に、配信/視聴ができない問題を修正しました

• [FIX] セッションウェブフックが一部の HTTP サーバーで正常に処理できず、エラーになる問題を修正しました

• [FIX] データチャネルの終了時にクライアント側で警告が出力される問題を修正しました

2023.2.2

バグフィックスアップデート

リリース:

2024-01-04

変更履歴

• [FIX] sora.conf の event_webhook_url が未指定の状態で録画を開始した場合、セッションが破棄されない問題を修正しました

• [FIX] ウェブフックで mTLS 利用時に、特定の条件下でクライアント証明書を送らなくなる問題を修正しました

  • ウェブフックで HTTPS を利用する場合は TLS 1.2 のみを利用するように変更しました

• [FIX] ウェブフックで mTLS 利用時に、 CA 証明書が指定されていない場合に OS 組み込みの証明書を利用できない問題を修正しました

• [FIX] 統計エクスポーターで mTLS 利用時に、 CA 証明書が指定されていない場合に OS 組み込みの証明書を利用できない問題を修正しました

• [FIX] 音声ストリーミングで mTLS 利用時に、 CA 証明書が指定されていない場合に OS 組み込みの証明書を利用できない問題を修正しました

• [FIX] API ログの書き込みに失敗した場合でも、 API の処理を中断しないように修正しました

• [FIX] PurgeClusterNode API の API ログ操作名が LeaveCluster となっていたのを PurgeClusterNode に修正しました

• [FIX] クラスターに参加済のノードが、別クラスターに対する JoinCluster API を受け入れてしまう問題を修正しました

• [FIX] 録画機能で大幅にパケットの到着が遅れている場合、分割録画に失敗することがある問題を修正しました

2023.2.0

メジャーアップデート

リリース:

2023-12-20

ハイライト

• セッション単位で録画する新しい録画機能を追加しました

  • 今までの録画機能は レガシー録画機能 と名前を変更しました

  • レガシー録画機能と新しい録画機能は別チャネルであれば同時に利用することができます

  • レガシー録画機能は 2025 年 12 月リリース予定の Sora にて廃止します

  • 詳細は 録画機能 (セッション単位) をご確認ください

• 接続単位で録画をブロックできる機能を追加しました

  • 今まではチャネルに参加している全ての接続が録画されていましたが、新しい録画機能では接続単位で録画をブロックできるようになりました

  • 新しい録画機能でのみ利用できます

• より大規模な配信を可能にする配信ワーカー機能を追加しました

  • 今まで音声や映像をクライアントに配信するワーカーは 1 つでしたが、配信するワーカーを複数にすることで、より多くのユーザーに配信することができるようになりました

• データチャネルの負荷を下げるために SCTP パケットのチェックサム計算を省略する機能を追加しました

  • 利用するにはクライアント側もチェックサム計算を省略する機能に対応している必要があります

• ウェブフックで IPv6 アドレスが利用できるようになりました

• ウェブフックなどでルート CA 証明書に OS 組み込みのものを利用するようにしました

正式版

• セッションウェブフック が正式版になりました

• DataChannel 経由のシグナリング が正式版になりました

• リアルタイムメッセージング機能 が正式版になりました

廃止情報

• sora.conf の legacy_log_format を廃止しました

  • 詳細は sora.conf の legacy_log_format の廃止 をご確認ください

• sora.conf の legacy_log_extension を廃止しました

  • 詳細は sora.conf の legacy_log_extension の廃止 をご確認ください

• sora.conf の legacy_webhook_audio_video_json_structure を廃止しました

  • 詳細は sora.conf の legacy_webhook_audio_video_json_structure の廃止 をご確認ください

破壊的変更

• sora.conf の signaling_notify_metadata を false にした場合でもシグナリング通知の data が含まれるようになりました

• sora.conf の以下の設定を全て false にした場合、シグナリング通知の data が含まれなくなりました

  • signaling_notify_metadata

  • signaling_notify_client_id

  • signaling_notify_bundle_id

  • signaling_notify_connection_id

  • signaling_notify_connection_created_timestamp

• 実験的機能のクラスター機能利用時のセッションウェブフック session.destroyed に connections が含まれなくなりました

• 実験的機能のクラスター機能のログを cluster.jsonl に出力するよう変更しました

• 実験的機能のセッションウェブフック audio-streaming.started に max_connections と total_connections が含まれなくなりました

• 実験的機能のセッションウェブフック audio-streaming.started に max_connections と total_connections が含まれなくなりました

変更履歴

• [CHANGE] ウェブフックなどで利用するルート CA 証明書に OS 組み込みのものを利用するように変更しました

  • Ubuntu の場合は apt install ca-certificates でインストールされる証明書を利用します

  • RHEL の場合は dnf install ca-certificates でインストールされる証明書を利用します

  • 詳細は ウェブフックリクエストなどの送信先サーバー証明書の検証に利用する OS 組み込みのルート CA 証明書について をご確認ください

• [UPDATE] DataChannel を利用したメッセージングのみで接続する場合に role が sendrecv 以外でも接続ができるようになりました

• [ADD] シグナリング "type": "offer" に channel_id と session_id を追加しました

• [ADD] connection.jsonl の ice_connection_state に ICE コネクションステート checking と disconnected だった時間を追加しました

• [ADD] Sora が利用している Erlang VM の設定を追加できる環境変数 SORA_ADDITIONAL_ERL_ARGS を追加しました

• [ADD] 認証成功時の払い出しに検証用の RTP パケットロスシミュレーターの設定値、 rtp_packet_loss_simulator_incoming と rtp_packet_loss_simulator_outgoing が指定できるようになりました

• [ADD] sora.jsonl と internal.jsonl に UUIDv4 を Base32 でエンコードしたユニークな ID を含めるようにしました

  • "id": "base32(uuidv4)"

• [FIX] データチャネルで利用する SCTP のストリーム ID 採番を RFC 8832 に準拠させました

  • https://www.rfc-editor.org/rfc/rfc8832.html

• [FIX] 録画機能で H.264 利用時に送られてくる分割ペイロードが壊れている場合は処理をスキップするように修正しました

OBS WHIP

これは実験的機能です

• [ADD] OBS WHIP で User-Agent として送られてくる情報を sora_client としてウェブフックで送信するようにしました

  "sora_client": {
    "raw": "Mozilla/5.0 (OBS-Studio/30.0.0; Mac OS X; ja-JP)",
    "type": "OBS-Studio",
    "version": "30.0.0",
    "environment": "environment":"Mozilla/5.0 (OBS-Studio/30.0.0; Mac OS X; ja-JP)"
  },
  

• [ADD] OBS WHIP で AV1 が動作するようにしました

  • OBS WHIP で AV1 を配信する仕組みは 2024 年 12 月 現在、 OBS には組み込まれていません

• [FIX] WHIP 利用時に認証ウェブフックの項目に ignore_disconnect_websocket が含まれない問題を修正しました

  • 常に false が含まれます

転送フィルター機能

これは実験的機能です

転送フィルターに version や metadata が指定できるようになりました。

version を指定することで、転送フィルターの更新 API が並列で実行されても期待した値に変更することができるようになりました。

• [ADD] 転送フィルターに version を設定できるようになりました

• [ADD] 転送フィルターに metadata を設定できるようになりました

• [ADD] 転送フィルター API CreateChannelForwardingFilter と CreateConnectionForwardingFilter に version を指定できるようになりました

• [ADD] 転送フィルター API CreateChannelForwardingFilter と UpdateChannelForwardingFilter に metadata を指定できるようになりました

• [ADD] 転送フィルター API CreateConnectionForwardingFilter と UpdateConnectionForwardingFilter に metadata を指定できるようになりました

• [ADD] 転送フィルター API UpdateChannelForwardingFilter と UpdateConnectionForwardingFilter API に指定した expected_version が既存の version と一致していない場合は更新エラーになるようになりました

  • expected_version が既存のバージョンと一致した場合のみ desired_version で指定した値で version の値を更新します

• [ADD] セッションウェブフックの戻り値に version と metadata を指定できるようになりました

• [ADD] 認証成功の払い出し時に version と metadata を指定できるようになりました

• [ADD] シグナリング時に version と metadata を指定できるようになりました

セッション API

• [ADD] 指定したセッションを取得する GetSession API を追加しました

  • channel_id を指定してセッションを取得します

• [ADD] セッション一覧を取得する ListSessions API を追加しました

  • 全てのセッション一覧を取得します

録画機能

• [ADD] sora.conf に単一録画ファイルと分割録画ファイルの両方を出力する機能を有効にするかどうかを指定する recording_dual_output を追加しました

  • デフォルトは true です

  • false に指定した場合は 単一録画ファイルと分割録画ファイルの両方が出力 のパターンを指定できなくなります

• [ADD] sora.conf に録画期限の最大値を指定する recording_max_expire_time を追加しました

  • デフォルトは 86400 s です

  • 設定できる最大値は 86400 s です

  • レガシー録画機能では一括録画と一括＆分割録画で expire_time が指定できます

  • 新しい録画機能(セッション単位)では一括録画、分割録画、一括＆分割録画で expire_time が指定できます

• [ADD] sora.conf に分割録画時の分割時間の最大値を指定する recording_max_split_duration を追加しました

  • デフォルトは 86400 s です

  • 設定できる最大値は 86400 s です

• [ADD] sora.conf に一括録画を含む場合に録画期限の設定を要求する recording_expire_time_required を追加しました

  • この設定は一括録画時に録画ファイルが大きくなりすぎるのを防ぐための設定です

  • デフォルトは false です

  • この設定を true にした場合、一括録画を含む場合に expire_time が必須になります

  • この設定を true にした場合、レガシー録画機能では expire_time に 0 以外の値を指定する必要があります

  • この設定を true にした場合、新しい録画機能(セッション単位)では expire_time の値を指定する必要があります

  • この設定を true にした場合でも分割録画のみの場合は expire_time は必須になりません

新しい録画機能 (セッション単位)

今までの録画機能は レガシー録画機能 と名前を変更しました。

レガシー録画機能と新しい録画機能は別チャネルであれば同時に利用することができます。

• [ADD] sora.conf にレガシー録画を有効にするかどうか指定する legacy_recording を追加しました

  • デフォルトは true です

  • false にした場合、レガシー録画機能が利用できなくなります

  • この設定は移行用の設定で、 2025 年 12 月リリース予定の Sora にて廃止します。

• [ADD] セッションウェブフック session.created 時に "recording": true を指定することで録画を開始します

• [ADD] セッションウェブフック session.created 時に "recording_expire_time" を指定することができるようになりました

  • セッション破棄時に録画は自動で終了します

  • セッション破棄前に期限が来た場合はそこで録画は終了します

• [ADD] セッションウェブフック session.created 時に "recording_split_duration" を指定することができるようになりました

• [ADD] セッションウェブフック session.created 時に "recording_split_only" を指定することができるようになりました

• [ADD] セッションウェブフック session.created 時に "recording_metadata" を指定することができるようになりました

• [ADD] セッションウェブフック recording.started を追加しました

• [ADD] セッションウェブフック recording.report を追加しました

• [ADD] 新しい録画用の StartRecording API を追加しました

  • セッション破棄時に自動で録画は終了します

  • expire_time がオプションになっています

  • expire_time デフォルトは未定義です

• [ADD] 新しい録画用の StopRecording API を追加しました

詳細については 録画機能 (セッション単位) をご確認ください。

移行については レガシー録画機能から新しい録画機能 (セッション単位) への移行 をご確認ください。

新しい録画機能 (セッション単位) における接続単位の録画ブロック機能

これは実験的機能です

この機能は新しい録画機能 (セッション単位) でのみ利用できます。レガシー録画機能では利用できません

• [ADD] 認証成功時に "recording_block": true を払い出すことで、その接続の録画をブロックし、録画ファイルの出力を拒否できるようになりました

  • これは録画が有効になっていない場合に払い出しても問題ありません

  • この値を途中で変更することはできません

• [ADD] イベントウェブフック connection.{created, updated, destroyed} の data に "recording_block" の項目を追加しました

  • 認証成功時に "recording_block": true を払い出していれば true に、それ以外は false になります

シグナリング通知メタデータ

sora.conf で signaling_notify_metadata を false にした際の挙動を変更しました。

• [CHANGE] sora.conf の signaling_notify_metadata を false にした際でも data 項目が含まれるようになりました

  • data の metadata と authn_metadata と authz_metadata は含まれません

• [CHANGE] sora.conf で以下の設定を全て false にした場合、シグナリング通知の data が含まれなくなりました

  • signaling_notify_metadata

  • signaling_notify_client_id

  • signaling_notify_bundle_id

  • signaling_notify_connection_id

  • signaling_notify_connection_created_timestamp

• [FIX] sora.conf で signaling_notify_metadata を false にした際にも、シグナリング通知の data 項目の authn_metadata と authz_metadata が含まれてしまう問題を修正しました

外部への HTTP リクエストに HTTP ヘッダーを追加

ウェブフックや統計エクスポーター、音声ストリーミングを利用した際の外部への HTTP リクエストに、 x-sora- prefix とは別に sora- prefix の HTTP ヘッダーを追加しました。

これは RFC 6648 による x- prefix の非推奨化に準拠するためです。

今後 x-sora- prefix は非推奨になります。 現時点で具体的な時期は決まっていませんが、将来的に 1 年以上の移行期間を設けて廃止する予定です。

• [ADD] セッションウェブフックに sora-session-webhook-type ヘッダーを追加しました

  • すでにある x-sora-session-webhook-type ヘッダーは将来的に廃止予定です

• [ADD] イベントウェブフックに sora-event-webhook-type ヘッダーを追加しました

  • すでにある x-sora-event-webhook-type ヘッダーは将来的に廃止予定です

• [ADD] 統計エクスポーターに sora-stats-exporter-type ヘッダーを追加しました

  • すでにある x-sora-stats-exporter-type ヘッダーは将来的に廃止予定です

• [ADD] セッションウェブフックに sora-session-id ヘッダーを追加しました

• [ADD] イベントウェブフックに sora-connection-id ヘッダーを追加しました

• [ADD] イベントウェブフックに sora-session-id ヘッダーを追加しました

ウェブフック

• [CHANGE] セッションウェブフック audio-streaming.started に max_connections と total_connections が含まれなくなりました

• [CHANGE] セッションウェブフック audio-streaming.stopped に max_connections と total_connections が含まれなくなりました

• [CHANGE] クラスター機能利用時のセッションウェブフック session.destroyed に connections が含まれなくなりました

• [ADD] sora.conf にウェブフックで IPv6 利用する webhook_ipv6 を追加しました

  • デフォルトは false です

  • この設定を有効にしない限りウェブフックで IPv6 は利用できません

• [ADD] sora.conf にイベントウェブフック connection.updated の送信間隔を変更する connection_updated_webhook_interval を追加しました

  • デフォルトは 1 min です

  • 最小は 1 min です

  • 最大は 10 min です

  • 時間単位は min のみが指定できます

• [ADD] sora.conf に 録画イベントウェブフック split-archive.available を送信しないようにする ignore_split_archive_available_webhook を追加しました

  • デフォルトは false です

• [ADD] 接続イベントウェブフック connection.{created, updated, destroyed} に ICE コネクションステートが checking と disconnected だった時間の項目を追加しました

  • data.ice_connection_state.total_checking_duration_ms に checking だった合計時間(ミリ秒)が入ります

  • data.ice_connection_state.total_disconnected_duration_ms に disconnected だった合計時間(ミリ秒)が入ります

• [ADD] 認証ウェブフックに spotlight_focus_rid と spotlight_unfocus_rid を追加しました

  • spotlight が true の時だけ追加されます

• [ADD] 接続イベントウェブフック connection.{created, updated, destroyed} に ICE コネクションステートの checking と disconnected の時間を通知する項目を追加しました

  • ice_connection_state 項目を追加しました

  • ice_connection_state に total_checking_duration_ms に checking だった合計時間(ミリ秒)が入ります

  • ice_connection_state に total_disconnected_duration_ms に disconnected だった合計時間(ミリ秒)が入ります

  "data": {
    "ice_connection_state": {
      "total_checking_duration_ms": 0,
      "total-disconnected_duration_ms": 0
    }
  }
  

• [ADD] セッションウェブフック session.updated を追加しました

  • クラスターが有効時には connections は含まれません

  • 録画機能 (セッション単位) 有効時に recording 項目が含まれます

• [ADD] セッションウェブフック session.destroyed に reason が含まれるようになりました

  • reason には以下が含まれます

    • normal

      • 正常終了

    • terminated_api

      • TerminateSession API を利用した終了

    • abort

      • 異常終了

• [ADD] sora.conf にセッションウェブフック session.updated を送信しないようにする ignore_session_updated_webhook を追加しました

  • デフォルトは false です

• [ADD] sora.conf にセッションウェブフック session.updated の送信間隔を変更する session_updated_webhook_interval を追加しました

  • デフォルトは 1 min です

  • 最小は 1 min です

  • 最大は 10 min です

  • 時間単位は min のみが指定できます

• [FIX] 認証ウェブフックで simulcast_rid は spotlight が true の場合は追加しないようにしました

  • simulcast が true かつ spotlight が false の時だけ追加されます

データチャネル

• [ADD] データチャネルの SCTP のパケットのチェックサム計算を省略する仕組みを追加しました

  • データチャネルは DTLS レイヤーでデータ保護が行われているため、 SCTP のチェックサムは追加の整合性を得ることができないため省略することができます

  • クライアント側もチェックサム計算を省略する機能に対応している必要があります

  • データチャネル利用時の CPU リソースがクライアント、SFU ともに節約されます

  • https://datatracker.ietf.org/doc/html/draft-ietf-tsvwg-sctp-zero-checksum

• [ADD] SCTP のチェックサムを省略した回数の統計情報を追加しました

  • total_received_sctp_zero_checksum

  • total_sent_sctp_zero_checksum

クラスター機能

これは実験的機能です

Sora 2023.1.x で構築されているクラスターは Sora 2023.2.x へローリングアップデートで移行できます。

警告

2023.2.x から 2023.1.x へのローリングアップデートは行えません。クラスターを再構築する必要があります。

• [CHANGE] クラスター関連のログは cluster.jsonl に出力するよう変更しました

• [ADD] 最新のバージョンと 1 世代前のバージョンの Sora ノードが混在する状態でのクラスター運用ができるようになりました

  • 全てのクラスターに参加するノードが同じバージョンになるまでは 1 世代前のバージョンと混在できる仕組みを追加しました

  • Sora 2023.2.x と 2023.1.x で、特定のノードのアップデートが難しい場合でも、先に他のノードをアップデートすることができるようになります

  • クラスターに 1 世代前のバージョンのノードが混在している場合、新しい接続は全て古いバージョンのクラスターの仕組みを利用します

  • 全てのノードが新しいバージョンのクラスターになったタイミングで、新しいバージョンのクラスターの仕組みを利用しはじめます

詳細については クラスター機能 をご確認ください。

注釈

InitCluster API でクラスターを初期化する際には、新旧バージョンは混在させないでください。また Sora 2023.2.x で構成されたクラスターに JoinCluster API で Sora 2023.1.x のノードを参加させることはできません。

メディア配信ワーカー機能

これは実験的機能です

メディア配信ワーカー機能は音声や映像を配信するワーカーを複数用意することで、 1 チャネルで高ビットレートの映像をより多くのクライアントに配信することができるようになります。

• [ADD] sora.conf に音声や映像の 1 配信に利用するメディア配信ワーカー数を指定する media_publish_worker_number を追加しました

  • デフォルトのメディア配信ワーカー数は 1 です

  • 同時に 100 クライアント以上へ配信する場合はまず 10 を設定することを推奨します

  • ワーカー数が 10 であれば 1 チャネル 1000 クライアント以上の配信ができるようになります

  • 最小は 1 で、最大は 500 です

ワーカー数の設定を 10 以上で検討している場合はまずサポートにご相談ください。

詳細については メディア配信ワーカー機能 をご確認ください。

シグナリング通知メタデータ拡張機能

これは実験的機能です

• [ADD] 認証成功時に、シグナリング通知メタデータ拡張の初期値を払い出す signaling_notify_metadata_ext を追加しました。

  • sora.conf にて signaling_notify_metadata_ext を有効にしている必要があります

  • デフォルトは {} です

統計エクスポーター

これは実験的機能です

• [ADD] sora.conf に統計エクスポーターをデフォルトで有効にするかどうかの default_stats_exporter を追加しました

  • デフォルトは true です

• [ADD] 認証成功時の払い出しで接続単位で統計エクスポーターを有効にするかどうかを指定する stats_exporter を追加しました

  • false を設定した場合は stats_collector_url が指定されていたとしても統計情報がエクスポートされません

H.265

これは実験的機能です

2024 年 12 月 現在、WebRTC H.265 のプロファイルに対応している WebRTC ライブラリはありません。 現在 仕様策定中 です。

• [ADD] H.265 サイマルキャストに対応しました

• [ADD] sora.conf に H.265 のデフォルトレベル ID を指定する default_h265_param_level_id を追加しました

  • デフォルトは 93 (3.1) です

• [ADD] 認証払い出し時に H.265 のデフォルトレベル ID を指定する video_h265_params を追加しました

  • "video_h265_params": {"level_id": 93} のように指定できます

  • level_id の値は 0 から 255 の間である必要があります

• [ADD] シグナリング時に H.265 のデフォルトレベル ID を指定する h265_params を追加しました

  • "video": {"codec_type": "H265", "h265_params": {"level_id": 93}} のように指定できます

  • level_id の値は 0 から 255 の間である必要があります

• [ADD] sora.conf に、シグナリング時に H.265 のパラメータ指定を許可するかどうか設定する signaling_h265_params を追加しました

  • デフォルトは false です

2023.1.3

バグフィックスアップデート

リリース:

2023-10-17

変更履歴

• [FIX] 録画機能利用時、分割録画に失敗かつ分割録画ファイルが一つ以上生成されている場合に、終了処理に失敗する問題を修正しました

  • 終了中の失敗のため、録画処理自体には影響はありません

• [FIX] サイマルキャスト機能の simulcast_encodings と spotlight_encodings の scalabilityMode のデフォルト値を L1T1 に修正しました

  • AV1 サイマルキャスト利用時に L1T1 以外の scalabilityMode を利用すると録画ができない問題があります

• [FIX] データチャネルを利用したメッセージング機能利用時に、パケロスが発生すると一定期間パケットを破棄してしまうことがある問題を修正しました

  • この問題は ordered が true で max_retransmits や max_packet_life_time が設定されている場合に発生します

• [FIX] クラスター機能利用時に、ノードの起動・停止と新規チャネルへの接続が重なると接続に失敗することがある問題を修正しました

• [FIX] sora.conf の default_simulcast_rid の設定値が設定に反映されない問題を修正しました

• [FIX] 依存している OpenSSL を 3.1.3 にアップデートしました

2023.1.2

バグフィックスアップデート

リリース:

2023-08-10

変更履歴

• [FIX] Safari 側の問題により Safari 14 系および Safari 15 系の一部で Sora に接続できない問題を修正しました

  • Safari 15.6 以降では問題が修正されていることを確認しています

2023.1.1

バグフィックスアップデート

リリース:

2023-07-14

変更履歴

• [ADD] connection ログに ice_connection_state という ICE コネクション機能の統計情報を追加しました

  • サポートにて問題をより素早く解決しやすくするための追加です

• [ADD] connection ログに network_status に不安定レベル毎の統計情報を追加しました

  • サポートにて問題をより素早く解決しやすくするための追加です

• [ADD] GetStatsConnection API に ice_connection_state の統計情報を追加しました

• [ADD] GetStatsConnection API に network_status にレベル毎の統計情報を追加しました

• [FIX] CentOS 7 x86_64 利用時にセグメンテーション違反で Sora が落ちてしまう問題を修正しました

• [FIX] DTLS 再ネゴシエーションの挙動を修正しました

• [FIX] スポットライト機能利用時に OBS での WHIP が利用できない問題を修正しました

  • 新しく WHIP エンドポイント URL 指定時に spotlight=true を指定することで利用できるようにしました

  • ただし、音声がそのままでは配信されないため FocusSpotlightFixed API を利用して音声を配信する必要があります

• [FIX] ICE コネクションステート機能で disconnected 時のクライアント状態確認の挙動を修正しました

• [FIX] PutSignalingNotifyMetadata API の結果の誤字を修正しました

• [FIX] JoinCluster API のエラー応答の誤字を修正しました

2023.1.0

メジャーアップデート

リリース:

2023-06-28

サポート期間変更

• Sora 2023.1.0 より、サポート提供期間をメジャーアップデートがリリースされた日から 12 ヶ月後の月末最終日まで に変更しました

• 2023年 6 月リリースの Sora 2023.1.0 およびその後リリースされる可能性のある Sora 2023.1.x は、2024 年 6 月 30 日までサポート対象となります

詳細は サポートライフサイクル をご確認ください。

ハイライト

• OBS で WebRTC を利用した配信を実現する WHIP に対応しました

  • 詳細は OBS (WHIP) 機能 をご確認ください

• VP9 / AV1 でのサイマルキャストに対応しました

  • 詳細は VP9 と AV1 でのサイマルキャスト をご確認ください

• メディアストリームを柔軟に制御するための 転送フィルター機能 を追加しました

• 音声ストリーミング機能に自動開始/停止機能を追加しました

  • 詳細は 自動開始/停止機能 をご確認ください

• IPv6 のみの環境での動作に対応しました

  • 詳細は IPv6 のみ をご確認ください

互換なしの変更情報

• 移行用の設定である sora_conf-legacy_webhook_audio_video_json_structure の設定のデフォルトを false に変更しました

  • 詳細は sora.conf の legacy_webhook_audio_video_json_structure の廃止 をご確認ください

• 移行用の設定である legacy_log_format の設定のデフォルトを false に変更しました

  • 詳細は sora.conf の legacy_log_format の廃止 をご確認ください

• 移行用の設定である legacy_log_extension の設定のデフォルトを false に変更しました

  • 詳細は sora.conf の legacy_log_extension の廃止 をご確認ください

廃止情報

• Ubuntu 18.04 向けパッケージのサポートを終了しました

  • 詳細は Ubuntu 18.04 サポートの終了 をご確認ください

• sora.conf の split_archive_legacy_prefix を廃止しました

  • 詳細は sora.conf の split_archive_legacy_prefix の廃止 をご確認ください

• sora.conf の default_multistream を廃止しました

  • 詳細は sora.conf の default_multistream の廃止 をご確認ください

• sora.conf の dcsctp_heartbeat_interval を廃止しました

  • 詳細は DataChannel で利用している SCTP 関連の実験的な設定の廃止 をご確認ください

• sora.conf の dcsctp_slow_start_tcp_style を廃止しました

  • 詳細は DataChannel で利用している SCTP 関連の実験的な設定の廃止 をご確認ください

変更履歴

• [CHANGE] データチャネル関連の設定である dcsctp_heartbeat_interval を廃止しました

• [CHANGE] データチャネル関連の設定である dcsctp_slow_start_tcp_style を廃止しました

• [CHANGE] サイマルキャスト利用時に "active": false を指定したストリームは、 ~r0 といった SDP が生成されます

  • r1 と r2 が false の場合は a=simulcast:recv r0;~r1;~r2 のような SDP が生成されます

  • これは RFC 8853: Using Simulcast in SDP and RTP Sessions に準拠しています

• [CHANGE] sora.conf のウェブフックの audio と video 項目のレガシーな入れ子構造を利用する sora_conf-legacy_webhook_audio_video_json_structure のデフォルト値を false に変更しました

  • これは移行用設定です

• [CHANGE] sora.conf のログフォーマットのレガシー形式を維持する legacy_log_format のデフォルト値を false に変更しました

  • これは移行用設定です

• [CHANGE] sora.conf の JSONL 形式で出力しているログのレガシー拡張子を .log に維持する legacy_log_extension のデフォルト値を false に変更しました

  • これは移行用設定です

• [UPDATE] RHEL 9.2 に対応しました

• [UPDATE] RHEL 8.8 に対応しました

• [ADD] 録画イベントウェブフック recording.started に data.start_timestamp を追加しました

• [ADD] 録画イベントウェブフック recording.started に data.split_duration を追加しました

• [ADD] sora.conf に IPv6 アドレスのみを利用する ipv6_only の設定を追加しました

• [ADD] クラスター機能が有効な際、セッションウェブフックに external_signaling_url 項目を追加しました

  • sora.conf の external_signaling_url に指定されている値がそのまま入ります

• [ADD] モードが block_new_connection の場合は、接続に失敗する仕組みを追加しました

• [ADD] イベントウェブフックにログの書き込みが成功したかどうかを示す log_written フラグを追加しました

  • イベントウェブフックログの書き込みが成功した場合は "log_written": true が含まれます

  • イベントウェブフックログの書き込みが失敗した場合は "log_written": false が含まれます

  • イベントウェブフックログには常に log_written が含まれます

• [ADD] 録画機能で録画ファイル生成に失敗したファイル情報を recording.report ウェブフックやファイルに failed_archives という項目で追加しました

• [ADD] 録画機能の recording.report イベントウェブフックに "file_written" フラグを追加しました

  • report-*.json ファイルの書き込みに成功した場合 "file_written": true が含まれます

  • report-*.json ファイルの書き込みに失敗した場合 "file_written": false が含まれます

  • report-*.json ファイルには常に file_written が含まれます

• [ADD] 認証ウェブフックに id を追加しました

• [FIX] IPv6 のみの環境で Firefox が正常に動作しない問題を修正しました

• [FIX] Sora 終了中に HTTP API が呼ばれるとクラッシュログが出力される問題を修正しました

• [FIX] 認証ウェブフックで simulcast が false の場合でも simulcast_rid が含まれていた問題を修正しました

  • simulcast が false の場合は simulcast_rid は含まれなくなります

• [FIX] 録画機能で H.264 でまれに録画が失敗してしまう問題を修正しました

• [FIX] スポットライト機能でフォーカスが当たっていない場合でも、無音の音声パケットが配信されてしまう問題を修正しました

パッケージファイル名の変更

OS 名とバージョンの間に - を入れるようにし、x86_64 もアーキテクチャを追加しました。 展開後のディレクトリにアーキテクチャは含まれません。

• [CHANGE] sora-2023.1.0-ubuntu22.04-arm64v8.tar.gz から sora-2023.1.0-ubuntu-22.04-arm64v8.tar.gz に変更しました

  • ubuntu22.04 を ubuntu-22.04 に変更しました

• [CHANGE] sora-2023.1.0-ubuntu20.04-arm64v8.tar.gz から sora-2023.1.0-ubuntu-20.04-arm64v8.tar.gz に変更しました

  • ubuntu20.04 を ubuntu-20.04 に変更しました

• [CHANGE] sora-2023.1.0-ubuntu22.04.tar.gz から sora-2023.1.0-ubuntu-22.04-x86_64.tar.gz に変更しました

  • ubuntu22.04 を ubuntu-22.04 に変更しました

  • ファイル名に -x86_64 を追加しました

• [CHANGE] sora-2023.1.0-ubuntu20.04.tar.gz から sora-2023.1.0-ubuntu-20.04-x86_64.tar.gz に変更しました

  • ubuntu20.04 を ubuntu-20.04 に変更しました

  • ファイル名に -x86_64 を追加しました

• [CHANGE] sora-2023.1.0-ubuntu20.04.tar.gz から sora-2023.1.0-ubuntu-20.04-x86_64.tar.gz に変更しました

  • ubuntu20.04 を ubuntu-20.04 に変更しました

  • ファイル名に -x86_64 を追加しました

• [CHANGE] sora-2023.1.0-rhel9.2.tar.gz から sora-2023.1.0-rhel-9.2-x86_64.tar.gz に変更しました

  • rhel9.2 を rhel-9.2 に変更しました

  • ファイル名に -x86_64 を追加しました

• [CHANGE] sora-2023.1.0-rhel8.8.tar.gz から sora-2023.1.0-rhel-8.8-x86_64.tar.gz に変更しました

  • rhel8.8 を rhel-8.8 に変更しました

  • ファイル名に -x86_64 を追加しました

• [CHANGE] sora-2023.1.0-centos7.9.tar.gz から sora-2023.1.0-centos-7.9-x86_64.tar.gz に変更しました

  • centos7.9 を centos-7.9 に変更しました

  • ファイル名に -x86_64 を追加しました

セッション破棄 API

• [ADD] 指定したセッションを終了させる TerminateSession API を追加しました

  • channel_id の指定は必須で、 session_id がオプションで指定できます

ヘルスチェック

• [ADD] http://<IP アドレス>:5000/.ok で Sora のヘルスチェックができるようになりました

  • 単体利用時には問題が無ければ常に 200 OK を返します

  • クラスター利用時には block_new_connection モード時には 503 Service Unavailable を返します

詳細は ヘルスチェック機能 をご確認ください。

シグナリング通知

• [ADD] シグナリング通知の "event_type": "connection.created" に timestamp を追加しました

  • data にも "data": [{"timestamp": "2023-06-28T10:00:00.999999", ...}, .. ] のように timestamp が含まれるようになります

• [ADD] シグナリング通知の "event_type": "connection.created" に timestamp を含める設定 signaling_notify_connection_created_timestamp を sora.conf に追加しました

  • デフォルトは true です

映像コーデックパラメーター指定機能

• [ADD] ウェブフックに映像コーデックパラメーター "video_vp9_params": {"profile_id": 0} を追加しました

  • この設定を利用する場合 legacy_webhook_audio_video_json_structure が false である必要があります

• [ADD] ウェブフックに映像コーデックパラメーター "video_av1_params": {"profile": 0} を追加しました

  • この設定を利用する場合 sora_conf-legacy_webhook_audio_video_json_structure が false である必要があります

• [ADD] ウェブフックに映像コーデックパラメーター "video_h264_params": {"profile_level_id": ""} を追加しました

  • この設定を利用する場合 sora_conf-legacy_webhook_audio_video_json_structure が false である必要があります

• [ADD] シグナリング接続時に H.264 のプロファイルレベル ID を "video": {"codec_type": "H264", "h264_params": {"profile_level_id": "42e01f"} のように指定できるようになりました

  • この指定を利用する場合は signaling_h264_params が true である必要があります

  • h264_params を指定する場合は、 codec_type は H264 である必要があります

• [ADD] シグナリング接続時に VP9 のプロファイル ID を "video": {"codec_type": "VP9", "vp9_params": {"profile_id": 0}} のように指定できるようになりました

  • この指定を利用する場合は signaling_vp9_params が true である必要があります

  • vp9_params を指定する場合は、 codec_type は VP9 である必要があります

  • profile_id には 0 から 3 までの値を指定できます

• [ADD] シグナリング接続時に AV1 のプロファイルを "video": {"codec_type": "AV1", "av1_params": {"profile": 0}} のように指定できるようになりました

  • この指定を利用する場合は signaling_av1_params が true である必要があります

  • av1_params を指定する場合は、 codec_type は AV1 である必要があります

  • profile には 0 から 2 までの値を指定できます

• [ADD] 認証成功時払い出しに VP9 のプロファイル ID を指定できる "video_vp9_params": {"profile_id": 0} を追加しました

  • この設定を利用する場合 sora_conf-legacy_webhook_audio_video_json_structure が false である必要があります

  • profile_id には 0 から 3 までの値を指定できます

• [ADD] 認証成功時払い出しに AV1 のプロファイルを指定できる "video_av1_params": {"profile": 0} を追加しました

  • この設定を利用する場合 sora_conf-legacy_webhook_audio_video_json_structure が false である必要があります

  • profile には 0 から 2 までの値を指定できます

• [ADD] 認証成功時払い出しに H.264 のプロファイルを指定できる "video_h264_params": {"profile_level_id": "42e01f"} を追加しました

  • この設定を利用する場合 sora_conf-legacy_webhook_audio_video_json_structure が false である必要があります

  • h264_profile_level_id は 2024 年 6 月リリース予定の Sora にて廃止します

• [ADD] sora.conf に VP9 のプロファイル ID のデフォルト値を指定する default_vp9_param_profile_id を追加しました

  • デフォルトは 0 が設定されています

  • 0 から 3 までの値を指定できます

• [ADD] sora.conf に AV1 のプロファイルのデフォルト値を指定する default_av1_param_profile を追加しました

  • デフォルトは 0 が設定されています

  • 0 から 2 までの値を指定できます

• [ADD] sora.conf に H.264 のプロファイルレベル ID のデフォルト値を指定する default_h264_param_profile_level_id を追加しました

  • 既存の default_h264_profile_level_id は 2024 年 6 月リリース予定の Sora にて廃止します

OBS (WHIP) 対応

OBS が対応予定の WebRTC (WHIP) で配信ができるようになりました。

• [ADD] sora.conf に OBS (WHIP) を有効にする whip を追加しました

  • デフォルトは false です

• [ADD] sora.conf に OBS (WHIP) の Bearer トークンを認証ウェブフックの metadata に対応させるキーを指定する whip_bearer_token_metadata_key を追加しました

  • OBS (WHIP) からの接続についても Bearer トークンを利用した認証機能が利用できます

  • デフォルトは未指定です

• [ADD] WHIP 向けエンドポイント URL https://example.com/whip/<channel-id> を追加しました

  • クエリー文字列で client_id と bundle_id を指定できるようになりました

• [ADD] WHIP 向けリソース URL https://example.com/whip-resource/<channel-id>/<secret> を追加しました

  • PATCH と DELETE メソッドに対応しています

• [ADD] WHIP を利用した際、認証ウェブフックに whip: true を追加しました

  • WHIP を利用していない接続の場合はこの項目は含まれません

詳細は OBS (WHIP) 対応機能 をご確認ください。

VP9 / AV1 サイマルキャスト対応

• [UPDATE] VP9 と AV1 でのサイマルキャスト機能に対応しました

  • Chrome 113 以降でスポットライト機能にて VP9 と AV1 が利用できるようになりました

  • Edge 113 以降でスポットライト機能にて VP9 が利用できるようになりました

• [UPDATE] 認証成功時の払い出し simulcast_encodings と spotlight_encodings で scalabilityMode を指定できるようになりました

  • デフォルトでは scalabilityMode に L1T3 が設定されています

• [UPDATE] simulcast_encodings_file と spotlight_encodings_file で scalabilityMode を指定できるようになりました

詳細は scalabilityMode をご確認ください。

Lyra 録音機能

• [ADD] 録画機能に Lyra コーデックを利用した際に WebM ファイルで録音する仕組みを追加しました

詳細は recording-lyra をご確認ください。

転送フィルター機能

今まで PauseRtpStream / ResumeRtpStream API で実現していたメディアストリームの停止/再開をより細かく、柔軟に設定をできるようにした、 転送フィルター機能を追加しました。

• [ADD] セッション生成時 forwarding_filter を指定することでチャネル単位の転送フィルターを追加できるようになりました

• [ADD] シグナリング接続時に forwarding_filter を指定することで接続単位の転送フィルターを追加できるようになりました

• [ADD] 認証成功時に forwarding_filter を指定することで接続単位の転送フィルターを追加できるようになりました

• [ADD] チャネル単位でチャネルとコネクションの転送フィルターを確認できる ListForwardingFilters API を追加しました

• [ADD] チャネル単位の転送フィルターを作成する CreateChannelForwardingFilter API を追加しました

• [ADD] チャネル単位の転送フィルターを更新する UpdateChannelForwardingFilter API を追加しました

• [ADD] チャネル単位の転送フィルターを削除する DeleteChannelForwardingFilter API を追加しました

• [ADD] コネクション単位の転送フィルターを作成する CreateConnectionForwardingFilter API を追加しました

• [ADD] コネクション単位の転送フィルターを更新する UpdateConnectionForwardingFilter API を追加しました

• [ADD] コネクション単位の転送フィルターを削除する DeleteConnectionForwardingFilter API を追加しました

• [ADD] 転送フィルターで転送がブロックされたタイミングでシグナリング通知する機能を追加しました

• [ADD] 転送フィルターで転送がブロックが解除されたタイミングでシグナリング通知する機能を追加しました

• [ADD] sora.conf に転送フィルターをシグナリング経由で指定できるかどうかを設定する signaling_forwarding_filter を追加しました

  • デフォルト は false です

• [ADD] sora.conf に転送フィルターのブロックの状態が変わったタイミングでシグナリング通知を飛ばすかどうかを設定する signaling_notify_forwarding_filter を追加しました

  • デフォルト は true です

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

SDP 再利用機能

今までマルチストリーム利用した際に、クライアント切断してもその SDP が残ってしまう問題がありました。 今回のリリースで、SDP を再利用する仕組みにより SDP が残る問題を解決しました。

• [CHANGE] recycle_media_section が true の際に、SDP を再利用する仕組みを追加しました

• [ADD] sora.conf に SDP の再利用を行う recycle_media_section 設定を追加しました

  • デフォルトは true です

音声ストリーミング機能

• [ADD] 音声ストリーミングの結果通知の状態を確認する ListAudioStreamingResultPushState API を追加しました

• [ADD] 音声ストリーミング機能にサブスクライブが 0 になると音声ストリーミングを停止し、サブスクライブが 1 以上になると音声ストリーミングを開始する機能を追加しました

  • この機能はセッション生成時に指定できます

  • この機能が有効になっている場合は音声ストリーミング開始/終了 API は利用できません

• [ADD] セッションウェブフックの払い出しに音声ストリーミングの自動開始と停止を有効にする audio_streaming_auto を追加しました

  • この設定を利用する場合は必ず audio_streaming を true で払い出す必要があります

• [ADD] sora.conf に音声ストリーミングのウェブフックを送信するかどうかを設定する ignore_audio_streaming_webhook を追加しました

  • デフォルトは true で、送信しません

• [ADD] 音声ストリーミング機能の開始のウェブフック audio-streaming.started を追加しました

  • sora.conf にて ignore_audio_streaming_webhook を false にすることで送信します

• [ADD] 音声ストリーミング機能の終了のウェブフック audio-streaming.stopped を追加しました

  • sora.conf にて ignore_audio_streaming_webhook を false にすることで送信します

WebSocket 経由シグナリングでの ping / pong / stats のインターバルやタイムアウトの設定

WebSocket 経由でのシグナリングにおいて、 "type": "ping" や "type": "pong" のインターバルやタイムアウトを設定できるようになりました。 また "type": "ping" 送信時の "stats": true にする間隔を指定できるようになりました。

• [CHANGE] "type": "ping" 時におくる "stats": true の間隔を 5 秒から 30 秒に変更しました

• [ADD] sora.conf に ping を送信する間隔を指定する websocket_signaling_ping_interval 設定を追加しました

  • デフォルトは 5 s です

  • 最小は 5 s です

  • 最大は 300 s です

• [ADD] sora.conf に pong のタイムアウト時間を指定する websocket_signaling_pong_timeout 設定を追加しました

  • デフォルトは 60 s です

  • 最小は 60 s です

  • 最大は 600 s です

• [ADD] sora.conf に ping 送信時に "stats": true にする間隔を指定する websocket_stats_timer_interval 設定を追加しました

  • デフォルトは 30 s です

  • 最小は 30 s です

  • 最大は 600 s です

クラスター機能利用時のディスク障害時の対応を追加

• [CHANGE] クラスター利用時に block_new_connection モードへ遷移した場合には新規接続のリダイレクトを行わないように変更しました

• [ADD] クラスター利用時にディスク障害が発生した際に、 block_new_connection モードへ遷移する機能を追加しました

2022.2.3

リリース:

2023-02-08

変更履歴

• [FIX] 依存している OpenSSL を 3.0.8 にアップデートしました

• [FIX] 2023 年 4 月 4 日リリース予定の Chrome 112 でシグナリング時に接続が必ず失敗してしまう問題を修正しました

• [FIX] ディスク障害が発生してログの書き込みに失敗した際に、障害が復旧した後でもログが書き込めなくなることがある問題を修正しました

2022.1.4

リリース:

2023-02-08

変更履歴

• [FIX] 2023 年 4 月 4 日リリース予定の Chrome 112 でシグナリング時に接続が必ず失敗してしまう問題を修正しました

2022.2.2

リリース:

2023-01-05

変更履歴

• [FIX] 音声ストリーミング機能で sora.conf の default_audio_streaming_result_push が true の際、プッシュ通知が行われない問題を修正しました

• [FIX] 音声ストリーミング機能でロールが recvonly の場合にプッシュ通知が受信できない問題を修正しました

• [FIX] 音声ストリーミング機能で API を利用して音声ストリーミングを開始した際、通知が正常に行われない問題を修正しました

2022.2.1

リリース:

2022-12-21

変更履歴

• [FIX] 開発ツールが Safari / Mobile Safari / Firefox で動作しない問題を修正しました

2022.2.0

リリース:

2022-12-21

ハイライト

• sora ログと internal ログを JSONL 形式で出力するようになりました

• Google が公開した超低ビットレートコーデック Lyra に対応しました

• 音声パケットを HTTP/2 経由で出力する音声ストリーミング機能を追加しました

• 録画開始ととアーカイブ開始のウェブフックを追加しました

• ウェブフックが mTLS と CA 証明書の指定に対応しました

互換なしの変更情報

• 実験的機能であるセッションウェブフックのログ出力を req/res 形式に変更しました

• 実験的機能であるセンシティブデータ向け設定 redact_archive_metadata_sensitive_data と redact_api_sensitive_data を廃止しました

  • 録画メタデータファイルと API はセンシティブなデータがあっても編集を行わないようにしました

• クラスター機能の仕組みを変更したため互換性がなくなりました、クラスターの再構築をお願いします

変更履歴

• [FIX] DTLS 処理終了時に起きていた問題を修正しました

• [FIX] 録画ウェブフックの expired_at が秒単位の UNIX Time ではなくマイクロ秒になっていたのを修正しました

• [FIX] 録画ウェブフックの split-archive.available と split-archive-*.json に offset が含まれていなかったのを修正しました

• [FIX] ULPFEC が有効でな状態でパケロス発生時に録画に失敗することがある問題を修正しました

• [FIX] 録画機能のウェブフックやファイルに含まれる統計値の名前 total_audio_discarded が間違っていたのを修正しました

JSONL 形式でのログ出力

• [ADD] sora.conf にログフォーマットのレガシー形式を維持する legacy_log_format を追加しました

  • デフォルトは true です

  • これは移行用設定です

• [ADD] sora.conf に JSONL 形式で出力しているログのレガシー拡張子を .log に維持する legacy_log_extension を追加しました

  • デフォルトは true です

  • これは移行用設定です

• [ADD] sora.conf の legacy_log_format を false にすることで以下のログは JSONL 形式で出力されます

  • sora ログ

  • internal ログ

  • signaling ログ

  • api ログ

  • auth_webhook ログ

  • session_webhook ログ

  • session_webhook_error ログ

  • event_webhook ログ

  • event_webhook_error ログ

  • connection ログ

• [ADD] sora.conf の legacy_log_extension を false にすることで JSONL 形式で出力されているログファイルの拡張子が .log から .jsonl に変更されます

  • sora.log が sora.jsonl に変更されます

  • internal.log が internal.jsonl に変更されます

  • signaling.log が signaling.jsonl に変更されます

  • api.log が api.jsonl に変更されます

  • auth_webhook.log が auth_webhook.jsonl に変更されます

  • session_webhook.log が session_webhook.jsonl に変更されます

  • session_webhook_error.log が session_webhook_error.jsonl に変更されます

  • event_webhook.log が event_webhook.jsonl に変更されます

  • event_webhook_error.log が event_webhook_error.jsonl に変更されます

  • connection.log が connection.jsonl に変更されます

• [CHANGE] サポート用ログファイルである connection_created_wait_timeout_error/<timestamp>_<connection_id>.json の拡張子を .json から .jsonl に変更しました

クラスター機能

• [CHANGE] クラスターの仕組みを変更したため、2022.1 系までのクラスターの仕組みとは互換性がありません

  • クラスターの初期化が必要になります

• [ADD] クラスター初期化に利用する InitCluster API を追加しました

• [CHANGE] クラスター機能の ListClusterNodes API の member_since を廃止しました

• [CHANGE] クラスター機能の ListClusterChannels API の戻り値を変更しました

  • owners を追加し、その下にリストで node_name epoch epoch_latest connected を持つようにしました

  • node_in_charge を node_name に変更しました

  • node_in_charge_epoch を epoch に変更しました

  • node_in_charge_epoch_stale を epoch_latest に変更しました

  • node_in_charge_connected を connected に変更しました

Lyra コーデックへの対応

これは実験的機能です

• [ADD] sora.conf に Google が公開した音声圧縮用超低ビットレートコーデック Lyra を有効にする設定 lyra を追加しました

  • デフォルトは false です

  • lyra = true のように設定してください

• [ADD] シグナリング接続時の音声コーデックタイプに Lyra を指定できるようになりました

  • 指定する際は大文字の LYRA で指定する必要があります

  • Lyra を利用する際は lyra_params を指定する必要があります

    • lyra_params には lyra のバージョンを指定する version とビットレートを指定する bit_rate が指定できます

    • {"audio": "codec_type": "LYRA", "lyra_params": {"version": "1.3.0", "bit_rate": 9200}}

• [ADD] 認証成功時に {"audio": true, "audio_codec_type": "LYRA", "audio_lyra_params": {"version": "1.3.0", "bitrate": 9200} のように指定できるようになりました

  • この指定を利用する場合は sora_conf-legacy_webhook_audio_video_json_structure を false にする必要があります

音声ストリーミング機能

これは実験的機能です

• [ADD] sora.conf に音声ストリーミングのリクエスト先の URL を指定する audio_streaming_url を追加しました

• [ADD] sora.conf に音声ストリーミングで利用するデフォルトのランゲージコードを指定する default_audio_streaming_language_code を追加しました

• [ADD] sora.conf に音声ストリーミングでデフォルトで結果をプッシュ通知で行うかどうかを指定する default_audio_streaming_result_push を追加しました

• [ADD] sora.conf に音声ストリーミングで mTLS を利用する秘密鍵を指定する audio_streaming_tls_privkey_file を追加しました

• [ADD] sora.conf に音声ストリーミングで mTLS を利用する証明書を指定する audio_streaming_tls_fullchain_file を追加しました

• [ADD] sora.conf に音声ストリーミングで利用する CA ルート証明書を指定する audio_streaming_tls_verify_cacert_file を追加しました

• [ADD] 音声ストリーミングを開始する StartAudioStreaming API を追加しました

• [ADD] 音声ストリーミングを終了する StopAudioStreaming API を追加しました

• [ADD] 音声ストリーミングの解析結果を購読する SubscribeAudioStreamingResultPush API を追加しました

• [ADD] 音声ストリーミングの解析結果を購読解除する UnsubscribeAudioStreamingResultPush API を追加しました

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

音声冗長化機能

• [CHANGE] sora.conf の audio_red のデフォルト値を false に変更しました

センシティブデータ

• [ADD] sora.conf にセンシティブなデータが含まれる可能性がある項目を "REDACTED" という文字列への書き換えをスキップする skip_redact_sensitive_data を追加しました

  • デフォルトでは false です

• [CHANGE] sora.conf の redact_archive_metadata_sensitive_data を廃止しました

  • 録画メタデータファイルの event_metadata はセンシティブなデータの書き換え対象外としました

• [CHANGE] sora.conf の redact_api_sensitive_data を廃止しました

  • API の event_metadata はセンシティブなデータの書き換え対象外としました

詳細は センシティブデータ をご確認ください。

ウェブフックの audio と video 項目の JSON 構造のフラット化

• [ADD] sora.conf にウェブフックの audio と video 項目のレガシーな JSON 構造する sora_conf-legacy_webhook_audio_video_json_structure を追加しました

  • デフォルトでは true です

  • これは移行用設定です

詳細は ウェブフックの audio と video 項目の JSON 構造のフラット化 をご確認ください

セッションウェブフックログを req/res 形式に変更

• [CHANGE] session_webhook.jsonl の出力形式を req/res 形式に変更しました

• [CHANGE] session_webhook_error.jsonl の出力形式を req 形式に変更しました

録画とアーカイブ開始ウェブフックを追加

• [ADD] 録画開始ウェブフック recording.started を追加しました

• [ADD] アーカイブ開始ウェブフック archive.started を追加しました

• [ADD] sora.conf に ignore_recording_started_webhook を追加しました

  • デフォルトでは false です

• [ADD] sora.conf に ignore_archive_started_webhook を追加しました

  • デフォルトでは false です

ウェブフック mTLS / CA 証明書指定対応

• [ADD] sora.conf にウェブフックのリクエスト先との通信で mTLS を利用する際の証明書を指定する webhook_tls_fullchain_file を追加しました

• [ADD] sora.conf にウェブフックのリクエスト先との通信で mTLS を理世する際の秘密鍵を指定する webhook_tls_privkey_file を追加しました

• [ADD] sora.conf にウェブフックのリクエスト先の証明書をベリファイするルート CA を指定する webhook_tls_verify_cacert_file を追加しました

ウェブフック統計情報

• [ADD] ウェブフック関連の統計情報を GetStatsReport API に追加しました

  • total_auth_webhook_allowed

    • 認証ウェブフックで許可された数

  • total_auth_webhook_denied

    • 認証ウェブフックで拒否された数

  • total_successful_auth_webhook

    • 認証ウェブフックが成功した数

  • total_failed_auth_webhook

    • 認証ウェブフックが失敗した数

  • total_successful_session_webhook

    • セッションウェブフックが成功した数

  • total_failed_session_webhook

    • セッションウェブフックが失敗した数

  • total_successful_event_webhook

    • イベントウェブフックが成功した数

  • total_failed_event_webhook

    • イベントウェブフックが失敗した数

クラッシュログ出力 API

これは実験的機能です

• [ADD] 意図的に crash.log を出力させる 20221221.GenerateCrashLog API を追加しました

  • この API はログ出力の動作確認にのみ利用してください

  • この API はかならずステータスコード 500 を返します

2022.1.3

リリース:

2022-11-02

変更履歴

• [FIX] 依存している OpenSSL を 3.0.7 にアップデートしました

• [FIX] データチャネルの性能ボトルネックを修正しました

• [FIX] データチャネル利用時に高負荷になった状態が継続する問題を修正しました

• [FIX] データチャネル利用時に意図しないメッセージを受信した際の問題を修正しました

• [FIX] データチャネル利用時に意図しないエラーが発生する問題を修正しました

• [FIX] データチャネル利用時に compress が true になっている Label のメッセージが壊れている場合の問題を修正しました

2022.1.1

リリース:

2022-07-12

変更履歴

• [FIX] 依存している OpenSSL を 3.0.5 にアップデートしました

• [FIX] 録画機能の {"type": "split-archive-end"} ウェブフックには解像度を含めないように修正しました

• [FIX] 録画機能の split-archive-end-<connection_id>.json ファイルには解像度を含めないように修正しました

• [FIX] sora.log にでるべきログの一部が internal.log に出力されていた問題を修正しました

• [FIX] クラスターのノードが異常な状態になったタイミングで emergency ログを出力して終了するように修正しました

• [FIX] sora.conf の default_multistream が true の時に、 "type": "connect" メッセージの role に sendrecv を指定し、かつ multistream を 指定しない 場合に、エラーとなり接続できない問題を修正しました

2022.1.0

リリース:

2022-06-29

ハイライト

• Ubuntu 22.04 に対応しました

• RHEL 9 に対応しました

• サイマルキャスト機能が正式版になりました

• スポットライト機能が正式版になりました

• スポットライト機能がサイマルキャスト無効でも利用できるようになりました

• サイマルキャスト機能やスポットライト機能利用時に、視聴されていないストリームは復号処理を行わない仕組みを追加しました

• 録画機能で、録画ファイル分割出力機能を有効にした場合にも recording.report ウェブフック通知とレポートファイルが作成されるようになりました

• クラスター利用時に、同一ライセンスを利用できる「最大ノード数ライセンス」の提供を開始しました

• クラスター機能で録画状態を共有する機能を追加しました

• クラスター機能でクラスター参加を自動で行う仕組みを追加しました

• クラスター機能でネットワーク障害発生時に自動で復旧を試みる仕組みを追加しました

• 特定の接続からのストリームを受信しないようにできる bundle_id を追加しました

• センシティブなデータが含まれる可能性がある session_metadata や event_metadata の値を "REDACTED" という文字列に書き換える仕組みを追加しました

廃止情報

• sora.conf の demo を廃止しました

• sora.conf の remote_stats を廃止しました

• sora.conf の unuse_metadata_list を廃止しました

• sora.conf の use_re_offer を廃止しました

• GetAllRemoteStats API を廃止しました

• GetChannelRemoteStats API を廃止しました

• GetConnectionRemoteStats API を廃止しました

• StopRecording API の redirect を廃止しました

互換なしの変更情報

• マルチストリームをデフォルトで有効にしました

  • sora.conf の default_multistream を false にすることでマルチストリームがデフォルトではなくなります

  • この設定は 2023 年 6 月リリースの Sora にて廃止します

  • 詳細は sora.conf の default_multistream の廃止 をご確認ください

• type: archive.end を type: split-archive.end に変更しました

  • sora.conf の split_archive_legacy_prefix を true にすることで type: archive.end がそのまま利用できます

  • この設定は 2023 年 6 月リリースの Sora にて廃止します

  • 詳細は sora.conf の split_archive_legacy_prefix の廃止 をご確認ください

• type: archive.split を type: split-archive.available に変更しました

  • sora.conf の split_archive_legacy_prefix を true にすることで type: archive.split がそのまま利用できます

  • この設定は 2023 年 6 月リリースの Sora にて廃止します

  • 詳細は sora.conf の split_archive_legacy_prefix の廃止 をご確認ください

• archive-<connection-id>_<index>.webm を split-archive-<connection-id>_<index>.webm に変更しました

  • sora.conf の split_archive_legacy_prefix を true にすることで archive-<connection-id>_<index>.webm がそのまま利用できます

  • この設定は 2023 年 6 月リリースの Sora にて廃止します

  • 詳細は sora.conf の split_archive_legacy_prefix の廃止 をご確認ください

• archive-<connection-id>_<index>.json を split-archive-<connection-id>_<index>.json に変更しました

  • sora.conf の split_archive_legacy_prefix を true にすることで archive-<connection-id>_<index>.json がそのまま利用できます

  • この設定は 2023 年 6 月リリースの Sora にて廃止します

  • 詳細は sora.conf の split_archive_legacy_prefix の廃止 をご確認ください

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

• セッションウェブフックでセッションの接続数が 0 ではないタイミングで multistream と spotlight がセッションと異なる新規接続が来た場合は INVALID-SIGNALING-PARAMS エラーを返し切断するように変更しました

• セッションウェブフック session.created と session.destroyed の created_time と destroyed_time を UNIX 時間に変更しました

• sora.log と internal.log の時刻を RFC3339 準拠に変更しました

• cluster 関連設定名を変更しました

  • cluster_node_name を node_name へ変更しました

  • cluster_api_url を external_api_url へ変更しました

  • cluster_signaling_url を external_signaling_url へ変更しました

  • sora_version を version に変更しました

• cluster 関連 API の引数や戻り値を変更しました

• クラスター機能を有効にしたときのモードを initial へ変更しました

• クラスターに参加したときに自動でモードが initial から normal へ切り替わるよう変更しました

変更履歴

• [CHANGE] セッションウェブフック session.created の created_time を UNIX 時間に変更しました

• [CHANGE] セッションウェブフック session.destroyed の created_time を UNIX 時間に変更しました

• [CHANGE] セッションウェブフック session.destroyed の destroyed_time を UNIX 時間に変更しました

• [UPDATE] 組み込みの開発ツールを 2022.1.0 にアップデートしました

• [ADD] RHEL 9 x86_64 に対応しました

• [ADD] Ubuntu 22.04 x86_64 に対応しました

• [ADD] イベントウェブフック connection.created に RFC3339 形式で出力する created_timestamp を追加しました

• [ADD] イベントウェブフック connection.updated に RFC3339 形式で出力する created_timestamp を追加しました

• [ADD] イベントウェブフック connection.destroyed に RFC3339 形式で出力する created_timestamp を追加しました

• [ADD] イベントウェブフック connection.destroyed に RFC3339 形式で出力する destroyed_timestamp を追加しました

• [ADD] イベントウェブフック connection.destroyed に UNIX 時間で出力する destroyed_time を追加しました

• [ADD] GetStatsReport API に Sora のバージョンを取得できる version を追加しました

• [ADD] 認証成功時の H.265 の払い出しを追加しました

• [ADD] 認証ウェブフックに simulcast_rid を追加しました

• [ADD] Sora 内部で利用するファイルを書き出す data ディレクトリを追加しました

• [ADD] sora.conf に Sora 内部で利用するファイルを書き出す data ディレクトリを指定する data_dir を追加しました

• [FIX] Opus の RED の仕様変更ともない動作しなくなっていた問題を修正しました

• [FIX] 0 番ポートでパケットが送られてきた場合の問題を修正しました

• [FIX] DTLS で異常なパケットが送られてきた場合でも可能な限り丁寧に終了処理を行うように修正しました

• [FIX] 異常な STUN パケットが送られてきた場合の問題を修正しました

• [FIX] 録画した WebM ファイルの Cluster Timecode が負の値になると発生する問題を修正しました

マルチストリームをデフォルトで有効化

マルチストリームをデフォルトで有効にしました。

いままでマルチストリームを利用する場合は、シグナリング接続時に "multistream": true を指定して有効にする必要がありました。これをデフォルトで有効に変更しました。

今後は、マルチストリームを利用しない場合は明示的に "multistream": false を指定する必要があります。

• [CHANGE] マルチストリームをデフォルトで有効に変更しました

• [ADD] sora.conf にマルチストリームのデフォルト値を指定する default_multistream を追加しました

  • デフォルトでは true が設定されています

  • この設定は 2023 年 6 月リリース予定の Sora にて廃止します

  • 詳細は sora.conf の default_multistream の廃止 をご確認ください

例外的にスポットライト機能を利用するときは "multistream": true を明示する必要があります。

bundle_id の追加

複数のコネクションを同じ端末から接続する際、それぞれのコネクションで同一の bundle_id を指定すると、 同一の bundle_id を指定した接続からの音声や映像、メッセージングを受信しなくなります。

画面共有の映像を受信したくない場合などにお使いください。

• [ADD] sora.conf に "type": "connect" 時に bundle_id を指定できるかどうかを設定する signaling_bundle_id を追加しました

  • デフォルトでは false が設定されています

• [ADD] sora.conf に signaling_notify_bundle_id を追加しました

  • デフォルトでは true が設定されています

• [ADD] "type": "connect" で bundle_id が指定できるようになりました

  • 詳細は bundle_id の指定 をご確認ください

• [ADD] 認証成功時の払い出しで bundle_id を指定できるようになりました

  • 詳細は bundle_id の払い出し をご確認ください

sora.log と internal.log の出力

• [CHANGE] タイムスタンプの出力を RFC3339 準拠に変更しました

  • Sora 2021.2.7 まで

    • 2022-03-07 02:54:26.847 UTC [info] [-/-/-] <0.1218.0> SORA | node_name=sora@192.0.2.1, version=2021.2.7

  • Sora 2022.1.0 から

    • 2022-03-07T02:54:26.847130Z [info] [-/-/-] <0.1218.0> SORA | node_name=sora@192.0.2.1, version=2022.1.0

録画機能

• [CHANGE] 分割録画ファイルとメタデータファイルの出力名を archive-<connection_id>_<index>.(json|webm) から split-archive-<connection_id>_<index>.(json|webm) に変更しました

  • sora.conf の split_archive_legacy_prefix を true にすることで archive-<connection_id>_<index>.(json|webm) を維持できます

• [CHANGE] 録画分割時のウェブフックのタイプ "type": "archive.split" を "type": "split-archive.available" に変更しました

• [CHANGE] 録画分割時のウェブフックのタイプ "type": "split.end" を "type": "split-archive.end" に変更しました

• [CHANGE] 録画一時ファイルディレクトリ archive_tmp_dir に保存される録画一時ファイルは、録画が失敗した場合には削除されなくなりました

• [ADD] report-<connection_id>.json に node_name と label 項目を追加しました

• [ADD] sora.conf に分割録画ファイル名を archive-<connection_id>_<index>.(json|webm) にする split_archive_legacy_prefix を追加しました

  • デフォルトは false です

  • この設定は 2023 年 6 月リリース予定の Sora にて廃止します

  • 詳細は sora.conf の split_archive_legacy_prefix の廃止 をご確認ください

• [ADD] 録画の状態をクラスターで共有する仕組みを追加しました

• [ADD] split_only に true を指定した場合に、 archive.end ウェブフックと対になる split-archive-end-<connection_id>.json ファイルを作成するようになりました

• [ADD] split_only に true を指定した場合でも recording.report ウェブフックリクエストを飛ばすようになりました

• [ADD] split_only に true を指定した場合でも report-<recording_id>.json ファイルを作成するようになりました

• [ADD] 録画メタデータファイルとレポートファイルに label と node_name を追加するようにしました

• [UPDATE] 録画で生成された WebM ファイルが Windows の Windows標準アプリケーションの"映画＆テレビ" で正常に再生できない問題へ対応しました

  • Sora 側の問題ではなく Windows標準アプリケーションの"映画＆テレビ" が WebM の仕様を守っていないことによる問題です

サイマルキャストやスポットライト機能利用時の負荷削減

• [ADD] サイマルキャストやスポットライト利用時に誰も視聴していない音声や映像ストリームの復号を行わない処理を追加しました

• [ADD] 統計 API の rtp 項目に tocal_decrypt_skipped_audio_srtp を追加しました

• [ADD] 統計 API の rtp 項目に tocal_decrypt_skipped_video_srtp を追加しました

• [ADD] 統計 API の simulcast.rtp.(r0|r1|r2) 項目に total_decrypt_skipped_srtp を追加しました

サイマルキャスト無効でのスポットライト機能利用

• [ADD] スポットライト機能が "simulcast": false でも利用できるようになりました

クラスター機能

• [CHANGE] クラスター有効時に起動した際のモードを initial モードに変更しました

• [CHANGE] クラスターに参加したタイミングで自動で initial モードから normal モードに切り替わるように変更しました

• [CHANGE] sora.conf の cluster_node_name を node_name に変更しました

• [CHANGE] sora.conf の cluster_signaling_url を external_signaling_url に変更しました

• [CHANGE] sora.conf の cluster_api_url を external_api_url に変更しました

• [CHANGE] クラスター有効時に sora.log / internal.log にクラスターノード名を出力するように変更しました

• [CHANGE] JoinCluster API の cluster_node_name を contact_node_name に変更しました

• [CHANGE] ListClusterNodes API の cluster_node_name を node_name に変更しました

• [ADD] クラスターから特定のノードの情報を完全消去する PurgeClusterNode API を追加しました

• [ADD] sora.conf に Sora 起動時に自動でクラスター参加を試みる contact_node_name_list を追加しました

  • 詳細は contact_node_name_list をご確認ください

• [ADD] sora.conf にネットワーク障害等発生時に自動で再接続を試みる cluster_auto_reconnect を追加しました

  • デフォルトは有効です

• [ADD] ネットワーク障害等発生時に自動で復旧を試みる仕組みを追加しました

最大ノード数対応ライセンス

クラスター利用時に、複数のノードに同一のライセンスが利用できる最大ノードライセンスの提供を開始しました。

詳細は 最大ノード数ライセンス をご確認ください。

• [CHANGE] 最大ノード数ライセンスに対応していないライセンスを複数のノードに適用し、クラスターを構築しようとすると DUPLICATE-LICENSE が出力されるように変更されました

  • 無制限ライセンスをご利用のお客様でクラスターを利用されている場合はサポートまでご連絡ください

• [ADD] クラスター利用時に同一のライセンスを利用できる最大ノード数ライセンスに対応しました

  • 新規でライセンスを発行し直す必要がありますのでサポートまでご連絡ください

  • 新しくライセンスに max_nodes という項目を追加し、この最大ノード数までは複数の Sora で同一のライセンスを利用できるようになります

統計機能

• [ADD] 統計 API の rtp 項目に total_received_srtp_invalid を追加しました

• [ADD] 統計 API の turn 項目に total_received_unknown_packet を追加しました

• [ADD] 統計 API の turn 項目に total_received_stun_unknown を追加しました

• [ADD] 統計 API の turn 項目に total_received_stun_invalid を追加しました

• [ADD] 統計 API の turn 項目に total_received_turn_invalid_stun を追加しました

• [ADD] データチャネルの破棄やリトライの回数をラベルごとに取得できるようになりました

  • データチャネルの破棄メッセージ数 total_data_channel_abandon_message を追加しました

  • データチャネルの再送メッセージ数 total_data_channel_retransmit_message を追加しました

  • データチャネルの DATA_CHANNEL_OPEN メッセージ数 total_data_channel_ack_message を追加しました

  • データチャネルの DATA_CHANNEL_ACK メッセージ数 total_data_channel_open_message を追加しました

• [UPDATE] total_sent_data_channel_message から DATA_CHANNEL_OPEN メッセージを除外しました

• [UPDATE] total_received_data_channel_message から DATA_CHANNEL_ACK メッセージを除外しました

センシティブデータ編集済出力機能

詳細は センシティブデータ をご確認ください。

• [CHANGE] auth_webhook.log に含まれる event_metadata の中身を編集済みを表す "REDACTED" という文字列に書き換える変更を行いました

• [CHANGE] session_webhook.log に含まれる session_metadata と event_metadata の中身を編集済みを表す "REDACTED" という文字列にに書き換える変更を行いました

• [CHANGE] event_webhook.log に含まれる event_metadata の中身を、編集済みを表す "REDACTED" という文字列に書き換える変更を行いました

  • event_webhook_error.log の event_metadata は書き換えを行いません

• [ADD] sora.conf にAPI 戻り値に含まれるセンシティブな可能性があるデータを、編集済みを表す "REDACTED" という文字列に書き換える redact_api_sensitive_data を追加しました

  • デフォルトでは true

  • event_metadata の中身を "REDACTED" という文字列に書き換えます

• [ADD] sora.conf に録画メタデータファイルに含まれるセンシティブな可能性があるデータを "REDACTED" という文字列に書き換える redact_archive_metadata_sensitive_data を追加しました

  • デフォルトでは true

  • event_metadata の中身を "REDACTED" という文字列に書き換えます

2021.2.8

リリース:

2022-04-11

対応 Chrome:

M98 以降

対応 Firefox:

97 以降

対応 Safari:

15.3 以降

対応 Edge:

98 以降

変更履歴

• [FIX] 依存ライブラリ OpenSSL を 1.1.1n にアップデートしました

2021.2.7

リリース:

2022-02-24

対応 Chrome:

M98 以降

対応 Firefox:

97 以降

対応 Safari:

15.3 以降

対応 Edge:

98 以降

変更履歴

• [CHANGE] 録画失敗時でも一時ファイルを削除しないようにしました

• [FIX] PauseRtpStream API がイベントウェブフック connection.created を受け取ったタイミングで実行しても正常に動作しない問題を修正しました

• [FIX] 録画ファイル分割出力のみの場合でも、一時ファイルが録画終了時まで削除されずに残っていた問題を修正しました

2021.2.1

リリース:

2021-12-20

対応 Chrome:

M97 以降

対応 Firefox:

95 以降

対応 Safari:

15.1 以降

対応 Edge:

97 以降

• [FIX] 録画機能利用時に sora.conf の archive_tmp_dir と archive_dir で指定される 2 つのディレクトリが異なるファイルシステムにある場合に、録画ファイルの生成に失敗する問題を修正しました

2021.2.0

リリース:

2021-12-15

対応 Chrome:

M97 以降

対応 Firefox:

95 以降

対応 Safari:

15.1 以降

対応 Edge:

97 以降

ハイライト

• クラスター機能を追加しました

• DataChannel を利用したメッセージング機能を追加しました

• 統計エクスポーター機能を追加しました

• スポットライト機能のフォーカス/アンフォーカスを変更する API を追加しました

• ICE コネクションステート機能を追加しました

• シグナリング通知に録画開始/終了の通知を追加しました

• セッションウェブフックを追加しました

• 音声冗長化機能に対応しました

• AV1 コーデック利用時の録画に対応しました

廃止情報

• CentOS 8 への対応を終了しました

  • 詳細は CentOS 8 対応 をご確認ください

• スポットライトレガシー機能を廃止しました

  • 詳細は スポットライトレガシー機能の廃止 をご確認ください

• 統計機能の rtp にある rtcp を廃止しました

  • 詳細は rtp にある RTCP 関連統計情報を廃止 をご確認ください

• sora.conf の extmap_allow_mixed 設定を廃止しました

  • 詳細は extmap_allow_mixed 設定のデフォルト有効化と廃止 をご確認ください

• sora.conf の dcsctp_association_max_retrans 設定を廃止しました

  • 詳細は sora.conf の dcsctp_association_max_retrans を廃止 をご確認ください

• 実験的機能である sora.conf の opus_param_clock_rate 設定を廃止しました

• ListAllConnections API を廃止しました

  • 今後は ListConnections API をご利用ください。

• ListChannelClients API を廃止しました

  • 今後は ListChannelConnections API をご利用ください

互換性なしの変更情報

変更点の不明点についてはサポートまでお問い合わせください

猶予期間を儲けない変更となっておりますのでご注意ください

• ListConnections API の戻り値に含まれる connection_created_timestamp_sec の項目名を created_time に変更、単位を秒からマイクロ秒に変更しております

• ListChannelConnections API の戻り値に含まれる connection_created_timestamp_sec の項目名を created_time に変更しており、単位を秒からマイクロ秒に変更しております

変更履歴

• [CHANGE] connection.log のタイムスタンプを秒からマイクロ秒に変更しました

• [CHANGE] Chrome 側の破壊的変更により Chrome M95 以前の AV1 への対応を廃止しました

  • AV1 を利用する場合は Chrome M96 以降をご利用ください

• [ADD] sora.conf に TURN-TCP で Allocate-Success を遅延させる turn_tcp_allocate_success_delay_time を追加しました

  • デフォルトは 100 ms です

  • 0-1000 ms の範囲で指定できます

• [ADD] Sora 起動時に Sora のバージョンが INFO レベルで sora.log に出力されるようになりました

  • 2021-12-15 12:34:56.789 UTC [info] [-/-/-] <0.235.0> SORA | node_name=sora@127.0.0.1, version=2021.2.0

移行

• [CHANGE] sora.conf の use_re_offer が true の場合 type: update を Sora に送るとエラーになるよう変更しました

• [CHANGE] sora.conf の use_re_offer のデフォルト値を true に変更しました

  • この設定は 2022 年 6 月リリース予定の Sora にて廃止します

• [CHANGE] sora.conf の unuse_metadata_list のデフォルト値を true に変更しました

  • この設定は 2022 年 6 月リリース予定の Sora にて廃止します

開発ツール

• [CHANGE] デモ機能を 開発ツール と名前を変更しました

• [CHANGE] sora.conf の demo を true にした場合 devtools が有効になるように変更しました

  • sora.conf の demo は 2022 年 6 月のリリースにて廃止します

  • 詳細は sora.conf の demo の廃止 をご確認ください

• [ADD] sora.conf に devtools を追加しました

  • デフォルトは false です

ウェブフック

• [ADD] 認証ウェブフックに node_name を追加しました

• [ADD] イベントウェブフックに node_name を追加しました

• [ADD] イベントウェブフックの recording.report に filename と file_path を追加しました

  • metadata_filename と metadata_file_path は 2022 年 12 月リリース予定の Sora で廃止します

  • 廃止対象は JSON 内の "data" 直下のフィールドのみで、 "archives" 以下にある metadata_filename と metadata_file_path は変更ありません

セッションウェブフック

詳細は セッションウェブフック をご確認ください。

• [ADD] sora.conf にセッションウェブフックの URL を指定する session_webhook_url を追加しました

• [ADD] sora.conf にセッション生成時のタイムアウトを指定する session_created_timeout を追加しました

  • デフォルトは 5 s です

• [ADD] sora.conf に セッション破棄時のタイムアウトを指定する session_destroyed_timeout を追加しました

  • デフォルトは 15 s です

• [ADD] session.created セッションウェブフックを追加しました

  • セッションが作成されたタイミングで送信します

• [ADD] session.destroyed セッションウェブフックを追加しました

  • セッションが破棄されたタイミングで送信します

• [ADD] session.vanished セッションウェブフックを追加しました

  • block_new_connection または block_new_session モード時にすべてのセッションが破棄されたタイミングで送信します

• [ADD] sora.conf に session.vanished をウェブフックリクエストとして送信しない ignore_session_vanished_webhook を追加しました

  • デフォルトは true です

• [ADD] セッションウェブフックリクエスト送信時の HTTP ヘッダーに x-sora-session-webhook-type を追加しました

  • ヘッダーの値は type の値が入ります

• [ADD] セッションウェブフックのログを出力する log/session_webhook.log を追加しました

• [ADD] セッションウェブフックの失敗ログを出力する log/session_webhook_failed.log を追加しました

• [ADD] GetStatsReport API に合計セッション生成回数 total_session_created を追加しました

• [ADD] GetStatsReport API に合計セッション破棄回数 total_session_destroyed を追加しました

モード機能

詳細は モード機能 をご確認ください。

• [ADD] 新規セッションやコネクションを受け付けなくするモードの仕組みを追加しました

  • 初期値は normal です

  • sora.conf にて cluster を有効にしたときの初期値は block_new_connection です

• [ADD] モードを切り替える ChangeMode API を追加しました

  • "mode": "normal" を指定するとすべての新規コネクションを受け付けます

  • "mode": "block_new_session" を指定することで新規セッションをブロックすることができます

  • "mode": "block_new_connection" を指定することで新規コネクションをブロックすることができます

• [ADD] 現在のモードを取得する GetMode API を追加しました

クラスター機能

詳細は クラスター機能 をご確認ください。

• [ADD] クラスター機能利用時にどのノードへも接続ができない場合 NO-ACCEPTABLE-NODE を出力するようにしました

• [ADD] 複数 Sora でクラスターを構築し、冗長化する機能を追加しました

• [ADD] クラスター機能利用時に新規のチャネルへの接続する際、同時接続に余裕のある Sora ノードに割り当てる機能を追加しました

• [ADD] クラスター機能利用時に既存のチャネルへの接続する際、そのチャネルへの接続が存在する Sora ノードに割り当てる機能を追加しました

• [ADD] シグナリング接続時に別の Sora ノードにリダイレクトする "type": "redirect" を追加しました

  • リダイレクト先のシグナリング URL が "location": "wss://node01.example.com/signaling" に含まれます

• [ADD] リダイレクト先のシグナリング URL を利用する際に "redirect": true を "type": "connect" に追加できるようにしました

• [ADD] sora.conf にクラスター利用時にリダイレクトに利用する cluster_signaling_url の設定を追加しました

  • cluster_signaling_url = wss://node01.example.com/signaling

• [ADD] sora.conf にクラスター利用時の Sora ノード名を指定する cluster_node_name の設定を追加しました

  • cluster_node_name = node01@192.0.2.10

• [ADD] sora.conf にクラスター利用時に API URL を指定する cluster_api_url の設定を追加しました

  • cluster_api_url = https://node01.example.com/

• [ADD] sora.conf にクラスター利用時のノード間通信に使用するポート番号を指定する cluster_listen_min_port と cluster_listen_max_port の設定を追加しました

  • デフォルトは cluster_listen_min_port が 49010 で、 cluster_listen_max_port が 49020 です

• [ADD] クラスターに参加するための JoinCluster API を追加しました

  • クラスターからの離脱は bin/sora stop を実行します

• [ADD] クラスターに参加しているノード一覧を取得するための ListClusterNodes API を追加しました

• [ADD] クラスターに割り当てられているチャネル ID 一覧を取得するための ListClusterChannels API を追加しました

音声冗長化機能

この機能は Chrome 96 以降で利用できます

• [ADD] sora.conf に 音声冗長化機能を有効にする audio_red を追加しました。

  • デフォルトは false です

  • 音声冗長化についての詳細は PSA: opus+red enabled by default in M96 を参照ください

• [ADD] 1 チャネルへの接続が audio_red への対応が混在していてもやりとりできるようにしました。

録画機能

• [ADD] AV1 の録画に対応しました

  • この機能は Chrome 96 以降で利用できます

• [ADD] StartRecording API にて metadata を指定可能にしました

  • metadata は JSON オブジェクトである必要があります

  • metadata はオプションです

• [ADD] recording.report や録画メタデータファイルに StartRecording API で指定した metadata を出力するようにしました

  • 指定しなければ metadata が出力されません

• [ADD] シグナリング通知を利用している場合、録画開始時に "event_type": "recording.started" が通知されるようになりました

• [ADD] シグナリング通知を利用している場合、録画終了時に "event_type": "recording.stopped" が通知されるようになりました

• [ADD] sora.conf に録画関連をシグナリング通知で送信するかどうかを指定する signaling_notify_recording を追加しました

統計エクスポーター機能

クライアントから送られてきた統計情報を HTTP/2 経由で外部へ出力する機能です。

詳細は 統計エクスポーター機能 をご確認ください。

• [ADD] sora.conf に統計エクスポーターの接続先を指定する stats_collector_url を追加しました

  • stats_collector_url = http://h2c.example.com:5890/collector

  • stats_collector_url = https://h2.example.com/collector

• [ADD] 統計コレクターへ送信時の HTTP ヘッダーに x-sora-stats-exporter-type を追加しました

  • ヘッダーの値は type の値が入ります

• [ADD] sora.conf に統計エクスポーターの数を指定する stats_exporter_number を追加しました

  • デフォルトは 5 です

• [ADD] sora.conf に stats_exporter_tls_fullchain_file を追加しました

• [ADD] sora.conf に stats_exporter_tls_privkey_file を追加しました

• [ADD] sora.conf に stats_exporter_tls_verify_cacert_file を追加しました

• [ADD] 頻繁に送らない項目を定義しました

  • 1 h に 1 回送ります

  • codec / local-candidate / remote-candidate / certificate / peer-connection / track-stream

スポットライト機能

フォーカス/アンフォーカス挙動変更 API を追加しました。

• [ADD] スポットライトのフォーカス/アンフォーカス挙動を変更する RequestSpotlightRid API` を追加しました

• [ADD] スポットライトのフォーカス/アンフォーカス挙動をリセットする ResetSpotlightRid API を追加しました

• [ADD] スポットライトのフォーカス/アンフォーカス挙動を一括で変更する BatchRequestSpotlightRid API を追加しました

ICE コネクションステート機能

詳細は ICE コネクションステート機能 をご確認ください。

• [ADD] sora.conf に ice_connection_state_disconnected_timeout を追加しました

  • デフォルトは 5 s です

• [ADD] sora.conf に ice_connection_state_failed_timeout を追加しました

  • デフォルトは 10 s です

• [ADD] sora.log に warning で ICE-CONNECTION-DISCONNECTED が出力されるようになりました

  • 1000 ms 間隔で 5 秒間 STUN Binding-Request を送っても 1 度も STUN Binding-Success が返ってこない場合に出力されます

  • 1000 ms は sora.conf の ice_connection_state_disconnected_timeout にて変更できます

• [ADD] sora.log に error で ICE-CONNECTION-FAILED が出力されるようになりました

  • この場合 Sora は接続を切断します

  • 50 ms 間隔で 10 秒間 STUN Binding-Request を送っても 1 度も STUN Binding-Success が返ってこない場合に出力されます

  • 50 ms は sora.conf の ice_connection_state_failed_timeout にて変更できます

DataChannel 機能

• [CHANGE] 利用しない DataChannel を作成しない仕組みを追加しました

  • sora.conf の signaling_notify が無効の場合は label: notify の DataChannel は作成しません

  • sora.conf の sora_conf-e2ee が無効の場合は label: e2ee の DataChannel は作成しません

  • sora.conf の user_agent_stats が無効の場合は label: stats の DataChannel は作成しません

• [CHANGE] dcsctp_association_max_retrans を廃止しました

  • 切断判定には ICE コネクションステート機能が利用されます

メッセージング機能

詳細は リアルタイムメッセージング機能 をご確認ください。

DataChannel を利用したメッセージをユーザーが提起して自由に送ることができる機能です。ラベルは # から始まる必要があります。

• [ADD] type: connect に data_channels を追加しました

  • メッセージ機能は [{"label": "#abc", "direction": "sendrecv"}, ...] で指定できます

  • メッセージのラベルを指定する label を追加しました

    • ^#[a-zA-Z0-9][a-zA-Z0-9-]{1,30}$

  • メッセージのメッセージの方向を指定する direction を追加しました

    • sendrecv / sendonly / recvonly のどれかを指定して下さい

    • 方向はクライアントから見た視点で role と同様です

  • メッセージの順番を指定する ordered を追加しました

    • デフォルトは true です

  • メッセージのリトライ時間を指定する max_packet_life_time を追加しました

    • デフォルト指定無しです

    • 単位はミリ秒です

  • メッセージのリトライ回数を指定する max_retransmits を追加しました

    • デフォルト指定無しです

  • メッセージの圧縮を指定する compress を追加しました

    • デフォルトは false です

• [ADD] sora.conf に data_channel_messaging を追加しました

  • デフォルトは false です

• [ADD] 認証成功時の払い出しで data_channels を指定できるようにしました

  • "type": "connect" 時に、指定された data_channels を上書きできます

• [ADD] sora.conf に data_channel_messaging_only を追加しました

  • デフォルトは false です

ユーザーエージェント統計 API

リモート統計情報 API の名前を変更し整理した API です。

リモート統計情報 API は 2022 年 6 月リリースの Sora にて廃止しますので、 ユーザーエージェント統計情報 API に切り替えをお願いします。

• [CHANGE] remote_stats をデフォルト false にしました

• [ADD] sora.conf に user_agent_stats を追加しました

  • デフォルトは true です

  • remote_stats は 2022 年 6 月にて廃止します

• [ADD] ListUserAgentStats API を追加しました

  • GetAllRemoteStats の代替 API です

• [ADD] ListChannelUserAgentStats API を追加しました

  • GetChannelRemoteStats の代替 API です

• [ADD] GetUserAgentStats API を追加しました

  • GetConnectionRemoteStats の代替 API です

2021.1.4

リリース:

2021-10-29

対応 Chrome:

M95 以降

対応 Firefox:

93 以降

対応 Safari:

15.1 以降

対応 Edge:

95 以降

変更履歴

• [FIX] ネットワークが不安定な場合に録画が失敗する問題を修正しました

• [FIX] Safari を利用した場合に特定条件で復号が失敗する問題を修正しました

2021.1.2

リリース:

2021-09-17

対応 Chrome:

M93 以降

対応 Firefox:

92 以降

対応 Safari:

14.1 以降

対応 Edge:

93 以降

変更履歴

• [UPDATE] デモ機能で利用している sora-demo を 2021.1.6 にアップデートしました

• [ADD] 切断 API の reason を指定した場合に、指定した reason が、イベントウェブフック connection.destroyed に disconnect_api_reason として含まれるようになりました

  • 今まで reason として入ってきていたのと同じ値が入ります

• [ADD] "type": "disconnect" に reason を指定した場合に、指定した reason が、イベントウェブフック connection.destroyed に type_disconnect_reason として含まれるようになりました

• [ADD] イベントウェブフック connection.* の data に "created_time": "connection.created 時の UNIX 時刻" を追加しました

• [ADD] sora.conf にスポットライトでフォーカスされた後、一定時間追い出されなくなる default_spotlight_focus_min_interval を追加しました

  • デフォルトは 2000 ms です

• [FIX] スポットライト機能で複数人が音を出し続けていると頻繁にフォーカスが入れ替わる問題を修正しました

  • アンフォーカス後のフォーカスは、最低でも default_spotlight_delayed_focus_interval だけ待つようになりました

• [FIX] スポットライト機能でアンフォーカスからフォーカスに変わるタイミングで音声や映像が配信されなくなる場合がある問題を修正しました

• [FIX] スポットライト機能で自動アンフォーカスが指定した時間よりも速く行われる問題を修正しました

• [FIX] IPv6 のみで正常に接続できない場合がある問題を修正しました

• [FIX] クライアントから "type": "candidate" を送ることができる回数を 20 から 50 に変更しました

• [FIX] DataChannel におけるエンドポイント障害検出カウンターのリセットタイミングを修正しました

• [FIX] 一部の HTTP API のバリデーションが正常に動作していない問題を修正しました

• [FIX] シグナリングが DataChannel に切り替わったタイミングで WebSocket のアイドルタイムアウトが無制限になるように修正しました

• [FIX] SRTP/SRTCP の暗号が AES-GCM の場合に、長時間配信すると正常に復号できなくなる問題を修正しました

• [FIX] sora.conf の不要なコメントを削除しました

2021.1

リリース:

2021-06-23

対応 Chrome:

M91 以降

対応 Firefox:

89 以降

対応 Safari:

14.1 以降

対応 Edge:

91 以降

廃止情報

role の upstream と downstream を廃止

role の upstream と downstream を廃止しました。

詳細は role の upstream と downstream を廃止 をご確認ください。

allow_client_id_assignment 設定を廃止

接続時や認証成功時に、常に client_id を指定できるようになり、 sora.conf の allow_client_id_assignment を廃止しました。

詳細は client_id を指定する設定の廃止 をご確認ください。

旧サイマルキャスト API を廃止

Sora_20180820.ChangeSimulcastQuality API を廃止しました。

詳細は 旧サイマルキャスト画質変更 API の廃止 をご確認ください。

互換なしの変更情報

廃止以外の互換性がない機能変更はありません。

実験的機能から正式機能へ昇格

• Sora_20201120.PushChannelByRole API

• Sora_20201120.DisconnectChannelByRole API

ハイライト

• スポットライト機能に rid 指定機能を追加しました

• スポットライト機能に遅延フォーカス機能を追加しました

• スポットライト機能に自動アンフォーカス機能を追加しました

• スポットライト機能にフォーカスなしの音声配信機能を追加しました

• シグナリングを WebSocket から DataChannel へ切り替える機能を追加しました

• DataChannel 経由のシグナリング利用時に WebSocket の切断を無視する機能を追加しました

• より少ない CPU リソースでより多くの接続を処理できるようになりました

変更履歴

• [UPDATE] デモ機能で利用している sora-demo を 2021.1 にアップデートしました

• [UPDATE] より少ない CPU リソースで多くの接続を処理できるようになりました

• [ADD] TURN-TCP 利用時の Proxy Protocol v1 へ対応しました

  • これに伴い TURN-TLS、TURN-TCP、シグナリングで 443 番ポートを使用する の内容が Sora 2021.1 向けに変更されています

  • nginx の変更はしなくても動作しますが、変更をお勧めします

• [ADD] シグナリング "type": "offer" 時に配信で有効になっている audio または video の mid を含めるようにしました

  • 例: "type": "offer", "mid": {"audio": "audio_lFaJYL", "video": "video_lMjsoq"}

• [ADD] "type": "udpate" の代わりに "type": "re-offer" を送れるように、 sora.conf に use_re_offer を追加しました

  • デフォルトは false です

  • この設定は 2021 年 12 月リリースの Sora にてデフォルト true に変更されます

  • この設定は 2022 年 6 月リリースの Sora にて廃止され、常に "type": "re-offer" が送られるようになります

• [ADD] シグナリング通知メタデータの利用時に、 metadata_list の代わりに data を送れるように、 sora.conf に unuse_metadata_list を追加しました

  • デフォルトは false です

  • この設定は 2021 年 12 月リリースの Sora にてデフォルト true に変更されます

  • この設定は 2022 年 6 月リリースの Sora にて廃止され、常に data が送られるようになります

• [FIX] 録画機能の利用時で映像が送られてこない際に WebM の PixelWidth / PixelHeight が 0 になる問題を修正しました

• [FIX] 不安定な回線や音声パケットが送られてこなくなる場合にクライアント側でリップシンクが正常に行われず、音声と映像がずれてしまう問題を修正しました

• [FIX] 音声クロックレートが 48000 Hz 固定になってしまう問題を修正しました

• [FIX] スポットライトレガシーで recvonly が利用できてしまう問題を修正しました

• [FIX] TURN-TCP で問題があった際に、シグナリングを切断しない限り接続が残り続ける問題を修正しました

統計機能

• [ADD] RTP ヘッダー拡張の統計情報を追加しました

• [ADD] サイマルキャストの rid 単位の RTP 統計情報を追加しました

• [ADD] サイマルキャストの rid 単位の RTP ヘッダー拡張統計情報を追加しました

• [ADD] RTCP 統計情報を rtcp に移動しました

  • 2021 年 12 月のリリースにて rtp から RTCP 関連の統計情報を削除します

スポットライト機能

実験的機能

• [CHANGE] デフォルトの r0 の maxFramerate を 1.0 から 5.0 に変更しました

スポットライト機能: rid 指定

実験的機能

スポットライト利用時にフォーカス、アンフォーカスそれぞれで受信する映像を接続ごとに指定できるようになりました。 これによりモバイル端末や回線が不安定な場合は映像を一切受信しないなどの設定ができます。

• [ADD] アンフォーカス時に受信する rid を指定できるように、 sora.conf に default_spotlight_unfocus_rid を追加しました

  • デフォルトは r0

  • none, r0, r1, r2 を指定可能

• [ADD] フォーカス時に受信する rid を指定できるように、 sora.conf に default_spotlight_focus_rid を追加しました

  • デフォルトは r1

  • none, r0, r1, r2 を指定可能

• [ADD] アンフォーカス時に受信する rid を指定できるように、シグナリング "type": "connect" に spotlight_unfocus_rid を追加しました

  • デフォルトは sora.conf の default_spotlight_unfocus_rid の値が採用されます

  • none, r0, r1, r2 を指定可能

• [ADD] フォーカス時に受信する rid を指定できるように、シグナリング "type": "connect" に spotlight_focus_rid を追加しました

  • デフォルトは sora.conf の default_spotlight_focus_rid の値が採用されます

  • none, r0, r1, r2 を指定可能

• [ADD] アンフォーカス時に受信する rid を指定できるように、認証成功時の払い出しに、 spotlight_unfocus_rid を追加しました

  • デフォルトは sora.conf の default_spotlight_unfocus_rid の値が採用されます

  • "type": "connect" 時に、指定された spotlight_unfocus_rid を上書きできます

  • none, r0, r1, r2 を指定可能

• [ADD] フォーカス時に受信する rid を指定できるように、認証成功時の払い出しに spotlight_focus_rid を追加しました

  • デフォルトは sora.conf の default_spotlight_focus_rid の値が採用されます

  • "type": "connect" 時に、指定された spotlight_focus_rid を上書きできます

  • none, r0, r1, r2 を指定可能

スポットライト機能: 遅延フォーカス

実験的機能

スポットライト利用時に、ちょっとした物音やあいづちではすぐにフォーカスされないように、フォーカスを遅延させる機能を追加しました。 この機能によりサーバーからクライアントへのパケット流量を減らすことができるようになりました。

• [ADD] アンフォーカス時にフォーカスを遅延させるかどうかを指定できるように、 sora.conf に default_spotlight_delayed_focus を追加しました

  • デフォルトは true

• [ADD] アンフォーカス時にフォーカスを遅延させる時間を指定できるように、 sora.conf に default_spotlight_delayed_focus_interval を追加しました

  • デフォルトは 2000 ms

スポットライト機能: フォーカスなしの音声配信

実験的機能

スポットライト利用時に、他の人にフォーカスが移った場合でも音声を配信し続ける機能を追加しました。 この機能によりスポットライトの数が少ない場合でも、他の人がフォーカスされたことにより音声が送られなくなる、といったことがなくなりました。

• [ADD] フォーカスなしでも音声を配信するかどうかを指定できるように、 sora.conf に default_spotlight_unfocus_audio を追加しました

  • デフォルトは true

• [ADD] フォーカスなしでも音声を配信する上限レートを指定できるように、 sora.conf に default_spotlight_unfocus_audio_rate_limit を追加しました

  • デフォルトは 2

  • 単位は 1 音声ストリーム = 50 packets / s です

スポットライト機能: 自動アンフォーカス機能

実験的機能

スポットライト利用時に、一定時間音声が配信されていない場合はアンフォーカスする機能を追加しました。 この機能によりサーバーからクライアントへのパケット流量を減らすことができるようになりました。

• [ADD] 音がない場合に自動でアンフォーカスするかどうかを指定できるように、 sora.conf に default_spotlight_auto_unfocus を追加しました

  • デフォルトは true

• [ADD] 自動でアンフォーカスする無音時間を指定できるように、 sora.conf に default_spotlight_auto_unfocus_interval を追加しました

  • デフォルトは 10 s

  • 1 ms 以上、30 s 以下

  • API でフォーカスが固定されている場合は自動アンフォーカスの対象外になります

DataChannel 機能: シグナリングの WebSocket から DataChannel への切り替え機能

実験的機能

注釈

DataChannel は TURN を利用するため UDP が通らない場合でも問題なく繋がります。

重要

DataChannel 機能を利用する場合は Sora JavaScript SDK 2021.1 以降が必要になります

シグナリングやシグナリング通知、プッシュ通知などで利用している WebSocket から DataChannel へ切り替えます。

ただし WebSocket は切断判定に利用するため、Sora から切断することはありません 。

• [ADD] sora.conf に default_data_channel_signaling を追加しました

  • デフォルトは false です

• [ADD] シグナリング "type": "connect" で data_channel_signaling: boolean を指定できるようにしました

  • デフォルトは sora.conf の default_data_channel_signaling に設定された値です

• [ADD] 認証成功時の払い出しで data_channel_signaling: boolean を指定できるようにしました

  • デフォルトは sora.conf の default_data_channel_signaling に設定された値です

  • "type": "connect" 時に、指定された data_channel_signaling を上書きできます

• [ADD] シグナリング "type": "offer" 時に data_channel_signaling: boolean を払い出すようにしました

  • この払い出しは data_channel_signaling が true の時のみ有効です

• [ADD] WebSocket から DataChannel へ切り替わった場合は "type": "switched" が WebSocket 経由で送られるようにしました

  • "type": "switched" を送ったタイミングからWebSocket 経由の "type": "ping" の間隔が 5 秒から 30 秒へ変更されます

  • "type": "switched" を送ったタイミングからWebSocket 経由の "type": "pong" を確認しなくなります

以下の機能が DataChannel に切り替わります。

• シグナリング

  • DataChannel の label は signaling です

  • 以下が利用できるメッセージタイプです

    • "type": "re-offer"

    • "type": "re-answer"

    • "type": "disconnect"

• シグナリング通知

  • DataChannel の label は notify です

  • 以下が利用できるメッセージタイプです

    • "type": "notify"

• プッシュ通知

  • DataChannel の label は push です

  • 以下が利用できるメッセージタイプです

    • "type": "push"

• E2EE

  • DataChannel の label は e2ee です

• 統計情報

  • DataChannel の label は stats です

  • 以下が利用できるメッセージタイプです

    • "type": "req-stats"

    • "type": "stats"

DataChannel 機能: WebSocket の切断を無視する機能

実験的機能

重要

WebSocket の切断を切断判定に利用しない場合、 DataChannel におけるエンドポイント障害検出が切断の判断に利用されます。 この判断は sora.conf の dcsctp_association_max_retrans の値に依存します。

• [ADD] sora.conf に default_ignore_disconnect_websocket を追加しました

  • デフォルトは false です

  • この値を true にした場合、 DataChannel 経由でのシグナリング有効時に WebSocket を切断しても、Sora はクライアントの切断と見なさずに接続が継続します

• [ADD] "type": "connect" 時に ignore_disconnect_websocket: boolean を指定できるようにしました

  • デフォルトは sora.conf に設定された値です

  • この値を true にした場合、 DataChannel 経由でのシグナリング有効時に WebSocket を切断しても、Sora はクライアントの切断と見なさずに接続が継続します

• [ADD] 認証成功時の払い出しに ignore_disconnect_websocket: boolean を指定できるようにしました

  • デフォルトは sora.conf に設定された値です

  • "type": "connect" 時に、指定された ignore_disconnect_websocket を上書きできます

  • この値を true にした場合、 DataChannel 経由でのシグナリング有効時に WebSocket を切断しても、Sora はクライアントの切断と見なさずに接続が継続します

• [ADD] "type": "offer" 時に data_channel_signaling が true の場合 ignore_disconnect_websocket: boolean を払い出すようにしました

DataChannel 機能: メッセージの圧縮機能

実験的機能

DataChannel で送受信するメッセージを圧縮して送受信できる機能です。

"type": "offer" 時に送られてくる data_channels: [{"label": "signaling", "compress": true}, ...] のように compress が true になっている場合は圧縮して送る必要があります。

• [ADD] "type": "offer" 時に DataChannel の情報を送るようにしました

  • data_channels: [{"label": "<label>", "compress": boolean}, ...] の形式で送られてきます

  • DataChannel を有効にしていない場合は data_channels キーは含まれません

  • compress が true の場合、 DataChannel 経由でのメッセージを zlib/deflate で圧縮/展開する必要があります

DataChannel 機能: クライアント統計情報の要求

実験的機能

DataChannel 経由でのシグナリングが有効になると、統計情報を "type": "pong" に入れて返すのではなく、 サーバーから "type": "req-stats" が送られてきたら、 "type": "stats", "reports": [...] で送るという仕組みに切り替わります。

• [ADD] DataChannel 経由でのシグナリング利用時に label の stats から "type": "req-stats" が送られてきます

  • 送られてくる間隔は sora.conf の data_channel_stats_timer_interval で指定できます

• [ADD] sora.conf に data_channel_stats_timer_interval を追加しました

  • デフォルトは 5 s です

  • 最小は 5 s で最大は 300 s です

DataChannel 機能: サーバー統計情報

実験的機能

GetStats* 系 API に DataChannel 関連の Sora 統計情報を追加しました。

• [ADD] total_dropped_received_data_channel を追加

  • sora.conf にて data_channel_packet_loss_simulator_incoming を 0 ではない値を指定した際に破棄されたパケットの合計数です

• [ADD] total_dropped_sent_data_channel を追加

  • sora.conf にて data_channel_packet_loss_simulator_outgoing を 0 ではない値を指定した際に破棄されたパケットの合計数です

• [ADD] 項目に data_channel を追加しました

  • label 単位の統計情報が確認できます

  • total_received_data_channel_message

    • label 単位で受信したメッセージ数の合計

  • total_received_data_channel_message_byte_size

    • label 単位で受信したメッセージのバイト数の合計

  • total_sent_data_channel_message

    • label 単位で送信したメッセージの数の合計

  • total_sent_data_channel_message_byte_size

    • label 単位で送信したメッセージのバイト数の合計

• [ADD] 項目に sctp を追加しました

  • total_received_invalid_sctp

  • total_received_sctp

  • total_received_sctp_byte_size

  • total_received_sctp_chunk_abort

  • total_received_sctp_chunk_asconf

  • total_received_sctp_chunk_asconf_ack

  • total_received_sctp_chunk_auth

  • total_received_sctp_chunk_cookie_ack

  • total_received_sctp_chunk_cookie_echo

  • total_received_sctp_chunk_cwr

  • total_received_sctp_chunk_data

  • total_received_sctp_chunk_ecne

  • total_received_sctp_chunk_error

  • total_received_sctp_chunk_forward_tsn

  • total_received_sctp_chunk_heartbeat

  • total_received_sctp_chunk_heartbeat_ack

  • total_received_sctp_chunk_i_data

  • total_received_sctp_chunk_i_forward_tsn

  • total_received_sctp_chunk_init

  • total_received_sctp_chunk_init_ack

  • total_received_sctp_chunk_pad

  • total_received_sctp_chunk_reconfig

  • total_received_sctp_chunk_sack

  • total_received_sctp_chunk_shutdown

  • total_received_sctp_chunk_shutdown_ack

  • total_received_sctp_chunk_shutdown_complete

  • total_received_sctp_chunk_unknown

  • total_received_unknown_sctp

  • total_sent_sctp

  • total_sent_sctp_byte_size

  • total_sent_sctp_chunk_abort

  • total_sent_sctp_chunk_asconf

  • total_sent_sctp_chunk_asconf_ack

  • total_sent_sctp_chunk_auth

  • total_sent_sctp_chunk_cookie_ack

  • total_sent_sctp_chunk_cookie_echo

  • total_sent_sctp_chunk_cwr

  • total_sent_sctp_chunk_data

  • total_sent_sctp_chunk_ecne

  • total_sent_sctp_chunk_error

  • total_sent_sctp_chunk_forward_tsn

  • total_sent_sctp_chunk_heartbeat

  • total_sent_sctp_chunk_heartbeat_ack

  • total_sent_sctp_chunk_i_data

  • total_sent_sctp_chunk_i_forward_tsn

  • total_sent_sctp_chunk_init

  • total_sent_sctp_chunk_init_ack

  • total_sent_sctp_chunk_pad

  • total_sent_sctp_chunk_reconfig

  • total_sent_sctp_chunk_sack

  • total_sent_sctp_chunk_shutdown

  • total_sent_sctp_chunk_shutdown_ack

  • total_sent_sctp_chunk_shutdown_complete

  • total_sent_sctp_chunk_unknown

DataChannel 機能: 設定

実験的機能

詳細は DataChannel シグナリング機能 をご確認ください。

• [ADD] sora.conf に dcsctp_association_max_retrans を追加しました

  • DataChannel で利用している SCTP プロトコルのエンドポイント障害検出の最大再送値です

  • デフォルトは 10 です

  • 最小は 1 で最大は 128 です

• [ADD] sora.conf に dcsctp_heartbeat_interval を追加しました

  • DataChannel で利用している SCTP プロトコルのハートビートを送る間隔です

  • デフォルトは 30 s です

  • 最小は 0 s で最大は 120 s です

  • 0 s に設定した場合は SCTP レイヤーでのハートビートを送りません

• [ADD] sora.conf に data_channel_packet_loss_simulator_incoming を追加しました

  • デフォルトは 0 で無効です

  • Sora が受信する DataChannel のメッセージを、指定した割合で破棄します

• [ADD] sora.conf に data_channel_packet_loss_simulator_outgoing を追加しました

  • デフォルトは 0 で無効です

  • Sora が送信する DataChannel のメッセージを、指定した割合で破棄します

RTP ヘッダー拡張機能

実験的機能

RTP ヘッダー拡張の利用を指定できるようにしました。

• [ADD] sora.conf に RTP ヘッダー拡張 urn:3gpp:video-orientation を有効にする設定 rtp_hdrext_video_orientation を追加しました

  • デフォルトは false

• [ADD] sora.conf に RTP ヘッダー拡張 http://www.webrtc.org/experiments/rtp-hdrext/video-content-type を有効にする設定 rtp_hdrext_video_content_type を追加しました

  • デフォルトは false

• [ADD] sora.conf に RTP ヘッダー拡張 http://www.webrtc.org/experiments/rtp-hdrext/video-timing を有効にする設定 rtp_hdrext_video_timing を追加しました

  • デフォルトは false

• [ADD] sora.conf に RTP ヘッダー拡張 http://www.webrtc.org/experiments/rtp-hdrext/playout-delay を有効にする設定 rtp_hdrext_playout_delay を追加しました

  • デフォルトは false

• [ADD] sora.conf に RTP ヘッダー拡張 http://www.webrtc.org/experiments/rtp-hdrext/color-space を有効にする設定 rtp_hdrext_color_space を追加しました

  • デフォルトは false

• [ADD] sora.conf に RTP ヘッダー拡張 urn:ietf:params:rtp-hdrext:sdes:mid を有効にする設定 rtp_hdrext_sdes_mid を追加しました

  • デフォルトは false

2020.3.5

リリース:

2021-03-12

対応 Chrome:

M89 以降

対応 Firefox:

86 以降

対応 Safari:

14.0 以降

対応 Edge:

89 以降

変更履歴

• [UPDATE] デモ機能のバージョンを 2020.6.2 にアップデートしました

  • サイマルキャストの利用可能判定処理を改善した Sora JavaScript SDK 2020.6.2 にアップデートしています

• [FIX] ネットワークが不安定な場合に、リップシンクが正常に動作しない問題を暫定的に修正しました

  • 正式な対応は今後リリース予定です

• [FIX] サイマルキャスト利用時に複数の SSRC が r0 と判断されてしまう問題を修正しました

• [FIX] サイマルキャスト利用時に複数の SSRC に対する rid が重複した時に WARNING ログを出力するようにしました

• [FIX] サイマルキャスト利用時に、ストリームの切り替わりでブロックノイズが出る問題を修正しました

• [FIX] 映像の切り替えが発生した際に映像が乱れる問題を修正しました

• [FIX] VP8 サイマルキャストで Temporal Scalability が存在しない場合に、視聴側が切断される問題を修正しました

• [FIX] 実験的機能である opus_params が正常に利用できなくなっていた問題を修正しました

2020.3.3

リリース:

2021-02-03

対応 Chrome:

M88 以降

対応 Firefox:

85 以降

対応 Safari:

14.0 以降

対応 Edge:

88 以降

• [FIX] ライセンスファイルの接続上限数の半分を超えた時点で、接続数の超過エラーを示す EXCEED-MAX-CONNECTIONS が発生する問題を修正しました

  • バージョン 2020.3 / 2020.3.1 / 2020.3.2 がこの問題の影響を受けます

2020.3.2

リリース:

2021-01-19

対応 Chrome:

M87 以降

対応 Firefox:

84 以降

対応 Safari:

14.0 以降

対応 Edge:

87 以降

変更履歴

• [FIX] マルチストリーム機能利用時に、短い間に複数の接続・切断が発生した場合に、Sora から "type": "update" が連続で送られてしまう問題を修正しました

• [FIX] スポットライト機能のシグナリング通知 spotlight.focused と spotlight.unfocused に新しく spotlight_number を追加しました

  • この追加により ChangeSpotlightNumber API を実行した後に参加者が現時点でのスポットライト数を確認することができない問題を解決しています

2020.3.1

リリース:

2020-12-23

対応 Chrome:

M87 以降

対応 Firefox:

84 以降

対応 Safari:

14.0 以降

対応 Edge:

87 以降

変更履歴

• [FIX] スポットライト機能利用時に音声のみで接続できない問題を修正しました

• [FIX] サイマルキャスト利用時に映像を無効にしている場合に simulcast_rid を指定してもデフォルトの値が採用されてしまう問題を修正しました

• [FIX] サイマルキャスト機能やスポットライト機能利用時に RequestRtpStream API を利用すると、新規接続の rid が固定されてしまう問題を修正しました

• [FIX] サイマルキャスト機能やスポットライト機能利用時に ResetRtpStream API を利用すると、新規接続の rid が固定されてしまう問題を修正しました

• [FIX] ListPauseRtpStreams API の戻り値を recv_connection_id と send_connection_id に修正しました

2020.3

リリース:

2020-12-16

対応 Chrome:

M87 以降

対応 Firefox:

83 以降

対応 Safari:

14.0 以降

対応 Edge:

87 以降

互換なしの変更情報

変更点の不明点についてはサポートまでお問い合わせください

移行についての詳細は 2020.2.x から 2020.3.x をご確認ください。

• bin/sora start を廃止しました、今後は bin/sora daemon をお使いください

  • systemd を利用していて bin/sora foreground を利用されている方に影響はありません

• 録画ディレクトリ構成を変更しました

  • archive/ 以下にすべて生成するのではなくレコーディング ID 単位でディレクトリを生成するようになりました

• レコーディング ID を明示的にしました

  • StartRecording API の戻り値の id を recording_id に変更しました

  • recording.report イベントウェブフックの id を recording_id に変更しました

  • archive.available イベントウェブフックの data の中に recording_id を追加しました

• sora.conf にて時間を指定する設定項目で単位指定を必須にしました

  • 単位が必要な値を指定する場合は 30 s や 2000 ms といった単位を指定する必要があります

  • 数値と単位の間にはスペースを入れてください

  • 例: webhook_response_timeout = 5 s

  • 例: default_forwarding_pli_interval = 30000 ms

  • 例: connection_created_wait_timeout = 30 s

• サイマルキャスト機能の quality 指定をすべて rid に変更しました

• sora.conf の allow_client_id_assignment をデフォルト true に変更しました

• sora.conf の allow_client_id_assignment を true にした際にクライアントが client_id を含めない場合、認証ウェブフックに client_id が含まれないよう変更しました

  • いままでは client_id に null が入っていました

• sora.conf の spotlight_legacy をデフォルト false にしました

  • スポットライトレガシーを利用したい場合は sora.conf にて spotlight_legacy = true を設定してください

• 実験的機能として提供していた ChangeSimulcastQuality API を非推奨にしました

  • RequestRtpStream API を利用してください

• 実験的機能として提供していた RequestSpotlightQuality API を廃止しました

  • RequestRtpStream API を利用してください

• 実験的機能として提供していた ResetSpotlightQuality API を廃止しました

  • ResetRtpStream API を利用してください

• sora.conf の generic_nack_cache_size_msec を廃止しました

ハイライト

• Red Hat Enterprise Linux 8 向けパッケージを追加しました

• サイマルキャスト機能が正式版になりました

• サイマルキャストのエンコーディング設定がカスタマイズ可能になりました

• サイマルキャスト利用時の録画が可能になりました

• サイマルキャスト利用時の転送が可能になりました

• ウェブフックにベーシック認証機能を追加しました

• 実験的機能として録画ファイル分割出力機能を追加しました

• 実験的機能としてシグナリング通知メタデータ拡張機能を追加しました

• 実験的機能として E2EE (End to End Encryption) 機能を追加しました

• 実験的機能として認証ウェブフックログ機能を追加しました

変更履歴

Red Hat Enterprise Linux 8 対応

CentOS 8 のサポートが 2021 年 12 月に終了することが発表されました。 それにともない時雨堂では Red Hat Enterprise Linux 8 向けのパッケージを用意しました。

• [ADD] Red Hat Enterprise Linux 8 向けパッケージを追加しました

サイマルキャスト機能

• [CHANGE] quality の指定をすべて rid に変更しました

  • rid とはサイマルキャストのストリームそれぞれに付いている id です

  • rid は r0 / r1 / r2 があります

  • rid には優先度があり、数値が少ないほど優先されて配信されます

  • r0 は必ず配信されますが、回線が不安定になったりした場合は r2 -> r1 の順番で配信が停止していきます

• [ADD] 実験的機能として rid をリクエストできる RequestRtpStream API を追加しました

• [ADD] 実験的機能として rid をリセットできる ResetRtpStream API を追加しました

• [FIX] 視聴者が受信するストリームの rid 変更後に配信側を再接続した場合に状態が不整合になる問題を修正しました

  • マルチストリームが無効な状態でのみ発生していた問題です

サイマルキャストエンコーディング設定のカスタマイズ機能

• [ADD] sora.conf に simulcast_encodings_file を追加しました

  • simulcast_encodings_file = etc/simulcast_encodings.json といったかたちで JSON ファイルを指定可能になります

  • 詳細は 映像のエンコーディングパラメータのカスタマイズ をご確認ください

• [ADD] 認証成功時の払い出しに simulcast_encodings を追加しました

  • 詳細は simulcast_encodings の払い出し をご確認ください

サイマルキャスト録画機能

• [ADD] サイマルキャストで録画機能が利用可能になりました

  • 配信されている 優先度が一番低い映像 を録画します

    • r0 / r1 / r2 の 3 本が配信されていれば r2 が録画されます

    • 優先度が低い映像については 映像の優先度 をご確認ください

サイマルキャスト転送機能

• [ADD] サイマルキャストで転送機能が利用可能になりました

• [ADD] sora.conf に forwarding_simulcast を追加しました

  • all と single が指定できます

    • all は配信されているすべてのストリームが転送されます

    • single は配信されている優先度が低いストリームが転送されます

      • 優先度が低い映像については 映像の優先度 をご確認ください

スポットライト機能

• [FIX] 認証ウェブフック通知に spotlight / spotlight_number を追加しました

  • sora.conf にて spotlight_legacy = false の場合に含まれます

スポットライトのサイマルキャストエンコーディング設定カスタマイズ機能

• [ADD] sora.conf に spotlight_encodings_file を追加しました

  • spotlight_encodings_file = etc/spotlight_encodings.json といったかたちで JSON ファイルを指定可能になります

  • 設定方法は simulcast_encodings_file と同様ですが spotlight 時のみ利用されます

  • 詳細は スポットライト利用時の映像のエンコーディングパラメータのカスタマイズ をご確認ください

• [ADD] 認証成功時の払い出しに spotlight_encodings を追加しました

  • 詳細は spotlight_encodings の払い出し をご確認ください

ウェブフックベーシック認証機能

ウェブフックを通知する際にベーシック認証を利用できるようになりました。

• [ADD] sora.conf にウェブフックのベーシック認証を有効にする webhook_basic_authn を追加しました

  • デフォルトは false です

• [ADD] sora.conf にウェブフックのベーシック認証に利用するユーザー ID を指定する webhook_basic_authn_user_id を追加しました

• [ADD] sora.conf にウェブフックのベーシック認証に利用するパスワードを指定する webhook_basic_authn_password を追加しました

ウェブフックを安全でない通信でも利用できる機能

ウェブフックを HTTPS で利用する際に証明書のチェックを行わなくできます。自己署名証明書などが利用できるようになりました。

• [ADD] sora.conf にウェブフックの安全でない通信を許可する webhook_insecure を追加しました

  • デフォルトは false です

認証ウェブフック機能

• [CHANGE] sora.conf の allow_client_id_assignment を true にした際、クライアントが client_id を指定しない場合、認証ウェブフックに client_id を含まないよう変更しました

  • いままでは client_id に null が入っていました

イベントウェブフック機能

• [CHANGE] イベントウェブフック connection.* の channel_upstream_connections を非推奨にしました

  • 2021 年 6 月廃止予定です

• [CHANGE] イベントウェブフック connection.* の channel_downstream_connections を非推奨にしました

  • 2021 年 6 月廃止予定です

• [ADD] イベントウェブフック connection.* に simulcast: boolean と spotlight: boolean の項目を追加しました

  • spotlight_legacy は非対応です

• [ADD] 実験的機能としてイベントウェブフック connection.* に channel_sendrecv_connections を追加しました

  • 送受信している接続数

• [ADD] 実験的機能としてイベントウェブフック connection.* に channel_sendonly_connections を追加しました

  • 送信のみしている接続数

• [ADD] 実験的機能としてイベントウェブフック connection.* に channel_recvonly_connections を追加しました

  • 受信のみしている接続数

• [FIX] WebRTC が確立していなくてもイベントウェブフック connection.updated が発火してしまう問題を修正

  • sora.conf と connection_created_timeout を 60 秒以上にしており、パケロスがひどい場合のみ発生していました

• [FIX] イベントウェブフック connection.destroyed の reason に Disconnect API で指定した値以外が入ってくるのを修正しました

録画機能

• [FIX] 録画機能利用時に WebM ヘッダーとイベントウェブフック通知に含まれる解像度が最大解像度にならない問題を修正しました

• [FIX] 録画メタデータファイルのタイムスタンプが WebM の最初および最後のフレームの時刻とずれていた問題を修正しました

録画ディレクトリ構成とファイル名の変更

• [CHANGE] レコーディング ID 単位でディレクトリを生成しその下に録画ファイル、録画メタデータファイル、録画レポートファイルを生成するように変更しました

  • レコーディング ID とは StartRecording API の戻り値に入っている recording_id です

• [CHANGE] 録画ファイルの名前を archive-<connection_id>.webm に変更しました

• [CHANGE] 録画メタデータファイルの名前を archive-<connection_id>.json に変更しました

• [CHANGE] 録画レポートファイルの名前を report-<recording_id>.json に変更しました

録画ファイル分割出力機能

実験的機能

• [ADD] StartRecording に分割録画間隔を指定する split_duration を追加しました

  • 指定は秒で行い、最大 86400 秒 (24 時間) まで指定できます

    • 3600 秒を指定する例

    • {"split_duration": 3600}

  • split_duration を指定すると今までの録画終了時に出力されるファイルとは別に指定した時間間隔で録画ファイルを出力します

  • ファイルは archive-<Connection-ID>_0001.webm として出力されます

  • メタデータファイルは archive-<Connection-ID>_0001.json として出力されます

  • 連番は 0001 開始で 9999 までいったら 10000 となりそのあとは 10001 と続きます

• [ADD] StartRecording に分割録画のみを行う split_only を追加しました

  • この指定をする場合はかならず split_duration を指定し、 expire_time を 0 に指定する必要があります

    • {"split_duration": 180, "split_only": true, "expire_time": 0}

  • この指定を有効にした場合はイベントウェブフックの recording.report を通知しません

  • この指定を有効にした場合は録画終了時にファイル出力を行いません

• [ADD] 録画ファイル分割出力用の archive.split イベントウェブフックを追加しました

  • このウェブフックは分割録画がファイルが出力された際に通知します

  • 詳細は archive.split をご確認ください

• [ADD] 録画ファイル分割出力用の archive.end イベントウェブフックを追加しました

  • このウェブフックは分割録画が終了した際に通知します

  • 詳細は archive.end をご確認ください

レコーディング ID の明示化

• [CHANGE] StartRecording API の戻り値の id を recording_id に変更しました

• [CHANGE] recording.report イベントウェブフックの data の中の id を削除しました

• [CHANGE] recording.report イベントウェブフックの data の中に recording_id を追加しました

• [CHANGE] archive.available イベントウェブフックの data の中の id を削除しました

• [ADD] archive.available イベントウェブフックの data の中に recording_id を追加しました

• [ADD] archive.failed イベントウェブフックの data の中に recording_id を追加しました

デモ機能

• [UPDATE] 組み込みのデモ機能のバージョンを 2020.4.0 にアップデートしました

sora.conf 設定

• [CHANGE] sora.conf の allow_client_id_assignment をデフォルト true に変更しました

• [CHANGE] sora.conf の generic_nack_cache_size_msec を廃止しました

  • 内部的な設定のため非公開設定としました

• [CHANGE] sora.conf の spotlight_legacy のデフォルトを false にしました

  • スポットライトレガシーを利用したい場合は sora.conf にて spotlight_legacy = true を設定してください

• [CHANGE] sora.conf から turn_fqdn の記載を削除しました

  • 設定が非推奨のため削除しました。設定自体はできます

• [CHANGE] 時間を指定する設定項目の単位を明示的に指定するようにしました

  • 単位が必要な値を指定する場合は 30 s や 2000 ms といった単位を指定する必要があります

  • 数値と単位の間にはスペースを入れてください

  • 単位指定が必要になった設定項目

    • webhook_response_timeout

    • connection_created_wait_timeout

    • default_forwarding_pli_interval

  • 詳細は 単位指定 をご確認ください

DTLS 再送制御

• [UPDATE] DTLS パケットをしつこく再送するようにしました

  • hello ハンドシェイクはハンドシェイクパケットとタイマーをトリガーにしてしつこく再送します

  • cipher ハンドシェイクはハンドシェイクパケットをトリガーにしつこく再送します

スポットライトレガシー機能

• [FIX] スポットライトレガシー利用時に音声のみを指定した場合に受信も音声のみになってしまう問題を修正

E2EE (End to End Encryption) 機能

実験的機能

• [ADD] シグナリングに E2EE 用のメッセージングルーティング機能を追加しました

• [ADD] 認証ウェブフック時に通知する項目として e2ee を追加しました

  • 型は boolean となります

• [ADD] sora.conf に E2EE を利用可能にするかどうかの e2ee = true を追加しました

  • 詳細は e2ee_true をご確認ください

シグナリング通知メタデータ

• [ADD] 接続時に送られてきた signaling_notify_metadata は metadata 以外に authn_metadata としてシグナリング通知時に含めるようにしました

• [ADD] 認証成功時に払い出した signaling_notify_metadata は metadata 以外に authz_metadata としてシグナリング通知時に含めるようにしました

• [ADD] 接続時に送る signaling_notify_metadata の最大サイズを指定できる sora.conf に signaling_notify_authn_metadata_max_size を追加しました

  • デフォルトは 64512 で、 64 KiB です

  • 0..1048576 (1 MiB) の範囲で指定できます

シグナリング通知メタデータ拡張機能

実験的機能

• [ADD] sora.conf にシグナリング通知メタデータ拡張を有効にする signaling_notify_metadata_ext を追加しました

  • デフォルトは false です

  • この設定を有効にした場合、接続時に送った signaling_notify_metadata は authn_metadata となります

    • metadata は初期値 {} となります

  • この設定を有効にした場合、認証成功時に払い出した signaling_notify_metadata は authz_metadata となります

    • metadata は初期値 {} となります

• [ADD] 指定したチャネルのシグナリング通知メタデータ一覧を取得する ListSignalingNotifyMetadata API を追加しました

• [ADD] 指定した接続の metadata を取得する GetSignalingNotifyMetadata API を追加しました

• [ADD] 指定した接続の metadata を追加する PutSignalingNotifyMetadata API を追加しました

• [ADD] 指定した接続の metadata を削除する DeleteSignalingNotifyMetadata API を追加しました

• [ADD] 指定した接続の metadata のアイテムを追加する PutSignalingNotifyMetadataItem API を追加しました

• [ADD] 指定した接続の metadata のアイテムを削除する DeleteSignalingNotifyMetadataItem API を追加しました

認証ウェブフックログ機能

実験的機能

認証ウェブフックのログを出力するように変更しました。リクエストとレスポンスを一つの JSON としてログに書き込みます。

• [ADD] 認証イベントウェブフックのリクエストとレスポンスを log/auth_webhook.log として出力するようにしました

• [ADD] sora.conf に認証イベントフェブフックのログ出力するかどうかの auth_webhook_log を追加しました

  • デフォルトで有効です

認証成功時での H.264 プロファイルレベルの指定機能

実験的機能

H.264 利用時にプロファイル ID を認証成功時の払い出しに指定可能にしました。

• [ADD] 認証払い出し時の h264_profile_level_id を指定可能にしました

  • 文字列で指定することで SDP の払い出しが可能になります

  • この払い出しは sora.conf の設定を上書きします

廃止機能

• [CHANGE] bin/sora start を廃止しました、今後は bin/sora daemon をお使いください

  • 詳細は 廃止機能 をご確認ください

新規 API

新しく API を追加しました。既存 API のアップデート版となります。

• [ADD] 新しく ListConnections API を追加しました

  • すべての接続リストが返ってきます

  • 詳しくは ListConnections API をご確認ください

• [ADD] 新しく ListChannelConnections API を追加しました

  • 指定したチャネルの接続リストが返ってきます

  • 詳しくは ListChannelConnections API をご確認ください

実験的 API

実験的機能

• [CHANGE] 実験的機能として提供している PauseRtpStream API と ResumeRtpStream API のパラメータを変更しました

  • connection_id を recv_connection_id に変更しました

  • stream_id を send_connection_id に変更しました

• [ADD] 実験的機能として ListChannels API を追加しました

  • すべてのチャネルリストが返ってきます

  • 詳しくは ListChannels API をご確認ください

• [ADD] 実験的機能として DisconnectChannelByRole API を追加しました

  • 指定したチャネルの指定したロールの接続をすべて切断します

• [ADD] 実験的機能として PushChannelByRole API を追加しました

  • 指定したチャネルの指定したロールの接続にプッシュ通知を送ります

• [FIX] 実験的機能として提供している ChangeUpstreamVideoBitRate API の利用時に新規接続が走るとビットレートが戻ってしまう問題を修正しました

非推奨 API

• [CHANGE] 切断用の DisconnectChannelUpstream API を非推奨 API としました

  • 実験的機能として提供している DisconnectChannelByRole API を利用してください

  • 2021 年 6 月廃止します

• [CHANGE] 切断用の DisconnectChannelDownstream API を非推奨 API としました

  • 実験的機能として提供している DisconnectChannelByRole API を利用してください

  • 2021 年 6 月廃止します

• [CHANGE] プッシュ用の PushUpstream API を非推奨 API としました

  • 実験的機能として提供している PushChannelByRole API を利用してください

  • 2021 年 6 月廃止します

• [CHANGE] プッシュ用の PushDownstream API を非推奨 API としました

  • 実験的機能として提供している PushChannelByRole API を利用してください

  • 2021 年 6 月廃止します

• [CHANGE] 実験的機能として提供していたサイマルキャスト用の ChangeSimulcastQuality API を非推奨 API としました

  • 実験的機能として提供している RequestRtpStream API を利用してください

  • 2021 年 6 月廃止します

• [CHANGE] 実験的機能として提供していたスポットライトレガシー用の CastAlwaysSpotlight API を非推奨 API としました

  • 2021 年 12 月廃止します

• [CHANGE] 実験的機能として提供していたスポットライトレガシー用の CancelSpotlight API を非推奨 API としました

  • 2021 年 12 月廃止します

• [CHANGE] 実験的機能として提供していたスポットライトレガシー用の CastSpotlight API を非推奨 API としました

  • 2021 年 12 月廃止します

• [CHANGE] 実験的機能として提供していたスポットライトレガシー用の DowngradeSpotlightBitRate API を非推奨 API としました

  • 2021 年 12 月廃止します

• [CHANGE] 実験的機能として提供していたスポットライトレガシー用の ResetSpotlightBitRate API を非推奨 API としました

  • 2021 年 12 月廃止します

廃止 API

• [CHANGE] 実験的機能として提供していた RequestSpotlightQuality API を廃止しました

  • 実験的機能として提供している RequestRtpStream API を利用してください

• [CHANGE] 実験的機能として提供していた ResetSpotlightQuality API を廃止しました

  • 実験的機能として提供している ResetRtpStream API を利用してください

2020.2.2

リリース:

2020-10-07

対応 Chrome:

M86

対応 Firefox:

81

対応 Safari:

14.0

対応 Edge:

86

変更履歴

• [FIX] Disconnect API や {"type": "disconnect"} を利用して切断した際に SIGNALING-INTERNAL-ERROR がクライアントに返される問題を修正しました

• [FIX] WebSocket ping フレームが internal.log に出力されてしまう問題を修正しました

2020.2.1

リリース:

2020-09-23

対応 Chrome:

M85

対応 Firefox:

80

対応 Safari:

14.0

対応 Edge:

85

変更履歴

• [FIX] デモ機能が有効にならない不具合を修正しました

2020.2

リリース:

2020-09-23

対応 Chrome:

M85

対応 Firefox:

80

対応 Safari:

14.0

対応 Edge:

85

互換なしの変更情報

• 今までのスポットライト機能の呼び名がスポットライトレガシー機能に変更しました

  • ignore_spotlight_changed_webhook を ignore_spotlight_legacy_changed_webhook に変更しました

  • spotlight_auto_downgrade_bit_rate を spotlight_legacy_auto_downgrade_bit_rate に変更しました

  • spotlight_auto_sharing_video_bit_rate を spotlight_legacy_auto_sharing_video_bit_rate に変更しました

  • スポットライトレガシー機能は 2021 年 12 月まで利用できます

ハイライト

• デモ機能を 1 から作り直し、オープンソースとして公開しました

  • https://github.com/shiguredo/sora-devtools

• 実験的機能として、新しいスポットライト機能を追加しました

  • スポットライト機能

変更履歴

• [FIX] connection.log の remote_stats が出力されない問題を修正しました

新しいデモ機能

デモ機能を TypeScript / React / Redux を利用して書き直しました。 また、ソースコードを Apache License 2.0 でオープンソースとして公開しました。

https://github.com/shiguredo/sora-devtools

• [CHANGE] 今までのスポットライト機能はスポットライトレガシーに変更しました

  • 今までの spotlight_sendrecv は spotlight_legacy_sendrecv に変更しました

  • 今までの spotlight_sendonly は spotlight_legacy_sendonly に変更しました

  • 今までの spotlight_recvonly は spotlight_legacy_recvonly に変更しました

• [CHANGE] ログとシグナリング通知の項目を別タブに変更しました

• [ADD] 新しいスポットライト機能のデモを追加しました

  • spotlight_sendrecv を追加しました

  • spotlight_sendonly を追加しました

  • spotlight_recvonly を追加しました

  • sora.conf にて spotlight_legacy = false にしたときのみ利用できます

    • デフォルトは true です

• [ADD] マイクのミュート機能を追加しました

• [ADD] ビデオのミュート機能を追加しました

• [ADD] フェイク機能を追加しました

  • Chrome / Edge / Firefox / Safari で利用できます

• [ADD] autoGainContraol の設定を追加しました

• [ADD] noiseSuppression の設定を追加しました

• [ADD] echoCancellation の設定を追加しました

• [ADD] echoCancellationType の設定を追加しました

  • browser と system が指定できます

• [ADD] オーディオボリュームメータを追加しました

• [ADD] コピーURL 機能を追加しました

  • 現在の設定を URL パラメータに反映した URL をクリップボードに保存します

• [ADD] マルチサイマルキャストでストリーム個別の画質変更ボタンを追加しました

• [ADD] クライアント側の情報を JSON 形式でダウンロードできるボタンを追加しました

• [ADD] デバッグ機能を有効にすることでログ、通知、統計を確認できるようになりました

新しいスポットライト機能

実験的機能

今までのスポットライト機能の課題を解決した、 新しいスポットライト機能を実験的機能として追加しました。

• [ADD] sora.conf に spotlight_legacy を追加しました

  • 新しいスポットライト機能を使う場合は sora.conf にて spotlight_legacy = false にする必要があります

• [ADD] type: connect 時に multistream: true / simulcast: true / spotlight: true を指定すると新しいスポットライト機能が利用できます

• [ADD] サイマルキャストを利用し 2 つの画質を配信するようにしました

  • 1/1 解像度の 30 FPS

  • 1/4 解像度の 1 FPS

• [ADD] 直近で発話したクライアントのストリームは 1/1 解像度 30 FPS で、音声ありを受信します

• [ADD] 直近で発話していないクライアントのストリームは 1/4 解像度 1 FPS で、音声なしを受信します

• [ADD] 直近で発話したクライアントのストリームは最大 8 まで受信可能にしました

• [ADD] 指定したストリームにフォーカスを当て続ける FocusSpotlightFixed API 追加しました

• [ADD] 指定したストリームにフォーカスを当てる FocusSpotlight API を追加しました

• [ADD] 指定したストリームをフォーカスから外す UnfocusSpotlight API を追加しました

• [ADD] 指定したチャネルのスポットライト数を変更する ChangeSpotlightNumber API を追加しました

• [ADD] 指定したストリームの画質を変更要求する RequestSpotlightQuality API を追加しました

  • 現時点では low / middle しか要求できません

• [ADD] 指定したストリームの画質をリセットする ResetSpotlightQuality API を追加しました

• [ADD] フォーカスが当たった場合 type: spotlight.focused が発火します

  • 固定されたかどうかが fixed の項目で true/false が入ります

  • signaling_notify 経由で参加者全員に通知されます

  • ignore_spotlight_changed_webhook を false にしていた場合は Webhook が通知されます

• [ADD] フォーカスが外れた場合 type: spotlight.unfocused が発火します

  • signaling_notify 経由で参加者全員に通知されます

  • ignore_spotlight_changed_webhook を false にしていた場合は Webhook が通知されます

• [ADD] sora.conf に default_spotlight_number を追加しました

古いスポットライト機能

実験的機能

今までのスポットライト機能を spotlight_legacy に変更しました。

• [CHANGE] ignore_spotlight_changed_webhook を ignore_spotlight_legacy_changed_webhook に変更しました

• [CHANGE] spotlight_auto_downgrade_bit_rate を spotlight_legacy_auto_downgrade_bit_rate に変更しました

• [CHANGE] spotlight_auto_sharing_video_bit_rate を spotlight_legacy_auto_sharing_video_bit_rate に変更しました

• [ADD] sora.conf に spotlight_legacy を追加しました

  • デフォルトは true です

H.264 プロファイルレベルの指定機能

実験的機能

H.264 利用時にプロファイル ID が今まは固定でしたが、自由に設定できるようにしました。

• [ADD] sora.conf に default_h264_profile_level_id を追加可能にしました

統計レポート API

実験的機能

• [ADD] GetStatsReport API に total_connection_created の項目を追加しました

• [ADD] GetStatsReport API に total_connection_updated の項目を追加しました

• [ADD] GetStatsReport API に total_connection_destroyed の項目を追加しました

• [FIX] GetStatsReport API の total_turn_udp_connections の値が反映されない問題を修正しました

• [FIX] GetStatsReport API の total_turn_tcp_connections の値が反映されない問題を修正しました

2020.1.1

リリース:

2020-08-18

対応 Chrome:

M84

対応 Firefox:

79

対応 Safari:

13.1.1

対応 Edge:

84

互換なしの変更情報

特にありません。

変更履歴

• [CHANGE] DTLS 証明書を 1 日 1 回から 1 時間に 1 回更新するようにしました

• [FIX] DTLS に利用する証明書を接続単位で保持するように修正しました

• [FIX] サポート用のログ connection.log の書き込みを非同期に修正しました

  • ログの書き込みが 5 秒以上かかった場合、 connection.log が書き込まれない問題を解決します

• [FIX] DTLS 証明書の再発行後のタイミングにマルチストリームの再ハンドシェイクが発生した場合、そのチャネルの接続がすべて切断してしまう問題を修正しました

  • 再発行した証明書の fingerprint をクライアントに送ってしまい、クライアント側が DTLS Alert close_notify を送ってきてしまうため切断されてしまう問題を解決します

2020.1

リリース:

2020-06-24

対応 Chrome:

M83

対応 Firefox:

77

対応 Safari:

13.1.1

対応 Edge:

83

重要なお知らせ

• Ubuntu 20.04 版を提供開始しました

• Ubuntu 16.04 版は 2021 年 4 月でパッケージ、サポートの提供を終了します

• bin/sora start から bin/sora daemon に今後切り替わります

• ロールの upstream / downstream は 2021 年 6 月リリース予定の Sora で利用ができなくなります

  • 今回追加された新しいロール sendrecv / sendonly / recvonly へ置き換えをお願いします

  • 最新の SDK を利用いただければ特に問題はでません

互換なしの変更情報

• バージョン表記を変更しました

• 設定ファイルの形式を変更しました

• コネクション ID のエンコード方式を Hex から Crockford's Base32 に変更しました

• PCMU のサポートを廃止しました

• デモ機能のファイル名を変更しました

• サイマルキャストで利用する際のロールを sendrecv / sendonly / recvonly のみ利用可能にしました

ハイライト

• Ubuntu 20.04 に対応しました

• 録画機能を改善しました

• 録画機能を RTCP Sender Report によるリップシンクに対応しました

• 録画の処理を非同期にしました

• ロールに sendrecv / sendonly / recvonly を追加しました

• 切断時に、接続ごとのクライアントとサーバーの統計情報を connection.log に出力するようにしました

• 実験的機能として、クライアント側の統計情報を API 経由で確認できるようにしました

• 実験的機能として、Sora からの映像配信を停止/再開する API を追加しました

• 実験的機能として、サイマルキャストの画質をストリーム別に指定できる API を追加しました

• 実験的機能として、AV1 や H.265 に対応しました

変更履歴

• [CHANGE] PCMU のサポートを廃止しました

• [CHANGE] 配信側への SDP での SSRC 指定を行わないように変更しました

  • Chrome の仕様に合わせました

• [CHANGE] UUIDv4 の値を Hex から Base32 に変更しました

  • Crockford's Base32 を利用しています

• [ADD] ロールに sendrecv / sendonly / recvonly を追加しました

  • 今後はこちらのロールをご利用ください

  • sendrecv は送受信

  • sendonly は送信のみ

  • recvonly は受信のみ

• [ADD] RTP 拡張 Generic Frame Descriptor v00 に対応しました

• [ADD] 音声の RTP に対して RTCP-SR/RTCP-RR を対応しました

• [ADD] RTCP-RR の送信間隔を audio と video で独立させました

• [ADD] DTLS アラートのログを sora.log で出力するようにしました

  • DTLS アラート close notify のログは出力されません

• [FIX] 音声のみの場合は PLI を送信しないようにしました

設定ファイル

• [ADD] 設定ファイルに signaling_loopback_address_only を追加しました

  • この設定を有効にすることでシグナリングに接続できるのが 127.0.0.1 からのみになります

• [CHANGE] 設定ファイルを etc/sora.conf に変更しました

• [CHANGE] 設定ファイルの必須設定をなくしました

  • license_file は etc/license.json がデフォルト値になりました

  • signaling_port は 5000 がデフォルト値になりました

  • api_port は 3000 がデフォルト値になりました

ウェブフック

• [UPDATE] イベントウェブフックのワーカー選択のキーを connection_id から channel_id に変更しました

• [ADD] 認証ウェブフックに simulcast フラグを追加しました

ログ

• [ADD] サポート向けに接続の統計情報を出力する connection.log を追加しました

  • リモート統計情報とローカル統計情報を出力します

• [CHANGE] sora.log の時刻が UTC で出力されるようになりました

• [CHANGE] warning.log / error.log を統一し sora.log に変更しました

TURN

• [ADD] TURN-TCP のみを利用するように指定できる turn_tcp_only の設定を追加しました

• [ADD] TURN-TLS のみを利用するように指定できる turn_tls_only の設定を追加しました

• [ADD] turn_tcp_only と turn_tls_only を有効にした場合は接続ごとに sora.log にログを出力するようにしました

• [CHANGE] TURN-TCP のデフォルト値を true に変更しました

• [CHANGE] type: offer 時の iceTrasnports: relay を削除しました

  • chrome が iceTransportPolicy へ対応したためです

RTP 転送

• [ADD] RTP 転送 API 実行時に api.log を出力するようにしました

• [FIX] StopForwardingRtp API で connection_id が見つからない場合のエラーを修正しました

録画機能

• [UPDATE] RTCP-SR を利用したリップシンク機能を追加しました

• [ADD] 録画完了時の統計機能項目を追加しました

  • video_reset_no_video_timeout

  • video_reset_pli

  • video_reset_other

  • extract_queue_trimmed

  • final_extract_limit

  • total_video_chunk_postponed_partial

  • total_video_chunk_postponed_queued

  • total_video_chunk_postponed_undefined

  • total_video_force_forward

  • total_audio_sender_report

  • total_video_sender_report

  • total_audio_lip_sync_mode_recv_time

  • total_audio_lip_sync_mode_rtcp_sr

  • total_video_lip_sync_mode_recv_time

  • total_video_lip_sync_mode_rtcp_sr

• [CHANGE] 録画一時ファイルの作成を非同期にしました

• [CHANGE] 録画ファイルが空の場合のログを削除するようにしました

• [FIX] スポットライト機能利用時に録画開始が利用できないよう修正しました

デモ機能

• [UPDATE] デモ機能で利用している sora-js-sdk のバージョンを 2020.1 に上げました

• [ADD] デモ機能のページすべてに <meta name="robots" content="noindex"> を追加しました

• [ADD] デモ機能に AV1 と H.265 を追加しました

  • クライアントが非対応の場合は動作しません

• [ADD] multi_simulcast_sendonly.html を追加しました

• [CHANGE] pub.html を sendonly.html に変更しました

• [CHANGE] sub.html を recvonly.html に変更しました

• [CHANGE] multi_pubsub.html を multi_sendrecv.html に変更しました

• [CHANGE] multi_pub.html を multi_sendonly.html に変更しました

• [CHANGE] multi_sub.html を multi_recvonly.html に変更しました

• [CHANGE] spotlight_pubsub.html を spotlight_sendrecv.html に変更しました

• [CHANGE] spotlight_sub.html を supotlight_recvonly.html に変更しました

• [CHANGE] simulcast_pub.html を simulcast_sendonly.html に変更しました

• [CHANGE] simulcast_sub.html を simulcast_recvonly.html に変更しました

• [CHANGE] multi_simulcast_pubsub.html を multi_simulcast_sendrecv.html に変更しました

• [CHANGE] multi_simulcast_sub.html を multi_simulcast_recvonly.html に変更しました

統計機能

• [ADD] GetStatsReport に sora_client の項目を追加しました

• [ADD] 統計 API に TURN 失敗の値を追加しました

  • total_received_turn_unknown_stun

  • total_received_turn_invalid_stun

  • total_received_unknown_channel_number

  • total_received_expired_channel_number

実験的機能

実験的機能を利用する場合はかならずサポートまでご連絡ください。

H.265 に対応しました

実験的機能

• [ADD] H.265 を利用可能にする設定 h265 を sora.conf に追加しました

  • デフォルトは false です

• [ADD] type: connect 時の video: {video_codec: "H265"} を指定可能にしました

• [ADD] H.265 のキーフレーム判定に対応しました

AV1 に対応しました

実験的機能

• [ADD] AV1 を利用可能にする設定 av1 を sora.conf に追加しました

  • デフォルトは false です

• [ADD] type: connect 時の video: {video_codec: "AV1"} を指定可能にしました

• [ADD] AV1 のキーフレーム判定に対応しました

• [ADD] AV1 の解像度取得に対応対応しました

サマルキャストで受信しているストリーム単位で画質を変更する仕組みを追加しました

実験的機能

この機能はサイマルキャストでのみ利用できます。

• [ADD] ChangeSimulcastQuality API で特定のストリームの画質の変更を可能にしました

  • stream_id にストリームを配信している接続の connection_id を指定します

指定したストリームの映像を停止/再開する API を追加しました

実験的機能

この機能はマルチストリームでのみ利用できます。

• [ADD] signaling_notify_rtp_stream を sora.conf に追加しました

  • true の場合は Rtp Stream Pause/Resume API 実行時に pause/resume 通知が飛びます

  • 受信を停止/再開した接続、された接続の両方に飛びます

• [ADD] PauseRtpStream API 追加しました

  • 指定した接続のストリームを停止します

  • connection_id にストリームの受信を再開する connection_id を指定します

  • stream_id にストリームの受信を再開したいストリームを配信している接続の connection_id を指定します

• [ADD] ResumeRtpStream API 追加しました

  • 指定した接続のストリームを再開します

  • connection_id にストリームの受信を再開する connection_id を指定します

  • stream_id にストリームの受信を再開したいストリームを配信している接続の connection_id を指定します

• [ADD] ListPauseRtpStreams API 追加しました

  • 指定したチャネルの停止しているストリーム一覧を返します

リモート統計情報を取得する API を追加しました

実験的機能

この機能はクライアント側でのみ取得できる統計情報をサーバー経由で取得可能にする仕組みです。

• [ADD] sora.conf に remote_stats: true を追加

  • type: ping 時に stats: true を有効にします

• [ADD] 認証成功時の払い出しに remote_stats: boolean を追加しました

• [ADD] GetAllRemoteStats API を追加しました

  • すべての接続のリモート統計情報を取得します

• [ADD] GetChannelRemoteStats API を追加しました

  • 指定したチャネル ID すべての接続のリモート統計情報を取得します

• [ADD] GetConnectionRemoteStats API を追加しました

  • 指定した接続のリモート統計情報を取得します

19.10.9

リリース:

2020-04-20

対応 Chrome:

M81

対応 Firefox:

75

対応 Safari:

13.1

対応 Edge:

81

互換なしの変更情報

特にありません

変更履歴

• [FIX] 配信が非常に不安定な場合、録画の処理でメモリを多量に消費してしまう問題

19.10.8

リリース:

2020-02-07

対応 Chrome:

M80

対応 Firefox:

72

対応 Safari:

13

対応 Edge:

79

互換なしの変更情報

特にありません

変更履歴

• [FIX] Firefox と特定のネットワークで正常につながらない問題を修正しました

  • Firefox 側の問題への対応です

• [FIX] Chrome M80 で H.264 の仕組みが変わったことにより録画が正常に動作しない問題を修正しました

  • Chrome 側の挙動変更への対応です

• [FIX] スポットライトで長時間インアクティブだった場合、再開時にスポットライト枠に表示されない問題を修正しました

• [FIX] マルチストリーム利用時に視聴側から送られてきた キーフレーム要求を正常に処理できていない問題を修正しました

• [FIX] 録画機能利用時に録画ファイルの中で約 22 分に一度音声が最大 20 秒空白になる問題を修正しました

19.10.4

リリース:

2020-01-28

対応 Chrome:

M79

対応 Firefox:

72

対応 Safari:

13

対応 Edge:

79

互換なしの変更情報

特にありません

変更履歴

• [FIX] SDP の RTP 拡張から mid を削除しました

  • ブラウザ側のバグに対応したものです

• [FIX] イベントウェブフックのタイムスタンプの取得タイミングを修正しました

• [FIX] 接続失敗イベントウェブフックでクラッシュしていた問題を修正しました

• [FIX] マルチストリームで sendonly を利用した際の SDP 関連の処理を修正しました

19.10.3

リリース:

2019-12-11

対応 Chrome:

M79

対応 Firefox:

71

対応 Safari:

13

対応 Edge Beta:

79

互換なしの変更情報

特にありません

ハイライト

• HTTP API への接続をループバックのみに限定する api_loopback_address_only を sys.config の設定に追加しました

変更履歴

• [ADD] HTTP API への接続をループバックのみに限定する api_loopback_address_only を sys.config の設定に追加しました

  • この設定を有効にすることで HTTP API を叩けるのが 127.0.0.1 からのみになります

• [ADD] 録画失敗時のウェブフックに以下に以下の項目を追加しました

  • audio

  • video

  • start_time

  • stop_time

  • file_path

    • ファイル自体は生成されません

  • filename

    • ファイル自体は生成されません

• [ADD] シグナリングログに type: disconnect を追加しました

  • クライアント側から type: disconnect が送られてきた場合に出力します

• [ADD] シグナリングログに type: close ログを追加しました

  • close ログはクライアント側から切断された場合に出力します

• [ADD] シグナリングログに type: closed ログを追加しました

  • closed ログはサーバー側から切断された場合に出力します

• [ADD] シグナリングログに type: error-closed ログを追加しました

  • error-closed ログはクライアントが想定外の切断をした場合に出力します

• [ADD] 実験的機能として認証成功時の戻り値で simulcast と simulcast_quality を指定可能にしました

  • この機能を利用される場合は必ず事前にサポートまでご連絡ください

• [ADD] 実験的機能として ListConnections と ListAllConnections API に multistream / simulcast / spotlight のフラグを追加しました

  • この機能を利用される場合は必ず事前にサポートまでご連絡ください

• [ADD] 実験的機能としてマルチストリームに配信のみで参加できる仕組みを追加しました

  • この機能を利用される場合は必ず事前にサポートまでご連絡ください

• [ADD] 実験的機能としてイベントウェブフック通知の HTTP ヘッダーに X-SORA-EVENT-WEBHOOK-TYPE を追加しました

  • この機能を利用される場合は必ず事前にサポートまでご連絡ください

• [ADD] 実験的機能として Opus パラメータに ptime を追加しました

  • この機能を利用される場合は必ず事前にサポートまでご連絡ください

• [FIX] Android のサイマルキャスト配信時に正常に動作しない問題を修正しました

• [FIX] デモ機能のマルチストリームサイマルキャスト視聴のみで初期の画質指定が抜けていたのを追加しました

• [FIX] 録画時に接続の切断と録画終了 API がほぼ同時に実行されるとアーカイブが recording.report に入らない問題を修正しました

• [FIX] 認証成功時に払い出す ipv4_address と ipv6_address が正常に動作しない問題を修正しました

19.10.1

リリース:

2019-11-06

対応 Chrome:

M78

対応 Firefox:

70

対応 Safari:

13

対応 Edge Beta:

79

互換なしの変更情報

特にありません

ハイライト

• TURN の UDP または TCP のどちらを利用しているかがシグナリング通知、およびイベントウェブフックで取得できるようになりました

• マルチストリームの「視聴のみ」で、配信者が存在しない場合でも接続できるようになりました

• マルチストリームの「視聴のみ」で、配信者が存在しなくなった場合でも接続を維持するようになりました

変更履歴

• [ADD] シグナリング通知の connection.created / connection.updated / connection.destroyed に turn_transport_type を追加しました

  • "udp" または "tcp" の文字列が入ります

• [ADD] イベントウェブフックの connection.created / connection.updated / connection.destroyed に turn_transport_type を追加しました

  • "udp" または "tcp" の文字列が入ります

• [CHANGE] マルチストリームの視聴のみで今までは配信がある必要がありましたが、配信がない場合でも Sora に接続することが可能になりました

• [CHANGE] マルチストリームの視聴のみで配信者が 0 になっても切断しないようにしました

• [FIX] サイマルキャスト対応と非対応のマルチストリームが同じチャネルに参加した際にクラッシュする問題を修正しました

• [FIX] サイマルキャストの視聴時に配信側が通常の配信に切り替わった場合、クラッシュする問題を修正しました

• [FIX] ネットワークの不安定レベル通知機能が音声のみの配信の場合、常に unstable_level 3 を配信するようになっていた問題を修正しました

19.10.0

リリース:

2019-10-16

対応 Chrome:

M77

対応 Firefox:

69

対応 Safari:

13

対応 Edge Dev:

79

互換なしの変更情報

• PlanB への対応を廃止しました

• サイマルキャスト (Google 独自) への対応を廃止しました

ハイライト

• CentOS 8.0 に対応しました

• 実験的機能として マルチストリームでサイマルキャスト機能が利用可能になりました

変更履歴

• [UPDATE] ChangeSimulcastQuality API をマルチストリームに対応しました

• [UPDATE] ChangeUpstreamVideoBitRate API をマルチストリームに対応しました

• [UPDATE] サイマルキャストを利用した配信者はビットレートシェアリング機能は無効にしました

• [UPDATE] 録画機能で Opus ステレオ音声の録音に対応しました

• [ADD] CentOS 8.0 に対応しました

• [ADD] GetStatsConnection API に視聴側の再送キャッシュヒット率を追加しました

  • total_generic_nack_cache_hit

    • 再送要求に正しく応答した回数

  • total_generic_nack_cache_miss

    • 再送要求に応答できなかった回数

• [ADD] GetStatsConnection API に配信側が不安定になった際、 キーフレーム要求(PLI)を送った回数を追加しました

  • total_pli_trigger

    • 再送要求に限界がきてキーフレーム要求を送った回数

• [ADD] GetStatsConnection API に RTP パケロスシミュレーターの統計情報を追加しました

  • total_dropped_received_rtp

    • 受信した RTP パケットをパケロスシミュレータで落とした回数

  • total_dropped_sent_rtp

    • 送信した RTP パケットをパケロスシミュレータで落とした回数

• [ADD] GetStatsConnection API に network_status の unstable_level の値を追加しました

  • unstable_level

  • 0-3 の値が入ります

• [ADD] 新規接続時に送る PLI の頻度を抑える仕組みを追加しました

• [ADD] 実験的機能としてマルチストリーム機能でサイマルキャスト機能が利用可能になりました

  • 現時点でサイマルキャスト機能は Chrome でのみ利用できます

  • 詳細は マルチストリームでサイマルキャスト をご確認ください

• [ADD] 設定 default_simulcast_quality を追加しました

  • sys.config にて指定できます

  • サイマルキャストで simulcast: true を選んだときの視聴する画質のデフォルトを指定します

  • デフォルトは "low" です

  • "low" 、 "middle" 、 "high" を指定できます

• [ADD] デモ機能に multi_simulcast_pubsub.html と multi_simulcast_sub.html を追加しました

• [ADD] シグナリング Offer 時に Sora のバージョンを追加しました

  • "version": "19.10.0" の形式です

  • hide_origin_username が有効な場合はバージョン情報は送りません

• [ADD] 実験的機能として Opus パラメータをシグナリングで指定できるようになりました

  • これらの機能を利用される場合は必ず事前にサポートまでご連絡ください

  • {"audio": {"opus_params": {"stereo": false, "useinbandfec": false}}}

  • clock_rate

  • channels

  • maxplaybackrate

  • stereo

  • sprop_stereo

  • minptime

  • useinbandfec

  • usedtx

• [ADD] 実験的機能として Opus パラメータのデフォルト値を sys.config で指定できるようになりました

  • これらの機能を利用される場合は必ず事前にサポートまでご連絡ください

  • opus_param_clock_rate

  • opus_param_channels

  • opus_param_maxplaybackrate

  • opus_param_stereo

  • opus_param_sprop_stereo

  • opus_param_minptime

  • opus_param_useinbandfec

  • opus_param_usedtx

• [ADD] イベントウェブフックのワーカー数を指定可能にしました

  • デフォルトは 5 です

  • sys.config にて {event_webhook_worker_number, 5} のように指定します

  • 5-5000 の範囲で指定できます

• [ADD] ウェブフックのレスポンスタイムアウトを指定可能にしました

  • デフォルトは 5 秒です

  • sys.config にて {webhook_response_timeout, 5} のように指定します

  • 1-600 秒の範囲で指定できます

• [ADD] 録画ファイル生成時のウェブフックに client_id と connection_id をトップレベルに含むようにしました

• [ADD] 録画ファイル生成時のウェブフック archive.available に統計情報を追加しました

  • total_filled_audio_packet

    • 穴埋めした音声パケットのトータル

  • total_discard_audio_packet

    • 破棄した音声パケットのトータル

  • min_audio_level

    • RTP 拡張 audio level の最小値（音声出力の最大値)のトータル

  • total_discarded_audio_packet

    • 調整のために捨てた音声パケットのトータル

  • total_stored_video_keyframe_head

    • 映像キーフレームの先頭パケットのトータル

  • total_stored_audio_packet

    • 録画に利用した音声パケットのトータル

  • total_stored_video_packet

    • 録画に利用した映像パケットのトータル

  • total_discarded_unknown_packet

    • 録画に利用せず破棄した不明パケットのトータル

  • total_pli_trigger

    • 再送要求に限界がきてキーフレーム要求 (PLI) を送ったトータル

• [CHANGE] すべてのブラウザの最新版が Unified Plan になったため SDP の Plan B タイプへの対応を削除しました

  • plan_b: boolean を削除しました

• [CHANGE] サイマルキャスト機能から Google 独自の SDP 書き換え方式への対応を削除しました

  • simulcast_rid: boolean を削除しました

  • simulcast: true は常に rid ベースのサイマルキャストが利用されます

  • rid ベースのサイマルキャストは Chrome と Edge Dev でのみ利用できます

• [FIX] 録画ファイルのメタデータに音声のビットレートが含まれていなかったのを修正しました

• [FIX] サイマルキャスト機能利用時に視聴側を先に繋ぐと音声が配信されない問題を修正しました

• [FIX] サイマルキャストのエンコーディング指定を role: upstream 時のみに修正しました

• [FIX] 録画時に recording.report に録画ファイルが含まれない問題を修正しました

• [FIX] Generic Nack の再送が rtp_packet_loss_simulator_outgoing の対象になっていなかったのを修正しました

• [FIX] マルチストリームの Answer が遅延した場合でも正常に映像が表示されるよう修正しました

19.04.9

リリース:

2019-07-22

対応 Chrome:

M75

対応 Firefox:

68

対応 Safari:

12.1.1

対応 Edge Dev:

77

互換なしの変更情報

特にありません

変更履歴

• [CHANGE] Opus の DTX 機能を無効化しました

  • Chrome と Firefox の WebM 再生機能が Opus の DTX 機能に非対応であり、音ずれが発生するため

19.04.8

リリース:

2019-07-17

対応 Chrome:

M75

対応 Firefox:

68

対応 Safari:

12.1.1

対応 Edge Dev:

77

互換なしの変更情報

特にありません

変更履歴

• [FIX] 前回、Firefox で正常に動作するようバージョンアップを行ったことにより、別のネットワーク環境で正常に繋がらなくなった問題を修正しました

19.04.7

リリース:

2019-07-12

対応 Chrome:

M75

対応 Firefox:

67

対応 Safari:

12.1.1

対応 Edge Dev:

77

互換なしの変更情報

特にありません

変更履歴

• [UPDATE] デモ機能が利用している sora-js-sdk を 1.14.0 にアップデートしました

• [UPDATE] 接続に失敗した際ログの config に以下を追加しました

  • turn_fqdn

  • rtx

  • ulpfec

• [UPDATE] 統計情報出力に以下の値を追加しました

  • dtls

  • received_turn_binding_request

  • received_turn_binding_error

  • received_turn_binding_success

  • sent_turn_binding_request

  • sent_turn_binding_error

  • sent_turn_binding_success

• [CHANGE] デモ機能のスポットライトの最大数を 8 に変更しました

• [CHANGE] スポットライトの最大数を 8 に変更しました

• [ADD] api_log の対象に以下の API を追加しました

  • DowngradeSpotlightBitRate

  • ResetSpotlightBitRate

  • StartRecording

  • StopRecording

• [FIX] シグナリングで type: candidate の sdp に空文字が含まれても問題ないような処理を追加しました

• [FIX] Firefox が特定のネットワークで接続できない問題を修正しました

• [FIX] デモ機能の rid ベースのサイマルキャスト配信機能で音声が配信されていなかった問題を修正しました

• [FIX] 録画機能利用時に StopRecording API を実行中にクライアントの切断が発生した場合起きる問題を修正しました

• [FIX] mDNS の値が UUID 以外の値が入ってくると正常に処理されない問題を修正しました

• [FIX] Chrome で映像で指定しているビットレートが音声と共有されてしまう問題を修正しました

19.04.4

リリース:

2019-06-10

対応 Chrome:

M75

対応 Firefox:

67

対応 Safari:

12.1.1

対応 Edge Dev:

76

互換なしの変更情報

サポート向けに出力している sdp.log を signaling.log に名前を変更しました。ログローテーションの変更をお願いします。

変更履歴

• [ADD] 実験的機能として rid ベースのサイマルキャストに対応しました

• [ADD] 統計 API に RTX / RED / RED-RTX の統計情報を追加しました

• [CHANGE] デモ機能の simulcast_pub.html はデフォルトで rid ベースのサイマルキャストを利用するように変更しました

• [UPDATE] ULPFEC で確保している RTP キャッシュにサイズ上限を追加しました

• [UPDATE] ULPFEC で正常処理ができていない部分を修正しました

• [CHANGE] サポート向けの sdp.log を signaling.log に変更しました

  • サポート時の対応を迅速にするために、出力するログ内容を変更しました

  • そのため sdp ではなく signaling が主となったためファイル名を変更しました

• [CHANGE] ULPFEC をデフォルトで無効にしました

  • パケロスが多い場合、 ULPFEC を無効にしている場合より不安定になるためデフォルトで無効にしました

• [FIX] 認証成功時の払い出しで audio と video が false の場合にエラーになるように修正しました

• [FIX] 認証成功時の払い出しで audio や video が false の場合に上書きすると正常に動作しない問題を修正しました

• [FIX] マルチストリーム機能で同時接続でまれに相手が見えなくなる問題を修正しました

• [FIX] TURN-UDP で複数の Allocate-Request が送られてきた場合に正常動作しない問題を修正しました

19.04.1

リリース:

2019-05-23

対応 Chrome:

M74

対応 Firefox:

67

対応 Safari:

12.1.1

対応 Edge (Chromium ベース):

76

廃止情報

特にありません

互換なしの変更情報

今回の変更で不明な点はサポートまでお問い合わせください

metadata_list の戻り値を list に変更し、 signaling_notify_client_id や signaling_notify_connection_id の設定が反映されるようにしました。

今までは {"connection_id0": "metadata0", "connection_id1": "metadata1"} という形式でした、 ただし signaling_notify_connection_id を false にしていたとしても connection_id が共有されてしまう問題がありました。 また client_id が含まれていないという問題もあり、抜本的な変更を行いました。

詳細は シグナリング通知 の signaling_notify_metadata をご確認ください

変更履歴

• [CHANGE] metadata_list の戻り値を変更しました

  • 詳細は シグナリング通知 の signaling_notify_metadata をご確認ください

• [FIX] 録画で音声が途中で途切れる可能性がある問題を修正しました

• [FIX] スポットライト機能利用時の統計情報が一部取得できていなかった問題を修正しました

• [FIX] ULPFEC が特定環境で正常に動作しない問題を修正しました

• [FIX] 回線が不安定な場合に Firefox で SRTP/AES-GCM を利用した際、正常に動作しない問題を修正しました

• [FIX] 特定環境で確保したにもかかわらず利用されていない TURN-TCP が放置されてタイムアウトが発生してしまう問題を修正しました

19.04.0

リリース:

2019-04-17

対応 Chrome:

M73

対応 Firefox:

66

対応 Safari:

12.1

対応 Edge (Chromium ベース):

74

廃止情報

特にありません

互換なしの変更情報

プレビュー版の機能に対して後方互換性を維持しない変更を行っています

• スポットライト機能 CastAlwaysSpotlight API

  • client_id を connection_id に変更しました

• スポットライト機能 CastSpotlight API

  • client_id を connection_id に変更しました

• スポットライト機能 CancelSpotlight API

  • client_id を connection_id に変更しました

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

  • type: connect 時に spotlight を指定した場合、 audio を false にするとエラーになるように変更しました

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

  • channel_id を削除しました

• サイマルキャスト機能 ChangeSimulcastQuality API

  • client_id を connection_id に変更しました

ハイライト

• Safari に正式対応しました

• スポットライト機能が Safari に対応しました

• 1 接続ごとにユニークなコネクション ID を払い出すようになりました

• クライアント ID を指定可能にする設定を追加しました

• クライアント ID の重複が可能になりました

• クライアントにネットワーク不安定レベルを通知する機能を追加しました

• イベントウェブフックがエラーになった場合、 event_webhook_error.log にもログが記録されるようになりました

• イベントウェブフックの connection.updated の通知を無効にできる設定を追加しました

• 映像の前方誤り訂正機能がマルチストリームでも利用可能になりました

• デモ機能に getDisplayMedia の機能を追加しました

• スポットライト機能に自動で映像のビットレートをシェアする機能を追加しました

• チャネルの接続を、配信者や視聴者単位で切断できる API を追加しました

• Edge の対応を終了し Edge (Chromium ベース) への対応を開始しました

変更履歴

• [UPDATE] Safari 12.1 にて Safari に正式に対応しました

  • 実験的機能としての Unified Plan はまだ動作が未確定なため、プレビュー版としての対応です

• [UPDATE] デモ機能が利用している sora-js-sdk を 1.12.0 にアップデートしました

  • Safari 12.1 に対応しました

  • Safari 12.0 にも対応しています

• [UPDATE] デモ機能で Safari のデフォルト映像コーデックを H.264 から VP8 に変更しました

  • Safari 12.1 で VP8 に対応しました

  • Safari 12.0 で VP8 は利用できません

• [UPDATE] デモ機能 multi_pubsub と spotlight_pubsub のデフォルトビットレートを 500kbs から 1000kbps に変更しました

  • 自動で映像のビットレートをシェアする機能を追加したためです

• [UPDATE] スポットライト機能が Safari に対応しました

  • Safari が VP8 に対応し、動作が安定したため対応しました

• [ADD] 1 接続ごとにユニークな コネクション ID を払い出すようになりました

• [ADD] クライアント ID を重複させることが可能になりました

  • これはプレビュー版の機能です

• [ADD] シグナリング接続時、または認証成功の戻り値にクライアント ID を指定可能にする設定を追加しました

  • これはプレビュー版の機能です

  • デフォルトでは無効に設定されています

  • sys.config の allow_client_id_assignment を true に指定することで有効にできます

  • 設定を有効にした場合で、 client_id を指定しない場合、認証ウェブフックでで通知される client_id は null になります

  • クライアント ID が指定可能な場合、コネクション ID を判定に使うことが必須になり、後方互換性が失われますので注意してください

• [ADD] デモ機能の pub.html, multi_pubsub.html が getDisplayMedia に対応しました

  • 最新版の Chrome と Firefox で有効です

  • Safari では利用できません

• [ADD] ブラウザへの追従のため RTP 拡張対応の extmap_allow_mixed を追加しました

  • 有効にした場合 Safari 12.0 が繋がらなくなります

  • デフォルトでは無効になっています

    • sys.config の extmap_allow_mixed を true に指定することで有効にできます

• [ADD] イベントウェブフック通知がエラーになった場合は event_webhook_error.log にもログが記載されるようになりました

  • event_webhook.log にはすべてのログが記録されます

  • event_webhook_error.log にはエラーになったイベントウェブフックのログが記録されます

• [ADD] イベントウェブフックの connection.updated の通知を無効にできる設定を追加しました

  • デフォルトでは通知されます

  • sys.config の ignore_connection_updated_webhook を true に指定することで通知を無効にできます

• [ADD] シグナリング通知でネットワークの状態を通知する機能を追加しました

  • デフォルトで有効になっています

    • sys.config の signaling_notify_network を false に指定することで無効にできます

  • ネットワークの不安定レベル (unstable_level) を通知します

    • 不安定レベルは 0 から 3 まで 4 段階あり、 0 が一番安定、 3 が一番不安定です

    • 映像を配信している人のみに有効です

  • 送信間隔は 10 秒で固定しています

    • Sora 19.10 にて送信間隔を変更できるようにする予定です

• [ADD] マルチストリーム配信側の ULPFEC (前方誤り訂正) に対応しました

• [ADD] 片方向配信やマルチストリームにて、映像ビットレートを動的に変更できる ChangeUpstreamVideoBitRate API を追加しました

  • 詳細は ChangeUpstreamVideoBitRate API をご確認ください

  • この API を利用することで、再接続することなく映像ビットレートを変更できるようになります

  • マルチストリームでは、分割されたビットレート以上にビットレートを上げることができません

    • 例えば 1000kbps で指定し、 2 名がそのチャネルに参加している場合には、指定可能な最大ビットレートは 500kbps となります

• [ADD] 指定したチャネルすべての配信者を切断する DisconnectChannelUpstream API を追加しました

  • 詳細は 指定したチャネルすべての配信者の接続を切断する をご確認ください

  • この API は片方向配信、マルチストリーム、スポットライトすべてで利用できます

• [ADD] 指定したチャネルすべての視聴者を切断する DisconnectChannelDownstream API を追加しました

  • 詳細は 指定したチャネルすべての視聴者の接続を切断する をご確認ください

  • この API は片方向配信、マルチストリーム、スポットライトすべてで利用できます

• [ADD] マルチストリームのビットレートシェアリング機能を指定可能にしました

  • 詳細は マルチストリームにおける映像ビットレート自動シェアリング機能 をご確認ください

  • この機能は配信者の人数で映像のビットレートを分割する機能です

  • デフォルトで有効になっています

    • sys.config の multistream_auto_sharing_video_bit_rate を false に指定することで無効にできます

• [ADD] スポットライト機能に、自動で映像ビットレートをシェアする機能を追加しました

  • 詳細は スポットライトにおける映像ビットレート自動シェアリング機能 をご確認ください

  • この機能は配信者の人数またはスポットライトの数で映像のビットレートを分割する機能です

  • デフォルトで有効になっています

    • sys.config の spotlight_auto_sharing_video_bit_rate を false に指定することで無効にできます

• [ADD] ログ出力に api.log を追加しました

  • 一部の API 操作に関するログを出力します

  • ログローテーションされませんので、ログローテーションをお願いします

• [ADD] クライアント切断 DisconnectClient API を追加しました

  • Disconnect API に ClientId を渡した場合と同じ動作をします

• [ADD] 認証の戻り値で client_id がバリデーションでエラーになった際、 warning ログが出力されるようになりました

• [ADD] デモ機能のデバッグ情報に PUSH API からの通知を表示するようにしました

• [ADD] Edge (Chromium ベース) への対応を開始しました

  • 詳細は Microsoft Edge の WebRTC について をご確認ください

• [CHANGE] ULPFEC (前方誤り訂正) をデフォルトで有効にしました

  • 片方向配信とマルチストリームでの配信が対象です

  • sys.config の ulpfec を false に指定することで無効にできます

• [CHANGE] スポットライト機能のシグナリング接続時に audio を false にするとエラーになるよう変更しました

• [CHANGE] スポットライト機能向け CastAlwaysSpotlight API の client_id を connection_id に変更しました

• [CHANGE] スポットライト機能向け CastSpotlight API の client_id を connection_id に変更しました

• [CHANGE] スポットライト機能向け CancelSpotlight API の client_id を connection_id に変更しました

• [CHANGE] サイマルキャスト機能向け ChangeSimulcastQuality API の client_id を connection_id に変更しました

• [CHANGE] スポットライト機能のシグナリング通知 spotlight.changed から channel_id を削除しました

• [CHANGE] スポットライト機能のデモでクライアント ID を表示していた部分をコネクション ID を表示するように変更しました

• [CHANGE] GetStats API は allow_client_id_assignment を true にした場合は利用できなくなりました

  • クライアント ID が重複可能になるため、既存の API の仕組みでは対応できないためです

  • 代わりに GetStatsClient または GetStatsConnection API を利用してください

• [CHANGE] Disocnnect API は allow_client_id_assignment を true にした場合は利用できなくなりました

  • クライアント ID が重複可能になるため、既存の API の仕組みでは対応できないためです

  • 代わりに DisconnectClient または DisconnectConnection API を利用してください

• [FIX] スポットライト機能でスポットライトがあたっている参加者が接続を切断した場合、シグナリング通知で client_id=null を送るように修正しました

• [FIX] TURN-TCP 利用時に、特定環境で TCP の接続が残ったままになる問題を修正しました

18.10.5

リリース:

2019-01-21

対応 Chrome:

M71

対応 Firefox:

64

対応 Edge:

44

対応 Safari:

12.0

廃止情報

特にありません

互換なしの変更情報

GetStats API の項目を一部変更しました。

• total_received_bytes を total_received_byte_size に変更しました

• total_sent_bytes を total_sent_byte_size に変更しました

• total_received_packets を total_received に変更しました

• total_sent_packets を total_sent に変更しました

ハイライト

• ジッターやパケロスが多い、不安定な回線でも録画が行えるように改善しました

アップグレード時の注意

互換なしの変更情報を確認してください。

変更履歴

• [UPDATE] デモ機能が利用している sora-js-sdk を 1.10.2 にアップデートしました

• [CHANGE] GetStats API の項目を一部変更しました。

  • total_received_bytes を total_received_byte_size に変更しました

  • total_sent_bytes を total_sent_byte_size に変更しました

  • total_received_packets を total_received に変更しました

  • total_sent_packets を total_sent に変更しました

• [FIX] 録画機能で、ジッターやパケロスが多い場合でも正常に録画できるよう改善しました

• [FIX] turn_tls_fqdn や turn_fqdn が認証時に動作しない問題を修正しました

• [FIX] 録画機能の PCMU がいくつかの条件で正常に動作しない問題を修正しました

• [FIX] マルチストリームのキャッシュテーブルが初期化されていなかった問題を修正しました

18.10.2

リリース:

2018-12-04

対応 Chrome:

M70

対応 Firefox:

63

対応 Edge:

44

対応 Safari:

12.1 (Safari TP 70)

廃止情報

• generic_nack_cache_size が廃止されました

  • generic_nack_cache_size_msec を利用指定ください

互換なしの変更情報

• generic_nack_cache_size が廃止されました

  • generic_nack_cache_size_msec を利用指定ください

ハイライト

• 高ビットレートでの再送制御の効率化を行いました

• サポート対象の映像ビットレートを 5Mbps から 15Mbps に変更しました

アップグレード時の注意

• generic_nack_cache_size を廃止し、 generic_nack_cache_size_msec を追加しました

  • generic_nack_cache_size の設定を削除してください

変更履歴

• [UPDATE] デモ機能の simulcast_pub/simulcast_sub の H.264 を有効にしました

  • Safari TP 70 にて動作を確認しています

• [UPDATE] デモ機能の up.html の映像ビットレートに 50Mbps を追加しました

  • サポート対象は 15Mbps が最大になります

• [UPDATE] サポート対象の映像ビットレートを 5Mbps から 15Mbps に引き上げました

• [UPDATE] RTP パケロスシミュレータをマルチストリームとスポットライトに対応しました

• [UPDATE] H.264 のキーフレーム判定をより正確に判定するようにしました

• [UPDATE] 視聴者側の Generic NACK キャッシュサイズをビットレートによって変更する仕組みに変更しました

  • これにより高ビットレートでも再送制御が機能するようになりました

• [ADD] generic_nack_cache_size_msec を追加しました

  • デフォルト値以外の値を設定を検討している場合はサポートまでお問い合わせください

• [CHANGE] generic_nack_cache_size を廃止しました

• [FIX] サイマルキャスト利用時でない場合でも視聴側がサイマルキャストを利用していた問題を修正しました

• [FIX] サイマルキャスト配信側が不安定から復旧した際に視聴側が期待している画質が配信されない問題を修正しました

• [FIX] 配信側の Generic NACK 送信の無駄を減らしました

• [FIX] Plan B で映像のみの配信者しかいない場合、音声が有効の視聴者が接続できない問題を修正しました

• [FIX] 回線が不安定な際、正常に録画ができず録画に失敗する問題を修正しました

18.10.0

リリース:

2018-10-30

対応 Chrome:

M70

対応 Firefox:

63

対応 Edge:

42

対応 Safari:

12.1 (Safari TP 68)

廃止情報

特にありません

互換なしの変更情報

特にありません

ハイライト

• 1 つのチャネルで、同じ映像を複数のビットレートで送信できるサイマルキャスト機能を、プレビュー版として追加しました

• スポットライト機能利用時のクライアントやサーバーの負荷を改善する API や機能を追加しました

• キーフレームの欠損時に再送なしで回復できる前方誤り訂正機能(FEC)の一つである ULPFEC に対応しました

アップグレード時の注意

特にありません

変更履歴

• [UPDATE] デモ機能の Sora JS SDK を 1.10.0 に上げる

• [UPDATE] スポットライト関連のデモ機能のコーデックを VP9 に変更しました

• [ADD] スポットライトで利用するビットレートを一時的に下げる DowngradeSpotlightChannelBitRate API を追加しました

  • スポットライトを利用している指定したチャネルのビットレートを一時的に半分に下げます

• [ADD] スポットライトで利用するビットレートをリセットする ResetSpotlightChannelBitRate API を追加しました

  • DowngradeSpotlightChannelBitRate API で下げたビットレートをもとに戻します

• [ADD] DisconnectChannel API と Disconnect API にオプションとして reason を指定できるようにしました

  • reason をした場合イベントウェブフックの connection.destroyed にて指定した reason が追加されるようになります

  • 切断理由を明確にしたい場合ご利用ください

• [ADD] スポットライトで配信されていないクライアントのビットレートを自動的に下げる設定を追加しました

  • デフォルトでは無効になっています

  • 有効にする場合は sys.config で {spotlight_auto_downgrade_bit_rate, false} を true にしてください

• [ADD] イベントウェブフックの connection.destroyed に reason を追加しました

  • DisconnectChannel API と Disconnect API の reason に指定された文字が入ります

  • 指定しない、またはそれ以外で切断された場合は null が入ります

• [ADD] プレビュー機能としてサイマルキャストを追加しました

  • Chrome または Safari TP の最新版が利用できます

  • VP8 でのみ利用できます

  • 片方向配信でのみ利用できます

  • マルチストリームやスポットライトでは利用できません

  • 配信側はシグナリングの type: connect にて {"simulcast": true} を指定してください

  • 視聴側はシグナリングの type: connect にて simulcast: true | {quality: low | middle | high} を指定してください

    • quality を指定しない場合は low がデフォルトで選択されます

• [ADD] サイマルキャスト向けの ChangeSimulcastQuality API を追加しました

  • ChannelId と ClientId と Quality を指定することで指定した Quality の映像を受信するようになります

• [ADD] デモ機能にサイマルキャスト機能を追加しました

  • simulcast_pub.html

  • simulcast_sub.html

• [ADD] ULPFEC を片方向配信にてデフォルトで適用するようにした

  • sys.config にて ulpfec が有効になっています

  • ULPFEC は キーフレーム(全画面フレーム)が欠損した場合に再送無しで欠損を回復する仕組みです

18.04.12

リリース:

2018-09-21

対応 Chrome:

M69

対応 Firefox:

62

対応 Edge:

42

対応 Safari:

12.0

廃止情報

特にありません

互換なしの変更情報

特にありません

アップグレード時の注意

sys.config の cert_file と cert_key_file が不要になりました。

もし設定ファイルを使いまわしている方は設定を削除する必要はありませんが、できるだけ新しい設定ファイルを利用してください。

cert_file と cert_key_file が不要になったことで sys.config の最後の項目が connection_created_wait_timeout に変更されています。

18.04.11 までの設定ファイルの末尾:

 %% SDP の offer 時に払い出される origin の username を隠蔽するかどうかを指定してください
 %% true の場合は origin の username が "-" として払い出されます
 %% {hide_origin_username, true},

 %% WebRTC の接続が確立するまでの許容時間を秒で指定してください
 %% {connection_created_wait_timeout, 30}

 %% WebRTC に使用する証明書を指定してください ECDSA 形式のみ対応しています
 {cert_file, "etc/certs/ecdsa_server_cert.pem"},

 %% WebRTC に使用する証明書の秘密鍵を指定してください ECDSA 形式のみ対応しています
 {cert_key_file, "etc/certs/ecdsa_server_key.pem"}
]

18.04.12 の設定ファイルの末尾:

 %% SDP の offer 時に払い出される origin の username を隠蔽するかどうかを指定してください
 %% true の場合は origin の username が "-" として払い出されます
 %% {hide_origin_username, true},

 %% WebRTC の接続が確立するまでの許容時間を秒で指定してください
 {connection_created_wait_timeout, 30}
]

変更履歴

注意

今回 etc ディレクトリが含まれなくなっております。次回からは etc ディレクトリを含んでおくようにしますので、今回はお手数をおかけしますが作成をお願いいたします

• [CHANGE] WebRTC の DTLS に利用している証明書を Sora が動的に生成する仕組みを追加しました

• [CHANGE] sys.config の cert_file と cert_key_file を削除しました

  • 証明書は Sora が動的に生成する仕組みになりました

• [UPDATE] Safari 12.0 に対応しました

  • ただし High Sierra の場合 Safari で Firefox への配信が正常に行われません、これは Safari 側の問題です

  • 対応は Safari のアップデートを待ちになります

• [UPDATE] 映像コーデックに指定可能なビットレートの最大値を 5Mbps から 30Mbps に変更しました

  • ネットワーク条件がかなり限定されることもあり、現時点では 5Mbps より大きい値はサポート外とさせていただきます

  • 今後対応できるように検証、改善を進めてまいります

• [UPDATE] デモ機能で利用している Sora JavaScript SDK を 1.9.2 に上げました

• [UPDATE] シグナリングの type: "ping" の Sora 側での判断を変更しました

  • 今までは type: "ping" を送って 30 秒反応がない場合は切断するという方式でしたが、もう少し許容できるように、 5 秒ごとに ping を送り、 60 秒間隔で pong が一度でも送られて来ているかどうかという判断をする仕組みに変更しました

• [FIX] 録画時に、 0 バイトのペイロードの RTP RTX を受け取ると録画ファイルが途中から再生できなる問題を修正しました

• [FIX] PCMU が片方向と双方向で正常に動作しなくなっていた問題を修正しました

• [FIX] 録画時に映像コーデックに H.264 を利用した場合に正常に録画されない問題を修正しました

18.04.11

リリース:

2018-08-08

対応 Chrome:

M68

対応 Firefox:

61

対応 Edge:

42

対応 Safari:

11.1

廃止情報

特にありません

互換なしの変更情報

特にありません

アップグレード時の注意

Sora がデフォルトで利用している証明書を更新しました。

証明書を自前で発行して設定していない方は 必ず 更新をお願いします。

変更履歴

• [UPDATE] 片方向配信の映像に特定の RTP 拡張が入っている場合 Chrome Canary M70 で動作しないため、RTP 拡張を最低限にまで落としました

• [UPDATE] Sora がデフォルトで利用している証明書を更新しました

  • 証明書の設定を自前で行っていない方は 必ず 更新をお願いします

• [ADD] プレビュー機能として RTP パケロスシミュレータを追加しました

  • この機能を使った場合クライアント接続ごとに warning ログが発生しますので注意してください

  • sys.config にて {rtp_packet_loss_simulator_incoming, 2} を設定すると Sora が受信する 2% のパケットをドロップします

  • sys.config にて {rtp_packet_loss_simulator_outgoing, 1} を設定すると 1% Sora が送信するパケットをドロップします

• [FIX] シグナリングで音声と映像を有効にして録画する際、クライアント側で音声のみを送信した場合に録画が正常に行われない問題を修正しました

• [FIX] 録画のときに、映像、音声どちらかが大きく遅れた場合に録画がずれる問題を修正しました

18.04.10

リリース:

2018-07-24

対応 Chrome:

M68

対応 Firefox:

61

対応 Edge:

42

対応 Safari:

11.1

廃止情報

特にありません

互換なしの変更情報

特にありません

アップグレード時の注意

特にありません

変更履歴

• [UPDATE] ICE 周りで Chrome M68 で変更箇所に対応しました

• [UPDATE] TURN-TCP のパケット処理をより厳密にするようにしました

• [UPDATE] スポットライト固定 API (CastAlwaysSpotlight) で spotlight_id をオプションに変更しました

  • spotlight_id を指定しない場合は、空いているスポットライトが利用されます

• [FIX] クライアントが複数 IP アドレスを保持している場合にたまに繋がらなくなる問題を修正しました

• [FIX] ローカルネットワーク上でまれに TURN-UDP が有効にもかかわらず TURN-TCP が選択されてしまう問題を修正しました

• [FIX] スポットライトのシグナリング通知で connection.created の前に spotligh.changed が通知される問題を修正しました

18.04.9

リリース:

2018-06-29

対応 Chrome:

M67

対応 Firefox:

61

対応 Edge:

42

対応 Safari:

11.1

廃止情報

特にありません

互換なしの変更情報

特にありません

アップグレード時の注意

{turn_fqdn, "sora.example.com"} を廃止することを取りやめました

変更履歴

• [UPDATE] スポットライト機能のデモのデフォルトで利用するコーデックを VP9 から VP8 に変更しました

  • Chrome M67-M69 では VP9 で映像を切り替えた際にうまく映像が切り替わらないバグが存在するためです

• [UPDATE] スポットライト機能のデモで映像が切り替わった際にクライアント ID を切り替えるようにしました

  • この機能は signaling_notify が有効になっている必要があります

• [UPDATE] {turn_fqdn, "sora.example.com"} を廃止することを取りやめました

  • iOS の審査通過条件である NAT64/DNS64 下で動作するには TURN の URL が FQDN である必要があるためです

  • 以前新しく追加した turn_tls_fqdn は turn_fqdn の設定を上書きします、そのため TURN-TCP/UDP と TURN-TLS で別の FQDN を指定することが可能になりました

• [FIX] スポットライト機能で配信されなくなるクライアントが出てしまう問題を修正しました

18.04.6

リリース:

2018-06-18

対応 Chrome:

M67

対応 Firefox:

60

対応 Edge:

42

対応 Safari:

11.1

廃止情報

特にありません

互換なしの変更情報

特にありません

アップグレード時の注意

特にありません

変更履歴

• [FIX] Firefox 利用時にマルチストリームで複数クライアントが接続した際、クライアント側のイベントが正常に発火しない問題を修正しました

• [FIX] デモ機能で Firefox を利用した際に、正常に disconnect が利用できない問題を修正しました

• [FIX] デモ機能で Chrome を利用した際に、 onremovetrack と onremovestream 両方が発火する場合の動作を修正しました

18.04.5

リリース:

2018-06-14

対応 Chrome:

M67

対応 Firefox:

60

対応 Edge:

42

対応 Safari:

11.1

廃止情報

特にありません

互換なしの変更情報

特にありません

ハイライト

• マルチストリームで同一のチャネル ID にほぼ同時に複数クライアントが接続した際、正常につながらない問題を修正しました

アップグレード時の注意

特にありません

変更履歴

• [UPDATE] デモ機能が利用している sora-js-sdk を 1.9.1 にアップデートしました

• [FIX] マルチストリームで同一のチャネル ID にほぼ同時に複数クライアントが接続した際、正常につながらない問題を修正しました

• [FIX] ウェブフック機能の HTTP Proxy が正常に動作しない問題を修正しました

18.04.3

リリース:

2018-05-30

対応 Chrome:

M67

対応 Firefox:

60

対応 Edge:

42

対応 Safari:

11.1

廃止情報

• スナップショット機能を廃止しました

• Ubuntu 14.04 版の新規提供を終了しました

互換なしの変更情報

• スナップショット機能を廃止しました

ハイライト

• Ubuntu 18.04 版のパッケージ提供を開始しました

• ウェブフックが HTTP Proxy に対応しました

• 視聴のみの参加者がいる配信で、スポットライト機能が使えるようになりました

• スポットライト機能向けのシグナリング通知を追加しました

アップグレード時の注意

特にありません

変更履歴

• [ADD] Ubuntu 18.04 版のパッケージ提供を開始しました

• [ADD] ウェブフックの HTTP Proxy 対応を追加しました

  • sys.config に以下の設定を追加しました

  • webhook_proxy_url

    • {webhook_proxy_url, "http://proxy.example.com:8080/"}

  • webhook_proxy_auth_user

  • webhook_proxy_auth_password

• [ADD] GetStatsReport API に total_turn_udp_connections と total_turn_tcp_connections を追加しました

• [ADD] デモ機能で Chrome Canary M68 以降でマルチストリームを利用した際は Unified Plan を利用するように修正しました

• [ADD] 視聴のみの参加者がいる配信で、スポットライト機能が使えるようになりました

• [ADD] スポットライト機能向けのシグナリング通知を追加しました

• [ADD] デモ機能にスポットライト機能視聴のみの spotlight_sub.html を追加しました

• [ADD] turn_tcp_listen_port を追加しました

  • TURN-TCP の待受ポートを指定します

  • turn_tcp_port は URL 払い出しでの利用になりました

• [ADD] turn_tls_fqdn を追加しました

  • turn_fqdn が TURN-TLS でしか利用しない変更をいれたため名前を変更しました

  • turn_fqdn は次のリリースで廃止します

• [UPDATE] デモ機能 spotlight_pubsub.html で音量バーを表示するようにしました

• [CHANGE] スナップショット機能を削除しました

• [CHANGE] turn_tcp_port は払い出し URL に利用されるポート番号の設定に変更しました

• [CHANGE] Ubuntu 14.04 版のパッケージ新規提供を終了しました

• [FIX] TURN-UDP/TCP の場合は FQDN は利用しないように修正しました

  • Safari 11.1 では FQDN の場合 TURN が正常に動作しないため

18.04.1

リリース:

2018-05-02

対応 Chrome:

M66

対応 Firefox:

59

対応 Edge:

42

対応 Safari:

11.1

廃止情報

• スナップショット機能を廃止予定のため、現在利用されているお客様がいらっしゃいましたらご連絡ください

  • スナップショット機能は VP8 でしか利用できないこと、さらには RTP 転送機能を利用すれば似たようなことが実現できることもあり、廃止する予定です

  • もし利用されているお客様がいない場合は次のリリースにて廃止します

互換なしの変更情報

特にありません

ハイライト

• シグナリング通知のフォーマットが仕様と異なっている問題を修正しました

アップグレード時の注意

特にありません

変更履歴

• [UPDATE] Edge 42 で動作確認を行いました

  • 現時点でもかなり不安定ですので Edge での利用はお勧めしません

  • TURN-TLS が設定されていると動作しません

  • TURN IPv6 が設定されていると動作しません

  • VP9 コーデックには非対応です

  • マルチストリームは利用できません

• [FIX] シグナリング通知時の connection.destroyed と connection.created のフォーマットが仕様と異なっている問題を修正しました

• [ADD] スポットライト機能で映像コーデックに VP8 や H.264 が利用可能になりました

18.04.0

リリース:

2018-04-27

対応 Chrome:

M66

対応 Firefox:

59

対応 Edge:

41

対応 Safari:

11.1

廃止情報

• スナップショット機能を廃止予定のため、現在利用されているお客様がいらっしゃいましたらご連絡ください

  • スナップショット機能は VP8 でしか利用できないこと、さらには RTP 転送機能を利用すれば似たようなことが実現できることもあり、廃止する予定です

  • もし利用されているお客様がいない場合は次のリリースにて廃止します

互換なしの変更情報

特にありません

ハイライト

• プレビュー版のスポットライト機能 (旧「音声検出による映像の動的切り替え機能」) に対して大幅なアップデートを行いました

• シグナリング通知に対して大幅なアップデートを行いました

• クライアントが Sora と WebRTC による接続ができなかった場合に、クライアント単位の詳細なログを出力する機能をプレビュー版として追加しました

アップグレード時の注意

特にありません

変更履歴

• [UPDATE] デモ機能が利用している sora-js-sdk を 1.8.2 にアップデートしました

• [FIX] Android Chrome でデモ機能を利用した際に相手の映像と音声が視聴できない問題を修正しました

• [CHANGE] デモ機能の Canvas 合成配信を削除しました

  • Sora の機能とは関係ないため、今後 GitHub にて公開予定です

• [CHANGE] 「音声検出による映像の動的切替機能」から「スポットライト機能」に名前を変更しました

• [CHANGE] スポットライト機能のデモを vad.html から spotlight_pubsub.html に変更しました

  • スポットライトの数を 2 で固定していたのを 1-5 の範囲で指定できるようにしました

• [CHANGE] スポットライト機能のフェイクデモを vad_fake.html から spotlight_fake.html に変更しました

  • スポットライトの数を 2 で固定していたのを 1-5 の範囲で指定できるようにしました

• [CHANGE] スポットライト機能で、参加者や視聴者が表示されるストリームにばらつきが出ないようにしました

• [ADD] スポットライト機能で、アクティブな話者 (配信されている話者) の数を認証ウェブフックの戻り値で指定できるようになりました

• [ADD] スポットライト機能で、アクティブな話者 (配信されている話者) が切り替わった場合に "spotlight.changed" でウェブフックを飛ばす機能を追加しました

  • 詳細は spotlight.changed をご確認ください

  • デフォルトでは無効になっています、有効にする場合は ignore_spotlight_changed_webhook を false にしてください

• [ADD] スポットライト機能で、指定した参加者を強制的に画面に表示する API を追加しました

  • 詳細は 指定した参加者を強制的に画面に表示する をご確認ください

• [ADD] スポットライト機能で、指定した参加者を常に画面に表示する API を追加しました

  • 詳細は 指定した参加者を常に画面に表示する をご確認ください

• [ADD] スポットライト機能で、指定した参加者を常に画面に表示するのを解除する API を追加しました

  • 詳細は 指定した参加者を常に画面に表示する状態を解除する をご確認ください

• [ADD] 正常に接続できなかった場合にエラーを log/connection-created-timeout-error ディレクトリ以下に出力する機能をプレビュー版として追加しました

  • ログのファイル名形式は <unix_time_sec>_<client_id>.json になります

  • 内部のデータは弊社にて解析するためのログを出力しておりますので加工せずにそのままお送りください

• [CHANGE] シグナリング通知機能をデフォルトで有効にしました

  • 詳細は シグナリング通知機能 をご確認ください。

• [ADD] シグナリング通知の際、クライアント ID を含めるようにしました

  • sys.config の {signaling_notify_client_id, false} でクライアント ID を含めなくなります

• [ADD] シグナリング通知の際、音声と映像が有効かどうかを含めるようにしました

  • sys.config の {signaling_notify_media, false} で音声と映像が有効かどうかを含めなくなります

• [ADD] シグナリング通知の際、メタデータを含めるようにしました

  • シグナリング通知に使われるメタデータは type: connect 時の signaling_notify_metadata で指定できます

  • シグナリング通知に使われるメタデータは認証ウェブフックの戻り値で signaling_notify_metadata で上書きできます

  • sys.config の {signaling_notify_metadata, false} でメタデータを含めなくなります

18.02.2

リリース:

2018-03-23

対応 Chrome:

M65

対応 Firefox:

59

対応 Edge:

41

対応 Safari:

11.0

廃止情報

こちら現在検討中ですので急いで対応して頂く必要はありません

• ListConnections API を廃止予定です

  • 今後は ListChannelClients API を利用して下さい

互換なしの変更情報

18.04 で互換なしの変更を予定しておりましたが、取り下げます

ハイライト

• Safari 11.0.3 でマルチストリーム利用時に音声のみでの配信が正常に動作しない問題を修正しました

アップグレード時の注意

特にありません

変更履歴

• [FIX] デモ機能でエラーが起きた時うまく表示ができなかった問題を修正しました

• [FIX] Safari 11.0.3 でマルチストリーム利用時に音声のみでの配信が正常に動作しない問題を修正しました

18.02.1

リリース:

2018-03-16

対応 Chrome:

M65

対応 Firefox:

59

対応 Edge:

41

対応 Safari:

11.0

廃止情報

こちら現在検討中ですので急いで対応して頂く必要はありません

• ListConnections API を廃止予定です

  • 今後は ListChannelClients API を利用して下さい

互換なしの変更情報

18.04 で互換なしの変更を予定しておりましたが、取り下げます

ハイライト

• Firefox 59 で onremovetrack が発火しなくなっている問題を修正しました

アップグレード時の注意

特にありません

変更履歴

• [UPDATE] デモ機能が利用している sora-js-sdk を 1.8.1 にアップデートしました

• [ADD] 音声検出による映像の動的表示機能を Firefox に対応しました

• [CHANGE] エラーに出力されるログ UNKNOWN-TYPE を INVALID-SIGNALING-TYPE に変更しました

• [FIX] BUNDLE にすべての m= line の mid を列挙するよう修正しました

  • この修正で Firefox 59 で onremovetrack が発火しない問題が解決します

18.02.0

リリース:

2018-02-28

対応 Chrome:

M64

対応 Firefox:

58

対応 Edge:

41

対応 Safari:

11.0

ハイライト

• 音声検出による映像の動的切替機能を追加しました

アップグレード時の注意

特にありません

変更履歴

• [ADD] プレビュー機能として音声検出による映像の動的表示機能を追加しました

  • 詳細は 音声検出による映像の動的表示機能 をご確認ください

• [ADD] デモ機能に音声検出による映像の動的表示機能を利用した vad.html と vad_fake.html を追加しました

• [ADD] デモ機能に音声入力/音声出力/映像入力それぞれのデバイスを切り替える機能を追加しました

• [ADD] RTCP-XR に対応しました

• [FIX] マルチストリーム利用時に終了処理時にビットレート判定の部分で配信者数が 0 になる問題を修正しました

• [FIX] マルチストリーム利用時に音声のみを指定しているにも関わらず映像が配信されてしまう問題を修正しました

• [FIX] マルチストリーム利用時にクライアントが createAnswer に失敗した際に、接続が残った状態になるのを修正しました

• [FIX] TURN-TCP を利用した際にシグナリングが接続確立する前に切断したときの問題を修正しました

18.01.1

リリース:

2018-01-24

対応 Chrome:

M63

対応 Firefox:

58

対応 Edge:

41

対応 Safari:

11

廃止情報

こちら現在検討中ですので急いで対応して頂く必要はありません

• ListConnections API を廃止予定です

  • 今後は ListChannelClients API を利用して下さい

互換なしの変更情報

18.04 にて次の互換なしの変更を予定しておりましたが、取り下げます

• type: connect 時にクライアントから SDP を送るのを必須に変更します

• role: upstream を role: pub に変更します

• role: downstream を role: sub に変更します

• マルチストリーム利用時の role: upstream を role: pubsub に変更します

• マルチストリーム利用時の role: downstream を role: sub に変更します

• マルチストリーム利用時の plan_b を廃止します

  • 今後は type: connect 時に送る SDP にてサーバー側で自動で判断します

ハイライト

• Firefox 58 で配信を行おうとすると Firefox がクラッシュする問題を修正しました

アップグレード時の注意

特にありません

変更履歴

• [FIX] Firefox 58 で配信を行おうとすると Firefox がクラッシュする問題を修正しました

18.01.0

リリース:

2018-01-15

対応 Chrome:

M63

対応 Firefox:

57

対応 Edge:

41

対応 Safari:

11

廃止情報

こちら現在検討中ですので急いで対応して頂く必要はありません

• ListConnections API を廃止予定です

  • 今後は ListChannelClients API を利用して下さい

互換なしの変更情報

18.04 にて次の互換なしの変更を予定しておりましたが、取り下げます

• type: connect 時にクライアントから SDP を送るのを必須に変更します

• role: upstream を role: pub に変更します

• role: downstream を role: sub に変更します

• マルチストリーム利用時の role: upstream を role: pubsub に変更します

• マルチストリーム利用時の role: downstream を role: sub に変更します

• マルチストリーム利用時の plan_b を廃止します

  • 今後は type: connect 時に送る SDP にてサーバー側で自動で判断します

ハイライト

• ライセンスファイル更新時にサーバーを落とさなくても良くなりました

アップグレード時の注意

特にありません

変更履歴

• [UPDATE] デモ機能でクライアント ID を表示するようにしました

• [UPDATE] デモ機能が利用している sora-js-sdk を 1.7.7 にアップデートしました

• [ADD] RTP 拡張 video-content-type に対応しました

• [ADD] RTP 拡張 video-timing に対応しました

• [ADD] プレビュー機能としてライセンス更新 API を追加しました

  • 詳細は UpdateLicense API をご確認ください

• [ADD] プレビュー機能としてライセンス情報取得 API を追加しました

  • 詳細は GetLicense API をご確認ください

• [ADD] プレビュー機能として RTP 転送 API 利用時の PLI をクライアントに送る間隔を sys.config で指定できるようにしました

  • 配信側への キーフレーム要求の間隔を指定できるようになりました

  • 指定する場合は sys.config にて default_forwarding_pli_interval を指定して下さい

• [FIX] TURN-TCP 利用時にうまく終了処理ができていなかったのを修正しました

• [FIX] 録画 API 利用時に終了処理が正常に動作していなかったのを修正しました

• [FIX] 録画終了時の負荷が高くなった際に録画が正常に終了しない問題を修正しました

• [FIX] デモ機能で multi_sub が Firefox や Safari で正常に動作していなかったのを修正しました

• [FIX] マルチストリームの downstream 利用時に配信側が存在しなくなった場合の動作がおかしくなる問題を修正しました

• [FIX] マルチストリームの downstream 利用時に配信側が存在しない場合に新規で接続した場合のエラーを修正しました

17.10.5

リリース:

2017-12-20

対応 Chrome:

M63

対応 Firefox:

57

対応 Edge:

41

対応 Safari:

11

廃止情報

• 18.01 で ListConnections API を廃止します

  • 今後は ListChannelClients API を利用して下さい

互換なしの変更情報

18.04 にて次の互換なしの変更を予定しておりましたが、取り下げます

• type: connect 時にクライアントから SDP を送るのを必須に変更します

• role: upstream を role: pub に変更します

• role: downstream を role: sub に変更します

• マルチストリーム利用時の role: upstream を role: pubsub に変更します

• マルチストリーム利用時の role: downstream を role: sub に変更します

• マルチストリーム利用時の plan_b を廃止します

  • 今後は type: connect 時に送る SDP にてサーバー側で自動で判断します

ハイライト

特にありません

アップグレード時の注意

特にありません

変更履歴

• [UPDATE] デモ機能の Sora JavaScript SDK を 1.7.4 にアップデートしました

• [ADD] シグナリングの type: connect と type: update の sdp を sdp.log に出力するようにしました

• [ADD] シグナリングでクライアントが投げてきた JSON が間違っていた場合に INVALID-JSON エラー返すようにしました

• [CHANGE] シグナリング時にチャネル ID で undefined を利用可能にしました

  • それに伴い NOT-USE-CHANNEL-ID エラーを削除しました

• [FIX] 録画機能の WebM 作成時に録画するデータが届く前に録画終了した場合の問題を修正しました

• [FIX] 録画機能の録画予約終了と録画開始が重なった場合の問題を修正しました

• [FIX] 録画機能で録画が終了してるタイミングで録画停止 API が呼び出された場合の問題を修正しました

• [FIX] TURN 機能の TURN-UDP と TURN-TCP で ChannelNumber が期限が切れるまで保持するように修正しました

• [FIX] スナップショット機能と録画機能を同時に利用した際の問題を修正しました

• [FIX] RTP 転送機能と録画機能を同時に利用した際の問題を修正しました

17.10.2

リリース:

2017-11-15

対応 Chrome:

M62

対応 Firefox:

57

対応 Edge:

41

対応 Safari:

11

廃止情報

• 18.01 で ListConnections API を廃止します

  • 今後は ListChannelClients API を利用して下さい

互換なしの変更情報

18.04 にて次の互換なしの変更を予定しておりましたが、取り下げます

• type: connect 時にクライアントから SDP を送るのを必須に変更します

• role: upstream を role: pub に変更します

• role: downstream を role: sub に変更します

• マルチストリーム利用時の role: upstream を role: pubsub に変更します

• マルチストリーム利用時の role: downstream を role: sub に変更します

• マルチストリーム利用時の plan_b を廃止します

  • 今後は type: connect 時に送る SDP にてサーバー側で自動で判断します

ハイライト

• デモ機能にデバッグモードを追加しました

• プレビュー版の機能をいくつか追加しました

アップグレード時の注意

特にありません

変更履歴

• [ADD] デモ機能にデバッグモードを追加しました

• [ADD] GetStatsAllConnections API を追加

  • GetStats API で個別に取得していた統計情報を取得する機能です

• [ADD] 片方向配信時に視聴側の帯域情報を配信側に伝えることで配信側のビットレートを自動で変更する機能を追加しました

  • これはプレビュー版の機能です

  • この機能を利用する場合は必ずサポートまでご連絡ください、ドキュメントには反映していません

  • sys.config に設定が必要です

    • {report_sub_remb, true}

• [ADD] StartForwardingRtp API 戻り値の SDP に SSRC を追加しました

  • これはプレビュー版の機能です

  • この機能を利用する場合は必ずサポートまでご連絡ください、ドキュメントには反映していません

• [ADD] StartForwardingRtp API 戻り値の SDP の t= の start_time に API 開始時間を追加しました

  • これはプレビュー版の機能です

  • この機能を利用する場合は必ずサポートまでご連絡ください、ドキュメントには反映していません

• [ADD] StartForwardingRtp API の引数にオプションとして rtcp_port を追加しました

  • これはプレビュー版の機能です

  • この機能を利用する場合は必ずサポートまでご連絡ください、ドキュメントには反映していません

  • 現在はすべての RTCP リストを送信しています

• [ADD] GetStatsReport API に erlang_vm と browser と error の統計情報を追加しました

  • これはプレビュー版の機能です

  • この機能を利用する場合は必ずサポートまでご連絡ください、ドキュメントには反映していません

  • sys.config に設定が必要です

    • {stats_report_erlang_vm, true}

      • ErlangVM の統計情報が取得できるようになります

    • {stats_report_browser, true}

      • シグナリング接続の成功と失敗がブラウザごとにカウントされるようになります

    • {stats_report_error, true}

      • シグナリングの失敗と SDP 生成の失敗がカウントされるようになります

• [FIX] TURN-TCP が採用されないタイミングでクラッシュしていた問題を修正しました

• [FIX] Edge で一部の SDP が処理できなかった問題を修正しました

• [FIX] デモ機能のビットレート指定が反映されていなかった問題を修正しました

• [FIX] RTP 拡張 abs-send-time の処理を修正しました

• [FIX] 認証ウェブフックの戻り値の処理を修正しました

17.10.0

リリース:

2017-10-25

対応 Chrome:

M62

対応 Firefox:

56

対応 Edge:

41

対応 Safari:

11

廃止情報

• 17.12 で ListConnections API を廃止します

  • 今後は ListChannelClients API を利用して下さい

互換なしの変更情報

18.04 にて次の互換なしの変更を予定しておりましたが、取り下げます

• type: connect 時にクライアントから SDP を送るのを必須に変更します

• role: upstream を role: pub に変更します

• role: downstream を role: sub に変更します

• マルチストリーム利用時の role: upstream を role: pubsub に変更します

• マルチストリーム利用時の role: downstream を role: sub に変更します

• マルチストリーム利用時の plan_b を廃止します

  • 今後は type: connect 時に送る SDP にてサーバー側で自動で判断します

ハイライト

• 映像の再送制御機能について最適化を行い、より安定した配信が可能になりました

• イベントウェブフック機能について並列化を行い、イベント通知がより安定して処理できるようになりました

• デモ機能を、 Sora JavaScript SDK を利用したものに置き換えました

アップグレード時の注意

特にありません

変更履歴

• [UPDATE] Chrome M62 での動作を確認しました

• [UPDATE] 映像の再送制御機能を最適化を行い、より安定した配信が可能になりました

  • Generic NACK の仕組みを 1 から書き換えました

• [UPDATE] イベントウェブフック機能を並列化を行い、イベント通知をより安定して処理できるようになりました

  • この対応を入れた後でも connection.created と connection.destroyed の順番は保証されます

• [ADD] サーバー起動時に sysctl -a と ulimint -n のログを取得する仕組みを追加しました

  • log 以下に sysctl.log と ulimit.log が生成されます

• [ADD] サーバーの状態を取得できる GetStatsReport API を追加しました

  • 以下の値が取得できます

  • 現在接続している数

  • 現在までの接続が成功した数

  • 現在までの接続が失敗した数

  • 現在までの合計接続時間 (秒)

  • 平均接続時間 (秒)

  • 平均セットアップ時間 (ミリ秒)

    • シグナリングを開始してから接続するまでにかかった時間の平均

• [CHANGE] デモ機能を一新しました

  • Sora JavaScript SDK を利用したデモとなっています

    • https://github.com/shiguredo/sora-js-sdk

  • ファイル名が一部変更になりました

  • QueryString を利用して指定が可能になりました

    • 詳細はデモ機能の QueryString をご確認下さい

  • up.html -> pub.html

  • down.html -> sub.html

  • multistream.html -> multi_pubsub.html

  • multistream_down.html -> multi_sub.html

• [CHANGE] プレビュー版だったストリーミング機能を削除しました

  • ストリーミング機能はまだ安定的に動作しないこともあり、一度削除しました

  • もしストリーミング機能が使いたい場合は StartForwardingRtp/StopForwardingRtp API と FFmpeg を利用してください

• [FIX] 片方向配信時の視聴側の RTCP が一部正常に処理できていない問題を修正しました

17.08.3

リリース:

2017-10-13

対応 Chrome:

M61

対応 Firefox:

56

対応 Edge:

40.15063

対応 Safari:

11

廃止情報

• 17.12 で ListConnections API を廃止します

  • 今後は ListChannelClients API を利用して下さい

変更履歴

• [FIX] マルチストリームの録画終了時に正常終了しない問題を修正しました

• [FIX] マルチストリームの録画終了時に PLI の定期送信が正常に終了しない問題を修正しました

• [FIX] マルチストリームで音声のみを配信している状態に、音声と映像で参加すると、VP9 しか受け付けない問題を修正しました

17.08.2

リリース:

2017-09-27

対応 Chrome:

M61

対応 Firefox:

55

対応 Edge:

40.15063

対応 Safari:

11

廃止情報

• 17.12 で ListConnections API を廃止します

  • 今後は ListChannelClients API を利用して下さい

ハイライト

• プレビュー機能として Safari 11 に対応しました

• プレビュー機能として Opus のビットレートを指定できるようになりました

• CentOS 7.4 に対応しました

アップグレード時の注意

• sys.config の application_specific_maximum を default_video_bit_rate に変更しました

変更履歴

• [UPDATE] Chrome M61 での動作を確認しました

• [UPDATE] プレビュー機能として Safari 11 に対応しました

• [UPDATE] デモ機能の multistream_down.html で音声をデフォルトで有効にしました

• [UPDATE] CentOS 7.4 に対応しました

• [ADD] プレビュー機能として音声コーデックに Opus 利用した際にビットレートが指定できるようになりました

  • Chrome と Safari でのみ有効になります、 Firefox や Edge では有効になりません

• [CHANGE] sys.config の application_specific_maximum を default_video_bit_rate に変更しました

• [FIX] デモ機能の multistream_down.html で音声が正常に動作していなかったのを修正しました

• [FIX] snapshot を利用した際に特定の条件で正常に動作しない問題を修正しました

• [FIX] マルチストリーム時に downstream に対して RTCP-BYE を送らないよう修正しました

• [FIX] DTLS が完了していないタイミングで SRTP や SRTCP が送られてきた場合うまく動作しない問題を修正しました

17.08.0

リリース:

2017-08-30

対応 Chrome:

M60

対応 Firefox:

55

対応 Edge:

40.15063

対応 Safari:

Technology Preview 38

廃止情報

• 17.12 で ListConnections API を廃止します

  • 今後は ListChannelClients API を利用して下さい

ハイライト

• 音声や映像の転送処理の高速化を行いました

• TURN-TCP 周りの動作を安定させました

• OpenSSL ライブラリのインストールが不要になりました

• StartForwardingRtp の戻り値に FFmpeg 連携用の SDP 追加しました

• StartForwardingRtp/StopForwardingRtp API がマルチストリームに対応しました

• チャネルごとのユーザー接続情報を取得できる ListChannelClients API を追加しました

アップグレード時の注意

• イベントフックで送られてくる event_metadata の項目を metadata から event_metadata に変更しました

• StartForwardingRtp API の戻り値が FFmpeg で利用可能な sdp のみになりました

変更履歴

• [UPDATE] TURN-TLS URL 払い出し機能が正式版になりました

• [UPDATE] GetStats API が正式版になりました

• [UPDATE] Chrome M60 での動作を確認しました

• [UPDATE] Firefox 55 での動作を確認しました

• [UPDATE] Safari TP 38 での動作を確認しました

• [ADD] シグナリングで type: disconnect 送った際の終了処理を追加しました

• [ADD] 録画 API 終了時に生成されるメタデータファイルにアーカイブそれぞれの metadata_file_path と metadta_filename を追加しました

• [ADD] イベントフック connection.created/updated/destroyed に audio/video の項目を追加しました

• [ADD] クライアント統計情報に transport_cc を追加しました

• [ADD] ListChannelClients API を追加しました

  • 指定したチャネル ID のクライアント情報を取得できます

• [ADD] デモ機能の multistream.html に cpuOveruseDetection を追加しました

• [ADD] マルチストリームの SDP に AS/TIAS 追加しました

• [ADD] 片方向配信の SDP に AS/TIAS 追加しました

• [ADD] RTP が転送機能をマルチストリームに対応しました

  • StartForwardingRtp/StopForwardingRtp 時に client_id を指定することで RTP 転送が可能になります

• [CHANGE] 3gpp:video-orientation を無効にしました

• [CHANGE] OpenSSL のインストールが不要になりました

• [CHANGE] イベントフックで connection.created/updated/destroyed に入ってくる event_metadata を metadata から event_metadta に変更しました

• [CHANGE] goog-remb オプションを sys.config から削除しました

• [CHANGE] transport-wide オプションを sys.config から削除しました

• [CHANGE] StartForwardingRtp API の戻り値が SDP を返すようにしました

  • FFmpeg との連携を簡単にするための SDP を生成するようにしました

• [CHANGE] StartForwardingRtp API を実行したタイミングで PLI を 20 秒で送るようにしました

• [FIX] デモ機能で音声のみの受信が Firefox で正常に動作しなかった問題を修正しました

• [FIX] クライアント統計情報に TURN-TCP が反映されるようにしました

• [FIX] TURN-TCP 利用時にうまくアドレスが取得できない場合、正常に動作しなかった問題を修正しました

• [FIX] TURN-TCP 利用時に不必要に出ていたログを削除しました

• [FIX] マルチストリーム利用時に RTCP-RR の値の一部が指定されていなかった問題を修正しました

• [FIX] マルチストリーム利用時にクライアント側のエンコードビットレートが不安定になる問題を修正しました

17.06.2

リリース:

2017-07-05

対応 Chrome:

M59

対応 Firefox:

54

対応 Edge:

40.15063

対応 Safari:

Technology Preview 34

変更履歴

• [UPDATE] 配信機能のパフォーマンス向上を行いました

  • より遅延が少なくなりました

• [UPDATE] マルチストリーム使用時の Generic NACK の動作を安定化させました

• [ADD] DTLS-SRTP の AES-GCM に対応しました

  • 現時点では Chrome で chrome://flags で有効にした場合のみ使用できます

• [CHANGE] デモ機能のデフォルトビデオコーデックを VP9 に変更しました

  • up.html

  • down.html

  • canvas.html

  • multistream.html

  • multistream_down.html

• [CHANGE] 配信と視聴のデモ機能が Edge と Safari Technology Preview 34 に対応しました

  • Safari が対応しているコーデックは H.264 のみであることに注意してください

  • Edge は VP9 のコーデックに対応していないため注意してください

• [CHANGE] マルチストリームのデモ機能が Safari Technology Preview 34 に対応しました

  • Safari が対応しているコーデックは H.264 のみであることに注意してください

• [FIX] 無駄に出力されていた TURN-TCP-CLOSED メッセージの表示を停止しました

• [FIX] MESSAGE-OVERFLOWED の通知のみに変更しました

• [FIX] TURN-TCP で意図しない問題が起きた場合のエラーメッセージを追加しました

17.06.0

リリース:

2017-06-09

対応 Chrome:

M59

対応 Firefox:

53

対応 Edge:

40.15063

対応 Safari:

Technology Preview 32

ハイライト

• 多くの機能がプレビュー版を卒業し、正式版になりました

• Safari Technology Preview 32 での動作を確認しました

• RTX 機能に対応しました

• クライアントの統計機能を取得する GetStats API を追加しました

アップグレード

特に注意する点はありません

変更履歴

• [UPDATE] Chrome M59 に対応しました

• [UPDATE] マルチストリーム機能が正式版になりました

• [UPDATE] IPv6 対応が正式版になりました

• [UPDATE] TURN IPv6 が正式版になりました

• [UPDATE] TURN-TCP が正式版になりました

• [UPDATE] hide_origin_username 機能が正式版になりました

• [UPDATE] RTX 機能が正式版になりました

• [UPDATE] label 機能が正式版になりました

• [FIX] 壊れた STUN パケットが送られてきたときは破棄するようにしました

• [FIX] マルチストリーム配信中に通常配信が接続できてしまう問題を修正しました

• [FIX] 通常視聴接続中にマルチストリームが繋げてしまう問題を修正しました

• [FIX] 録画 API が正常に動作しない問題を修正しました

• [FIX] RTX を Chrome と Edge の両環境で正常に動作するようになりました

  • 今回のリリースで RTX デフォルトで有効にしてあります

  • 17.08 にて RTX を正式リリース予定です

• [CHANGE] StartForwardingRtp API を音声と映像の出力を分割するようにしました

  • port がなくなり audio_port と video_port の引数が追加しました

• [CHANGE] プレビュー機能の UI 機能を廃止しました

• [CHANGE] プレビュー機能の Upgrade / Downgrade API を廃止しました

• [UPDATE] Generic NACK の仕組みを改善しました

• [ADD] Safari Technology Preview 32 に対応しました

  • この機能はレビュー版です、 Safari 11 が出るタイミングで正式対応する予定です

  • デモ機能に確認用の up_safari.html と down_safari.html を用意しました

• [ADD] プレビュー機能としてクライアントの統計情報を取得する GetStats API を追加しました

• [ADD] 3gpp:video-orientation 拡張に対応しました

  • Chrome のみで使用できます

• [ADD] goog-remb オプションを sys.config に追加しました

• [ADD] transport-wide オプションを sys.config に追加しました

後方互換性のない変更

特にありません

17.04.6

リリース:

2017-05-23

対応 Chrome:

M58

対応 Firefox:

53

変更履歴

• [FIX] マルチストリーム使用で音声のみが使用できなくなっている問題を修正しました

17.04.5

リリース:

2017-05-16

対応 Chrome:

M58

対応 Firefox:

53

変更履歴

• [FIX] マルチストリーム使用時に Generic NACK が正常に動作しない問題を修正しました

• [FIX] マルチストリーム使用時に録画が正常に行われない問題を修正しました

• [FIX] 異常な STUN パケットが送られてきた場合に無視するように修正しました

• [FIX] StopForwardingRtp API が正常に動作しない問題を修正しました

17.04.1

リリース:

2017-05-08

対応 Chrome:

M58

対応 Firefox:

53

変更履歴

• [FIX] StopRecording API 実行時に録画中の配信が archives に含まれない問題を修正しました

17.04.0

リリース:

2017-04-28

対応 Chrome:

M58

対応 Firefox:

53

注意

Firefox 53 でマルチストリーム使用時に SDP レベルでのビットレートコントロールがおかしくなる問題が入っています

• 1332031 - TIAS cancels bitrate limiting when additional m-sections appears

• 1342727 - TIAS issues with the webrtc49 update (FF53+)

そのため現時点での Firefox ではマルチストリームを使用しないことをお勧めします。 今後、 Sora は RTCP レイヤーでのビットレートコントロールに対応していく予定です。

ハイライト

• Windows 10 Creators Update の Edge に対応しました

  • Edge 側の制限と Sora が未対応な部分でいくつかの機能は使用できません

• アドレスの自動収集に対応しました

  • sys.config で明示的にアドレスを指定しなくても動作します

• IPv6 アドレスに対応しました

  • シグナリングや API では IPv6 を使用できません

• マルチストリームで視聴のみができるようになりました

• マルチストリームでビットレートが配信者の人数で分割することで 1 チャネルで最大 12 人までの配信が可能になりました

• ARM64 向けのパッケージの提供を開始しました

変更履歴

• [FIX] マルチストリームで VP9 を指定したとしても VP8 になっていたのを修正しました

• [FIX] TURN-TCP 使用時に UDP と TCP 両方にパケットを送信していたのを修正しました

• [CHANGE] ライセンスで接続数が越えた場合は EXCEED-MAX-CONNECTIONS がクライアントに送られるようになりました

• [CHANGE] 改善に向けて RTX 機能を一時的に無効にしました

• [CHANGE] 設定ファイルの allow_anonymous を廃止しました

  • auth_webhook_url を有効にしないかぎり、すべての接続が成功するようになりました

• [CHANGE] 設定ファイルの ip_address を廃止しました

  • 新しく追加された ipv4_address を使用してください

• [CHANGE] シグリングで使用していた access_token を廃止しました

  • 17.02 で入った metadata を使用してください

• [CHANGE] 20151104 の StartRecording / StopRecording / ListRecording API を廃止しました

  • 今までは 400 が返っていましたが、今後は 404 が返ります

• [ADD] マイクロソフト Edge に対応しました

  • Edge 側の制限で動作させるためには多くの制限があります

  • マルチストリームは使用できません

  • Certificate Management API は使用できません

  • IPv6 アドレスは使用できません

  • IPv6 対応 TURN サーバーは使用できません

  • STUN サーバーは使用できません

  • 接続できない TURN サーバーは iceServers の urls に指定できません

    • そのため ipv4_address にはクライアントが接続可能な IPv4 アドレスを指定してください

  • Sora は今回のリリースで RTX を一時的に無効にしたため Generic NACK が使用できません

• [ADD] 使用可能な IP アドレスを自動で収集するようになりました

  • IP アドレスを設定ファイルに設定する必要がなくなりました

• [ADD] 設定ファイルに ipv4_address を追加しました

• [ADD] 設定ファイルに ipv6 を追加しました

  • シグナリングや API では IPv6 を使用できません

  • IPv6 を使用する場合は有効にしてください

  • デフォルトでは無効になっています

• [ADD] 設定ファイルに ipv6_address を追加しました

  • この機能を使用するには ipv6 を true にする必要があります

• [ADD] TURN 機能が IPv6 アドレスに対応しました

  • 設定ファイルで ipv6 を有効にして、さらに IPv6 アドレスが指定または収集された場合に払い出されます

• [ADD] 認証の戻り値で candidate や TURN の url に使用する IP アドレスが指定可能になりました

  • ipv4_address と ipv6_address が指定できます

  • 設定ファイルの値を上書きします

• [ADD] Chrome でのマルチストリームで視聴のみを可能にする

  • マルチストリーム使用時に role: downstream を使用することで、視聴で専用のみが実現できます

• [ADD] マルチストリームで使用されるビットレートが配信者の人数分で分割されるようになりました

  • この機能を導入することで最大 12 人での同時配信が可能になりました

• [ADD] Chrome でのマルチストリームでビデオコーデックが指定できるようになりました

• [ADD] マルチストリームで Generic NACK の有無が有効になりました

• [ADD] ARM64 向けのパッケージを提供開始しました

  • 対応 OS は Ubuntu 16.04 のみです

• [ADD] 設定ファイルに label を追加しました

  • この機能はプレビュー機能です

  • 認証やイベントウェブフック通知時に含まれるサーバー固有の値を指定できます

• [ADD] 設定ファイルに hide_origin_username を追加しました

  • この機能はプレビュー機能です

  • SDP の offer 時に払い出される origin の username を "-" にすることができます

• [ADD] TURN の URL 払い出しに使用する FQDN を指定可能になりました

  • FQDN が優先されます

• [ADD] TURN-TLS の URL 払い出しに対応しました

  • TURN-TLS の TLS 部分の処理は nginx などで終端して貰う前提の機能です

後方互換性のない変更

• allow_anonymous を廃止しました

  • 認証を使用したい場合は auth_webhook_url を有効にしてください

• Sora 自身の IP アドレスをする ip_address を廃止しました

  • ipv4_address を使用してください

• シグナリングで使用していた access_token を廃止しました

  • metadata を使用していください

• 録画用の古い API の戻り値を 400 から 404 に変更しました

17.02.14

リリース:

2017-03-17

対応 Chrome:

M57

対応 Firefox:

52

• [FIX] connection.updated の signaling_notify の判定が間違っていたのを修正しました

• [FIX] snapshot のタイマーが固定されないのを修正しました

• [CHANGE] connection_created_wait_timeout のデフォルト値を 30 秒に変更しました

• [CHANGE] connection_created_wait_timeout の最大値を 600 秒に変更しました

• [CHANGE] snapshot の最大時間を 10 秒に変更しました

• [ADD] 不安定な回線でも最初のキーフレームを受け取る可能性を上げる仕組みを追加しました

• [ADD] event_metadata を追加しました

  • 認証成功時の戻り値に event_metadata を含むことでイベントウェブフック通知時に含まれる metadata を指定できるようになりました

• [UPDATE] Chrome M57 に対応しました

• [UPDATE] Firefox 52 に対応しました

17.02.8

リリース:

2017-02-27

対応 Chrome:

M56

対応 Firefox:

51

• [FIX] 音声のみの録音で生成される WebM が一部期待通りに生成されない問題を修正しました

• [FIX] Fingerpirnt のチェックを非同期で行うように修正しました

  • Answer が送られてくるのが遅くなった場合に証明書エラーになっていた問題に対応しました

• [CHANGE] デモ機能は Chrome の場合 M56 以上が必須になりました

• [UPDATE] Chrome M56 に対応しました

• [UPDATE] マルチストリームの性能を向上させました

• [UPDATE] シグナリング経由での通知機能を、認証ウェブフックの戻り値によりクライアント単位で有効/無効にできるようになりました

• [UPDATE] TURN-TCP の動作を安定化させました

  • Firefox での TURN-TCP も問題なく動作するようになりました

• [CHANGE] シグナリングの connect 時の access_token を 17.04 にて廃止します

• [ADD] Answer が 30 秒以内に送られてこない場合はエラーとする仕組みを追加しました

  • 今後 30 秒という値は sys.config の設定にて変更できるようになる予定です

• [ADD] シグナリングの connect 時の access_token の代わりに metadata を追加しました

  • access_token はオプション扱いで値が入ってこない場合、認証サーバーには null が入っていましたが、 metadata は入力しなければ項目自体が入ってきません

  • それ以外は特に変更は無く、 access_token 同様、どんな値でも入れることができます

• [ADD] H.264/Opus の WebM 形式での録画に対応しました

• [ADD] H.264 のみの WebM 形式での録画に対応しました

• [ADD] プレビュー機能として指定したチャネル ID の RTP を転送する API を追加しました

  • StartForwardingRtp/StopForwardingRtp API を追加し、指定した IP アドレスとポート番号に対して配信されてくる RTP をそのまま転送します

  • DTLS-SRTP の中身 (RTP) をそのまま送ります

  • RTCP は送信しません

• [ADD] プレビュー機能として RTX へ対応しました

  • デフォルトでは無効になっており、有効にするには sys.config にて {rtx, true} にする必要があります

  • RTX は RFC4588 で定義されている機能で、再送制御機能です

17.01.5

リリース:

2017-02-07

対応 Chrome:

M56

対応 Firefox:

51

• [FIX] イベントウェブフックの通知の一部が間違っていたのを修正しました

17.01.4

リリース:

2017-02-02

対応 Chrome:

M56

対応 Firefox:

51

• [UPDATE] Chrome M56 に対応しました

• [FIX] 切断のウェブフックの通知タイプのスペルが間違っていたのを修正しました

• [FIX] マルチストリームの RTCP が正常にハンドリングするように修正しました

17.01.2

リリース:

2017-01-25

対応 Chrome:

M55

対応 Firefox:

51

2017 年のリリースからバージョン番号を変更しました

• [UPDATE] Firefox 51 に対応しました

• [FIX] generic_nack を false にした場合はキャッシュを行わない用に修正しました

• [FIX] 接続判定に誤りがありライセンスの接続数よりも 1 本多く接続できるようになっていたのを修正しました

• [CHANGE] log/warning.log には warning のみを出力するようにしました

• [CHANGE] log/error.log には error のみを出力するようにしました

• [CHANGE] 認証ウェブフックの upstream_connections を channel_upstream_connections に変更しました

• [CHANGE] 認証ウェブフックの downstream_connections を channel_downstream_connections に変更しました

• [CHANGE] イベントウェブフックの upstream_connections を channel_upstream_connections に変更しました

• [CHANGE] イベントウェブフックの downstream_connections を channel_downstream_connections に変更しました

• [ADD] canvas を使用してカメラ映像とペイントを合成し配信する機能のデモを追加しました

• [ADD] イベントウェブフックに送受信の流量情報を追加しました

  • total_sent_bytes

    • そのクライアントが今までに送信したパケット(バイト)量です

  • total_received_bytes

    • そのクライアントが今までに受信したパケット(バイト)量です

• [ADD] プレビュー版 としてTURN-TCP 機能を 追加しました

  • この機能は sys.config にて {turn_tcp, true} を指定することで有効になります

    • デフォルトは {turn_tcp, false} です

  • TURN-TCP で使用するポート番号は {turn_tcp_port, 3478} のように指定してください

    • デフォルトは 3478 ポートを使用します

• [ADD] プレビュー版 としてシグナリング経由でのサーバー情報の通知機能を追加しました

  • この機能は sys.config にて {signaling_notify, true} を指定することで有効になります

• [UPDATE] RFC7983 に対応しました

  • Multiplexing Scheme Updates for SRTP Extension for DTLS

3.4.5

リリース:

2016-12-20

対応 Chrome:

M55

対応 Firefox:

50

• [FIX] Chrome Canary M57 にて正常に通信ができない問題を修正しました

• [FIX] 接続数が多くなった場合、性能劣化が起きる問題を修正しました

• [UPDATE] CentOS 7.3 向けパッケージの提供を開始しました

3.4.1

リリース:

2016-11-30

対応 Chrome:

M55

対応 Firefox:

50

• [UPDATE] Firefox 50 での動作を確認しました

• [UPDATE] Chrome M55 での動作を確認しました

• [ADD] 実験的にマルチストリームでの録画に対応しました

  • 一つのチャネルで複数の映像が流れた場合の録画にも対応しました

• [ADD] 認証レスポンスでオーディオとビデオのパラメータの上書きを可能にしました

  • allowed だけでなく audio や video を返せるようになりました

  • サーバー側でこのクライアントは VP9 コーデックで、ビットレートは 500 を指定するといったことが可能になります

• [ADD] 録画成功時、録画ファイルとは別に録画ファイルのメタ情報を JSON 形式で出力するようになりました

  • 録画ファイル名.json という形で出力されます

• [CHANGE] 録画機能 API が非同期になり、エラーメッセージが変更になりました

  • いくつかの録画機能向けの API が追加されました

• [CHANGE] 録画機能が StopRecording API を実行するか、有効期限が切れるまではそのチャネルで録画をするようになりました

  • このタイミングで recording.report を通知するようになりました、これはその間に録画されたファイルの情報を通知します

• [CHANGE] 録画機能のイベントウェブフック archive.finished が archive.available に変更しました

  • ファイルへの変換が終了したタイミングで今までは archive.finished を通知しておりましたが、今後は archive.available を通知します

• [CHANGE] archive.available の通知内容に情報を追加、変更しました

  • filepath を file_path に変更しました

  • 録画ファイル生成時間 created_at を ISO8601 から UNIX Time に変更しました

  • 録画開始時間 start_time (UNIX Time) を追加しました

  • 録画終了時間 stop_time (UNIX Time) を追加しました

  • メタデータファイルパス metadta_file_path を追加しました

  • メタデータファイル名 metadta_filename を追加しました

  • コーデック情報だけでなくビットレートや解像度なども出力するようにしました

• [CHANGE] イベントウェブフックの中に入ってくる時間の項目を created_at から timestmap に変更しました

• [FIX] TURN 機能が正常に動かない不具合があったのを修正しました

• [FIX] 映像保存時にパケロスが長期的に発生した場合に正常に映像が保存されない問題を修正しました

• [FIX] マルチストリームでビットレートやコーデックを指定できるよう修正しました

  • ただし PlanB の場合はコーデック指定は行えず、 VP8 のみ限定

• [FIX] UpgradeRole / DowngradeRole API のエラー処理を修正しました

3.3.4

リリース:

2016-10-28

対応 Chrome:

M54

対応 Firefox:

49

• [ADD] デモ機能の有効無効を選択できる機能を追加しました

  • いままでデフォルトで有効であった、いろいろな機能を試すためのデモ機能を無効にできる仕組みを追加しました

  • sys.config で {demo, true} とすることで有効にすることができます

• [ADD] Generic NACK を有効かどうかを指定できる設定を追加しました

  • sys.config の generic_nack 項目にて指定できます。デフォルトで有効になっています。

• [ADD] 録画できる解像度の制限をなくしました

  • 解像度が HD や QVGA でも録画を可能にしました

• [UPDATE] Chrome M54 での動作を確認しました

• [UPDATE] 認証処理時にクライアントが指定した音声・映像・マルチストリームの情報を認証サーバーへ送るようにしました

  • 映像のビットレートやコーデックなどを認証条件に含めることができるようになりました

• [CHANGE] シグナリング時のエラー戻り値を JSON から文字列に変更しました

  • WebSocket の制限でエラー理由のメッセージサイズに制限があるため文字列へ変更しました

• [CHANGE] 認証ウェブフックの Reason がクライアントに送られる Reason に置き換わりました

  • エラー理由が JSON から文字列に切り替わったため認証サーバーから送った Reason がクライアントに送られます

• [CHANGE] 認証ウェブフックで認証失敗時に metadata を送れなくなりました

  • エラー理由が JSON から文字列に切り替わったため metadata を失敗時に送れなくなりました

• [CHANGE] 認証ウェブフックで認証失敗時の reason のサイズが最大で 100 バイトまでになりました

  • WebSocket の仕様に準拠するための制限です

• [CHANGE] マルチストリームのチャネル空間が通常と共有されるようになりました

  • multistream: false と multistream: true でのチャネル ID 空間が共有されます

  • multistream: false で使用しているチャネル ID は multistream: ture 使用できなくなりました

• [FIX] マルチストリームで PLI が一定状況で想定外の動作をする問題を修正しました

• [FIX] マルチストリームの Plan B で映像のみ、音声のみの順番で繋ぐと例外が発生する問題を修正しました

  • こちらは現時点で正常な動作は行えず、既知のバグとして問題解決に取り組んでおります

• [FIX] イベントフック通知の戻りのステータスコードが 200 を要求していたのを 200 番台で問題ないように修正しました

• [FIX] TURN 機能使用時の Nonce の動作を RFC 準拠に修正しました

• [FIX] TURN 機能使用時に CreatePermission が送られてきていない状態で Binding-Request を受け取った場合例外が発生する問題を修正しました

3.2.1

リリース:

2016-10-11

対応 Chrome:

M53

対応 Firefox:

49

• [UPDATE] Firefox 49 での動作を確認しました

  • Firefox でも application_specific_maximum が使用できるようになりました

• [UPDATE] マルチストリーム(Unified Plan) で audio のみの配信に対応しました

• [UPDATE] マルチストリーム(Plan B) で audio のみの配信に対応しました

• [UPDATE] 組み込み UI を改善しました

  • クライアント単位の情報が見やすくなりました

  • TURN 関連の統計情報を追加しました

• [UPDATE] ストリーミング配信の安定性を向上させました

  • MPD を WebRTC 向けに調整することで、長時間の安定的な配信が可能になりました

• [UPDATE] 配信先を変更した場合の安定性を向上させました

  • 配信者を切り替えた場合に視聴者側の映像が不安定になりにくくなりました

• [UPDATE] WebRTC の接続が確立するまでのデフォルト許容時間を 10 秒に変更しました

• [UPDATE] パケット再送信用のキャッシュサイズを指定可能になりました

  • sys.config の generic_nack_cache_size にて指定できます

• [UPDATE] マルチストリームのサンプルファイルを統合しました

  • Chrome でも Firefox でも multistream.html にてご使用いただけます

3.1.0

リリース:

2016-09-14

対応 Chrome:

M53

対応 Firefox:

48

• [UPDATE] Chrome M53 での動作を確認しました

• [CHANGE] "undefined" という channel_id は使用できなくなりました

  • undefined は channel_id が設定されずにエラーが発生した場合のログなどに使用されます

• [CHANGE] sys.config の認証 URL を auth_url から auth_webhook_url に変更しました

• [CHANGE] sys.config のウェブフック URL を webhook_url から event_webhook_url に変更しました

• [CHANGE] ウェブフックのログファイルを webhook.log から event_webhook_log に変更しました

• [CHANGE] 認証の判断を HTTP ステータスコードから戻りの JSON に変更しました

  • 今までは HTTP ステータスコード 200 を認証成功、それ以外を認証失敗としていましたが戻りの JSON で判断するように変更しました

  • ステータスコードは成功でも失敗でも 200 番台系である必要があります

  • 認証成功の場合は {"allowed": true} 認証失敗の場合は {"allowed": false, "reason": "failure reason"} を戻す必要があります

• [CHANGE] metadata の取り扱いを変更しました

  • auth_response_with_metadata という設定は削除されました

  • アプリケーション側が認証成功時の戻り JSON に {"metadata": "<JSON>"} を戻すことで metadata がクライアントまで送られるようになりました

  • "metadata" はそのままクライアントに "meatadata": "<JSON>" として送られるようになります

• [CHANGE] signaling.* という通知はなくなり connection.* という通知に変更しました

  • より扱いやすいタイミングへの通知に変更しました

  • 名前が変わっただけでなくタイミングも変わりました

• [UPDATE] イベントウェブフックで送られる値に access_token を含むようにしました

• [UPDATE] シグナリングのエラー通知を増やしました

• [CHANGE] type: notification を type: notify に変更しました

  • 実験的機能として提供中

• [FIX] シグナリング失敗時に role と channel_id が入らない問題を修正しました

• [UPDATE] PCMU 録音時にメモリを使用せず、一時的にディスクに書き込む仕組みを追加しました。

  • この機能により長時間の録音でもメモリを消費することがなくなりました

• [ADD] 組み込み UI を追加しました

  • 実験的機能として提供中

  • 各クライアントの統計情報を確認できるようになりました

3.0.2

リリース:

2016-09-06

対応 Chrome:

M52

対応 Firefox:

48

• [FIX] 2016 年 9 月 6 日付の Chrome Canary M55 では、WebRTC 暗号部分が Google 独自の方式に非対応だったために Sora が動作しない問題を修正しました

3.0.0

リリース:

2016-08-31

対応 Chrome:

M52

対応 Firefox:

48

• [CHANGE] WebRTC の通信が確立したタイミングのフック名を signaling.compileted に変更しました

  • transport.encrypted から singnaling.completed に変更しました

• [ADD] スナップショット機能を追加しました

  • 映像を受け取らず音声だけの場合に、映像のスナップショットをシグナリング経由で受け取る機能です

  • WebP という画像フォーマット形式で出力しています

  • 映像から無変換で画像を切り出しているため、映像コーデックが VP8 で Chrome でのみ表示できます

• [ADD] WebM-DASH ライブストリーミング機能を追加しました

  • この機能は実験的機能で 3.x で正式版をリリース予定です

  • WebRTC 経由で送られてきた映像を MPEG-DASH 形式に無変換でファイルを生成する仕組みです

  • この技術で CDN を使うことができるようになるため、 WebRTC では限界のあった配信数を大幅に増やすことができます

  • 遅延が 1 分以上発生します

• [ADD] 録画機能で音声だけの録音に対応しました

  • 今までは映像または映像と音声の組み合わせのみでしたが、今後は音声のみでも録音できるようになりました

• [ADD] 音声コーデックに PCMU を選択できるようになりました

• [ADD] PCMU を録音できるようになりました

  • wav ファイルを出力します

  • 現時点ではオンメモリでの保存のため、メモリを消費します

  • 3.x でディスク書き込みに対応予定です

• [ADD] 配信者が映像で使用可能な最大ビットレートを指定できるようになりました

  • リリース時点では Chrome のみで、Firefox では 2016 年 9 月にリリース予定の Firefox 49 から使用できます

• [ADD] Chrome でマルチストリーム機能が使用可能になりました

  • この機能は実験的機能で 3.x で正式版をリリース予定です

• [FIX] Firefox で Generic NACK が有効になっていなかったのを修正しました

• [FIX] 音声と映像が出力されない場合のエラーを修正しました

2.6.0

リリース:

2016-07-15

対応 Chrome:

M51

対応 Firefox:

47

• [UPDATE] TURN の NONCE が古い場合は 438 を返すように変更しました

• [FIX] TURN 機能がマルチストリーム使用時にも使えるようになりました

• [ADD] Push API を追加しました

  • PushChannel API

    • 特定のチャネル全員にメッセージを配信します

  • PushClient API

    • 特定のクライアントにメッセージを配信します

  • PushUpstream API

    • 配信者に対してメッセージを配信します

  • PushDownstream API

    • 視聴者全員に対してメッセージを配信します

2.5.0

リリース:

2016-07-06

対応 Chrome:

M51

対応 Firefox:

47

• [UPDATE] VP8/VP9 においてキーフレームからの開始を強制するようにしました

• [UPDATE] SDP の情報が不足していた場合にシグナリング経由でエラーを通知するた機能を追加しました

• [ADD] ベータ機能として type: notification を追加しました

• [ADD] 視聴者側からの RTCP-RR における RTPFB の TMMBN に対応しました

  • https://datatracker.ietf.org/doc/html/rfc5104#section-4.2.2

• [FIX] たまに視聴者に接続開始から数十秒配信がされなくなる問題を修正しました

• [ADD] シグナリングを使ってチャネル接続クライアントにメッセージを送る type: broadcast を追加しました

2.4.0

日時:

2016-06-24

対応 Chrome:

M51

対応 Firefox:

47

CPU リソースの消費を抑えるなど全体的なパフォーマンスが向上しました

• [CHANGE] api_port の sys.config に設定されている初期の値を 6000 から 3000 に変更しました

• [ADD] ブラウザからクロスドメインでの HTTP API が使えるようになる api_cors_origin という設定を追加しました

• [ADD] 視聴者参加時に視聴者を配信者から視聴者へ戻す API を追加しました

  • DowngradeRole API を使うことで配信者を視聴者に戻すことができるようになります

• [ADD] 組み込み TURN 機能を追加しました

• [ADD] ベータ機能としてネットワークライセンス認証の仕組みを追加しました

• [FIX] 配信者側のカメラ切り替えをしたとしても視聴者側が停止しない仕組みを追加しました

2.3.0

日時:

2016-06-08

対応 Chrome:

M51

対応 Firefox:

47

• [ADD] 録画時に一時ファイルを作成して録画するように変更しました

  • 録画ファイルの一時的置き場を指定する archive_tmp_dir 設定が追加されました

  • ディスク容量のあくかぎり、長時間の録画が可能になりました

• [CHANGE] 録画ディレクトリ指定の設定名が archive_filepath から archive_dir に変更しました

  • 設定ファイルの互換性が無くなりました

• [UPDATE] RTCP-RR で戻す統計情報が RFC に準拠しました

• [ADD] 実験的機能としてマルチストリームを使った視聴者参加機能を追加しました

  • 視聴者に対して API 経由で配信者に切り替えを行えます

2.2.0

日時:

2016-05-30

対応 Chrome:

M51

対応 Firefox:

46

• [ADD] ビデオコーデックで VP9 形式の録画機能を追加しました

• [CHANGE] archive.finished フック内のパラメータを codec_type から codec_name に変更しました

• [CHANGE] ListRecording API 内のパラメータを codec_type から codec_name に変更しました

• [UPDATE] 視聴者が指定したメディアのみを受け取れるようになりました

2.1.0

日時:

2016-05-18

対応 Chrome:

M50

対応 Firefox:

46

• [ADD] 録画失敗時のフック archive.failed を追加しました

• [CHANGE] マルチストリーム周りの動作を変更しました

  • すべてをマルチストリームベースにするための仕組みを少しずついれています詳細についてはお問い合わせください

2.0.0

日時:

2016-05-02

対応 Chrome:

M50

対応 Firefox:

46

既存の API との互換性が無くなりました

• [CHANGE] Stream API が無くなり Webhook に変更しました

• [CHANGE] Action API が通常の API に名前を変更しました

• [CHANGE] すべての JSON のキーに使用する形式を camelCase から snake_case に変更しました

• [ADD] 配信側のコーデックを指定できるようにしました

• [ADD] 無変換での VP8 コーデックと Opus に対応した録画機能を追加しました

1.2.0

日時:

2016-03-16

対応 Chrome:

M49

対応 Firefox:

45

• [FIX] 視聴時に UDP で異常が発生した場合、シグナリング部分を正常終了するようにしました

• [ADD] 認証成功時と失敗時にあいてから送られてきた JSON を metadata: として戻す機能を追加しました

• [ADD] Generic NACK に対応しました

• [BETA] 実験的に配信側のコーデックを指定できるようにしました

• [BETA] 実験的に VP8 コーデックに対応した録画機能を追加しました

1.1.4

日時:

2016-03-14

対応 Chrome:

M49

対応 Firefox:

45

• [FIX] candidate が Answer 到着前に来た場合、保留しておいて Answer 到着時に最優先で返す対応を追加しました

• [FIX] Event API で渡す JSON が sanke_case になっているのを camelCase に修正しました

1.1.0

日時:

2016-02-09

対応 Chrome:

M48

対応 Firefox:

44

• [BETA] 実験的に Firefox 44 以降の Multistream 対応に対応しました

• [ADD] RTCP-RR の動的処理を行うように変更しました

• [UPDATE] CentOS 7.1 へのパッケージを提供開始しました

• [CHANGE] DTLS 1.2 のみの対応に変更しました

  • Chrome は M48 から DTLS 1.2 に対応しました

• [CHANGE] 使用する暗号方式を ECDHE-ECDSA-AES-GCM のみの対応に変更しました

1.0.1

日時:

2015-12-16

対応 Chrome:

M47

対応 Firefox:

43

• [FIX] connect upstream 時の Offer SDP ログを保存し忘れていたのを修正しました

• [FIX] elasped time を 30 秒から 60 秒に変更しました

1.0.0

対応 Chrome:

M47

対応 Firefox:

43

古いドキュメント

2024.1.x

重要

2025 年 6 月 30 日までサポート対象です。

https://support-2024-1.shiguredo-sora-doc.pages.dev/

2023.2.x

危険

サポート対象外です。

https://support-2023-2.shiguredo-sora-doc.pages.dev/

2023.1.x

危険

サポート対象外です。

https://support-2023-1.shiguredo-sora-doc.pages.dev/

2022.2.x

危険

サポート対象外です。

https://support-2022-2-3.shiguredo-sora-doc.pages.dev/

2022.1.x

危険

サポート対象外です。

https://support-2022-1-3.shiguredo-sora-doc.pages.dev/

コンテンツ

• 2024.1.x から 2024.2.x への移行
  • 概要
  • レガシー録画機能のデフォルト無効
  • セッション単位での同時接続数を制限する session-webhook-trial_max_connections の追加
  • JSON Lines 形式のログ出力に対してエスケープ処理を行わないよう変更
  • ウェブフック送信を行わない場合でもログを出力するように変更
  • 既存のセッションの同時接続数が 0 の際に、このセッションと異なる multistream または spotlight 設定の新規接続が来た場合の挙動の変更
  • プレイアウト遅延機能が配信側から視聴側への適用に変更
  • 録画の出力ファイルが MP4 形式に対応しました
  • WebSocket シグナリング時のフレームサイズが大きい場合のエラー改善
  • クライアントからの "type": "disconnect" による切断の改善
  • WebSocket シグナリング利用時に Sora から正常切断が発生した際の改善
  • DataChannel シグナリングのみの利用時に Sora から切断が発生した際の "type": "close" メッセージの送信
  • Sora からの正常切断時の reason の値を空文字にする設定
  • シグナリングエラー時の改善
  • シグナリングエラー時のエラーメッセージの改善
  • クラスターのローリングアップデートについて
  • 統計情報 total_received_intra_frame を total_received_key_frame に変更しました
  • JoinCluster API を廃止しました
  • ListClusterNodes API の include_all_known_nodes を廃止しました
  • sora.conf の legacy_auth_webhook_log を廃止しました
  • sora.conf の legacy_event_webhook_connection_destroyed_reason を廃止しました
  • sora_conf-signaling_forwarding_filter を非推奨にしました
  • 認証成功時とセッション生成時の払い出し forwarding_filter を非推奨にしました
  • mode_session_vanished ウェブフックを非推奨にしました
  • RTP ストリーム停止/再開 API を非推奨にしました
• レガシー録画機能から新しい録画機能 (セッション単位) への移行
  • レガシー録画の有効化
  • レガシー録画機能ではできて、新しい録画機能ではできないこと
  • 変更点
  • レガシー録画機能と新しい録画機能の同時利用
• レガシーストリーム(非マルチストリーム)機能からマルチストリーム機能への移行
  • なぜレガシーストリームを廃止するのか
  • Sora 2024.1.0 からレガシーストリームをデフォルトで無効にし非推奨へ
  • 2025 年 6 月リリース予定の Sora でレガシーストリームが廃止に
  • レガシーストリーム機能ではできて、マルチストリーム機能ではできないこと
  • 移行時の注意点
• リリースノート
  • 2024.2.1
  • 2024.2.0
• 用語集
  • クライアント
  • チャネル
  • セッション
  • コネクション
  • ロール
• 既知の問題
  • Chrome/Edge の不具合による録画機能利用時の音ズレ問題について
  • 署名アルゴリズムに SHA-1 が利用されている中間証明書をご利用されているお客様へ
  • サイマルキャスト録画機能
  • マルチストリーム機能
  • OBS WHIP/WHEP 機能
  • 仕様としての制限
• 実験的機能
  • 概要
  • トライアル一覧
  • 実験的機能一覧
• 非推奨機能
  • CentOS 7 対応
  • Ubuntu 20.04 対応
  • レガシー録画機能の廃止
  • レガシーストリーム(非マルチストリーム)機能の廃止
  • ListForwardingFilters API の channel_forwarding_filter の廃止
  • 認証成功時とセッション生成時の forwarding_filter の廃止
  • RTP ストリーム停止/再開 API の廃止
  • 統計エクスポーター機能の廃止
  • ユーザーエージェント統計の廃止
  • mode_session_vanished の廃止
  • スポットライト機能 spotlight_number 項目の認証成功時の払い出しの非推奨化
  • ウェブフックと統計エクスポーターの HTTP ヘッダー x-sora prefix の非推奨化
  • API
• 廃止機能
  • 概要
  • ListClusterNodes API の include_all_known_nodes の廃止
  • sora.conf の legacy_auth_webhook_log の廃止
  • sora.conf の legacy_event_webhook_connection_destroyed_reason の廃止
  • 認証成功時の払い出し h264_profile_level_id の廃止
  • sora.conf の default_h264_profile_level_id の廃止
  • Lyra コーデック対応の廃止
  • sora.conf の legacy_log_format の廃止
  • sora.conf の legacy_log_extension の廃止
  • sora.conf の legacy_webhook_audio_video_json_structure の廃止
  • DataChannel で利用している SCTP 関連の実験的な設定の廃止
  • Ubuntu 18.04 サポートの終了
  • sora.conf の split_archive_legacy_prefix の廃止
  • sora.conf の default_multistream の廃止
  • redact_archive_metadata_sensitive_data と redact_api_sensitive_data の廃止
  • recording.report の metadata_filename と metadata_file_path の廃止
  • シグナリング通知メタデータ metadata_list の廃止
  • "type": "update" の廃止
  • sora.conf の demo の廃止
  • sora.conf の remote_stats の廃止
  • StopRecording API の redirect の配信
  • CentOS 8 対応
  • extmap_allow_mixed 設定のデフォルト有効化と廃止
  • スポットライトレガシー機能の廃止
  • rtp にある RTCP 関連統計情報を廃止
  • sora.conf の opus_param_clock_rate を廃止
  • sora.conf の dcsctp_association_max_retrans を廃止
  • role の upstream と downstream を廃止
  • client_id を指定する設定の廃止
  • 旧サイマルキャスト画質変更 API の廃止
  • bin/sora start の廃止
  • Ubuntu 16.04 サポートの終了

問い合わせ (サポート)

• FAQ
  • WebRTC 全般
  • シグナリング
  • 認証
  • 通知
  • API
  • 録画
  • TURN
  • ウェブフック
  • DataChannel
  • クラスター機能
  • その他
  • 性能
  • 運用
  • SDK
  • ライセンス
  • アップデート
  • サポート
• トラブルシューティング
  • 突然切断された
  • VP9 の映像が乱れる
• Sora が期待どおりに動かない場合、または、動作に問題がある場合
  • 事前確認
  • 問い合わせの場合、お送り頂く情報
  • 録画関連の問い合わせについて
• Sora の仕様や使い方に関して質問がある場合
• サポートライフサイクル
  • 概要
  • 変更内容
  • サポートライフサイクル例
  • 対応 OS のサポートライフサイクル

設定

• チュートリアル
  • 概要
  • チュートリアルの注意点
  • Sora の展開
  • 設定ファイル
  • 起動
  • シグナリングへの HTTPS の適用
  • 開発者ツールを利用してみる
  • 次のステップ
  • トラブルシューティング
• 本番稼働に向けて
  • 優先順位
  • IPv4 アドレスの固定
  • IPv6 アドレスの利用について
  • sora.conf の turn_fqdn を設定する
  • ウェブフックなどで利用する CA 証明書のインストール
  • HTTP API のループバックアドレスからのみのアクセス
  • シグナリングのループバックアドレスからのみのアクセス
  • ファイルディスクリプタ数の設定
  • systemd の適用
  • TURN-TLS、TURN-TCP、シグナリングで 443 番ポートを使用する
  • カーネルパラメーターの適用
  • コンテナ環境での利用する場合
  • SDK の利用
  • やりたいことが 1:1 の双方向配信の場合
  • やりたいことが複数人での双方向配信の場合
  • やりたいことが 1:多 の双方向配信の場合
  • やりたいことが 1:多 の片方向配信で、大規模の場合
  • やりたいことが OBS からの配信の場合
  • やりたいことが OBS での取り込みの場合
  • Edge が機能要件に含まれている場合
  • Firefox が機能要件に含まれている場合
  • 認証を外部の指定した HTTP サーバーで判断したい場合
  • 接続、切断の検知を外部の指定した HTTP サーバーで利用したい場合
  • 配信されている音声や映像を記録したい場合
  • クライアント側で参加してきたユーザーの情報を通知したい場合
• ライセンス
  • ライセンスファイルのパス設定と配置
  • ライセンスの更新
  • 同時接続数制限を超えて接続しよう賭した場合
  • ライセンス期限が過ぎている場合
  • ライセンスファイルのパスの更新
  • 最大ノード数ライセンス
  • ライセンスエラー時の動作確認用ライセンスの提供について
• ログファイル
  • log/ 以下のログファイル
  • 特別なログ
  • JSONL (JSON Lines) 形式
  • auth_webhook ログ
  • auth_webhook_error ログ
  • session_webhook ログ
  • connection ログ
  • sora ログ
• sora.conf リファレンス
  • 単位指定
  • 範囲表記
  • license_file
  • label
  • ipv4_address
  • ipv6
  • ipv6_address
  • ipv6_only
  • devtools
  • media_publish_worker_number
  • auth_webhook_url
  • auth_webhook_log
  • session_webhook_url
  • session_webhook_worker_number
  • session_created_timeout
  • session_destroyed_timeout
  • session_updated_webhook_interval
  • session_created_response_validate_warning_as_error
  • event_webhook_url
  • event_webhook_worker_number
  • stats_webhook_url
  • stats_webhook_log
  • stats_webhook_worker_number
  • webhook_ipv6
  • webhook_connect_timeout
  • webhook_response_timeout
  • connection_updated_webhook_interval
  • webhook_insecure
  • webhook_basic_authn
  • webhook_basic_authn_user_id
  • webhook_basic_authn_password
  • webhook_proxy_url
  • webhook_proxy_auth_user
  • webhook_proxy_auth_password
  • webhook_tls_fullchain_file
  • webhook_tls_privkey_file
  • webhook_tls_verify_cacert_file
  • ignore_connection_updated_webhook
  • ignore_connection_failed_webhook
  • ignore_session_updated_webhook
  • ignore_session_vanished_webhook
  • ignore_audio_streaming_webhook
  • ignore_audio_streaming_failed_webhook
  • ignore_spotlight_changed_webhook
  • ignore_recording_started_webhook
  • ignore_archive_started_webhook
  • ignore_split_archive_available_webhook
  • ignore_connection_rtc_webhook
  • archive_dir
  • archive_tmp_dir
  • default_recording_format
  • default_recording_mp4_pli_interval
  • recording_max_expire_time
  • recording_max_split_duration
  • recording_expire_time_required
  • recording_dual_output
  • signaling_port
  • signaling_loopback_address_only
  • signaling_normal_close_reason
  • signaling_notify
  • signaling_notify_session_id
  • signaling_notify_client_id
  • signaling_notify_bundle_id
  • signaling_notify_connection_id
  • signaling_notify_connection_created_timestamp
  • signaling_notify_media
  • signaling_notify_metadata
  • signaling_notify_metadata_ext
  • signaling_notify_authn_metadata_max_size
  • signaling_notify_network
  • signaling_notify_rtp_stream
  • signaling_notify_recording
  • signaling_notify_forwarding_filter
  • signaling_notify_audio_streaming_failed
  • signaling_notify_ice_connection_state
  • signaling_vp9_params
  • signaling_av1_params
  • signaling_h264_params
  • signaling_h265_params
  • signaling_bundle_id
  • copy_websocket_signaling_header_names
  • websocket_signaling_ping_interval
  • websocket_signaling_pong_timeout
  • websocket_stats_timer_interval
  • default_data_channel_signaling
  • data_channel_signaling_close_message
  • default_ignore_disconnect_websocket
  • data_channel_messaging
  • data_channel_messaging_only
  • data_channel_stats_timer_interval
  • data_channel_stats_max_retransmits
  • whip
  • whip_bearer_token_metadata_key
  • whip_turn
  • whep
  • whep_bearer_token_metadata_key
  • whep_turn
  • api_port
  • api_loopback_address_only
  • api_cors_origin
  • turn
  • turn_realm
  • turn_fqdn
  • turn_tls_fqdn
  • turn_tcp
  • turn_tcp_allocate_success_delay_time
  • turn_tcp_listen_port
  • turn_tcp_port
  • turn_tcp_only
  • turn_tls
  • turn_tls_port
  • turn_tls_only
  • rtx
  • ulpfec
  • audio_red
  • generic_nack
  • default_audio_bit_rate
  • default_video_bit_rate
  • default_vp9_param_profile_id
  • default_av1_param_profile
  • default_h264_param_profile_level_id
  • default_h265_param_level_id
  • default_simulcast_rid
  • simulcast_encodings_file
  • simulcast_multicodec
  • simulcast_codecs_file
  • default_forwarding_pli_interval
  • forwarding_simulcast
  • signaling_forwarding_filters
  • signaling_forwarding_filter
  • audio_streaming_url
  • audio_streaming_header
  • default_audio_streaming_result_push
  • default_audio_streaming_language_code
  • audio_streaming_max_retries
  • audio_streaming_retry_interval
  • audio_streaming_tls_fullchain_file
  • audio_streaming_tls_privkey_file
  • audio_streaming_tls_verify_cacert_file
  • recycle_media_section
  • hide_origin_username
  • connection_created_wait_timeout
  • default_spotlight_focus_rid
  • default_spotlight_unfocus_rid
  • default_spotlight_unfocus_audio
  • default_spotlight_unfocus_audio_rate_limit
  • default_spotlight_delayed_focus
  • default_spotlight_delayed_focus_interval
  • default_spotlight_auto_unfocus
  • default_spotlight_auto_unfocus_interval
  • default_spotlight_focus_min_interval
  • default_spotlight_number
  • spotlight_encodings_file
  • multistream_auto_sharing_video_bit_rate
  • default_rtc_stats
  • rtc_stats_log
  • user_agent_stats
  • ice_connection_state_disconnected_timeout
  • ice_connection_state_failed_timeout
  • skip_redact_sensitive_data
  • stats_collector_url
  • default_stats_exporter
  • stats_exporter_number
  • stats_exporter_tls_fullchain_file
  • stats_exporter_tls_privkey_file
  • stats_exporter_tls_verify_cacert_file
  • node_name
  • cluster
  • cluster_temporary_node
  • cluster_relay
  • default_cluster_affinity
  • cluster_affinity_threshold
  • external_signaling_url
  • external_api_url
  • cluster_listen_min_port
  • cluster_listen_max_port
  • data_dir
  • av1
  • h265
  • h264_b_frame
  • h265_b_frame
  • legacy_recording
  • legacy_signaling_error
  • legacy_stream
  • rtp_hdrext_video_orientation
  • rtp_hdrext_video_content_type
  • rtp_hdrext_video_timing
  • rtp_hdrext_playout_delay
  • default_playout_delay_min_delay
  • default_playout_delay_max_delay
  • rtp_hdrext_color_space
  • rtp_hdrext_sdes_mid
  • rtp_hdrext_abs_capture_time
  • rtp_hdrext_dependency_descriptor_vp9
  • rtp_packet_loss_simulator_incoming
  • rtp_packet_loss_simulator_outgoing
  • data_channel_packet_loss_simulator_incoming
  • data_channel_packet_loss_simulator_outgoing
  • ignore_turn_five_tuple
  • opus_param_channels
  • opus_param_maxplaybackrate
  • opus_param_stereo
  • opus_param_sprop_stereo
  • opus_param_ptime
  • opus_param_minptime
  • opus_param_useinbandfec
  • opus_param_usedtx
• systemd
  • 設定
• Linux カーネルチューニング
  • 確認方法
  • Ubuntu
• IPv6 での動作について
  • 概要
  • お問い合わせの際の情報について
  • IPv6 のみ
  • ウェブフックの IPv6 対応
• メタデータ
  • 概要
  • 接続時の認証メタデータ指定
  • 認証ウェブフック成功時のメタデータ払い出し
  • 認証ウェブフック成功時のイベントメタデータ払い出し
  • 接続時のシグナリング通知メタデータ指定
  • 認証ウェブフック成功時のシグナリング通知メタデータ払い出し
  • シグナリング通知メタデータ拡張
  • セッション生成時のセッションメタデータ払い出し
  • 一括録画ファイルメタデータ archive-<connection_id>.json
  • 分割録画ファイルメタデータ split-archive-<connection_id>_<index>.json
  • 録画(セッション単位) の StartRecording API で指定するメタデータ
  • 録画(セッション単位) のセッションウェブフック session.created で指定するメタデータ
  • レガシー録画の StartRecording API で指定するメタデータ
• センシティブデータ
  • 概要
  • 対象ログと項目
  • 書き換えをスキップする
  • 録画メタデータの扱いについて

アプリケーション連携

• アプリケーション連携チュートリアル
  • 概要
  • JSON
  • ウェブフックのローカル開発
  • サンプルコードについて
  • aiohttp
  • ウェブフック HTTP 実装
  • ウェブフック HTTPS 対応
  • ウェブフック mTLS (mutual-TLS またはクライアント認証) 対応
  • ウェブフック IPv6 対応
  • 認証ウェブフック
  • セッションウェブフック
  • イベントウェブフック
  • API
  • 指定したチャネルのコネクションを切断する
  • 接続してから 3 分経過したコネクションを切断する

シグナリング

• WebSocket 経由のシグナリング
  • 概要
  • 用語
  • 仕組み
  • 注意
  • 設定
  • シグナリングのタイプ
  • シグナリングエラー
  • シーケンス図
• DataChannel 経由のシグナリング
  • 概要
  • 目的
  • SDK 対応状況
  • 注意
  • 制限
  • 推奨メッセージサイズ
  • シグナリング切り替え
  • WebSocket が閉じたことを無視する
  • DataChannel への切り替え要否の判断
  • label 単位の圧縮
  • 設定
  • label とシグナリングのタイプ
  • DataChannel 関連の設定
  • シーケンス図
• シグナリングの型定義
  • 基本的なデータ型
  • シグナリング
  • 完全な型定義
• シグナリング通知
  • 概要
  • シグナリング通知を利用することで実現できること
  • シグナリング通知の利用が向いていないこと
  • シグナリング通知の有効 / 無効について
  • sora.conf によるシグナリング通知関連の共通設定
  • コネクションのシグナリング通知
  • sora.conf の設定内容と connection.created 出力の例
  • スポットライト機能のシグナリング通知
  • 録画のシグナリング通知
  • 転送フィルターのシグナリング通知
  • 音声ストリーミング
  • ICE コネクションステートのシグナリング通知
  • ネットワークのシグナリング通知
  • RTP ストリーム停止と再開のシグナリング通知
  • シーケンス図
• シグナリング通知メタデータ
  • 概要
  • 注意
  • 設定
  • シグナリング接続時での指定
  • 認証ウェブフックの戻り値での指定
  • 接続時のシグナリング通知メタデータを認証払い出し時のシグナリング通知メタデータで上書き
• シグナリング通知メタデータ拡張機能
  • 概要
  • 目的
  • シグナリング通知メタデータの課題
  • メタデータ拡張機能を利用することで実現できること
  • メタデータ拡張機能の有効 / 無効について
  • メタデータ拡張機能の特徴
  • メタデータ拡張機能の制限
  • メタデータ拡張の初期値
  • 利用方法
• Sora クライアント要求仕様
  • 概要
  • クライアント側の終了処理条件
  • アプリケーション経由の "type": "disconnect" 送信後の終了処理
  • 異常発生による終了
  • ライセンスエラーによる終了
  • RTCPeerConnectionState が定義されていない場合
  • クライアントの状態
  • クライアントからの "type": "disconnect" による切断
  • WebSocket シグナリング利用時に Sora から正常切断
  • DataChannel シグナリングのみ利用時に Sora から切断が発生した際の "type": "close" メッセージの送信

ウェブフック

• ウェブフック
  • 概要
  • ウェブフックリクエスト
  • ウェブフックの設定
  • ウェブフックのタイムアウト時間の指定
  • ウェブフックリクエストなどの送信先サーバー証明書の検証に利用する OS 組み込みのルート CA 証明書について
  • ウェブフックリクエスト送信先のサーバーがベーシック認証を利用している場合
  • ウェブフックリクエスト送信先のサーバーが自己発行証明書などを利用している場合
  • ウェブフックリクエスト送信先のサーバーが mTLS を利用している場合
  • ウェブフックリクエスト送信先が IPv6 アドレスのみ対応している場合
  • connection.updated と session.updated ウェブフック
  • ウェブフックの順番保証
  • ウェブフックの警告メッセージ
• 認証ウェブフック
  • 概要
  • 注意
  • HTTP ヘッダー
  • 設定
  • 認証処理時に送信する JSON
  • 認証ウェブフックに含まれる同時接続数について
  • sora_client
  • 認証成功時のレスポンス JSON
  • 認証失敗時のレスポンス JSON
  • 認証ウェブフック成功時の払い出し
  • WebSocket シグナリング時の HTTP ヘッダーを認証ウェブフックにコピーする機能
  • 認証ウェブフックログ
  • クラスターリレー機能利用時に認証が 2 回行われる場合がある
  • エラーメッセージ
  • シーケンス図
• 認証ウェブフック成功時の払い出し
  • 概要
  • 範囲表記
  • audio の払い出し
  • video の払い出し
  • client_id の払い出し
  • bundle_id の払い出し
  • simulcast / simulcast_rid の払い出し
  • simulcast_encodings の払い出し
  • simulcast_codecs の払い出し
  • spotlight_encodings の払い出し
  • spotlight の払い出し
  • data_channel_signaling の払い出し
  • ignore_disconnect_websocket の払い出し
  • data_channels の払い出し
  • metadata の払い出し
  • event_metadata の払い出し
  • シグナリング経由での通知機能の払い出し
  • シグナリング通知メタデータ拡張機能の初期値払い出し
  • 録画ブロック機能の払い出し
  • cluster_affinity の払い出し
  • forwarding_filters の払い出し
  • forwarding_filter の払い出し
  • connection_lifetime の払い出し
  • playout_delay_min_delay と playout_delay_max_delay の払い出し
  • ipv4_address と ipv6_address の払い出し
  • turn_fqdn 払い出し
  • turn_tls_fqdn の 払い出し
  • rtc_stats の払い出し
  • user_agent_stats の払い出し
  • audio_streaming_language_code の払い出し
  • stats_exporter の払い出し
  • turn_tcp_only / turn_tls_only の払い出し
  • rtp_packet_loss_simulator_incoming / rtp_packet_loss_simulator_outgoing の払い出し
  • シーケンス図
• セッションウェブフック
  • 概要
  • 目的
  • セッション ID
  • 設定
  • ログ
  • multistream と spotlight が既存セッションと異なる場合の挙動
  • session.created
  • session.destroyed
  • session.updated
  • session.vanished
  • recording.started
  • recording.report
  • audio-streaming.started
  • audio-streaming.stopped
  • API
  • クラスター時の挙動について
  • クラスターリレー時の挙動について
  • HTTP ヘッダー
  • シーケンス図
• イベントウェブフック
  • 概要
  • 注意
  • ログ
  • 設定
  • 接続イベント
  • 録画・録音イベント
  • 録画・録音保存イベント
  • スポットライト機能
  • 音声ストリーミング機能
  • HTTP ヘッダー
  • シーケンス図
• 統計ウェブフック
  • 概要
  • 注意
  • ログ
  • 統計ウェブフックの間隔
  • 設定
  • 統計情報
  • stats 項目に含まれる統計情報の送信頻度
  • RTC 統計情報ログ出力
• ウェブフックの型定義
  • 基本的なデータ型
  • 完全な型定義

正式 API

• API
  • 概要
  • 用語
  • API の種類
  • x-sora-target ヘッダー
  • 設定
  • HTTPie
• シグナリング API
  • DisconnectChannel
  • DisconnectClient
  • DisconnectConnection
  • DisconnectChannelByRole
  • ListConnections
  • ListChannelConnections
• コネクション API
  • RequestKeyFrame
• セッション API
  • TerminateSession
• サイマルキャスト API
  • RequestRtpStream
  • ResetRtpStream
• スポットライト API
  • FocusSpotlightFixed
  • FocusSpotlight
  • UnfocusSpotlight
  • ChangeSpotlightNumber
  • RequestSpotlightRid
  • ResetSpotlightRid
  • BatchRequestSpotlightRid
• プッシュ API
  • PushChannel
  • PushClient
  • PushConnection
  • PushChannelByRole
• 録画 (セッション単位) API
  • StartRecording
  • StopRecording
• 統計 API
  • 統計項目一覧
  • GetStatsConnection
  • GetStatsClient
  • GetStatsAllConnections
• ライセンス API
  • GetLicense
  • UpdateLicense
• モード API
  • ChangeMode
  • GetMode
• 転送フィルター API
  • ListForwardingFilters
  • CreateChannelForwardingFilter
  • UpdateChannelForwardingFilter
  • DeleteChannelForwardingFilter
  • CreateConnectionForwardingFilter
  • UpdateConnectionForwardingFilter
  • DeleteConnectionForwardingFilter
• 音声ストリーミング API
  • StartAudioStreaming
  • StopAudioStreaming
  • SubscribeAudioStreamingResultPush
  • UnsubscribeAudioStreamingResultPush
  • ListAudioStreamingResultPushState

実験的 API

• 実験的 API
  • 概要
  • その他の API
• セッション API
  • GetSession
  • ListSessions
• シグナリング API
  • ListChannels
• RTP 転送 API
  • 注意
  • StartForwardingRtp
  • StopForwardingRtp
• シグナリング通知メタデータ拡張 API
  • ListSignalingNotifyMetadata
  • GetSignalingNotifyMetadata
  • PutSignalingNotifyMetadata
  • DeleteSignalingNotifyMetadata
  • PutSignalingNotifyMetadataItem
  • DeleteSignalingNotifyMetadataItem
• RTP ストリーム停止/再開 API
  • PauseRtpStream
  • ResumeRtpStream
  • ListPauseRtpStreams
• 統計 API
  • GetStatsReport
• RTC 統計情報 API
  • 統計情報更新のタイミングについて
  • ListRtcStats
  • ListChannelRtcStats
  • GetRtcStats

非推奨・廃止 API

• 非推奨 API
  • 概要
  • レガシー録画 API
  • ユーザーエージェント API
• レガシー録画 API
  • StartRecording
  • StopRecording
  • GetStartedRecording
  • ListStartedRecording
  • ListArchiving
• ユーザーエージェント統計情報 API
  • 統計情報更新のタイミングについて
  • ListUserAgentStats
  • ListChannelUserAgentStats
  • GetUserAgentStats
• 廃止 API
  • 概要
  • 廃止クラスター API
  • 廃止 シグナリング API
  • 廃止 サイマルキャスト API
  • 廃止 統計 API
  • 廃止 プッシュ API
  • 廃止 リモート統計情報 API
  • 廃止 スポットライト API

テスト API

• テスト API
  • 概要
  • 注意
  • GenerateCrashLog
  • FailArchive
  • SendSignalingNotify
  • LockIceConnectionState

クラスター機能

• クラスター機能
  • 概要
  • 用語
  • クライアントへの複数シグナリング設定
  • リレー機能
  • アフィニティ機能
  • テンポラリーノード機能
  • シグナリングのリダイレクト機能
  • リダイレクト機能によるノード選択
  • ロードバランス機能
  • HTTP API のリダイレクト機能
  • クラスターへの登録
  • クラスター自動復旧
  • ネットワーク分断時の接続受け付けの停止
  • 特定ノードへの新規チャネル ID の割り当て停止
  • ライセンスで決められた最大同時接続数の合計を維持する機能
  • 設定
  • API
  • 接続時の挙動
  • リレーの終了とアフィニティ機能
  • シーケンス図
• クラスター機能チュートリアル
  • 概要
  • 前提
  • クラスターの構築
  • クラスター操作
• クラスター機能運用
  • クラスター利用時のファイル操作に問題が発生した場合
  • クラスターのレギュラーノード数
  • クラスターのテンポラリーノード数
  • 最大ノード数
  • クラスター利用時のライセンス
  • ポートの開放
  • ノード間通信
  • ノード間通信の暗号化
  • テンポラリーノード機能の利用
  • クラスターからの一時的な離脱
  • 一時的に離脱したノードを含めるクラスターノード一覧
  • クラスターからレギュラーノード情報の完全消去
  • クラスターのローリングアップデート
  • クラスターのローリングアップデート中の挙動
  • Sora のバージョンダウン
  • Sora のローリングアップデート失敗
  • クラスター破綻からの再構築手順
  • ノード名変更手順
  • ロードバランサーの導入
  • ログの出力
  • クラスター構成情報ファイル
  • クラスターからのレギュラーノードの完全消去について
  • PurgeClusterNode API で完全消去したレギュラーノードの再度の参加
  • クラスターから消去されたレギュラーノードを別クラスターに参加させたい場合
  • ネットワーク障害やノード障害
• クラスター機能録画
  • クラスターにおける録画機能
  • 録画ファイルの出力ノード
  • report-<recording_id>.json ファイルの出力ノード
  • report-<recording_id>.json ファイルが一時的に出力されない場合
  • report-<recording_id>.json ファイルの archives の内容と実際に出力される録画ファイルが一致しない場合
• クラスター API
  • InitCluster
  • RegisterClusterNode
  • ListClusterNodes
  • ListClusterChannels
  • PurgeClusterNode

機能

• 開発者ツール
  • 概要
  • 目的
  • 設定
  • オープンソース版
• マルチストリーム機能
  • 概要
  • 制限
  • シグナリング仕様
  • role
  • マルチストリームにおける映像ビットレート自動シェアリング機能
  • シーケンス図
• サイマルキャスト機能
  • 概要
  • 注意
  • 映像の優先度
  • 映像の種類のデフォルト
  • 映像のエンコーディングパラメーターのカスタマイズ
  • 配信側の利用方法
  • 視聴側の利用方法
  • 視聴側のストリームの変更 API
  • シーケンス図
• サイマルキャストマルチコーデック機能
  • 概要
  • 注意
  • 制限
  • 利用方法
• スポットライト機能
  • 概要
  • 仕組み
  • 注意
  • マルチストリームのサイマルキャストとの違い
  • SDK 対応状況
  • スポットライト利用時の映像の種類のデフォルト
  • スポットライト利用時の映像のエンコーディングパラメーターのカスタマイズ
  • フォーカスする配信数
  • 遅延フォーカス
  • 遅延アンフォーカス
  • フォーカスなし音声配信
  • 自動アンフォーカス
  • サイマルキャスト機能を無効にして接続する
  • シグナリング
  • シグナリング通知
  • セッションウェブフック
  • イベントウェブフック
  • API
  • シーケンス図
• OBS Studio WHIP 対応機能
  • 概要
  • 注意
  • WHIP とは何か
  • OBS の WHIP 対応について
  • OBS 以外の WHIP クライアントへの対応について
  • Sora での利用方法
  • OBS での WHIP 利用方法
  • Sora の OBS (WHIP) の挙動
  • WHIP エンドポイント URL
  • WHIP リソース URL
  • 認証仕様
  • ウェブフック仕様
  • 認証ウェブフック成功時の払い出し
  • クラスター利用時の認証ウェブフックの挙動
  • TURN の利用
  • 録画利用時の注意
  • クラスター利用時の挙動
  • シーケンス図
• OBS Studio WHEP 対応機能
  • 概要
  • 注意
  • WHEP とは何か
  • OBS の WHEP 対応について
  • OBS 以外の WHEP クライアントへの対応について
  • Sora での利用方法
  • OBS での WHEP 利用方法
  • Sora の OBS (WHEP) の挙動
  • WHEP エンドポイント URL
  • WHEP リソース URL
  • 認証仕様
  • 認証成功時の払い出し
  • ウェブフック仕様
  • TURN の利用
  • クラスター利用時の挙動
  • シーケンス図
• TURN 機能
  • 推奨設定
  • TURN はすべて同時に試される
  • ブラウザの TURN 対応状況
  • 注意
  • 設定
  • 内蔵 TURN 機能のメリット
  • Sora の TURN 機能
  • Sora の TURN-TCP 機能
  • Sora の TURN-TLS URL 払い出し機能
  • Sora の TURN IPv6 対応
  • TURN-TCP / TURN-TLS の検証
  • Sora TURN 機能の制限
  • 外部の TURN サーバーを使用する場合
  • TURN 機能を使う場合の注意点
  • シーケンス図
• 録画機能 (セッション単位)
  • レガシー録画機能から録画機能(セッション単位)への移行
  • 概要
  • 用語
  • 録画ファイルの出力
  • 録画ファイルの出力形式
  • 制限
  • 無変換録画
  • 録画の開始と終了について
  • コネクション単位の録画ブロックについて
  • sora.conf の設定による録画指定制限
  • MP4 形式のキーフレーム要求間隔の変更
  • 録画情報の API 経由での取得
  • 録画関連イベントのウェブフックについて
  • 単一録画ファイル出力のみ
  • 分割録画ファイル出力のみ
  • 単一録画ファイルと分割録画ファイル
  • 録画ファイル出力失敗時の録画一時ファイル
  • シグナリング通知
  • 録画ファイル合成ツール
  • 録画ファイルアップロードツール
  • 試してみる
  • シーケンス図
• レガシー録画機能
  • 概要
  • 用語
  • 録画ファイルの出力
  • 制限
  • 無変換録画
  • 録画の開始と終了について
  • sora.conf の設定による録画指定制限について
  • 録画関連イベントのウェブフックについて
  • 単一録画ファイル出力のみ
  • 分割録画ファイル出力のみ
  • 単一録画ファイルと分割録画ファイル
  • 録画ファイル出力失敗時の録画一時ファイル
  • シグナリング通知
  • 録画ファイル合成ツール
  • 試してみる
  • 録画関連ファイルアップローダー
  • シーケンス図
• リアルタイムメッセージング機能
  • 概要
  • 注意
  • 制限
  • SDK 対応状況
  • DataChannel を利用したリアルタイムメッセージング機能を有効にする
  • リアルタイムメッセージング用 DataChannel の作成
  • data_channels 仕様
  • "type": "connect" 時の "data_channels"
  • 認証成功時の戻り値
  • "type": "offer" 時の "data_channels"
  • DataChannel を利用したメッセージングのみで接続する
  • シーケンス図
• ICE コネクションステート機能
  • 概要
  • 前提
  • 挙動
  • 設定
  • シグナリング通知
  • ウェブフック
  • テスト
  • ステート図
  • シーケンス図
• モード機能
  • 概要
  • 目的
  • モード
  • ウェブフック
  • API
  • クラスター機能
  • シーケンス図
• ヘルスチェック機能
  • 概要
  • 確認
  • 単体利用時
  • クラスター利用時
• メディア配信ワーカー機能
  • 概要
  • この機能を検討する基準
  • 注意
  • 設定
  • 仕組み
  • シーケンス図
• 音声ストリーミング機能
  • 概要
  • 注意
  • HTTP/2
  • マルチストリームでのみ利用可能
  • 音声ストリーミングの配信
  • 音声ストリーミングのヘッダー
  • 言語コードの指定
  • セッションウェブフック経由での開始
  • セッション破棄時の音声ストリーミング終了
  • API 経由での開始と終了
  • 自動開始/停止機能
  • リトライ条件
  • audio_streaming 関連の払い出し設定の組み合わせによる動作
  • 1 コネクション 1 HTTP/2 コネクション
  • プッシュ通知経由での戻り値の通知
  • ウェブフック
  • シグナリング通知経由で audio-streaming.failed をクライアントへ通知する
  • 設定
  • API
  • Audio Streaming Gateway Suzu
  • シーケンス図
• 転送フィルター機能
  • 概要
  • 目的
  • 注意
  • 機能
  • 転送フィルタールールの仕様
  • フィルタールールの適用
  • 転送フィルター共通 API の仕様
  • チャネル単位の転送フィルター API の仕様
  • コネクション単位の転送フィルター API の仕様
  • セッション生成時のチャネル単位転送フィルター仕様
  • シグナリング時のコネクション単位転送フィルター仕様
  • 認証成功時払い出し時のコネクション単位転送フィルターの仕様
  • シグナリング通知
  • フィルター例
  • FAQ
  • シーケンス図
• マルチ転送フィルター機能
  • 概要
  • 認証接続時と認証成功時/セッション生成時の払い出しの注意点
  • 仕様
  • 性能
  • 認証成功時の払い出し
  • セッション生成時の払い出し
• プレイアウト遅延機能
  • 概要
  • 仕組み
  • 注意
  • 設定
  • 利用方法
  • 設定例
• 統計エクスポーター機能
  • 概要
  • 注意
  • HTTP/2
  • WebRTC Stats Collector Kohaku
  • 設定
  • エクスポーター
  • type の頻度指定
  • シーケンス図

SDK

• Sora JavaScript (TypeScript) SDK
  • 概要
  • サンプル
  • ドキュメント
  • ライセンス
  • サポートについて
  • Discord
• Sora iOS (Swift) SDK
  • 概要
  • ドキュメント
  • サンプル
  • ライセンス
  • サポートについて
  • Discord
  • NAT64/DNS64 対応
• Sora Android (Kotlin) SDK
  • 概要
  • ドキュメント
  • サンプル
  • ライセンス
  • サポートについて
  • Discord
• Sora Unity (C++) SDK
  • 概要
  • ドキュメント
  • ライセンス
  • サンプル
  • サポートについて
  • Discord
• Sora C++ SDK
  • 概要
  • 特徴
  • サンプル
  • ライセンス
  • サポートについて
  • Discord
• Sora Python (C++) SDK
  • 概要
  • 特徴
  • サンプル
  • ドキュメント
  • ライセンス
  • サポートについて
  • Discord
• Sora C (C++) SDK
  • 概要
  • 特徴
  • ライセンス
  • サポートについて
  • Discord

ツール

• WebRTC 負荷試験ツール Zakuro
  • 概要
  • ライセンス
  • サポートについて
  • Discord
• WebRTC 録画合成ツール Hisui
  • 概要
  • ライセンス
  • サポートについて
  • Discord
• WebRTC 統計コレクター Kohaku
  • 概要
  • ライセンス
  • サポートについて
  • Discord
• 音声ストリーミングゲートウェイ Suzu
  • 概要
  • ライセンス
  • サポートについて
  • Discord
• Sora Archive Uploader
  • 概要
  • ライセンス
  • サポートについて
  • Discord
• Sora Exporter
  • 概要
  • ライセンス
  • サポートについて
  • Discord
• Media Processors
  • 概要
  • ライセンス
  • サポートについて
  • Discord

libwebrtc

• libwebrtc 音声処理
  • libwebrtcでの音声処理全般（前提知識）
  • ハイパスフィルタ
  • ノイズ抑制
  • モバイル版エコーキャンセル
  • オートゲインコントロール（AGC）
• libwebrtc リップシンク
  • 概要
  • 詳細
• libwebrtc ペーサー
  • 概要
  • 詳細
• libwebrtc ミキサーのストリーム数上限
  • 処理対象となる入力ストリーム数の上限値
  • 処理対象入力ストリームの選択方法
  • 処理対象入力ストリームが入れ替わった場合の挙動

その他

• Microsoft Edge の WebRTC について
• Apple Safari の WebRTC について
• nginx
• HLS 配信
• お勧めのカメラとスピーカーフォン
• オープンソースライセンス
• 古いリリースノート
• 古いドキュメント