@blockcast/mmt-container 0.1.0 → 0.3.0-main.ef68de90edb3

package/dist/align.d.ts

@@ -0,0 +1,152 @@
+/**
+ * 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` 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;
+/**
+ * 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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;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

@@ -0,0 +1,88 @@
+// src/align.ts
+function secondsFromTicks(ticks, timescale) {
+  if (!Number.isFinite(ticks)) {
+    throw new Error(`[align] secondsFromTicks: ticks must be finite, got ${ticks}`);
+  }
+  if (!Number.isFinite(timescale) || timescale <= 0) {
+    throw new Error(
+      `[align] secondsFromTicks: timescale must be positive and finite, got ${timescale}`
+    );
+  }
+  return ticks / timescale;
+}
+function asSeconds(n) {
+  if (!Number.isFinite(n)) {
+    throw new Error(`[align] asSeconds: value must be finite, got ${n}`);
+  }
+  return n;
+}
+function groupIdForTicks(ticks, groupDurationTicks) {
+  if (!Number.isInteger(ticks)) {
+    throw new Error(
+      `[align] groupIdForTicks: ticks must be an integer, got ${ticks}`
+    );
+  }
+  if (!Number.isInteger(groupDurationTicks) || groupDurationTicks <= 0) {
+    throw new Error(
+      `[align] groupIdForTicks: groupDurationTicks must be a positive integer, got ${groupDurationTicks}`
+    );
+  }
+  if (ticks < 0) return 0;
+  return Math.floor(ticks / groupDurationTicks);
+}
+function groupIdFor(mediaTimeSec, groupDurationSec) {
+  if (!Number.isFinite(mediaTimeSec)) {
+    throw new Error(
+      `[align] groupIdFor: mediaTimeSec must be a finite number, got ${mediaTimeSec}`
+    );
+  }
+  if (!Number.isFinite(groupDurationSec) || groupDurationSec <= 0) {
+    throw new Error(
+      `[align] groupIdFor: groupDurationSec must be a positive finite number, got ${groupDurationSec}`
+    );
+  }
+  if (mediaTimeSec < 0) return 0;
+  const TS = 1e9;
+  const ticks = Math.round(mediaTimeSec * TS);
+  const durTicks = Math.round(groupDurationSec * TS);
+  if (durTicks <= 0) {
+    throw new Error(
+      `[align] groupIdFor: groupDurationSec=${groupDurationSec} rounds to <1 tick at 1e9 Hz; pass groupIdForTicks directly for sub-nanosecond durations`
+    );
+  }
+  if (!Number.isSafeInteger(ticks)) {
+    throw new Error(
+      `[align] groupIdFor: mediaTimeSec=${mediaTimeSec} overflows safe-integer ticks at 1e9 Hz (>~104 days); use groupIdForTicks with a narrower timescale`
+    );
+  }
+  return groupIdForTicks(ticks, durTicks);
+}
+function driftCheck(expected, actual) {
+  if (!Number.isInteger(expected) || !Number.isInteger(actual)) {
+    throw new Error(
+      `[align] driftCheck: both arguments must be integer groupIds, got expected=${expected} actual=${actual}`
+    );
+  }
+  const deltaGroups = actual - expected;
+  if (deltaGroups === 0) return { kind: "aligned", deltaGroups: 0 };
+  return { kind: "drifted", deltaGroups };
+}
+function subgroupKeyFor(input) {
+  if (input.kind === "mpu-metadata") return "metadata:0";
+  const values = input.kind === "timed" ? [input.movieFragmentSequenceNumber, input.sampleNumber] : [input.itemId];
+  for (const value of values) {
+    if (!Number.isInteger(value) || value < 0 || value > 4294967295) {
+      throw new Error(`[align] subgroup key coordinates must be uint32, got ${value}`);
+    }
+  }
+  return input.kind === "timed" ? `timed:${input.movieFragmentSequenceNumber}:${input.sampleNumber}` : `non-timed:${input.itemId}`;
+}
+export {
+  asSeconds,
+  driftCheck,
+  groupIdFor,
+  groupIdForTicks,
+  secondsFromTicks,
+  subgroupKeyFor
+};
+//# sourceMappingURL=align.js.map

package/dist/align.js.map

@@ -0,0 +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` 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-init-parser.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Audio Init Data Parser — extract frame samples from a codec descriptor.
+ *
+ * Consumes the RAW codec configuration bytes (AudioSpecificConfig for AAC,
+ * OpusHead for Opus) — i.e. the catalog `description` field (hang
+ * `AudioConfig.description`), NOT the catalog `initData` field.
+ *
+ * Since BLO-9884 these are two distinct catalog fields: `initData` is a
+ * base64 ISOBMFF init segment (ftyp + moov) per draft-ietf-moq-cmsf-00 §3.1,
+ * while `description` carries the bare codec descriptor. Hang's `root.ts`
+ * parses a CMSF `initData` segment with `decodeInitSegment()` and routes the
+ * descriptor it recovers (`init.description`) into `description`; the bytes
+ * that reach this parser are therefore always the bare descriptor. Do NOT
+ * pass a ftyp+moov `initData` blob here — the ASC bit-reader would interpret
+ * the ftyp box size word as an audioObjectType and return a garbage frame
+ * count (the audio analogue of the "Failed to parse avcC" CMAF regression
+ * documented in root.ts).
+ *
+ * Supported codecs:
+ *   - AAC (mp4a.40.*): AudioSpecificConfig per ISO 14496-3 §1.6.2.1
+ *   - Opus: fixed 960 samples per RFC 6716 §2.1.4
+ *
+ * Reference: hang-mmt-fec/rs/moq-mux/src/import/aac.rs:AacConfig::parse()
+ */
+/**
+ * Parse AAC AudioSpecificConfig (ASC) to extract frame samples.
+ *
+ * ASC is a bit-packed structure (ISO 14496-3 §1.6.2.1):
+ *   audioObjectType (5 bits, or 5+6 if ==31)
+ *   samplingFrequencyIndex (4 bits, explicit rate if ==0xf)
+ *   channelConfiguration (4 bits)
+ *   ... (SBR/PS extensions follow)
+ *
+ * The audioObjectType determines frame samples:
+ *   LC-AAC → 1024, HE-AAC(SBR) → 2048, AAC-LD → 512, AAC-ELD → 480
+ *
+ * @param asc - Raw AudioSpecificConfig bytes (NOT ADTS, NOT fMP4 esds box)
+ * @returns frame samples, or null if ASC is invalid/too short
+ */
+export declare function parseAacFrameSamples(asc: Uint8Array): number | null;
+/**
+ * Parse AAC ASC to extract sample rate.
+ * Useful when catalog samplerate is missing but initData is available.
+ */
+export declare function parseAacSampleRate(asc: Uint8Array): number | null;
+/**
+ * Opus frame samples: 960 at 48kHz (20ms) per RFC 6716 §2.1.4.
+ *
+ * Opus supports variable frame sizes (2.5, 5, 10, 20, 40, 60, 80, 100, 120ms)
+ * but the frame size is per-packet (in the TOC byte), not in the init data.
+ * OpusHead (RFC 7845) carries sample_rate and channel_count only.
+ *
+ * 960 samples at 48kHz = 20ms is the normative default per RFC 6716.
+ */
+export declare function parseOpusFrameSamples(_opusHead?: Uint8Array): number;
+/**
+ * Extract frame samples from a bare codec descriptor based on codec string.
+ *
+ * @param codec - Codec string from catalog (e.g., "mp4a.40.2", "opus")
+ * @param codecConfig - Raw codec descriptor bytes: AudioSpecificConfig for
+ *   AAC, OpusHead for Opus. This is the catalog `description` field, NOT the
+ *   catalog `initData` (ftyp+moov) field — see the file header.
+ * @returns frame samples, or null if codec unsupported or the descriptor is invalid
+ */
+export declare function frameSamplesFromInit(codec: string, codecConfig: Uint8Array): number | null;
+//# sourceMappingURL=audio-init-parser.d.ts.map

package/dist/audio-init-parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audio-init-parser.d.ts","sourceRoot":"","sources":["../src/audio-init-parser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AA+BH;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,UAAU,GAAG,MAAM,GAAG,IAAI,CAuDnE;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,UAAU,GAAG,MAAM,GAAG,IAAI,CA0BjE;AAED;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,SAAS,CAAC,EAAE,UAAU,GAAG,MAAM,CAEpE;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,UAAU,GAAG,MAAM,GAAG,IAAI,CAQ1F"}

package/dist/audio-init-parser.js

@@ -0,0 +1,118 @@
+// src/audio-init-parser.ts
+var AAC_SAMPLE_RATES = [
+  96e3,
+  88200,
+  64e3,
+  48e3,
+  44100,
+  32e3,
+  24e3,
+  22050,
+  16e3,
+  12e3,
+  11025,
+  8e3,
+  7350
+];
+function aacFrameSamplesForObjectType(objectType) {
+  switch (objectType) {
+    case 5:
+      return 2048;
+    // SBR (HE-AAC v1)
+    case 29:
+      return 2048;
+    // PS (HE-AAC v2, implies SBR)
+    case 23:
+      return 512;
+    // ER AAC-LD
+    case 39:
+      return 480;
+    // ER AAC-ELD
+    default:
+      return 1024;
+  }
+}
+function parseAacFrameSamples(asc) {
+  if (asc.length < 2) return null;
+  let bitPos = 0;
+  const readBits = (n) => {
+    let val = 0;
+    for (let i = 0; i < n; i++) {
+      const byteIdx = bitPos + i >> 3;
+      const bitIdx = 7 - (bitPos + i & 7);
+      if (byteIdx >= asc.length) return -1;
+      val = val << 1 | asc[byteIdx] >> bitIdx & 1;
+    }
+    bitPos += n;
+    return val;
+  };
+  let objectType = readBits(5);
+  if (objectType === 31) {
+    objectType = 32 + readBits(6);
+  }
+  if (objectType < 0) return null;
+  const freqIndex = readBits(4);
+  if (freqIndex < 0) return null;
+  if (freqIndex === 15) {
+    readBits(24);
+  }
+  readBits(4);
+  if (objectType === 2 && asc.length >= 4) {
+    const remaining = asc.length * 8 - bitPos;
+    if (remaining >= 11) {
+      const syncExt = readBits(11);
+      if (syncExt === 695) {
+        const extObjectType = readBits(5);
+        if (extObjectType === 5 || extObjectType === 22) {
+          return 2048;
+        }
+        if (extObjectType === 29) {
+          return 2048;
+        }
+      }
+    }
+  }
+  return aacFrameSamplesForObjectType(objectType);
+}
+function parseAacSampleRate(asc) {
+  if (asc.length < 2) return null;
+  let bitPos = 0;
+  const readBits = (n) => {
+    let val = 0;
+    for (let i = 0; i < n; i++) {
+      const byteIdx = bitPos + i >> 3;
+      const bitIdx = 7 - (bitPos + i & 7);
+      if (byteIdx >= asc.length) return -1;
+      val = val << 1 | asc[byteIdx] >> bitIdx & 1;
+    }
+    bitPos += n;
+    return val;
+  };
+  let objectType = readBits(5);
+  if (objectType === 31) readBits(6);
+  const freqIndex = readBits(4);
+  if (freqIndex < 0) return null;
+  if (freqIndex === 15) {
+    return readBits(24);
+  }
+  return AAC_SAMPLE_RATES[freqIndex] ?? null;
+}
+function parseOpusFrameSamples(_opusHead) {
+  return 960;
+}
+function frameSamplesFromInit(codec, codecConfig) {
+  if (codec.startsWith("mp4a")) {
+    return parseAacFrameSamples(codecConfig);
+  }
+  if (codec.startsWith("opus") || codec === "Opus") {
+    return parseOpusFrameSamples(codecConfig);
+  }
+  return null;
+}
+export {
+  frameSamplesFromInit,
+  parseAacFrameSamples,
+  parseAacSampleRate,
+  parseOpusFrameSamples
+};
+//# sourceMappingURL=audio-init-parser.js.map

package/dist/audio-init-parser.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/audio-init-parser.ts"],
+  "sourcesContent": ["/**\n * Audio Init Data Parser \u2014 extract frame samples from a codec descriptor.\n *\n * Consumes the RAW codec configuration bytes (AudioSpecificConfig for AAC,\n * OpusHead for Opus) \u2014 i.e. the catalog `description` field (hang\n * `AudioConfig.description`), NOT the catalog `initData` field.\n *\n * Since BLO-9884 these are two distinct catalog fields: `initData` is a\n * base64 ISOBMFF init segment (ftyp + moov) per draft-ietf-moq-cmsf-00 \u00A73.1,\n * while `description` carries the bare codec descriptor. Hang's `root.ts`\n * parses a CMSF `initData` segment with `decodeInitSegment()` and routes the\n * descriptor it recovers (`init.description`) into `description`; the bytes\n * that reach this parser are therefore always the bare descriptor. Do NOT\n * pass a ftyp+moov `initData` blob here \u2014 the ASC bit-reader would interpret\n * the ftyp box size word as an audioObjectType and return a garbage frame\n * count (the audio analogue of the \"Failed to parse avcC\" CMAF regression\n * documented in root.ts).\n *\n * Supported codecs:\n *   - AAC (mp4a.40.*): AudioSpecificConfig per ISO 14496-3 \u00A71.6.2.1\n *   - Opus: fixed 960 samples per RFC 6716 \u00A72.1.4\n *\n * Reference: hang-mmt-fec/rs/moq-mux/src/import/aac.rs:AacConfig::parse()\n */\n\n// ISO 14496-3 Table 1.14: samplingFrequencyIndex \u2192 Hz\nconst AAC_SAMPLE_RATES = [\n  96000, 88200, 64000, 48000, 44100, 32000, 24000, 22050,\n  16000, 12000, 11025, 8000, 7350,\n] as const\n\n/**\n * AAC Audio Object Types that determine frame size.\n * ISO 14496-3 Table 1.3:\n *   1  = AAC-Main    \u2192 1024 samples\n *   2  = AAC-LC      \u2192 1024 samples\n *   3  = AAC-SSR     \u2192 1024 samples\n *   4  = AAC-LTP     \u2192 1024 samples\n *   5  = SBR         \u2192 2048 samples (HE-AAC v1)\n *   6  = AAC-Scalable \u2192 1024 samples\n *   23 = ER AAC-LD   \u2192 512 samples\n *   39 = ER AAC-ELD  \u2192 480 samples\n *   29 = PS          \u2192 2048 samples (HE-AAC v2, implies SBR)\n */\nfunction aacFrameSamplesForObjectType(objectType: number): number {\n  switch (objectType) {\n    case 5:  return 2048  // SBR (HE-AAC v1)\n    case 29: return 2048  // PS (HE-AAC v2, implies SBR)\n    case 23: return 512   // ER AAC-LD\n    case 39: return 480   // ER AAC-ELD\n    default: return 1024  // LC, Main, SSR, LTP, Scalable, etc.\n  }\n}\n\n/**\n * Parse AAC AudioSpecificConfig (ASC) to extract frame samples.\n *\n * ASC is a bit-packed structure (ISO 14496-3 \u00A71.6.2.1):\n *   audioObjectType (5 bits, or 5+6 if ==31)\n *   samplingFrequencyIndex (4 bits, explicit rate if ==0xf)\n *   channelConfiguration (4 bits)\n *   ... (SBR/PS extensions follow)\n *\n * The audioObjectType determines frame samples:\n *   LC-AAC \u2192 1024, HE-AAC(SBR) \u2192 2048, AAC-LD \u2192 512, AAC-ELD \u2192 480\n *\n * @param asc - Raw AudioSpecificConfig bytes (NOT ADTS, NOT fMP4 esds box)\n * @returns frame samples, or null if ASC is invalid/too short\n */\nexport function parseAacFrameSamples(asc: Uint8Array): number | null {\n  if (asc.length < 2) return null\n\n  // Bit reader\n  let bitPos = 0\n  const readBits = (n: number): number => {\n    let val = 0\n    for (let i = 0; i < n; i++) {\n      const byteIdx = (bitPos + i) >> 3\n      const bitIdx = 7 - ((bitPos + i) & 7)\n      if (byteIdx >= asc.length) return -1\n      val = (val << 1) | ((asc[byteIdx]! >> bitIdx) & 1)\n    }\n    bitPos += n\n    return val\n  }\n\n  // audioObjectType: 5 bits, extended to 5+6=11 bits if ==31\n  let objectType = readBits(5)\n  if (objectType === 31) {\n    objectType = 32 + readBits(6)\n  }\n  if (objectType < 0) return null\n\n  // samplingFrequencyIndex: 4 bits\n  const freqIndex = readBits(4)\n  if (freqIndex < 0) return null\n  if (freqIndex === 0xf) {\n    // Explicit 24-bit sample rate follows\n    readBits(24)\n  }\n\n  // channelConfiguration: 4 bits\n  readBits(4)\n\n  // Check for SBR/PS signaling (implicit in HE-AAC)\n  // If base objectType is AAC-LC and SBR extension is present, frame size doubles\n  if (objectType === 2 /* AAC-LC */ && asc.length >= 4) {\n    // Check for SBR extension: 11-bit sync word 0x2b7\n    const remaining = (asc.length * 8) - bitPos\n    if (remaining >= 11) {\n      const syncExt = readBits(11)\n      if (syncExt === 0x2b7) {\n        const extObjectType = readBits(5)\n        if (extObjectType === 5 /* SBR */ || extObjectType === 22 /* ER SBR */) {\n          return 2048 // SBR present \u2192 2048 samples\n        }\n        if (extObjectType === 29 /* PS */) {\n          return 2048 // PS implies SBR \u2192 2048 samples\n        }\n      }\n    }\n  }\n\n  return aacFrameSamplesForObjectType(objectType)\n}\n\n/**\n * Parse AAC ASC to extract sample rate.\n * Useful when catalog samplerate is missing but initData is available.\n */\nexport function parseAacSampleRate(asc: Uint8Array): number | null {\n  if (asc.length < 2) return null\n\n  let bitPos = 0\n  const readBits = (n: number): number => {\n    let val = 0\n    for (let i = 0; i < n; i++) {\n      const byteIdx = (bitPos + i) >> 3\n      const bitIdx = 7 - ((bitPos + i) & 7)\n      if (byteIdx >= asc.length) return -1\n      val = (val << 1) | ((asc[byteIdx]! >> bitIdx) & 1)\n    }\n    bitPos += n\n    return val\n  }\n\n  // Skip audioObjectType (5 or 11 bits)\n  let objectType = readBits(5)\n  if (objectType === 31) readBits(6)\n\n  const freqIndex = readBits(4)\n  if (freqIndex < 0) return null\n  if (freqIndex === 0xf) {\n    return readBits(24)\n  }\n  return AAC_SAMPLE_RATES[freqIndex] ?? null\n}\n\n/**\n * Opus frame samples: 960 at 48kHz (20ms) per RFC 6716 \u00A72.1.4.\n *\n * Opus supports variable frame sizes (2.5, 5, 10, 20, 40, 60, 80, 100, 120ms)\n * but the frame size is per-packet (in the TOC byte), not in the init data.\n * OpusHead (RFC 7845) carries sample_rate and channel_count only.\n *\n * 960 samples at 48kHz = 20ms is the normative default per RFC 6716.\n */\nexport function parseOpusFrameSamples(_opusHead?: Uint8Array): number {\n  return 960\n}\n\n/**\n * Extract frame samples from a bare codec descriptor based on codec string.\n *\n * @param codec - Codec string from catalog (e.g., \"mp4a.40.2\", \"opus\")\n * @param codecConfig - Raw codec descriptor bytes: AudioSpecificConfig for\n *   AAC, OpusHead for Opus. This is the catalog `description` field, NOT the\n *   catalog `initData` (ftyp+moov) field \u2014 see the file header.\n * @returns frame samples, or null if codec unsupported or the descriptor is invalid\n */\nexport function frameSamplesFromInit(codec: string, codecConfig: Uint8Array): number | null {\n  if (codec.startsWith('mp4a')) {\n    return parseAacFrameSamples(codecConfig)\n  }\n  if (codec.startsWith('opus') || codec === 'Opus') {\n    return parseOpusFrameSamples(codecConfig)\n  }\n  return null\n}\n"],
+  "mappings": ";AA0BA,IAAM,mBAAmB;AAAA,EACvB;AAAA,EAAO;AAAA,EAAO;AAAA,EAAO;AAAA,EAAO;AAAA,EAAO;AAAA,EAAO;AAAA,EAAO;AAAA,EACjD;AAAA,EAAO;AAAA,EAAO;AAAA,EAAO;AAAA,EAAM;AAC7B;AAeA,SAAS,6BAA6B,YAA4B;AAChE,UAAQ,YAAY;AAAA,IAClB,KAAK;AAAI,aAAO;AAAA;AAAA,IAChB,KAAK;AAAI,aAAO;AAAA;AAAA,IAChB,KAAK;AAAI,aAAO;AAAA;AAAA,IAChB,KAAK;AAAI,aAAO;AAAA;AAAA,IAChB;AAAS,aAAO;AAAA,EAClB;AACF;AAiBO,SAAS,qBAAqB,KAAgC;AACnE,MAAI,IAAI,SAAS,EAAG,QAAO;AAG3B,MAAI,SAAS;AACb,QAAM,WAAW,CAAC,MAAsB;AACtC,QAAI,MAAM;AACV,aAAS,IAAI,GAAG,IAAI,GAAG,KAAK;AAC1B,YAAM,UAAW,SAAS,KAAM;AAChC,YAAM,SAAS,KAAM,SAAS,IAAK;AACnC,UAAI,WAAW,IAAI,OAAQ,QAAO;AAClC,YAAO,OAAO,IAAO,IAAI,OAAO,KAAM,SAAU;AAAA,IAClD;AACA,cAAU;AACV,WAAO;AAAA,EACT;AAGA,MAAI,aAAa,SAAS,CAAC;AAC3B,MAAI,eAAe,IAAI;AACrB,iBAAa,KAAK,SAAS,CAAC;AAAA,EAC9B;AACA,MAAI,aAAa,EAAG,QAAO;AAG3B,QAAM,YAAY,SAAS,CAAC;AAC5B,MAAI,YAAY,EAAG,QAAO;AAC1B,MAAI,cAAc,IAAK;AAErB,aAAS,EAAE;AAAA,EACb;AAGA,WAAS,CAAC;AAIV,MAAI,eAAe,KAAkB,IAAI,UAAU,GAAG;AAEpD,UAAM,YAAa,IAAI,SAAS,IAAK;AACrC,QAAI,aAAa,IAAI;AACnB,YAAM,UAAU,SAAS,EAAE;AAC3B,UAAI,YAAY,KAAO;AACrB,cAAM,gBAAgB,SAAS,CAAC;AAChC,YAAI,kBAAkB,KAAe,kBAAkB,IAAiB;AACtE,iBAAO;AAAA,QACT;AACA,YAAI,kBAAkB,IAAa;AACjC,iBAAO;AAAA,QACT;AAAA,MACF;AAAA,IACF;AAAA,EACF;AAEA,SAAO,6BAA6B,UAAU;AAChD;AAMO,SAAS,mBAAmB,KAAgC;AACjE,MAAI,IAAI,SAAS,EAAG,QAAO;AAE3B,MAAI,SAAS;AACb,QAAM,WAAW,CAAC,MAAsB;AACtC,QAAI,MAAM;AACV,aAAS,IAAI,GAAG,IAAI,GAAG,KAAK;AAC1B,YAAM,UAAW,SAAS,KAAM;AAChC,YAAM,SAAS,KAAM,SAAS,IAAK;AACnC,UAAI,WAAW,IAAI,OAAQ,QAAO;AAClC,YAAO,OAAO,IAAO,IAAI,OAAO,KAAM,SAAU;AAAA,IAClD;AACA,cAAU;AACV,WAAO;AAAA,EACT;AAGA,MAAI,aAAa,SAAS,CAAC;AAC3B,MAAI,eAAe,GAAI,UAAS,CAAC;AAEjC,QAAM,YAAY,SAAS,CAAC;AAC5B,MAAI,YAAY,EAAG,QAAO;AAC1B,MAAI,cAAc,IAAK;AACrB,WAAO,SAAS,EAAE;AAAA,EACpB;AACA,SAAO,iBAAiB,SAAS,KAAK;AACxC;AAWO,SAAS,sBAAsB,WAAgC;AACpE,SAAO;AACT;AAWO,SAAS,qBAAqB,OAAe,aAAwC;AAC1F,MAAI,MAAM,WAAW,MAAM,GAAG;AAC5B,WAAO,qBAAqB,WAAW;AAAA,EACzC;AACA,MAAI,MAAM,WAAW,MAAM,KAAK,UAAU,QAAQ;AAChD,WAAO,sBAAsB,WAAW;AAAA,EAC1C;AACA,SAAO;AACT;",
+  "names": []
+}

package/dist/audio-ring-buffer.d.ts

@@ -0,0 +1,50 @@
+/**
+ * AudioRingBuffer — plain FIFO audio buffer (no clock recovery).
+ *
+ * Source of truth for the audio buffer algorithm used in both moq-lib and
+ * moqtail AudioWorklet processors. AudioWorklet isolation requires the
+ * worklet copy to be self-contained (no imports), so changes here must be
+ * manually synced to:
+ *   - moqtail-private/apps/client-js/src/lib/audio-worklet-processor.js
+ *   - hang-mmt-fec/js/watch/src/audio/ring-buffer.ts (uses @moq/lite Time types)
+ *
+ * Rationale: FEC guarantees gap-free, ordered audio on multicast; MoQ
+ * delivers ordered audio without drops. The decoder output rate matches
+ * the AudioContext destination rate closely enough that skip/dup clock
+ * recovery is unnecessary and harmful — a single sample skip at 48 kHz is
+ * a ~21 µs phase glitch, and repeated skip/dup produces audible pitch
+ * wobble on pure tones (measured: 16 Hz offset + ±11 Hz spread on a 1 kHz
+ * test tone before this refactor).
+ */
+export interface AudioRingBufferConfig {
+    /** Number of audio channels */
+    channels: number;
+    /** Sample rate in Hz */
+    rate: number;
+    /** Buffer latency in milliseconds */
+    latencyMs: number;
+    /** Start in unstalled state (for source switching) */
+    startUnstalled?: boolean;
+}
+export declare class AudioRingBuffer {
+    #private;
+    readonly channels: number;
+    readonly rate: number;
+    constructor(config: AudioRingBufferConfig);
+    get stalled(): boolean;
+    get capacity(): number;
+    get length(): number;
+    /**
+     * Append decoded audio samples to the FIFO.
+     * Timestamp parameter retained for API compatibility but is ignored —
+     * FIFO is sequence-based, not time-based.
+     */
+    write(_timestampUs: number, data: Float32Array[]): void;
+    /**
+     * Read samples into output buffers — plain FIFO, no clock recovery.
+     * FEC + MoQ delivery guarantees no gaps, so skip/dup is unnecessary.
+     * Underrun → zero-fill.
+     */
+    read(output: Float32Array[]): number;
+}
+//# sourceMappingURL=audio-ring-buffer.d.ts.map

package/dist/audio-ring-buffer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audio-ring-buffer.d.ts","sourceRoot":"","sources":["../src/audio-ring-buffer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,MAAM,WAAW,qBAAqB;IACpC,+BAA+B;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,wBAAwB;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,qCAAqC;IACrC,SAAS,EAAE,MAAM,CAAC;IAClB,sDAAsD;IACtD,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,qBAAa,eAAe;;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBAOV,MAAM,EAAE,qBAAqB;IAYzC,IAAI,OAAO,IAAI,OAAO,CAA0B;IAChD,IAAI,QAAQ,IAAI,MAAM,CAAmC;IACzD,IAAI,MAAM,IAAI,MAAM,CAA+C;IAEnE;;;;OAIG;IACH,KAAK,CAAC,YAAY,EAAE,MAAM,EAAE,IAAI,EAAE,YAAY,EAAE,GAAG,IAAI;IA8BvD;;;;OAIG;IACH,IAAI,CAAC,MAAM,EAAE,YAAY,EAAE,GAAG,MAAM;CAwBrC"}

package/dist/audio-ring-buffer.js

@@ -0,0 +1,80 @@
+// src/audio-ring-buffer.ts
+var AudioRingBuffer = class {
+  #buffer;
+  #writeIndex = 0;
+  #readIndex = 0;
+  #stalled;
+  constructor(config) {
+    this.channels = config.channels;
+    this.rate = config.rate;
+    this.#stalled = !(config.startUnstalled ?? false);
+    const samples = Math.ceil(config.rate * (config.latencyMs / 1e3));
+    this.#buffer = [];
+    for (let i = 0; i < config.channels; i++) {
+      this.#buffer[i] = new Float32Array(samples);
+    }
+  }
+  get stalled() {
+    return this.#stalled;
+  }
+  get capacity() {
+    return this.#buffer[0].length;
+  }
+  get length() {
+    return this.#writeIndex - this.#readIndex;
+  }
+  /**
+   * Append decoded audio samples to the FIFO.
+   * Timestamp parameter retained for API compatibility but is ignored —
+   * FIFO is sequence-based, not time-based.
+   */
+  write(_timestampUs, data) {
+    const samples = data[0].length;
+    const start = this.#writeIndex;
+    const end = start + samples;
+    const overflow = end - this.#readIndex - this.#buffer[0].length;
+    if (overflow >= 0) {
+      this.#stalled = false;
+      this.#readIndex += overflow;
+    }
+    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 = this.#buffer[ch];
+      for (let i = 0; i < samples; i++) {
+        dst[(start + i) % dst.length] = src[i];
+      }
+    }
+    this.#writeIndex = end;
+  }
+  /**
+   * Read samples into output buffers — plain FIFO, no clock recovery.
+   * FEC + MoQ delivery guarantees no gaps, so skip/dup is unnecessary.
+   * Underrun → zero-fill.
+   */
+  read(output) {
+    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 = this.#buffer[ch];
+      for (let i = 0; i < readSamples; i++) {
+        dst[i] = src[(this.#readIndex + i) % src.length];
+      }
+      for (let i = readSamples; i < requested; i++) {
+        dst[i] = 0;
+      }
+    }
+    this.#readIndex += readSamples;
+    return readSamples;
+  }
+};
+export {
+  AudioRingBuffer
+};
+//# sourceMappingURL=audio-ring-buffer.js.map

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

@@ -0,0 +1,7 @@
+{
+  "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": ";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": []
+}