`vmafx` — modernized CLI reference¶

vmafx runs the vmaf scorer with modernized defaults: lossless score precision and a VMAFX banner. Use it for workflows that consume scores programmatically; use vmaf when you need upstream Netflix output.

Meson builds vmafx as a separate executable next to vmaf, and on POSIX the installed vmafx is a symlink to vmaf. On Windows it is a dedicated vmafx.exe. The binary detects the vmafx basename at startup and adjusts its behavior (ADR-0690).

Relationship to vmaf

Every flag documented in cli.md is also accepted by vmafx. The only differences are the defaults described on this page. To restore all legacy defaults with vmafx, pass --netflix-compat.

Modernized defaults¶

Behavior	`vmaf` default	`vmafx` default
Output precision	`%.6f` (6 decimal places, matches upstream Netflix)	`%.17g` (IEEE-754 round-trip lossless, `--precision=max`)
Backend selection	auto: SYCL, then CUDA	same, auto is the default for both
Startup banner	`VMAF version <V>`	`VMAFX version <V> (precision=max)`
`--version` output	`<version string>`	`VMAFX <version string> (auto-backend, precision=max)`

The banner is printed to stderr only on a terminal and without --quiet.

Backend auto-selection is identical for both binaries: the compiled-in backends are tried in registry order, SYCL then CUDA. HIP and Metal join only when you pass --hip_device or --metal_device (cli.md). No difference exists at the backend level between the two binaries.

Why `--precision=max` is the vmafx default¶

The Netflix-upstream %.6f precision preserves bit-for-bit compatibility with the three golden-data test pairs in python/test/. This is essential for the vmaf binary, which participates in the golden-data gate.

vmafx targets new workflows that consume VMAF scores programmatically and benefit from the full IEEE-754 double range. %.17g outputs the minimum number of significant digits required for exact round-trip through strtod, avoiding silent truncation when scores are stored in JSON, CSV, or database tables. See precision.md for full details (ADR-0119).

Quick start¶

# .y4m pair — precision=max applied automatically
vmafx --reference ref.y4m --distorted dist.y4m

# Equivalent vmaf invocation with explicit flag
vmaf --reference ref.y4m --distorted dist.y4m --precision=max

# Opt back into legacy %.6f precision via explicit flag
vmafx --reference ref.y4m --distorted dist.y4m --precision=legacy

# Check which version and defaults are active
vmafx --version
# Output: VMAFX <version> (auto-backend, precision=max)

`--netflix-compat` — restore legacy defaults¶

--netflix-compat is a single flag that restores the complete set of Netflix-upstream legacy defaults, regardless of whether the binary was invoked as vmaf or vmafx. It is the recommended way to ensure output that is bit-for-bit identical to upstream Netflix/vmaf.

When --netflix-compat is passed, the following defaults are forced as the final post-parse pass (overriding any vmafx-mode modernizations):

Setting	`--netflix-compat` forced value
Backend	CPU only (equivalent to `--backend=cpu`)
Output precision	`%.6f` (equivalent to `--precision=legacy`)
Default model	`vmaf_v0.6.1` (restores legacy upstream default model)

The flag is idempotent on the vmaf binary — vmaf already uses these defaults, so vmaf --netflix-compat is a no-op in practice.

# Restore legacy defaults on vmafx (overrides precision=max and auto-backend)
vmafx --reference ref.y4m --distorted dist.y4m --netflix-compat

# Equivalent explicit form (both flags together)
vmafx --reference ref.y4m --distorted dist.y4m --backend=cpu --precision=legacy

# On the vmaf binary — idempotent, same output as without the flag
vmaf --reference ref.y4m --distorted dist.y4m --netflix-compat

Both --netflix-compat and --precision=legacy produce %.6f-formatted scores. The difference is that --netflix-compat also forces --backend=cpu, ensuring the CPU golden-data path is taken regardless of available GPU hardware.

When to use `--netflix-compat`¶

Use --netflix-compat when:

Reproducing results for comparison with upstream Netflix/vmaf.
Running a workflow that must satisfy the three golden-data test assertions in python/test/ (CPU + %.6f precision is required).
Debugging a numeric difference between vmafx and vmaf output: adding --netflix-compat to the vmafx invocation isolates whether the difference is from backend (GPU vs CPU) or precision (%.17g vs %.6f).

AI tool aliases¶

Three companion Python tools also ship vmafx-* aliases alongside their existing vmaf-* names. For each pair, both names invoke the same Python callable:

`vmaf-*` name	`vmafx-*` alias	Package
`vmaf-train`	`vmafx-train`	`ai/` (hatch package `vmaf-train`)
`vmaf-tune`	`vmafx-tune`	`tools/vmaf-tune/` (hatch package `vmaf-tune`)
`vmaf-mcp`	`vmafx-mcp`	`mcp-server/vmaf-mcp/` (hatch package `vmaf-mcp`)

Install any package with pip install -e <path> to get both names. The aliases are console_scripts entries pointing to the same Python callables; no behavior difference exists between vmaf-train and vmafx-train.

vmafx-mcp is also a Go binary

The same name belongs to the Go MCP server (cmd/vmafx-mcp). The "same callable" statement holds only for the Python package vmaf-mcp.

Smoke test¶

After installation, confirm the symlink and default banner:

# On POSIX, confirm vmafx resolves to the vmaf binary
ls -la $(which vmafx)
# -> ... vmafx -> vmaf

# Version string shows VMAFX identity and defaults
vmafx --version
# -> VMAFX <version> (auto-backend, precision=max), for example v1.0.0-rc.2-310-g1b1663830

# Or inside the dev container:
docker exec vmaf-dev-mcp vmafx --version

vmafx — modernized CLI reference¶

Modernized defaults¶

Why --precision=max is the vmafx default¶