Research 0101: vmaf-tune Predictor Real Hardware Retrain (2026-05-14)¶

Question¶

Which vmaf-tune predictor stubs can be replaced by real weights with data already present on this machine?

Findings¶

• The shipped model/predictor_<codec>.onnx family had synthetic-stub cards for every codec adapter.
• The local Phase-A hardware sweep runs/phase_a/full_grid/comprehensive.jsonl contains real measured rows for six hardware codecs: h264_nvenc, hevc_nvenc, av1_nvenc, h264_qsv, hevc_qsv, and av1_qsv.
• That corpus predates the canonical trainer key names and uses codec, q, vmaf, and actual_kbps; the trainer only consumed encoder, crf, vmaf_score, and bitrate_kbps.
• There is no equivalent local corpus for libx264, libx265, libsvtav1, libaom-av1, libvvenc, or the AMF adapters in this pass, so flipping those would either keep synthetic targets or require a new encode sweep.

Decision¶

Teach the trainer to normalize the existing hardware-sweep aliases and retrain only the six codecs with real measured rows. Keep remaining predictors as explicit synthetic stubs until their corpora are built.

Results¶

Command:

PYTHONPATH=tools/vmaf-tune/src .venv/bin/python -m vmaftune.predictor_train \
  --corpus runs/phase_a/full_grid/comprehensive.jsonl \
  --output-dir model \
  --codec h264_nvenc --codec hevc_nvenc --codec av1_nvenc \
  --codec h264_qsv --codec hevc_qsv --codec av1_qsv \
  --epochs 200 --batch-size 64

Held-out metrics:

The metrics are intentionally not made to look stub-perfect. These are real-corpus replacements with honest validation numbers; the mandatory verify pass in vmaf-tune fast remains the guardrail.

Alternatives Considered¶

References¶

• req: "then well yeah do the real weights, we can train everything on this machine"
• req: "more than half of tune is a scaffold"
• runs/phase_a/full_grid/comprehensive.jsonl (local, gitignored)
• tools/vmaf-tune/src/vmaftune/predictor_train.py