vmaf-tune recommend — pick a CRF for a quality or bitrate target¶

vmaf-tune recommend returns one (preset, CRF) pair for a target. It works in two modes:

• Corpus mode (--from-corpus): select a row from an existing corpus JSONL. No encode and no scoring run.
• Live mode (--source): run the coarse-to-fine search, write every visited point to --output, and report the winner.

The base predicate is the point-estimate recipe from Research-0061 (Bucket 5). The optional uncertainty-aware extension (ADR-0393) changes only how much of the corpus is scanned.

Quick start¶

Corpus mode¶

1. Build a corpus once with the corpus subcommand:

   vmaf-tune corpus --source ref.yuv --width 1920 --height 1080 \
       --framerate 24 --duration 10 \
       --preset medium --crf 18 --crf 22 --crf 26 --crf 30 --crf 34 \
       --output corpus.jsonl
   

2. Ask for the lowest-bitrate encode whose VMAF reaches 92:

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

3. Or ask for the row whose bitrate is closest to 5 Mbps:

   vmaf-tune recommend --from-corpus corpus.jsonl --target-bitrate 5000
   

Live mode¶

vmaf-tune recommend \
    --source ref.yuv --width 1920 --height 1080 \
    --framerate 24 --duration 10 \
    --preset medium \
    --target-vmaf 92
# stdout: src=ref.yuv preset=medium crf=27 vmaf=92.341 (visited 15 encodes)

Live mode needs --source, --width, --height, --preset and --target-vmaf; it has no --crf flag because the search generates the CRF axis. --target-bitrate is corpus mode only.

Predicates¶

Passing both targets is an error (exit code 2). In corpus mode, rows with a non-zero exit_status and rows with a missing or non-finite vmaf_score are ignored.

Flags¶

Selection¶

Live search¶

Uncertainty¶

Output¶

Corpus mode prints one summary line (a trailing [UNMET] replaces [OK] when no row reaches the target):

crf=22  vmaf=95.000  kbps=5000  predicate=target_vmaf>=92.0  [OK]

Live mode prints the winner of each source and preset, using the smallest passing CRF:

src=ref.yuv preset=medium crf=27 vmaf=92.341 (visited 15 encodes)

Uncertainty-aware extension¶

The point-estimate recipe treats every row's VMAF as exact. In practice the predictor's residuals carry a distribution, and the conformal-prediction surface wraps each prediction in a (low, high) interval whose width is the predictor's local confidence. --with-uncertainty uses that width to decide how much to scan.

Each row is classed by the width of its interval:

When every visited row's interval lies below the target (high < target), the result is tagged UNMET, interval-excluded and returns the highest-VMAF row.

Rows without a vmaf_interval object (low and high) have a NaN width and land in MIDDLE, so a corpus built by plain corpus runs behaves exactly like the point-estimate recipe. This keeps pre-uncertainty behaviour for callers who upgrade the binary but keep an uncalibrated corpus.

Calibration sidecar¶

The defaults are tight_interval_max_width = 2.0 and wide_interval_min_width = 5.0 VMAF, from Research-0067, defined by vmaftune.uncertainty.ConfidenceThresholds. The sidecar schema matches the auto driver's loader, so one file drives auto, recommend and ladder:

{
  "tight_interval_max_width": 1.6,
  "wide_interval_min_width": 4.2
}

Extra keys are ignored.

Worked example¶

The example assumes the visited rows carry a vmaf_interval object. No vmaf-tune subcommand writes that object into corpus rows (their VMAF is measured, not predicted), so rows from a plain corpus or live run land in MIDDLE and the pick is the point-estimate one. The command says so: stderr reads vmaf-tune recommend: --with-uncertainty: no row carries a vmaf_interval ... and the result line ends with uncertainty=unavailable. Supply intervals from a calibrated predictor pipeline, or use the library override shown below.

$ vmaf-tune recommend --source ref.yuv --width 1920 --height 1080 \
    --encoder libx264 --preset medium --target-vmaf 93.0 \
    --coarse-to-fine --with-uncertainty \
    --uncertainty-sidecar calibration.json \
    --output corpus.jsonl

vmaf-tune: scoring backend = cpu
src=ref.yuv preset=medium crf=20 vmaf=94.250 \
    decision=tight rows_examined=2/15 (all 15 encoded) \
    predicate=target_vmaf>=93.0 (TIGHT, low=93.420)

• decision=tight: the interval at CRF 20 has width=0.6 <= tight_max=2.0 and low=93.42 >= target=93.0, so the search stopped there.
• rows_examined=2/15 (all 15 encoded): the pick examined two of the 15 rows the coarse-to-fine sweep produced. Every encode has already run when the pick starts, so the short-circuit saves no encode. With --from-corpus the line carries rows_examined=N/M alone (no encodes run there).
• predicate=...(TIGHT, low=93.420): the predicate that fired, with the lower bound that promoted the row.

If the predictor's intervals were all width >= 5.0, the output would read:

src=ref.yuv preset=medium crf=20 vmaf=94.250 \
    decision=wide rows_examined=15/15 (all 15 encoded) \
    predicate=target_vmaf>=93.0 (UNCERTAIN)

Library entry point¶

from vmaftune.recommend import (
    UncertaintyAwareRequest,
    pick_target_vmaf_with_uncertainty,
)
from vmaftune.uncertainty import (
    ConfidenceDecision,
    ConfidenceThresholds,
    load_confidence_thresholds,
)

thresholds = load_confidence_thresholds("calibration.json")
req = UncertaintyAwareRequest(
    target_vmaf=93.0,
    thresholds=thresholds,
    encoder="libx264",
    preset="medium",
)
result = pick_target_vmaf_with_uncertainty(rows, req)
assert result.decision is not ConfidenceDecision.WIDE  # confident pick

Per-call interval overrides go through sample_uncertainty, which is useful when the deep-ensemble and conformal pipeline produces intervals out of band:

overrides = {
    20: (94.0, 93.5, 94.5),  # (point, low, high) at CRF 20
    23: (91.0, 90.0, 92.0),
}
req = UncertaintyAwareRequest(
    target_vmaf=93.0,
    sample_uncertainty=overrides,
)

See also¶

• vmaf-tune.md — overview of every subcommand.
• vmaf-tune-coarse-to-fine.md — the live search, its flags, and the timing comparison against a full grid.
• vmaf-tune-corpus.md — builds the corpus and documents its row schema.
• vmaf-tune-benchmark.md — ranks encoders from the same corpus.
• vmaf-tune-ladder.md — the ABR-ladder consumer of the same intervals.
• docs/ai/conformal-vqa.md — the conformal prediction surface (ADR-0393).
• Research-0067 — provenance of the threshold defaults.