2024.1.x から 2024.2.x への移行¶
概要¶
2024.1.x から 2024.2.x への移行について変更点や注意点をまとめています。
もし不明点がある場合はサポートまでお問い合わせください。
レガシー録画機能のデフォルト無効¶
レガシー録画機能を利用する sora.conf の legacy_recording をデフォルトで false に変更しました。
レガシー録画機能を利用する場合は true へ変更をお願いします。
レガシー録画機能は 2025 年 12 月リリース予定の Sora にて廃止しますので、録画機能(セッション単位)への以降をお願いします。
以降については レガシー録画機能から新しい録画機能 (セッション単位) への移行 をご確認ください。
セッション単位での同時接続数を制限する session-webhook-max_connections の追加¶
セッション単位での同時接続数を制限する session-webhook-max_connections を追加しました。
詳細については session-webhook-max_connections をご確認ください。
ウェブフックを送信を行わない場合でもログを出力するように変更¶
ウェブフックの送信を行わない (ignore) の設定した場合でも、以下のウェブフックはログを出力するように変更しました。
recording.started セッションウェブフック
session.updated セッションウェブフック
session.vanished セッションウェブフック
connection.failed イベントウェブフック
archive.started イベントウェブフック
recording.started イベントウェブフック
ただし、 sora_config-legacy_signaling_error を 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-webhook.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を追加しました
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-DESTROYEDAPI やライフタイムなどによるセッションの破棄
DISCONNECTED-APIAPI によるコネクションの破棄
DataChannel シグナリングのみ利用時に Sora から切断が発生した際の "type": "close" メッセージの送信¶
DataChannel シグナリングのみ利用時に Sora から切断が発生した際、
DataChannel を閉じる前に "type": "close" メッセージを送信する設定を追加しました。
sora.conf の data_channel_signaling_close_message を true に設定することで有効になります。
デフォルトは false です。
DataChannel が閉じられたのが正常な処理なのか、それとも何か問題が発生したのかを明確にするための仕組みです。
正常な場合の切断理由は以下の 3 つです。
LIFETIME-EXPIREDライフタイムによるコネクションの破棄
SESSION-DESTROYEDAPI やライフタイムなどによるセッションの破棄
DISCONNECTED-APIAPI によるコネクションの破棄
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 の通知タイミングを改善しました。
この設定は legacy_signaling_error を false にすることで有効になります。
シグナリング時のエラーが
sora.jsonlに出力されなくなりますシグナリング時のエラーが
signaling_error.jsonlに出力されるようになります認証失敗時のエラーが
sora.jsonlに出力されなくなります認証失敗時のエラーが
signaling_error.jsonlに出力されるようになりますイベントウェブフック connection.failed が認証失敗時には通知されなくなります
イベントウェブフック connection.failed が認証成功後に接続に失敗した時のみ通知されるようになります
認証失敗時のエラーログの改善¶
認証失敗時のログを 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 に出力するように変更しました。
エラーメッセージ変更内容¶
AUTHENTICATION-FAILURE
UNAUTHORIZED
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
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 へアップデートを行っていください。
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 にて廃止します。
移行に際する不明点などはサポートまでお問い合わせください。