easyVmaf

Python tool based on FFmpeg and FFprobe to handle the video preprocessing required for VMAF:

• Deinterlacing
• Upscaling / downscaling
• Frame-to-frame syncing
• Frame rate adaptation

Details about How it Works can be found here.

Requirements

• Linux / macOS
• Python >= 3.8
• FFmpeg >= 5.0 built with --enable-libvmaf (built-in models required)
• Python package: ffmpeg-progress-yield

For GPU-accelerated VMAF:

• NVIDIA GPU with CUDA support
• FFmpeg built with --enable-nonfree --enable-ffnvcodec --enable-libvmaf
• libvmaf built with -Denable_cuda=true -Denable_float=true
• NVIDIA Container Toolkit (for Docker GPU usage)

Installation

pip install easyvmaf

Or from source:

git clone https://github.com/gdavila/easyVmaf.git
cd easyVmaf
pip install -e .

FFmpeg must be on PATH, or override via environment variables:

FFMPEG=/path/to/ffmpeg FFPROBE=/path/to/ffprobe easyvmaf ...

Usage

easyvmaf -d <distorted> -r <reference> [options]

Required arguments

Flag	Description
-d D	Distorted video path (supports glob patterns for batch)
-r R	Reference video path

Optional arguments

Flag	Default	Description
-sw SW	0	Sync window size in seconds. Enables automatic sync search between the first frames of the distorted and a subsample of the reference. 0 disables sync.
-ss SS	0	Sync start time: offset into the reference where the sync window begins.
-fps FPS	0	Force frame rate conversion. Disables auto-deinterlace when set.
-subsample N	1	Frame subsampling factor to speed up computation.
-reverse	off	Reverse sync direction: match reference first-frames against distorted instead of the default.
-model MODEL	HD	VMAF model. Options: HD, 4K.
-threads N	0	Number of threads (0 = auto).
-output_fmt FMT	json	Per-frame VMAF output file format: json, xml, or csv.
-verbose	off	Enable verbose log level.
-progress	off	Show FFmpeg progress during VMAF computation.
-endsync	off	Stop when the shorter video ends.
-cambi_heatmap	off	Compute and save CAMBI banding heatmap.
-sync_only	off	Measure sync offset only — skip VMAF computation.
-json	off	Print final results as JSON to stdout. Compatible with -sync_only and full VMAF runs. In batch mode, one JSON object per line (NDJSON).
-gpu	off	Use GPU-accelerated VMAF via libvmaf_cuda. Requires a CUDA-capable FFmpeg build (see Docker: CUDA).

Examples

Basic VMAF (no sync)

easyvmaf -d distorted.mp4 -r reference.mp4

With automatic sync

# Sync window of 2 seconds starting from the beginning of reference
easyvmaf -d distorted.mp4 -r reference.mp4 -sw 2

# Sync window starting at 6 s into reference, reverse direction
easyvmaf -d distorted.mp4 -r reference.mp4 -sw 3 -ss 6 -reverse

Sync measurement only

# Human-readable output
easyvmaf -d distorted.mp4 -r reference.mp4 -sw 2 -sync_only

# Structured JSON output
easyvmaf -d distorted.mp4 -r reference.mp4 -sw 2 -sync_only -json

Structured JSON output

The -json flag prints a single JSON object to stdout (or one object per line in batch mode):

easyvmaf -d distorted.mp4 -r reference.mp4 -sw 2 -json

{
  "distorted": "distorted.mp4",
  "reference": "reference.mp4",
  "sync": { "offset": 0.7007, "psnr": 48.863779 },
  "vmaf": {
    "model": "HD",
    "vmaf_hd": 89.123456,
    "vmaf_hd_neg": 88.654321,
    "vmaf_hd_phone": 91.234567,
    "output_file": "distorted_vmaf.json"
  }
}

Batch processing

# Glob pattern — one result per file
easyvmaf -d "folder/*.mp4" -r reference.mp4 -json

4K model

easyvmaf -d distorted_4k.mp4 -r reference_4k.mp4 -model 4K

GPU-accelerated VMAF

Requires a CUDA build of FFmpeg/libvmaf (see Docker section below):

easyvmaf -d distorted.mp4 -r reference.mp4 -gpu

Sync computation always runs on CPU regardless of -gpu. The GPU is used only for the final VMAF scoring step.

---

Docker

CPU build

docker build -t easyvmaf .

CUDA / GPU build

docker build -f Dockerfile.cuda -t easyvmaf:cuda .

Note: The CUDA image links FFmpeg with --enable-nonfree components (nvcc/CUDA). It cannot be legally redistributed — build and use locally only.

Build arguments

Both Dockerfiles accept these build-time arguments:

ARG	Default	Description
FFMPEG_version	8.1	FFmpeg release tag
VMAF_version	3.0.0	libvmaf release tag
EASYVMAF_VERSION	2.1.0	easyVmaf version label
DAV1D_version	1.4.3	dav1d release (CUDA image only — built from source)

# Custom versions
docker build --build-arg FFMPEG_version=8.1 --build-arg VMAF_version=3.0.0 -t easyvmaf .

Running with Docker

# CPU
docker run --rm -v /path/to/videos:/videos \
  easyvmaf -d /videos/distorted.mp4 -r /videos/reference.mp4

# With sync
docker run --rm -v /path/to/videos:/videos \
  easyvmaf -d /videos/distorted.mp4 -r /videos/reference.mp4 -sw 2

# JSON output
docker run --rm -v /path/to/videos:/videos \
  easyvmaf -d /videos/distorted.mp4 -r /videos/reference.mp4 -json

# GPU (requires NVIDIA Container Toolkit)
docker run --rm --gpus all -v /path/to/videos:/videos \
  easyvmaf:cuda -d /videos/distorted.mp4 -r /videos/reference.mp4 -gpu

Docker Compose

A docker-compose.yml is included with pre-configured easyvmaf (CPU) and easyvmaf-cuda (GPU) services:

# CPU service
VIDEO_DIR=/path/to/videos docker compose run easyvmaf \
  -d /videos/distorted.mp4 -r /videos/reference.mp4

# GPU service
VIDEO_DIR=/path/to/videos docker compose run easyvmaf-cuda \
  -d /videos/distorted.mp4 -r /videos/reference.mp4 -gpu

VIDEO_DIR defaults to ./video_samples if not set.

---

Sync examples explained

Reference delayed relative to distorted

reference.ts starts 0.7 seconds after distorted-A.ts. Use -sw to search for the offset automatically:

easyvmaf -d distorted-A.ts -r reference.ts -sw 2

The sync window sw=2 means easyVmaf searches the first 2 seconds of reference.ts for the best PSNR match against the first frames of distorted-A.ts.

Distorted delayed relative to reference

distorted-B.ts starts 8.3 seconds after reference.ts. Use -reverse to flip the sync direction:

easyvmaf -d distorted-B.ts -r reference.ts -sw 3 -ss 6 -reverse

-ss 6 begins the sync search 6 seconds into reference.ts; -reverse matches reference first-frames against the distorted stream.