3b6fd99989
WAI is a container + capability-dispatch standard for media. It does not re-implement codecs; it dispatches to SOTA standard libraries (PNG, FLAC, zstd as the mandatory floor; AVIF, JPEG-XL, Opus, AV1, XZ as the recommended modern set) and adds an envelope that lets a neural shared-prior path coexist with the model-free floor. The capability a file requires is named, not supplied. Two paths open every conforming file: the neural condition (sink regenerates from a shared ambient prior) and the zeroth condition (registered SOTA codec menu). Apache-2.0. Adds: - wai/SPEC.md — WAI v1.0 spec (envelope, manifest, capability dispatch, registered capabilities including v1.1 multi-rendition extension) - wai/wai-rs/ — Rust reference implementation: lib + cdylib + staticlib, C FFI, 11 capability + envelope round-trip tests passing - wai/wai-web/ — wasm-bindgen wrapper for browser sinks - wai/wai-neural/ — Python tooling for neural-condition models - wai/tools/ — codec export + encode helpers (Python) - wai/corpus/CORPUS.md — third-party test corpus reacquisition guide Updates README.md to list four standards instead of three. Known consumer: CommunicationOS uses WAI for media transport over MoQT/MLS sessions. Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
94 lines
3.6 KiB
Markdown
94 lines
3.6 KiB
Markdown
# Contributing to WAI
|
|
|
|
WAI has two layers — a spec and a reference implementation. The
|
|
contribution paths are different.
|
|
|
|
## To the spec (`SPEC.md`)
|
|
|
|
Open for revision. WAI is a v1.0 **draft**; until it freezes at v1.0
|
|
final, substantive changes are welcome.
|
|
|
|
A spec change is in scope if it:
|
|
|
|
- Names a real-world ambiguity in the existing text (point at the
|
|
section and the case that breaks).
|
|
- Adds a missing structural requirement (byte layout, conformance rule,
|
|
dispatch behavior) needed to make a third implementation falsifiable.
|
|
- Tightens the capability-dispatch or container semantics.
|
|
- Adds a new codec or capability — with a byte-precise wire definition
|
|
and cross-implementation fixtures, not a placeholder.
|
|
|
|
A spec change is out of scope if it:
|
|
|
|
- Adds optional fields with no testable conformance impact. WAI leans
|
|
toward fewer well-defined fields.
|
|
- Re-litigates the capability-as-requirement model (§1 is intentional:
|
|
the model is named, never transported, never hash-pinned).
|
|
- Substitutes an existing primitive for a different one (e.g. another
|
|
entropy coder for rANS) without a concrete failure mode in the
|
|
existing one.
|
|
|
|
How to propose a change: open a draft in a parallel `SPEC-vX-draft.md`,
|
|
quote the section it modifies, and regenerate + run the
|
|
cross-implementation conformance suite (below) to show the change does
|
|
not regress the two reference implementations.
|
|
|
|
## To the reference implementations
|
|
|
|
Code is Apache-2.0. There are two interoperable references:
|
|
|
|
- **`wai/`** — Python, readability-first. Container, static rANS,
|
|
`entropy_zeroth`, and the image/audio/video zeroth codecs;
|
|
`python -m wai encode|play`. Neural paths (EnCodec, TAESD) live here
|
|
and are out of scope for byte-level conformance (the model is a
|
|
requirement, not part of the standard).
|
|
- **`wai-rs/`** — Rust, performance + embeddability. Same wire format;
|
|
`wai` binary with `encode`/`play`.
|
|
|
|
The two MUST stay byte-interoperable on every lossless path. Before
|
|
submitting:
|
|
|
|
```bash
|
|
# Rust: 10 library + 9 cross-Python conformance tests
|
|
cd wai-rs
|
|
cargo test
|
|
cargo build --release --bin wai
|
|
|
|
# Regenerate the canonical Python reference fixtures and re-check the
|
|
# Rust port still agrees byte-for-byte (run from the wai-rs root; the
|
|
# sibling `wai/` Python package must be importable)
|
|
python tests/gen_cross_fixtures.py
|
|
cargo test --test cross_python
|
|
```
|
|
|
|
Both must pass. The cross-Python suite is what catches wire drift
|
|
between the two implementations — it is the executable definition of
|
|
conformance for v1.0 (`SPEC.md` §9).
|
|
|
|
## A third implementation
|
|
|
|
Conformance is **cross-implementation byte-equivalence**, not "passes
|
|
its own tests." A new-language implementation is conformant when, given
|
|
the fixtures emitted by `wai-rs/tests/gen_cross_fixtures.py`, it
|
|
produces byte-identical output for the bit-exact paths (rANS,
|
|
`entropy_zeroth`, container) and reconstruction-equivalent output
|
|
(identical quantized arrays) for the lossy codecs (image 4:4:4 + 4:2:0,
|
|
audio MDCT, video I+P). Validate against the same fixtures the Rust
|
|
reference is held to.
|
|
|
|
A third implementation is in scope when it brings up a language
|
|
ecosystem that doesn't have one yet and is validated against those
|
|
fixtures. It is *not* in scope when it duplicates an existing reference
|
|
for ergonomic reasons; consolidate instead.
|
|
|
|
## License
|
|
|
|
By contributing, you agree your contribution is licensed under the same
|
|
terms as the corresponding layer:
|
|
|
|
- Contributions to the spec: published under the same open terms
|
|
(royalty-free; contributors grant patent rights for compliant
|
|
implementations).
|
|
- Contributions to either reference implementation: Apache-2.0.
|
|
|
|
No CLA. The license is the agreement.
|