@blockcast/mmt-container 2.2.0-main.da2e7cd1dd5d → 2.2.0-main.e75bbd7576a6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blockcast/mmt-container",
-  "version": "2.2.0-main.da2e7cd1dd5d",
+  "version": "2.2.0-main.e75bbd7576a6",
   "description": "MMTP/LOC container parsing for MMT over MoQ and SSM",
   "type": "module",
   "main": "dist/index.js",
@@ -169,10 +169,10 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@blockcast/fec-worker": "2.2.0-main.da2e7cd1dd5d",
-    "@blockcast/mmt-base": "2.2.0-main.da2e7cd1dd5d",
-    "@blockcast/mmt-fec": "2.2.0-main.da2e7cd1dd5d",
-    "@blockcast/mmt-manifest-verify": "2.2.0-main.da2e7cd1dd5d",
+    "@blockcast/fec-worker": "2.2.0-main.e75bbd7576a6",
+    "@blockcast/mmt-base": "2.2.0-main.e75bbd7576a6",
+    "@blockcast/mmt-fec": "2.2.0-main.e75bbd7576a6",
+    "@blockcast/mmt-manifest-verify": "2.2.0-main.e75bbd7576a6",
     "@noble/curves": "^1.9.7",
     "@noble/hashes": "^1.8.0",
     "ajv": "^8.17.1",

package/src/fec-manager.ts

@@ -22,6 +22,7 @@ import {
   isoBlockContains,
   isoBlocksBehindLowerBound,
   parseFecBlockProfile,
+  serial32Add,
   serial32Distance,
   serial32Precedes,
   ssbg1FitsSymbol,
@@ -169,6 +170,17 @@ export interface FecPacketStats {
 
 export type FecSymbolSource = 'multicast' | 'moq'
 
+/**
+ * What feedRebuiltSourceSymbol did with a rebuilt source: whether its block
+ * took it, and the block the synchronous decoder recovered with it, if any.
+ */
+export interface RebuiltSourceFeed {
+  readonly taken: boolean
+  readonly recovered: Uint8Array | null
+}
+
+const NOT_TAKEN: RebuiltSourceFeed = Object.freeze({ taken: false, recovered: null })
+
 /**
  * One iso-ssbg1-v1 first-arrival source symbol MmtpRouter holds until a repair
  * symbol states its block: the exact protected packet (no SS_ID, unpadded),
@@ -514,6 +526,10 @@ export class FECManager {
   // Source symbol count per track-scoped block — marks complete when K symbols arrive.
   #blockSourceCounts = new Map<string, number>()
   #blockSourceEsis = new Map<string, Set<number>>()
+  // Source ESIs per block that another FEC instance rebuilt and fed in
+  // (feedRebuiltSourceSymbol). Kept apart from #blockSourceEsis: they are
+  // not network arrivals and never make a block clean.
+  #blockRebuiltEsis = new Map<string, Set<number>>()
   // Authored SSB_length per block (ISO/IEC 23008-1 §C.5.3), learned from the
   // first repair symbol. The FFmpeg moq_mmt publisher closes a block every D
   // media units, usually before it holds K symbols; under iso-ssbg1-v1
@@ -2540,6 +2556,7 @@ export class FECManager {
     }
     resetMap(this.#blockSourceCounts)
     resetMap(this.#blockSourceEsis)
+    resetMap(this.#blockRebuiltEsis)
     resetMap(this.#blockAuthoredLengths)
     resetMap(this.#blockRepairRsIds)
     resetMap(this.#blockRsbLengths)
@@ -2672,6 +2689,7 @@ export class FECManager {
     dropMap(this.#pendingWorkerCleanupClients)
     dropMap(this.#blockSourceCounts)
     dropMap(this.#blockSourceEsis)
+    dropMap(this.#blockRebuiltEsis)
     dropMap(this.#blockAuthoredLengths)
     dropMap(this.#blockRepairRsIds)
     dropMap(this.#blockRsbLengths)
@@ -2891,6 +2909,10 @@ export class FECManager {
       }
     }
 
+    if (isSourceSymbol && source === 'multicast') {
+      this.#noteMulticastSource(this.#isoLocatorFor(packetId, catalogTrackName), (sbn + esi) >>> 0, packetId, catalogTrackName)
+    }
+
     return true
   }
 
@@ -3263,6 +3285,7 @@ export class FECManager {
     const locator = this.#growingIsoLocatorFor(packetId, catalogTrackName)
     const evictedBefore = locator.heldEvicted
     const held = locator.hold(ssId, source)
+    if (held && source.source === 'multicast') this.#noteMulticastSource(locator, ssId, packetId, catalogTrackName)
     const evicted = locator.heldEvicted - evictedBefore
     if (evicted > 0) {
       const before = this.#isoHeldEvictedCount
@@ -4062,7 +4085,22 @@ export class FECManager {
       this.#isoSourceOversizeCount++
       return null
     }
-    const sbn = located.block.start
+    return this.#feedDecoderSource(packetId, ssId, symbolData, catalogTrackName, located.block.start)
+  }
+
+  /**
+   * Hand one placed source symbol to the stream's decoder: its Worker, which
+   * answers through onFrame (null here), or its synchronous decoder, whose
+   * recovered block is returned. `sbn` is the SS_Start of the block a repair
+   * stated for `ssId`.
+   */
+  #feedDecoderSource(
+    packetId: number,
+    ssId: number,
+    symbolData: Uint8Array,
+    catalogTrackName: string | undefined,
+    sbn: number,
+  ): Uint8Array | null {
     const blockKey = this.#blockKey(sbn, packetId, catalogTrackName)
     const syncBlockOwner = this.#syncDecoderBlockOwners.get(blockKey)
 
@@ -4107,6 +4145,97 @@ export class FECManager {
     return recovered
   }
 
+  /**
+   * Feed a source symbol of this stream that another FEC instance over the
+   * same packets rebuilt: a keyframe overlay recovery whose base SS_ID the
+   * caller determined (draft-ramadan-moq-mmt-02 7.1, 7.4.4; joint decoding,
+   * BLO-52085). It joins its block's decoder as a received source would, so
+   * it reduces the erasures the block still has to solve, but it is not a
+   * network arrival: no transport accounting, no classification evidence,
+   * no deadline refresh, and it never makes a block clean.
+   *
+   * Only a block a repair stated takes one (a repair-less span has no
+   * decoder block). A block that is terminal, or already holds that source,
+   * does not. The symbol is the exact protected packet, unpadded, as
+   * feedSourceSymbol takes it.
+   *
+   * `recovered` is the block the synchronous decoder completed with it; the
+   * caller routes it and completes the block, as for any recovery. When
+   * every source of the block is then present, received or rebuilt, and no
+   * decoder returned it (a Worker answers asynchronously, and reports such a
+   * block as clean on its own side), the block is completed here as
+   * recovered, with nothing left to route.
+   */
+  feedRebuiltSourceSymbol(
+    packetId: number,
+    ssId: number,
+    symbolData: Uint8Array,
+    catalogTrackName?: string,
+  ): RebuiltSourceFeed {
+    if (!this.#hasBlockProfile(packetId)) return NOT_TAKEN
+    const located = this.#isoLocatorFor(packetId, catalogTrackName).locate(ssId)
+    if (located === null || located.block.span) return NOT_TAKEN
+    if (!ssbg1FitsSymbol(symbolData.byteLength, this.#trackConfig(packetId).symbolSize)) return NOT_TAKEN
+    const sbn = located.block.start
+    const key = this.#blockKey(sbn, packetId, catalogTrackName)
+    if (this.#completedBlocks.has(key) || this.#blockSourceEsis.get(key)?.has(located.esi)) return NOT_TAKEN
+    let rebuilt = this.#blockRebuiltEsis.get(key)
+    if (rebuilt?.has(located.esi)) return NOT_TAKEN
+    if (rebuilt === undefined) {
+      rebuilt = new Set()
+      this.#blockRebuiltEsis.set(key, rebuilt)
+    }
+    const config = this.#trackConfigs.get(packetId)
+    const wasShort = config !== undefined &&
+      this.#lateSourceWaitMs(key, sbn, packetId, catalogTrackName, config) !== undefined
+    rebuilt.add(located.esi)
+    const recovered = this.#feedDecoderSource(packetId, ssId, symbolData, catalogTrackName, sbn)
+    if (recovered === null && !this.#completeWhenSourcesPresent(key, sbn, located.block.length, packetId, catalogTrackName)) {
+      // The late-source cut assumed only a late source could complete this
+      // block; with this source its group can, so it gets a full multicast
+      // wait again, counted from now.
+      // ponytail: from now, not from its sources, so it can close up to one
+      // multicast wait after its uncut deadline; at most once per block, since
+      // a rebuilt source only adds to what the block holds and the cut cannot
+      // apply to it again. Keep the uncut deadline and re-arm to it if a lab
+      // run shows that wait.
+      if (wasShort && this.#activeBlocks.has(key) &&
+        this.#lateSourceWaitMs(key, sbn, packetId, catalogTrackName, config!) === undefined) {
+        this.#armBlockTimeout(sbn, packetId, catalogTrackName, this.#multicastWaitMs(config!))
+      }
+    }
+    return { taken: true, recovered }
+  }
+
+  /**
+   * A block that holds every one of its `length` sources, received or
+   * rebuilt by another instance, with at least one rebuilt, is recovered:
+   * every packet of it was delivered, by its own arrival or by the instance
+   * that rebuilt it, so nothing is routed. Returns whether it completed it.
+   */
+  #completeWhenSourcesPresent(
+    key: string,
+    sbn: number,
+    length: number,
+    packetId: number,
+    catalogTrackName: string | undefined,
+  ): boolean {
+    const rebuilt = this.#blockRebuiltEsis.get(key)
+    if (rebuilt === undefined || this.#completedBlocks.has(key)) return false
+    let present = rebuilt.size
+    for (const esi of this.#blockSourceEsis.get(key) ?? []) if (!rebuilt.has(esi)) present++
+    if (present < length) return false
+    this.#traceLifecycle('recovered', sbn, packetId, catalogTrackName)
+    this.countRecovery(packetId, sbn, catalogTrackName)
+    this.cancelBlockTimeout(sbn, packetId, catalogTrackName)
+    if (catalogTrackName === undefined) {
+      this.onBlockComplete?.(sbn, packetId)
+    } else {
+      this.onBlockComplete?.(sbn, packetId, catalogTrackName)
+    }
+    return true
+  }
+
   /**
    * fec-01 4.5: a reed-solomon repair packet whose SSB_length + RSB_length
    * exceeds 255, or whose RS_ID is not below RSB_length, is discarded with the
@@ -4364,9 +4493,100 @@ export class FECManager {
       this.#completeCleanBlock(blockKey, sbn, packetId, catalogTrackName)
       return null
     }
+    // Its K' is known now: a block this repair shows short of it waits less.
+    if (recovered === null) this.#shortenUnrecoverableWait(blockKey, sbn, packetId, catalogTrackName)
     return recovered
   }
 
+  /**
+   * A first-arrival multicast source, held or placed. A datagram flow keeps
+   * its sources in send order, so one that moves the stream's newest source
+   * position past a block leaves the sources that block still misses
+   * reordered behind it at best: it shortens the wait of every block it
+   * passed that only a late source can complete. MoQ is left out: its streams
+   * can overtake one another, so a MoQ source shows nothing about the sources
+   * sent before it.
+   */
+  #noteMulticastSource(
+    locator: IsoBlockLocator<IsoHeldSource>,
+    ssId: number,
+    packetId: number,
+    catalogTrackName: string | undefined,
+  ): void {
+    const previous = locator.newestSource
+    if (!locator.noteSource(ssId) || previous === undefined) return
+    // The blocks whose last SS_ID lies in [previous, ssId): this source
+    // passed them and the previous newest one had not.
+    for (const block of locator.blocksBetween((previous - 1) >>> 0, ssId)) {
+      if (block.span || !serial32Precedes(serial32Add(block.start, block.length - 1), ssId)) continue
+      this.#shortenUnrecoverableWait(
+        this.#blockKey(block.start, packetId, catalogTrackName),
+        block.start,
+        packetId,
+        catalogTrackName,
+      )
+    }
+  }
+
+  /**
+   * The wait of a block that only a late source can complete (BLO-52085): a
+   * repair stated it, its received sources plus every symbol its repair group
+   * carries (RSB_length) are short of K' (the repair scheduler's
+   * group-cannot-complete), and a later source of the stream has arrived, so
+   * a source it misses is lost or reordered behind that one. The span, which
+   * covers repair symbols paced after its sources, buys it nothing: it waits
+   * the late-symbol allowance alone, the multicast wait less the span (the
+   * catalog tolerance or the measured delivery gap). Undefined for any other
+   * block.
+   */
+  #lateSourceWaitMs(
+    key: string,
+    sbn: number,
+    packetId: number,
+    catalogTrackName: string | undefined,
+    config: ResolvedFECTrackConfig,
+  ): number | undefined {
+    const authoredLength = this.#blockAuthoredLengths.get(key)
+    const rsbLength = this.#blockRsbLengths.get(key)
+    if (authoredLength === undefined || rsbLength === undefined) return undefined
+    // A source another instance rebuilt (feedRebuiltSourceSymbol) is one the
+    // decoder holds: the group need only cover what neither delivered.
+    let present = this.#blockSourceCounts.get(key) ?? 0
+    const received = this.#blockSourceEsis.get(key)
+    for (const esi of this.#blockRebuiltEsis.get(key) ?? []) if (!received?.has(esi)) present++
+    if (present + rsbLength >= authoredLength) return undefined
+    const newestSource = this.#isoLocators.get(this.#streamKey(packetId, catalogTrackName))?.newestSource
+    if (newestSource === undefined || !serial32Precedes(serial32Add(sbn, authoredLength - 1), newestSource)) {
+      return undefined
+    }
+    return this.#multicastWaitMs(config) - config.interleaveDepthMs
+  }
+
+  /**
+   * Bring an open block's wait in to its late-source wait, when it has one.
+   * Never later than it is armed: only a source can complete such a block,
+   * so a repair of its group (paced across the span) must not keep it open.
+   */
+  #shortenUnrecoverableWait(
+    key: string,
+    sbn: number,
+    packetId: number,
+    catalogTrackName: string | undefined,
+  ): void {
+    if (!this.#activeBlocks.has(key)) return
+    const config = this.#trackConfigs.get(packetId)
+    if (config === undefined) return
+    const waitMs = this.#lateSourceWaitMs(key, sbn, packetId, catalogTrackName, config)
+    if (waitMs === undefined) return
+    const armedAtMs = this.#blockWaitDeadlinesMs.get(key)
+    this.#armBlockTimeout(
+      sbn,
+      packetId,
+      catalogTrackName,
+      armedAtMs === undefined ? waitMs : Math.min(waitMs, armedAtMs - this.#receiptNow()),
+    )
+  }
+
   /**
    * Record a block's authored SSB_length from a repair symbol. Returns false,
    * leaving the block unchanged, when the symbol contradicts the block: a
@@ -4582,6 +4802,20 @@ export class FECManager {
       this.#completeCleanBlock(key, sbn, packetId, catalogTrackName)
       return
     }
+    // A late arrival can be the last source a block lacked besides those
+    // another instance rebuilt (feedRebuiltSourceSymbol).
+    if (
+      this.#blockRebuiltEsis.has(key) &&
+      this.#completeWhenSourcesPresent(
+        key,
+        sbn,
+        this.#isoLocatorFor(packetId, catalogTrackName).blockAt(sbn)?.length ?? authoredLength,
+        packetId,
+        catalogTrackName,
+      )
+    ) {
+      return
+    }
 
     this.noteBlockActivity(sbn, packetId, catalogTrackName, true)
 
@@ -4601,6 +4835,7 @@ export class FECManager {
     this.cancelBlockTimeout(sbn, packetId, catalogTrackName)
     this.#blockSourceCounts.delete(key)
     this.#blockSourceEsis.delete(key)
+    this.#blockRebuiltEsis.delete(key)
     this.#blockAuthoredLengths.delete(key)
     this.#blockRepairRsIds.delete(key)
     this.#blockRsbLengths.delete(key)
@@ -4714,7 +4949,18 @@ export class FECManager {
       )
     }
 
-    this.#armBlockTimeout(sbn, packetId, catalogTrackName, timeoutMs)
+    // A block only a late source can complete waits the late-symbol
+    // allowance from its own sources' activity; nothing else moves it later.
+    if (!sourceProgress && this.#lateSourceWaitMs(key, sbn, packetId, catalogTrackName, trackConfig) !== undefined) {
+      this.#shortenUnrecoverableWait(key, sbn, packetId, catalogTrackName)
+      return
+    }
+    this.#armBlockTimeout(
+      sbn,
+      packetId,
+      catalogTrackName,
+      this.#lateSourceWaitMs(key, sbn, packetId, catalogTrackName, trackConfig) ?? timeoutMs,
+    )
   }
 
   #failBlock(
@@ -4732,6 +4978,7 @@ export class FECManager {
     }
     this.#blockSourceCounts.delete(key)
     this.#blockSourceEsis.delete(key)
+    this.#blockRebuiltEsis.delete(key)
     this.#blockAuthoredLengths.delete(key)
     this.#blockRepairRsIds.delete(key)
     this.#blockRsbLengths.delete(key)
@@ -4771,6 +5018,7 @@ export class FECManager {
     this.#retireBlockClass(key, block.sbn, block.packetId, block.catalogTrackName)
     this.#blockSourceCounts.delete(key)
     this.#blockSourceEsis.delete(key)
+    this.#blockRebuiltEsis.delete(key)
     this.#blockAuthoredLengths.delete(key)
     this.#blockRepairRsIds.delete(key)
     this.#blockRsbLengths.delete(key)
@@ -4879,6 +5127,7 @@ export class FECManager {
     this.#blockKeysBySbn.clear()
     this.#blockSourceCounts.clear()
     this.#blockSourceEsis.clear()
+    this.#blockRebuiltEsis.clear()
     this.#blockAuthoredLengths.clear()
     this.#blockRepairRsIds.clear()
     this.#blockRsbLengths.clear()

package/src/index.ts

@@ -299,6 +299,7 @@ export {
   type MmtpFeedOutcomeKey,
   type TrackInfo,
   type MmtpReorderStats,
+  type MmtpRecoveredHeadTimingStats,
   type MmtpReorderFrameDiagnostics,
   type MmtpReorderStreamDiagnostics,
   type FrameMeta as ParserFrameMeta,

package/src/iso-block-locator.ts

@@ -85,6 +85,7 @@ export class IsoBlockLocator<T> {
   #retentionBlocks: number
   #heldEvicted = 0
   #newest: number | undefined
+  #newestSource: number | undefined
   /** Pending holes (see `deferIncompleteGaps`): unstated, sources still held. */
   readonly #holes: IsoBlockRange[] = []
   /**
@@ -152,6 +153,23 @@ export class IsoBlockLocator<T> {
     if (this.#newest === undefined || serial32Precedes(this.#newest, position)) this.#newest = position
   }
 
+  /**
+   * The newest source SS_ID noted with `noteSource` (RFC 1982 order). Unlike
+   * `newest`, a repair never moves it: a repair can run ahead of its sources,
+   * a source cannot run ahead of the sources sent before it except by
+   * reordering.
+   */
+  get newestSource(): number | undefined {
+    return this.#newestSource
+  }
+
+  /** Note a received source's SS_ID; true when it is the newest one yet. */
+  noteSource(ssId: number): boolean {
+    if (this.#newestSource !== undefined && !serial32Precedes(this.#newestSource, ssId)) return false
+    this.#newestSource = ssId
+    return true
+  }
+
   /** Held sources evicted by `heldCapacity` (never by the horizon itself). */
   get heldEvicted(): number {
     return this.#heldEvicted
@@ -412,6 +430,7 @@ export class IsoBlockLocator<T> {
     this.#held.clear()
     this.#coverageEnd = undefined
     this.#newest = undefined
+    this.#newestSource = undefined
   }
 
   #claim(block: IsoBlockRange): IsoPlacedSource<T>[] {

package/src/iso-bmff-timing.ts

@@ -581,6 +581,14 @@ type PendingMovieFragment = Array<IsoBmffSampleTiming | null>
 export class IsoBmffTimingResolver {
   #track: IsoBmffTrackTiming | null = null
   #fragments = new Map<string, PendingMovieFragment>()
+  /** First sample of each pending fragment, kept in `#delivered` with its sample count. */
+  #firstSamples = new Map<string, IsoBmffSampleTiming>()
+  /**
+   * First sample and sample count of the newest fragments whose every slot was
+   * cleared. Abandonment counts: `releaseSample` clears a slot too, which
+   * matches the combiner, since it retires an abandoned sample as well.
+   */
+  #delivered = new Map<string, { first: IsoBmffSampleTiming, sampleCount: number }>()
   #pendingSamples = 0
   #evictedSamples = 0
   #lastMovieFragmentRejection: IsoBmffMovieFragmentRejection | null = null
@@ -591,6 +599,11 @@ export class IsoBmffTimingResolver {
     }
   }
 
+  /** True once an FT=0 has bound the track that FT=1 timing is read against. */
+  get initialized(): boolean {
+    return this.#track !== null
+  }
+
   get pendingSampleCount(): number {
     return this.#pendingSamples
   }
@@ -618,10 +631,18 @@ export class IsoBmffTimingResolver {
     return true
   }
 
+  /**
+   * `recovered` marks an FEC-recovered copy. A recovered block hands back
+   * every FT=1 it holds, the received ones included, so a recovered copy of a
+   * fragment whose samples are all done is a duplicate: admitting it again
+   * would charge stale timing and could displace the live MPU's. A source
+   * copy is still admitted again (a rendition switch re-arms timing that way).
+   */
   addMovieFragment(
     mpuSequenceNumber: number,
     data: Uint8Array,
     additionalSampleLimit = this.maxPendingSamples,
+    recovered = false,
   ): boolean {
     this.#lastMovieFragmentRejection = null
     if (!Number.isInteger(additionalSampleLimit) || additionalSampleLimit < 0) {
@@ -648,6 +669,9 @@ export class IsoBmffTimingResolver {
         (sample, index) => sample !== null && sameSample(sample, parsed.samples[index]!),
       )
     }
+    const delivered = recovered ? this.#delivered.get(key) : undefined
+    if (delivered && delivered.sampleCount === parsed.samples.length &&
+        sameSample(delivered.first, parsed.samples[0]!)) return true
     // Sliding window, not a one-way ratchet. `consumeSample` and
     // `releaseSample` between them cover every sample some component observed
     // -- but a sample whose data units never arrive at all is observed by
@@ -683,6 +707,7 @@ export class IsoBmffTimingResolver {
       return false
     }
     this.#fragments.set(key, [...parsed.samples])
+    this.#firstSamples.set(key, parsed.samples[0]!)
     this.#pendingSamples += parsed.samples.length
     return true
   }
@@ -758,6 +783,7 @@ export class IsoBmffTimingResolver {
     let live = 0
     for (const sample of samples) if (sample !== null) live++
     this.#fragments.delete(oldest)
+    this.#firstSamples.delete(oldest)
     this.#pendingSamples -= live
     this.#evictedSamples += live
     return live
@@ -779,13 +805,26 @@ export class IsoBmffTimingResolver {
     if (!samples || !samples[index]) return false
     samples[index] = null
     this.#pendingSamples--
-    if (samples.every(value => value === null)) this.#fragments.delete(key)
+    if (samples.every(value => value === null)) {
+      this.#fragments.delete(key)
+      const first = this.#firstSamples.get(key)!
+      this.#firstSamples.delete(key)
+      this.#delivered.delete(key)
+      this.#delivered.set(key, { first, sampleCount: samples.length })
+      // ponytail: the dedupe memory is as wide as the timing budget, in fragments;
+      // a recovered copy older than that is admitted again, as before.
+      if (this.#delivered.size > this.maxPendingSamples) {
+        this.#delivered.delete(this.#delivered.keys().next().value!)
+      }
+    }
     return true
   }
 
   reset(): void {
     this.#track = null
     this.#fragments.clear()
+    this.#firstSamples.clear()
+    this.#delivered.clear()
     this.#pendingSamples = 0
   }
 }