@blockcast/mmt-container 0.1.0-main.149f78a4adae

package/README.md

@@ -0,0 +1,432 @@
+# @blockcast/mmt-container
+
+MMTP / LOC container parsing for MMT over MoQ and SSM multicast. This package sits one layer above the wire decoder: given raw MMTP packets from any transport (WebTransport, Direct Sockets API, AMT tunnel), it produces reassembled MFUs, decoded CMSF catalogs, FEC-decoded source blocks, and CMAF segments ready for `MediaSource.appendBuffer()`. It is the TypeScript counterpart of the Rust `mmt-container` crate and is used by the moqtail and hang-mmt-fec reference players.
+
+This package is **container-agnostic about the codec** (H.264/AVC, HEVC, AAC, Opus) and **transport-agnostic about how packets arrive** — `MmtpContainerParser` accepts any `Uint8Array`. FEC decode is delegated to `@blockcast/mmt-fec` (synchronous WASM) or `@blockcast/fec-worker` (off-main-thread).
+
+## Install
+
+```bash
+pnpm add @blockcast/mmt-container
+```
+
+ESM-only (`"type": "module"`). Node 18+ or any modern browser. No CommonJS build is shipped — consumers must use `import`.
+
+## Quick start
+
+```ts
+import {
+  MmtpContainerParser,
+  MmtpToCmaf,
+  FECManager,
+  parseTrackRole,
+  resolveGroupDurationTicks,
+} from "@blockcast/mmt-container"
+
+// 1. Validate the catalog and pull track roles (Phase 14 convention)
+const role = parseTrackRole("video/base") // → "base"
+
+// 2. Wire the parser. mfuTimeoutMs is REQUIRED — derive from FEC
+//    interleaveDepthMs or frame duration; do not let it default.
+const parser = new MmtpContainerParser({
+  mfuTimeoutMs: 500,
+  defaultTrack: { type: "video", codec: "avc1.640033" },
+  reorderWindow: 8,
+})
+
+// 3. Optional: per-track FEC decoder (RaptorQ via @blockcast/mmt-fec)
+const fec = new FECManager()
+fec.configure({ k: 32, symbolSize: 1312, interleaveDepthMs: 1000, fps: 30 })
+
+// 4. CMAF wrapper for MSE
+const cmaf = new MmtpToCmaf()
+parser.onFrame((data, meta) => {
+  if (meta.trackType === "video") {
+    const segment = cmaf.wrapVideoSample(data, meta.timestamp, meta.keyframe)
+    sourceBuffer.appendBuffer(segment)
+  }
+})
+
+// 5. Feed raw MMTP packets from any transport
+transport.onPacket = (pkt: Uint8Array) => parser.feed(pkt)
+```
+
+For two-phase operation (parse header → feed FEC → emit frame) see `MmtpRouter` and `MmtpDecodePipeline`; both are exported from this package.
+
+## Exports
+
+The package exposes a wide subpath surface so consumers can tree-shake aggressively. Every entry mirrors `package.json#exports`.
+
+| Subpath | What you get |
+|---------|--------------|
+| `@blockcast/mmt-container` | Container, reassembly, catalog, and routing APIs (`src/index.ts`) |
+| `./browser-runtime` | Self-contained browser ESM bundle for pages that do not provide an import map |
+| `./mfu` | `MFUReassembler` for fragmented MFUs (FI=1/2/3) |
+| `./loc` | LOC FEC extension headers (`FecSourceInfo`, `AuthTag`) |
+| `./codec-utils` | H.264 helpers — Annex-B ↔ AVCC, SPS/PPS extraction, `mmtpTimestampToMicros`, ADTS wrap |
+| `./fec-manager` | `FECManager` — per-track FEC decoder lifecycle (sync WASM + Worker variants) |
+| `./mmtp-router` | `MmtpRouter` — packet routing with two-phase FEC feed |
+| `./multicast-transport` | `MulticastTransport` — `window.multicast` gateway `subscribe({ consume: 'bytes' })` wrapper |
+| `./multicast-manager` | `MulticastManager` — backwards-compat facade composing transport + router + FEC |
+| `./media-router` | `MediaRouter` — MoQ ↔ multicast source arbitration + base/delta migration |
+| `./multicast-unwrap` | Container-aware MMTP dispatch (LOC vs raw MMTP) |
+| `./signaling` | Packet-type classifier (`isSignalingPacket`, `isSourcePacket`, `classifyPacket`) |
+| `./mmtp-container-parser` | `MmtpContainerParser` (the unified, transport-agnostic parser) |
+| `./fec-codec` | Algorithm-pluggable codec interface — `NoneCodec`, `ReedSolomonCodec`, `createFecCodec` |
+| `./cmcd-producer` | `CmcdProducer` — RFC 9559 CMCD with `x-bc-*` vendor keys |
+| `./cmaf-block-assembler` | `CmafBlockAssembler` — assembles one CMAF segment per FEC source block |
+| `./cmaf-group-batcher` | `CmafGroupBatcher` — MoQ group → CMAF segment batcher |
+| `./carp-catalog` | CARP / CMSF catalog types, track-role parser, switching-set validator, track-timing |
+| `./catalog-validator` | `createCatalogSchemaValidator` — compiles the published schema with package-defined semantic keywords installed |
+| `./switching-set-alignment` | Cross-track group alignment helpers |
+| `./phase14-catalog-override` | Test-harness catalog override hook (`globalThis.__PHASE14_CATALOG_OVERRIDE`) |
+| `./align` | Group-id derivation (`groupIdForTicks`, `groupIdFor`, `driftCheck`) — shared with Go sender + Rust relay |
+| `./mmtp-decode-pipeline` | `MmtpDecodePipeline` — unified MoQ + multicast decode path |
+| `./mmtp-to-cmaf` | `MmtpToCmaf` + standalone segment builders (`encodeMultiSampleSegment`, `buildVideoInitSegment`, `generateGreenFillNAL`, `generateSilenceFrame`) |
+| `./track-pipeline-setup` | `setupTrackPipeline` — shared wiring for both reference players |
+| `./track-session` | `TrackSession` + `SessionManager` — per-track state machine (Patent Claim 9) |
+
+## Components
+
+### MMTP parser (`@blockcast/mmt-base`)
+
+The low-level ISO/IEC 23008-1 packet parser belongs to the dependency leaf
+`@blockcast/mmt-base`, not this package. Import it directly for MMTP headers,
+MPU/MFU extraction, payload IDs, and AL-FEC signaling. Import strict RFC 6330
+OTI helpers from `@blockcast/mmt-fec`; the obsolete container and mmt-base OTI
+paths have been removed.
+
+Key exports:
+
+```ts
+interface MMTPHeader {
+  version: number
+  packetType: number          // 0x00=MPU, 0x02=Signaling, 0x03=Repair
+  packetId: number
+  timestamp: bigint
+  sequenceNumber: number
+  payloadLength: number
+  fecType: number             // 0=none, 1=src+payloadId, 2=repair-mode-0, 3=repair-mode-1
+  rapFlag: boolean            // Random-access-point bit (keyframe)
+}
+
+function parseMMTPHeader(buf: Uint8Array): MMTPHeader
+function parseMPUHeader(buf: Uint8Array, offset: number): MPUHeader
+function extractMFUPayload(packet: Uint8Array): MFUExtraction | null
+function extractFecPayloadId(packet: Uint8Array): { ssId: number } | null
+function extractRepairFecPayloadId(packet: Uint8Array): RepairFecId | null
+function parseAlFecMessage(buf: Uint8Array): AlFecConfig
+function parseMoqRepairFrame(buf: Uint8Array): MoqRepairFrame
+```
+
+Constants worth knowing: `MMTP_HEADER_SIZE = 12`, `MPU_HEADER_SIZE = 8`, `MFU_DU_HEADER_SIZE_TIMED = 14`, `PACKET_TYPE_MPU = 0x00`, `PACKET_TYPE_REPAIR = 0x03`, `ALFEC_MESSAGE_ID = 0x0203`, `FEC_CODE_RAPTORQ = 2`.
+
+```ts
+import { parseMMTPHeader, extractMFUPayload } from "@blockcast/mmt-base"
+
+const hdr = parseMMTPHeader(packet)
+if (hdr.packetType === 0x00) {           // MPU
+  const mfu = extractMFUPayload(packet)
+  console.log(`pkt ${hdr.packetId} seq=${hdr.sequenceNumber} keyframe=${hdr.rapFlag}`)
+}
+```
+
+### MFU reassembler (`./mfu`)
+
+Stateful reassembler for fragmented MFUs per ISO/IEC 23008-1:2023 §9.2.3.3 and the repository's contiguous-source producer profile. It partitions bounded continuation state by physical stream, MPU, and wrapping terminal source-packet sequence (`packet_sequence + fragment_counter`), queues FI=2/FI=3 by run and counter until FI=1 and any missing predecessor arrive, then propagates FI=1's intrinsic DU identity while draining the exact countdown. The terminal sequence is transport association only. ISO-permitted interleaving remains separated and incomplete; there is no scope, timestamp, SS_ID, or arrival-order fallback. Recovered packets use the authored u32 sequence from the reconstructed MMTP header.
+
+```ts
+interface MFUReassemblerOptions {
+  /** REQUIRED. null is clock-free reliable MoQ; otherwise derive a positive
+   *  deadline from datagram/FEC timing. */
+  timeoutMs: number | null
+  maxBuffered?: number  // default 100; shared active/continuation-only run cap
+}
+
+class MFUReassembler {
+  constructor(opts: MFUReassemblerOptions)
+  // null means valid incomplete input. Strict rejection throws
+  // MfuReassemblyError with a stable kebab-case code.
+  addFragment(frag: MFUFragment): ReassembledMFU | null
+  readonly stats: ReassemblerStats
+}
+```
+
+The constructor rejects non-null, non-finite, or non-positive deadlines. Reliable MoQ deliberately passes `null`; it does not invent a wall-clock timeout.
+
+### CARP / CMSF catalog (`./carp-catalog`)
+
+Validate the published catalog schema through the package API. The schema uses
+the package-defined `uniqueMulticastAuthTrackBindings` keyword to reject reused
+`(mediaTrack, sourceSymbolFormat)` bindings, so compiling the JSON with a bare
+JSON Schema validator is not supported.
+
+```ts
+import schema from "@blockcast/mmt-container/catalog.schema.json" with { type: "json" }
+import { createCatalogSchemaValidator } from "@blockcast/mmt-container/catalog-validator"
+
+const validateCatalog = createCatalogSchemaValidator(schema)
+if (!validateCatalog(catalog)) {
+  throw new Error(JSON.stringify(validateCatalog.errors))
+}
+```
+
+Implements `draft-law-ramadan-moq-carp-reliability` §3 (FEC), §4 (multicast endpoints), and `draft-ramadan-moq-mmt-00` §4.4.4 (track timing). Plain TypeScript interfaces with type guards — no Zod, no runtime schema dependency. Upstream Zod schemas should derive from these via `z.infer<>`.
+
+```ts
+type FecAlgorithm = "none" | "raptorq" | "reed-solomon"
+
+interface FecCatalogConfig {
+  algorithm: FecAlgorithm        // §3.1
+  sourceSymbols: number          // K (REQUIRED)
+  repairSymbols: number          // P (REQUIRED)
+  symbolSize: number             // T, 8-byte aligned (REQUIRED)
+  interleaveDepthMs?: number     // FEC block span in MILLISECONDS, default 0 (single-group blocks)
+  repairTrack: string            // §6.1 — required
+  mode?: "interleaved" | "object"
+  uep?: { keyRatio: number; deltaRatio: number }   // §9.1 — Unequal Error Protection
+  deltaFailWindowBlocks?: number                   // D-11, base track only
+  deltaProbeIntervalMs?: number                    // D-13, base track only
+}
+
+interface MulticastEndpoint {
+  protocol: "ssm" | "asm" | "amt"
+  sourceAddress?: string         // REQUIRED for SSM
+  groupAddress: string
+  port: number
+  tracks: string[]
+  relayAddress?: string          // REQUIRED for AMT
+}
+
+interface TrackTimingConfig {
+  groupDurationMs: number          // REQUIRED, positive integer
+  groupDurationTicks?: number      // override when ms × timescale isn't integer
+}
+
+function isFecCatalogConfig(x: unknown): x is FecCatalogConfig
+function isMulticastCatalogConfig(x: unknown): x is MulticastCatalogConfig
+function resolveGroupDurationTicks(timing: TrackTimingConfig, timescale: number): number
+function validateSwitchingSetTiming(...): { ok: true } | { ok: false; ... }
+```
+
+#### Track-role convention (Phase 14)
+
+This is **project-specific**, not in any IETF draft yet. The container's switching-set parser derives its internal role from the last `/`-segment of a track name. MMTP catalogs may also carry the publisher-owned `trackRole` dispatch tag; the canonical schema validates it as a non-empty string. `parseTrackRole` remains the name-based helper for base/delta/repair switching sets (`carp-catalog.ts:41-79`):
+
+| Track name suffix | Role | Use |
+|-------------------|------|-----|
+| `video/base` | `base` | I-frame-only leg, always-on multicast |
+| `video/delta` | `delta` | P/B-frame leg, multicast + NACK repair |
+| `video/repair` | `repair` | FEC repair-symbol leg, cross-CDN federated |
+| `video` (no slash) | `single` | Legacy single-track stream (D-04) |
+
+Empty names, unknown suffixes, trailing slashes, and any non-ASCII / control characters all throw at parse time (T-14-01 fuzz hardening at `carp-catalog.ts:49-57`). Multi-track switching sets must include all three roles or `validateSwitchingSet` reports the missing roles.
+
+```ts
+import { parseTrackRole, validateSwitchingSet } from "@blockcast/mmt-container/carp-catalog"
+
+parseTrackRole("video/base")     // "base"
+parseTrackRole("video")          // "single" (legacy)
+parseTrackRole("video/foo")      // throws "unknown role suffix"
+
+validateSwitchingSet(["v/base", "v/delta", "v/repair"])  // { ok: true }
+validateSwitchingSet(["v/base", "v/delta"])              // { ok: false, missing: ["repair"] }
+```
+
+### FEC manager (`./fec-manager`)
+
+Codec-agnostic FEC decode service. Owns per-track decoder instances (sync WASM via `@blockcast/mmt-fec`, async via `@blockcast/fec-worker`), tracks per-block source-symbol counts, manages block timeouts, and emits `onBlockComplete` / `onBlockFailed` / `onBlockRecovered`.
+
+```ts
+interface FECManagerConfig {
+  k?: number
+  symbolSize?: number     // T (bytes per symbol). NOT repair count.
+  interleaveDepthMs?: number // FEC block span in MILLISECONDS — see MIN_INTERLEAVE_DEPTH_MS in fec-manager.ts
+  fps?: number
+}
+
+class FECManager {
+  configure(cfg: FECManagerConfig): void
+  setFecDecoder(packetId: number, client: WasmFecDecoder, k: number): void
+  setWorkerDecoder(packetId: number, worker: FecWorkerClient): void
+  feedSourceSymbol(packetId: number, ssId: number, data: Uint8Array, ts: number): Uint8Array | null
+  feedRepairSymbol(packetId: number, ssStart: number, ssbLen: number, rsId: number, data: Uint8Array, ts: number): Uint8Array | null
+  readonly fecStats: FecStats
+  getBlockStates(): Array<{ sbn: number; state: "collecting" | "complete" | "failed"; ... }>
+  onBlockComplete: ((sbn: number, packetId: number) => void) | null
+  onBlockFailed: ((sbn: number) => void) | null
+  onBlockRecovered: ((sbn: number, pid: number, data: ArrayBuffer, meta: FrameMeta) => void) | null
+}
+```
+
+`FECManager.configure()` takes `symbolSize` (bytes per symbol, T). Repair count is a distinct parameter and must never be passed in its place.
+
+`interleaveDepthMs` is the full FEC block span in **milliseconds** per CARP §5.1, valid range 33 ms (interactive / gaming, `MIN_INTERLEAVE_DEPTH_MS`) to 10 000 ms (broadcast ATSC 3.0). `configure()` warns if a positive value below `MIN_INTERLEAVE_DEPTH_MS` (33) is passed — that is almost certainly a raw frame count, not milliseconds — and such sub-floor values never drive the block timeout (the established timeout is preserved instead of collapsing to ~0).
+
+This package depends on the FEC primitives from:
+- **`@blockcast/mmt-fec`** — RaptorQ WASM decoder + OTI codec + `computeFecTimeout`
+- **`@blockcast/fec-worker`** — Web Worker host, `FecWorkerClient`, `FecTrackStats`
+
+### MMTP → CMAF demux (`./mmtp-to-cmaf`)
+
+Converts reassembled MFU samples (raw codec data: AVCC NALUs, AAC ADTS-stripped, Opus packets) into ISO/IEC 14496-12 fMP4 segments (`moof` + `mdat`) suitable for `MediaSource.appendBuffer()`. ISOBMFF box construction is inline — no `mp4-muxer` / `mp4box.js` dependency.
+
+```ts
+class MmtpToCmaf {
+  setInitSegmentFromMpu(data: Uint8Array, isAudio: boolean): void
+  buildVideoInit(avcC: Uint8Array, w: number, h: number): void
+  buildAudioInit(sampleRate: number, channels: number, asc?: Uint8Array, timescale?: number): void
+  setAudioTimescale(timescale: number): void
+  wrapVideoSample(data: Uint8Array, ts: number, keyframe: boolean): Uint8Array
+  wrapAudioSample(data: Uint8Array, ts: number, sampleDuration?: number, compositionTimeOffset?: number): Uint8Array
+  wrapAudioSamples(samples: Array<{ data: Uint8Array; duration: number; compositionTimeOffset?: number }>, baseDecodeTime: number, trackId?: number): Uint8Array
+  readonly videoInitSegment: Uint8Array | null
+  readonly audioInitSegment: Uint8Array | null
+}
+```
+
+Standalone helpers exported from the same module:
+
+| Function | Purpose |
+|----------|---------|
+| `encodeDataSegment(...)` | Single-sample moof+mdat |
+| `encodeMultiSampleSegment(...)` | Multi-sample moof+mdat (one per FEC block — used by `CmafBlockAssembler`) |
+| `buildVideoInitSegment(avcC, w, h)` | ftyp + moov for AVC |
+| `buildAudioInitSegment(sampleRate, channels, asc?, timescale?)` | ftyp + moov for AAC / Opus |
+| `generateGreenFillNAL(avcC, w, h)` | Green-fill NAL when a FEC block fails (loss visible) |
+| `generateSilenceFrame(codec, sampleRate, channels)` | Audio silence frame for FEC-failed audio blocks |
+
+Per-track timestamp rebase (`#videoBaseTs` / `#audioBaseTs` at `mmtp-to-cmaf.ts:550-562`) prevents the negative-uint64 `tfdt` bug that kills Chromium MediaSource (`CHUNK_DEMUXER_ERROR_APPEND_FAILED`).
+
+### CMCD producer (`./cmcd-producer`)
+
+Transport-agnostic CMCD (Common Media Client Data) telemetry per **RFC 9559**. Maps `FecTrackStats` snapshots and `TransportSnapshot` state to `x-bc-*` vendor keys (proto tags 70-99). Does NOT call `fetch()` or write to QUIC — emits via two callbacks (`onCmcdParams` for MoQ SUBSCRIBE params; `onCmcdPost` for HTTP POST query strings).
+
+```ts
+class CmcdProducer {
+  constructor(opts: CmcdProducerOptions)
+  updateTransport(snapshot: TransportSnapshot): void
+  updatePlayMode(mode: "full" | "base-only" | "single-track"): void
+  updateDeltaFailRate(rate: number): void
+  incrementSwitchMiscount(): void
+  emitSwitchDrift(driftUs: number): void
+  onSnapshot(data: SnapshotData): void
+  onTransition(event: TransportTransitionEvent): void
+}
+```
+
+Vendor keys emitted (BLO-1044):
+
+| Key | Source | Notes |
+|-----|--------|-------|
+| `x-bc-fec-algo` | FEC config | `none` / `raptorq` / `reed-solomon` |
+| `x-bc-fec-k`, `x-bc-fec-p` | FEC config | source / repair counts |
+| `x-bc-fec-recovery` | `recoveryRate` | Block-level recovery, 4 decimal places |
+| `x-bc-scu` | green-fill count | Omitted when 0 |
+| `x-bc-alta-verified`, `x-bc-alta-failures` | ALTA stats | Omitted when ALTA disabled (D-09) |
+| `x-bc-transport` | `TransportSnapshot.transport` | `native` / `amt` / `moq` |
+| `x-bc-multicast-group`, `x-bc-multicast-source`, `x-bc-amt-relay` | endpoint | Omitted when null |
+| `x-bc-play-mode` | Phase 14 D-12 | `full` / `base-only` / `single-track` |
+| `x-bc-delta-fail-rate` | Phase 14 D-15 | 0..1, omitted on single-track |
+| `x-bc-switch-miscount`, `x-bc-switch-drift-us` | switching-set drift | One-shot for drift |
+| `x-bc-ct` | transport transition | `mc-start` / `mc-to-uc` / `amt-start` |
+
+All string values pass through `sanitize()` (T-06-01) — commas, `\r`, `\n` are stripped to prevent header injection.
+
+### Multicast transport (`./multicast-transport`)
+
+Thin wrapper around the lowercase `window.multicast` gateway. Calls `globalThis.multicast.subscribe({ group, source, port, consume: 'bytes' })`, listens for `"bytes"` events (`CustomEvent<ArrayBuffer>`) on the returned `EventTarget` subscription, pumps packets to a callback, runs a 5-second watchdog, and fires `onTakeover` once both video and audio are confirmed receiving.
+
+```ts
+class MulticastTransport {
+  static isAvailable(): boolean       // tests for window.multicast
+  constructor(onPacket: (pkt: Uint8Array) => void)
+  join(cfg: MulticastTransportConfig): Promise<boolean>
+  feedPacket(data: ArrayBuffer | Uint8Array): void   // for AMT / ASM injection
+  confirmVideo(): void
+  confirmAudio(): void
+  onTakeover(cb: () => void): void
+  onFailback(cb: () => void): void
+  dispose(): void
+  readonly stats: { packetsReceived: number; bytesReceived: number }
+}
+```
+
+Direct Sockets is Chrome-IWA-only. Outside an IWA context `isAvailable()` returns false and join() warns + returns false. AMT tunneling and unicast fallback are handled by `@blockcast/mmt-transport`, not by this transport class.
+
+## Track-role convention summary (Phase 14)
+
+The role suffix → role mapping is the load-bearing convention for every multi-track Blockcast stream. Quick reference:
+
+```
+{name}/base    → base    (always-on multicast, I-frames)
+{name}/delta   → delta   (multicast + NACK, P/B-frames)
+{name}/repair  → repair  (FEC repair-symbol track, cross-CDN federated)
+{name}         → single  (legacy single-track)
+```
+
+Why a name-based convention rather than a catalog field?
+- D-01: keeps CMSF wire format unchanged (no new field upstream of IETF MOQ)
+- D-02: subscription URLs and track names already encode the role
+- D-03: parsers fail loudly on unknown suffixes (`error on bad init`, no silent fallback)
+- D-05: a track has exactly one role — no multi-role arrays
+
+Roles are required by:
+- `MediaRouter` for base/delta source arbitration and base-only fallback (D-11)
+- `setupTrackPipeline` for per-role transport selection
+- The FEC pipeline for routing repair-track packets to repair-symbol decoders
+
+## DRM extension (planned, M7)
+
+`CMSFTrack` will gain an optional `contentProtection?: Array<{ schemeIdUri: string; value?: string; pssh?: string; defaultKeyId?: string }>` field as part of the v4 M7 milestone (Shaka MoQ-CMSF + DRM). It is additive — no wire-format change, no decoder change. Signaled values support Widevine / PlayReady / FairPlay / ClearKey via the standard DASH-IF `schemeIdUri` mapping. Decryption happens in browser MSE (Encrypted Media Extensions) or mobile MediaDrm; this package's job is signaling only.
+
+> **Upstream gap:** at the time of writing, the parent monorepo's
+> `.planning/reliable-multicast-M7-spec.md` referenced by the libmmt
+> README has not yet landed. M1-M4 specs exist; M7 is tracked in
+> `MILESTONES.md` and `ROADMAP.md` only.
+
+## Specifications
+
+- **ISO/IEC 23008-1:2023** — MPEG-H Part 1 (MMT)
+- **ISO/IEC 23008-1:2023/Amd 1:2025** — AL-FEC framework for MMT (`ALFEC_MESSAGE_ID = 0x0203`)
+- **ISO/IEC 14496-12** — ISOBMFF (consumed for fMP4 box construction in `mmtp-to-cmaf.ts`)
+- **draft-ietf-moq-catalogformat** — CMSF catalog (IETF MOQ WG)
+- **draft-law-ramadan-moq-carp-reliability** — CARP §3 (FEC) + §4 (multicast endpoints) + §5.1 (interleave units) + §6.1 (repair track)
+- **draft-ramadan-moq-mmt-00** — MMT-over-MoQ wire format (§4.4.4 group-duration signaling, §5.3 MMTP→CMAF mapping)
+- **draft-ramadan-moq-fec** — AL-FEC over MoQ (§7.1 LOC FEC Source Info: SBN(32)+ESI(32)+optional QUIC-varint length)
+- **RFC 6330** — RaptorQ Forward Error Correction (strict OTI codec in `@blockcast/mmt-fec`)
+- **RFC 9559** — CMCD (used by `CmcdProducer`)
+- **ATSC A/331** — Signaling, Delivery, Synchronization, Error Protection
+
+## Related packages
+
+| Package | Relationship |
+|---------|--------------|
+| `@blockcast/mmt-fec` | RaptorQ geometry, timeout, and OTI helpers. Direct dependency. |
+| `@blockcast/fec-worker` | Web-Worker-hosted FEC client (`FecWorkerClient`, `FecTrackStats`, `FrameMeta`, `FecBlockSnapshot`). Direct dependency. |
+| `@blockcast/mmt-transport` | Higher-level transport manager (MoQ + SSM + AMT + DRIAD). Consumes this package's parser. |
+| `@blockcast/mmt-base` | Canonical MMTP/MPU/MFU, AL-FEC signaling, and payload-boundary parser leaf. Direct dependency. |
+| `@blockcast/mmt-alta-parse` | ALTA sender-authentication trailer parser. Direct dependency. |
+| `@blockcast/mmt-render` | Reference renderer + `AudioRingBuffer` (canonical location). The `audio-ring-buffer` re-export here is deprecated. |
+
+## Testing
+
+```bash
+npm test          # vitest run
+npm run test:watch
+```
+
+Tests live in `src/__tests__/` and as inline `if (import.meta.vitest) {…}` blocks (e.g. `loc.ts:166`). Coverage includes:
+
+- MFU reassembly and container integration with the `@blockcast/mmt-base` parser
+- CARP catalog ingest + role parser (with T-14-01 fuzz cases)
+- Switching-set timing alignment
+- CMCD producer with synthesized `FecTrackStats`
+- `MmtpContainerParser` end-to-end with mock packets
+- `MmtpRouter` two-phase parsing + FEC feed
+- `MediaRouter` source arbitration + group drift
+- Worker-pipeline tests (`fec-manager.test.ts` exercises `FecWorkerClient` mocks for the Worker decode path)
+
+## License
+
+Apache-2.0 — see `LICENSE`.

package/dist/__tests__/test-utils.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Build a minimal MMTP source packet for testing.
+ * MMTP header (12 bytes) + MPU header (8 bytes) + optional MFU DU header (14 bytes) + video data + optional FEC ID (4 bytes)
+ */
+export interface BuildMmtpPacketOptions {
+    packetId?: number;
+    packetType?: number;
+    fecType?: number;
+    rapFlag?: boolean;
+    timestamp?: number;
+    sequenceNumber?: number;
+    fi?: number;
+    fragmentCounter?: number;
+    mpuSeq?: number;
+    fragmentType?: number;
+    timedFlag?: number;
+    includeMfuDuHeader?: boolean;
+    payloadLength?: number;
+    videoData?: Uint8Array;
+    appendFecId?: boolean;
+    ssId?: number;
+    movieFragmentSequenceNumber?: number;
+    sampleNumber?: number;
+    sampleOffset?: number;
+    priority?: number;
+}
+export declare function buildMmtpPacket(opts: BuildMmtpPacketOptions): Uint8Array;
+/** Build AVCC NAL unit: 4-byte length prefix + NAL header byte + payload.
+ *  nalType=5 → IDR (keyframe), nalType=1 → P-frame (delta). */
+export declare function makeAvcc(nalType: number, payloadSize?: number): Uint8Array;
+/** Build HEVC NAL unit: 4-byte length prefix + 2-byte NAL header.
+ *  hevcType in range 16-21 → IRAP (keyframe). */
+export declare function makeHevc(hevcType: number, payloadSize?: number): Uint8Array;
+export interface TestIsoBmffInitializationOptions {
+    trackId?: number;
+    timescale?: number;
+    defaultSampleDuration?: number;
+    defaultSampleSize?: number;
+    handlerType?: 'vide' | 'soun';
+}
+/** Build current-profile single-track FT=0 timing metadata for parser tests. */
+export declare function buildTestIsoBmffInitialization(options?: TestIsoBmffInitializationOptions): Uint8Array;
+export interface TestIsoBmffMovieFragmentOptions {
+    trackId?: number;
+    movieFragmentSequenceNumber?: number;
+    decodeTime?: bigint;
+    sampleSizes: readonly number[];
+    sampleDurations?: readonly number[];
+    compositionOffsets?: readonly number[];
+    mdatPrefix?: Uint8Array;
+}
+/** Build current-profile FT=1 moof + declared mdat prefix for parser tests. */
+export declare function buildTestIsoBmffMovieFragment(options: TestIsoBmffMovieFragmentOptions): Uint8Array;
+export interface TestMmtpTimingPacketOptions {
+    packetId?: number;
+    mpuSequenceNumber?: number;
+    movieFragmentSequenceNumber?: number;
+    sampleSizes: readonly number[];
+    decodeTime?: bigint;
+    timescale?: number;
+    defaultSampleDuration?: number;
+    sampleDurations?: readonly number[];
+    compositionOffsets?: readonly number[];
+    handlerType?: 'vide' | 'soun';
+}
+/** Build the canonical FT=0 and FT=1 packets required before timed FT=2. */
+export declare function buildTestMmtpTimingPackets(options: TestMmtpTimingPacketOptions): {
+    initialization: Uint8Array;
+    movieFragment: Uint8Array;
+};
+//# sourceMappingURL=test-utils.d.ts.map

package/dist/__tests__/test-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-utils.d.ts","sourceRoot":"","sources":["../../src/__tests__/test-utils.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,EAAE,CAAC,EAAE,MAAM,CAAA;IACX,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,kBAAkB,CAAC,EAAE,OAAO,CAAA;IAC5B,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,SAAS,CAAC,EAAE,UAAU,CAAA;IACtB,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,2BAA2B,CAAC,EAAE,MAAM,CAAA;IACpC,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,sBAAsB,GAAG,UAAU,CAkExE;AAED;+DAC+D;AAC/D,wBAAgB,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,SAAI,GAAG,UAAU,CASrE;AAED;iDACiD;AACjD,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,SAAI,GAAG,UAAU,CAOtE;AA8CD,MAAM,WAAW,gCAAgC;IAC/C,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,qBAAqB,CAAC,EAAE,MAAM,CAAA;IAC9B,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B,WAAW,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;CAC9B;AAED,gFAAgF;AAChF,wBAAgB,8BAA8B,CAC5C,OAAO,GAAE,gCAAqC,GAC7C,UAAU,CA+BZ;AAED,MAAM,WAAW,+BAA+B;IAC9C,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,2BAA2B,CAAC,EAAE,MAAM,CAAA;IACpC,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,WAAW,EAAE,SAAS,MAAM,EAAE,CAAA;IAC9B,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IACnC,kBAAkB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IACtC,UAAU,CAAC,EAAE,UAAU,CAAA;CACxB;AAED,+EAA+E;AAC/E,wBAAgB,6BAA6B,CAC3C,OAAO,EAAE,+BAA+B,GACvC,UAAU,CAoDZ;AAED,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B,2BAA2B,CAAC,EAAE,MAAM,CAAA;IACpC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAA;IAC9B,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,qBAAqB,CAAC,EAAE,MAAM,CAAA;IAC9B,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IACnC,kBAAkB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IACtC,WAAW,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;CAC9B;AAED,4EAA4E;AAC5E,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,2BAA2B,GAAG;IAChF,cAAc,EAAE,UAAU,CAAA;IAC1B,aAAa,EAAE,UAAU,CAAA;CAC1B,CA+BA"}

package/dist/align.d.ts

@@ -0,0 +1,148 @@
+/**
+ * Shared group-alignment primitive for MMT over MoQ switching sets.
+ *
+ * Pure math — no MMT wire parsing, no CMCD, no I/O. Callers wire the output
+ * into their own drift-observation plumbing (see media-router.ts for the
+ * libmmt wiring).
+ *
+ * ──────────────────────────────────────────────────────────────────────────
+ * Contract (integer-ticks form, authoritative):
+ *
+ *     groupId = ticks < 0  ?  0  :  floor(ticks / groupDurationTicks)
+ *
+ * Where `ticks` is a media timestamp expressed at the catalog's `timescale`
+ * (Hz), and `groupDurationTicks = groupDurationSec * timescale`.
+ *
+ * Integer math means there is no epsilon and no float rounding to reason
+ * about. The seconds-form wrapper `groupIdFor(Seconds, seconds)` exists for
+ * legacy callers but converts to ticks internally.
+ *
+ * Every sender/receiver that emits or consumes MoQ groups from an MMT or
+ * CMAF switching set MUST derive groupId from this formula so that base,
+ * delta, and repair tracks agree on the group boundary for a given media
+ * timestamp across languages and processes.
+ *
+ * Test vectors that exercise the contract live at
+ * `packages/container/test-vectors/align.json`; the Go and Rust siblings
+ * load the same fixture so cross-language agreement is executable, not
+ * prose. **Formula changes require updating the fixture AND all three
+ * sibling implementations in the same release** — divergence between
+ * sender/relay/receiver is worse than any formula change.
+ *
+ * Canonical implementations:
+ *   Go:   Blockcast/multicast `cmd/caddy/sender/group_align.go`
+ *         (commit 104eeff) — sender-side groupId stamping on egress.
+ *   Rust: moqtail/moqtail `apps/relay/src/server/abr.rs`
+ *         (commit 39accbf; experimental branch, may be rebased — rely
+ *         on the SHA, not the branch name) — relay-side check.
+ *   TS:   THIS FILE (libmmt) — consumed by moq-lib + moqtail-ts via
+ *         @blockcast/mmt-container.
+ * ──────────────────────────────────────────────────────────────────────────
+ */
+/**
+ * Branded seconds type. Construct only via `secondsFromTicks(ticks, timescale)`
+ * or `asSeconds(n)` (the latter exists solely for tests and bring-up). The
+ * brand prevents accidentally passing a raw tick count — or a Date.now()
+ * millisecond — to an API that expects a media-time in seconds.
+ */
+export type Seconds = number & {
+    readonly __brand: 'Seconds';
+};
+/**
+ * Explicit conversion constructor: ticks at `timescale` Hz → Seconds.
+ *
+ * Call this at the wire/catalog boundary so the brand flows with the value
+ * through the rest of the system. Throws on non-finite inputs or
+ * non-positive timescale (CLAUDE.md §Architectural Principles: error on
+ * bad init).
+ */
+export declare function secondsFromTicks(ticks: number, timescale: number): Seconds;
+/**
+ * Escape hatch for tests / bring-up code that holds a raw seconds number
+ * (e.g. a catalog field that ships as float seconds). Production code
+ * should prefer `secondsFromTicks` so the conversion site is explicit.
+ */
+export declare function asSeconds(n: number): Seconds;
+/**
+ * Deterministic groupId from integer ticks. Authoritative form of the
+ * contract (see module docstring).
+ *
+ * @param ticks              — media presentation time in ticks (integer).
+ *                             Negative values clamp to group 0 (matches
+ *                             the Go sibling's base-clamp).
+ * @param groupDurationTicks — group duration in ticks (positive integer).
+ * @returns non-negative integer groupId.
+ *
+ * Throws on non-integer/non-finite inputs or non-positive duration. These
+ * are init-time errors, not packet-hot-path errors — callers ingesting
+ * wire data should validate once at catalog load, not once per packet.
+ */
+export declare function groupIdForTicks(ticks: number, groupDurationTicks: number): number;
+/**
+ * Seconds-form wrapper around `groupIdForTicks`. Kept for backwards
+ * compatibility with existing callers that hold `Seconds` (or a raw
+ * `number` that semantically represents seconds).
+ *
+ * Internally converts to ticks using a synthetic 1e9 Hz timescale so the
+ * integer-math contract is the single source of truth. The `| number`
+ * branch of the parameter type is a migration ramp — new code should
+ * pass `Seconds` explicitly (via `secondsFromTicks` or `asSeconds`).
+ *
+ * @param mediaTimeSec     — finite number of seconds; negatives clamp to 0.
+ * @param groupDurationSec — positive finite seconds.
+ *
+ * @deprecated Use `groupIdForTicks(ticks, groupDurationTicks)` with
+ *   tick-space inputs from the catalog. The seconds wrapper rounds to the
+ *   nearest nanosecond and throws above ~104 days of media time; the
+ *   integer-ticks form has no rounding and a much wider safe range.
+ *
+ *   The rounding is not benign: when `groupDurationTicks / timescale` is not
+ *   ns-exact (33333@90k, 1001@30k, 1024@44.1k — all real catalog cadences)
+ *   the quantized duration under-counts and `expected` slips a whole group.
+ *   See the divergence fixture in `__tests__/align.test.ts`.
+ *
+ *   No non-test caller remains in this package: `MediaRouter` now takes
+ *   `GroupBoundaryTicks` (PCL-2211). Removal is tracked by BLO-21176.
+ */
+export declare function groupIdFor(mediaTimeSec: Seconds | number, groupDurationSec: number): number;
+/**
+ * Result of a drift check between expected and actual groupIds.
+ *
+ * Discriminated on `kind` so callers must handle both outcomes explicitly
+ * (the previous `{ drifted: boolean, deltaGroups: number }` shape let a
+ * drifted result slip through with a silent `if (result.drifted)` gate).
+ */
+export type DriftCheckResult = {
+    readonly kind: 'aligned';
+    readonly deltaGroups: 0;
+} | {
+    readonly kind: 'drifted';
+    readonly deltaGroups: number;
+};
+/**
+ * Compare a packet-stamped groupId against the formula-derived expectation.
+ *
+ * Pure observer — does not throw on drift, does not mutate anything.
+ * Callers decide how to react (e.g. bump a CMCD counter, log, ignore).
+ *
+ * @param expected — groupId as derived via `groupIdForTicks` or `groupIdFor`.
+ * @param actual   — groupId as stamped on the incoming packet/group.
+ */
+export declare function driftCheck(expected: number, actual: number): DriftCheckResult;
+export type MmtpSubgroupKeyInput = {
+    readonly kind: 'mpu-metadata';
+} | {
+    readonly kind: 'timed';
+    readonly movieFragmentSequenceNumber: number;
+    readonly sampleNumber: number;
+} | {
+    readonly kind: 'non-timed';
+    readonly itemId: number;
+};
+/**
+ * Canonical, domain-separated key for MMTP payloads sharing one MoQ subgroup.
+ * This is a map/storage key, not the scalar MoQ subgroup ID. MPU metadata is
+ * carried in subgroup 0; media identity remains explicit and collision-free.
+ */
+export declare function subgroupKeyFor(input: MmtpSubgroupKeyInput): string;
+//# sourceMappingURL=align.d.ts.map

package/dist/align.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"align.d.ts","sourceRoot":"","sources":["../src/align.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH;;;;;GAKG;AACH,MAAM,MAAM,OAAO,GAAG,MAAM,GAAG;IAAE,QAAQ,CAAC,OAAO,EAAE,SAAS,CAAA;CAAE,CAAA;AAE9D;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAU1E;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAK5C;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,kBAAkB,EAAE,MAAM,GAAG,MAAM,CAajF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,UAAU,CACxB,YAAY,EAAE,OAAO,GAAG,MAAM,EAC9B,gBAAgB,EAAE,MAAM,GACvB,MAAM,CA+BR;AAED;;;;;;GAMG;AACH,MAAM,MAAM,gBAAgB,GACxB;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,WAAW,EAAE,CAAC,CAAA;CAAE,GACrD;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;CAAE,CAAA;AAE9D;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,gBAAgB,CAS7E;AAED,MAAM,MAAM,oBAAoB,GAC5B;IAAE,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAA;CAAE,GACjC;IACE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;IACtB,QAAQ,CAAC,2BAA2B,EAAE,MAAM,CAAA;IAC5C,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;CAC9B,GACD;IAAE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAA;AAE3D;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,oBAAoB,GAAG,MAAM,CAgBlE"}