@blockcast/mmt-container 0.1.0-main.1fa0d55ca4da → 0.1.0-main.21c14c2ed355

package/README.md

@@ -65,6 +65,8 @@ The package exposes a wide subpath surface so consumers can tree-shake aggressiv
 | `./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 |
@@ -82,7 +84,7 @@ The package exposes a wide subpath surface so consumers can tree-shake aggressiv
 | `./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`) |
+| `./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) |
 
@@ -190,14 +192,21 @@ interface FecCatalogConfig {
 }
 
 interface MulticastEndpoint {
-  protocol: "ssm" | "asm" | "amt"
+  protocol: "ssm" | "asm" | "amt" | "atsc3"
   sourceAddress?: string         // REQUIRED for SSM
   groupAddress: string
   port: number
   tracks: string[]
-  relayAddress?: string          // REQUIRED for AMT
+  // 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
@@ -209,6 +218,45 @@ function resolveGroupDurationTicks(timing: TrackTimingConfig, timescale: 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 stays `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.
+
 #### 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`):
@@ -263,6 +311,47 @@ class FECManager {
 
 `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`). Vanished blocks are materialised from SBN evidence.
+  A frame split across ADJACENT blocks (a K-close) is expected; only source
+  packets whose authored order and SBN 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, packetId, signal,
+  subscriberPriority }` 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`
@@ -293,7 +382,6 @@ Standalone helpers exported from the same module:
 | `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`).
@@ -322,7 +410,6 @@ Vendor keys emitted (BLO-1044):
 | `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 |

package/dist/align.d.ts

@@ -101,8 +101,12 @@ export declare function groupIdForTicks(ticks: number, groupDurationTicks: numbe
  *   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.
+ *   No non-test caller remains in this package: `MediaRouter` took tick-space
+ *   inputs from PCL-2211, and its group-alignment observer was then removed
+ *   outright as unwired telemetry (BLO-34141). Removal of this wrapper is
+ *   tracked by BLO-21176; the exported `groupIdForTicks` / `driftCheck` stay
+ *   regardless — they are the formula shared with the Go sender and the Rust
+ *   relay, not internals of the deleted observer.
  */
 export declare function groupIdFor(mediaTimeSec: Seconds | number, groupDurationSec: number): number;
 /**

package/dist/align.d.ts.map

@@ -1 +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"}
+{"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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;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"}

package/dist/align.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../src/align.ts"],
-  "sourcesContent": ["/**\n * Shared group-alignment primitive for MMT over MoQ switching sets.\n *\n * Pure math \u2014 no MMT wire parsing, no CMCD, no I/O. Callers wire the output\n * into their own drift-observation plumbing (see media-router.ts for the\n * libmmt wiring).\n *\n * \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n * Contract (integer-ticks form, authoritative):\n *\n *     groupId = ticks < 0  ?  0  :  floor(ticks / groupDurationTicks)\n *\n * Where `ticks` is a media timestamp expressed at the catalog's `timescale`\n * (Hz), and `groupDurationTicks = groupDurationSec * timescale`.\n *\n * Integer math means there is no epsilon and no float rounding to reason\n * about. The seconds-form wrapper `groupIdFor(Seconds, seconds)` exists for\n * legacy callers but converts to ticks internally.\n *\n * Every sender/receiver that emits or consumes MoQ groups from an MMT or\n * CMAF switching set MUST derive groupId from this formula so that base,\n * delta, and repair tracks agree on the group boundary for a given media\n * timestamp across languages and processes.\n *\n * Test vectors that exercise the contract live at\n * `packages/container/test-vectors/align.json`; the Go and Rust siblings\n * load the same fixture so cross-language agreement is executable, not\n * prose. **Formula changes require updating the fixture AND all three\n * sibling implementations in the same release** \u2014 divergence between\n * sender/relay/receiver is worse than any formula change.\n *\n * Canonical implementations:\n *   Go:   Blockcast/multicast `cmd/caddy/sender/group_align.go`\n *         (commit 104eeff) \u2014 sender-side groupId stamping on egress.\n *   Rust: moqtail/moqtail `apps/relay/src/server/abr.rs`\n *         (commit 39accbf; experimental branch, may be rebased \u2014 rely\n *         on the SHA, not the branch name) \u2014 relay-side check.\n *   TS:   THIS FILE (libmmt) \u2014 consumed by moq-lib + moqtail-ts via\n *         @blockcast/mmt-container.\n * \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n */\n\n/**\n * Branded seconds type. Construct only via `secondsFromTicks(ticks, timescale)`\n * or `asSeconds(n)` (the latter exists solely for tests and bring-up). The\n * brand prevents accidentally passing a raw tick count \u2014 or a Date.now()\n * millisecond \u2014 to an API that expects a media-time in seconds.\n */\nexport type Seconds = number & { readonly __brand: 'Seconds' }\n\n/**\n * Explicit conversion constructor: ticks at `timescale` Hz \u2192 Seconds.\n *\n * Call this at the wire/catalog boundary so the brand flows with the value\n * through the rest of the system. Throws on non-finite inputs or\n * non-positive timescale (CLAUDE.md \u00A7Architectural Principles: error on\n * bad init).\n */\nexport function secondsFromTicks(ticks: number, timescale: number): Seconds {\n  if (!Number.isFinite(ticks)) {\n    throw new Error(`[align] secondsFromTicks: ticks must be finite, got ${ticks}`)\n  }\n  if (!Number.isFinite(timescale) || timescale <= 0) {\n    throw new Error(\n      `[align] secondsFromTicks: timescale must be positive and finite, got ${timescale}`,\n    )\n  }\n  return (ticks / timescale) as Seconds\n}\n\n/**\n * Escape hatch for tests / bring-up code that holds a raw seconds number\n * (e.g. a catalog field that ships as float seconds). Production code\n * should prefer `secondsFromTicks` so the conversion site is explicit.\n */\nexport function asSeconds(n: number): Seconds {\n  if (!Number.isFinite(n)) {\n    throw new Error(`[align] asSeconds: value must be finite, got ${n}`)\n  }\n  return n as Seconds\n}\n\n/**\n * Deterministic groupId from integer ticks. Authoritative form of the\n * contract (see module docstring).\n *\n * @param ticks              \u2014 media presentation time in ticks (integer).\n *                             Negative values clamp to group 0 (matches\n *                             the Go sibling's base-clamp).\n * @param groupDurationTicks \u2014 group duration in ticks (positive integer).\n * @returns non-negative integer groupId.\n *\n * Throws on non-integer/non-finite inputs or non-positive duration. These\n * are init-time errors, not packet-hot-path errors \u2014 callers ingesting\n * wire data should validate once at catalog load, not once per packet.\n */\nexport function groupIdForTicks(ticks: number, groupDurationTicks: number): number {\n  if (!Number.isInteger(ticks)) {\n    throw new Error(\n      `[align] groupIdForTicks: ticks must be an integer, got ${ticks}`,\n    )\n  }\n  if (!Number.isInteger(groupDurationTicks) || groupDurationTicks <= 0) {\n    throw new Error(\n      `[align] groupIdForTicks: groupDurationTicks must be a positive integer, got ${groupDurationTicks}`,\n    )\n  }\n  if (ticks < 0) return 0\n  return Math.floor(ticks / groupDurationTicks)\n}\n\n/**\n * Seconds-form wrapper around `groupIdForTicks`. Kept for backwards\n * compatibility with existing callers that hold `Seconds` (or a raw\n * `number` that semantically represents seconds).\n *\n * Internally converts to ticks using a synthetic 1e9 Hz timescale so the\n * integer-math contract is the single source of truth. The `| number`\n * branch of the parameter type is a migration ramp \u2014 new code should\n * pass `Seconds` explicitly (via `secondsFromTicks` or `asSeconds`).\n *\n * @param mediaTimeSec     \u2014 finite number of seconds; negatives clamp to 0.\n * @param groupDurationSec \u2014 positive finite seconds.\n *\n * @deprecated Use `groupIdForTicks(ticks, groupDurationTicks)` with\n *   tick-space inputs from the catalog. The seconds wrapper rounds to the\n *   nearest nanosecond and throws above ~104 days of media time; the\n *   integer-ticks form has no rounding and a much wider safe range.\n *\n *   The rounding is not benign: when `groupDurationTicks / timescale` is not\n *   ns-exact (33333@90k, 1001@30k, 1024@44.1k \u2014 all real catalog cadences)\n *   the quantized duration under-counts and `expected` slips a whole group.\n *   See the divergence fixture in `__tests__/align.test.ts`.\n *\n *   No non-test caller remains in this package: `MediaRouter` now takes\n *   `GroupBoundaryTicks` (PCL-2211). Removal is tracked by BLO-21176.\n */\nexport function groupIdFor(\n  mediaTimeSec: Seconds | number,\n  groupDurationSec: number,\n): number {\n  if (!Number.isFinite(mediaTimeSec as number)) {\n    throw new Error(\n      `[align] groupIdFor: mediaTimeSec must be a finite number, got ${mediaTimeSec}`,\n    )\n  }\n  if (!Number.isFinite(groupDurationSec) || groupDurationSec <= 0) {\n    throw new Error(\n      `[align] groupIdFor: groupDurationSec must be a positive finite number, got ${groupDurationSec}`,\n    )\n  }\n  if ((mediaTimeSec as number) < 0) return 0\n  // 1e9 Hz keeps both operands inside Number.MAX_SAFE_INTEGER (2^53-1)\n  // for ~104 days of media time. Beyond that, Math.round returns a\n  // non-safe-integer float that Number.isInteger still accepts \u2014 throw\n  // explicitly so the caller picks a narrower timescale rather than\n  // silently quantizing.\n  const TS = 1_000_000_000\n  const ticks = Math.round((mediaTimeSec as number) * TS)\n  const durTicks = Math.round(groupDurationSec * TS)\n  if (durTicks <= 0) {\n    throw new Error(\n      `[align] groupIdFor: groupDurationSec=${groupDurationSec} rounds to <1 tick at 1e9 Hz; pass groupIdForTicks directly for sub-nanosecond durations`,\n    )\n  }\n  if (!Number.isSafeInteger(ticks)) {\n    throw new Error(\n      `[align] groupIdFor: mediaTimeSec=${mediaTimeSec} overflows safe-integer ticks at 1e9 Hz (>~104 days); use groupIdForTicks with a narrower timescale`,\n    )\n  }\n  return groupIdForTicks(ticks, durTicks)\n}\n\n/**\n * Result of a drift check between expected and actual groupIds.\n *\n * Discriminated on `kind` so callers must handle both outcomes explicitly\n * (the previous `{ drifted: boolean, deltaGroups: number }` shape let a\n * drifted result slip through with a silent `if (result.drifted)` gate).\n */\nexport type DriftCheckResult =\n  | { readonly kind: 'aligned'; readonly deltaGroups: 0 }\n  | { readonly kind: 'drifted'; readonly deltaGroups: number }\n\n/**\n * Compare a packet-stamped groupId against the formula-derived expectation.\n *\n * Pure observer \u2014 does not throw on drift, does not mutate anything.\n * Callers decide how to react (e.g. bump a CMCD counter, log, ignore).\n *\n * @param expected \u2014 groupId as derived via `groupIdForTicks` or `groupIdFor`.\n * @param actual   \u2014 groupId as stamped on the incoming packet/group.\n */\nexport function driftCheck(expected: number, actual: number): DriftCheckResult {\n  if (!Number.isInteger(expected) || !Number.isInteger(actual)) {\n    throw new Error(\n      `[align] driftCheck: both arguments must be integer groupIds, got expected=${expected} actual=${actual}`,\n    )\n  }\n  const deltaGroups = actual - expected\n  if (deltaGroups === 0) return { kind: 'aligned', deltaGroups: 0 }\n  return { kind: 'drifted', deltaGroups }\n}\n\nexport type MmtpSubgroupKeyInput =\n  | { readonly kind: 'mpu-metadata' }\n  | {\n      readonly kind: 'timed'\n      readonly movieFragmentSequenceNumber: number\n      readonly sampleNumber: number\n    }\n  | { readonly kind: 'non-timed'; readonly itemId: number }\n\n/**\n * Canonical, domain-separated key for MMTP payloads sharing one MoQ subgroup.\n * This is a map/storage key, not the scalar MoQ subgroup ID. MPU metadata is\n * carried in subgroup 0; media identity remains explicit and collision-free.\n */\nexport function subgroupKeyFor(input: MmtpSubgroupKeyInput): string {\n  if (input.kind === 'mpu-metadata') return 'metadata:0'\n\n  const values =\n    input.kind === 'timed'\n      ? [input.movieFragmentSequenceNumber, input.sampleNumber]\n      : [input.itemId]\n  for (const value of values) {\n    if (!Number.isInteger(value) || value < 0 || value > 0xffff_ffff) {\n      throw new Error(`[align] subgroup key coordinates must be uint32, got ${value}`)\n    }\n  }\n\n  return input.kind === 'timed'\n    ? `timed:${input.movieFragmentSequenceNumber}:${input.sampleNumber}`\n    : `non-timed:${input.itemId}`\n}\n"],
-  "mappings": ";AA0DO,SAAS,iBAAiB,OAAe,WAA4B;AAC1E,MAAI,CAAC,OAAO,SAAS,KAAK,GAAG;AAC3B,UAAM,IAAI,MAAM,uDAAuD,KAAK,EAAE;AAAA,EAChF;AACA,MAAI,CAAC,OAAO,SAAS,SAAS,KAAK,aAAa,GAAG;AACjD,UAAM,IAAI;AAAA,MACR,wEAAwE,SAAS;AAAA,IACnF;AAAA,EACF;AACA,SAAQ,QAAQ;AAClB;AAOO,SAAS,UAAU,GAAoB;AAC5C,MAAI,CAAC,OAAO,SAAS,CAAC,GAAG;AACvB,UAAM,IAAI,MAAM,gDAAgD,CAAC,EAAE;AAAA,EACrE;AACA,SAAO;AACT;AAgBO,SAAS,gBAAgB,OAAe,oBAAoC;AACjF,MAAI,CAAC,OAAO,UAAU,KAAK,GAAG;AAC5B,UAAM,IAAI;AAAA,MACR,0DAA0D,KAAK;AAAA,IACjE;AAAA,EACF;AACA,MAAI,CAAC,OAAO,UAAU,kBAAkB,KAAK,sBAAsB,GAAG;AACpE,UAAM,IAAI;AAAA,MACR,+EAA+E,kBAAkB;AAAA,IACnG;AAAA,EACF;AACA,MAAI,QAAQ,EAAG,QAAO;AACtB,SAAO,KAAK,MAAM,QAAQ,kBAAkB;AAC9C;AA4BO,SAAS,WACd,cACA,kBACQ;AACR,MAAI,CAAC,OAAO,SAAS,YAAsB,GAAG;AAC5C,UAAM,IAAI;AAAA,MACR,iEAAiE,YAAY;AAAA,IAC/E;AAAA,EACF;AACA,MAAI,CAAC,OAAO,SAAS,gBAAgB,KAAK,oBAAoB,GAAG;AAC/D,UAAM,IAAI;AAAA,MACR,8EAA8E,gBAAgB;AAAA,IAChG;AAAA,EACF;AACA,MAAK,eAA0B,EAAG,QAAO;AAMzC,QAAM,KAAK;AACX,QAAM,QAAQ,KAAK,MAAO,eAA0B,EAAE;AACtD,QAAM,WAAW,KAAK,MAAM,mBAAmB,EAAE;AACjD,MAAI,YAAY,GAAG;AACjB,UAAM,IAAI;AAAA,MACR,wCAAwC,gBAAgB;AAAA,IAC1D;AAAA,EACF;AACA,MAAI,CAAC,OAAO,cAAc,KAAK,GAAG;AAChC,UAAM,IAAI;AAAA,MACR,oCAAoC,YAAY;AAAA,IAClD;AAAA,EACF;AACA,SAAO,gBAAgB,OAAO,QAAQ;AACxC;AAsBO,SAAS,WAAW,UAAkB,QAAkC;AAC7E,MAAI,CAAC,OAAO,UAAU,QAAQ,KAAK,CAAC,OAAO,UAAU,MAAM,GAAG;AAC5D,UAAM,IAAI;AAAA,MACR,6EAA6E,QAAQ,WAAW,MAAM;AAAA,IACxG;AAAA,EACF;AACA,QAAM,cAAc,SAAS;AAC7B,MAAI,gBAAgB,EAAG,QAAO,EAAE,MAAM,WAAW,aAAa,EAAE;AAChE,SAAO,EAAE,MAAM,WAAW,YAAY;AACxC;AAgBO,SAAS,eAAe,OAAqC;AAClE,MAAI,MAAM,SAAS,eAAgB,QAAO;AAE1C,QAAM,SACJ,MAAM,SAAS,UACX,CAAC,MAAM,6BAA6B,MAAM,YAAY,IACtD,CAAC,MAAM,MAAM;AACnB,aAAW,SAAS,QAAQ;AAC1B,QAAI,CAAC,OAAO,UAAU,KAAK,KAAK,QAAQ,KAAK,QAAQ,YAAa;AAChE,YAAM,IAAI,MAAM,wDAAwD,KAAK,EAAE;AAAA,IACjF;AAAA,EACF;AAEA,SAAO,MAAM,SAAS,UAClB,SAAS,MAAM,2BAA2B,IAAI,MAAM,YAAY,KAChE,aAAa,MAAM,MAAM;AAC/B;",
+  "sourcesContent": ["/**\n * Shared group-alignment primitive for MMT over MoQ switching sets.\n *\n * Pure math \u2014 no MMT wire parsing, no CMCD, no I/O. Callers wire the output\n * into their own drift-observation plumbing (see media-router.ts for the\n * libmmt wiring).\n *\n * \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n * Contract (integer-ticks form, authoritative):\n *\n *     groupId = ticks < 0  ?  0  :  floor(ticks / groupDurationTicks)\n *\n * Where `ticks` is a media timestamp expressed at the catalog's `timescale`\n * (Hz), and `groupDurationTicks = groupDurationSec * timescale`.\n *\n * Integer math means there is no epsilon and no float rounding to reason\n * about. The seconds-form wrapper `groupIdFor(Seconds, seconds)` exists for\n * legacy callers but converts to ticks internally.\n *\n * Every sender/receiver that emits or consumes MoQ groups from an MMT or\n * CMAF switching set MUST derive groupId from this formula so that base,\n * delta, and repair tracks agree on the group boundary for a given media\n * timestamp across languages and processes.\n *\n * Test vectors that exercise the contract live at\n * `packages/container/test-vectors/align.json`; the Go and Rust siblings\n * load the same fixture so cross-language agreement is executable, not\n * prose. **Formula changes require updating the fixture AND all three\n * sibling implementations in the same release** \u2014 divergence between\n * sender/relay/receiver is worse than any formula change.\n *\n * Canonical implementations:\n *   Go:   Blockcast/multicast `cmd/caddy/sender/group_align.go`\n *         (commit 104eeff) \u2014 sender-side groupId stamping on egress.\n *   Rust: moqtail/moqtail `apps/relay/src/server/abr.rs`\n *         (commit 39accbf; experimental branch, may be rebased \u2014 rely\n *         on the SHA, not the branch name) \u2014 relay-side check.\n *   TS:   THIS FILE (libmmt) \u2014 consumed by moq-lib + moqtail-ts via\n *         @blockcast/mmt-container.\n * \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n */\n\n/**\n * Branded seconds type. Construct only via `secondsFromTicks(ticks, timescale)`\n * or `asSeconds(n)` (the latter exists solely for tests and bring-up). The\n * brand prevents accidentally passing a raw tick count \u2014 or a Date.now()\n * millisecond \u2014 to an API that expects a media-time in seconds.\n */\nexport type Seconds = number & { readonly __brand: 'Seconds' }\n\n/**\n * Explicit conversion constructor: ticks at `timescale` Hz \u2192 Seconds.\n *\n * Call this at the wire/catalog boundary so the brand flows with the value\n * through the rest of the system. Throws on non-finite inputs or\n * non-positive timescale (CLAUDE.md \u00A7Architectural Principles: error on\n * bad init).\n */\nexport function secondsFromTicks(ticks: number, timescale: number): Seconds {\n  if (!Number.isFinite(ticks)) {\n    throw new Error(`[align] secondsFromTicks: ticks must be finite, got ${ticks}`)\n  }\n  if (!Number.isFinite(timescale) || timescale <= 0) {\n    throw new Error(\n      `[align] secondsFromTicks: timescale must be positive and finite, got ${timescale}`,\n    )\n  }\n  return (ticks / timescale) as Seconds\n}\n\n/**\n * Escape hatch for tests / bring-up code that holds a raw seconds number\n * (e.g. a catalog field that ships as float seconds). Production code\n * should prefer `secondsFromTicks` so the conversion site is explicit.\n */\nexport function asSeconds(n: number): Seconds {\n  if (!Number.isFinite(n)) {\n    throw new Error(`[align] asSeconds: value must be finite, got ${n}`)\n  }\n  return n as Seconds\n}\n\n/**\n * Deterministic groupId from integer ticks. Authoritative form of the\n * contract (see module docstring).\n *\n * @param ticks              \u2014 media presentation time in ticks (integer).\n *                             Negative values clamp to group 0 (matches\n *                             the Go sibling's base-clamp).\n * @param groupDurationTicks \u2014 group duration in ticks (positive integer).\n * @returns non-negative integer groupId.\n *\n * Throws on non-integer/non-finite inputs or non-positive duration. These\n * are init-time errors, not packet-hot-path errors \u2014 callers ingesting\n * wire data should validate once at catalog load, not once per packet.\n */\nexport function groupIdForTicks(ticks: number, groupDurationTicks: number): number {\n  if (!Number.isInteger(ticks)) {\n    throw new Error(\n      `[align] groupIdForTicks: ticks must be an integer, got ${ticks}`,\n    )\n  }\n  if (!Number.isInteger(groupDurationTicks) || groupDurationTicks <= 0) {\n    throw new Error(\n      `[align] groupIdForTicks: groupDurationTicks must be a positive integer, got ${groupDurationTicks}`,\n    )\n  }\n  if (ticks < 0) return 0\n  return Math.floor(ticks / groupDurationTicks)\n}\n\n/**\n * Seconds-form wrapper around `groupIdForTicks`. Kept for backwards\n * compatibility with existing callers that hold `Seconds` (or a raw\n * `number` that semantically represents seconds).\n *\n * Internally converts to ticks using a synthetic 1e9 Hz timescale so the\n * integer-math contract is the single source of truth. The `| number`\n * branch of the parameter type is a migration ramp \u2014 new code should\n * pass `Seconds` explicitly (via `secondsFromTicks` or `asSeconds`).\n *\n * @param mediaTimeSec     \u2014 finite number of seconds; negatives clamp to 0.\n * @param groupDurationSec \u2014 positive finite seconds.\n *\n * @deprecated Use `groupIdForTicks(ticks, groupDurationTicks)` with\n *   tick-space inputs from the catalog. The seconds wrapper rounds to the\n *   nearest nanosecond and throws above ~104 days of media time; the\n *   integer-ticks form has no rounding and a much wider safe range.\n *\n *   The rounding is not benign: when `groupDurationTicks / timescale` is not\n *   ns-exact (33333@90k, 1001@30k, 1024@44.1k \u2014 all real catalog cadences)\n *   the quantized duration under-counts and `expected` slips a whole group.\n *   See the divergence fixture in `__tests__/align.test.ts`.\n *\n *   No non-test caller remains in this package: `MediaRouter` took tick-space\n *   inputs from PCL-2211, and its group-alignment observer was then removed\n *   outright as unwired telemetry (BLO-34141). Removal of this wrapper is\n *   tracked by BLO-21176; the exported `groupIdForTicks` / `driftCheck` stay\n *   regardless \u2014 they are the formula shared with the Go sender and the Rust\n *   relay, not internals of the deleted observer.\n */\nexport function groupIdFor(\n  mediaTimeSec: Seconds | number,\n  groupDurationSec: number,\n): number {\n  if (!Number.isFinite(mediaTimeSec as number)) {\n    throw new Error(\n      `[align] groupIdFor: mediaTimeSec must be a finite number, got ${mediaTimeSec}`,\n    )\n  }\n  if (!Number.isFinite(groupDurationSec) || groupDurationSec <= 0) {\n    throw new Error(\n      `[align] groupIdFor: groupDurationSec must be a positive finite number, got ${groupDurationSec}`,\n    )\n  }\n  if ((mediaTimeSec as number) < 0) return 0\n  // 1e9 Hz keeps both operands inside Number.MAX_SAFE_INTEGER (2^53-1)\n  // for ~104 days of media time. Beyond that, Math.round returns a\n  // non-safe-integer float that Number.isInteger still accepts \u2014 throw\n  // explicitly so the caller picks a narrower timescale rather than\n  // silently quantizing.\n  const TS = 1_000_000_000\n  const ticks = Math.round((mediaTimeSec as number) * TS)\n  const durTicks = Math.round(groupDurationSec * TS)\n  if (durTicks <= 0) {\n    throw new Error(\n      `[align] groupIdFor: groupDurationSec=${groupDurationSec} rounds to <1 tick at 1e9 Hz; pass groupIdForTicks directly for sub-nanosecond durations`,\n    )\n  }\n  if (!Number.isSafeInteger(ticks)) {\n    throw new Error(\n      `[align] groupIdFor: mediaTimeSec=${mediaTimeSec} overflows safe-integer ticks at 1e9 Hz (>~104 days); use groupIdForTicks with a narrower timescale`,\n    )\n  }\n  return groupIdForTicks(ticks, durTicks)\n}\n\n/**\n * Result of a drift check between expected and actual groupIds.\n *\n * Discriminated on `kind` so callers must handle both outcomes explicitly\n * (the previous `{ drifted: boolean, deltaGroups: number }` shape let a\n * drifted result slip through with a silent `if (result.drifted)` gate).\n */\nexport type DriftCheckResult =\n  | { readonly kind: 'aligned'; readonly deltaGroups: 0 }\n  | { readonly kind: 'drifted'; readonly deltaGroups: number }\n\n/**\n * Compare a packet-stamped groupId against the formula-derived expectation.\n *\n * Pure observer \u2014 does not throw on drift, does not mutate anything.\n * Callers decide how to react (e.g. bump a CMCD counter, log, ignore).\n *\n * @param expected \u2014 groupId as derived via `groupIdForTicks` or `groupIdFor`.\n * @param actual   \u2014 groupId as stamped on the incoming packet/group.\n */\nexport function driftCheck(expected: number, actual: number): DriftCheckResult {\n  if (!Number.isInteger(expected) || !Number.isInteger(actual)) {\n    throw new Error(\n      `[align] driftCheck: both arguments must be integer groupIds, got expected=${expected} actual=${actual}`,\n    )\n  }\n  const deltaGroups = actual - expected\n  if (deltaGroups === 0) return { kind: 'aligned', deltaGroups: 0 }\n  return { kind: 'drifted', deltaGroups }\n}\n\nexport type MmtpSubgroupKeyInput =\n  | { readonly kind: 'mpu-metadata' }\n  | {\n      readonly kind: 'timed'\n      readonly movieFragmentSequenceNumber: number\n      readonly sampleNumber: number\n    }\n  | { readonly kind: 'non-timed'; readonly itemId: number }\n\n/**\n * Canonical, domain-separated key for MMTP payloads sharing one MoQ subgroup.\n * This is a map/storage key, not the scalar MoQ subgroup ID. MPU metadata is\n * carried in subgroup 0; media identity remains explicit and collision-free.\n */\nexport function subgroupKeyFor(input: MmtpSubgroupKeyInput): string {\n  if (input.kind === 'mpu-metadata') return 'metadata:0'\n\n  const values =\n    input.kind === 'timed'\n      ? [input.movieFragmentSequenceNumber, input.sampleNumber]\n      : [input.itemId]\n  for (const value of values) {\n    if (!Number.isInteger(value) || value < 0 || value > 0xffff_ffff) {\n      throw new Error(`[align] subgroup key coordinates must be uint32, got ${value}`)\n    }\n  }\n\n  return input.kind === 'timed'\n    ? `timed:${input.movieFragmentSequenceNumber}:${input.sampleNumber}`\n    : `non-timed:${input.itemId}`\n}\n"],
+  "mappings": ";AA0DO,SAAS,iBAAiB,OAAe,WAA4B;AAC1E,MAAI,CAAC,OAAO,SAAS,KAAK,GAAG;AAC3B,UAAM,IAAI,MAAM,uDAAuD,KAAK,EAAE;AAAA,EAChF;AACA,MAAI,CAAC,OAAO,SAAS,SAAS,KAAK,aAAa,GAAG;AACjD,UAAM,IAAI;AAAA,MACR,wEAAwE,SAAS;AAAA,IACnF;AAAA,EACF;AACA,SAAQ,QAAQ;AAClB;AAOO,SAAS,UAAU,GAAoB;AAC5C,MAAI,CAAC,OAAO,SAAS,CAAC,GAAG;AACvB,UAAM,IAAI,MAAM,gDAAgD,CAAC,EAAE;AAAA,EACrE;AACA,SAAO;AACT;AAgBO,SAAS,gBAAgB,OAAe,oBAAoC;AACjF,MAAI,CAAC,OAAO,UAAU,KAAK,GAAG;AAC5B,UAAM,IAAI;AAAA,MACR,0DAA0D,KAAK;AAAA,IACjE;AAAA,EACF;AACA,MAAI,CAAC,OAAO,UAAU,kBAAkB,KAAK,sBAAsB,GAAG;AACpE,UAAM,IAAI;AAAA,MACR,+EAA+E,kBAAkB;AAAA,IACnG;AAAA,EACF;AACA,MAAI,QAAQ,EAAG,QAAO;AACtB,SAAO,KAAK,MAAM,QAAQ,kBAAkB;AAC9C;AAgCO,SAAS,WACd,cACA,kBACQ;AACR,MAAI,CAAC,OAAO,SAAS,YAAsB,GAAG;AAC5C,UAAM,IAAI;AAAA,MACR,iEAAiE,YAAY;AAAA,IAC/E;AAAA,EACF;AACA,MAAI,CAAC,OAAO,SAAS,gBAAgB,KAAK,oBAAoB,GAAG;AAC/D,UAAM,IAAI;AAAA,MACR,8EAA8E,gBAAgB;AAAA,IAChG;AAAA,EACF;AACA,MAAK,eAA0B,EAAG,QAAO;AAMzC,QAAM,KAAK;AACX,QAAM,QAAQ,KAAK,MAAO,eAA0B,EAAE;AACtD,QAAM,WAAW,KAAK,MAAM,mBAAmB,EAAE;AACjD,MAAI,YAAY,GAAG;AACjB,UAAM,IAAI;AAAA,MACR,wCAAwC,gBAAgB;AAAA,IAC1D;AAAA,EACF;AACA,MAAI,CAAC,OAAO,cAAc,KAAK,GAAG;AAChC,UAAM,IAAI;AAAA,MACR,oCAAoC,YAAY;AAAA,IAClD;AAAA,EACF;AACA,SAAO,gBAAgB,OAAO,QAAQ;AACxC;AAsBO,SAAS,WAAW,UAAkB,QAAkC;AAC7E,MAAI,CAAC,OAAO,UAAU,QAAQ,KAAK,CAAC,OAAO,UAAU,MAAM,GAAG;AAC5D,UAAM,IAAI;AAAA,MACR,6EAA6E,QAAQ,WAAW,MAAM;AAAA,IACxG;AAAA,EACF;AACA,QAAM,cAAc,SAAS;AAC7B,MAAI,gBAAgB,EAAG,QAAO,EAAE,MAAM,WAAW,aAAa,EAAE;AAChE,SAAO,EAAE,MAAM,WAAW,YAAY;AACxC;AAgBO,SAAS,eAAe,OAAqC;AAClE,MAAI,MAAM,SAAS,eAAgB,QAAO;AAE1C,QAAM,SACJ,MAAM,SAAS,UACX,CAAC,MAAM,6BAA6B,MAAM,YAAY,IACtD,CAAC,MAAM,MAAM;AACnB,aAAW,SAAS,QAAQ;AAC1B,QAAI,CAAC,OAAO,UAAU,KAAK,KAAK,QAAQ,KAAK,QAAQ,YAAa;AAChE,YAAM,IAAI,MAAM,wDAAwD,KAAK,EAAE;AAAA,IACjF;AAAA,EACF;AAEA,SAAO,MAAM,SAAS,UAClB,SAAS,MAAM,2BAA2B,IAAI,MAAM,YAAY,KAChE,aAAa,MAAM,MAAM;AAC/B;",
   "names": []
 }

package/dist/audio-ring-buffer.js

@@ -1,36 +1,27 @@
-var __typeError = (msg) => {
-  throw TypeError(msg);
-};
-var __accessCheck = (obj, member, msg) => member.has(obj) || __typeError("Cannot " + msg);
-var __privateGet = (obj, member, getter) => (__accessCheck(obj, member, "read from private field"), getter ? getter.call(obj) : member.get(obj));
-var __privateAdd = (obj, member, value) => member.has(obj) ? __typeError("Cannot add the same private member more than once") : member instanceof WeakSet ? member.add(obj) : member.set(obj, value);
-var __privateSet = (obj, member, value, setter) => (__accessCheck(obj, member, "write to private field"), setter ? setter.call(obj, value) : member.set(obj, value), value);
-
 // src/audio-ring-buffer.ts
-var _buffer, _writeIndex, _readIndex, _stalled;
 var AudioRingBuffer = class {
+  #buffer;
+  #writeIndex = 0;
+  #readIndex = 0;
+  #stalled;
   constructor(config) {
-    __privateAdd(this, _buffer);
-    __privateAdd(this, _writeIndex, 0);
-    __privateAdd(this, _readIndex, 0);
-    __privateAdd(this, _stalled);
     this.channels = config.channels;
     this.rate = config.rate;
-    __privateSet(this, _stalled, !(config.startUnstalled ?? false));
+    this.#stalled = !(config.startUnstalled ?? false);
     const samples = Math.ceil(config.rate * (config.latencyMs / 1e3));
-    __privateSet(this, _buffer, []);
+    this.#buffer = [];
     for (let i = 0; i < config.channels; i++) {
-      __privateGet(this, _buffer)[i] = new Float32Array(samples);
+      this.#buffer[i] = new Float32Array(samples);
     }
   }
   get stalled() {
-    return __privateGet(this, _stalled);
+    return this.#stalled;
   }
   get capacity() {
-    return __privateGet(this, _buffer)[0].length;
+    return this.#buffer[0].length;
   }
   get length() {
-    return __privateGet(this, _writeIndex) - __privateGet(this, _readIndex);
+    return this.#writeIndex - this.#readIndex;
   }
   /**
    * Append decoded audio samples to the FIFO.
@@ -39,24 +30,24 @@ var AudioRingBuffer = class {
    */
   write(_timestampUs, data) {
     const samples = data[0].length;
-    const start = __privateGet(this, _writeIndex);
+    const start = this.#writeIndex;
     const end = start + samples;
-    const overflow = end - __privateGet(this, _readIndex) - __privateGet(this, _buffer)[0].length;
+    const overflow = end - this.#readIndex - this.#buffer[0].length;
     if (overflow >= 0) {
-      __privateSet(this, _stalled, false);
-      __privateSet(this, _readIndex, __privateGet(this, _readIndex) + overflow);
+      this.#stalled = false;
+      this.#readIndex += overflow;
     }
-    if (__privateGet(this, _stalled) && end - __privateGet(this, _readIndex) >= Math.floor(__privateGet(this, _buffer)[0].length / 2)) {
-      __privateSet(this, _stalled, false);
+    if (this.#stalled && end - this.#readIndex >= Math.floor(this.#buffer[0].length / 2)) {
+      this.#stalled = false;
     }
     for (let ch = 0; ch < this.channels; ch++) {
       const src = data[ch];
-      const dst = __privateGet(this, _buffer)[ch];
+      const dst = this.#buffer[ch];
       for (let i = 0; i < samples; i++) {
         dst[(start + i) % dst.length] = src[i];
       }
     }
-    __privateSet(this, _writeIndex, end);
+    this.#writeIndex = end;
   }
   /**
    * Read samples into output buffers — plain FIFO, no clock recovery.
@@ -64,29 +55,25 @@ var AudioRingBuffer = class {
    * Underrun → zero-fill.
    */
   read(output) {
-    if (__privateGet(this, _stalled)) return 0;
-    const available = __privateGet(this, _writeIndex) - __privateGet(this, _readIndex);
+    if (this.#stalled) return 0;
+    const available = this.#writeIndex - this.#readIndex;
     if (available === 0) return 0;
     const requested = output[0].length;
     const readSamples = Math.min(available, requested);
     for (let ch = 0; ch < this.channels; ch++) {
       const dst = output[ch];
-      const src = __privateGet(this, _buffer)[ch];
+      const src = this.#buffer[ch];
       for (let i = 0; i < readSamples; i++) {
-        dst[i] = src[(__privateGet(this, _readIndex) + i) % src.length];
+        dst[i] = src[(this.#readIndex + i) % src.length];
       }
       for (let i = readSamples; i < requested; i++) {
         dst[i] = 0;
       }
     }
-    __privateSet(this, _readIndex, __privateGet(this, _readIndex) + readSamples);
+    this.#readIndex += readSamples;
     return readSamples;
   }
 };
-_buffer = new WeakMap();
-_writeIndex = new WeakMap();
-_readIndex = new WeakMap();
-_stalled = new WeakMap();
 export {
   AudioRingBuffer
 };

package/dist/audio-ring-buffer.js.map

@@ -2,6 +2,6 @@
   "version": 3,
   "sources": ["../src/audio-ring-buffer.ts"],
   "sourcesContent": ["/**\n * AudioRingBuffer \u2014 plain FIFO audio buffer (no clock recovery).\n *\n * Source of truth for the audio buffer algorithm used in both moq-lib and\n * moqtail AudioWorklet processors. AudioWorklet isolation requires the\n * worklet copy to be self-contained (no imports), so changes here must be\n * manually synced to:\n *   - moqtail-private/apps/client-js/src/lib/audio-worklet-processor.js\n *   - hang-mmt-fec/js/watch/src/audio/ring-buffer.ts (uses @moq/lite Time types)\n *\n * Rationale: FEC guarantees gap-free, ordered audio on multicast; MoQ\n * delivers ordered audio without drops. The decoder output rate matches\n * the AudioContext destination rate closely enough that skip/dup clock\n * recovery is unnecessary and harmful \u2014 a single sample skip at 48 kHz is\n * a ~21 \u00B5s phase glitch, and repeated skip/dup produces audible pitch\n * wobble on pure tones (measured: 16 Hz offset + \u00B111 Hz spread on a 1 kHz\n * test tone before this refactor).\n */\n\nexport interface AudioRingBufferConfig {\n  /** Number of audio channels */\n  channels: number;\n  /** Sample rate in Hz */\n  rate: number;\n  /** Buffer latency in milliseconds */\n  latencyMs: number;\n  /** Start in unstalled state (for source switching) */\n  startUnstalled?: boolean;\n}\n\nexport class AudioRingBuffer {\n  readonly channels: number;\n  readonly rate: number;\n\n  #buffer: Float32Array[];\n  #writeIndex = 0;\n  #readIndex = 0;\n  #stalled: boolean;\n\n  constructor(config: AudioRingBufferConfig) {\n    this.channels = config.channels;\n    this.rate = config.rate;\n    this.#stalled = !(config.startUnstalled ?? false);\n\n    const samples = Math.ceil(config.rate * (config.latencyMs / 1000));\n    this.#buffer = [];\n    for (let i = 0; i < config.channels; i++) {\n      this.#buffer[i] = new Float32Array(samples);\n    }\n  }\n\n  get stalled(): boolean { return this.#stalled; }\n  get capacity(): number { return this.#buffer[0].length; }\n  get length(): number { return this.#writeIndex - this.#readIndex; }\n\n  /**\n   * Append decoded audio samples to the FIFO.\n   * Timestamp parameter retained for API compatibility but is ignored \u2014\n   * FIFO is sequence-based, not time-based.\n   */\n  write(_timestampUs: number, data: Float32Array[]): void {\n    const samples = data[0].length;\n\n    const start = this.#writeIndex;\n    const end = start + samples;\n\n    // Overflow: discard oldest samples (protects against encoder/AudioContext\n    // clock drift when one runs faster than the other).\n    const overflow = end - this.#readIndex - this.#buffer[0].length;\n    if (overflow >= 0) {\n      this.#stalled = false;\n      this.#readIndex += overflow;\n    }\n\n    // Unstall at half capacity \u2014 enough prebuffer for bounded jitter.\n    if (this.#stalled && (end - this.#readIndex) >= Math.floor(this.#buffer[0].length / 2)) {\n      this.#stalled = false;\n    }\n\n    // Append samples sequentially\n    for (let ch = 0; ch < this.channels; ch++) {\n      const src = data[ch];\n      const dst = this.#buffer[ch];\n      for (let i = 0; i < samples; i++) {\n        dst[(start + i) % dst.length] = src[i];\n      }\n    }\n    this.#writeIndex = end;\n  }\n\n  /**\n   * Read samples into output buffers \u2014 plain FIFO, no clock recovery.\n   * FEC + MoQ delivery guarantees no gaps, so skip/dup is unnecessary.\n   * Underrun \u2192 zero-fill.\n   */\n  read(output: Float32Array[]): number {\n    if (this.#stalled) return 0;\n\n    const available = this.#writeIndex - this.#readIndex;\n    if (available === 0) return 0;\n\n    const requested = output[0].length;\n    const readSamples = Math.min(available, requested);\n\n    for (let ch = 0; ch < this.channels; ch++) {\n      const dst = output[ch];\n      const src = this.#buffer[ch];\n      for (let i = 0; i < readSamples; i++) {\n        dst[i] = src[(this.#readIndex + i) % src.length];\n      }\n      // Zero-fill remainder on underrun\n      for (let i = readSamples; i < requested; i++) {\n        dst[i] = 0;\n      }\n    }\n\n    this.#readIndex += readSamples;\n    return readSamples;\n  }\n}\n"],
-  "mappings": ";;;;;;;;;AAAA;AA8BO,IAAM,kBAAN,MAAsB;AAAA,EAS3B,YAAY,QAA+B;AAL3C;AACA,oCAAc;AACd,mCAAa;AACb;AAGE,SAAK,WAAW,OAAO;AACvB,SAAK,OAAO,OAAO;AACnB,uBAAK,UAAW,EAAE,OAAO,kBAAkB;AAE3C,UAAM,UAAU,KAAK,KAAK,OAAO,QAAQ,OAAO,YAAY,IAAK;AACjE,uBAAK,SAAU,CAAC;AAChB,aAAS,IAAI,GAAG,IAAI,OAAO,UAAU,KAAK;AACxC,yBAAK,SAAQ,CAAC,IAAI,IAAI,aAAa,OAAO;AAAA,IAC5C;AAAA,EACF;AAAA,EAEA,IAAI,UAAmB;AAAE,WAAO,mBAAK;AAAA,EAAU;AAAA,EAC/C,IAAI,WAAmB;AAAE,WAAO,mBAAK,SAAQ,CAAC,EAAE;AAAA,EAAQ;AAAA,EACxD,IAAI,SAAiB;AAAE,WAAO,mBAAK,eAAc,mBAAK;AAAA,EAAY;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOlE,MAAM,cAAsB,MAA4B;AACtD,UAAM,UAAU,KAAK,CAAC,EAAE;AAExB,UAAM,QAAQ,mBAAK;AACnB,UAAM,MAAM,QAAQ;AAIpB,UAAM,WAAW,MAAM,mBAAK,cAAa,mBAAK,SAAQ,CAAC,EAAE;AACzD,QAAI,YAAY,GAAG;AACjB,yBAAK,UAAW;AAChB,yBAAK,YAAL,mBAAK,cAAc;AAAA,IACrB;AAGA,QAAI,mBAAK,aAAa,MAAM,mBAAK,eAAe,KAAK,MAAM,mBAAK,SAAQ,CAAC,EAAE,SAAS,CAAC,GAAG;AACtF,yBAAK,UAAW;AAAA,IAClB;AAGA,aAAS,KAAK,GAAG,KAAK,KAAK,UAAU,MAAM;AACzC,YAAM,MAAM,KAAK,EAAE;AACnB,YAAM,MAAM,mBAAK,SAAQ,EAAE;AAC3B,eAAS,IAAI,GAAG,IAAI,SAAS,KAAK;AAChC,aAAK,QAAQ,KAAK,IAAI,MAAM,IAAI,IAAI,CAAC;AAAA,MACvC;AAAA,IACF;AACA,uBAAK,aAAc;AAAA,EACrB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,KAAK,QAAgC;AACnC,QAAI,mBAAK,UAAU,QAAO;AAE1B,UAAM,YAAY,mBAAK,eAAc,mBAAK;AAC1C,QAAI,cAAc,EAAG,QAAO;AAE5B,UAAM,YAAY,OAAO,CAAC,EAAE;AAC5B,UAAM,cAAc,KAAK,IAAI,WAAW,SAAS;AAEjD,aAAS,KAAK,GAAG,KAAK,KAAK,UAAU,MAAM;AACzC,YAAM,MAAM,OAAO,EAAE;AACrB,YAAM,MAAM,mBAAK,SAAQ,EAAE;AAC3B,eAAS,IAAI,GAAG,IAAI,aAAa,KAAK;AACpC,YAAI,CAAC,IAAI,KAAK,mBAAK,cAAa,KAAK,IAAI,MAAM;AAAA,MACjD;AAEA,eAAS,IAAI,aAAa,IAAI,WAAW,KAAK;AAC5C,YAAI,CAAC,IAAI;AAAA,MACX;AAAA,IACF;AAEA,uBAAK,YAAL,mBAAK,cAAc;AACnB,WAAO;AAAA,EACT;AACF;AArFE;AACA;AACA;AACA;",
+  "mappings": ";AA8BO,IAAM,kBAAN,MAAsB;AAAA,EAI3B;AAAA,EACA,cAAc;AAAA,EACd,aAAa;AAAA,EACb;AAAA,EAEA,YAAY,QAA+B;AACzC,SAAK,WAAW,OAAO;AACvB,SAAK,OAAO,OAAO;AACnB,SAAK,WAAW,EAAE,OAAO,kBAAkB;AAE3C,UAAM,UAAU,KAAK,KAAK,OAAO,QAAQ,OAAO,YAAY,IAAK;AACjE,SAAK,UAAU,CAAC;AAChB,aAAS,IAAI,GAAG,IAAI,OAAO,UAAU,KAAK;AACxC,WAAK,QAAQ,CAAC,IAAI,IAAI,aAAa,OAAO;AAAA,IAC5C;AAAA,EACF;AAAA,EAEA,IAAI,UAAmB;AAAE,WAAO,KAAK;AAAA,EAAU;AAAA,EAC/C,IAAI,WAAmB;AAAE,WAAO,KAAK,QAAQ,CAAC,EAAE;AAAA,EAAQ;AAAA,EACxD,IAAI,SAAiB;AAAE,WAAO,KAAK,cAAc,KAAK;AAAA,EAAY;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOlE,MAAM,cAAsB,MAA4B;AACtD,UAAM,UAAU,KAAK,CAAC,EAAE;AAExB,UAAM,QAAQ,KAAK;AACnB,UAAM,MAAM,QAAQ;AAIpB,UAAM,WAAW,MAAM,KAAK,aAAa,KAAK,QAAQ,CAAC,EAAE;AACzD,QAAI,YAAY,GAAG;AACjB,WAAK,WAAW;AAChB,WAAK,cAAc;AAAA,IACrB;AAGA,QAAI,KAAK,YAAa,MAAM,KAAK,cAAe,KAAK,MAAM,KAAK,QAAQ,CAAC,EAAE,SAAS,CAAC,GAAG;AACtF,WAAK,WAAW;AAAA,IAClB;AAGA,aAAS,KAAK,GAAG,KAAK,KAAK,UAAU,MAAM;AACzC,YAAM,MAAM,KAAK,EAAE;AACnB,YAAM,MAAM,KAAK,QAAQ,EAAE;AAC3B,eAAS,IAAI,GAAG,IAAI,SAAS,KAAK;AAChC,aAAK,QAAQ,KAAK,IAAI,MAAM,IAAI,IAAI,CAAC;AAAA,MACvC;AAAA,IACF;AACA,SAAK,cAAc;AAAA,EACrB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,KAAK,QAAgC;AACnC,QAAI,KAAK,SAAU,QAAO;AAE1B,UAAM,YAAY,KAAK,cAAc,KAAK;AAC1C,QAAI,cAAc,EAAG,QAAO;AAE5B,UAAM,YAAY,OAAO,CAAC,EAAE;AAC5B,UAAM,cAAc,KAAK,IAAI,WAAW,SAAS;AAEjD,aAAS,KAAK,GAAG,KAAK,KAAK,UAAU,MAAM;AACzC,YAAM,MAAM,OAAO,EAAE;AACrB,YAAM,MAAM,KAAK,QAAQ,EAAE;AAC3B,eAAS,IAAI,GAAG,IAAI,aAAa,KAAK;AACpC,YAAI,CAAC,IAAI,KAAK,KAAK,aAAa,KAAK,IAAI,MAAM;AAAA,MACjD;AAEA,eAAS,IAAI,aAAa,IAAI,WAAW,KAAK;AAC5C,YAAI,CAAC,IAAI;AAAA,MACX;AAAA,IACF;AAEA,SAAK,cAAc;AACnB,WAAO;AAAA,EACT;AACF;",
   "names": []
 }