@blockcast/mmt-container 2.0.1 → 2.1.0-main.5b10b5454faf

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -97,7 +97,7 @@ export interface MulticastRepairEndpoint {
97
97
  /** The repair packet IDs this group carries. */
98
98
  packetIds: number[];
99
99
  /** Each repair packet ID bound to the media packet ID it repairs. */
100
- repairOwners: ReadonlyArray<{ packetId: number; ownerPacketId: number }>;
100
+ repairOwners: ReadonlyArray<{ packetId: number; ownerPacketId: number; instance?: "keyframe" }>;
101
101
  /** Ingress tracks: the owners' source tracks and the repair tracks. */
102
102
  tracks: MmtpIngressContext["tracks"];
103
103
  /** The protected flow (`MmtpRouter.registerProvenanceFlow`) this group's datagrams belong to. */
@@ -590,7 +590,7 @@ function newBlockPolicyStats(
590
590
  repairsSkippedRangeNoAnchor: 0,
591
591
  repairsSkippedGroupCannotComplete: 0,
592
592
  repairsSkippedMootRap: 0,
593
- repairStops: { preempted: 0, reprioritized: 0, expired: 0, resolved: 0, reset: 0, disposed: 0, moot: 0 },
593
+ repairStops: { preempted: 0, reprioritized: 0, expired: 0, resolved: 0, reset: 0, disposed: 0, moot: 0, "overlay-recovered": 0 },
594
594
  lastRepairSkip: null,
595
595
  keyframeRepairFetchesSent: 0,
596
596
  rangeRepairFetchesSent: 0,
@@ -1257,14 +1257,27 @@ function repairTrackNamesBySource(
1257
1257
  return bySource;
1258
1258
  }
1259
1259
 
1260
- /** The repair tracks an `ok` binding joins: base layers, then the overlay. */
1260
+ /** The base repair layers an `ok` binding joins. The keyframe overlay is
1261
+ * not among them: it is its own FEC instance (draft-ramadan-mmt-fec-02 7.4). */
1261
1262
  function boundRepairNames(binding: FecSourceBinding | undefined): string[] {
1262
1263
  if (binding?.status !== "ok") return [];
1263
- const names = binding.layers.map((layer) => layer.repairTrackName);
1264
- if (binding.overlay) names.push(binding.overlay.repairTrackName);
1265
- return names;
1264
+ return binding.layers.map((layer) => layer.repairTrackName);
1266
1265
  }
1267
1266
 
1267
+ interface OverlayBinding {
1268
+ repairPacketId: number;
1269
+ repairTrackName: string;
1270
+ sourceCatalogTrackName: string;
1271
+ k: number;
1272
+ symbolSize: number;
1273
+ blockProfile: FecBlockProfile;
1274
+ }
1275
+
1276
+ type RepairOwnerEntry = MulticastRepairEndpoint["repairOwners"][number] & {
1277
+ ownerTrackName?: string;
1278
+ repairTrackName?: string;
1279
+ };
1280
+
1268
1281
  export class MulticastManager {
1269
1282
  readonly #fec: FECManager;
1270
1283
  readonly #router: MmtpRouter;
@@ -1276,7 +1289,11 @@ export class MulticastManager {
1276
1289
  #failbackHooked = false;
1277
1290
  /** Live joinRepairEndpoints() releases → the repair owners they registered,
1278
1291
  * re-applied after configureMultiTrack() clears catalog-derived owners. */
1279
- readonly #repairReleases = new Map<() => void, MulticastRepairEndpoint["repairOwners"]>();
1292
+ readonly #repairReleases = new Map<() => void, RepairOwnerEntry[]>();
1293
+ /** Each source's catalog keyframe overlay, from its `ok` binding. */
1294
+ readonly #overlayBindings = new Map<number, OverlayBinding>();
1295
+ /** Installed overlay decoders (`setKeyframeOverlayDecoder`), by source. */
1296
+ readonly #overlayInstalls = new Map<number, { reattach: () => void; dispose: () => void }>();
1280
1297
  #reportedFecDiagnosticsFailure = false;
1281
1298
 
1282
1299
  // ── Stream-global FEC timing reduction ──
@@ -1568,6 +1585,65 @@ export class MulticastManager {
1568
1585
  this.#router.setPacketIdType(packetId, trackType);
1569
1586
  }
1570
1587
 
1588
+ /**
1589
+ * Decode the keyframe overlay of `sourcePacketId` (draft-ramadan-mmt-fec-02
1590
+ * 7.4) with `decoder`, a decoder of the same kind `setFecDecoder` takes.
1591
+ * Opt-in: nothing else installs one, so a receiver that never calls this
1592
+ * holds no overlay state and drops overlay repair. K_overlay, T, scheme
1593
+ * and block profile come from the source's `ok` catalog binding, which
1594
+ * must declare an overlay (`configureMultiTrack` first). The overlay is
1595
+ * decoded on its own FEC state, apart from the base: no repair FETCH, no
1596
+ * repair lifecycle event and no base statistic for its blocks. A second
1597
+ * install on the same source replaces the first; the returned disposer
1598
+ * removes only the install it created. Call it on releasing the overlay
1599
+ * join.
1600
+ */
1601
+ setKeyframeOverlayDecoder(
1602
+ sourcePacketId: number,
1603
+ decoder: WasmFecDecoder,
1604
+ catalogTrackName?: string,
1605
+ ): () => void {
1606
+ const binding = this.#overlayBindings.get(sourcePacketId);
1607
+ if (!binding || (catalogTrackName !== undefined && binding.sourceCatalogTrackName !== catalogTrackName)) {
1608
+ throw new Error(
1609
+ `[MulticastManager] packetId=${sourcePacketId} has no catalog keyframe overlay to decode`,
1610
+ );
1611
+ }
1612
+ this.#overlayInstalls.get(sourcePacketId)?.dispose();
1613
+ let fec: FECManager;
1614
+ let uninstall: () => void;
1615
+ const attach = () => {
1616
+ fec = new FECManager();
1617
+ fec.setFecDecoder(binding.repairPacketId, decoder, binding.k, {
1618
+ blockProfile: binding.blockProfile,
1619
+ k: binding.k,
1620
+ symbolSize: binding.symbolSize,
1621
+ trackKind: "video",
1622
+ }, binding.repairTrackName);
1623
+ uninstall = this.#router.installKeyframeOverlay(
1624
+ binding.repairPacketId, fec, binding.k, binding.repairTrackName,
1625
+ );
1626
+ };
1627
+ const detach = () => {
1628
+ uninstall();
1629
+ fec.releasePacket(binding.repairPacketId);
1630
+ };
1631
+ attach();
1632
+ const install = {
1633
+ reattach: () => {
1634
+ detach();
1635
+ attach();
1636
+ },
1637
+ dispose: () => {
1638
+ if (this.#overlayInstalls.get(sourcePacketId) !== install) return;
1639
+ this.#overlayInstalls.delete(sourcePacketId);
1640
+ detach();
1641
+ },
1642
+ };
1643
+ this.#overlayInstalls.set(sourcePacketId, install);
1644
+ return install.dispose;
1645
+ }
1646
+
1571
1647
  /**
1572
1648
  * Register a Worker-backed FEC decoder for a specific packetId (track).
1573
1649
  * Worker-backed tracks decode asynchronously — recovered frames arrive via
@@ -2291,7 +2367,14 @@ export class MulticastManager {
2291
2367
  console.warn("[MulticastManager] repair group release failed", error);
2292
2368
  }
2293
2369
  };
2294
- const repairOwners = endpoints.flatMap((endpoint) => endpoint.repairOwners);
2370
+ // An overlay leg's source and repair track names come from the
2371
+ // endpoint's ingress tracks.
2372
+ const repairOwners: RepairOwnerEntry[] = endpoints.flatMap((endpoint) =>
2373
+ endpoint.repairOwners.map((owner) => owner.instance !== "keyframe" ? owner : {
2374
+ ...owner,
2375
+ ownerTrackName: endpoint.tracks.find((t) => t.packetId === owner.ownerPacketId)?.name,
2376
+ repairTrackName: endpoint.tracks.find((t) => t.packetId === owner.packetId)?.name,
2377
+ }));
2295
2378
  this.#applyRepairOwners(repairOwners);
2296
2379
  for (const endpoint of endpoints) {
2297
2380
  const ingress: MmtpIngressContext = {
@@ -2344,10 +2427,18 @@ export class MulticastManager {
2344
2427
  return release;
2345
2428
  }
2346
2429
 
2347
- #applyRepairOwners(owners: MulticastRepairEndpoint["repairOwners"]): void {
2348
- for (const { packetId, ownerPacketId } of owners) {
2430
+ #applyRepairOwners(owners: RepairOwnerEntry[]): void {
2431
+ for (const { packetId, ownerPacketId, instance, ownerTrackName, repairTrackName } of owners) {
2349
2432
  this.#router.setPacketIdRole(packetId, "repair");
2350
- this.#router.setRepairPacketIdOwner(packetId, ownerPacketId);
2433
+ if (instance === "keyframe") {
2434
+ this.#router.setKeyframeOverlayLeg(packetId, {
2435
+ sourcePacketId: ownerPacketId,
2436
+ ...(ownerTrackName === undefined ? {} : { sourceCatalogTrackName: ownerTrackName }),
2437
+ ...(repairTrackName === undefined ? {} : { repairTrackName }),
2438
+ });
2439
+ } else {
2440
+ this.#router.setRepairPacketIdOwner(packetId, ownerPacketId);
2441
+ }
2351
2442
  }
2352
2443
  }
2353
2444
 
@@ -2668,8 +2759,10 @@ export class MulticastManager {
2668
2759
  packet: Uint8Array,
2669
2760
  ownerPacketId?: number,
2670
2761
  catalogTrackName?: string,
2762
+ /** The repair track it arrived on: names its FEC instance (mmt-02 7.4.2). */
2763
+ repairTrackName?: string,
2671
2764
  ) {
2672
- this.#router.feedRepairPacket(packet, ownerPacketId, catalogTrackName);
2765
+ this.#router.feedRepairPacket(packet, ownerPacketId, catalogTrackName, repairTrackName);
2673
2766
  }
2674
2767
 
2675
2768
  /** Route a Worker-recovered FEC block through the MMTP parser + dedup pipeline. */
@@ -2759,7 +2852,10 @@ export class MulticastManager {
2759
2852
  const ownedRepairNames = new Set<string>();
2760
2853
  const claimed = new Map<string, number>();
2761
2854
  for (const binding of bindings.values()) {
2762
- for (const name of boundRepairNames(binding)) claimed.set(name, (claimed.get(name) ?? 0) + 1);
2855
+ const overlay = binding.status === "ok" ? binding.overlay?.repairTrackName : undefined;
2856
+ for (const name of [...boundRepairNames(binding), ...(overlay === undefined ? [] : [overlay])]) {
2857
+ claimed.set(name, (claimed.get(name) ?? 0) + 1);
2858
+ }
2763
2859
  }
2764
2860
  for (const [name, count] of claimed) if (count === 1) ownedRepairNames.add(name);
2765
2861
  const repairOwnerGroup = new Map<string, string>();
@@ -2896,6 +2992,7 @@ export class MulticastManager {
2896
2992
  const catalogTracksByName = new Map(
2897
2993
  catalog.tracks.map((track) => [track.name, track] as const),
2898
2994
  );
2995
+ const overlayBindings = new Map<number, OverlayBinding>();
2899
2996
 
2900
2997
  for (let i = 0; i < catalog.tracks.length; i++) {
2901
2998
  const track = catalog.tracks[i]!;
@@ -2928,10 +3025,12 @@ export class MulticastManager {
2928
3025
  const binding = bindings.get(track.name);
2929
3026
  if (binding?.status === "ok") {
2930
3027
  const fecCfg = binding.base;
2931
- // Every repair layer and the keyframe overlay route to this source's
2932
- // decoder, not only layer 0. A layer whose packetId had no registered
2933
- // owner would have its repair symbols dropped as an unknown owner, and
2934
- // two sources whose RS_ID ranges overlap would be indistinguishable.
3028
+ // Every base repair layer routes to this source's decoder, not only
3029
+ // layer 0. A layer whose packetId had no registered owner would have
3030
+ // its repair symbols dropped as an unknown owner, and two sources whose
3031
+ // RS_ID ranges overlap would be indistinguishable. The keyframe overlay
3032
+ // is another FEC instance: it is recorded as an overlay leg, never
3033
+ // owned by this source's base decoder (draft-ramadan-mmt-fec-02 7.4.4).
2935
3034
  if (track.packetId !== undefined) {
2936
3035
  for (const repairName of boundRepairNames(binding)) {
2937
3036
  if (!ownedRepairNames.has(repairName)) continue;
@@ -2940,6 +3039,32 @@ export class MulticastManager {
2940
3039
  this.#router.setRepairPacketIdOwner(repairTrack.packetId, track.packetId);
2941
3040
  }
2942
3041
  }
3042
+ // By its name too: a catalog that states no PID for it (learned at
3043
+ // subscribe time) must still keep its MoQ repair from the base.
3044
+ const overlayName = binding.overlay?.repairTrackName;
3045
+ const overlayPacketId = overlayName === undefined ? undefined : catalogTracksByName.get(overlayName)?.packetId;
3046
+ if (overlayName !== undefined && ownedRepairNames.has(overlayName)) {
3047
+ this.#router.setKeyframeOverlayLeg(overlayPacketId, {
3048
+ sourcePacketId: track.packetId,
3049
+ sourceCatalogTrackName: track.name,
3050
+ repairTrackName: overlayName,
3051
+ });
3052
+ }
3053
+ // Decodable only with its packet ID: its symbols are keyed by it.
3054
+ if (overlayName !== undefined && overlayPacketId !== undefined && ownedRepairNames.has(overlayName)) {
3055
+ const geometry = binding.overlay!.geometry;
3056
+ overlayBindings.set(track.packetId, {
3057
+ repairPacketId: overlayPacketId,
3058
+ repairTrackName: overlayName,
3059
+ sourceCatalogTrackName: track.name,
3060
+ k: binding.overlay!.sourceSymbols,
3061
+ symbolSize: fecCfg.symbolSize,
3062
+ blockProfile: parseFecBlockProfile(
3063
+ geometry.blockProfile,
3064
+ `tracks[${JSON.stringify(track.name)}].fec keyframe overlay blockProfile`,
3065
+ ),
3066
+ });
3067
+ }
2943
3068
  }
2944
3069
  const wasmDecoder = fecDecoders.get(i);
2945
3070
  if (track.packetId !== undefined && wasmDecoder !== undefined) {
@@ -2977,6 +3102,20 @@ export class MulticastManager {
2977
3102
  }
2978
3103
  }
2979
3104
  }
3105
+ // An installed overlay decoder starts a new epoch on a reconfigure, or is
3106
+ // disposed when the new catalog no longer declares the same overlay.
3107
+ for (const [sourcePacketId, install] of [...this.#overlayInstalls]) {
3108
+ const before = this.#overlayBindings.get(sourcePacketId);
3109
+ const after = overlayBindings.get(sourcePacketId);
3110
+ const same = before !== undefined && after !== undefined &&
3111
+ (Object.keys(after) as Array<keyof OverlayBinding>).every((key) => after[key] === before[key]);
3112
+ if (!same) install.dispose();
3113
+ else if (this.#router.hasKeyframeOverlay(after.repairPacketId)) this.#router.resetKeyframeOverlays(sourcePacketId);
3114
+ // A retired packet ID took the router's instance with it.
3115
+ else install.reattach();
3116
+ }
3117
+ this.#overlayBindings.clear();
3118
+ for (const [sourcePacketId, binding] of overlayBindings) this.#overlayBindings.set(sourcePacketId, binding);
2980
3119
  }
2981
3120
 
2982
3121
  /**
@@ -3202,6 +3341,13 @@ export class MulticastManager {
3202
3341
  return this.#router.addFecRapObserver(observer);
3203
3342
  }
3204
3343
 
3344
+ /** Observe each base block whose RAP the keyframe overlay recovered (fec-multicast-00 §6.6). */
3345
+ addKeyframeOverlayRecoveredObserver(
3346
+ observer: (packetId: number, catalogTrackName: string | undefined, sbn: number) => void,
3347
+ ): () => void {
3348
+ return this.#router.addKeyframeOverlayRecoveredObserver(observer);
3349
+ }
3350
+
3205
3351
  /** Catalog/reset epoch of a packet's streams; gap decisions carry it. */
3206
3352
  epochFor(packetId: number): number {
3207
3353
  return this.#fec.epochFor(packetId);
@@ -545,6 +545,14 @@ export interface RepairFetchHost {
545
545
  addRapCompleteObserver?(
546
546
  observer: (packetId: number, catalogTrackName: string | undefined, ssId: number) => void,
547
547
  ): () => void
548
+ /**
549
+ * Observe each base block (`sbn`) whose RAP fragments the keyframe overlay
550
+ * recovered with the keyframe's FT=0 and FT=1 held (optional; called
551
+ * synchronously). Its keyframe FETCH is then stopped (fec-multicast-00 §6.6).
552
+ */
553
+ addKeyframeOverlayRecoveredObserver?(
554
+ observer: (packetId: number, catalogTrackName: string | undefined, sbn: number) => void,
555
+ ): () => void
548
556
  /**
549
557
  * A FETCH the scheduler admitted and handed to the transport (optional):
550
558
  * every attempt, a retry or a reprioritised restart included.
@@ -562,8 +570,9 @@ export interface RepairFetchHost {
562
570
  * Why the scheduler ended a running FETCH (the transport cancels it on the
563
571
  * wire): preempted by a sent keyframe FETCH, reissued at a new class's
564
572
  * priority, past its deadline, its block resolved, track reset or a newer
565
- * request for the block, dispose, or `moot` (a RAP above the block arrived
566
- * complete first, draft-ramadan-moq-fec §11.4.2).
573
+ * request for the block, dispose, `moot` (a RAP above the block arrived
574
+ * complete first, draft-ramadan-moq-fec §11.4.2), or `overlay-recovered`
575
+ * (the keyframe overlay recovered the block's RAP, fec-multicast-00 §6.6).
567
576
  */
568
577
  export type RepairStopReason =
569
578
  | 'preempted'
@@ -573,6 +582,7 @@ export type RepairStopReason =
573
582
  | 'reset'
574
583
  | 'disposed'
575
584
  | 'moot'
585
+ | 'overlay-recovered'
576
586
  type StopReason = RepairStopReason
577
587
 
578
588
  interface FetchRun {
@@ -1373,12 +1383,32 @@ export function wireRepairFetch(mc: RepairFetchHost, opts: WireRepairFetchOption
1373
1383
  })
1374
1384
  })
1375
1385
 
1386
+ // fec-multicast-00 §6.6: once the overlay recovered a block's RAP (its FT=0
1387
+ // and FT=1 held), the rest of the block is concealed as a non-keyframe
1388
+ // block, so its keyframe FETCH is stopped whatever its deadline. Deferred
1389
+ // as the RAP observer is: this fires from inside the recovered-block route.
1390
+ const removeOverlayObserver = mc.addKeyframeOverlayRecoveredObserver?.((packetId, catalogTrackName, sbn) => {
1391
+ queueMicrotask(() => {
1392
+ if (disposed) return
1393
+ for (const entry of [...entries.values()]) {
1394
+ if (entry.range || entry.priority !== 0 || entry.packetId !== packetId || entry.sbn !== sbn) continue
1395
+ if (catalogTrackName !== undefined && entry.catalogTrackName !== catalogTrackName) continue
1396
+ stop(entry, 'overlay-recovered')
1397
+ retire(entry)
1398
+ releaseHold(entry)
1399
+ clearEntry(entry)
1400
+ }
1401
+ dispatch()
1402
+ })
1403
+ })
1404
+
1376
1405
  return () => {
1377
1406
  disposed = true
1378
1407
  mc.setUnicastRepair?.(false)
1379
1408
  removeResetObserver()
1380
1409
  removeLifecycleObserver()
1381
1410
  removeRapObserver?.()
1411
+ removeOverlayObserver?.()
1382
1412
  for (const entry of [...entries.values()]) {
1383
1413
  clearEntry(entry)
1384
1414
  if (entry.running) releaseHold(entry)