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

package/src/fec-starvation-detector.ts

@@ -0,0 +1,128 @@
+/**
+ * FecStarvationDetector — post-cutover source-starvation detection (BLO-9413/D4).
+ *
+ * The packet-presence watchdog (MulticastTransport, 5s) only catches TOTAL
+ * silence: any packet — including FEC repair — resets it. The observed
+ * BLO-9413 failure delivered repair symbols continuously while ZERO source
+ * symbols arrived (`sourceSymbols:0, repairSymbols:551, blocksComplete:0`):
+ * the watchdog stayed fed forever while nothing reconstructable reached the
+ * decoder. This detector closes that hole by watching delivery progress and
+ * driving the designed-but-previously-uncalled TrackSession loss arcs:
+ *
+ *   starvation sustained ≥ windowMs → onStarvation()  → session.lossDetected()
+ *   block progress resumes          → onRecovery()    → session.lossRecovered()
+ *
+ * TrackSession's own FEC block-span hysteresis then decides whether a recovery
+ * cancels the failback — this detector deliberately does NOT add a second
+ * hysteresis layer.
+ *
+ * Push-fed: call update() with each FecTrackStats-shaped snapshot (e.g. from
+ * MulticastManager.setOnFecStatsUpdate or a host sampler). Hosts that can also
+ * observe decoded/appended media should include a monotonic mediaFrames count:
+ * media progress is delivery progress even if sparse FEC block counters do not
+ * advance in the same sample window. Evaluation happens only on update — a
+ * fully dead transport stops producing updates and stays the transport
+ * watchdog's responsibility (total-silence backstop).
+ */
+
+/** Monotonic counters sampled from the FEC layer (FecTrackStats subset). */
+export interface FecStarvationSnapshot {
+  sourceSymbols: number
+  repairSymbols: number
+  blocksComplete: number
+  blocksRecovered: number
+  /** Optional host-observed decoded/appended media frames for this packetId. */
+  mediaFrames?: number
+}
+
+export interface FecStarvationDetectorConfig {
+  /**
+   * How long starvation must persist before onStarvation fires. Derive from
+   * the stream's FEC block-span config — no magic defaults, matching the
+   * TrackSession hysteresis convention.
+   */
+  windowMs: number
+  /** Starvation sustained ≥ windowMs. Fires once per starvation episode. */
+  onStarvation(): void
+  /** Healthy delivery resumed after onStarvation fired. Fires once per episode. */
+  onRecovery(): void
+  /** Injectable clock for tests. Defaults to Date.now. */
+  now?: () => number
+}
+
+export class FecStarvationDetector {
+  #config: FecStarvationDetectorConfig
+  #now: () => number
+  #last: FecStarvationSnapshot | null = null
+  #lastSampleAt = 0
+  #starvedSince: number | null = null
+  #latched = false
+
+  constructor(config: FecStarvationDetectorConfig) {
+    if (config.windowMs <= 0) {
+      throw new Error(
+        `[FecStarvationDetector] windowMs=${config.windowMs}. Derive a positive window ` +
+        `from the stream's FEC block-span config — a non-positive ` +
+        `window would fire on the first repair packet of a healthy stream.`
+      )
+    }
+    this.#config = config
+    this.#now = config.now ?? Date.now
+  }
+
+  /** True while a starvation episode is active (onStarvation fired, no recovery yet). */
+  get isStarved(): boolean { return this.#latched }
+
+  update(snapshot: FecStarvationSnapshot): void {
+    const last = this.#last
+    const prevSampleAt = this.#lastSampleAt
+    const now = this.#now()
+    this.#last = { ...snapshot }
+    this.#lastSampleAt = now
+    if (last === null) return // first sample = baseline only
+
+    const srcDelta = snapshot.sourceSymbols - last.sourceSymbols
+    const repDelta = snapshot.repairSymbols - last.repairSymbols
+    const doneDelta =
+      (snapshot.blocksComplete - last.blocksComplete) +
+      (snapshot.blocksRecovered - last.blocksRecovered)
+    const mediaDelta = (snapshot.mediaFrames ?? 0) - (last.mediaFrames ?? 0)
+
+    const packetsFlowing = srcDelta > 0 || repDelta > 0
+    if (!packetsFlowing && mediaDelta <= 0) return // total silence — transport watchdog's domain
+
+    // Starving: traffic arrives but nothing reconstructable comes out. Source
+    // and repair symbols arrive at symbol cadence while complete/recovered
+    // blocks arrive at block cadence; requiring source and block deltas in the
+    // same snapshot false-fails healthy live streams. A repaired block is still
+    // decodable media, and host-observed frame progress is even stronger
+    // evidence, so either resets the starvation clock.
+    const starving = doneDelta === 0 && mediaDelta <= 0
+
+    if (starving) {
+      // The episode began when delivery was last known healthy — the previous
+      // sample's timestamp, not this sample's arrival (the deltas in THIS
+      // sample describe the interval since then).
+      if (this.#starvedSince === null) this.#starvedSince = prevSampleAt
+      if (!this.#latched && now - this.#starvedSince >= this.#config.windowMs) {
+        this.#latched = true
+        this.#config.onStarvation()
+      }
+      return
+    }
+
+    // Healthy sample: completed or recovered blocks are reaching the decoder.
+    this.#starvedSince = null
+    if (this.#latched) {
+      this.#latched = false
+      this.#config.onRecovery()
+    }
+  }
+
+  /** Reset episode state (e.g. on transport switch / re-join). Keeps no baseline. */
+  reset(): void {
+    this.#last = null
+    this.#starvedSince = null
+    this.#latched = false
+  }
+}

package/src/fec-worker-setup.ts

@@ -0,0 +1,177 @@
+/**
+ * Shared fec-setup helper.
+ *
+ * Wires a FecWorkerClient into a MulticastManager for a specific track.
+ * Both moq-lib (`hang-mmt-fec/js/watch/src/element.ts`) and moqtail
+ * (`moqtail-private/apps/client-js/src/lib/player.ts`) call this from their
+ * SessionManager `fec-setup` handler so the Worker+ALTA setup lives in one
+ * place instead of being duplicated across ~80 lines per player.
+ *
+ * Callers are responsible for holding the returned `dispose()` and calling it
+ * from their `fec-teardown` path (and/or effect cleanup).
+ */
+
+import type { FecWorkerClient, FecTrackConfig } from '@blockcast/fec-worker'
+import { deriveFecInterleaveDepth } from '@blockcast/mmt-fec'
+import type { MulticastManager } from './multicast-manager.js'
+import { computeFecDeliveryWindowMs } from './track-session.js'
+
+/** Asset URLs the helper needs. Callers pass the already-resolved set. */
+export interface FecWorkerAssetUrls {
+  /** URL to the fec-worker entry bundle (new Worker() target). */
+  fecWorker: string
+  /** URL to the RaptorQ WASM module (compiled via compileStreaming). */
+  rqWasm: string
+  /** URL to the ALTA WASM module. Fetched only when an ALTA key is provided. */
+  altaWasm: string
+}
+
+export interface FecWorkerSetupOptions {
+  /** MulticastManager that should receive the configured Worker. */
+  multicastManager: MulticastManager
+  /** MMTP packetId this track occupies (from catalog). */
+  packetId: number
+  /** Human-readable track name (catalog key). */
+  trackName: string
+  /** Track type from catalog. Never inferred from name. */
+  trackType: 'video' | 'audio'
+  /** FEC K from catalog (source symbols per block). */
+  fecK: number
+  /** Symbol size in bytes (T) — the ALTA-adjusted value if ALTA is signed. */
+  fecSymbolSize: number
+  /** Repair symbols per block (P). */
+  fecRepairCount: number
+  /** Interleave depth in ms. */
+  fecInterleaveMs: number
+  /** Duration of one FEC media unit in ms (video frame or audio access unit). */
+  mediaUnitDurationMs: number
+  /** Optional repair track name (MoQ). Forwarded to FecTrackConfig. */
+  repairTrackName?: string
+  /** Audio sample rate (optional — audio tracks only). */
+  sampleRate?: number
+  /** Codec string (optional; "unknown" is acceptable for first setup). */
+  codec?: string
+  /** Video framerate (optional metadata forwarded to the worker). */
+  framerate?: number
+  /** Base64 SPKI public key (optional). Accepts padded/unpadded, std or url-safe alphabet. */
+  altaPublicKeySpki?: string
+  /** Absolute or origin-relative asset URLs. */
+  assetUrls: FecWorkerAssetUrls
+  /** Optional FecWorkerClient factory — main use is test injection. */
+  clientFactory?: (workerUrl: URL) => FecWorkerClient
+}
+
+export interface FecWorkerSetupResult {
+  /** The configured client (already registered with MulticastManager). */
+  client: FecWorkerClient
+  /** True when the ALTA public key decoded and the ALTA WASM compiled. */
+  altaEnabled: boolean
+  /** Releases the Worker and removes it from MulticastManager routing. */
+  dispose: () => void
+}
+
+/**
+ * Configure a FecWorkerClient and attach it to `multicastManager` via
+ * `setFecWorker(packetId, client, trackType, config, trackName)`. Worker-path takes precedence
+ * over any sync WASM decoder already registered for the same packetId —
+ * sync decoders remain as a fallback.
+ *
+ * Any loader failure is re-thrown so the caller can log and leave the sync
+ * WASM decoder active as fallback (same pattern both players used before).
+ */
+export async function setupFecWorkerForTrack(
+  opts: FecWorkerSetupOptions,
+): Promise<FecWorkerSetupResult> {
+  const interleaveDepthBlocks = deriveFecInterleaveDepth(
+    opts.fecInterleaveMs,
+    opts.mediaUnitDurationMs,
+  )
+  const deliveryWindowMs = computeFecDeliveryWindowMs({
+    interleaveDepthMs: opts.fecInterleaveMs,
+    sourceSymbols: opts.fecK,
+    repairSymbols: opts.fecRepairCount,
+    symbolSize: opts.fecSymbolSize,
+    mediaUnitsPerSecond: 1000 / opts.mediaUnitDurationMs,
+  })
+  // Resolve URL against location.origin when available (browser runtime).
+  // Absolute URLs pass through unchanged per the URL() spec.
+  const origin =
+    typeof location !== 'undefined' && location.origin ? location.origin : 'http://localhost'
+  const workerUrl = new URL(opts.assetUrls.fecWorker, origin)
+
+  const FecWorkerCtor = await import('@blockcast/fec-worker')
+  const client = opts.clientFactory
+    ? opts.clientFactory(workerUrl)
+    : new FecWorkerCtor.FecWorkerClient(workerUrl)
+
+  // Compile RaptorQ WASM once; ALTA WASM only when we have a key to decode.
+  const rqWasm = await WebAssembly.compileStreaming(fetch(opts.assetUrls.rqWasm))
+
+  let altaKeyBuffer: ArrayBuffer | undefined
+  let altaWasmModule: WebAssembly.Module | undefined
+  if (opts.altaPublicKeySpki) {
+    const b64 = opts.altaPublicKeySpki.replace(/-/g, '+').replace(/_/g, '/')
+    const padded = b64.padEnd(Math.ceil(b64.length / 4) * 4, '=')
+    try {
+      const keyBytes = Uint8Array.from(atob(padded), c => c.charCodeAt(0))
+      // SPKI size range: Ed25519=44, P-256=91; tolerate 32..=256 for forward-compat.
+      if (keyBytes.length >= 32 && keyBytes.length <= 256) {
+        altaKeyBuffer = keyBytes.buffer
+        altaWasmModule = await WebAssembly.compileStreaming(fetch(opts.assetUrls.altaWasm))
+      } else {
+        console.warn(
+          `[fec-worker-setup] ALTA SPKI wrong length for "${opts.trackName}": ` +
+            `${keyBytes.length} (expected 32..256) — ALTA disabled`,
+        )
+      }
+    } catch (e) {
+      console.warn(`[fec-worker-setup] ALTA key decode / WASM compile failed for "${opts.trackName}":`, e)
+    }
+  }
+
+  const altaEnabled = !!(altaKeyBuffer && altaWasmModule)
+  const fecTrackConfig = {
+    codec: opts.codec ?? 'unknown',
+    trackName: opts.trackName,
+    trackType: opts.trackType,
+    framerate: opts.framerate,
+    sampleRate: opts.sampleRate,
+    algorithm: 'raptor',
+    k: opts.fecK,
+    repairCount: opts.fecRepairCount,
+    symbolSize: opts.fecSymbolSize,
+    interleaveDepth: interleaveDepthBlocks,
+    interleaveMs: opts.fecInterleaveMs,
+    deliveryWindowMs,
+    fecMode: 'subframe' as const,
+    repairTrack: opts.repairTrackName,
+    altaEnabled,
+    relayBlockSigEnabled: false,
+  } as unknown as FecTrackConfig
+
+  client.configure(fecTrackConfig, rqWasm, altaKeyBuffer, altaWasmModule)
+  opts.multicastManager.setFecWorker(opts.packetId, client, opts.trackType, {
+    k: opts.fecK,
+    symbolSize: opts.fecSymbolSize,
+    interleaveDepthMs: opts.fecInterleaveMs,
+    // FEC timing is expressed in media units. For audio this is the access-unit
+    // cadence (for example 1024/48kHz), not a video-only framerate field.
+    fps: 1000 / opts.mediaUnitDurationMs,
+    timeoutMs: deliveryWindowMs,
+  }, opts.trackName)
+
+  let disposed = false
+  return {
+    client,
+    altaEnabled,
+    dispose: () => {
+      if (disposed) return
+      disposed = true
+      try {
+        client.dispose()
+      } catch {
+        /* dispose errors are non-fatal */
+      }
+    },
+  }
+}

package/src/fmp4-completion.ts

@@ -0,0 +1,47 @@
+/**
+ * fMP4 data-unit completion policy (BLO-13291).
+ *
+ * FFmpeg's `mmt` muxer in fMP4-fragments mode (mfu_mode=0, mmtenc_fmp4.c
+ * send_media_fragment) delivers one complete moof+mdat (optionally
+ * sidx-prefixed) per MPU data unit, split across FI=1/2/3 MMTP fragments.
+ * Neither wire counter can prove the chain is byte-complete:
+ *
+ * - MPU payload header byte 3 is the eight-bit fragment counter. It proves
+ *   ordering, but cannot declare the total byte length of a fragmented DU.
+ * - Each fragment's payload_length bounds that packet only; it does not declare
+ *   the total size of the multi-packet fMP4 data unit.
+ * - packet_sequence_number has legitimate gaps: repair and signaling packets
+ *   consume sequence slots in the same flow at every FEC block boundary.
+ *
+ * The data unit is self-describing instead: ISOBMFF top-level box headers
+ * declare their 32-bit sizes. A candidate assembly is complete exactly when
+ * it parses as a whole number of known top-level boxes covering its full
+ * length. Any interior hole shifts subsequent box headers (type/size garbage)
+ * or leaves a declared size overrunning the buffer; missing tail bytes leave
+ * the final box short.
+ */
+
+/** Top-level box types the MMT fMP4 writers emit around a data unit. */
+const TOP_LEVEL_BOX_TYPES = new Set(['ftyp', 'styp', 'moov', 'moof', 'mdat', 'sidx', 'free', 'skip', 'prft', 'emsg'])
+
+/**
+ * True when `candidate` parses as one or more complete top-level ISOBMFF
+ * boxes covering exactly its byte length. size==0 ("to end of file") and
+ * size==1 (64-bit largesize) are treated as unverifiable and return false —
+ * the MMT muxers never emit them for streamed data units.
+ */
+export function isCompleteFmp4DataUnit(candidate: Uint8Array): boolean {
+  if (candidate.length < 8) return false
+  const dv = new DataView(candidate.buffer, candidate.byteOffset, candidate.byteLength)
+  let pos = 0
+  while (pos < candidate.length) {
+    if (pos + 8 > candidate.length) return false
+    const size = dv.getUint32(pos)
+    if (size < 8) return false
+    const type = String.fromCharCode(candidate[pos + 4]!, candidate[pos + 5]!, candidate[pos + 6]!, candidate[pos + 7]!)
+    if (!TOP_LEVEL_BOX_TYPES.has(type)) return false
+    if (pos + size > candidate.length) return false
+    pos += size
+  }
+  return pos === candidate.length
+}

package/src/fmp4-reader.ts

@@ -0,0 +1,112 @@
+/**
+ * Minimal ISOBMFF box reader. NOT a full MP4 parser — just enough to walk
+ * the box tree and pull out fields that libmmt's fMP4 writers emit.
+ * Used by unit tests; not part of the runtime pipeline.
+ */
+
+export type Box = {
+  type: string
+  start: number
+  end: number
+  payloadStart: number
+}
+
+export function walkBoxes(data: Uint8Array, start = 0, end = data.length): Box[] {
+  const out: Box[] = []
+  const dv = new DataView(data.buffer, data.byteOffset, data.byteLength)
+  let pos = start
+  while (pos + 8 <= end) {
+    const size = dv.getUint32(pos)
+    const type = String.fromCharCode(data[pos + 4], data[pos + 5], data[pos + 6], data[pos + 7])
+    if (size < 8 || pos + size > end) break
+    out.push({ type, start: pos, end: pos + size, payloadStart: pos + 8 })
+    pos += size
+  }
+  return out
+}
+
+export function findBox(boxes: Box[], type: string): Box | undefined {
+  return boxes.find(b => b.type === type)
+}
+
+export function childrenOf(data: Uint8Array, box: Box): Box[] {
+  return walkBoxes(data, box.payloadStart, box.end)
+}
+
+export function readFullBox(data: Uint8Array, box: Box): { version: number; flags: number; bodyStart: number } {
+  const dv = new DataView(data.buffer, data.byteOffset, data.byteLength)
+  const verFlags = dv.getUint32(box.payloadStart)
+  return { version: verFlags >>> 24, flags: verFlags & 0xffffff, bodyStart: box.payloadStart + 4 }
+}
+
+export function readTfdtBaseMediaDecodeTime(segment: Uint8Array): number {
+  const moof = findBox(walkBoxes(segment), 'moof')!
+  const traf = findBox(childrenOf(segment, moof), 'traf')!
+  const tfdt = findBox(childrenOf(segment, traf), 'tfdt')!
+  const { version, bodyStart } = readFullBox(segment, tfdt)
+  const dv = new DataView(segment.buffer, segment.byteOffset, segment.byteLength)
+  if (version === 1) {
+    const hi = dv.getUint32(bodyStart)
+    const lo = dv.getUint32(bodyStart + 4)
+    return hi * 0x100000000 + lo
+  }
+  return dv.getUint32(bodyStart)
+}
+
+export type TrunSample = {
+  duration: number
+  size: number
+  flags: number
+  compositionTimeOffset: number
+}
+export type TrunInfo = {
+  version: number
+  flags: number
+  sampleCount: number
+  dataOffset: number
+  samples: TrunSample[]
+}
+
+export function readTrun(segment: Uint8Array): TrunInfo {
+  const moof = findBox(walkBoxes(segment), 'moof')!
+  const traf = findBox(childrenOf(segment, moof), 'traf')!
+  const trun = findBox(childrenOf(segment, traf), 'trun')!
+  const { version, flags, bodyStart } = readFullBox(segment, trun)
+  const dv = new DataView(segment.buffer, segment.byteOffset, segment.byteLength)
+  const sampleCount = dv.getUint32(bodyStart)
+  let cursor = bodyStart + 4
+  let dataOffset = 0
+  if (flags & 0x000001) { dataOffset = dv.getInt32(cursor); cursor += 4 }
+  const hasDuration = !!(flags & 0x000100)
+  const hasSize = !!(flags & 0x000200)
+  const hasFlags = !!(flags & 0x000400)
+  const hasCompositionTimeOffset = !!(flags & 0x000800)
+  const samples: TrunSample[] = []
+  for (let i = 0; i < sampleCount; i++) {
+    const s: TrunSample = { duration: 0, size: 0, flags: 0, compositionTimeOffset: 0 }
+    if (hasDuration) { s.duration = dv.getUint32(cursor); cursor += 4 }
+    if (hasSize) { s.size = dv.getUint32(cursor); cursor += 4 }
+    if (hasFlags) { s.flags = dv.getUint32(cursor); cursor += 4 }
+    if (hasCompositionTimeOffset) {
+      s.compositionTimeOffset = version === 1
+        ? dv.getInt32(cursor)
+        : dv.getUint32(cursor)
+      cursor += 4
+    }
+    samples.push(s)
+  }
+  return { version, flags, sampleCount, dataOffset, samples }
+}
+
+export function readMfhdSequence(segment: Uint8Array): number {
+  const moof = findBox(walkBoxes(segment), 'moof')!
+  const mfhd = findBox(childrenOf(segment, moof), 'mfhd')!
+  const { bodyStart } = readFullBox(segment, mfhd)
+  const dv = new DataView(segment.buffer, segment.byteOffset, segment.byteLength)
+  return dv.getUint32(bodyStart)
+}
+
+export function readMdatSize(segment: Uint8Array): number {
+  const mdat = findBox(walkBoxes(segment), 'mdat')!
+  return mdat.end - mdat.payloadStart
+}