# レガシー版 Hisui からのマイグレーションガイド
このドキュメントは [C++ で実装されている 2024.1.1 以前の Hisui][hisui-legacy] から Rust で
書き直された 2025.1.0 の Hisui への移行方法や両者の相違点についてを説明するものです。
このドキュメントでは、前者と後者をそれぞれ「レガシー Hisui」および「新 Hisui」と呼称します。
新 Hisui は実装言語が変更されただけではなく、さまざまな点でレガシー Hisui とは異なっています。
互換性は可能な限り維持されてはいますが、レガシー Hisui のユーザーは
新 Hisui に切り替える前に、このドキュメントに一通り目を通すことをおすすめします。
[hisui-legacy]: https://github.com/shiguredo/hisui-legacy
## 注意
このガイドは Hisui 2025.2.0 時点の内容をもとに記載されています。
2025.2.0 以降の Hisui の変更点については [CHANGES.md](../CHANGES.md) ファイルをご参照ください。
## **[2025.1.x のみ]** `hisui legacy` サブコマンドを用いた移行方法
新 Hisui は、サブコマンド方式のコマンドラインインタフェースを採用しています。
そのため、レガシー Hisui とは異なり、コマンドラインの第一引数はサブコマンドの名前となっています。
新 Hisui の 2025.1.x では、レガシー Hisui との互換性維持を目的とした `hisui legacy` サブコマンドが提供されています。
レガシー Hisui からの移行コストをできるだけ抑えたい場合には [Hisui の 2025.1.x のマイグレーションガイド](https://github.com/shiguredo/hisui/blob/support/2025.1/docs/migrate_hisui_legacy.md) を参考に `hisui legacy` サブコマンドをお試しください。
ただし `hisui legacy` サブコマンドは Hisui 2025.2.0 で廃止されているため、
基本的には、次に説明する `hisui compose` サブコマンドへの移行を推奨しています。
## `hisui compose` サブコマンドへの移行方法
[`hisui compose`](./command_compose.md) サブコマンドは「レガシー Hisuiでのレイアウトファイルを指定した合成」を中心に据えて、
その分、コマンドライン引数をシンプルにしたものと考えることができます。
レイアウトファイルの互換性は維持されているので、レガシー Hisui ですでにレイアウトファイルを使って合成を行っていた場合には、
基本的には、次のような単純な修正で移行できます。
```bash
# レガシー Hisui
hisui --layout /path/to/layout.json
# 新 Hisui
# => `hisui` の直後に `compose` を追加する
# => オプション名を `--layout` から `--layout-file` に変更する
# => レポートファイルなどが配置されているディレクトリを指定する
hisui compose --layout-file /path/to/layout.json /path/to/合成対象の録画ファイルが配置されているディレクトリ/
```
`hisui compose` サブコマンドで `--layout-file` オプションを省略した場合にはデフォルトレイアウトでの合成が行われます。
デフォルトレイアウトは、レガシー Hisui でレポートファイルを指定した場合のレイアウトと同じになっているため、
レガシー Hisui でレポートファイル指定で合成を行っていた場合には、
次のように `--layout-file` オプションの指定を省略することで、同じ結果が得られます。
```bash
# レガシー Hisui
hisui -f /path/to/report.json ...その他の引数...
# 新 Hisui
# => `hisui` の直後に `compose` を追加する
# => レポートファイルなどが配置されているディレクトリを指定する
# => `--layout-file` オプションは指定しない
hisui compose /path/to/合成対象の録画ファイルが配置されているディレクトリ/
```
なお `hisui compose` サブコマンドでは、レガシー Hisui とは異なり、
エンコードコーデックやエンコードパラメーターなどを、コマンドライン引数ではなくレイアウトファイルの中で指定するようになっています。
そのため、もしレガシー Hisui でそれらを指定していた場合には移行時に注意が必要となります。
レイアウト機能自体の詳細については [レイアウト機能のドキュメント](./layout.md) をご参照ください。
---
これ以降では、レガシー Hisui と新 Hisui の相違点について説明します。
## 相違点: 廃止された機能
本セクションでは、新 Hisui では廃止されて使えなくなった機能について説明します。
### 実験的なコマンドライン引数は廃止
レガシー Hisui で実験的な扱いであったり、ドキュメントに記載がなかったりした引数は、新 Hisui では完全に廃止されました。
### 合成結果の WebM 形式での出力は廃止
出力形式としては MP4 のみのサポートとなりました。
レイアウトファイルで `format` が指定されても無視されます。
### OneVPL を使った H.264 エンコードおよびデコードの廃止
OneVPL 対応は廃止されました。
Linux 環境で、H.264 のエンコードおよびデコードを行うためには OpenH264 ないし NVIDIA Video Codec が必須となります。
なお macOS 環境では Apple Video Toolbox を使った H.264 ストリーム処理をサポートしています。
### `--video-codec-engines` コマンドライン引数は廃止
利用可能なコーデック一覧を取得する方法としては、代わりに [list-codecs](./command_list_codecs.md) サブコマンドが導入されました。
## 相違点: 挙動が変わった機能
本セクションでは、新 Hisui での挙動の変更点について説明します。
なお基本的には、細かい調整や修正が主であって、普通に使っている範囲では、これらの変更の影響を受けることは少ないと思われます。
### MP4 ファイル出力が常に faststart 方式で行われるようになった
faststart 方式は「MP4 の再生に必要なメタデータをファイルの先頭付近に配置することで再生開始までの時間を短くする」というものです。
新 Hisui では、常にこの方式を採用し、またその際に（レガシー Hisui と異なり）一時ファイルを利用しなくなりました。
### AV1 デコーダーの変更
AV1 ストリーム用のデコーダーが SVT-AV1 から dav1d に変更されました。
### ログメッセージの内容の変更
ログメッセージの出力内容には互換性がありません。
### プログレスバーの内容の変更
プログレスバーの出力内容には互換性がありません。
レガシー Hisui ではプログレスバーの右にパーセントと経過時間が表示されていましたが、
新 Hisui ではより詳細な情報が表示されるようになりました。
プログレスバーの左側には経過時間と予想完了時間を示すようになり、右側には合成対象の全体の出力時間に対する処理が完了した割合が表示されるようになりました。
レガシー Hisui
`[============================================================] 100% 21.078s`
新 Hisui
`[00:00:26 (ETA: 0s)] [########################################] complete 100% of 135s total output duration`
### 音声のみ合成でのデフォルト出力ファイルの拡張子の変更
レガシー Hisui で出力ファイルの名前を省略した場合は、
「音声のみの場合は `.mp4a`」で「それ以外の場合は `.mp4`」という拡張子になっていました。
新 Hisui では、デフォルト出力ファイルの拡張子は常に `.mp4` となります。
### デフォルトエンコードパラメーターの変更
後述するように、新 Hisui ではエンコードパラメーターを以前よりも細かく指定できるようになりました。
それに伴ってデフォルトで使用されるエンコードパラメーターも調整されており、レガシー Hisui とは異なるものとなっています。
レガシー Hisui でのデフォルトエンコードパラメーターは明文化されているものではなかったので、ここで詳細に変更点を列挙することはしませんが、
新 Hisui でのデフォルトパラメーターについては [layout-examples/compose-default.jsonc](../layout-examples/compose-default.jsonc) ファイルをご参照ください。
### レイアウトファイルでの解像度指定の制限が少し緩和された
レガシー Hisui では「4 の倍数」という制限だったのが、新 Hisui では「2 の倍数」と緩和されました。
### レイアウトファイルで、ひとつのリージョンの中で同じソースが複数回指定された場合の挙動の変更
レガシー Hisui では、別々のソースとして扱われますが、新 Hisui では同じリージョン内での重複したソースはひとつにまとめられます。
### レイアウトファイルでのメディアファイルの探索方法の変更
レガシー Hisui では、`archive-*.json` の中身に記載されているパスの情報などを考慮して対応するメディアファイルのパスを決定していました。
新 Hisui では、`archive-*.json` の中身は考慮せずに、単純に、指定された `archive-*.json` のパスの
拡張子を（`.mp4` ないし `.webm` に）置換することでメディアファイルのパスを決定しています。
### レイアウトファイル使用時の、セルへの映像ソース割り当ての際に、ソースの指定順を常に考慮しなくなった
基本的には、レガシー Hisui でも新 Hisui でも、映像ソースはその開始時刻の順番でセルに割り当てられます。
そのため、利用可能なセルの数に限りがある場合には、設定によっては、開始時刻が後ろのソースが合成結果から除外されるようになります。
ただし、レガシー Hisui では
「`max_columns` と `max_rows` の両方が指定されていて、かつ、映像ソースの数が `max_columns * max_rows` よりも多い」
という条件が成立した場合には「開始時刻順」ではなく、「ソースの指定順」で
採用するソースが選択されるようになっています（つまり、セル数に限りがある場合には、リストの後ろのソースが除外される）。
新 Hisui ではこのような特別扱いはなく、ソースの指定順の影響は受けません。
### レイアウトファイルでの、ソースのワイルドカード指定の際の制限が少し緩和された
レガシー Hisui では「ワイルドカードを使用する場合には Sora の録画データと同じディレクトリにレイアウトファイルがあること」という制限がありました。
新 Hisui では、この制限は緩和され「ROOT_DIR 引数で指定したディレクトリを基点として、その子孫ディレクトリにあるファイルが参照可能」というようになりました。
### レイアウトファイルで `resolution` の指定が必須ではなくなった
省略された場合には、リージョンのサイズから自動計算されます。
なお「`resolution` が未指定」かつ「リージョンのサイズが明示的に指定されていない場合」には、全体の解像度の値が一意に定まらないためエラーとなります。
## 相違点: 追加された機能
本セクションでは、新 Hisui で新しく追加された機能を紹介します。
### 分割録画対応
Sora の分割録画機能を使って作成された録画ファイルの合成ができるようになりました。
`hisui compose` で指定するレイアウトファイルの中で、`split-archive-*.json` のようにソースリストを指定すれば、
ワイルドカードに一致したソース群の中で、コネクション ID が同じものは、ひとつのソースとして連結して扱われます。
### MP4 ファイル入力に対応
Sora の MP4 録画機能で録画されたファイルを合成できるようになりました。
### macOS に対応
新 Hisui は macOS でのビルドおよび実行に対応しています。
### NVIDIA Video Codec に対応
NVIDIA Video Codec を利用した H.264 / H.265 / AV1 のエンコードおよび H.264 / H.265 / VP8 / VP9 / AV1 デコードに対応しています。
### H.265 ストリームのデコードおよびエンコードに対応（macOS のみ）
macOS では Apple Video Toolbox を、Linux では NVIDIA Video Codec を使って H.265 ストリームを扱えるようになりました。
### レイアウトファイルへの追加項目
新 Hisui では、レガシー Hisui に比べてレイアウトファイルで指定できる項目が増えています。
追加項目は以下の通りです。
- audio_codec
- video_codec
- audio_bitrate
- video_bitrate
- frame_rate
- libvpx_vp8_encode_params
- libvpx_vp9_encode_params
- nvcodec_h264_decode_params
- nvcodec_h265_decode_params
- nvcodec_vp8_decode_params
- nvcodec_vp9_decode_params
- nvcodec_av1_decode_params
- nvcodec_h264_encode_params
- nvcodec_h265_encode_params
- nvcodec_av1_encode_params
- openh264_encode_params
- svt_av1_encode_params
- video_toolbox_h264_encode_params
- video_toolbox_h265_encode_params
- video_layout.リージョン名.cell_width
- video_layout.リージョン名.cell_height
- video_layout.リージョン名.border_pixels
各項目についての説明は [レイアウトの仕様ドキュメント](./layout_spec.md) をご参照ください。
### エンコードパラメーターの細かい指定と自動調整に対応
新 Hisui では、レガシー Hisui に比べて、合成結果のエンコードの際のパラメーターをより細かく指定できるようになっています。
詳細は [エンコードパラメーター指定のドキュメント](./layout_encode_params.md) をご参照ください。
また [`hisui tune`](./command_tune.md) サブコマンドを使うことで、用途に合ったエンコードパラメーターを、ある程度自動で探索することもできます。
### Hisui 自体のマルチスレッド実行に対応
新 Hisui では `--thread-count` 引数を指定することでデコードや画像合成、エンコードなどの処理を別々のスレッドで実行することができます
(デフォルトではレガシー Hisui と同様にシングルスレッドで実行されます）。
なお、この引数が影響するのはあくまでも Hisui 自体が使用するワーカースレッドのみとなります。
映像エンコーダーは、内部的にマルチスレッドでの処理に対応していることが多いですが、
それらの挙動の制御は `libvpx_vp8_encode_params` などの、各エンコーダー固有のオプション指定を通して行ってください。
### 統計情報の出力に対応
新 Hisui では `--stats-file` 引数を指定することで、
合成処理中に収集された統計情報をファイルに出力することができます。