@blockcast/mmt-render 0.1.0 → 0.3.0-main.1cd3cdea89da

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@blockcast/mmt-render",
-  "version": "0.1.0",
-  "description": "Shared MMT render pipeline (FEC-aware pacing, interleave timing, audio worklet) for MoQ players",
+  "version": "0.3.0-main.1cd3cdea89da",
+  "description": "Shared MMT render pipeline (FEC-aware pacing, audio worklet, video render) for MoQ players",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -18,10 +18,6 @@
       "import": "./dist/pacing/frame-pacer.js",
       "types": "./dist/pacing/frame-pacer.d.ts"
     },
-    "./pacing/interleave-timing": {
-      "import": "./dist/pacing/interleave-timing.js",
-      "types": "./dist/pacing/interleave-timing.d.ts"
-    },
     "./audio": {
       "import": "./dist/audio/index.js",
       "types": "./dist/audio/index.d.ts"
@@ -73,8 +69,8 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@blockcast/mmt-container": "^0.1.0",
-    "@blockcast/mmt-fec": "^0.1.0"
+    "@blockcast/mmt-container": "0.4.0-main.1cd3cdea89da",
+    "@blockcast/mmt-fec": "0.3.0-main.1cd3cdea89da"
   },
   "devDependencies": {
     "@types/audioworklet": "^0.0.77",

package/src/index.ts

@@ -2,7 +2,7 @@
  * @blockcast/mmt-render — shared MMT render pipeline for MoQ players.
  *
  * Subpath exports:
- *   - ./pacing                FrameCountPacer, InterleaveTiming
+ *   - ./pacing                FrameCountPacer
  *   - ./audio                 AudioRenderPipeline, AudioRingBuffer, worklet helpers
  *   - ./video                 VideoRenderPipeline, KeyframeGate
  *   - ./audio/worklet.js      Prebuilt self-contained AudioWorklet bundle

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/index.ts

@@ -1,5 +1,3 @@
 export { FrameCountPacer } from './frame-pacer.js'
 export type { FrameCountPacerOpts, PacerSnapshot } from './frame-pacer.js'
-export { InterleaveTiming } from './interleave-timing.js'
-export type { InterleaveTimingOpts } from './interleave-timing.js'
 export { auDurationMsFromCodec, pictureDurationMs } from './au-duration.js'

package/dist/pacing/interleave-timing.d.ts

@@ -1,64 +0,0 @@
-/**
- * InterleaveTiming — per-AU presentation-time reconstruction.
- *
- * When encoders pack multiple AUs per MMTP MPU with a single mpu_timestamp
- * (normal for FEC-interleaved audio, and for video with multi-picture MPUs),
- * the raw mpu_timestamp is ambiguous for per-AU scheduling. The FEC block
- * math (draft-ramadan-moq-fec-00 §8.3) combined with the Sony libatsc3
- * pattern recovers correct per-AU time:
- *
- *   au_index_in_block = groupInBlock × symbolsPerGroup + objectId
- *   ssId              = sbn × K + au_index_in_block
- *   presentationUs    = anchorMpuUs + ssId × frameDurationUs
- *
- * The anchor (anchorMpuUs) is the mpu_timestamp of the first observed AU.
- * Every downstream per-AU time is then deterministic from FEC coordinates
- * + codec frame duration — identical whether the AU arrives via MoQ unicast
- * (group_id/object_id) or multicast UDP (SS_ID from FEC Payload ID).
- *
- * Consumers: CMAF segment assembler (block boundary → segment cut points),
- * debug overlays, cross-path FEC combining, sync diagnostics.
- */
-import type { FecBlockMapper } from '@blockcast/mmt-fec';
-export interface InterleaveTimingOpts {
-    /** Track's FEC mapper (provides K, D, symbolsPerGroup). */
-    mapper: FecBlockMapper;
-    /** Nominal AU duration in microseconds. */
-    frameDurationUs: number;
-    /** Wall-time anchor: the mpu_timestamp of the first observed AU (µs). */
-    anchorMpuUs: number;
-}
-export declare class InterleaveTiming {
-    readonly mapper: FecBlockMapper;
-    readonly frameDurationUs: number;
-    readonly anchorMpuUs: number;
-    constructor(opts: InterleaveTimingOpts);
-    /**
-     * Presentation time (µs) for an AU at MoQ coords (group_id, object_id).
-     * Per draft §8.3 + Sony anchor.
-     */
-    presentationUs(groupId: number, objectId: number): number;
-    /**
-     * Presentation time (µs) for an AU identified by its flat SS_ID
-     * (multicast FEC Payload ID path).
-     */
-    presentationUsFromSsId(ssId: number): number;
-    /**
-     * Inverse: which (group_id, object_id) AU is scheduled at the given
-     * wall offset (µs) from anchor? Clamps to ssId≥0.
-     */
-    frameAtOffset(offsetUs: number): {
-        groupId: number;
-        objectId: number;
-        ssId: number;
-    };
-    /**
-     * Block start/end in microseconds. Source blocks span `D × GOP_duration`
-     * of wall time; this returns the anchored wall range [startUs, endUs).
-     */
-    blockTimeRangeUs(sbn: number): {
-        startUs: number;
-        endUs: number;
-    };
-}
-//# sourceMappingURL=interleave-timing.d.ts.map

package/dist/pacing/interleave-timing.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"interleave-timing.d.ts","sourceRoot":"","sources":["../../src/pacing/interleave-timing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAA;AAExD,MAAM,WAAW,oBAAoB;IACnC,2DAA2D;IAC3D,MAAM,EAAE,cAAc,CAAA;IACtB,2CAA2C;IAC3C,eAAe,EAAE,MAAM,CAAA;IACvB,yEAAyE;IACzE,WAAW,EAAE,MAAM,CAAA;CACpB;AAED,qBAAa,gBAAgB;IAC3B,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAA;IAC/B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAA;IAChC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;gBAEhB,IAAI,EAAE,oBAAoB;IAYtC;;;OAGG;IACH,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM;IAKzD;;;OAGG;IACH,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAI5C;;;OAGG;IACH,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE;IAWpF;;;OAGG;IACH,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE;CAQlE"}

package/dist/pacing/interleave-timing.js

@@ -1,58 +0,0 @@
-// src/pacing/interleave-timing.ts
-var InterleaveTiming = class {
-  constructor(opts) {
-    if (!(opts.frameDurationUs > 0)) {
-      throw new Error("frameDurationUs must be > 0");
-    }
-    if (!Number.isFinite(opts.anchorMpuUs)) {
-      throw new Error("anchorMpuUs must be finite");
-    }
-    this.mapper = opts.mapper;
-    this.frameDurationUs = opts.frameDurationUs;
-    this.anchorMpuUs = opts.anchorMpuUs;
-  }
-  /**
-   * Presentation time (µs) for an AU at MoQ coords (group_id, object_id).
-   * Per draft §8.3 + Sony anchor.
-   */
-  presentationUs(groupId, objectId) {
-    const coords = this.mapper.derive(groupId, objectId);
-    return this.anchorMpuUs + coords.ssId * this.frameDurationUs;
-  }
-  /**
-   * Presentation time (µs) for an AU identified by its flat SS_ID
-   * (multicast FEC Payload ID path).
-   */
-  presentationUsFromSsId(ssId) {
-    return this.anchorMpuUs + ssId * this.frameDurationUs;
-  }
-  /**
-   * Inverse: which (group_id, object_id) AU is scheduled at the given
-   * wall offset (µs) from anchor? Clamps to ssId≥0.
-   */
-  frameAtOffset(offsetUs) {
-    const rawSsId = Math.max(0, Math.floor(offsetUs / this.frameDurationUs));
-    const { sbn, esi } = this.mapper.fromSsId(rawSsId);
-    const spg = this.mapper.symbolsPerGroup;
-    const groupInBlock = Math.floor(esi / spg);
-    const objectId = esi - groupInBlock * spg;
-    const groupId = sbn * this.mapper.d + groupInBlock;
-    return { groupId, objectId, ssId: rawSsId };
-  }
-  /**
-   * Block start/end in microseconds. Source blocks span `D × GOP_duration`
-   * of wall time; this returns the anchored wall range [startUs, endUs).
-   */
-  blockTimeRangeUs(sbn) {
-    const firstSsId = sbn * this.mapper.k;
-    const lastSsId = (sbn + 1) * this.mapper.k;
-    return {
-      startUs: this.anchorMpuUs + firstSsId * this.frameDurationUs,
-      endUs: this.anchorMpuUs + lastSsId * this.frameDurationUs
-    };
-  }
-};
-export {
-  InterleaveTiming
-};
-//# sourceMappingURL=interleave-timing.js.map

package/dist/pacing/interleave-timing.js.map

@@ -1,7 +0,0 @@
-{
-  "version": 3,
-  "sources": ["../../src/pacing/interleave-timing.ts"],
-  "sourcesContent": ["/**\n * InterleaveTiming \u2014 per-AU presentation-time reconstruction.\n *\n * When encoders pack multiple AUs per MMTP MPU with a single mpu_timestamp\n * (normal for FEC-interleaved audio, and for video with multi-picture MPUs),\n * the raw mpu_timestamp is ambiguous for per-AU scheduling. The FEC block\n * math (draft-ramadan-moq-fec-00 \u00A78.3) combined with the Sony libatsc3\n * pattern recovers correct per-AU time:\n *\n *   au_index_in_block = groupInBlock \u00D7 symbolsPerGroup + objectId\n *   ssId              = sbn \u00D7 K + au_index_in_block\n *   presentationUs    = anchorMpuUs + ssId \u00D7 frameDurationUs\n *\n * The anchor (anchorMpuUs) is the mpu_timestamp of the first observed AU.\n * Every downstream per-AU time is then deterministic from FEC coordinates\n * + codec frame duration \u2014 identical whether the AU arrives via MoQ unicast\n * (group_id/object_id) or multicast UDP (SS_ID from FEC Payload ID).\n *\n * Consumers: CMAF segment assembler (block boundary \u2192 segment cut points),\n * debug overlays, cross-path FEC combining, sync diagnostics.\n */\n\nimport type { FecBlockMapper } from '@blockcast/mmt-fec'\n\nexport interface InterleaveTimingOpts {\n  /** Track's FEC mapper (provides K, D, symbolsPerGroup). */\n  mapper: FecBlockMapper\n  /** Nominal AU duration in microseconds. */\n  frameDurationUs: number\n  /** Wall-time anchor: the mpu_timestamp of the first observed AU (\u00B5s). */\n  anchorMpuUs: number\n}\n\nexport class InterleaveTiming {\n  readonly mapper: FecBlockMapper\n  readonly frameDurationUs: number\n  readonly anchorMpuUs: number\n\n  constructor(opts: InterleaveTimingOpts) {\n    if (!(opts.frameDurationUs > 0)) {\n      throw new Error('frameDurationUs must be > 0')\n    }\n    if (!Number.isFinite(opts.anchorMpuUs)) {\n      throw new Error('anchorMpuUs must be finite')\n    }\n    this.mapper = opts.mapper\n    this.frameDurationUs = opts.frameDurationUs\n    this.anchorMpuUs = opts.anchorMpuUs\n  }\n\n  /**\n   * Presentation time (\u00B5s) for an AU at MoQ coords (group_id, object_id).\n   * Per draft \u00A78.3 + Sony anchor.\n   */\n  presentationUs(groupId: number, objectId: number): number {\n    const coords = this.mapper.derive(groupId, objectId)\n    return this.anchorMpuUs + coords.ssId * this.frameDurationUs\n  }\n\n  /**\n   * Presentation time (\u00B5s) for an AU identified by its flat SS_ID\n   * (multicast FEC Payload ID path).\n   */\n  presentationUsFromSsId(ssId: number): number {\n    return this.anchorMpuUs + ssId * this.frameDurationUs\n  }\n\n  /**\n   * Inverse: which (group_id, object_id) AU is scheduled at the given\n   * wall offset (\u00B5s) from anchor? Clamps to ssId\u22650.\n   */\n  frameAtOffset(offsetUs: number): { groupId: number; objectId: number; ssId: number } {\n    const rawSsId = Math.max(0, Math.floor(offsetUs / this.frameDurationUs))\n    const { sbn, esi } = this.mapper.fromSsId(rawSsId)\n    // Invert \u00A78.3: esi = groupInBlock * symbolsPerGroup + objectId\n    const spg = this.mapper.symbolsPerGroup\n    const groupInBlock = Math.floor(esi / spg)\n    const objectId = esi - groupInBlock * spg\n    const groupId = sbn * this.mapper.d + groupInBlock\n    return { groupId, objectId, ssId: rawSsId }\n  }\n\n  /**\n   * Block start/end in microseconds. Source blocks span `D \u00D7 GOP_duration`\n   * of wall time; this returns the anchored wall range [startUs, endUs).\n   */\n  blockTimeRangeUs(sbn: number): { startUs: number; endUs: number } {\n    const firstSsId = sbn * this.mapper.k\n    const lastSsId = (sbn + 1) * this.mapper.k\n    return {\n      startUs: this.anchorMpuUs + firstSsId * this.frameDurationUs,\n      endUs: this.anchorMpuUs + lastSsId * this.frameDurationUs,\n    }\n  }\n}\n"],
-  "mappings": ";AAiCO,IAAM,mBAAN,MAAuB;AAAA,EAK5B,YAAY,MAA4B;AACtC,QAAI,EAAE,KAAK,kBAAkB,IAAI;AAC/B,YAAM,IAAI,MAAM,6BAA6B;AAAA,IAC/C;AACA,QAAI,CAAC,OAAO,SAAS,KAAK,WAAW,GAAG;AACtC,YAAM,IAAI,MAAM,4BAA4B;AAAA,IAC9C;AACA,SAAK,SAAS,KAAK;AACnB,SAAK,kBAAkB,KAAK;AAC5B,SAAK,cAAc,KAAK;AAAA,EAC1B;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,eAAe,SAAiB,UAA0B;AACxD,UAAM,SAAS,KAAK,OAAO,OAAO,SAAS,QAAQ;AACnD,WAAO,KAAK,cAAc,OAAO,OAAO,KAAK;AAAA,EAC/C;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,uBAAuB,MAAsB;AAC3C,WAAO,KAAK,cAAc,OAAO,KAAK;AAAA,EACxC;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,cAAc,UAAuE;AACnF,UAAM,UAAU,KAAK,IAAI,GAAG,KAAK,MAAM,WAAW,KAAK,eAAe,CAAC;AACvE,UAAM,EAAE,KAAK,IAAI,IAAI,KAAK,OAAO,SAAS,OAAO;AAEjD,UAAM,MAAM,KAAK,OAAO;AACxB,UAAM,eAAe,KAAK,MAAM,MAAM,GAAG;AACzC,UAAM,WAAW,MAAM,eAAe;AACtC,UAAM,UAAU,MAAM,KAAK,OAAO,IAAI;AACtC,WAAO,EAAE,SAAS,UAAU,MAAM,QAAQ;AAAA,EAC5C;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,iBAAiB,KAAiD;AAChE,UAAM,YAAY,MAAM,KAAK,OAAO;AACpC,UAAM,YAAY,MAAM,KAAK,KAAK,OAAO;AACzC,WAAO;AAAA,MACL,SAAS,KAAK,cAAc,YAAY,KAAK;AAAA,MAC7C,OAAO,KAAK,cAAc,WAAW,KAAK;AAAA,IAC5C;AAAA,EACF;AACF;",
-  "names": []
-}

package/src/pacing/interleave-timing.ts

@@ -1,95 +0,0 @@
-/**
- * InterleaveTiming — per-AU presentation-time reconstruction.
- *
- * When encoders pack multiple AUs per MMTP MPU with a single mpu_timestamp
- * (normal for FEC-interleaved audio, and for video with multi-picture MPUs),
- * the raw mpu_timestamp is ambiguous for per-AU scheduling. The FEC block
- * math (draft-ramadan-moq-fec-00 §8.3) combined with the Sony libatsc3
- * pattern recovers correct per-AU time:
- *
- *   au_index_in_block = groupInBlock × symbolsPerGroup + objectId
- *   ssId              = sbn × K + au_index_in_block
- *   presentationUs    = anchorMpuUs + ssId × frameDurationUs
- *
- * The anchor (anchorMpuUs) is the mpu_timestamp of the first observed AU.
- * Every downstream per-AU time is then deterministic from FEC coordinates
- * + codec frame duration — identical whether the AU arrives via MoQ unicast
- * (group_id/object_id) or multicast UDP (SS_ID from FEC Payload ID).
- *
- * Consumers: CMAF segment assembler (block boundary → segment cut points),
- * debug overlays, cross-path FEC combining, sync diagnostics.
- */
-
-import type { FecBlockMapper } from '@blockcast/mmt-fec'
-
-export interface InterleaveTimingOpts {
-  /** Track's FEC mapper (provides K, D, symbolsPerGroup). */
-  mapper: FecBlockMapper
-  /** Nominal AU duration in microseconds. */
-  frameDurationUs: number
-  /** Wall-time anchor: the mpu_timestamp of the first observed AU (µs). */
-  anchorMpuUs: number
-}
-
-export class InterleaveTiming {
-  readonly mapper: FecBlockMapper
-  readonly frameDurationUs: number
-  readonly anchorMpuUs: number
-
-  constructor(opts: InterleaveTimingOpts) {
-    if (!(opts.frameDurationUs > 0)) {
-      throw new Error('frameDurationUs must be > 0')
-    }
-    if (!Number.isFinite(opts.anchorMpuUs)) {
-      throw new Error('anchorMpuUs must be finite')
-    }
-    this.mapper = opts.mapper
-    this.frameDurationUs = opts.frameDurationUs
-    this.anchorMpuUs = opts.anchorMpuUs
-  }
-
-  /**
-   * Presentation time (µs) for an AU at MoQ coords (group_id, object_id).
-   * 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
-  }
-
-  /**
-   * Presentation time (µs) for an AU identified by its flat SS_ID
-   * (multicast FEC Payload ID path).
-   */
-  presentationUsFromSsId(ssId: number): number {
-    return this.anchorMpuUs + ssId * this.frameDurationUs
-  }
-
-  /**
-   * Inverse: which (group_id, object_id) AU is scheduled at the given
-   * wall offset (µs) from anchor? Clamps to ssId≥0.
-   */
-  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)
-    // Invert §8.3: esi = groupInBlock * symbolsPerGroup + objectId
-    const spg = this.mapper.symbolsPerGroup
-    const groupInBlock = Math.floor(esi / spg)
-    const objectId = esi - groupInBlock * spg
-    const groupId = sbn * this.mapper.d + groupInBlock
-    return { groupId, objectId, ssId: rawSsId }
-  }
-
-  /**
-   * Block start/end in microseconds. Source blocks span `D × GOP_duration`
-   * of wall time; this returns the anchored wall range [startUs, endUs).
-   */
-  blockTimeRangeUs(sbn: number): { startUs: number; endUs: number } {
-    const firstSsId = sbn * this.mapper.k
-    const lastSsId = (sbn + 1) * this.mapper.k
-    return {
-      startUs: this.anchorMpuUs + firstSsId * this.frameDurationUs,
-      endUs: this.anchorMpuUs + lastSsId * this.frameDurationUs,
-    }
-  }
-}