README.md 5.1 KB
Newer Older
1
# `vmaf`
K
Kyle Swanson 已提交
2 3 4

`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`.

Z
Zhi Li 已提交
5 6 7 8
## Compile

Refer to the [`libvmaf`](../README.md) Compile section.

K
Kyle Swanson 已提交
9 10 11
## Usage

```
12
Usage: vmaf [options]
Z
Zhi Li 已提交
13

K
Kyle Swanson 已提交
14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41
Supported options:
 --reference/-r $path:      path to reference .y4m or .yuv
 --distorted/-d $path:      path to distorted .y4m or .yuv
 --width/-w $unsigned:      width
 --height/-h $unsigned:     height
 --pixel_format/-p: $string pixel format (420/422/444)
 --bitdepth/-b $unsigned:   bitdepth (8/10/12)
 --model/-m $params:        model parameters, colon ":" delimited
                            `path=` path to model file
                            `version=` built-in model version
                            `name=` optional name used in logs
 --output/-o $path:         path to output file
 --xml:                     write output file as XML (default)
 --json:                    write output file as JSON
 --csv:                     write output file as CSV
 --sub:                     write output file as subtitle
 --threads $unsigned:       number of threads to use
 --feature $string:         additional feature
 --cpumask: $bitmask        restrict permitted CPU instruction sets
 --subsample: $unsigned     compute scores only every N frames
 --quiet/-q:                disable FPS meter when run in a TTY
 --no_prediction/-n:        no prediction, extract features only
 --version/-v:              print version and exit
```

## Input
Pass 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`.

42
```shell script
K
Kyle Swanson 已提交
43 44 45 46 47 48 49 50 51 52
# .y4m
--reference ducks.y4m \
--distorted ducks_dist.y4m \

# .yuv
--reference ducks.yuv \
--distorted ducks_dist.yuv \
--width 1920 --height 1080 --pixel_format 420 --bitdepth 8 \
```

Z
Zhi Li 已提交
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.
K
Kyle Swanson 已提交
55

56
```shell script
K
Kyle Swanson 已提交
57 58 59 60 61 62 63 64 65 66
# built-in model
--model version=vmaf_v0.6.1

# model file
--model path=../model/vmaf_v0.6.1.json
```

## Additional Metrics
A number of addtional metrics are supported. Enable these metrics with the `--feature` flag.

67
```shell script
Z
Zhi Li 已提交
68
# psnr, psnr_hvs, ssim, ms-ssim, ciede
K
Kyle Swanson 已提交
69
--feature psnr \
Z
Zhi Li 已提交
70
--feature psnr_hvs \
K
Kyle Swanson 已提交
71 72
--feature float_ssim \
--feature float_ms_ssim
Z
Zhi Li 已提交
73
--feature ciede
K
Kyle Swanson 已提交
74 75 76 77
```

## Example

Z
Zhi Li 已提交
78
The 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.
K
Kyle Swanson 已提交
79

80
```shell script
81
./build/tools/vmaf \
K
Kyle Swanson 已提交
82 83 84 85 86 87 88
    --reference src01_hrc00_576x324.yuv \
    --distorted src01_hrc01_576x324.yuv \
    --width 576 --height 324 --pixel_format 420 --bitdepth 8 \
    --model version=vmaf_v0.6.1 \
    --feature psnr \
    --output output.xml
```
Z
Zhi Li 已提交
89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113
Example output:
```text
VMAF version e1d466c
48 frames ⠀⠩ 44.72 FPS
vmaf_v0.6.1: 76.668905
```
with `output.xml`:
```xml
<VMAF version="e1d466c">
  <params qualityWidth="576" qualityHeight="324" />
  <fyi fps="41.98" />
  <frames>
    <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" />
    ...
  </frames>
  <pooled_metrics>
    <metric name="integer_adm2" min="0.921008" max="0.962084" mean="0.934506" harmonic_mean="0.934463" />
    ...
    <metric name="psnr_y" min="29.640688" max="34.760779" mean="30.755064" harmonic_mean="30.727905" />
    <metric name="psnr_cb" min="38.019979" max="39.229987" mean="38.449441" harmonic_mean="38.447866" />
    <metric name="psnr_cr" min="40.649266" max="41.353846" mean="40.991910" harmonic_mean="40.991083" />
    <metric name="vmaf" min="71.176557" max="87.181420" mean="76.668905" harmonic_mean="76.510006" />
  </pooled_metrics>
  <aggregate_metrics />
</VMAF>
114
```