Enable VMAF Feature Extraction in FFmpeg

This article explains how to enable and configure feature extraction, such as motion and psychovisual models, using the libvmaf filter in FFmpeg. You will learn the correct command-line syntax to activate these individual metrics and extract detailed quality scores alongside your standard VMAF calculations.

Understanding VMAF Feature Extraction

The Video Multi-Method Assessment Fusion (VMAF) model developed by Netflix relies on several underlying features to calculate its final quality score. These features include motion, Visual Information Fidelity (VIF), and Detail Loss Metric (ADM2).

By default, FFmpeg’s libvmaf filter calculates the final fused VMAF score. However, you can explicitly enable individual feature extractors using the feature option. This is highly useful for debugging, deeper video analysis, or when using custom VMAF models that require specific feature inputs.

Command Syntax for Feature Extraction

To enable features, use the feature parameter inside the libvmaf filter configuration. The general syntax is:

libvmaf=feature='name=<feature_name>'

If you want to extract multiple features at once, separate them with a pipe character (|):

libvmaf=feature='name=<feature_1>|name=<feature_2>'

Common VMAF Feature Names

The most frequently used feature extractors in libvmaf include:

• motion: Measures the temporal difference between consecutive frames.
• adm2: The psychovisual Detail Loss Metric.
• vif_scale0, vif_scale1, vif_scale2, vif_scale3: Visual Information Fidelity metrics calculated at four different spatial scales.
• psnr: Peak Signal-to-Noise Ratio.
• ssim: Structural Similarity Index.
• ms_ssim: Multi-Scale Structural Similarity Index.

Practical Examples

To write these feature scores to a file, you must specify a log path (log_path) and a log format (log_fmt).

Example 1: Extracting the Motion Feature

This command compares a distorted video against a reference video and logs the frame-by-frame motion values to an XML file.

ffmpeg -i distorted.mp4 -i reference.mp4 \
-filter_complex "[0:v][1:v]libvmaf=feature='name=motion':log_path=vmaf_output.xml:log_fmt=xml" \
-f null -

Example 2: Extracting Multiple Features (Motion and ADM2)

To extract both psychovisual detail loss (adm2) and motion data simultaneously and save the output in JSON format, use the following command:

ffmpeg -i distorted.mp4 -i reference.mp4 \
-filter_complex "[0:v][1:v]libvmaf=feature='name=motion|name=adm2':log_path=vmaf_output.json:log_fmt=json" \
-f null -

Example 3: Extracting Features with a Specific Model

If you are using a custom VMAF model file (such as a 4K or phone model) that requires specific features, you can pass both the model and the features together:

ffmpeg -i distorted.mp4 -i reference.mp4 \
-filter_complex "[0:v][1:v]libvmaf=model='path=vmaf_v0.6.1.json':feature='name=motion|name=psnr':log_path=output.json:log_fmt=json" \
-f null -

Once the command finishes running, open the generated .json or .xml log file. You will find the individual frame-by-frame values for each enabled feature mapped alongside the overall VMAF score.