iamf-sentinel-pro — L3 rendered QC plugin for iamf-sentinel

The free core (iamf-sentinel) reads the file. This plugin decodes it and measures the truth:

• L3 rendered QC — 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.
• Source-referenced ADM fidelity QC (adm-compare, S-33x) — compares an IAMF encode against its BW64/ADM master.
• Platform profile packs (e.g. YouTube ingest) with the loudness-measurement calibration that keeps correct files from being flagged at tight tolerances.

The core discovers this package by import (see PLUGIN_SEAM.md): its presence enables sentinel validate --l3, diff --render, adm-compare, and the profile packs in sentinel_pro/profiles/.

Free software, Apache-2.0.

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.

Install & backends

pip install iamf-sentinel-pro            # kernel-backed: no scientific stack required
pip install "iamf-sentinel-pro[numpy]"   # adds the numpy reference backend (quotes: zsh eats bare brackets)

Measurement runs on the compiled sentinel-dsp kernel when the binary is present ($SENTINEL_DSP explicit path, else $PATH; SENTINEL_DSP=off forces the reference path) or on the numpy reference implementation. A present-but-broken kernel is an execution error, never a silent fallback. adm-compare and diff --render always need the [numpy] extra.

Build the kernel:

cmake -S sentinel-dsp -B build -DCMAKE_BUILD_TYPE=Release && cmake --build build -j2

Every change to either measurement implementation is gated by the differential suite (sentinel-dsp/tests/differential.py + tests/test_dsp_backend.py).

L3 and adm-compare additionally need the reference toolchain (decoder_main / iamfdec) and, for adm-compare, EAR (ear-render). The OCI recipes under oci/ package the toolchain reproducibly; oci/layer-scan.py is the release-CI hygiene check.

Related projects

• iamf-sentinel — the free, stdlib-pure core this package plugs into (L1/L2 + CI contract)
• iamf-loom — manifest-driven IAMF packager; its validation gate uses this stack's measurement
• iamf-adm-corpus — synthetic ADM corpus + harness behind the adm-compare method
• iamf-sentinel-mcp — MCP server exposing the validator and packager to agent runtimes

License

Apache-2.0 (see LICENSE / NOTICE). This tree was designed as the commercial half of an open-core split; the project has since adopted a full open-source posture and both sides are Apache-2.0 — the plugin seam remains as architecture, not a license boundary. The measurement DSP (Python and C++), the ADM reader, and all checks are original clean-room works (ITU-R BS.1770-4, ITU-R BS.2088 / EBU Tech 3285, ISO/IEC 14496-12). Reference decoders and EAR are invoked only as subprocess oracles. Commercial support and consulting are available — see the core repo's SUPPORT.md.