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

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

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

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

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

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

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

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

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

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

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

## 変更点

### API の変更

- レガシー録画で利用していた `20161101.StartRecording` API と `20161101.StopRecording` API はバージョンを `20231220` に変更してください
- レガシー録画で利用していた [StartRecording](OBSOLETE_API_LEGACY_RECORDING.html#c5b527) API は [StartRecording](API_RECORDING.html#c5b527) API を利用してください
- レガシー録画で利用していた [StopRecording](OBSOLETE_API_LEGACY_RECORDING.html#fd0de5) API は [StopRecording](API_RECORDING.html#fd0de5) API を利用してください
- レガシー録画で利用していた [GetStartedRecording](OBSOLETE_API_LEGACY_RECORDING.html#8095d0) API は [GetSession](API_SESSION.html#427a59) API を利用してください
- レガシー録画で利用していた [ListStartedRecording](OBSOLETE_API_LEGACY_RECORDING.html#838360) API は [ListSessions](API_SESSION.html#748f19) API を利用してください
- レガシー録画で利用していた [ListArchiving](OBSOLETE_API_LEGACY_RECORDING.html#d4ba61) 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 では新しい録画機能（セッション単位）といった利用ができます。