Load Specific VMAF Models in FFmpeg
This article explains how to load specific Video Multi-Method
Assessment Fusion (VMAF) model files, such as 4K, 1080p, or mobile
models, into the FFmpeg libvmaf filter. You will learn the
exact syntax required for modern FFmpeg versions to locate, specify, and
run VMAF analyses using resolution-specific JSON model files.
Understanding VMAF Model Selection
VMAF requires different machine learning models depending on the resolution of the video being tested and the viewing distance. Using the wrong model will result in inaccurate quality scores.
- Standard/1080p Model
(
vmaf_v0.6.1.json): Designed for 1080p HDTV viewing (viewing distance of 3H). - 4K Model (
vmaf_4k_v0.6.1.json): Designed for 4K UHDTV viewing (viewing distance of 1.5H). - NEG Model (
vmaf_v0.6.1neg.json): No Enhancement Gain model, ideal for measuring pure compression artifacts.
Modern FFmpeg Syntax (libvmaf v2.x and newer)
Modern versions of FFmpeg use JSON-based model files. To load a
specific model, you must use the model option inside the
libvmaf filter graph and define the path
key.
Loading the 1080p Model
To load the standard 1080p VMAF model, point the path
variable to your local JSON file:
ffmpeg -i distorted.mp4 -i reference.mp4 -filter_complex "[0:v][1:v]libvmaf=model='path=/path/to/vmaf_v0.6.1.json'" -f null -Loading the 4K Model
To load the 4K model for ultra-high-definition video quality assessment, change the path to point to the 4K JSON file:
ffmpeg -i distorted_4k.mp4 -i reference_4k.mp4 -filter_complex "[0:v][1:v]libvmaf=model='path=/path/to/vmaf_4k_v0.6.1.json'" -f null -Adding Custom Model Parameters
If you need to pass additional parameters to the model (such as
enabling the phone model or disabling certain features), you can append
them inside the model block using colons (:)
or semicolons depending on your shell’s escaping rules.
For example, to load a model and enable feature extractors:
ffmpeg -i distorted.mp4 -i reference.mp4 -filter_complex "[0:v][1:v]libvmaf=model='path=/path/to/vmaf_v0.6.1.json:enable_transform=true'" -f null -Legacy FFmpeg Syntax (Older .pkl Files)
If you are using an older version of FFmpeg that relies on deprecated
.pkl model files, you must use the model_path
option instead of model:
ffmpeg -i distorted.mp4 -i reference.mp4 -filter_complex "[0:v][1:v]libvmaf=model_path=/path/to/vmaf_v0.6.1.pkl" -f null -Note: It is highly recommended to upgrade FFmpeg and libvmaf to use the newer JSON format, as PKL support has been phased out in modern builds.