@blockcast/mmt-render 0.1.0 → 0.3.0-main.36c5f6abe867

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blockcast/mmt-render",
-  "version": "0.1.0",
+  "version": "0.3.0-main.36c5f6abe867",
   "description": "Shared MMT render pipeline (FEC-aware pacing, interleave timing, audio worklet) for MoQ players",
   "type": "module",
   "main": "dist/index.js",
@@ -73,8 +73,8 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@blockcast/mmt-container": "^0.1.0",
-    "@blockcast/mmt-fec": "^0.1.0"
+    "@blockcast/mmt-container": "0.3.0-main.36c5f6abe867",
+    "@blockcast/mmt-fec": "0.3.0-main.36c5f6abe867"
   },
   "devDependencies": {
     "@types/audioworklet": "^0.0.77",

package/src/pacing/frame-pacer.ts

@@ -83,13 +83,40 @@ export class FrameCountPacer {
    *   - pacing is disabled (NullBlockMapper → threshold=0)
    *   - the anchor is not yet set
    *   - still in warmup
+   *   - the caller reports a standing backlog (see `observedDelayMs`)
    *   - decoder is not ahead of wall clock by more than threshold
    * Otherwise returns aheadMs - thresholdMs/2 (leaves half the threshold as headroom).
+   *
+   * `observedDelayMs` is how far this frame is behind the producer's own clock,
+   * measured by the caller against a producer-supplied sending instant (for
+   * MMTP, the header send-wall timestamp). It is optional because the anchored
+   * rate below is blind to it: `#anchorWallMs` is the wall time of the FIRST
+   * frame read, so `aheadMs` measures consumption against the join instant and
+   * not against the producer. Once `aheadMs` reaches the threshold the loop
+   * consumes at exactly the source rate, and recovering latency present at join
+   * requires consuming FASTER than the source rate. So without this argument a
+   * consumer that joined a live stream mid-block keeps that join latency for the
+   * life of the subscription.
+   *
+   * A caller that can measure the real distance from the producer passes it and
+   * gets a drain: while the backlog exceeds the threshold there is nothing to
+   * pace against, so return 0 and let the transport set the rate. At the live
+   * edge the anchored-rate behavior below applies unchanged.
+   *
+   * Callers with no producer clock omit it and keep the pure ATSC3-style
+   * anchored pacing (see the class doc), where a first-frame anchor is correct
+   * because a broadcast push has no live edge to catch up to.
    */
-  computeSleepMs(): number {
+  computeSleepMs(observedDelayMs?: number): number {
     if (this.thresholdMs <= 0) return 0
     if (!this.#anchored) return 0
     if (this.#frameCount <= this.warmupFrames) return 0
+    // Only a finite measurement can license the drain. NaN/Infinity mean the
+    // caller could not measure the distance, which is not the same claim as
+    // "the consumer is at the edge", so fall through to anchored pacing.
+    if (observedDelayMs !== undefined && Number.isFinite(observedDelayMs) && observedDelayMs > this.thresholdMs) {
+      return 0
+    }
 
     const mediaMs = this.#frameCount * this.frameDurationMs
     const wallMs = now() - this.#anchorWallMs

package/src/pacing/interleave-timing.ts

@@ -18,12 +18,22 @@
  *
  * Consumers: CMAF segment assembler (block boundary → segment cut points),
  * debug overlays, cross-path FEC combining, sync diagnostics.
+ *
+ * This is the `k-padded-v1` K-stride pacing model and nothing more: it is
+ * presentation-time arithmetic for a stream whose blocks are K symbols and D
+ * media groups long, NOT an FEC block locator. FecBlockMapper no longer maps
+ * media groups to blocks (BLO-35597), so the stride math lives here, and a
+ * stream under any other `fec.blockProfile` (an `iso-ssbg1-v1` block's length
+ * is stated per block on the wire, so it has no stride) is refused.
  */
 
 import type { FecBlockMapper } from '@blockcast/mmt-fec'
 
+/** 2^32: SS_ID is a 32-bit serial number (ISO/IEC 23008-1 C.5.2). */
+const SS_ID_SPAN = 0x1_0000_0000
+
 export interface InterleaveTimingOpts {
-  /** Track's FEC mapper (provides K, D, symbolsPerGroup). */
+  /** Track's FEC mapper (provides K and D); must be `k-padded-v1`. */
   mapper: FecBlockMapper
   /** Nominal AU duration in microseconds. */
   frameDurationUs: number
@@ -35,6 +45,8 @@ export class InterleaveTiming {
   readonly mapper: FecBlockMapper
   readonly frameDurationUs: number
   readonly anchorMpuUs: number
+  /** Source symbols contributed by each media group: ceil(K / D). */
+  readonly symbolsPerGroup: number
 
   constructor(opts: InterleaveTimingOpts) {
     if (!(opts.frameDurationUs > 0)) {
@@ -43,7 +55,14 @@ export class InterleaveTiming {
     if (!Number.isFinite(opts.anchorMpuUs)) {
       throw new Error('anchorMpuUs must be finite')
     }
+    if (opts.mapper.blockProfile !== 'k-padded-v1') {
+      throw new Error(
+        `InterleaveTiming is the k-padded-v1 K-stride pacing model; a ${opts.mapper.blockProfile ?? 'non-FEC'} ` +
+          'stream has no K-stride block geometry',
+      )
+    }
     this.mapper = opts.mapper
+    this.symbolsPerGroup = Math.ceil(opts.mapper.k / opts.mapper.d)
     this.frameDurationUs = opts.frameDurationUs
     this.anchorMpuUs = opts.anchorMpuUs
   }
@@ -53,8 +72,14 @@ export class InterleaveTiming {
    * Per draft §8.3 + Sony anchor.
    */
   presentationUs(groupId: number, objectId: number): number {
-    const coords = this.mapper.derive(groupId, objectId)
-    return this.anchorMpuUs + coords.ssId * this.frameDurationUs
+    // §8.3 under k-padded-v1: SBN = floor(G / D), ESI = groupInBlock ×
+    // symbolsPerGroup + O, SS_ID = SBN × K + ESI (a 32-bit serial number;
+    // reduce SBN first so the product stays exact).
+    const { k, d } = this.mapper
+    const sbn = Math.floor(groupId / d)
+    const esi = (groupId - sbn * d) * this.symbolsPerGroup + objectId
+    const ssId = ((sbn % SS_ID_SPAN) * k + esi) % SS_ID_SPAN
+    return this.anchorMpuUs + ssId * this.frameDurationUs
   }
 
   /**
@@ -71,9 +96,11 @@ export class InterleaveTiming {
    */
   frameAtOffset(offsetUs: number): { groupId: number; objectId: number; ssId: number } {
     const rawSsId = Math.max(0, Math.floor(offsetUs / this.frameDurationUs))
-    const { sbn, esi } = this.mapper.fromSsId(rawSsId)
+    // k-padded-v1: SBN = floor(SS_ID / K), ESI = SS_ID mod K.
+    const sbn = Math.floor(rawSsId / this.mapper.k)
+    const esi = rawSsId % this.mapper.k
     // Invert §8.3: esi = groupInBlock * symbolsPerGroup + objectId
-    const spg = this.mapper.symbolsPerGroup
+    const spg = this.symbolsPerGroup
     const groupInBlock = Math.floor(esi / spg)
     const objectId = esi - groupInBlock * spg
     const groupId = sbn * this.mapper.d + groupInBlock