vmaf-tune — target-VMAF bisect (Phase B)¶

The vmaftune.bisect module finds the largest CRF whose actual measured VMAF still meets a target floor, given a (source, codec, target VMAF) triple. Largest CRF = lowest bitrate at acceptable quality — the cost-optimal point.

This is the production wiring that replaced the earlier placeholder predicate used by the compare, recommend-saliency, predict, tune-per-shot, and ladder subcommands. See ADR-0326 for the decision and Research-0090 for the algorithmic feasibility digest.

When to reach for it¶

The bisect is a 1-axis primitive that other phases compose with. It does not sweep presets; pin a preset up-front (or use the adapter's mid-range default). It does not pre-screen for unreachable targets; the bisect bails with a clear error when the curve never clears the floor in the searched window.

Algorithm in one paragraph¶

Integer binary search over the CRF window crf_range or adapter.quality_range. At each step, encode at the midpoint CRF, score with libvmaf. Measured VMAF >= target → narrow upward (try harder compression); else narrow downward. Midpoint rounds toward the lower-quality (higher-CRF) end so the "best so far" record is always a CRF we measured, not one we extrapolated to. Stops when the window collapses to a single CRF or after max_iterations.

The bisect assumes monotone-decreasing VMAF in CRF. Two non-adjacent samples that violate this contract (rising VMAF for rising CRF) abort the call with a clear error rather than falling back to a different search strategy.

Quick start — single-codec¶

from pathlib import Path
from vmaftune.bisect import bisect_target_vmaf

result = bisect_target_vmaf(
    Path("ref.yuv"),
    "libx264",
    target_vmaf=92.0,
    width=1920,
    height=1080,
    pix_fmt="yuv420p",
    framerate=24.0,
    duration_s=10.0,
    crf_range=(15, 40),       # default: adapter.quality_range
    max_iterations=8,
    preset="medium",          # default: adapter mid-range preset
)
if result.ok:
    print(
        f"best CRF {result.best_crf} → "
        f"VMAF {result.measured_vmaf:.2f} @ {result.bitrate_kbps:.0f} kbps "
        f"({result.n_iterations} encodes)"
    )
else:
    print(f"bisect failed: {result.error}")

The encode + score subprocesses go through the same seams Phase A already uses (encode.run_encode, score.run_score), so all the ffmpeg / vmaf binary settings (ffmpeg_bin, vmaf_bin, score_backend per ADR-0299) flow through verbatim.

Quick start — multi-codec compare¶

CLI:

vmaf-tune compare \
    --src ref.yuv \
    --width 1920 --height 1080 --pix-fmt yuv420p \
    --framerate 24 --duration 10 \
    --sample-clip-seconds 4 \
    --target-vmaf 92 \
    --encoders libx264,libx265,libsvtav1 \
    --crf-min 15 --crf-max 40 \
    --format markdown

Python API:

from pathlib import Path
from vmaftune.bisect import make_bisect_predicate
from vmaftune.compare import compare_codecs, emit_report

predicate = make_bisect_predicate(
    target_vmaf=92.0,
    width=1920,
    height=1080,
    framerate=24.0,
    duration_s=10.0,
    sample_clip_seconds=4.0,
    crf_range=(15, 40),
    max_iterations=8,
)

report = compare_codecs(
    src=Path("ref.yuv"),
    target_vmaf=92.0,
    encoders=("libx264", "libx265", "libsvtav1"),
    predicate=predicate,
)
print(emit_report(report, format="markdown"))

The predicate is bound once with the source geometry; compare_codecs dispatches per-codec via the adapter registry and ranks the results by ascending bitrate.

Output schema — BisectResult¶

BisectResult.to_recommend_result() projects onto compare.RecommendResult for downstream consumers that already speak the comparison schema.

Knobs¶

Container vs raw YUV sources¶

src may be either a raw planar .yuv (the legacy contract) or any FFmpeg-readable container (.mp4, .mkv, .mov, …). The bisect autodetects the shape via the file suffix and does two extra things for container sources (ADR-0497):

1. Encode — the encoder ffmpeg invocation omits the -f rawvideo -pix_fmt … -s … -r … input flags so ffmpeg autodetects the container; otherwise it would mis-interpret the demuxed bytes as raw YUV and produce zero frames.
2. Decode-then-score — every per-CRF encode is a .mkv container; the libvmaf CLI only accepts raw .yuv / .y4m, so the bisect decodes the encoded artefact to a raw YUV sidecar before invoking the vmaf binary. The reference is also decoded once per bisect and cached across iterations.

These steps add one ffmpeg call per encode + one per bisect to the critical path; both are negligible against the encoder runtime on sample clips longer than a second.

Error modes¶

What it does NOT do (yet)¶

• No cache: every call re-encodes; integrating the ADR-0298 cache key fields is a one-call insertion.
• No standalone bisect CLI subcommand: the primitive is exposed through vmaf-tune compare for multi-codec ranking and through the Python API for custom orchestration. tune-per-shot and ladder can bind the same predicate from Python.

See also¶

• ADR-0326 — decision + alternatives matrix.
• Research-0090 — algorithmic feasibility digest.
• ADR-0237 — vmaf-tune umbrella spec.
• tools/vmaf-tune/AGENTS.md — rebase-sensitive invariants for the harness.