How to Use FFmpeg VMAF to Analyze Video Quality

This article provides a practical guide on how to use the Video Multi-Method Assessment Fusion (VMAF) metric within FFmpeg to measure video quality. Developed by Netflix, VMAF predicts subjective video quality by comparing a distorted (compressed) video against its original reference video. You will learn the system prerequisites, the core FFmpeg command syntax, and how to export and interpret VMAF scores to optimize your video encoding workflows.

Prerequisites

To use VMAF in FFmpeg, you need: 1. FFmpeg compiled with VMAF support: Ensure your FFmpeg build includes the --enable-libvmaf configuration flag. You can verify this by running ffmpeg -filters | grep libvmaf in your terminal. 2. VMAF Model Files: VMAF relies on trained machine learning models (usually in .json format) to calculate scores. You can download these models (such as vmaf_v0.6.1.json for 1080p desktop viewing) from the official Netflix VMAF GitHub repository.

Basic Command Syntax

The VMAF filter requires two video inputs: the processed (distorted) video and the original (reference) video. In the FFmpeg filtergraph, the distorted video is passed as the first input, and the reference video is passed as the second.

Here is the basic command to calculate VMAF:

ffmpeg -i distorted.mp4 -i reference.mp4 -filter_complex "[0:v][1:v]libvmaf=model_path=vmaf_v0.6.1.json" -f null -

• -i distorted.mp4: The first input (index 0), which is the compressed video.
• -i reference.mp4: The second input (index 1), which is the uncompressed source video.
• -filter_complex "[0:v][1:v]libvmaf=...: Feeds the video streams of both inputs into the libvmaf filter.
• model_path: Points to the path of your downloaded VMAF model file.
• -f null -: Instructs FFmpeg to process the video without writing a physical output file, which saves time and disk space.

Exporting VMAF Scores to a File

To analyze the quality frame-by-frame, you can export the results to an external file (XML, JSON, or CSV) using the log_path and log_fmt options:

ffmpeg -i distorted.mp4 -i reference.mp4 -filter_complex "[0:v][1:v]libvmaf=model_path=vmaf_v0.6.1.json:log_path=vmaf_report.json:log_fmt=json" -f null -

Syncing Videos of Different Formats or Frame Rates

For VMAF to calculate scores accurately, both videos must have the exact same resolution and frame rate. If your compressed video was downscaled, you must upscale it back to the reference video’s resolution using a scale filter before passing it to the VMAF filter:

ffmpeg -i distorted_720p.mp4 -i reference_1080p.mp4 -filter_complex "[0:v]scale=1920:1080[distorted_scaled]; [distorted_scaled][1:v]libvmaf=model_path=vmaf_v0.6.1.json" -f null -

Interpreting VMAF Scores

Once the process completes, FFmpeg will output the final VMAF score in the terminal, as well as in the log file if specified.

• Score Range: VMAF scores range from 0 to 100.
• 93 - 100: Excellent quality. The distortion is generally imperceptible to the human eye (often referred to as “visually lossless”).
• 70 - 90: Good quality. Minor compression artifacts may be visible upon close inspection, but the viewing experience remains acceptable.
• Below 70: Poor quality. Distortions and artifacts are highly noticeable.