README.md
1# `vmaf`
2
3`vmaf` is a command line tool which supports VMAF feature extraction and prediction. The tool takes a pair of input videos as well as a trained VMAF model and writes an output log containing per-frame and pooled VMAF scores. Input videos can be either `.y4m` or `.yuv` and output logs are available in a number of formats: `.xml`, `.json`, `.csv`, `.sub`.
4
5## Compile
6
7Refer to the [`libvmaf`](../README.md) Compile section.
8
9## Usage
10
11```
12Usage: vmaf [options]
13
14Supported options:
15 --reference/-r $path: path to reference .y4m or .yuv
16 --distorted/-d $path: path to distorted .y4m or .yuv
17 --width/-w $unsigned: width
18 --height/-h $unsigned: height
19 --pixel_format/-p: $string pixel format (420/422/444)
20 --bitdepth/-b $unsigned: bitdepth (8/10/12)
21 --model/-m $params: model parameters, colon ":" delimited
22 `path=` path to model file
23 `version=` built-in model version
24 `name=` optional name used in logs
25 --output/-o $path: path to output file
26 --xml: write output file as XML (default)
27 --json: write output file as JSON
28 --csv: write output file as CSV
29 --sub: write output file as subtitle
30 --threads $unsigned: number of threads to use
31 --feature $string: additional feature
32 --cpumask: $bitmask restrict permitted CPU instruction sets
33 --subsample: $unsigned compute scores only every N frames
34 --quiet/-q: disable FPS meter when run in a TTY
35 --no_prediction/-n: no prediction, extract features only
36 --version/-v: print version and exit
37```
38
39## Input
40Pass your reference/distorted pair of videos to the tool using the `--reference` and `--distorted` flags. If your inputs are `.y4m` this is all that is required. If your inputs are raw `.yuv` the following parameters are also required: `--width`, `--height`, `--pixel_format`, `--bitdepth`.
41
42```shell script
43# .y4m
44--reference ducks.y4m \
45--distorted ducks_dist.y4m \
46
47# .yuv
48--reference ducks.yuv \
49--distorted ducks_dist.yuv \
50--width 1920 --height 1080 --pixel_format 420 --bitdepth 8 \
51```
52
53## VMAF Models
54`vmaf` now has a number of VMAF models built-in. This means that no external VMAF model files are required, and the models are read from the binary itself. Previous versions of `libvmaf` required a `.pkl` format model file. Since v2.0.0, these `.pkl` model files have been deprecated in favor of `.json` model files. If you have a previously trained `.pkl` model you would like to convert to `.json`, the following [Python conversion script](../../python/vmaf/script/convert_model_from_pkl_to_json.py) is available. If the `--model` parameter is not passed at all, `version=vmaf_v0.6.1` is enabled by default.
55
56```shell script
57# built-in model
58--model version=vmaf_v0.6.1
59
60# model file
61--model path=../model/vmaf_v0.6.1.json
62```
63
64## Additional Metrics
65A number of addtional metrics are supported. Enable these metrics with the `--feature` flag.
66
67```shell script
68# psnr, psnr_hvs, ssim, ms-ssim, ciede
69--feature psnr \
70--feature psnr_hvs \
71--feature float_ssim \
72--feature float_ms_ssim
73--feature ciede
74--feature cambi
75```
76
77## Example
78
79The following example shows a comparison using a pair of yuv inputs ([`src01_hrc00_576x324.yuv`](https://github.com/Netflix/vmaf_resource/blob/master/python/test/resource/yuv/src01_hrc00_576x324.yuv), [`src01_hrc01_576x324.yuv`](https://github.com/Netflix/vmaf_resource/blob/master/python/test/resource/yuv/src01_hrc01_576x324.yuv)). In addition to VMAF, the `psnr` metric is also computed and logged.
80
81```shell script
82./build/tools/vmaf \
83 --reference src01_hrc00_576x324.yuv \
84 --distorted src01_hrc01_576x324.yuv \
85 --width 576 --height 324 --pixel_format 420 --bitdepth 8 \
86 --model version=vmaf_v0.6.1 \
87 --feature psnr \
88 --output output.xml
89```
90Example output:
91```text
92VMAF version e1d466c
9348 frames ⠀⠩ 44.72 FPS
94vmaf_v0.6.1: 76.668905
95```
96with `output.xml`:
97```xml
98<VMAF version="e1d466c">
99 <params qualityWidth="576" qualityHeight="324" />
100 <fyi fps="41.98" />
101 <frames>
102 <frame frameNum="0" integer_adm2="0.962084" integer_adm_scale0="0.946338" integer_adm_scale1="0.939006" integer_adm_scale2="0.957474" integer_adm_scale3="0.980887" integer_motion2="0.000000" integer_motion="0.000000" integer_vif_scale0="0.505712" integer_vif_scale1="0.879061" integer_vif_scale2="0.937873" integer_vif_scale3="0.964301" psnr_y="34.760779" psnr_cb="39.229987" psnr_cr="41.349703" vmaf="83.856285" />
103 ...
104 </frames>
105 <pooled_metrics>
106 <metric name="integer_adm2" min="0.921008" max="0.962084" mean="0.934506" harmonic_mean="0.934463" />
107 ...
108 <metric name="psnr_y" min="29.640688" max="34.760779" mean="30.755064" harmonic_mean="30.727905" />
109 <metric name="psnr_cb" min="38.019979" max="39.229987" mean="38.449441" harmonic_mean="38.447866" />
110 <metric name="psnr_cr" min="40.649266" max="41.353846" mean="40.991910" harmonic_mean="40.991083" />
111 <metric name="vmaf" min="71.176557" max="87.181420" mean="76.668905" harmonic_mean="76.510006" />
112 </pooled_metrics>
113 <aggregate_metrics />
114</VMAF>
115```
116