# `hisui vmaf` コマンド
`hisui vmaf` コマンドは、録画ファイルの合成結果のエンコード品質評価を行うためのコマンドです。
このコマンドは、参照映像（合成後の映像）と歪み映像（参照映像のエンコード後の映像）の
VMAF（Video Multimethod Assessment Fusion）スコアを計算し、映像品質の客観的な評価を提供します。
具体的には、以下の処理を行います：
1. **参照映像の生成**: 録画ファイルを合成してエンコード前の生映像を出力
2. **歪み映像の生成**: 同じ合成映像をエンコード後、再度デコードした映像を出力
3. **VMAF 評価**: 両映像を比較して VMAF スコアを算出
これにより、エンコード処理による映像品質の劣化を定量的に測定できます。
このコマンドは、主に [`hisui tune`](command_tune.md) コマンドと組み合わせて、
映像エンコードパラメーターの調整に利用することを想定しています。
## 依存パッケージ
このコマンドを利用するためには https://github.com/Netflix/vmaf が提供する `vmaf` コマンドがシステムにインストールされている必要があります。
macOS の場合には以下のようにして、依存パッケージがインストールできます。
```bash
brew install libvmaf
```
## 使用方法
```console
$ hisui vmaf -h
Recording Composition Tool Hisui
Usage: hisui ... vmaf [OPTIONS] ROOT_DIR
Example:
$ hisui vmaf /path/to/archive/RECORDING_ID/
Arguments:
ROOT_DIR 合成処理を行う際のルートディレクトリを指定します
Options:
-h, --help このヘルプメッセージを表示します ('--help' なら詳細、'-h' なら簡易版を表示)
--version バージョン番号を表示します
--verbose 警告未満のログメッセージも出力します
-l, --layout-file <PATH> 合成に使用するレイアウトファイルを指定します [env: HISUI_LAYOUT_FILE_PATH] [default: HISUI_REPO/layout-examples/vmaf-default.jsonc]
--reference-yuv-file <PATH> 参照映像のYUVファイルの出力先を指定します [default: ROOT_DIR/reference.yuv]
--distorted-yuv-file <PATH> 歪み映像のYUVファイルの出力先を指定します [default: ROOT_DIR/distorted.yuv]
--vmaf-output-file <PATH> vmaf コマンドの実行結果ファイルの出力先を指定します [default: ROOT_DIR/vmaf-output.jsonc]
--openh264 <PATH> OpenH264 の共有ライブラリのパスを指定します [env: HISUI_OPENH264_PATH]
-c, --max-cpu-cores <INTEGER> 合成処理を行うプロセスが使用するコア数の上限を指定します [env: HISUI_MAX_CPU_CORES]
-f, --frame-count <FRAMES> 変換するフレーム数を指定します [default: 1000]
--timeout <SECONDS> 処理のタイムアウト時間（秒）を指定します（超過した場合は失敗扱い）
```
## 実行例
```console
$ hisui vmaf /path/to/archive/RECORDING_ID/
# Compose for VMAF
[00:00:09] [########################################] 1000/1000 (0s)
=> done
# Run vmaf command
VMAF version 3.0.0
675 frames ⠄⠀ 201.74 FPS
vmaf_v0.6.1: 96.361266
=> done
{
"reference_yuv_file_path": "/path/to/archive/RECORDING_ID/reference.yuv",
"distorted_yuv_file_path": "/path/to/archive/RECORDING_ID/distorted.yuv",
"vmaf_output_file_path": "/path/to/archive/RECORDING_ID/vmaf-output.jsonc",
"encode_engine": "libvpx",
"width": 642,
"height": 240,
"frame_rate": 25,
"encoded_frame_count": 675,
"elapsed_seconds": 12.4662,
"vmaf_min": 82.988863,
"vmaf_max": 100,
"vmaf_mean": 96.361266,
"vmaf_harmonic_mean": 96.351588
}
```
VMAF スコアの解釈方法については、VMAF 自体の[公式リポジトリ](https://github.com/Netflix/vmaf)や、
そこから辿れるドキュメントを参照してください。
なお、`hisui vmaf` コマンド実行後に生成される YUV ファイル群は、
映像の生データを格納しているため、ファイルサイズが巨大になる可能性があります。
VMAF スコアの計算後には不要なファイルなので、削除しても問題ありません。