Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
80 lines (60 loc) · 3.4 KB

CONTRIBUTING.md

File metadata and controls

80 lines (60 loc) · 3.4 KB
Raw

Contributing to rusty_av2d

Thanks for looking. This project has one unusual property that shapes every contribution: correctness is defined by byte-equality with the AVM reference decoder, not by tests we wrote ourselves.

The gate

Two things must pass before any change lands. Both are non-negotiable.

# 1. The conformance corpus — every clip must be byte-identical to the reference.
bash bench/conformance/run.sh

# 2. Unit and integration tests.
cargo test --release

run.sh decodes each clip in bench/conformance/corpus/ with this decoder and with the reference, then compares the raw output byte-for-byte. A single differing byte in a single frame fails the run. There is no tolerance, no PSNR threshold, and no "close enough".

You need the reference decoders

The corpus harness shells out to AOM's avmdec (and dav2d for streams it supports). Neither is vendored here — you have to build them yourself from their upstream repositories, and point the harness at them. Where the two oracles disagree, AVM wins: it is the normative implementation.

Adding a clip

New coverage is the most valuable contribution. bench/conformance/gen.sh mints a stream with the reference encoder and registers it:

python3 bench/conformance/mksrc.py sources/mysrc.yuv 432 240 8 7 420 8
bash bench/conformance/gen.sh myclip sources/mysrc.yuv 432 240 8 --enable-cdef=0

A clip earns its place if it exercises a tool, a format, or a geometry that no existing clip reaches. A clip that only re-covers ground is churn — the corpus runs on every change, so each addition is a permanent cost.

Debugging a divergence

When output diverges, do not start from the pixels. Pixel diffs tell you that you diverged, never where. The workflow that actually works:

  1. Compare pre-filter frames first. In-loop filters smear a single bad block across a wide area and will send you to the wrong place.
  2. Find the first divergent block in decode order, not raster order.
  3. Bisect the entropy stream. All tracing lives behind RUSTY_AV2D_DEBUG=1; the in-tree probes print the arithmetic-decoder state (rng, and dif where it matters) at partition, mode, and coefficient boundaries. Add the matching fprintf to AVM and diff the two traces line-for-line.
  4. Compare the full entropy state, never rng alone. Bypass and literal bits change dif and the bit counter while leaving rng untouched, so a real divergence can hide behind a matching rng for many symbols.

A geometry-correlated failure is almost never geometry math. It usually means the encoder selected a tool at that geometry which the corpus had never reached before — chase the first divergent symbol, not the spatial pattern.

Style

  • cargo fmt before committing; rustfmt.toml is checked in.
  • Match the surrounding code. The AV2 modules (src/av2_*.rs) carry dense reference citations in comments (avm reconinter.c:4106, dav recon_tmpl.c:2731). Keep that up — those citations are how the next person finds the ground truth.
  • Comments should state constraints the code cannot show. Don't narrate what the next line does.

Licensing

BSD-2-Clause, inherited from dav1d/rav1d and retained in full. Contributions are accepted under the same license. Do not paste code from AVM or any other reference implementation into this tree — it is used strictly as an external oracle. See NOTICE.md.