Metadata-Version: 2.4
Name: iamf-sentinel-pro
Version: 0.3.1
Summary: Pro plugin for iamf-sentinel: L3 rendered QC (decoder oracles + BS.1770-4), ADM source-referenced fidelity QC, platform profile packs
Author: The iamf-sentinel authors
License: Apache-2.0
Keywords: iamf,immersive-audio,loudness,bs1770,adm,qc
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: iamf-sentinel>=0.3.0
Provides-Extra: numpy
Requires-Dist: numpy>=1.24; extra == "numpy"
Requires-Dist: scipy>=1.10; extra == "numpy"
Provides-Extra: test
Requires-Dist: pytest>=7; extra == "test"
Requires-Dist: numpy>=1.24; extra == "test"
Requires-Dist: scipy>=1.10; extra == "test"
Dynamic: license-file

# 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](DESIGN-NOTES.md)** explains the notation and indexes every cited document.

## Install & backends

```bash
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:

```bash
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`).

**Verified platforms.** Every push runs the Pro test suite on **Linux, macOS, and Windows**
against **Python 3.11 and 3.12** — [`ci.yml`](.github/workflows/ci.yml) is the claim; the matrix
is the evidence. That matrix covers the **Python** side of Pro; the C++ kernel and its
differential against `dsp.py` are gated separately, on Linux only, by
[`dsp-differential.yml`](.github/workflows/dsp-differential.yml) — a green matrix here says
nothing about the kernel, and vice versa. Oracle-gated, sample-gated and kernel-gated tests
skip in that environment by design, and on Windows so do the tests that depend on POSIX
executable semantics (shell stubs, `PATH` resolution of extensionless files). Nothing is
claimed for a platform that does not have a green leg.

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`](https://github.com/jlivingston-Cipher/iamf-sentinel) — the free, stdlib-pure
  core this package plugs into (L1/L2 + CI contract)
- [`iamf-loom`](https://github.com/jlivingston-Cipher/iamf-loom) — manifest-driven IAMF packager;
  its validation gate uses this stack's measurement
- [`iamf-adm-corpus`](https://github.com/jlivingston-Cipher/iamf-adm-corpus) — synthetic ADM
  corpus + harness behind the `adm-compare` method
- [`iamf-sentinel-mcp`](https://github.com/jlivingston-Cipher/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`.
