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.4
SYCL	--backend sycl	Intel oneAPI; fp64-free device contract
HIP	--backend hip	AMD ROCm 10.1
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
• Ask a question or read how to get support
• Code of conduct
• Accessibility
• Security reporting policy
• Support development

💖 Support VMAFx

VMAFx is free and stays open source. Sponsor it on GitHub Sponsors (USD) or Ko-fi or Patreon (EUR) to pay for CI and cloud GPU test time. Sponsors are thanked by tier in SPONSORS.md; Support VMAFx explains what it pays for.

📈 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.

Each file's SPDX-License-Identifier header says which licence applies to it (ADR-1250). The files at the repository root hold the texts (ADR-1699):

Code	Licence	Text
Written by the fork	EUPL-1.2, a reciprocal licence	LICENSE
Inherited, ported or translated from Netflix/vmaf	BSD-2-Clause-Patent, with Netflix's copyright notice	NOTICE
Carried from libjxl, Xiph, IQA and other projects	that project's licence, with its notice in the file	LICENSES/

What that means in practice: the shipped libvmaf links both together. Distributing it, modified or not, obliges you to provide its source or point to a repository that has it (EUPL-1.2, Article 5). A modified library is distributed under EUPL-1.2. If you need permissive terms, use Netflix/vmaf upstream, which is unaffected. The per-file tags are authoritative; this section is a summary, not legal advice. Licensing lists what each published package carries, and Embedding VMAFx in another product goes through linking, modification and network use. Credits names every third-party project, model, dataset, paper and tool VMAFx builds on.

Standards & Governance

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

Praetor manages this repository's declared governance policy. This managed block records adoption state; it is not a verification certificate.

Verification: make verify-all runs the repository's configured verification cascade.

HISS Audit: praetorctl audit enforces policy, generated-surface integrity, and the debt ratchet.

Context Sync: praetorctl compile-context --verify verifies every generated agent context against AGENTS.md.

Documentation: make docs-lint enforces locked Markdown style and the private scratch-link policy.

Debt Baseline: .standards-baseline.json anchors the debt ratchet at 0 recorded infractions; audit forbids growth.