Repository navigation
docs(usage): document vmaf_vpl tool (ADR-0100 doc-substance bar) - #533
Merged
Merged
Conversation
docs/usage/vmaf-vpl.md was a partial stub with three inaccuracies: a non-existent --list-devices flag, incorrect --model semantics (it takes a built-in model name, not a file path), and an overstated input format claim (VPL only handles elementary streams, not generic FFmpeg-decodable containers). This commit corrects all three and brings the page to the ADR-0100 per-surface minimum bar: build prerequisites, input format section with pre-extraction commands, complete flags table with types/defaults, and a smoke invocation. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
lusoris
force-pushed
the
docs/vmaf-vpl-doc-substance
branch
from
June 3, 2026 12:47
0c0a493 to
1a2eb38
Compare
lusoris
marked this pull request as ready for review
June 3, 2026 12:47
There was a problem hiding this comment.
Pull request overview
This PR improves the vmaf_vpl usage documentation so it accurately reflects how the VPL-based developer tool is invoked and what inputs it accepts, and makes the page substantially more actionable for SYCL/VPL contributors.
Changes:
- Documented the elementary-stream-only input requirement and added FFmpeg pre-extraction examples.
- Replaced the stub flags list with a fuller flags table including types and defaults, and updated the smoke invocation accordingly.
- Clarified expected runtime behavior/output and the recommended
--fallbackdebugging path.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+63
to
+64
| --ref testdata/ref_576x324_48f.h265 \ | ||
| --dis testdata/dis_576x324_48f.h265 \ |
9 of 13 tasks
lusoris
added a commit
that referenced
this pull request
Sep 30, 2026
…ocumentation gate The standards gate now installs praetor main 25451d8 from the remote module proxy (PRAETOR_REF was f41e74d on master). Every praetor-managed file is regenerated with that engine's own code: adopt (with --verification-max-entries 200000), sync, compile-context and devcontainer --source-root at the pin, which keeps the vmafx-dev-mcp base image. Baseline (ADR-1351): f41e74d re-records 185 entries on this tree with no growth, 25451d8 records 431. All 246 new fingerprints are engine changes, replayed on the same tree against each commit's parent: d7a3778 adds 61 process exits from library code (Python 51, Go 5, Rust 5), 025bbc6 adds 142 long Python functions and 36 recursive ones, 53e7594 adds 7 Go calls without a deadline. They are recorded with --allow-increase and a reason. Documentation gate: praetor fixed cordanaLLM/praetor#532, #533 and #534, so the gate now passes here. .standards.yaml raises max_files to 8192 and max_file_bytes to 4 MiB, and style-excludes the generated ADR index, the ADR row fragments and testdata fixtures, the files the repository's own markdownlint hook already skips. The other 75 findings are fixed in the source: the 14 predictor model cards and their template in predictor_train.py (pinned by test_predictor_card_markdown.py), an MD013 re-enable in the SYCL overview and a fence language in the ADR fragments README. The figure engine under tools/figures/, the docs-figures target, a .gitattributes block and a workflow step arrive with it. Praetor defects, filed or tracked upstream and worked around here: - adopt still refuses to extend the Makefile block because of computed targets such as $(BUILD_DIR): (#537, open). GNU Make finds no docs-lint or docs-figures rule outside the block, so the block is praetor's own DocumentationMakefileBlock() text. - The repository-wide dist/ rule hid tools/figures/dist/; .gitignore re-includes it (#591). - black, ruff and markdownlint would rewrite or flag the locked figure engine; their pre-commit hooks skip tools/figures/ (#578). - Praetor requires the retired numbered workspace root to be ignored (#641, filed with this change). The ADR-1277 contract check accepts only that rule inside praetor's block, skips tools/markdownlint/ when scanning for references and still fails on a local directory. ADR-1351 amends ADR-1277. Also: repository.default_branch: master renders the ruleset for master; REUSE.toml labels the vendored interfig sources and the player bundle; adopt's praetorctl pre-tool hook registrations in .claude/settings.json, .codex/hooks.json and .gemini/settings.json are left out, since audit does not verify them and they change every agent session. T-PRAETOR-DOCS-GATE-LIMITS-2026-09-28 is closed. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
lusoris
added a commit
that referenced
this pull request
Sep 30, 2026
…ocumentation gate The standards gate now installs praetor main 25451d8 from the remote module proxy (PRAETOR_REF was f41e74d on master). Every praetor-managed file is regenerated with that engine's own code: adopt (with --verification-max-entries 200000), sync, compile-context and devcontainer --source-root at the pin, which keeps the vmafx-dev-mcp base image. Baseline (ADR-1351): f41e74d re-records 185 entries on this tree with no growth, 25451d8 records 431. All 246 new fingerprints are engine changes, replayed on the same tree against each commit's parent: d7a3778 adds 61 process exits from library code (Python 51, Go 5, Rust 5), 025bbc6 adds 142 long Python functions and 36 recursive ones, 53e7594 adds 7 Go calls without a deadline. They are recorded with --allow-increase and a reason. Documentation gate: praetor fixed cordanaLLM/praetor#532, #533 and #534, so the gate now passes here. .standards.yaml raises max_files to 8192 and max_file_bytes to 4 MiB, and style-excludes the generated ADR index, the ADR row fragments and testdata fixtures, the files the repository's own markdownlint hook already skips. The other 75 findings are fixed in the source: the 14 predictor model cards and their template in predictor_train.py (pinned by test_predictor_card_markdown.py), an MD013 re-enable in the SYCL overview and a fence language in the ADR fragments README. The figure engine under tools/figures/, the docs-figures target, a .gitattributes block and a workflow step arrive with it. Praetor defects, filed or tracked upstream and worked around here: - adopt still refuses to extend the Makefile block because of computed targets such as $(BUILD_DIR): (#537, open). GNU Make finds no docs-lint or docs-figures rule outside the block, so the block is praetor's own DocumentationMakefileBlock() text. - The repository-wide dist/ rule hid tools/figures/dist/; .gitignore re-includes it (#591). - black, ruff and markdownlint would rewrite or flag the locked figure engine; their pre-commit hooks skip tools/figures/ (#578). - Praetor requires the retired numbered workspace root to be ignored (#641, filed with this change). The ADR-1277 contract check accepts only that rule inside praetor's block, skips tools/markdownlint/ when scanning for references and still fails on a local directory. ADR-1351 amends ADR-1277. Also: repository.default_branch: master renders the ruleset for master; REUSE.toml labels the vendored interfig sources and the player bundle; adopt's praetorctl pre-tool hook registrations in .claude/settings.json, .codex/hooks.json and .gemini/settings.json are left out, since audit does not verify them and they change every agent session. T-PRAETOR-DOCS-GATE-LIMITS-2026-09-28 is closed. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
lusoris
added a commit
that referenced
this pull request
Sep 30, 2026
…ocumentation gate The standards gate now installs praetor main 25451d8 from the remote module proxy (PRAETOR_REF was f41e74d on master). Every praetor-managed file is regenerated with that engine's own code: adopt (with --verification-max-entries 200000), sync, compile-context and devcontainer --source-root at the pin, which keeps the vmafx-dev-mcp base image. Baseline (ADR-1351): f41e74d re-records 185 entries on this tree with no growth, 25451d8 records 431. All 246 new fingerprints are engine changes, replayed on the same tree against each commit's parent: d7a3778 adds 61 process exits from library code (Python 51, Go 5, Rust 5), 025bbc6 adds 142 long Python functions and 36 recursive ones, 53e7594 adds 7 Go calls without a deadline. They are recorded with --allow-increase and a reason. Documentation gate: praetor fixed cordanaLLM/praetor#532, #533 and #534, so the gate now passes here. .standards.yaml raises max_files to 8192 and max_file_bytes to 4 MiB, and style-excludes the generated ADR index, the ADR row fragments and testdata fixtures, the files the repository's own markdownlint hook already skips. The other 75 findings are fixed in the source: the 14 predictor model cards and their template in predictor_train.py (pinned by test_predictor_card_markdown.py), an MD013 re-enable in the SYCL overview and a fence language in the ADR fragments README. The figure engine under tools/figures/, the docs-figures target, a .gitattributes block and a workflow step arrive with it. Praetor defects, filed or tracked upstream and worked around here: - adopt still refuses to extend the Makefile block because of computed targets such as $(BUILD_DIR): (#537, open). GNU Make finds no docs-lint or docs-figures rule outside the block, so the block is praetor's own DocumentationMakefileBlock() text. - The repository-wide dist/ rule hid tools/figures/dist/; .gitignore re-includes it (#591). - black, ruff and markdownlint would rewrite or flag the locked figure engine; their pre-commit hooks skip tools/figures/ (#578). - Praetor requires the retired numbered workspace root to be ignored (#641, filed with this change). The ADR-1277 contract check accepts only that rule inside praetor's block, skips tools/markdownlint/ when scanning for references and still fails on a local directory. ADR-1351 amends ADR-1277. Also: repository.default_branch: master renders the ruleset for master; REUSE.toml labels the vendored interfig sources and the player bundle; adopt's praetorctl pre-tool hook registrations in .claude/settings.json, .codex/hooks.json and .gemini/settings.json are left out, since audit does not verify them and they change every agent session. T-PRAETOR-DOCS-GATE-LIMITS-2026-09-28 is closed. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
lusoris
added a commit
that referenced
this pull request
Sep 30, 2026
…ocumentation gate The standards gate now installs praetor main 25451d8 from the remote module proxy (PRAETOR_REF was f41e74d on master). Every praetor-managed file is regenerated with that engine's own code: adopt (with --verification-max-entries 200000), sync, compile-context and devcontainer --source-root at the pin, which keeps the vmafx-dev-mcp base image. Baseline (ADR-1351): f41e74d re-records 185 entries on this tree with no growth, 25451d8 records 431. All 246 new fingerprints are engine changes, replayed on the same tree against each commit's parent: d7a3778 adds 61 process exits from library code (Python 51, Go 5, Rust 5), 025bbc6 adds 142 long Python functions and 36 recursive ones, 53e7594 adds 7 Go calls without a deadline. They are recorded with --allow-increase and a reason. Documentation gate: praetor fixed cordanaLLM/praetor#532, #533 and #534, so the gate now passes here. .standards.yaml raises max_files to 8192 and max_file_bytes to 4 MiB, and style-excludes the generated ADR index, the ADR row fragments and testdata fixtures, the files the repository's own markdownlint hook already skips. The other 75 findings are fixed in the source: the 14 predictor model cards and their template in predictor_train.py (pinned by test_predictor_card_markdown.py), an MD013 re-enable in the SYCL overview and a fence language in the ADR fragments README. The figure engine under tools/figures/, the docs-figures target, a .gitattributes block and a workflow step arrive with it. Praetor defects, filed or tracked upstream and worked around here: - adopt still refuses to extend the Makefile block because of computed targets such as $(BUILD_DIR): (#537, open). GNU Make finds no docs-lint or docs-figures rule outside the block, so the block is praetor's own DocumentationMakefileBlock() text. - The repository-wide dist/ rule hid tools/figures/dist/; .gitignore re-includes it (#591). - black, ruff and markdownlint would rewrite or flag the locked figure engine; their pre-commit hooks skip tools/figures/ (#578). - Praetor requires the retired numbered workspace root to be ignored (#641, filed with this change). The ADR-1277 contract check accepts only that rule inside praetor's block, skips tools/markdownlint/ when scanning for references and still fails on a local directory. ADR-1351 amends ADR-1277. Also: repository.default_branch: master renders the ruleset for master; REUSE.toml labels the vendored interfig sources and the player bundle; adopt's praetorctl pre-tool hook registrations in .claude/settings.json, .codex/hooks.json and .gemini/settings.json are left out, since audit does not verify them and they change every agent session. T-PRAETOR-DOCS-GATE-LIMITS-2026-09-28 is closed.
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
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
docs/usage/vmaf-vpl.mdstub: removes a non-existent--list-devicesflag, corrects--modelsemantics (built-in name, not file path), and documents the elementary-stream-only input constraint (VPL does not demux containers).mkdocs.ymlnav so it is reachable from the site.ADR-0108 deliverables checklist
core/tools/vmaf_vpl.c), there is no design trade-off.vmaf_vpl.cis fork-local with no upstream counterpart../build/core/tools/vmaf_vpl --ref testdata/ref.h265 --dis testdata/dis.h265 --model vmaf_v0.6.1 --frames 48(requires SYCL build + Intel GPU).changelog.d/added/vmaf-vpl-doc-substance.mddocs/rebase-notes.md— no rebase impact: doc-only.State.md update
No bugs opened, closed, or ruled not-affecting — no state.md update required.
Test plan
mkdocs build --strictpasses (nav.omitted_files warning forvmaf-vpl.mdshould be gone).print_usage()incore/tools/vmaf_vpl.c(source of truth).🤖 Generated with Claude Code