How to Use FFmpeg VMAF to Analyze Video Quality

This guide explains how to measure perceptual video quality using Netflix's VMAF (Video Multi-Method Assessment Fusion) filter in FFmpeg. You will learn the prerequisites for running the filter, the basic syntax for comparing an encoded video against an original source, how to align mismatched resolutions or frame rates, and how to export the metrics to a log file for further analysis.

Prerequisites

To use VMAF, your FFmpeg build must be compiled with the --enable-libvmaf configuration flag. You can verify this by running:

ffmpeg -filters | grep libvmaf

If libvmaf appears in the output, your build supports VMAF analysis.

Basic VMAF Command

The libvmaf filter requires two inputs: the distorted (encoded) video and the reference (original) video. The reference video is generally mapped as the second input.

Run the following command in your terminal:

ffmpeg -i encoded.mp4 -i reference.mp4 -filter_complex "[0:v][1:v]libvmaf" -f null -
  • [0:v] refers to the video stream of the first input (encoded.mp4).
  • [1:v] refers to the video stream of the second input (reference.mp4).
  • -f null - processes the video frames without writing an output video file to disk.

Once processing finishes, FFmpeg displays the overall VMAF score (ranging from 0 to 100) directly in the terminal console.

Exporting Detailed Results to a File

To store per-frame scores and summary statistics, specify the model and configure logging parameters:

ffmpeg -i encoded.mp4 -i reference.mp4 -filter_complex "[0:v][1:v]libvmaf=log_fmt=json:log_path=vmaf_output.json:model=version=vmaf_v0.6.1" -f null -

Key options include:

  • log_fmt: Sets the output log format (json, xml, or csv).
  • log_path: Specifies the destination path for the generated log.
  • model: Specifies the VMAF model version or the path to a .json model file. Modern builds default to standard 1080p models (version=vmaf_v0.6.1), but 4K models (version=vmaf_4k_v0.6.1) are also supported.

Handling Mismatched Resolutions

VMAF requires both inputs to have the exact same dimensions. If the encoded video was downscaled (for example, from 1080p to 720p), you must upscale it back to the reference resolution using the bicubic scaler:

ffmpeg -i encoded_720p.mp4 -i reference_1080p.mp4 -filter_complex "[0:v]scale=1920:1080:flags=bicubic[distorted];[distorted][1:v]libvmaf=log_fmt=json:log_path=output.json" -f null -

Handling Frame Rate and Timestamp Sync

Both streams must be temporally synchronized. If the encoded video has a different frame rate or dropped frames, use the fps filter to normalize rates before computing the metric:

ffmpeg -i encoded.mp4 -i reference.mp4 -filter_complex "[0:v]fps=60[dist];[1:v]fps=60[ref];[dist][ref]libvmaf" -f null -

Interpreting VMAF Scores

  • 93–100: Perceptually transparent; the average viewer cannot distinguish the encoded video from the original.
  • 80–92: Good quality; minor artifacts are present upon close inspection, but acceptable for general streaming.
  • 70–79: Noticeable distortion and compression artifacts.
  • Below 70: Significant loss in visual fidelity.