@blockcast/mmt-container 0.5.0 → 1.0.0-main.3cb7359ea316

package/src/phase14-catalog-override.ts

@@ -14,6 +14,10 @@
  *     switching set without asking the publisher to change its catalog.
  *   - Tracks present only in the override are appended as-is.
  *   - Tracks present only in the MoQ catalog are preserved unchanged.
+ *   - `fec` is the draft-ramadan-moq-fec-catalog-00 instance array; a repair
+ *     track is `packaging: "fec-repair"` with `source` + `instanceId`, and each
+ *     of base and delta names its own (one Track Name in two `repairTrack`
+ *     members is no FEC on either, catalog-00 5 rule 2).
  *
  * This module is deliberately player-agnostic. It exposes:
  *
@@ -30,7 +34,7 @@
  * runtime unless the test harness opts in.
  */
 
-import type { FecAlgorithm, FecCatalogConfig } from "./carp-catalog.js";
+import type { FecCatalogConfig } from "./carp-catalog.js";
 
 // ---------------------------------------------------------------------------
 // Override fixture shape (IETF draft-ietf-moq-catalogformat-01)
@@ -48,7 +52,10 @@ export interface Phase14OverrideTrack {
 	name: string;
 	/** CMSF packaging kind. Optional per track — when absent, the merge
 	 *  derives it from the override's top-level `streamingFormat`. */
-	packaging?: "mmtp" | "cmaf" | "loc" | "timeline";
+	packaging?: "mmtp" | "cmaf" | "loc" | "timeline" | "fec-repair";
+	/** A `fec-repair` track's source track and instance (catalog-00 3.2). */
+	source?: string;
+	instanceId?: number;
 	/** Required when packaging is `mmtp`; the current publisher emits MFU mode. */
 	mmtpMode?: "mfu";
 	/** Required when packaging is `mmtp`; copied into synthesized CMSF tracks. */
@@ -63,7 +70,7 @@ export interface Phase14OverrideTrack {
 	role?: "video" | "audio" | "timeline";
 	altGroup?: number;
 	framerate?: number;
-	fec?: Partial<FecCatalogConfig> & { algorithm: FecAlgorithm };
+	fec?: FecCatalogConfig;
 }
 
 /**
@@ -150,6 +157,8 @@ export function mergeOverrideIntoHangRenditions<T extends Record<string, any>>(
 	if (!override) return catalog;
 
 	for (const track of override.tracks) {
+		// Repair tracks are placed after the media merge, below.
+		if (track.packaging === "fec-repair") continue;
 		// Default role inference: names without an explicit role field are
 		// treated as video unless the name suffix says audio.
 		const role: "video" | "audio" =
@@ -188,9 +197,41 @@ export function mergeOverrideIntoHangRenditions<T extends Record<string, any>>(
 		// eslint-disable-next-line @typescript-eslint/no-explicit-any
 		(catalog as any)[bagKey] = bag;
 	}
+
+	// A repair track is a hang `repair.renditions` entry, bound by `source` +
+	// `instanceId`, never a media rendition. It is added only when the
+	// source's effective `fec` names it: a publisher `fec` that won the merge
+	// may bind a different repair track, and attaching this one would cost
+	// that instance its FEC (rule 3).
+	for (const track of override.tracks) {
+		if (track.packaging !== "fec-repair") continue;
+		const source =
+			catalog["video"]?.renditions?.[track.source as string] ??
+			catalog["audio"]?.renditions?.[track.source as string];
+		if (!namesRepairTrack(source?.fec, track.name, track.instanceId)) continue;
+		// eslint-disable-next-line @typescript-eslint/no-explicit-any
+		const repair: { renditions?: Record<string, any> } = catalog["repair"] ?? {};
+		repair.renditions ??= {};
+		const { name, packaging: _p, mmtpMode: _m, timescale: _t, groupDurationMs: _g, altGroup: _a, ...entry } = track;
+		repair.renditions[name] ??= entry;
+		// eslint-disable-next-line @typescript-eslint/no-explicit-any
+		(catalog as any)["repair"] = repair;
+	}
 	return catalog;
 }
 
+/** Whether `fec` holds the instance `instanceId` (default 0) whose `repairTrack` is `name`. */
+function namesRepairTrack(fec: unknown, name: string, instanceId: unknown): boolean {
+	const id = instanceId ?? 0;
+	return (
+		Array.isArray(fec) &&
+		fec.some(
+			(i) =>
+				typeof i === "object" && i !== null && (i.instanceId ?? 0) === id && i.repairTrack === name,
+		)
+	);
+}
+
 // ---------------------------------------------------------------------------
 // CMSF tracks merge (moqtail-private)
 // ---------------------------------------------------------------------------
@@ -248,7 +289,12 @@ export function mergeOverrideIntoCmsfTracks(
 		(t) => t.role === "audio" && typeof t.codec === "string" && (t.codec as string).length > 0,
 	);
 
-	for (const ot of override.tracks) {
+	// Media first, so a repair track can check its source's effective `fec`.
+	const ordered = [
+		...override.tracks.filter((t) => t.packaging !== "fec-repair"),
+		...override.tracks.filter((t) => t.packaging === "fec-repair"),
+	];
+	for (const ot of ordered) {
 		const existing = byName.get(ot.name);
 		if (existing !== undefined) {
 			// Preserve publisher-emitted fec + framerate — those describe what
@@ -290,13 +336,18 @@ export function mergeOverrideIntoCmsfTracks(
 					`[phase14-catalog-override] track "${ot.name}" has no packaging — supply per-track or set top-level streamingFormat`,
 				);
 			}
-			// Role inference: repair tracks (ending in /repair) stay role-less
-			// per CMSF convention; others default to video.
-			const role = ot.role ?? (ot.name.endsWith("/repair") ? undefined : "video");
+			// Role inference: repair tracks stay role-less per CMSF convention;
+			// others default to video. Decided by packaging, never by name.
+			const isRepair = packaging === "fec-repair";
+			// Same rule as the hang path: only a repair track its source names.
+			if (isRepair && !namesRepairTrack(byName.get(ot.source as string)?.fec, ot.name, ot.instanceId)) {
+				continue;
+			}
+			const role = ot.role ?? (isRepair ? undefined : "video");
 			const inheritedCodec =
 				role === "audio" ? existingAudioTrack?.codec : existingVideoTrack?.codec;
 			const codec = ot.codec ?? inheritedCodec;
-			if (packaging !== "timeline" && (typeof codec !== "string" || codec.length === 0)) {
+			if (packaging !== "timeline" && !isRepair && (typeof codec !== "string" || codec.length === 0)) {
 				throw new Error(
 					`[phase14-catalog-override] track "${ot.name}" has no codec (packaging='${packaging}') — supply per-track or ensure the publisher catalog has a ${role ?? "video"} track to inherit from`,
 				);
@@ -317,14 +368,14 @@ export function mergeOverrideIntoCmsfTracks(
 					`[phase14-catalog-override] track "${ot.name}" has packaging='mmtp' but no valid groupDurationMs`,
 				);
 			}
-			const entry: CmsfTrackJson = {
-				name: ot.name,
-				packaging,
-				codec: codec as string,
-			};
-			if (mmtpMode !== undefined) entry.mmtpMode = mmtpMode;
-			if (ot.timescale !== undefined) entry.timescale = ot.timescale;
-			if (ot.groupDurationMs !== undefined) entry.groupDurationMs = ot.groupDurationMs;
+			const entry: CmsfTrackJson = { name: ot.name, packaging };
+			if (codec !== undefined && !isRepair) entry.codec = codec as string;
+			if (ot.source !== undefined) entry["source"] = ot.source;
+			if (ot.instanceId !== undefined) entry["instanceId"] = ot.instanceId;
+			// Block geometry on a repair track costs its instance FEC (rule 1).
+			if (mmtpMode !== undefined && !isRepair) entry.mmtpMode = mmtpMode;
+			if (ot.timescale !== undefined && !isRepair) entry.timescale = ot.timescale;
+			if (ot.groupDurationMs !== undefined && !isRepair) entry.groupDurationMs = ot.groupDurationMs;
 			if (role !== undefined) entry.role = role;
 			if (ot.framerate !== undefined) entry.framerate = ot.framerate;
 			if (ot.fec !== undefined) entry.fec = ot.fec;

package/src/repair-fetch.ts

@@ -29,7 +29,9 @@
  *     below a RAP the receiver already holds complete is not requested at
  *     all (`moot-rap`), and a P0 FETCH still running when such a RAP
  *     arrives is cancelled (`repair-stopped`, `moot`): the receiver resumes
- *     from that RAP (draft-ramadan-moq-fec §11.4.2).
+ *     from that RAP (draft-ramadan-moq-fec §11.4.2). Only a repair that
+ *     could not land by the block's playout deadline (it relies on the
+ *     keyframe budget's extension) is moot: one that can stalls nothing.
  *   - P1 (audio) dispatches, uncapped, while no P0 is queued or in flight;
  *     P2 (delta) only while no P0/P1 is, earliest absolute fail deadline
  *     first (§11.4.5 item 3).
@@ -575,6 +577,8 @@ type StopReason = RepairStopReason
 
 interface FetchRun {
   readonly controller: AbortController
+  /** When this FETCH went out: it lands around `sentAt + rtt`. */
+  readonly sentAt: number
   stopped: StopReason | null
 }
 
@@ -596,6 +600,11 @@ interface RepairEntry {
    * later: a block reclassified from delta can gain the keyframe budget.
    */
   deadlineAt: number
+  /**
+   * `deadlineAt` without the keyframe budget's extension: the block's playout
+   * deadline. A FETCH landing by it costs no stall, so it is never moot.
+   */
+  playoutDeadlineAt: number
   /** Inputs `deadlineAt` was computed from; they move with it. */
   anchorAt: number | null
   delayMs: number | null
@@ -697,9 +706,18 @@ export function wireRepairFetch(mc: RepairFetchHost, opts: WireRepairFetchOption
     return length === undefined ? undefined : entry.sbn + length - 1
   }
 
-  /** A keyframe request whose whole block lies below a RAP already held complete. */
+  /**
+   * A keyframe request whose whole block lies below a RAP already held
+   * complete, and whose repair can only land on the keyframe budget's
+   * extension. One that lands by the playout deadline stalls nothing, and
+   * skipping it only throws away the block's frames (BLO-51635).
+   */
   const moot = (entry: RepairEntry): boolean => {
     if (entry.priority !== 0) return false
+    const rttMs = readRtt()
+    // A running FETCH lands relative to when it was sent, not to now.
+    const sentAt = entry.running?.sentAt ?? performance.now()
+    if (rttMs !== null && sentAt + rttMs < entry.playoutDeadlineAt) return false
     const last = lastSsId(entry)
     if (last === undefined) return false
     try {
@@ -832,7 +850,7 @@ export function wireRepairFetch(mc: RepairFetchHost, opts: WireRepairFetchOption
       bound: entry.bound,
       ...(entry.range ? { range: true as const } : {}),
     })
-    const run: FetchRun = { controller: new AbortController(), stopped: null }
+    const run: FetchRun = { controller: new AbortController(), sentAt: now, stopped: null }
     entry.running = run
     // Hold the block open to the presentation deadline while this FETCH can
     // still land: the multicast span elapsing must not abort it.
@@ -1053,6 +1071,10 @@ export function wireRepairFetch(mc: RepairFetchHost, opts: WireRepairFetchOption
       )
       if (promotedDeadline !== null && promotedDeadline.deadlineAt > entry.deadlineAt) {
         entry.deadlineAt = promotedDeadline.deadlineAt
+        entry.playoutDeadlineAt = Math.max(
+          entry.playoutDeadlineAt,
+          promotedDeadline.deadlineAt - promotedDeadline.extensionMs,
+        )
         entry.anchorAt = promotedDeadline.anchorAt
         entry.delayMs = promotedDeadline.delayMs
         entry.bound = promotedDeadline.bound
@@ -1231,6 +1253,7 @@ export function wireRepairFetch(mc: RepairFetchHost, opts: WireRepairFetchOption
       priority,
       subscriberPriority: wire.subscriberPriority,
       deadlineAt: deadline.deadlineAt,
+      playoutDeadlineAt: deadline.deadlineAt - deadline.extensionMs,
       anchorAt: deadline.anchorAt,
       delayMs: deadline.delayMs,
       bound: deadline.bound,
@@ -1313,6 +1336,7 @@ export function wireRepairFetch(mc: RepairFetchHost, opts: WireRepairFetchOption
         priority,
         subscriberPriority: wire.subscriberPriority,
         deadlineAt: deadline.deadlineAt,
+        playoutDeadlineAt: deadline.deadlineAt - deadline.extensionMs,
         anchorAt: deadline.anchorAt,
         delayMs: deadline.delayMs,
         bound: deadline.bound,