Code comments throughout cite an internal numbered design docset (doc NN), ADRs, and pre-registered expectation labels — DESIGN-NOTES.md explains the notation and indexes every cited document.
One line for CI: iamf-sentinel tells your pipeline whether an IAMF file is correct —
structurally, semantically, and against a platform profile — and returns a stable exit code and a
citable list of check IDs. Pure standard-library Python; drops into any CI job with no procurement,
no native build, no toolchain.
Scope. Checks are written against the AOM IAMF v1.1.0 specification and ISO/IEC 14496-12, and cross-checked against the AOM reference tools. The tool reads IAMF v2.0.0 streams, recognises its six profiles and checks their limits, and reads object-based elements and the v2.0.0 rendering settings (position definitions with their default positions, element gain offset, binaural filter profile) and checks them; positions over time and parameter blocks remain unvalidated. The tool is spec- and reference-validated, not platform-certified: a
--profilename (e.g.youtube) applies the publicly-known shape constraints for that target, not a guarantee of acceptance by that platform's private ingest pipeline. A clean report means "conformant to the spec and the references" — necessary, but not by itself sufficient for any given platform.
A syntactically valid, fully decodable IAMF file can ship with two height channels silently missing
and C/LFE duplicated into the surrounds — produced by plausible CLI usage, and passed clean by the
encoder, the muxer, and both AOM reference decoders. Nothing in the ecosystem flags it. This tool
does (check S-201). The encode side self-certifies and the content-QC burden falls entirely on
publishers who have had no tooling — this is that tooling, and it is free to run and free to cite.
pip install iamf-sentinel # pure stdlib, Python ≥ 3.11 — no third-party runtime depsVerified platforms. Every push runs the core test suite on Linux, macOS, and Windows
against Python 3.11 and 3.12 — ci.yml is the claim; the matrix
is the evidence. requires-python is >=3.11, but only the two versions above are measured, and
the sample-gated and plugin-gated tests skip in that environment by design. Nothing here is
claimed for a platform that does not have a green leg.
sentinel validate path/to/file.iamf # raw .iamf or IAMF-in-MP4
sentinel validate movie.mp4 --profile generic --format html -o report.html
sentinel validate file.iamf --format json # CI: machine-readable findings
sentinel batch ./deliverables # directory roll-up, worst-exit for CI
sentinel diff a.iamf b.mp4 # descriptor-structure diff (remux proof)
sentinel intent-compare sidecar.intent.json out.wav # Pro: intent sidecar vs delivered ADM
sentinel checks -v # list the stable check registryExit codes (the CI contract): 0 pass · 1 findings at/above threshold · 2 execution error.
--strict promotes WARN to failing. batch returns the worst exit across the tree.
→ Open the hosted inspector — no install, no account, nothing to upload.
The same core also runs client-side as a WASM inspector: a single self-contained HTML page
that validates and inspects an IAMF file in a browser tab. The file is parsed in-tab and never
leaves your machine — the page is static and has no server side. The hosted copy is
docs/index.html in this repository, built from this tree by
python3 wasm/make_inspector.py . — the build is byte-deterministic, so you can regenerate it and
confirm the page you are running is the code you are reading. A native-vs-browser differential gate
keeps the embedded core finding-identical to this package.
- L1 — structural (clean-room OBU parser, written from the AOM IAMF v1.1.0 and v2.0.0 specs). Every read is bounds-checked; truncated or fuzzed input yields a structured finding, never a crash (a 63k-call bounded-fuzz acceptance pass: no hangs, no uncaught exceptions).
- L2 — channel semantics (the corruption killer). Substream topology vs declared layout (coupled-pairs-first invariant; a scalable element layer by layer, each layer against what its layout adds to the layer below), coupled/mono sanity, ambisonics (N+1)²/ACN completeness, dropped/duplicated/spurious substreams, annotation-presence.
- Objects and rendering settings (
S-210…S-217). An object-based element's object count and configuration; that each object element's rendering settings carry a position definition of the right kind for its object count, with a default position in range; the element gain offset; reserved rendering values that make a parser ignore a Mix Presentation; for LPCM, that an object's substream carries one channel per object. Positions over time and parameter blocks are not validated. - Descriptor-level loudness & container checks that need no decoder. Unmeasured
0.0loudness, stereo-only loudness on multichannel programs, declared clipping, RFC 6381 codec-string casing, IAMF brand / fast-start / sample-entry, ISO-BMFFiacbextraction so L1/L2 run on IAMF-in-MP4 exactly as on raw.iamf. - The CI contract. Stable check-ID taxonomy (
S-1xxstructural /S-2xxsemantic /S-3xxloudness /S-4xxcontainer), FAIL/WARN/INFO severities,json | text | htmlreports, and a declarativegenericprofile. This is the surface you cite: "passes iamf-sentinelS-1xx…S-4xxat v0.5.0." (This example is version-coupled: it moves with every release.)
The core reads the file. The L3 rendered QC plugin decodes it and measures the truth (it is a separate package for architecture, not licensing: the core stays stdlib-pure and CI-frictionless; the decoder oracles, DSP, and their dependencies live behind the seam):
- Decode each mix presentation × declared layout through the reference decoders (as subprocess oracles) and measure BS.1770-4 integrated loudness and true peak with an independent, calibrated implementation — catching declared-vs-measured loudness lies that descriptor checks can't see.
- Channel-identity on decoded PCM — catches the pure essence-misroute corruption (descriptor-clean, PCM-scrambled) that even L2 cannot see from the bitstream alone.
- Platform profile packs (e.g. YouTube ingest) and the loudness-measurement calibration that keeps correct files from being flagged at tight tolerances.
sentinel validate --l3, diff --render, and batch --l3 activate automatically when the plugin is
installed; without it they print a one-line "requires iamf-sentinel-pro" notice and the free checks
still run. See the pro repo's
PLUGIN_SEAM.md
for the exact boundary.
fixtures/ ships the clean-room IAMF serializer, the mutation suite (topology / drop / dup /
ambisonics / truncation / objects and rendering settings), and the corpus generator — so you can reproduce every check and build your
own regression corpus. These are part of the free core on purpose: they make the checks auditable and
the check IDs trustworthy.
F_TO_CHECK.md maps the executed WP1/WP3 failure catalogue to the checks that catch each one —
the requirements trail and the acceptance test in one table.
iamf-sentinel-pro— L3 rendered-QC plugin: decoder oracles, BS.1770-4 measurement, ADM fidelity, platform profile packsiamf-loom— manifest-driven IAMF packager; every output is gated by this validatoriamf-adm-corpus— synthetic ADM corpus + harness (the input-side instrument; this validator is the output-side one)iamf-sentinel-mcp— MCP server exposing the validator and packager to agent runtimesInseglet— authoring-side companion: a native REAPER MCP extension that authors immersive masters (beds, ambisonics, ADM) and exports straight into this stack's packager, whose output this validator gates
Apache-2.0 (see LICENSE / NOTICE) — and not just this core: the whole stack is free
software under Apache-2.0 — this package, the iamf-sentinel-pro plugin (L3 rendered QC,
ADM fidelity, profile packs), the sentinel-dsp measurement kernel, and the Loom
manifest-driven packager. The parser and all checks are original clean-room works written
from the AOM IAMF v1.1.0 and v2.0.0 specs and ISO/IEC 14496-12; no reference-decoder or encoder source
is used or derived. Reference decoders are invoked only as subprocess oracles, and only by
the separate -pro plugin.
This is an independent project, not an AOM deliverable; "IAMF" appears throughout as descriptive nominative use of the format name, not as a product name.
Maintained best-effort; commercial support and consulting are available — see
SUPPORT.md.