@blockcast/mmt-container 0.1.0-main.149f78a4adae

package/node_modules/@blockcast/mmt-fec/src/fec-block-mapper.ts

@@ -0,0 +1,332 @@
+/**
+ * FEC Block Mapper — §8.3 Source Symbol ESI Derivation
+ *
+ * Maps between MoQ transport identifiers (group_id, object_id) and
+ * FEC block coordinates (SBN, ESI, SS_ID) per draft-ramadan-moq-fec-00 §8.3.
+ *
+ * Shared by both players (audio/video pacing) and IWA (visualization + override).
+ *
+ * The formulas:
+ *   D = max(1, floor(interleaveDepthMs / gopDurationMs + 0.5))
+ *   SBN = floor(G / D)                             // source block number
+ *   first_group = SBN * D
+ *   symbols_per_group = ceil(K / D)
+ *   ESI = (G - first_group) * symbols_per_group + O
+ *   SS_ID = SBN * K + ESI
+ */
+
+import { deriveFecInterleaveDepth } from "./oti.js"
+
+/** Configuration from catalog FEC parameters. */
+export interface FecBlockConfig {
+  /** Block time span from catalog fec.interleaveDepthMs (milliseconds). */
+  interleaveDepthMs: number
+  /** GOP/frame duration (milliseconds). Measured from actual MMTP timestamps. */
+  gopDurationMs: number
+  /** K — source symbols per block from catalog fec.sourceSymbols. */
+  k: number
+}
+
+/** Result of mapping MoQ (group, object) → FEC coordinates. */
+export interface FecCoordinates {
+  /** Source Block Number */
+  sbn: number
+  /** Encoding Symbol ID within block (0..K-1 for source symbols) */
+  esi: number
+  /** Flat source symbol ID: SBN * K + ESI */
+  ssId: number
+  /** Which group within the block (0..D-1) */
+  groupInBlock: number
+  /** Total groups per block (D) */
+  groupsPerBlock: number
+}
+
+export class FecBlockMapper {
+  /** Groups per FEC block, recovered with positive round-half-up semantics. */
+  readonly d: number
+  /** Source symbols contributed by each group: ceil(K / D) */
+  readonly symbolsPerGroup: number
+  /** Source symbols per block */
+  readonly k: number
+  /** Block time span (ms) — used as pacing threshold */
+  readonly interleaveDepthMs: number
+  /** GOP/frame duration (ms) */
+  readonly gopDurationMs: number
+
+  constructor(config: FecBlockConfig) {
+    if (config.k <= 0) throw new Error('k must be > 0')
+    this.k = config.k
+    this.interleaveDepthMs = config.interleaveDepthMs
+    this.gopDurationMs = config.gopDurationMs
+    this.d = deriveFecInterleaveDepth(config.interleaveDepthMs, config.gopDurationMs)
+    this.symbolsPerGroup = Math.ceil(config.k / this.d)
+  }
+
+  /**
+   * §8.3: MoQ (group_id, object_id) → FEC (SBN, ESI, SS_ID).
+   *
+   * For a source object with MoQ Group_ID G and Object_ID O.
+   */
+  derive(groupId: number, objectId: number): FecCoordinates {
+    const sbn = Math.floor(groupId / this.d)
+    const firstGroup = sbn * this.d
+    const groupInBlock = groupId - firstGroup
+    const esi = groupInBlock * this.symbolsPerGroup + objectId
+    return {
+      sbn,
+      esi,
+      ssId: sbn * this.k + esi,
+      groupInBlock,
+      groupsPerBlock: this.d,
+    }
+  }
+
+  /**
+   * §8.3 inverse: SS_ID → (SBN, ESI).
+   *
+   * For MMTP over multicast UDP where the Source FEC Payload ID carries SS_ID directly.
+   */
+  fromSsId(ssId: number): { sbn: number; esi: number } {
+    return {
+      sbn: Math.floor(ssId / this.k),
+      esi: ssId % this.k,
+    }
+  }
+
+  /**
+   * Pacing threshold: one full block duration = interleaveDepthMs.
+   * The minimum buffer needed before FEC recovery can start.
+   */
+  get pacingThresholdMs(): number {
+    return this.interleaveDepthMs
+  }
+
+  /** Is this group the first in a new FEC block? (SBN boundary) */
+  isBlockBoundary(groupId: number): boolean {
+    return groupId % this.d === 0
+  }
+
+  /** Block start/end group IDs for a given SBN. For IWA visualization. */
+  blockRange(sbn: number): { firstGroup: number; lastGroup: number } {
+    return {
+      firstGroup: sbn * this.d,
+      lastGroup: (sbn + 1) * this.d - 1,
+    }
+  }
+
+  /** CMAF segment name for a block. Matches MoQ group naming convention. */
+  segmentName(trackName: string, sbn: number): string {
+    return `${trackName}/sbn_${sbn}`
+  }
+
+  /** Expected number of samples in a complete CMAF segment for this block. */
+  get samplesPerBlock(): number {
+    return this.k
+  }
+}
+
+/**
+ * Null/raw mode: no FEC. Every group is its own "block".
+ * Used when catalog has no FEC config (ATSC raw, DVB dongles, no-FEC MMTP).
+ * IWA uses this for passthrough visualization.
+ */
+export class NullBlockMapper extends FecBlockMapper {
+  constructor(gopDurationMs: number) {
+    if (gopDurationMs <= 0) throw new Error('NullBlockMapper: gopDurationMs must be > 0 (derive from catalog framerate or sampleRate)')
+    // D=1, K=1: each group is a single-symbol block
+    super({ interleaveDepthMs: gopDurationMs, gopDurationMs, k: 1 })
+  }
+
+  derive(groupId: number, objectId: number): FecCoordinates {
+    return {
+      sbn: groupId,
+      esi: objectId,
+      ssId: groupId,
+      groupInBlock: 0,
+      groupsPerBlock: 1,
+    }
+  }
+
+  get pacingThresholdMs(): number {
+    return 0
+  }
+}
+
+/**
+ * Object-level FEC (§9.1): each MoQ group (frame) is its own FEC block.
+ * K_actual = ceil(frame_bytes / symbolSize) — varies per block.
+ *
+ * SBN = group_id, ESI = object_id.
+ * SS_ID = Group_ID * sourceSymbols + Object_ID (§9.1.2).
+ *
+ * This mapper does NOT carry per-block K. Each block discovers its own K from:
+ *   1. Clean reception: counting source objects per group
+ *   2. Repair packets: RSB_length in Repair FEC Payload ID (§7.1)
+ *
+ * Callers MUST pass per-block K to FecBlockManager.addSourcePacket/addRepairPacket.
+ * Created once per stream, GC'd on stream close (Effect cleanup).
+ */
+export class ObjectBlockMapper extends FecBlockMapper {
+  /** Catalog sourceSymbols (max K) — used ONLY for SS_ID encoding (§9.1.2).
+   *  Actual per-block K varies: K_actual = ceil(frame_bytes / symbolSize). */
+  readonly sourceSymbolsMax: number
+
+  constructor(gopDurationMs: number, sourceSymbolsMax: number) {
+    if (sourceSymbolsMax <= 0) throw new Error('ObjectBlockMapper: sourceSymbolsMax must be > 0 (from catalog)')
+    // D=1, K=sourceSymbolsMax for SS_ID math only — actual block K varies
+    super({ interleaveDepthMs: gopDurationMs, gopDurationMs, k: sourceSymbolsMax })
+    this.sourceSymbolsMax = sourceSymbolsMax
+  }
+
+  /** SBN = group_id, ESI = object_id. SS_ID per §9.1.2. */
+  derive(groupId: number, objectId: number): FecCoordinates {
+    return {
+      sbn: groupId,
+      esi: objectId,
+      ssId: groupId * this.sourceSymbolsMax + objectId,
+      groupInBlock: 0,
+      groupsPerBlock: 1,
+    }
+  }
+
+  /**
+   * Decode SS_ID using block-specific K from repair metadata.
+   * In object mode, the global K is meaningless — each block has different K.
+   * Callers must pass blockK (from RSB_length in repair FEC Payload ID).
+   */
+  fromSsId(ssId: number, blockK?: number): { sbn: number; esi: number } {
+    if (blockK && blockK > 0) {
+      return {
+        sbn: Math.floor(ssId / blockK),
+        esi: ssId % blockK,
+      }
+    }
+    // Fallback: treat ssId as raw ESI (within current block)
+    return { sbn: 0, esi: ssId }
+  }
+
+  get pacingThresholdMs(): number {
+    return this.gopDurationMs // one frame latency
+  }
+
+  isBlockBoundary(_groupId: number): boolean {
+    return true // every group starts a new block
+  }
+
+  get samplesPerBlock(): number {
+    return 0 // variable — not known until frame arrives
+  }
+}
+
+/**
+ * Create a FecBlockMapper from catalog FEC config + measured GOP duration.
+ * Returns NullBlockMapper when FEC is not configured.
+ * Returns ObjectBlockMapper when fecMode is 'object'.
+ */
+export function createMapper(
+  fecConfig: { interleaveDepthMs?: number; sourceSymbols?: number; mode?: string } | undefined,
+  gopDurationMs: number,
+): FecBlockMapper {
+  if (!fecConfig || !fecConfig.sourceSymbols) {
+    return new NullBlockMapper(gopDurationMs)
+  }
+  // extensions feature — see moqcast-draft docs/fec-extensions-material.md, not in public -00
+  if (fecConfig.mode === 'object') {
+    return new ObjectBlockMapper(gopDurationMs, fecConfig.sourceSymbols)
+  }
+  return new FecBlockMapper({
+    interleaveDepthMs: fecConfig.interleaveDepthMs && fecConfig.interleaveDepthMs > 0
+      ? fecConfig.interleaveDepthMs
+      : gopDurationMs,
+    gopDurationMs,
+    k: fecConfig.sourceSymbols,
+  })
+}
+
+/** A registered track with its mapper and time anchor. */
+export interface BridgedTrack {
+  mapper: FecBlockMapper
+  /** Wall-clock time (ms) when group 0 of this track started. */
+  epochMs: number
+}
+
+/**
+ * Cross-track SBN alignment via wall-clock timestamps.
+ *
+ * Different physical layers have different FEC configs (WiFi K=4/80ms,
+ * cellular K=32/4000ms, ATSC K=64/10000ms). Each track has its own
+ * FecBlockMapper. The bridge converts between them using wall-clock
+ * timestamps as the universal coordinate.
+ */
+export class FecTimestampBridge {
+  #tracks = new Map<string, BridgedTrack>()
+
+  /** Register a track with its FEC mapper and start epoch. */
+  register(trackName: string, mapper: FecBlockMapper, epochMs: number): void {
+    this.#tracks.set(trackName, { mapper, epochMs })
+  }
+
+  /** Remove a track. */
+  unregister(trackName: string): void {
+    this.#tracks.delete(trackName)
+  }
+
+  /** All registered track names. */
+  get trackNames(): string[] {
+    return [...this.#tracks.keys()]
+  }
+
+  /** Get the mapper for a specific track. */
+  getMapper(trackName: string): FecBlockMapper | undefined {
+    return this.#tracks.get(trackName)?.mapper
+  }
+
+  /**
+   * Resolve a wall-clock timestamp to SBN on every registered track.
+   * Returns a map of trackName → { sbn, groupInBlock, groupsPerBlock }.
+   */
+  resolve(wallClockMs: number): Map<string, { sbn: number; groupId: number; groupInBlock: number }> {
+    const result = new Map<string, { sbn: number; groupId: number; groupInBlock: number }>()
+    for (const [name, track] of this.#tracks) {
+      const elapsedMs = wallClockMs - track.epochMs
+      if (elapsedMs < 0) continue
+      const groupId = Math.floor(elapsedMs / track.mapper.gopDurationMs)
+      const coords = track.mapper.derive(groupId, 0)
+      result.set(name, { sbn: coords.sbn, groupId, groupInBlock: coords.groupInBlock })
+    }
+    return result
+  }
+
+  /**
+   * Wall-clock time range for a specific block on a specific track.
+   */
+  blockTimeRange(trackName: string, sbn: number): { startMs: number; endMs: number } | undefined {
+    const track = this.#tracks.get(trackName)
+    if (!track) return undefined
+    const range = track.mapper.blockRange(sbn)
+    return {
+      startMs: track.epochMs + range.firstGroup * track.mapper.gopDurationMs,
+      endMs: track.epochMs + (range.lastGroup + 1) * track.mapper.gopDurationMs,
+    }
+  }
+
+  /**
+   * Find which SBNs on other tracks overlap a given block on a source track.
+   */
+  overlappingBlocks(
+    sourceTrack: string,
+    sourceSbn: number,
+    targetTrack: string,
+  ): { firstSbn: number; lastSbn: number } | undefined {
+    const source = this.#tracks.get(sourceTrack)
+    const target = this.#tracks.get(targetTrack)
+    if (!source || !target) return undefined
+    const sourceRange = this.blockTimeRange(sourceTrack, sourceSbn)
+    if (!sourceRange) return undefined
+    const targetStartGroup = Math.floor((sourceRange.startMs - target.epochMs) / target.mapper.gopDurationMs)
+    const targetEndGroup = Math.floor((sourceRange.endMs - target.epochMs) / target.mapper.gopDurationMs)
+    const firstCoords = target.mapper.derive(Math.max(0, targetStartGroup), 0)
+    const lastCoords = target.mapper.derive(Math.max(0, targetEndGroup), 0)
+    return { firstSbn: firstCoords.sbn, lastSbn: lastCoords.sbn }
+  }
+}

package/node_modules/@blockcast/mmt-fec/src/index.ts

@@ -0,0 +1,77 @@
+/**
+ * @mmt/fec - Container-agnostic FEC client for RaptorQ (RFC 6330)
+ *
+ * This package provides a TypeScript wrapper around the mmt-wasm WASM bindings
+ * for Forward Error Correction using RaptorQ (RFC 6330).
+ *
+ * Usage:
+ * ```typescript
+ * The stateful WASM decoder is owned by @blockcast/mmt-container's FecManager
+ * or @blockcast/fec-worker. This package supplies container-independent FEC
+ * geometry, OTI, mapping, and recovery primitives.
+ * ```
+ */
+
+export {
+	FecBlockManager,
+	FEC_STATE,
+	type FecState,
+	type FecBlockManagerOptions,
+	type FecBlockStats,
+} from "./block-manager.js";
+
+export {
+	processFecBlock,
+	processFecSymbol,
+	type ParsedFecSymbol,
+	type ProcessFecBlockResult,
+	type ProcessFecSymbolOptions,
+} from "./block-processor.js";
+
+export {
+	ReorderBuffer,
+	type ReorderBufferConfig,
+} from "./reorder-buffer.js";
+
+export {
+	splitToSymbols,
+	recoverFromSymbols,
+	computeK,
+} from "./cmaf-symbols.js";
+
+export {
+	splitFrameToSymbol,
+	recoverFrameFromSymbol,
+} from "./loc-symbols.js";
+
+export {
+	CmafFecRecovery,
+	type CmafFecRecoveryConfig,
+	type FecDecoder,
+} from "./cmaf-recovery.js";
+
+export {
+	buildOTI,
+	buildOTIFromCatalog,
+	parseOTI,
+	computeFecTimeout,
+	deriveFecInterleaveDepth,
+	catalogFecInterleaveMs,
+	type FecInterleaveCatalog,
+	parseRepairPacket,
+	type OTIParams,
+	fecBlockDeadlineMs,
+	fecBlockBudgetMs,
+	playbackLatencyMs,
+} from "./oti.js";
+
+export {
+	FecBlockMapper,
+	NullBlockMapper,
+	ObjectBlockMapper,
+	createMapper,
+	FecTimestampBridge,
+	type FecBlockConfig,
+	type FecCoordinates,
+	type BridgedTrack,
+} from "./fec-block-mapper.js";

package/node_modules/@blockcast/mmt-fec/src/loc-symbols.ts

@@ -0,0 +1,34 @@
+/**
+ * LOC Frame Symbol Splitter — per-frame FEC symbol operations for LOC
+ * (Low Overhead Container) raw codec bitstream frames.
+ *
+ * Unlike CMAF chunks which may span multiple symbols (K > 1), LOC frames
+ * map 1:1 to a single FEC symbol: pad to symbolSize or truncate.
+ *
+ * Pure functions — no side effects, no state.
+ */
+
+/**
+ * Pad a LOC frame (raw codec bitstream) to FEC symbol size.
+ * If the frame is already >= symbolSize, truncate to symbolSize.
+ */
+export function splitFrameToSymbol(
+	frame: Uint8Array,
+	symbolSize: number,
+): Uint8Array {
+	if (frame.length >= symbolSize) return frame.subarray(0, symbolSize);
+	const padded = new Uint8Array(symbolSize); // zero-initialized
+	padded.set(frame);
+	return padded;
+}
+
+/**
+ * Strip padding from a recovered FEC symbol to get the original frame.
+ * Uses the known original length to trim zero-padding.
+ */
+export function recoverFrameFromSymbol(
+	symbol: Uint8Array,
+	originalLength: number,
+): Uint8Array {
+	return symbol.subarray(0, originalLength);
+}