feat(tune): vmafx-tune Go Stage 2 — ladder subcommand (ADR-0730)#49
Open
lusoris wants to merge 1 commit into
Open
feat(tune): vmafx-tune Go Stage 2 — ladder subcommand (ADR-0730)#49lusoris wants to merge 1 commit into
lusoris wants to merge 1 commit into
Conversation
lusoris
force-pushed
the
feat/vmafx-tune-go-stage2-20260528
branch
from
24306b5 to
dd8ccf5
Compare
Ports the per-title ABR bitrate-ladder generator from Python to Go as
the Stage-2 subcommand of vmafx-tune-go (following Stage-1 compare).
New package pkg/ladder/:
- Build(src, encoder, Params) — samples a (resolution x VMAF-target)
grid via an injectable SamplerFn, computes the upper convex hull
(Pareto frontier), selects knee renditions via Kneedle perpendicular-
distance recursion, and applies a min-bitrate-gap filter.
- Unit-testable without ffmpeg or vmaf on PATH (SamplerFn seam).
New subcommand cmd/vmafx-tune/cmd/ladder.go:
- Wires bisect.Run as the production sampler for each grid cell.
- Supports all hardware encoders (NVENC, QSV, AMF, SVT-AV1) via
encoder.NewExtended, not just Stage-1 libx264/libx265.
- JSON output (schema_version:1) is a superset of Python ladder.py
output; Markdown output mirrors ladder.py _emit_markdown.
Six deep-dive deliverables (ADR-0108):
(a) no digest needed: continues ADR-0705 Stage-1 playbook
(b) ADR-0730 Alternatives considered: bisect vs tune-per-shot vs report
first; sequential vs concurrent sampling; resolution scaling scope
(c) AGENTS.md updated: Stage-2 SamplerFn seam (inv. 7-10), Stage-3
contract
(d) Reproducer: go test ./pkg/ladder/... ./cmd/vmafx-tune/...
(e) changelog.d/added/vmafx-tune-go-stage2.md
(f) docs/rebase-notes.md entry
Per-surface docs: docs/usage/vmafx-tune-go.md updated with ladder
flags, output schema, and Go-vs-Python behavioural differences table.
Also: .markdownlint.json disables MD040/MD060 (IDE-only warnings,
not enforced by make lint or CI).
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
lusoris
force-pushed
the
feat/vmafx-tune-go-stage2-20260528
branch
from
dd8ccf5 to
d9de1ef
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
the Stage-2 subcommand of
vmafx-tune-go.pkg/ladder/implements convex hull (Pareto frontier) +Kneedle knee selection + min-bitrate-gap filter; unit-testable without
ffmpeg or vmaf on PATH via
SamplerFninjection.vmafx-tune-go ladderwiresbisect.Runas theproduction sampler; supports all hardware encoders (NVENC, QSV, AMF,
SVT-AV1) via
encoder.NewExtended.schema_version:1) is a superset of Pythonladder.pyoutput; Markdown output mirrors
ladder.py _emit_markdown.ladderremoved from the stub list inroot.go; stubs updated to"Stage 3+" messaging.
Deep-dive deliverables (ADR-0108)
## Alternatives considered(bisect vs tune-per-shot vs report first; sequential vs concurrent; resolution scaling scope)cmd/vmafx-tune/AGENTS.mdinvariants 7–10 (SamplerFn seam, ladder JSON schema forward-compat, Stage-2 resolution note, Stage-3 contract)go test ./pkg/ladder/... ./pkg/bisect/... ./pkg/encoder/... ./cmd/vmafx-tune/...changelog.d/added/vmafx-tune-go-stage2.mddocs/rebase-notes.md— no upstream impact; Pythonladder.pyhull/knee divergence points documentedPer-surface docs (ADR-0100 / CLAUDE §12 r10)
docs/usage/vmafx-tune-go.mdupdated:ladderflags table, outputschema example, Go-vs-Python behavioural differences table, updated
migration roadmap (Stage 1 → Stage 5).
ffmpeg-patches impact
no rebase impact: no public C-API or header changes; pure Go addition
state.md
no state.md update needed: no bug opened, closed, or ruled not-affecting
Test plan
go test ./pkg/ladder/...— all unit tests pass without ffmpeg/vmafgo test ./cmd/vmafx-tune/...— build + flag tests passvmafx-tune-go ladder --help— lists all flags including--max-rungs,--min-bitrate-gapvmafx-tune-go ladder --reference src.mp4 --codec libx264 --targets 75,85,95 --resolutions 320x240,1280x720 --output ladder.json— emits valid JSON withschema_version:1vmafx-tune-go tune-per-shot— still exits non-zero with redirect messagevmafx-tune-go compare --reference src.mp4 --codecs libx264 --targets 85— compare still works🤖 Generated with Claude Code