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 をご確認ください。
ウェブフック送信を行わない場合でもログを出力するように変更¶
ウェブフックの送信を行わない (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-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 の通知タイミングを改善しました。
シグナリング時のエラーが
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 にて廃止します。
移行に際する不明点などはサポートまでお問い合わせください。