@blockcast/mmt-container 2.0.1-main.0f2de6af487b → 2.0.1-main.d041867bf493

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.
@@ -22431,6 +22431,14 @@ function isRouterDebugEnabled() {
22431
22431
  function debugRouter(message) {
22432
22432
  if (isRouterDebugEnabled()) console.debug(message);
22433
22433
  }
22434
+ var KEYFRAME_OVERLAY_EXTENSION_TYPE = 35585;
22435
+ function keyframeOverlaySsId(header) {
22436
+ const ext = header.extension;
22437
+ if (ext?.type !== KEYFRAME_OVERLAY_EXTENSION_TYPE || ext.data.length !== 4) return void 0;
22438
+ return new DataView(ext.data.buffer, ext.data.byteOffset, 4).getUint32(0);
22439
+ }
22440
+ var OVERLAY_OFFSET_MPUS = 16;
22441
+ var OVERLAY_MOQ_HORIZON_BLOCKS = 64;
22434
22442
  function assertStreamIdentity(role, stream) {
22435
22443
  if (stream === void 0 || !Number.isInteger(stream.packetId) || stream.packetId <= MMTP_SIGNALING_PACKET_ID || typeof stream.catalogTrackName !== "string" || stream.catalogTrackName.length === 0) {
22436
22444
  throw new Error(
@@ -22654,7 +22662,19 @@ var MmtpRouter = class {
22654
22662
  /** Keyframe-overlay repair track names, which name a leg too: a catalog
22655
22663
  * may state no PID for it (learned at subscribe time). */
22656
22664
  #overlayRepairNames = /* @__PURE__ */ new Map();
22657
- #overlayStats = { repairDropped: 0, ownerRefused: 0 };
22665
+ /** Installed overlay instances, by overlay repair PID (opt-in only). */
22666
+ #overlays = /* @__PURE__ */ new Map();
22667
+ #overlayRecoveredObservers = /* @__PURE__ */ new Set();
22668
+ /** Streams whose recovered sequence the base path ever re-stamped. */
22669
+ #restampedStreams = /* @__PURE__ */ new Set();
22670
+ #overlayStats = {
22671
+ repairDropped: 0,
22672
+ ownerRefused: 0,
22673
+ recovered: 0,
22674
+ restarts: 0,
22675
+ unsequencedDropped: 0,
22676
+ protectedDropped: 0
22677
+ };
22658
22678
  /** Callback fired when a delta-track FEC block completes or fails. */
22659
22679
  #onDeltaBlockCompleteCb = null;
22660
22680
  // Debug counters
@@ -22851,6 +22871,7 @@ var MmtpRouter = class {
22851
22871
  this.#fecManager.onSourceDiscontinuity = (packetId, catalogTrackName) => {
22852
22872
  this.#parser.markFecDiscontinuity(packetId, catalogTrackName);
22853
22873
  this.#requestFecPoke(packetId, catalogTrackName);
22874
+ this.resetKeyframeOverlays(packetId, catalogTrackName);
22854
22875
  };
22855
22876
  this.#fecManager.onBlockComplete = (sbn, packetId, catalogTrackName) => {
22856
22877
  this.#mseAssemblerFor(packetId, catalogTrackName)?.completeBlock(sbn);
@@ -23206,19 +23227,253 @@ var MmtpRouter = class {
23206
23227
  keyframeOverlayLeg(repairPacketId) {
23207
23228
  return this.#overlayLegs.get(repairPacketId);
23208
23229
  }
23209
- /** Overlay repair dropped for want of an overlay instance, and base-owner
23210
- * registrations refused on an overlay PID. */
23230
+ /**
23231
+ * Overlay counters: repair dropped for want of an installed instance, base
23232
+ * owners refused on an overlay PID, overlay blocks recovered, overlay
23233
+ * restarts, and recovered packets dropped for want of a wire sequence or
23234
+ * for a MoQ symbol on a protected flow (multicast-02 7.2.7).
23235
+ */
23211
23236
  get keyframeOverlayStats() {
23212
23237
  return { ...this.#overlayStats };
23213
23238
  }
23214
23239
  #isOverlayRepair(repairPacketId, repairTrackName) {
23215
23240
  return this.#overlayLegs.has(repairPacketId) || repairTrackName !== void 0 && this.#overlayRepairNames.has(repairTrackName);
23216
23241
  }
23217
- /** Overlay repair has no decoder until the overlay instance lands
23218
- * (BLO-52077 PR 2): drop it before any base owner, locator or decoder. */
23219
- #dropOverlayRepair(repairPacketId) {
23220
- this.#overlayStats.repairDropped++;
23221
- debugRouter(`[MmtpRouter] Dropping keyframe-overlay repair pid=${repairPacketId}: no overlay instance`);
23242
+ /**
23243
+ * Install the keyframe overlay decoded on `fec` for a known overlay leg
23244
+ * (draft-ramadan-mmt-fec-02 7.4.4: decoded independently of the base). `fec`
23245
+ * holds the overlay stream under `repairPacketId` and `streamName`. Replaces
23246
+ * an earlier install on the same leg; the returned disposer removes only
23247
+ * this one.
23248
+ */
23249
+ installKeyframeOverlay(repairPacketId, fec, k, streamName) {
23250
+ const leg = this.#overlayLegs.get(repairPacketId);
23251
+ if (!leg) throw new Error(`[MmtpRouter] packetId=${repairPacketId} is no known keyframe-overlay leg`);
23252
+ const inst = {
23253
+ repairPacketId,
23254
+ streamName,
23255
+ leg: { ...leg },
23256
+ fec,
23257
+ k,
23258
+ offsets: /* @__PURE__ */ new Map(),
23259
+ moqBlocks: /* @__PURE__ */ new Set()
23260
+ };
23261
+ this.#overlays.set(repairPacketId, inst);
23262
+ return () => {
23263
+ if (this.#overlays.get(repairPacketId) === inst) this.#overlays.delete(repairPacketId);
23264
+ };
23265
+ }
23266
+ /**
23267
+ * Observe each base block whose RAP MFU fragments a keyframe-overlay
23268
+ * recovery supplied, with the keyframe's FT=0 and FT=1 held
23269
+ * (fec-multicast-00 §6.6). The block is named by the recovered packets'
23270
+ * restored wire sequence through the base SS_ID offset, never by an overlay
23271
+ * coordinate. Called synchronously from the recovered-block route.
23272
+ */
23273
+ addKeyframeOverlayRecoveredObserver(observer) {
23274
+ this.#overlayRecoveredObservers.add(observer);
23275
+ return () => {
23276
+ this.#overlayRecoveredObservers.delete(observer);
23277
+ };
23278
+ }
23279
+ /** Whether an overlay is installed on `repairPacketId`. */
23280
+ hasKeyframeOverlay(repairPacketId) {
23281
+ return this.#overlays.has(repairPacketId);
23282
+ }
23283
+ /**
23284
+ * Start a new epoch of every overlay protecting `sourcePacketId` (its
23285
+ * source restarted): empty overlay stream, no coverage, no offsets.
23286
+ */
23287
+ resetKeyframeOverlays(sourcePacketId, catalogTrackName) {
23288
+ for (const inst of this.#overlaysForSource(sourcePacketId, catalogTrackName)) this.#resetOverlay(inst);
23289
+ }
23290
+ #resetOverlay(inst) {
23291
+ inst.fec.resetTrack(inst.repairPacketId, inst.streamName);
23292
+ inst.last = void 0;
23293
+ inst.offsets.clear();
23294
+ inst.moqBlocks.clear();
23295
+ }
23296
+ #overlaysForSource(sourcePacketId, catalogTrackName) {
23297
+ return [...this.#overlays.values()].filter(({ leg }) => leg.sourcePacketId === sourcePacketId && (catalogTrackName === void 0 || leg.sourceCatalogTrackName === void 0 || leg.sourceCatalogTrackName === catalogTrackName));
23298
+ }
23299
+ /**
23300
+ * The overlay instance a repair packet belongs to, by the track it arrived
23301
+ * on (7.4.2: its PID or its repair track name); null for overlay repair
23302
+ * with no instance installed; undefined for repair of no overlay.
23303
+ */
23304
+ #overlayRepairTarget(repairPacketId, repairTrackName) {
23305
+ const inst = this.#overlays.get(repairPacketId) ?? (repairTrackName === void 0 ? void 0 : [...this.#overlays.values()].find(({ leg }) => leg.repairTrackName === repairTrackName));
23306
+ if (inst) return inst;
23307
+ return this.#isOverlayRepair(repairPacketId, repairTrackName) ? null : void 0;
23308
+ }
23309
+ /** Overlay repair goes to its own instance, never to a base owner, locator
23310
+ * or decoder; with none installed it is dropped and counted. */
23311
+ #routeOverlayRepair(inst, repairPacketId, packet, header, source) {
23312
+ const repair = inst ? parseMoqRepairFrameWithHeader(packet, header) : null;
23313
+ if (!inst || !repair) {
23314
+ this.#overlayStats.repairDropped++;
23315
+ debugRouter(`[MmtpRouter] Dropping keyframe-overlay repair pid=${repairPacketId}: no overlay instance`);
23316
+ return;
23317
+ }
23318
+ const { fec, repairPacketId: pid, streamName: name } = inst;
23319
+ if (!fec.admitRepairBlockLength(pid, repair.ssbLength, repair.rsbLength, repair.rsId)) return;
23320
+ if (!fec.admitRepairSymbolSize(pid, repair.ssStart, repair.ssbLength, repair.rsId, repair.symbolData.byteLength)) return;
23321
+ const placement = fec.placeIsoRepair(pid, name, repair.ssStart, repair.ssbLength);
23322
+ if (placement.status !== "placed") return;
23323
+ const blockStart = placement.block.start;
23324
+ if (placement.span !== void 0) this.#replayOverlaySources(inst, placement.span.block.start, placement.span.placed);
23325
+ this.#replayOverlaySources(inst, blockStart, placement.placed);
23326
+ if (source === "moq") this.#noteOverlayMoqBlock(inst, blockStart);
23327
+ const alreadyCompleted = fec.isBlockCompleted(blockStart, pid, name);
23328
+ const recovered = fec.feedRepairSymbol(pid, repair.ssStart, repair.ssbLength, repair.rsId, repair.symbolData, name);
23329
+ if (recovered && !alreadyCompleted) this.#routeOverlayRecovered(inst, blockStart, recovered);
23330
+ }
23331
+ #replayOverlaySources(inst, blockStart, placed) {
23332
+ const { fec, repairPacketId: pid, streamName: name } = inst;
23333
+ for (const { ssId, payload } of placed) {
23334
+ if (payload.source === "moq") this.#noteOverlayMoqBlock(inst, blockStart);
23335
+ if (payload.oversized) continue;
23336
+ const alreadyCompleted = fec.isBlockCompleted(blockStart, pid, name);
23337
+ const recovered = fec.feedSourceSymbol(pid, ssId, payload.symbolData, name);
23338
+ if (recovered && !alreadyCompleted) this.#routeOverlayRecovered(inst, blockStart, recovered);
23339
+ }
23340
+ }
23341
+ /**
23342
+ * A source packet that carries a 0x8B01 overlay SS_ID is also a symbol of
23343
+ * every overlay installed for its source, at that SS_ID, with the bytes the
23344
+ * base protects: the packet minus its 4-byte SS_ID trailer, extension
23345
+ * included (7.1, 7.4.3).
23346
+ */
23347
+ #feedOverlaySource(packetId, catalogTrackName, packet, header, sequenceNumber, rapFlag, source) {
23348
+ if (this.#overlays.size === 0) return;
23349
+ const ssId = keyframeOverlaySsId(header);
23350
+ if (ssId === void 0) return;
23351
+ for (const inst of this.#overlaysForSource(packetId, catalogTrackName)) {
23352
+ this.#noteOverlaySsId(inst, ssId, sequenceNumber);
23353
+ const identity = MmtpContainerParser.sourcePacketIdentity(packet, header);
23354
+ if (identity !== null) {
23355
+ inst.offsets.delete(identity.mpuSequenceNumber);
23356
+ inst.offsets.set(identity.mpuSequenceNumber, ssId - sequenceNumber >>> 0);
23357
+ if (inst.offsets.size > OVERLAY_OFFSET_MPUS) inst.offsets.delete(inst.offsets.keys().next().value);
23358
+ }
23359
+ const { fec, repairPacketId: pid, streamName: name } = inst;
23360
+ const symbolData = packet.subarray(0, packet.length - 4);
23361
+ const oversized = !fec.isoSourceFits(pid, symbolData.length);
23362
+ const coords = fec.locateIsoSource(pid, name, ssId);
23363
+ if (coords === null) {
23364
+ fec.holdIsoSource(pid, name, ssId, {
23365
+ symbolData,
23366
+ source,
23367
+ oversized,
23368
+ evidence: sourceSymbolEvidence(packet, header, rapFlag, sequenceNumber)
23369
+ });
23370
+ continue;
23371
+ }
23372
+ if (source === "moq") this.#noteOverlayMoqBlock(inst, coords.sbn);
23373
+ if (oversized) continue;
23374
+ const alreadyCompleted = fec.isBlockCompleted(coords.sbn, pid, name);
23375
+ const recovered = fec.feedSourceSymbol(pid, ssId, symbolData, name);
23376
+ if (recovered && !alreadyCompleted) this.#routeOverlayRecovered(inst, coords.sbn, recovered);
23377
+ }
23378
+ }
23379
+ #noteOverlayMoqBlock(inst, blockStart) {
23380
+ inst.moqBlocks.add(blockStart);
23381
+ const newest = inst.last?.ssId;
23382
+ if (newest === void 0) return;
23383
+ for (const start of inst.moqBlocks) {
23384
+ if ((newest - start | 0) > OVERLAY_MOQ_HORIZON_BLOCKS * inst.k) inst.moqBlocks.delete(start);
23385
+ }
23386
+ }
23387
+ /**
23388
+ * An overlay SS_ID inconsistent with the source's packet_sequence_number
23389
+ * advance since the last one is an overlay restart (an FFmpeg muxer start,
23390
+ * a bridge swap that keeps psn continuous): it moved the other way, or
23391
+ * further than the psn advance plus K_overlay. Reordering keeps the two
23392
+ * consistent and is no restart.
23393
+ */
23394
+ #noteOverlaySsId(inst, ssId, psn) {
23395
+ const last = inst.last;
23396
+ if (last !== void 0) {
23397
+ const dSs = ssId - last.ssId | 0;
23398
+ const dPsn = psn - last.psn | 0;
23399
+ const consistent = dSs === 0 ? dPsn === 0 : Math.sign(dSs) === Math.sign(dPsn) && Math.abs(dSs) <= Math.abs(dPsn) + inst.k;
23400
+ if (!consistent) {
23401
+ this.#overlayStats.restarts++;
23402
+ this.#resetOverlay(inst);
23403
+ } else if (dPsn < 0) {
23404
+ return;
23405
+ }
23406
+ }
23407
+ inst.last = { ssId, psn };
23408
+ }
23409
+ /**
23410
+ * Route an overlay-recovered block's packets as source media of the
23411
+ * overlay's source (7.2: an overlay coordinate yields no base SS_ID). No
23412
+ * base-SS_ID derivation runs: no release-gate anchor, no parse ledger, no
23413
+ * base re-stamp, no block advance. Each packet's wire sequence is restored
23414
+ * from its keyframe's own offset; without one, a stream the base never
23415
+ * re-stamped keeps the header's sequence and any other drops the packet.
23416
+ */
23417
+ #routeOverlayRecovered(inst, blockStart, recovered) {
23418
+ const { fec, repairPacketId: pid, streamName: name } = inst;
23419
+ fec.markBlockCompleted(blockStart, pid, name);
23420
+ const sourcePacketId = inst.leg.sourcePacketId;
23421
+ const sourceName = inst.leg.sourceCatalogTrackName;
23422
+ if (this.#classifyPacketId(sourcePacketId) === null) return;
23423
+ const receiver = this.#provenanceFor(sourcePacketId, sourceName);
23424
+ if (receiver !== void 0 && inst.moqBlocks.has(blockStart)) {
23425
+ this.#overlayStats.protectedDropped++;
23426
+ return;
23427
+ }
23428
+ const blockProfile = fec.blockProfileForPacket(pid);
23429
+ const symbolSize = fec.symbolSizeForPacket(pid);
23430
+ if (blockProfile === void 0 || symbolSize === void 0 || !(symbolSize > 0)) return;
23431
+ const result = processFecBlock(recovered, { symbolSize, ownerPacketId: sourcePacketId, blockProfile });
23432
+ const streamKey = this.#mediaStreamKey(sourcePacketId, sourceName);
23433
+ const restamped = this.#restampedStreams.has(streamKey);
23434
+ const restored = /* @__PURE__ */ new Set();
23435
+ const symbols = result.symbols.flatMap((sym) => {
23436
+ const offset = inst.offsets.get(sym.fragment.mpuSequenceNumber);
23437
+ if (offset !== void 0) {
23438
+ const packetSequenceNumber = serial32Add(blockStart, sym.index) - offset >>> 0;
23439
+ restored.add(packetSequenceNumber);
23440
+ return [{ ...sym, packetSequenceNumber }];
23441
+ }
23442
+ if (!restamped) return [sym];
23443
+ this.#overlayStats.unsequencedDropped++;
23444
+ return [];
23445
+ });
23446
+ this.#overlayStats.recovered++;
23447
+ this.#routeProcessedFecSymbols(blockStart, { ...result, symbols }, sourcePacketId, sourceName, {
23448
+ deliveryProvenance: inst.moqBlocks.has(blockStart) ? "mixed" : "multicast"
23449
+ });
23450
+ this.#noteOverlayRecoveredRaps(sourcePacketId, sourceName, streamKey, symbols.filter((sym) => restored.has(sym.packetSequenceNumber)));
23451
+ }
23452
+ /** fec-multicast-00 §6.6: report each base block whose RAP MFU fragments
23453
+ * the overlay restored, when the keyframe's FT=0 and FT=1 are held too. A
23454
+ * packet whose wire sequence was not restored names no base block. */
23455
+ #noteOverlayRecoveredRaps(packetId, catalogTrackName, streamKey, symbols) {
23456
+ const ssIdSeqOffset = this.#ssIdSeqOffsetByStream.get(streamKey);
23457
+ if (ssIdSeqOffset === void 0 || this.#overlayRecoveredObservers.size === 0) return;
23458
+ const withMeta = (type) => new Set(symbols.filter((sym) => sym.fragmentType === type).map((sym) => sym.fragment.mpuSequenceNumber));
23459
+ const ft0 = withMeta(0);
23460
+ const ft1 = withMeta(1);
23461
+ const rapMfu = (fi) => new Set(symbols.filter((sym) => sym.fragmentType === 2 && sym.fragment.rapFlag && sym.fragment.fragmentationIndicator === fi).map((sym) => sym.fragment.mpuSequenceNumber));
23462
+ const single = rapMfu(0);
23463
+ const first = rapMfu(1);
23464
+ const last = rapMfu(3);
23465
+ const blocks = /* @__PURE__ */ new Set();
23466
+ for (const sym of symbols) {
23467
+ const mpu = sym.fragment.mpuSequenceNumber;
23468
+ if (sym.fragmentType !== 2 || !sym.fragment.rapFlag || !ft0.has(mpu) || !ft1.has(mpu)) continue;
23469
+ if (!single.has(mpu) && !(first.has(mpu) && last.has(mpu))) continue;
23470
+ const ssId = sym.packetSequenceNumber + ssIdSeqOffset >>> 0;
23471
+ const sbn = this.#fecManager?.locateIsoSource?.(packetId, catalogTrackName, ssId)?.sbn;
23472
+ if (sbn !== void 0) blocks.add(sbn);
23473
+ }
23474
+ for (const sbn of blocks) {
23475
+ for (const observer of this.#overlayRecoveredObservers) observer(packetId, catalogTrackName, sbn);
23476
+ }
23222
23477
  }
23223
23478
  /**
23224
23479
  * Register callback fired when a delta-track FEC block completes or fails.
@@ -23643,8 +23898,9 @@ var MmtpRouter = class {
23643
23898
  return;
23644
23899
  }
23645
23900
  const repairPacketId = header.packetId;
23646
- if (this.#isOverlayRepair(repairPacketId, repairTrackName)) {
23647
- this.#dropOverlayRepair(repairPacketId);
23901
+ const overlay = this.#overlayRepairTarget(repairPacketId, repairTrackName);
23902
+ if (overlay !== void 0) {
23903
+ this.#routeOverlayRepair(overlay, repairPacketId, packet, header, "moq");
23648
23904
  return;
23649
23905
  }
23650
23906
  const hintedOwner = ownerPacketIdHint != null && this.#classifyPacketId(ownerPacketIdHint) !== null ? ownerPacketIdHint : null;
@@ -23936,6 +24192,8 @@ var MmtpRouter = class {
23936
24192
  }
23937
24193
  }
23938
24194
  this.#parser.resetTrack(packetId, catalogTrackName);
24195
+ this.resetKeyframeOverlays(packetId, catalogTrackName);
24196
+ this.#restampedStreams.delete(this.#mediaStreamKey(packetId, catalogTrackName));
23939
24197
  const assistPrefix = assistKey(packetId, catalogTrackName, 0).slice(0, -1);
23940
24198
  for (const key of this.#assistBlocks.keys()) if (key.startsWith(assistPrefix)) this.#assistBlocks.delete(key);
23941
24199
  for (const key of this.#assistFailures.keys()) if (key.startsWith(assistPrefix)) this.#assistFailures.delete(key);
@@ -24029,6 +24287,10 @@ var MmtpRouter = class {
24029
24287
  for (const [name, leg] of [...this.#overlayRepairNames]) {
24030
24288
  if (leg.sourcePacketId === packetId) this.#overlayRepairNames.delete(name);
24031
24289
  }
24290
+ this.#overlays.delete(packetId);
24291
+ for (const [repairPacketId, inst] of [...this.#overlays]) {
24292
+ if (inst.leg.sourcePacketId === packetId) this.#overlays.delete(repairPacketId);
24293
+ }
24032
24294
  delete this.#pidCounts[packetId];
24033
24295
  delete this.#repairPidCounts[packetId];
24034
24296
  delete this.#moqRepairPidCounts[packetId];
@@ -24269,6 +24531,7 @@ var MmtpRouter = class {
24269
24531
  this.#repairOwnersByPacketId.clear();
24270
24532
  this.#overlayLegs.clear();
24271
24533
  this.#overlayRepairNames.clear();
24534
+ this.#overlays.clear();
24272
24535
  for (const { receiver } of this.#provenance.values()) receiver.release();
24273
24536
  this.#provenance.clear();
24274
24537
  this.#provenanceStreamFlow.clear();
@@ -24624,8 +24887,9 @@ var MmtpRouter = class {
24624
24887
  }
24625
24888
  }
24626
24889
  if (info.isRepair) {
24627
- if (this.#isOverlayRepair(info.packetId, catalogTrackNameForPacket(ingress, info.packetId))) {
24628
- this.#dropOverlayRepair(info.packetId);
24890
+ const overlay = this.#overlayRepairTarget(info.packetId, catalogTrackNameForPacket(ingress, info.packetId));
24891
+ if (overlay !== void 0) {
24892
+ this.#routeOverlayRepair(overlay, info.packetId, packet, parsed.header, source);
24629
24893
  return;
24630
24894
  }
24631
24895
  const ownerPacketId = this.#resolveRepairOwnerPacketId(info.packetId, ingress);
@@ -24834,6 +25098,17 @@ var MmtpRouter = class {
24834
25098
  });
24835
25099
  }
24836
25100
  }
25101
+ if (!overlapCopy && this.#classifyPacketId(info.packetId) !== null) {
25102
+ this.#feedOverlaySource(
25103
+ info.packetId,
25104
+ catalogTrackName,
25105
+ packet,
25106
+ parsed.header,
25107
+ info.sequenceNumber,
25108
+ info.rapFlag,
25109
+ source
25110
+ );
25111
+ }
24837
25112
  }
24838
25113
  }
24839
25114
  /**
@@ -25287,12 +25562,12 @@ var MmtpRouter = class {
25287
25562
  }
25288
25563
  return match;
25289
25564
  }
25290
- #routeProcessedFecSymbols(blockId, result, ownerPacketId, catalogTrackName) {
25565
+ #routeProcessedFecSymbols(blockId, result, ownerPacketId, catalogTrackName, overlay) {
25291
25566
  if (ownerPacketId == null) return;
25292
25567
  if (this.#classifyPacketId(ownerPacketId) === null) return;
25293
- const ssIdSeqOffset = this.#ssIdSeqOffsetByStream.get(
25294
- this.#mediaStreamKey(ownerPacketId, catalogTrackName)
25295
- );
25568
+ const fecSbnOf = (index) => overlay ? {} : { fecSbn: this.#fecAnchorForRecovered(blockId, index) };
25569
+ const streamKey = this.#mediaStreamKey(ownerPacketId, catalogTrackName);
25570
+ const ssIdSeqOffset = overlay ? void 0 : this.#ssIdSeqOffsetByStream.get(streamKey);
25296
25571
  if (ssIdSeqOffset !== void 0) {
25297
25572
  result = {
25298
25573
  ...result,
@@ -25300,12 +25575,13 @@ var MmtpRouter = class {
25300
25575
  const wire = this.#fecAnchorForRecovered(blockId, sym.index) - ssIdSeqOffset >>> 0;
25301
25576
  if (wire === sym.packetSequenceNumber) return sym;
25302
25577
  this.#restampedRecoveredSeqs++;
25578
+ this.#restampedStreams.add(streamKey);
25303
25579
  return { ...sym, packetSequenceNumber: wire };
25304
25580
  })
25305
25581
  };
25306
25582
  }
25307
- this.#stream(ownerPacketId, catalogTrackName).duplicates.advance(blockId);
25308
- const deliveryProvenance = this.#fecManager?.blockDeliveryProvenance?.(
25583
+ if (!overlay) this.#stream(ownerPacketId, catalogTrackName).duplicates.advance(blockId);
25584
+ const deliveryProvenance = overlay?.deliveryProvenance ?? this.#fecManager?.blockDeliveryProvenance?.(
25309
25585
  blockId,
25310
25586
  ownerPacketId,
25311
25587
  catalogTrackName
@@ -25383,7 +25659,7 @@ var MmtpRouter = class {
25383
25659
  rapFlag: sym.fragment.rapFlag,
25384
25660
  recovered: true,
25385
25661
  deliveryProvenance,
25386
- fecSbn: this.#fecAnchorForRecovered(blockId, sym.index),
25662
+ ...fecSbnOf(sym.index),
25387
25663
  ...catalogTrackName === void 0 ? {} : { catalogTrackName }
25388
25664
  });
25389
25665
  continue;
@@ -25495,7 +25771,7 @@ var MmtpRouter = class {
25495
25771
  rapFlag: assembled.rapFlag,
25496
25772
  recovered: true,
25497
25773
  ...assembled.deliveryProvenance === void 0 ? {} : { deliveryProvenance: assembled.deliveryProvenance },
25498
- fecSbn: this.#fecAnchorForRecovered(blockId, sym.index),
25774
+ ...fecSbnOf(sym.index),
25499
25775
  ...recoveredCatalogTrackName === void 0 ? {} : { catalogTrackName: recoveredCatalogTrackName }
25500
25776
  });
25501
25777
  continue;
@@ -25632,7 +25908,7 @@ var MmtpRouter = class {
25632
25908
  rapFlag: sym.fragment.rapFlag,
25633
25909
  recovered: true,
25634
25910
  deliveryProvenance,
25635
- fecSbn: this.#fecAnchorForRecovered(blockId, sym.index),
25911
+ ...fecSbnOf(sym.index),
25636
25912
  ...catalogTrackName === void 0 ? {} : { catalogTrackName }
25637
25913
  });
25638
25914
  } else {
@@ -25711,7 +25987,7 @@ var MmtpRouter = class {
25711
25987
  rapFlag: assembled.rapFlag,
25712
25988
  recovered: true,
25713
25989
  deliveryProvenance,
25714
- fecSbn: this.#fecAnchorForRecovered(blockId, sym.index),
25990
+ ...fecSbnOf(sym.index),
25715
25991
  ...assembled.catalogTrackName === void 0 ? {} : { catalogTrackName: assembled.catalogTrackName }
25716
25992
  });
25717
25993
  }
@@ -25746,7 +26022,7 @@ var MmtpRouter = class {
25746
26022
  ...sym.fragment.sampleNumber === void 0 ? {} : { sampleNumber: sym.fragment.sampleNumber },
25747
26023
  recovered: true,
25748
26024
  deliveryProvenance,
25749
- fecSbn: this.#fecAnchorForRecovered(blockId, sym.index),
26025
+ ...fecSbnOf(sym.index),
25750
26026
  ...catalogTrackName === void 0 ? {} : { catalogTrackName }
25751
26027
  });
25752
26028
  continue;
@@ -26925,7 +27201,7 @@ function newBlockPolicyStats(packetId, catalogTrackName, epoch) {
26925
27201
  repairsSkippedRangeNoAnchor: 0,
26926
27202
  repairsSkippedGroupCannotComplete: 0,
26927
27203
  repairsSkippedMootRap: 0,
26928
- repairStops: { preempted: 0, reprioritized: 0, expired: 0, resolved: 0, reset: 0, disposed: 0, moot: 0 },
27204
+ repairStops: { preempted: 0, reprioritized: 0, expired: 0, resolved: 0, reset: 0, disposed: 0, moot: 0, "overlay-recovered": 0 },
26929
27205
  lastRepairSkip: null,
26930
27206
  keyframeRepairFetchesSent: 0,
26931
27207
  rangeRepairFetchesSent: 0,
@@ -27272,6 +27548,10 @@ var MulticastManager = class {
27272
27548
  /** Live joinRepairEndpoints() releases → the repair owners they registered,
27273
27549
  * re-applied after configureMultiTrack() clears catalog-derived owners. */
27274
27550
  #repairReleases = /* @__PURE__ */ new Map();
27551
+ /** Each source's catalog keyframe overlay, from its `ok` binding. */
27552
+ #overlayBindings = /* @__PURE__ */ new Map();
27553
+ /** Installed overlay decoders (`setKeyframeOverlayDecoder`), by source. */
27554
+ #overlayInstalls = /* @__PURE__ */ new Map();
27275
27555
  #reportedFecDiagnosticsFailure = false;
27276
27556
  // ── Stream-global FEC timing reduction ──
27277
27557
  //
@@ -27512,6 +27792,63 @@ var MulticastManager = class {
27512
27792
  this.#configureTrackMapper(packetId, fecConfig);
27513
27793
  this.#router.setPacketIdType(packetId, trackType);
27514
27794
  }
27795
+ /**
27796
+ * Decode the keyframe overlay of `sourcePacketId` (draft-ramadan-mmt-fec-02
27797
+ * 7.4) with `decoder`, a decoder of the same kind `setFecDecoder` takes.
27798
+ * Opt-in: nothing else installs one, so a receiver that never calls this
27799
+ * holds no overlay state and drops overlay repair. K_overlay, T, scheme
27800
+ * and block profile come from the source's `ok` catalog binding, which
27801
+ * must declare an overlay (`configureMultiTrack` first). The overlay is
27802
+ * decoded on its own FEC state, apart from the base: no repair FETCH, no
27803
+ * repair lifecycle event and no base statistic for its blocks. A second
27804
+ * install on the same source replaces the first; the returned disposer
27805
+ * removes only the install it created. Call it on releasing the overlay
27806
+ * join.
27807
+ */
27808
+ setKeyframeOverlayDecoder(sourcePacketId, decoder, catalogTrackName) {
27809
+ const binding = this.#overlayBindings.get(sourcePacketId);
27810
+ if (!binding || catalogTrackName !== void 0 && binding.sourceCatalogTrackName !== catalogTrackName) {
27811
+ throw new Error(
27812
+ `[MulticastManager] packetId=${sourcePacketId} has no catalog keyframe overlay to decode`
27813
+ );
27814
+ }
27815
+ this.#overlayInstalls.get(sourcePacketId)?.dispose();
27816
+ let fec;
27817
+ let uninstall;
27818
+ const attach = () => {
27819
+ fec = new FECManager();
27820
+ fec.setFecDecoder(binding.repairPacketId, decoder, binding.k, {
27821
+ blockProfile: binding.blockProfile,
27822
+ k: binding.k,
27823
+ symbolSize: binding.symbolSize,
27824
+ trackKind: "video"
27825
+ }, binding.repairTrackName);
27826
+ uninstall = this.#router.installKeyframeOverlay(
27827
+ binding.repairPacketId,
27828
+ fec,
27829
+ binding.k,
27830
+ binding.repairTrackName
27831
+ );
27832
+ };
27833
+ const detach = () => {
27834
+ uninstall();
27835
+ fec.releasePacket(binding.repairPacketId);
27836
+ };
27837
+ attach();
27838
+ const install = {
27839
+ reattach: () => {
27840
+ detach();
27841
+ attach();
27842
+ },
27843
+ dispose: () => {
27844
+ if (this.#overlayInstalls.get(sourcePacketId) !== install) return;
27845
+ this.#overlayInstalls.delete(sourcePacketId);
27846
+ detach();
27847
+ }
27848
+ };
27849
+ this.#overlayInstalls.set(sourcePacketId, install);
27850
+ return install.dispose;
27851
+ }
27515
27852
  /**
27516
27853
  * Register a Worker-backed FEC decoder for a specific packetId (track).
27517
27854
  * Worker-backed tracks decode asynchronously — recovered frames arrive via
@@ -28509,6 +28846,7 @@ var MulticastManager = class {
28509
28846
  const catalogTracksByName = new Map(
28510
28847
  catalog.tracks.map((track) => [track.name, track])
28511
28848
  );
28849
+ const overlayBindings = /* @__PURE__ */ new Map();
28512
28850
  for (let i = 0; i < catalog.tracks.length; i++) {
28513
28851
  const track = catalog.tracks[i];
28514
28852
  const role = resolvedRoles[i];
@@ -28538,13 +28876,28 @@ var MulticastManager = class {
28538
28876
  }
28539
28877
  }
28540
28878
  const overlayName = binding.overlay?.repairTrackName;
28879
+ const overlayPacketId = overlayName === void 0 ? void 0 : catalogTracksByName.get(overlayName)?.packetId;
28541
28880
  if (overlayName !== void 0 && ownedRepairNames.has(overlayName)) {
28542
- this.#router.setKeyframeOverlayLeg(catalogTracksByName.get(overlayName)?.packetId, {
28881
+ this.#router.setKeyframeOverlayLeg(overlayPacketId, {
28543
28882
  sourcePacketId: track.packetId,
28544
28883
  sourceCatalogTrackName: track.name,
28545
28884
  repairTrackName: overlayName
28546
28885
  });
28547
28886
  }
28887
+ if (overlayName !== void 0 && overlayPacketId !== void 0 && ownedRepairNames.has(overlayName)) {
28888
+ const geometry2 = binding.overlay.geometry;
28889
+ overlayBindings.set(track.packetId, {
28890
+ repairPacketId: overlayPacketId,
28891
+ repairTrackName: overlayName,
28892
+ sourceCatalogTrackName: track.name,
28893
+ k: binding.overlay.sourceSymbols,
28894
+ symbolSize: fecCfg.symbolSize,
28895
+ blockProfile: parseFecBlockProfile(
28896
+ geometry2.blockProfile,
28897
+ `tracks[${JSON.stringify(track.name)}].fec keyframe overlay blockProfile`
28898
+ )
28899
+ });
28900
+ }
28548
28901
  }
28549
28902
  const wasmDecoder = fecDecoders.get(i);
28550
28903
  if (track.packetId !== void 0 && wasmDecoder !== void 0) {
@@ -28578,6 +28931,16 @@ var MulticastManager = class {
28578
28931
  }
28579
28932
  }
28580
28933
  }
28934
+ for (const [sourcePacketId, install] of [...this.#overlayInstalls]) {
28935
+ const before = this.#overlayBindings.get(sourcePacketId);
28936
+ const after = overlayBindings.get(sourcePacketId);
28937
+ const same = before !== void 0 && after !== void 0 && Object.keys(after).every((key) => after[key] === before[key]);
28938
+ if (!same) install.dispose();
28939
+ else if (this.#router.hasKeyframeOverlay(after.repairPacketId)) this.#router.resetKeyframeOverlays(sourcePacketId);
28940
+ else install.reattach();
28941
+ }
28942
+ this.#overlayBindings.clear();
28943
+ for (const [sourcePacketId, binding] of overlayBindings) this.#overlayBindings.set(sourcePacketId, binding);
28581
28944
  }
28582
28945
  /**
28583
28946
  * Why `configureMultiTrack` consumes the named catalog track without FEC
@@ -28749,6 +29112,10 @@ var MulticastManager = class {
28749
29112
  addRapCompleteObserver(observer) {
28750
29113
  return this.#router.addFecRapObserver(observer);
28751
29114
  }
29115
+ /** Observe each base block whose RAP the keyframe overlay recovered (fec-multicast-00 §6.6). */
29116
+ addKeyframeOverlayRecoveredObserver(observer) {
29117
+ return this.#router.addKeyframeOverlayRecoveredObserver(observer);
29118
+ }
28752
29119
  /** Catalog/reset epoch of a packet's streams; gap decisions carry it. */
28753
29120
  epochFor(packetId) {
28754
29121
  return this.#fec.epochFor(packetId);
@@ -31840,12 +32207,27 @@ function wireRepairFetch(mc, opts) {
31840
32207
  dispatch();
31841
32208
  });
31842
32209
  });
32210
+ const removeOverlayObserver = mc.addKeyframeOverlayRecoveredObserver?.((packetId, catalogTrackName, sbn) => {
32211
+ queueMicrotask(() => {
32212
+ if (disposed) return;
32213
+ for (const entry of [...entries.values()]) {
32214
+ if (entry.range || entry.priority !== 0 || entry.packetId !== packetId || entry.sbn !== sbn) continue;
32215
+ if (catalogTrackName !== void 0 && entry.catalogTrackName !== catalogTrackName) continue;
32216
+ stop(entry, "overlay-recovered");
32217
+ retire(entry);
32218
+ releaseHold(entry);
32219
+ clearEntry(entry);
32220
+ }
32221
+ dispatch();
32222
+ });
32223
+ });
31843
32224
  return () => {
31844
32225
  disposed = true;
31845
32226
  mc.setUnicastRepair?.(false);
31846
32227
  removeResetObserver();
31847
32228
  removeLifecycleObserver();
31848
32229
  removeRapObserver?.();
32230
+ removeOverlayObserver?.();
31849
32231
  for (const entry of [...entries.values()]) {
31850
32232
  clearEntry(entry);
31851
32233
  if (entry.running) releaseHold(entry);
@@ -31879,6 +32261,7 @@ export {
31879
32261
  HoldLastTimeline,
31880
32262
  JOIN_DEFER_WARN_MS,
31881
32263
  KEYFRAME_LOST_TIMEOUT_SLACK,
32264
+ KEYFRAME_OVERLAY_EXTENSION_TYPE,
31882
32265
  LOCHeaderExtensionId,
31883
32266
  MAX_ENCODING_SYMBOL_ID,
31884
32267
  MAX_RAPTORQ_SOURCE_SYMBOLS,
@@ -31988,6 +32371,7 @@ export {
31988
32371
  isTrackTimingConfig,
31989
32372
  joinedRepairSymbolCount,
31990
32373
  keyframeIntervalMediaTicks,
32374
+ keyframeOverlaySsId,
31991
32375
  mergeOverrideIntoCmsfTracks,
31992
32376
  mergeOverrideIntoHangRenditions,
31993
32377
  mfuReassemblyTimeoutMs,