vmaf-tune tune-per-shot — per-shot CRF tuning¶

vmaf-tune tune-per-shot splits a source into shots, finds the CRF that hits a target VMAF for each shot, and writes an FFmpeg plan that encodes one segment per shot and joins them with a concat-demuxer command. It does not run the encodes itself. The design is in ADR-0392; the tool overview is in vmaf-tune.md.

How it works¶

1. Detect shots. The C-side vmaf-perShot binary, which wraps TransNet V2 (ADR-0223), returns the shot boundaries. A uniform-time-window splitter then slices any shot longer than --max-shot-duration.
2. Extract. Each shot is cut to a temporary raw-YUV reference.
3. Bisect. The target-VMAF bisect runs per shot.
4. Plan. The tool emits one segment encode per shot and a final concat command.

The target-VMAF predicate stays pluggable: --predicate-module MODULE:CALLABLE bypasses the default bisect, and the Python API accepts tune_per_shot(..., predicate=...).

Quick start¶

A container source needs no pre-extraction. Its geometry, framerate and frame count are auto-probed with ffprobe (ADR-0548):

vmaf-tune tune-per-shot \
    --src clip.mp4 \
    --target-vmaf 92 \
    --encoder libx264 \
    --output per_shot_encode.mp4 \
    --plan-out plan.json

A raw YUV source needs explicit geometry:

vmaf-tune tune-per-shot \
    --src ref.yuv \
    --width 1920 --height 1080 \
    --framerate 24 \
    --target-vmaf 92 \
    --encoder libx264 \
    --output per_shot_encode.mp4 \
    --plan-out plan.json

The plan goes to stdout as JSON unless --plan-out is set. Pass --script-out plan.sh to also get a copy-paste shell script of the per-segment and concat commands.

Exit code 2 means a setup failure: an unavailable score backend, missing geometry for a raw source, or a failed bisect on a shot.

Flags¶

Segment directory¶

The directory for the concat listing (concat.txt) is, in order of priority:

1. --segment-dir;
2. <plan-out parent>/segments, when --plan-out is set;
3. <output parent>/segments.

When that directory is not writable (for example a read-only bind mount) the tool prints a WARN on stderr and still exits 0. The plan JSON stays the authoritative deliverable (ADR-0532).

Plan JSON schema¶

{
  "encoder": "libx264",
  "framerate": 24.0,
  "predicate": "bisect",
  "target_vmaf": 92.0,
  "shots": [
    {
      "start_frame": 0, "end_frame": 24,
      "crf": 22, "predicted_vmaf": 93.0,
      "bitrate_kbps": 5234.12
    },
    {
      "start_frame": 24, "end_frame": 72,
      "crf": 26, "predicted_vmaf": 92.5,
      "bitrate_kbps": 4182.44
    }
  ],
  "segment_commands": [
    ["ffmpeg", "-y", "-hide_banner", "-ss", "0.000000", "-i", "ref.mp4",
     "-frames:v", "24", "-c:v", "libx264", "-crf", "22",
     "/tmp/segments/shot_0000.mp4"]
  ],
  "concat_command": [
    "ffmpeg", "-y", "-hide_banner", "-f", "concat", "-safe", "0",
    "-i", "/tmp/segments/concat.txt", "-c", "copy", "out.mp4"
  ]
}

The vmaf-perShot CSV and JSON sidecar uses an inclusive end_frame. The planner normalises it to the half-open form.

Single-shot fallback¶

If vmaf-perShot is not on PATH, or it exits non-zero, the planner falls back to a single shot that covers the whole clip, [0, --total-frames). That keeps tune-per-shot usable as a smoke test on machines that have not built the shot detector.

The uniform-window splitter still applies to the fallback. Even when the detector returns one giant shot, --max-shot-duration (default 2.0 s) slices it into about \(\lceil \mathrm{duration} / \mathrm{window} \rceil\) equal sub-shots, so the tuner still produces a useful CRF timeline. --max-shot-duration 0 restores the historical single-shot behaviour (ADR-0513).

Tuning scene sensitivity¶

vmaf-perShot calls frame N a cut when the mean absolute luma delta against frame N-1 (in the 8-bit domain) crosses --diff-threshold. The compiled default is 12.0, tuned on the testdata fixtures (ADR-0222). Real content varies, and --scene-threshold passes through to the C binary unchanged, so diagnostic scripts that call vmaf-perShot directly use the same units.

Animated material with deep saturated transitions trips the heuristic easily at the default. Other content behaves as follows:

What it does not do¶

See also¶

• vmaf-tune.md — the tool overview.
• vmaf-perShot.md — the shot detector binary.
• vmaf-tune-bisect.md — the bisect run per shot.
• vmaf-tune-auto.md — auto can score per shot in execute mode.
• vmaf-tune-fast-nr.md — --fast-nr.
• ADR-0392 — design rationale and decision matrix.