vmafx — modernized CLI reference¶

Status: planned — not yet implemented in master. The vmafx symlink, --netflix-compat flag, and vmafx-* Python aliases are specified in ADR-0690 and ADR-0696 and are planned for the next implementation sprint. The vmaf binary with --precision=max is the interim equivalent. This page documents the intended behavior once the implementation lands.

vmafx is a thin alias for the vmaf binary that activates modernized defaults on invocation. It will be installed as a symlink to vmaf in the same bindir; the binary will detect the vmafx basename at startup and adjust its behavior accordingly (ADR-0690).

Relationship to vmaf. vmafx and vmaf will share one binary on disk. 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 explicitly.

Modernized defaults¶

The backend auto-selection priority (SYCL > CUDA > HIP > CPU) applies to both vmaf and vmafx and reflects the libvmaf registry order established after ADR-0726 dropped Vulkan. 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 (planned — not yet available)¶

These commands require the vmafx symlink from ADR-0690, which is not yet installed. Use the vmaf --precision=max equivalent until the implementation lands.

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

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

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

# Check which version and defaults are active (planned behavior)
vmafx --version
# Output: VMAFX 3.x.y-lusoris.N (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):

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 — see CLAUDE.md §8).
• 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. Both names invoke the same callable:

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.

Smoke test (once implemented)¶

After installation, confirm the symlink and default banner:

# Confirm vmafx resolves to the vmaf binary
ls -la $(which vmafx)
# -> ... vmafx -> vmaf

# Version string shows VMAFX identity and defaults
vmafx --version
# -> VMAFX 3.x.y-lusoris.N (auto-backend, precision=max)

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

Not yet available. The above commands will fail until the implementation sprint described in ADR-0690 lands. In the interim, use vmaf --reference ref.y4m --distorted dist.y4m --precision=max.

See also¶

• cli.md — full flag reference for all options accepted by both vmaf and vmafx.
• precision.md — detailed explanation of --precision modes (ADR-0119).
• ADR-0690 — decision record for the symlink implementation and argv[0] detection mechanism.
• ADR-0696 — decision record for the --netflix-compat flag design and post-parse ordering.
• ADR-0686 — VMAFX rebrand umbrella ADR.