AV2 specification Markdown package

This repository converts the official AV2 Bitstream & Decoding Process Specification to section-split GitHub-flavored Markdown. Each release package includes every linked attachment, copied byte-for-byte from that release:

Package	Official source	Attachments
out_1.0/	https://av2.aomedia.org/v1.0.0/index.html	245
out_rc13/	https://av2.aomedia.org/v13-public/index.html	244

The .h attachments are normative specification table fragments, not standalone C compilation units. They retain the upstream formatting and contents. They are not generated from AVM. Release attachment URLs, byte lengths, and SHA-256 checksums are recorded in each package's attachments-manifest.json; existing Markdown links such as ./attachments/dct_kernel16.h resolve within the package. Upstream copyright and specification licensing statements remain in the release Markdown introduction/annexes.

Conversion and reproducibility

Use the pinned Nix development environment for all commands:

nix develop
python convert.py input_v1.0.0/index.html out_1.0/ \
  --source-url https://av2.aomedia.org/v1.0.0/index.html
python convert.py input_rc13/index.html out_rc13/ \
  --source-url https://av2.aomedia.org/v13-public/index.html

Obtain each input index.html from the corresponding official URL above. The converter discovers attachment links in the HTML before splitting sections. It first copies attachments beside the input HTML; otherwise it reuses locked output assets or downloads missing files from the explicitly supplied release URL. Paths and fragments are normalized for discovery; unsafe/non-relative attachment paths fail. Missing files, empty/HTML download responses, and locked checksum or source-release mismatches fail rather than producing a silently incomplete package. Transient HTTP failures are retried with bounded backoff.

An existing manifest locks the attachment set and exact bytes. Keep it when reproducing a release. A fresh package with no manifest records the obtained bytes; review that new manifest when intentionally packaging another release. For fully offline conversion, place the matching attachments/ directory beside the input HTML and retain the release manifest in the output directory.

To repair/package existing Markdown without reconverting it:

python attachments.py out_1.0 --source-url https://av2.aomedia.org/v1.0.0/index.html
python attachments.py out_rc13 --source-url https://av2.aomedia.org/v13-public/index.html

Verification

nix develop --command python -m unittest -v test_attachments
nix develop --command python attachments.py out_1.0 --verify
nix develop --command python attachments.py out_rc13 --verify
nix develop --command python verify_releases.py
nix develop --command python verify_avm.py /path/to/avm

The unit tests cover discovery/deduplication, path validation, byte-preserving copy/download, offline operation, missing assets, and manifest enforcement. --verify checks that every Markdown attachment target exists and matches its manifest hash, length, and provenance URL. verify_releases.py independently fetches both official HTML documents, compares their attachment sets with the checked-in Markdown, re-downloads every attachment against the manifest, and runs full conversion with local-copy packaging into temporary directories.

verify_avm.py reads Git objects at the exact matching AVM base revision 966a7d7cd6fcf60360caf5dc413b2aeeb65e144d, regardless of the AVM checkout's HEAD. It compares all 16 DCT16 rows with both forward/inverse matrices in av2/common/txb_common.c (including used rows 0 and 1), and all rows of:

• default_coeff_base_lf_eob_cdf.h: 80 rows;
• default_coeff_base_lf_cdf.h: 1,320 rows;
• default_coeff_br_lf_cdf.h: 56 rows.

CDF comparisons check cumulative thresholds, parameter indices decoded through the official para_adjustment_list.h, and initial counts against AVM's CDF/PARA initializers. This includes the TX16 EOB context 1 and DC base/BR contexts 1–3, BR EOB context 7, and all four quantizer buckets used by the bounded EOB2 generator. AVM inverse thresholds are 32768 - cumulative_threshold; the terminal inverse threshold is zero. AVM is a cross-check only, never a source for packaged attachment bytes. These checks establish packaging and numeric table agreement; decoder acceptance and reconstructed-pixel verification are separate generator checks.

Verified provenance (2026-10-08)

All 489 linked files passed fresh official-download checksum verification and both full-converter integration checks. The official HTML SHA-256 values were:

• v1.0.0: b267c96181f40799ec1c866ca8de3e936804617b71ac19437430d516aa73f1e3
• rc13: ac50f11fe506142010cc2d640d9d55b71c22aaae6fbc6f23b611dbb9c2940e19

The AVM comparison above passed for every matrix entry and all 1,456 CDF rows. The first rc13 download attempt encountered HTTP 503; a subsequent bounded-retry run and the independent fresh-download verification completed successfully. git diff --check reports upstream trailing whitespace/blank EOF lines in some verbatim attachment files; these bytes are deliberately preserved and covered by their hashes. Authored code, documentation, and manifests pass that check.