🎬 VMAFx

Perceptual video quality assessment — GPU-accelerated, SIMD-tuned, numerically exact

A fork of Netflix/vmaf that keeps the reference scores byte-for-byte

📖 Full documentation · Documentation source

---

🎯 Why VMAFx

VMAFx keeps upstream's numbers and adds the parts a production pipeline needs. The three Netflix reference pairs are a required CI gate, so every change below is measured against scores that never move.

	Upstream libvmaf	VMAFx
GPU backends	CUDA	CUDA · SYCL · HIP · Metal, selected at runtime
SIMD	AVX2, AVX-512	AVX2 · AVX-512 · NEON · SVE2, held to feature-specific parity tolerances
Output precision	%.6f	%.6f by default, --precision=max for IEEE-754 round-trip
Model surface	.json / .pkl	plus ONNX tiny models with a signed registry
Integrations	FFmpeg filter	FFmpeg, an MCP server, a Kubernetes operator, Go and Rust bindings
Numerical contract	—	cross-backend parity is a gate, not a promise

🚀 Get started

Follow the installation and source-build guide for your platform. For a container workflow, see Docker.

After installation, compare a matching reference and distorted Y4M pair:

vmaf --reference reference.y4m --distorted distorted.y4m --json --output scores.json

Raw YUV needs its geometry spelled out, and a GPU backend is one flag:

vmaf --reference ref.yuv --distorted dis.yuv \
     --width 1920 --height 1080 --pixel_format 420 --bitdepth 8 \
     --backend cuda --feature cambi --json --output scores.json

See the CLI reference for model selection, backend selection and output options. For compressed inputs such as MP4, use FFmpeg integration.

🧩 Backends at a glance

Every GPU-backed feature extractor has at least one device twin, and each twin is held to the CPU reference by the cross-backend parity gate. The coverage matrix below distinguishes those extractors from CPU-only metrics.

Backend	Selected with	Notes
CPU	--backend cpu	scalar reference; SIMD paths dispatch automatically
CUDA	--backend cuda	NVIDIA, CUDA 13.3
SYCL	--backend sycl	Intel oneAPI; fp64-free device contract
HIP	--backend hip	AMD ROCm 10.0
Metal	--backend metal	Apple Silicon, Apple Family 7 and later

See GPU and SIMD backends for feature coverage per backend and the tolerances the gate enforces.

📚 Guides and reference

Task	Documentation
Score videos and choose output formats	CLI reference
Use VMAFx in FFmpeg	FFmpeg guide
Select hardware and check feature coverage	GPU and SIMD backends
Choose metrics and extractor options	Feature reference
Choose a scoring model	Models
Embed libvmaf in an application	C API
Train and run ONNX quality models	Tiny AI
Connect scoring tools through MCP	MCP servers

Build requirements, backend limitations and model defaults live in these guides so they can be maintained alongside their implementations.

🤝 Contribute

Start with CONTRIBUTING.md for setup, required checks and pull-request expectations. The engineering principles cover coding and numerical-correctness standards; the repository guide explains the source layout.

• Report a bug or request a feature
• Security reporting policy
• Support development

📈 Project status

• Roadmap and release goals
• Releases and downloads
• Changelog
• Release process

Upstream and license

VMAFx builds on Netflix/vmaf. See upstream releases for Netflix's release history.

The repository carries two sets of terms, separated by provenance and recorded per file as an SPDX-License-Identifier (ADR-1250):

• Code inherited, ported or translated from Netflix/vmaf or another project keeps the terms it already carries — BSD-2-Clause-Patent for Netflix's code, and its own licence for the libjxl, Xiph and IQA code the fork builds on. Those files carry the original copyright notice.
• Fork-authored code is licensed under EUPL-1.2, a reciprocal licence.

What that means in practice: because the shipped libvmaf links both together, redistributing a modified library obliges you to offer its source under EUPL-1.2. If you need permissive terms, use Netflix/vmaf upstream, which is unaffected. The per-file tags are authoritative; this paragraph is a summary.

Standards & Governance

This repository conforms to High-Integrity Systems Standards (HISS-16) and modernized NASA JPL Power-of-10 rules.

Gate	Command	Description
Verification	make verify-all	Runs full audit, test suite, and context integrity check
HISS Audit	standardsctl audit	Enforces zero technical debt regression against baseline
Context Sync	standardsctl compile-context	Transpiles canonical AGENTS.md to all AI targets