How to Load Specific VMAF Models in FFmpeg

Evaluating video quality with FFmpeg's libvmaf filter often requires switching between resolution-specific machine learning models, such as the standard 1080p model or the dedicated 4K model. This guide explains how to pass specific model files into FFmpeg using modern JSON-based VMAF syntax, configure resolution matching, and export your measurement logs correctly.

Modern VMAF Syntax (libvmaf v2.x+)

Recent versions of FFmpeg and libvmaf use JSON-formatted model files rather than deprecated .pkl files. You specify the target model using the model option inside the libvmaf filter.

The syntax requires passing the path key to the model configuration:

ffmpeg -i distorted.mp4 -i reference.mp4 -lavfi "libvmaf=model='path=/path/to/vmaf_4k_v0.6.1.json'" -f null -

Loading 1080p vs. 4K Models

The Video Multi-Method Assessment Fusion (VMAF) framework provides specific models tuned for the viewing distance and resolution of the target display:

  • 1080p Default Model (vmaf_v0.6.1.json): Designed for standard 1080p viewing conditions (a 1080p display viewed from a distance of 3x screen height).
  • 4K Model (vmaf_4k_v0.6.1.json): Tuned for 4K displays viewed from a distance of 1.5x screen height, which makes it more sensitive to fine artifacts.

1080p Evaluation Example

ffmpeg -i distorted_1080p.mp4 -i reference_1080p.mp4 -lavfi \
"[0:v][1:v]libvmaf=model='path=/usr/local/share/model/vmaf_v0.6.1.json':log_fmt=json:log_path=vmaf_1080p.json" \
-f null -

4K Evaluation Example

ffmpeg -i distorted_4k.mp4 -i reference_4k.mp4 -lavfi \
"[0:v][1:v]libvmaf=model='path=/usr/local/share/model/vmaf_4k_v0.6.1.json':log_fmt=json:log_path=vmaf_4k.json" \
-f null -

Built-in Model Versioning (Alternative Syntax)

If your libvmaf installation has models bundled directly into the library build, you can specify the version string instead of an absolute filesystem path:

ffmpeg -i distorted.mp4 -i reference.mp4 -lavfi \
"libvmaf=model='version=vmaf_4k_v0.6.1'" -f null -

Important Resolution and Scaling Rules

  1. Input Synchronization: The libvmaf filter requires both the distorted and reference streams to have the exact same resolution and pixel format.
  2. Model Match: For accurate scores, scale videos to the resolution that matches the model prior to analysis. If comparing a 1080p encode against a 4K source using the 4K model, upscale the 1080p encode to 4K inside the filtergraph:
ffmpeg -i distorted_1080p.mp4 -i reference_4k.mp4 -lavfi \
"[0:v]scale=3840:2160:flags=bicubic[dist];[dist][1:v]libvmaf=model='path=vmaf_4k_v0.6.1.json'" \
-f null -