How to Enable Feature Extraction in FFmpeg VMAF

This guide explains how to enable and export individual feature extraction metrics—such as motion, Visual Information Fidelity (VIF), and psychovisual models like CAMBI—using the FFmpeg libvmaf filter. You will learn the syntax introduced in VMAF version 2.x, how to configure specific sub-metric extractors, and how to dump the frame-by-frame feature scores into machine-readable log files.

Understanding VMAF Feature Extraction

When calculating VMAF, the engine computes several intermediate elementary features before applying a machine learning model to produce the final score. In FFmpeg, using the modern libvmaf library (v2.0+), you can explicitly enable feature extractors using the feature parameter. This allows you to inspect specific visual degradation factors independently, including motion intensity, spatial details, and banding artifacts.

The feature Syntax

The basic syntax for passing feature options to the libvmaf filter is:

libvmaf=feature='name=<feature_name>[:<option>=<value>]'

To extract multiple features simultaneously, separate each feature definition with a pipe character (|):

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

To retain and analyze these features, you must enable logging by setting log_fmt (json, xml, or csv) and specifying a log_path.

Common Feature Extractors

• motion: Computes frame-to-frame motion score based on luminance difference.
• cambi: The Contrast Aware Multiscale Banding Index, a psychovisual detector for banding and contouring artifacts.
• vif / vif_scale: Visual Information Fidelity metrics assessing visual detail retention across various scales.
• adm / adm2: Additive impairment measures that evaluate spatial detail and visual contrast.

Practical FFmpeg Examples

1. Extracting Motion Features

To calculate the overall VMAF score alongside the raw motion metric, run:

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

2. Extracting Psychovisual Models (CAMBI)

CAMBI supports custom parameters, such as adjusting the maximum search window or filtering thresholds. You can pass options directly into the feature declaration:

ffmpeg -i distorted.mp4 -i reference.mp4 -filter_complex \
"[0:v][1:v]libvmaf=feature='name=cambi:topk=0.001:enc_width=1920:enc_height=1080':log_fmt=json:log_path=cambi_output.json" \
-f null -

3. Combining Multiple Features

You can extract motion, CAMBI, and individual elementary metrics simultaneously in a single pass:

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

Reading the Extracted Output

When feature extraction is enabled, the resulting JSON or XML log contains an expanded metrics block for every processed frame. In a JSON log, each entry inside the frames array includes the standard VMAF score as well as keys for each requested feature:

{
  "frameNum": 0,
  "metrics": {
    "vmaf": 94.21,
    "integer_motion": 0.0,
    "cambi": 0.12,
    "adm2": 0.985
  }
}

These values can be parsed to diagnose specific encoding issues, such as heavy motion penalties or severe color-banding artifacts.