vmaf-tune — quality-aware encode automation harness¶

vmaf-tune finds the encoder settings that reach a target VMAF score. It drives FFmpeg over a grid of encoder parameters, scores each encode with vmaf, and either writes a JSONL corpus of (source, encoder, params, bitrate, vmaf) rows or answers a question directly: which CRF hits VMAF 92, which codec is cheapest at that target, what a per-title bitrate ladder looks like.

The tool is a fork-added Python package (ADR-0237, Research-0044). A Go port of the same subcommands is described in vmafx-tune-go.md.

Install¶

1. Install the package from the repository root. The core install has no runtime dependencies beyond the Python standard library:

   pip install -e tools/vmaf-tune
   

   This installs two equivalent console scripts, vmaf-tune and vmafx-tune. Without installing, run the checkout shim instead:

   python tools/vmaf-tune/vmaf-tune --help
   

2. Put the external binaries on PATH (or pass --ffmpeg-bin / --vmaf-bin):

   • ffmpeg built with the encoders you want to tune (--enable-libx264, plus --enable-libsvtav1 for libsvtav1, and so on). ffprobe is needed for container sources and HDR detection.
   • vmaf, this fork's CLI, built with meson (see getting started).

3. Optional extras, installed as pip install -e "tools/vmaf-tune[NAME]":

   Extra	Adds	For
   fast	Optuna	the TPE search of fast
   report	matplotlib	the charts of report; without it the report renders its tables and a placeholder per chart
   onnx	ONNX Runtime	ONNX inference: the fast proxy, the per-shot predictor and the saliency models
   dev	pytest, ruff, Optuna, matplotlib, ONNX Runtime	running the test suite (see Tests)

vmaf-tune --version prints the package version.

Quick start¶

Sweep two presets and three CRF values over one 1080p clip. The grid is the Cartesian product of --preset and --crf, so this writes six rows:

vmaf-tune corpus \
    --source ref.yuv \
    --width 1920 --height 1080 --pix-fmt yuv420p \
    --framerate 24 --duration 10 \
    --preset medium --preset slow \
    --crf 22 --crf 28 --crf 34 \
    --output corpus.jsonl

Then ask the corpus which CRF reaches a target:

vmaf-tune recommend --from-corpus corpus.jsonl --target-vmaf 92

The corpus page lists every corpus flag and the row schema. Recommend covers the target-VMAF and target-bitrate queries.

Subcommands¶

vmaf-tune --help lists 14 subcommands. Each one has a page with its flag table and examples.

There is no hdr subcommand. HDR handling is automatic on corpus and is controlled with --auto-hdr, --force-sdr, --force-hdr-pq and --force-hdr-hlg; see HDR and sampling.

ref.yuv ─► corpus ─► corpus.jsonl ─► recommend ──► CRF for a target
                          │        └► benchmark ─► encoder ranking
                          └─────────► predict / sidecar (predictor training)

ref.yuv ─► compare | ladder | tune-per-shot | fast | auto ─► JSON ─► report
                                                                       └► encode-profile

Topic pages¶

These pages cover behaviour shared across subcommands.

Design records¶

Tests¶

python3 -m venv .venv-tune
.venv-tune/bin/pip install -e "tools/vmaf-tune[dev]"
.venv-tune/bin/python -m pytest tools/vmaf-tune/tests/

The dev extra holds every package the suite imports, so a run from it has no failure and no skip for a missing package. Each test runs in its own temporary working directory (tests/conftest.py). The suite mocks subprocess.run almost everywhere, so it needs neither ffmpeg nor a built vmaf; the tests that need more skip and name what is missing:

Former section names¶

ADRs and the changelog archive link to sections of the page this overview replaced; each heading points to the page that now holds the content.

fast subcommand — proxy + Bayesian + GPU-verify (Phase A.5)¶

Now on vmaf-tune fast.

Codec adapter contract¶

Now under adapter contract.

Per-content-type recipes (F.4)¶

Now under per-content-type recipes.

Sample-clip mode¶

Now under clip sampling.