@blockcast/mmt-container 0.1.0 → 0.3.0-main.288475b64b3e

package/README.md

@@ -0,0 +1,538 @@
+# @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) |
+| `./block-policy` | Keyframe-protected repair policy — `BlockClassifier`, `repairPriorityForClass`, `decideGap` |
+| `./conceal-timeline` | Sink concealment — `videoConcealModeForCodec`, `HoldLastTimeline`, `AudioGapConcealer` |
+| `./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`, `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): AlFecMessage | null   // every FEC flow (Table C.3, Amd 1:2025)
+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
+  blockProfile?: "iso-ssbg1-v1"  // REQUIRED unless algorithm is "none"; never defaulted (BLO-35597)
+  sourceSymbols: number          // K (REQUIRED): K_max, the largest SSB_length of any block
+  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"  // extension; "object" (per-frame object blocks) is retired: @blockcast/mmt-fec refuses it
+  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" | "atsc3"
+  sourceAddress?: string         // REQUIRED for SSM
+  groupAddress: string
+  port: number
+  tracks: string[]
+  // relayAddress?: string — deprecated, read-only (see Breaking, below)
+}
+
+// Relay/tuning discovery is catalog-level, not per-endpoint:
+//   multicast.networkSource: [{ type: "amt", discovery: "driad" | "manual",
+//                               relay?: string, port?: number }]
+// `relay` is REQUIRED for discovery: "manual"; "driad" resolves it at runtime.
+// An endpoint-level `relayAddress` is retired — the schema and moq-rs both
+// reject it.
+
+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; ... }
+```
+
+#### Breaking: multicast emitter output (BLO-37834)
+
+`multicastFromConfig` / `multicastFromEnv` no longer emit
+`endpoints[].relayAddress` or `amtFallback`. Both are lifted into catalog-level
+`multicast.networkSource` (`{type: "amt", discovery, relay?}`), and a native
+multicast catalog omits `networkSource` entirely (BLO-37926). A reader that
+still looks for `relayAddress` or `amtFallback` reads `undefined`: read
+`networkSource` instead (`catalogAmtNetworkSource` in `./catalog-network-source`
+resolves a dialable AMT relay from it, skipping `discovery: "driad"` entries
+whose `relay` is a DNS name for a runtime lookup rather than an address), and
+keep accepting `relayAddress` from catalogs published before this change until
+every emitter is on it.
+
+Inputs are unchanged: `relayAddress` and `amtFallback` are still accepted and
+lifted. An input relay that would not survive into the emitted `networkSource`
+(two endpoints with different relays, one overridden by
+`amtFallback.relayDns` or an explicit `networkSource`, or one matched only by a
+`discovery: "driad"` entry, whose relay is a runtime discovery hint) now throws
+`conflicting_amt_relay` instead of being dropped. For that last case — wanting
+DRIAD *and* a named relay — emit both entries, `[{type: "amt", discovery:
+"manual", relay}, {type: "amt", discovery: "driad"}]`: readers join the first
+non-DRIAD AMT entry, so the manual one carries the relay while the DRIAD one
+keeps the discovery request. An `atsc3` endpoint now
+requires a `{type: "atsc3", …}` entry and throws `atsc3_requires_tuning`
+without one: that entry carries the frequency, PLP, service id and SLS URI,
+which is the only tuning information an ATSC3 receiver has, and the schema
+cannot enforce it because `networkSource` is optional there (a native join has
+none). `version`, `validUntil` and `enabled` are still emitted and still
+outside `$defs/multicast` (the BLO-3323 freshness model, tracked separately).
+
+`MulticastInputErrorKind` gains two members, `atsc3_requires_tuning` and
+`invalid_endpoints`. The union is exported, so a consumer that `switch`es on it
+exhaustively needs the two new arms to keep compiling.
+
+The package version stayed `0.1.0`: consumers pin a libmmt commit (`file:` or the
+per-commit `0.1.0-main.<sha>` prerelease from `stamp-prerelease.mjs`), and a
+`0.2.0` would fall outside the `^0.1.0` range that siblings such as
+`mmt-render` declare.
+
+> Superseded by BLO-40665. Every package is now bumped in lockstep by a `v*`
+> tag and the sibling ranges move with it, so the objection above no longer
+> applies -- it was an argument against bumping *one* package. The set is at
+> `0.3.0`; see `RELEASES.md`.
+
+#### 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 {
+  blockProfile?: FecBlockProfile // "iso-ssbg1-v1"; required for every FEC track, validated with parseFecBlockProfile
+  k?: number              // K_max (largest SSB_length), never a block stride
+  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.
+
+FEC blocks follow one block profile, `iso-ssbg1-v1` (ISO/IEC 23008-1 Annex C ssbg_mode1, BLO-35597):
+
+- A source symbol is `u16 length || packet || 00h` padding to T.
+- A block is K' = SSB_length symbols keyed by its 32-bit SS_Start, and SS_ID increments by one per FEC source packet, wrapping at 2^32 (RFC 1982 serial arithmetic). Blocks are variable-length (SSB_length ≤ K), so K is an upper bound and never a stride: no block number is computed from an SS_ID.
+- A source symbol is placed in a block only once a repair symbol states that block's (SS_Start, SSB_length); until then it is held. Repair ESI = SSB_length + RS_ID.
+- The `sbn` in `getBlockStates()`, the block callbacks, and `RepairFetchRequest` is that SS_Start block key (the name is historical). The MoQ repair group id is the 62-bit wrap-epoch-extended SS_Start (`extSsStart` in `@blockcast/mmt-fec`), never the 32-bit key itself.
+
+`blockProfile` is never defaulted and never inferred from the wire. The retired Blockcast-private token `k-padded-v1` (zero-padded K-symbol blocks) is refused wherever a profile is read: `parseFecBlockProfile` throws for it (and for an absent token), and `FECManager` track configuration, `setupFecWorkerForTrack`, and `wireRepairFetch` all validate through it.
+
+`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).
+
+### Keyframe-protected repair (`./block-policy`, `./conceal-timeline`)
+
+Every FEC block still gets in-band FEC decode. On top of that:
+
+- **Classification.** Each block is `keyframe | delta | unknown | audio`, from
+  first-arrival network source evidence only (MMTP R bit, MPU number, MFU
+  DU-header sample position) against catalog geometry (framerate,
+  `interleaveDepthMs`, keyframe interval). Geometry that cannot be derived
+  exactly, or any violated invariant, runs the track `all-protected` (every
+  video block `unknown`). A block every symbol of which vanished is
+  materialised from the surrounding block evidence. A frame split across
+  ADJACENT blocks (a block closing at K symbols) is expected; only source
+  packets whose authored order and block order disagree (a round-robin
+  interleave) trip `block-not-contiguous`. Pass the catalog track name to
+  `configureTrackFec(packetId, config, catalogTrackName)` so ABR rungs that
+  share a packetId each classify with their own framerate and GOP; a rung on
+  such a packetId without its own geometry runs `stream-geometry-absent`.
+- **Repair priority.** `wireRepairFetch` dispatches P0 (`keyframe`/`unknown`)
+  and P1 (`audio`) immediately; P2 (`delta`) only while no P0/P1 is queued or
+  in flight, earliest deadline first, preempted by any new P0/P1. No timers.
+- **FETCH priority (draft-ramadan-moq-fec §11.4.5).** The transport gets one
+  `RepairFetchRequest { repairTrack, sbn, blockProfile, packetId, signal,
+  subscriberPriority }`, FETCHes the block's repair group (MoQ group id
+  `extSsStart(wrapEpoch, sbn)`, never `sbn` itself), and puts
+  `subscriberPriority` on the FETCH
+  (`undefined` = omit the parameter; the publisher then uses 128,
+  draft-ietf-moq-transport-16 §9.2.2.3). P0 requests carry
+  `min(sourcePriority, 191)`; P1/P2 carry `max(repairPriority, 192)`. Both
+  priorities come from `ResolveRepairTarget` (`catalogRepairTarget` reads
+  them from a catalog). A missing source priority omits the parameter; a
+  missing repair priority declines the delta/audio FETCH; each emits a
+  `repair-priority` lifecycle event. Abort MUST send FETCH_CANCEL, from the
+  abort handler.
+- **Stall vs conceal.** FEC tracks release frames in authored order; a frame
+  after a gap waits until every block that could hold the missing frames
+  resolved. When media was lost, the frame carries `gapBefore`
+  (`decideGap`): video stalls only when a RAP may be inside the gap; audio
+  never stalls. The same object is the manager's `gap` lifecycle event.
+- **Concealment** is hold-last-good-frame (`HoldLastTimeline`) plus exact
+  audio sizing (`AudioGapConcealer`). No bitstream is ever synthesised.
+
+Typed evidence is `RepairLifecycleEvent` version 2 and
+`MulticastManager.getBlockPolicyStats()`.
+
+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 |
+| `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-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 (§5.3 FEC Source Info object extension 0x11: SS_ID(32), fixed 4 bytes)
+- **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"}