Getting started¶

VMAFx scores how a distorted video compares with its reference, the way a viewer would judge it. You can run it as a container image, as a downloaded binary, or from a source build. Pick one below, then score your first pair.

Choose how to get VMAFx¶

Each release is listed on the releases page. Until v1.0.0, the releases are candidates (v1.0.0-rc.N); the roadmap says what each candidate covers.

Container image¶

The images are published as ghcr.io/vmafx/vmafx:<tag>, where <tag> is a release tag such as v1.0.0-rc.2. The image's entry point is vmaf, so the arguments after the image name go straight to the CLI:

Images published after v1.0.0-rc.2 have zstd layers and need Docker Engine 23.0 or later, Docker Desktop 4.19 or later, Podman or containerd 1.5 or later (what can pull them).

docker run --rm ghcr.io/vmafx/vmafx:v1.0.0-rc.2 --version

Docker shows how to mount your videos and how to give a GPU image access to its device.

Release download¶

Each release attaches a CPU build of the CLI for Linux x86-64:

1. Download vmaf, the three libvmaf.so* files and the three libvmafx.so* files into one directory. The tool finds both libraries next to itself, so no LD_LIBRARY_PATH is needed.

2. Restore the executable bit, which a download does not keep:

   chmod +x vmaf
   ./vmaf --version
   

3. Optional: verify the signatures with the consumer verification recipes.

The binary is built with AVX-512 enabled and without the ONNX runtime, so the --tiny-* options are not available in it (build-native-release-artifacts.sh).

Build from source (any platform)¶

A source build gives you the GPU backends, the tests and the companion tools.

1. Install the build dependencies for your platform:

   Platform	Package manager	Guide
   Ubuntu 22.04 / 24.04 / 26.04	apt	Ubuntu
   Fedora, RHEL 9 family	dnf	Fedora
   Arch Linux	pacman	Arch
   Alpine (musl, CPU only)	apk	Alpine
   macOS (Apple silicon or Intel)	Homebrew	macOS
   Windows, MSVC	winget or Chocolatey	Windows
   Windows, MSYS2 / MinGW-w64	pacman (MSYS2)	Building on Windows

2. From the repository root, configure a CPU build. Meson's source directory is core/:

   meson setup build core \
     -Denable_cuda=false -Denable_sycl=false -Denable_hip=false \
     -Denable_metal=disabled -Denable_dnn=disabled
   

3. Compile and run the unit tests:

   ninja -C build
   python3 scripts/ci/run_meson_test.py -- -C build
   

The CLI is build/tools/vmaf (build/tools/vmaf.exe on Windows), with build/tools/vmafx as a second name for the same program.

Use a fresh build directory for each backend configuration. The backend guide lists the SDK and the Meson options each backend needs, and build flags lists every option. For a container with every toolchain installed, see the dev-MCP container.

Compilers¶

GCC and clang are the reference compilers: the Netflix golden-score gate builds with one of them (ADR-1317). An Intel icx / icpx build on Linux links glibc's math library, so its CPU scores equal a GCC build's (ADR-1495). No C or C++ file is compiled with floating-point contraction on any compiler (ADR-1461).

Next steps¶

1. Score your first pair and read the output.
2. Choose a backend for your hardware.
3. Use the CLI reference, the C API or the FFmpeg filter.
4. To report results from hardware the project does not own, use the tester image.