@blockcast/mmt-container 0.1.0 → 0.3.0

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

@@ -0,0 +1,310 @@
+/**
+ * FEC Block Mapper — catalog block geometry for one FEC stream.
+ *
+ * Carries the catalog FEC geometry every consumer shares (K, the block span
+ * `interleaveDepthMs`, the media-unit duration, and the derived media units per
+ * block D) together with the stream's `fec.blockProfile` (BLO-35597).
+ *
+ * It deliberately does NOT map MoQ media groups to FEC blocks. A recovered
+ * packet's media group is read from its own MMTP/MPU header
+ * ({@link recoveredPacketMediaGroup}), never from SBN arithmetic, and a source
+ * symbol's block comes from the wire:
+ *
+ * - `k-padded-v1`: `SBN = floor(SS_ID / K)`, `ESI = SS_ID mod K`
+ *   ({@link FecBlockMapper.fromSsId}).
+ * - `iso-ssbg1-v1`: a block is the SS_ID range `[SS_Start, SS_Start +
+ *   SSB_length)` its Repair FEC Payload ID states (ISO/IEC 23008-1 C.5.3), so
+ *   SS_ID alone locates nothing and `fromSsId` throws.
+ *
+ * Object FEC (draft-ramadan-moq-fec §9.1) is the one exception: there each MoQ
+ * group IS its own FEC block, so {@link ObjectBlockMapper} keeps its identity
+ * `derive`.
+ */
+
+import {
+  PACKET_TYPE_MPU,
+  parseFecBlockProfile,
+  parseMMTPHeader,
+  parseMPUHeader,
+  type FecBlockProfile,
+} from "@blockcast/mmt-base"
+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 from catalog fec.sourceSymbols: the source symbols per block under
+   * `k-padded-v1`, the maximum SSB_length under `iso-ssbg1-v1`.
+   */
+  k: number
+  /**
+   * The catalog `fec.blockProfile`. Required and validated with
+   * `parseFecBlockProfile`: there is no default and nothing is inferred.
+   */
+  blockProfile: FecBlockProfile
+}
+
+/** FEC coordinates of one MoQ object, for the mappers whose groups are blocks. */
+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 */
+  ssId: number
+}
+
+/**
+ * The media group (MPU sequence number) of a recovered MMTP packet, read from
+ * the packet's own MMTP header and MPU payload header. The media group of a
+ * recovered packet is a field the wire states; it is never derived from the
+ * FEC block it was recovered in.
+ *
+ * @param packet - One protected MMTP packet (as recovered from a source symbol)
+ * @returns The packet's `MPU_sequence_number`
+ * @throws when the packet is not a parseable MMTP MPU packet
+ */
+export function recoveredPacketMediaGroup(packet: Uint8Array): number {
+  const header = parseMMTPHeader(packet)
+  if (header.packetType !== PACKET_TYPE_MPU) {
+    throw new Error(
+      `recovered packet is not an MPU packet (packet_type 0x${header.packetType.toString(16).padStart(2, "0")}); it has no media group`,
+    )
+  }
+  return parseMPUHeader(packet.subarray(header.headerLength)).mpuSequenceNumber
+}
+
+/**
+ * Module-private marker for the one mapper without an FEC instance. A stream
+ * with no FEC has no block profile, and only {@link NullBlockMapper} can say
+ * so: this symbol is not exported, so every other construction must name a
+ * profile.
+ */
+const NO_FEC_INSTANCE: unique symbol = Symbol("no FEC instance")
+
+/** The geometry NullBlockMapper hands the base class: no block profile. */
+interface NoFecInstanceConfig {
+  readonly interleaveDepthMs: number
+  readonly gopDurationMs: number
+  readonly k: number
+  readonly blockProfile: typeof NO_FEC_INSTANCE
+}
+
+/** Catalog FEC geometry and block profile for one FEC stream. */
+export class FecBlockMapper {
+  /** Media units (GOPs/frames) per FEC block, recovered with positive round-half-up semantics. */
+  readonly d: number
+  /** K: source symbols per block (`k-padded-v1`) or the maximum SSB_length (`iso-ssbg1-v1`). */
+  readonly k: number
+  /** Block time span (ms) — used as pacing threshold */
+  readonly interleaveDepthMs: number
+  /** GOP/frame duration (ms) */
+  readonly gopDurationMs: number
+  /**
+   * The stream's `fec.blockProfile`. `null` only for {@link NullBlockMapper}:
+   * a stream without an FEC instance has no block profile.
+   */
+  readonly blockProfile: FecBlockProfile | null
+
+  /**
+   * @param config - Catalog FEC geometry and block profile
+   * @throws when `k` is not positive, the block profile is absent or unknown,
+   *   or the timing cannot define D
+   */
+  constructor(config: FecBlockConfig | NoFecInstanceConfig) {
+    if (config.k <= 0) throw new Error('k must be > 0')
+    this.blockProfile = config.blockProfile === NO_FEC_INSTANCE
+      ? null
+      : parseFecBlockProfile(config.blockProfile, 'FecBlockConfig.blockProfile')
+    this.k = config.k
+    this.interleaveDepthMs = config.interleaveDepthMs
+    this.gopDurationMs = config.gopDurationMs
+    this.d = deriveFecInterleaveDepth(config.interleaveDepthMs, config.gopDurationMs)
+  }
+
+  /**
+   * The `k-padded-v1` locator: SS_ID → (SBN, ESI) with `SBN = floor(SS_ID / K)`
+   * and `ESI = SS_ID mod K`, for MMTP over multicast UDP where the Source FEC
+   * Payload ID carries SS_ID directly.
+   *
+   * @throws under `iso-ssbg1-v1`, where a block is located by
+   *   `(SS_Start, SSB_length)` range membership and never from SS_ID alone
+   */
+  fromSsId(ssId: number): { sbn: number; esi: number } {
+    if (this.blockProfile !== 'k-padded-v1') {
+      throw new Error(
+        `fromSsId is the k-padded-v1 locator; a ${this.blockProfile ?? 'non-FEC'} stream locates a block by ` +
+          '(SS_Start, SSB_length) range membership, never from SS_ID alone',
+      )
+    }
+    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
+  }
+
+  /**
+   * The media group of a recovered packet, from its own header; see
+   * {@link recoveredPacketMediaGroup}. Identical under every block profile.
+   */
+  mediaGroupOf(packet: Uint8Array): number {
+    return recoveredPacketMediaGroup(packet)
+  }
+}
+
+/**
+ * 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.
+ *
+ * A stream without an FEC instance names no `fec.blockProfile`, so this
+ * mapper carries none (`blockProfile === null`) and needs none to construct.
+ */
+export class NullBlockMapper extends FecBlockMapper {
+  /** @param gopDurationMs - GOP/frame duration (ms), from catalog framerate or sampleRate */
+  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, blockProfile: NO_FEC_INSTANCE })
+  }
+
+  /** Every group is its own single-symbol block: SBN = group, ESI = object, SS_ID = group. */
+  derive(groupId: number, objectId: number): FecCoordinates {
+    return {
+      sbn: groupId,
+      esi: objectId,
+      ssId: groupId,
+    }
+  }
+
+  /** The inverse of {@link NullBlockMapper.derive}: every SS_ID is its own one-symbol block. */
+  override fromSsId(ssId: number): { sbn: number; esi: number } {
+    return { sbn: ssId, esi: 0 }
+  }
+
+  /** No FEC: nothing to wait for, so pacing never sleeps. */
+  override 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).
+ *
+ * That SS_ID is the K-stride numbering of `k-padded-v1`; `iso-ssbg1-v1`
+ * numbers SS_IDs consecutively per source packet (ISO/IEC 23008-1 C.5.2), so
+ * §9.1 object FEC is defined only under `k-padded-v1` and the constructor
+ * refuses any other profile.
+ *
+ * The stride of that numbering is the catalog `sourceSymbols`, never a
+ * block's own K: a short block (K_actual < sourceSymbols) still starts at
+ * `Group_ID * sourceSymbols` (its repair's SS_Start) and leaves the rest of
+ * its stride unused, which is exactly `k-padded-v1` with `SSB_length =
+ * K_actual`. So the SS_ID locator is the inherited
+ * {@link FecBlockMapper.fromSsId} over `k = sourceSymbols`, the exact inverse
+ * of {@link ObjectBlockMapper.derive}; it needs no per-block K and infers
+ * nothing.
+ *
+ * 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: SSB_length in the Repair FEC Payload ID (ISO 23008-1 C.5.3)
+ *
+ * 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
+
+  /**
+   * @param gopDurationMs - GOP/frame duration (ms)
+   * @param sourceSymbolsMax - Catalog `fec.sourceSymbols`
+   * @param blockProfile - Catalog `fec.blockProfile`; must be `k-padded-v1`
+   */
+  constructor(gopDurationMs: number, sourceSymbolsMax: number, blockProfile: FecBlockProfile) {
+    if (sourceSymbolsMax <= 0) throw new Error('ObjectBlockMapper: sourceSymbolsMax must be > 0 (from catalog)')
+    const profile = parseFecBlockProfile(blockProfile, 'ObjectBlockMapper fec.blockProfile')
+    if (profile !== 'k-padded-v1') {
+      throw new Error(
+        `ObjectBlockMapper: §9.1 object FEC numbers SS_ID = Group_ID * K + Object_ID, the k-padded-v1 stride; ` +
+          `it is not defined under ${profile}`,
+      )
+    }
+    // D=1, K=sourceSymbolsMax for SS_ID math only — actual block K varies
+    super({ interleaveDepthMs: gopDurationMs, gopDurationMs, k: sourceSymbolsMax, blockProfile: profile })
+    this.sourceSymbolsMax = sourceSymbolsMax
+  }
+
+  /**
+   * SBN = group_id, ESI = object_id. SS_ID per §9.1.2. Its inverse is the
+   * inherited `fromSsId` (SBN = floor(SS_ID / sourceSymbols), ESI = SS_ID mod
+   * sourceSymbols).
+   */
+  derive(groupId: number, objectId: number): FecCoordinates {
+    return {
+      sbn: groupId,
+      esi: objectId,
+      ssId: groupId * this.sourceSymbolsMax + objectId,
+    }
+  }
+
+  /** One frame of latency: each frame is its own block. */
+  override get pacingThresholdMs(): number {
+    return this.gopDurationMs // one frame latency
+  }
+}
+
+/**
+ * Create a FecBlockMapper from catalog FEC config + measured GOP duration.
+ *
+ * - No FEC instance (`fecConfig` absent or no `sourceSymbols`) →
+ *   {@link NullBlockMapper}; `fec.blockProfile` is not read, since a stream
+ *   without FEC names none.
+ * - Otherwise `fec.blockProfile` is required (validated with
+ *   `parseFecBlockProfile`, throwing when absent or unknown), and
+ *   `mode: 'object'` → {@link ObjectBlockMapper}, else {@link FecBlockMapper}.
+ */
+export function createMapper(
+  fecConfig: {
+    interleaveDepthMs?: number
+    sourceSymbols?: number
+    mode?: string
+    /** Catalog `fec.blockProfile`; required whenever `sourceSymbols` is declared. */
+    blockProfile?: unknown
+  } | undefined,
+  gopDurationMs: number,
+): FecBlockMapper {
+  if (!fecConfig || !fecConfig.sourceSymbols) {
+    return new NullBlockMapper(gopDurationMs)
+  }
+  const blockProfile = parseFecBlockProfile(fecConfig.blockProfile, 'fec.blockProfile')
+  // extensions feature — see moqcast-draft docs/fec-extensions-material.md, not in public -00
+  if (fecConfig.mode === 'object') {
+    return new ObjectBlockMapper(gopDurationMs, fecConfig.sourceSymbols, blockProfile)
+  }
+  return new FecBlockMapper({
+    interleaveDepthMs: fecConfig.interleaveDepthMs && fecConfig.interleaveDepthMs > 0
+      ? fecConfig.interleaveDepthMs
+      : gopDurationMs,
+    gopDurationMs,
+    k: fecConfig.sourceSymbols,
+    blockProfile,
+  })
+}

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

@@ -0,0 +1,94 @@
+/**
+ * @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 ProcessFecBlockOptions,
+	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,
+	deriveFecRetentionBlocks,
+	tryDeriveFecRetentionBlocks,
+	MAX_FEC_RETENTION_BLOCKS,
+	playbackLatencyMs,
+} from "./oti.js";
+
+export {
+	FecBlockMapper,
+	NullBlockMapper,
+	ObjectBlockMapper,
+	createMapper,
+	recoveredPacketMediaGroup,
+	type FecBlockConfig,
+	type FecCoordinates,
+} from "./fec-block-mapper.js";
+
+/**
+ * MoQ repair group ids for `iso-ssbg1-v1` blocks: the 62-bit
+ * wrap-epoch-extended SS_Start, the repair FETCH range for a lost SS_ID, and
+ * the check a received repair object's Group ID must pass.
+ */
+export {
+	extSsStart,
+	extendSsId,
+	repairFetchRange,
+	repairGroupIdMatches,
+	type RepairFetchAnchor,
+	type RepairFetchRange,
+} from "./repair-group.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);
+}