feat(tools): vmaf-tune — NVENC adapters (h264/hevc/av1)

[lusoris]

Summary

• Adds three NVIDIA NVENC codec adapters (h264_nvenc, hevc_nvenc,
  av1_nvenc) to tools/vmaf-tune/'s codec-adapter registry. Hardware
  encoders are 10–100× faster than software at the cost of ~3–5 VMAF
  points at matched bitrate; the rate-distortion curve is
  codec-distinct, not codec-shifted, which is why NVENC ships as
  separate codec entries rather than a flag on the existing software
  adapters.
• Shared mnemonic preset map (ultrafast → p1, medium → p4,
  placebo → p7, …) and the [0, 51] constant-quantizer window
  live in tools/vmaf-tune/src/vmaftune/codec_adapters/_nvenc_common.py
  so the per-codec adapter files stay thin.
• Documentation: docs/usage/vmaf-tune.md gains a "Hardware encoders
  (NVENC)" section with the preset map and the speed/quality
  trade-off note.

Codec one-hot follow-up (separate PR)

fr_regressor_v2 currently uses a 6-slot codec one-hot. Adding
the three NVENC codecs (and the parallel software-codec adapter PRs
for x265 / svtav1 / libaom) pushes the natural slot count to ≥ 9,
with headroom for ≥ 12 once QSV / VAAPI follow.

The schema needs extending before training v2 on a corpus that
includes hardware codecs. Tracking this as a follow-up:

• The codec-adapter contract is unblocked here (this PR).
• The schema bump is gated on training corpus availability for the
  new codecs and is out of scope for this PR.
• ADR-0280 § Consequences captures the dependency.

Six ADR-0108 deliverables

• (1) Research digest: docs/research/0065-vmaf-tune-nvenc-adapters.md.
• (2) Decision matrix: in docs/adr/0290-vmaf-tune-nvenc-adapters.md § Alternatives considered.
• (3) AGENTS.md invariant note: tools/vmaf-tune/AGENTS.md updated to call out the NVENC family + the _nvenc_common.py shared-helper convention.
• (4) Reproducer / smoke-test command: cd tools/vmaf-tune && python -m pytest tests/ -q.
• (5) CHANGELOG fragment: entry under [Unreleased] § Added in CHANGELOG.md.
• (6) Rebase note: entry 0290 in docs/rebase-notes.md. Wholly fork-local — no upstream Netflix/vmaf path overlap.

Test plan

• cd tools/vmaf-tune && python -m pytest tests/ -q (71 tests pass).
• cd tools/vmaf-tune && python -m pytest tests/test_codec_adapter_nvenc.py -v (58-case parametrised suite).
• Smoke check: from vmaftune.codec_adapters import known_codecs, get_adapter; assert "h264_nvenc" in known_codecs(); assert get_adapter("h264_nvenc").nvenc_preset("medium") == "p4".
• Linters: ruff check tools/vmaf-tune/ clean; pre-commit black/isort/ruff clean.
• Docs render: docs/usage/vmaf-tune.md "Hardware encoders (NVENC)" section visible.

Hardware availability

• h264_nvenc: NVIDIA Kepler+ (most modern GPUs).
• hevc_nvenc: NVIDIA Maxwell 2nd-gen+ (GTX 960+).
• av1_nvenc: NVIDIA Ada Lovelace+ (RTX 40-series, L40, L4).

When FFmpeg returns Encoder X not found, the harness records
exit_status != 0 and skips scoring — partial corpora over a
heterogeneous fleet stay well-formed.

Refs

• ADR-0280 (this PR)
• ADR-0237 (parent — vmaf-tune umbrella spec)
• Companion research digest: docs/research/0065-vmaf-tune-nvenc-adapters.md

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Adds NVIDIA NVENC codec adapters to the tools/vmaf-tune/ Phase-A codec-adapter registry so the corpus generator can sweep hardware encoders (h264_nvenc, hevc_nvenc, av1_nvenc) using the same adapter contract as software encoders.

Changes:

• Introduces three new NVENC codec adapters plus a shared _nvenc_common.py helper for preset + CQ validation.
• Expands the codec-adapter registry and adds a dedicated parametrized pytest suite for NVENC adapter behavior.
• Updates fork documentation/records (ADR + research digest + rebase notes + usage docs + changelog) to describe the new adapters.

Reviewed changes

Copilot reviewed 14 out of 14 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
tools/vmaf-tune/src/vmaftune/codec_adapters/_nvenc_common.py	Shared NVENC preset mapping and CQ validation helpers.
tools/vmaf-tune/src/vmaftune/codec_adapters/{h264_nvenc,hevc_nvenc,av1_nvenc}.py	New per-codec NVENC adapter dataclasses wired to the shared helper.
tools/vmaf-tune/src/vmaftune/codec_adapters/init.py	Registers NVENC adapters in the Phase-A codec registry.
tools/vmaf-tune/tests/test_codec_adapter_nvenc.py	New parametrized smoke/contract tests for NVENC adapters.
tools/vmaf-tune/tests/test_corpus.py	Updates Phase-A registry assertions to include NVENC codecs.
tools/vmaf-tune/AGENTS.md	Notes invariants/expectations for codec adapters and shared helpers.
docs/usage/vmaf-tune.md	Adds an NVENC usage section (presets, CQ window, trade-offs).
docs/research/0065-vmaf-tune-nvenc-adapters.md	New research digest describing design rationale.
docs/adr/0290-vmaf-tune-nvenc-adapters.md	New ADR capturing the decision and consequences.
docs/adr/README.md	Adds ADR index row for ADR-0290.
docs/rebase-notes.md	Adds a fork-local rebase note entry for this change.
CHANGELOG.md	Adds an Unreleased entry describing the NVENC adapters.

Comments suppressed due to low confidence (1)

tools/vmaf-tune/src/vmaftune/codec_adapters/init.py:44

• CodecAdapter is used as the return type of get_adapter(), but the Protocol currently only declares data attributes; it doesn't declare the validate() method that corpus.iter_rows() calls on every adapter. This makes type checking / IDE usage inconsistent. Please add def validate(self, preset: str, value: int) -> None: (and optionally presets) to the protocol so it matches the adapter contract actually relied on by the harness.

>>>>>>> f3e73397 (feat(tools): vmaf-tune — NVENC adapters (h264/hevc/av1))
from .x264 import X264Adapter
from .x265 import X265Adapter


class CodecAdapter(Protocol):
    """Phase A codec-adapter contract (subset of the ADR-0237 sketch).

    Phase B+ extends with two-pass / log-parsing / per-shot emit hooks.
    """

    name: str
    encoder: str

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.