@blockcast/mmt-container 0.3.0 → 0.4.0-main.d6f2737828fc

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

@@ -1,310 +0,0 @@
-/**
- * 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

@@ -1,94 +0,0 @@
-/**
- * @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

@@ -1,34 +0,0 @@
-/**
- * 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);
-}