# 2024.1.x から 2024.2.x への移行 ## 概要 2024.1.x から 2024.2.x への移行について変更点や注意点をまとめています。 もし不明点がある場合はサポートまでお問い合わせください。 ## レガシー録画機能のデフォルト無効 レガシー録画機能を利用する `sora.conf` の [legacy_recording](SORA_CONF.html#632f06) をデフォルトで `false` に変更しました。 レガシー録画機能を利用する場合は `true` へ変更をお願いします。 レガシー録画機能は 2025 年 12 月リリース予定の Sora にて廃止しますので、録画機能(セッション単位)への移行をお願いします。 以降については [レガシー録画機能から新しい録画機能 (セッション単位) への移行](LEGACY_RECORDING_TO_RECORDING.html) をご確認ください。 ## セッション単位での同時接続数を制限する [trial_max_connections](SESSION_WEBHOOK.html#48346d) の追加 セッション単位での同時接続数を制限する [trial_max_connections](SESSION_WEBHOOK.html#48346d) を追加しました。 詳細については [trial_max_connections](SESSION_WEBHOOK.html#48346d) をご確認ください。 ## JSON Lines 形式のログ出力に対してエスケープ処理を行わないよう変更 JSON Lines 形式のログ出力に対してエスケープ処理を行わないよう変更しました。 ## ウェブフック送信を行わない場合でもログを出力するように変更 ウェブフックの送信を行わない (ignore) の設定した場合でも、以下のウェブフックはログを出力するように変更しました。 - [recording.started](SESSION_WEBHOOK.html#9b5c58) セッションウェブフック - [session.updated](SESSION_WEBHOOK.html#2a5b1b) セッションウェブフック - [session.vanished](SESSION_WEBHOOK.html#9f1b17) セッションウェブフック - [connection.failed](EVENT_WEBHOOK.html#5266b6) イベントウェブフック - [archive.started](EVENT_WEBHOOK.html#462c97) イベントウェブフック - [recording.started](EVENT_WEBHOOK.html#9b5c58) イベントウェブフック ただし、 [legacy_signaling_error](SORA_CONF.html#88aa33) が `true` かつ [ignore_connection_failed_webhook](SORA_CONF.html#45096a) が `true` の場合は、 [connection.failed](EVENT_WEBHOOK.html#5266b6) イベントウェブフックのログは出力されません。 ## 既存のセッションの同時接続数が `0` の際に、このセッションと異なる `multistream` または `spotlight` 設定の新規接続が来た場合の挙動の変更 Sora にてセッションウェブフックの [multistream と spotlight が既存セッションと異なる場合の挙動](SESSION_WEBHOOK.html#c294e7) を変更します。 今までは既存セッションの同時接続数が `0` の場合に、 `multistream` または `spotlight` の設定が、 既存セッションと異なる新規接続が来た場合、 既存セッションを破棄し、新規セッションで接続できるようになっていましたが、 既存セッションを破棄せずにエラーになるように変更しました。 ## プレイアウト遅延機能が配信側から視聴側への適用に変更 Sora 2024.1.x まで、プレイアウト機能は配信側にのみ適用されていましたが、 2024.2.x からは視聴側のみに適用されるようになりました。 詳細は [プレイアウト遅延](PLAYOUT_DELAY.html) をご確認ください。 ## 録画の出力ファイルが MP4 形式に対応しました [StartRecording](API_RECORDING.html#c5b527) API で `format` を `mp4` に指定するか、 [session.created](SESSION_WEBHOOK.html#1d1984) の払い出しで `recording_format` を `mp4` に指定することで、 MP4 形式で録画の出力ファイルが作成されます。 また、 `sora.conf` の [default_recording_format](SORA_CONF.html#f9fa7d) を `mp4` に設定することで、 録画の出力ファイルのデフォルトが MP4 形式になります。 - 2025 年 12 月リリース予定の Sora では [default_recording_format](SORA_CONF.html#f9fa7d) のデフォルトが `webm` から `mp4` になります ### ウェブフック - [session.updated](SESSION_WEBHOOK.html#2a5b1b) や [session.destroyed](SESSION_WEBHOOK.html#ccb165) の `recording` の `format` を追加しました - [recording.started](SESSION_WEBHOOK.html#9b5c58) に `format` を追加しました ### キーフレーム要求間隔の変更 MP4 形式での出力時に、Sora からクライアントへのキーフレーム要求 (PLI) の間隔を [default_recording_mp4_pli_interval](SORA_CONF.html#874e5b) で指定できるようになりました。 WebM 形式ではキーフレームの間隔が最大でも 31 秒までという制約がありましたが、 MP4 形式ではこの制約がなくなりました。 詳細は [MP4 形式のキーフレーム要求間隔の変更](RECORDING.html#1640d0) をご確認ください。 ## 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](SORA_CONF.html#058a1e) を `true` に設定することで有効になります。 デフォルトは `false` です。 DataChannel が閉じられたのが正常な処理なのか、それとも何か問題が発生したのかを明確にするための仕組みです。 正常な場合の切断理由は以下の 3 つです。 - `LIFETIME-EXPIRED`- ライフタイムによるコネクションの破棄 - `SESSION-DESTROYED`- API やライフタイムなどによるセッションの破棄 - `DISCONNECTED-API`- API によるコネクションの破棄 ### data_channel_signaling_close_message = false ```mermaid sequenceDiagram participant C as Client participant S as Sora participant A as App note over C,S: WebRTC 確立 S-)C: "type": "switched"
"ignore_websocket_disconnect": true A->>+S: Disconnect API S->>-A: 200 OK S->>C: DataChannels Close ``` ### data_channel_signaling_close_message = true ```mermaid sequenceDiagram participant C as Client participant S as Sora participant A as App note over C,S: WebRTC 確立 S-)C: "type": "switched"
"ignore_websocket_disconnect": true A->>+S: Disconnect API S->>-A: 200 OK S->>C: "type": "close" over DataChannel
1000
"DISCONNECT-API" S->>C: DataChannels Close ``` ### "type": "close" メッセージの正常終了時の `reason` について - 正常な切断では `code` は `1000` で、 `reason` には切断理由が入ります - 異常による切断では `code` は `4490` で、 `reason` には切断理由がはいります ## Sora からの正常切断時の `reason` の値を空文字にする設定 [signaling_normal_close_reason](SORA_CONF.html#4486a4) はデフォルトで `true` で、切断理由が入りますが、 `false` にすることで切断理由を空文字を入れるようになります。 ## シグナリングエラー時の改善 シグナリングエラー時のログの出力先やウェブフック `connection.failed` の通知タイミングを改善しました。 - シグナリング時のエラーが `sora.jsonl` に出力されなくなりました - シグナリング時のエラーが `signaling_error.jsonl` に出力されるようになりました - 認証失敗時のエラーが `sora.jsonl` に出力されなくなりました - 認証失敗時のエラーが `signaling_error.jsonl` に出力されるようになりました - イベントウェブフック [connection.failed](EVENT_WEBHOOK.html#5266b6) が認証失敗時には通知されなくなりました - イベントウェブフック [connection.failed](EVENT_WEBHOOK.html#5266b6) が認証成功後に接続に失敗した時のみ通知されるようになりました この設定は [legacy_signaling_error](SORA_CONF.html#88aa33) を `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](SORA_CONF.html#88aa33) を `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_CONNECTION.html#716b40) API に合わせた変更になります。 ## JoinCluster API を廃止しました 今後は全く同じ機能を提供している [RegisterClusterNode](API_CLUSTER.html#09ed96) API をご利用ください。 ## ListClusterNodes API の include_all_known_nodes を廃止しました [ListClusterNodes](API_CLUSTER.html#a70901) API の `include_all_known_nodes` を廃止しました 常にクラスターに登録されている全てのノード情報を返すようになりました。 詳しくは [ListClusterNodes API の include_all_known_nodes の廃止](OBSOLETE.html#bd63a0) をご確認ください。 ## sora.conf の legacy_auth_webhook_log を廃止しました 移行用の設定 `sora.conf` の `legacy_auth_webhook_log` を廃止しました。 認証ウェブフックのエラーログは `auth_webhook_error.jsonl` に出力されるようになりました。 詳しくは [sora.conf の legacy_auth_webhook_log の廃止](OBSOLETE.html#c7a1d5) をご確認ください。 ## 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 の廃止](OBSOLETE.html#c1c1cd) をご確認ください。 ## [signaling_forwarding_filter](SORA_CONF.html#d15a40) を非推奨にしました 複数の転送フィルターを指定できる [signaling_forwarding_filters](SORA_CONF.html#bf0e30) を追加したことから、 [signaling_forwarding_filter](SORA_CONF.html#d15a40) を非推奨にしました。 2025 年 12 月リリース予定の Sora にて廃止します。 移行に際する不明点などはサポートまでお問い合わせください。 ## 認証成功時とセッション生成時の払い出し `forwarding_filter` を非推奨にしました 複数の転送フィルターを指定できる `forwarding_filters` を追加したことから、 認証成功時とセッション生成時の払い出し `forwarding_filter` を非推奨にしました。 2025 年 12 月リリース予定の Sora にて廃止します。 移行に際する不明点などはサポートまでお問い合わせください。 ## [session.vanished](MODE.html#9f1b17) ウェブフックを非推奨にしました [Sora Exporter](SORA_EXPORTER.html) を利用する事で、より柔軟なセッションの監視ができることから、 [session.vanished](MODE.html#9f1b17) ウェブフックを非推奨にしました。 2025 年 6 月リリース予定の Sora にて廃止します。 移行に際する不明点などはサポートまでお問い合わせください。 ## RTP ストリーム停止/再開 API を非推奨にしました RTP ストリーム停止/再開 API は [転送フィルター](FORWARDING_FILTER.html) により同等の機能が提供でき、 重複機能となるため非推奨にしました。 今後は [転送フィルター](FORWARDING_FILTER.html) をご利用ください。 2025 年 12 月リリース予定の Sora にて廃止します。 移行に際する不明点などはサポートまでお問い合わせください。