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

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

@@ -0,0 +1,277 @@
+/**
+ * FEC Block Processor
+ *
+ * Splits decoded FEC blocks (K symbols concatenated by WASM RaptorQ decoder)
+ * into individual MFU fragments ready for reassembly and decoding.
+ *
+ * Extracted from moqtail.html's inline processFecBlock() for reuse across
+ * both moq-lib and moqtail players. Pure function — no side effects.
+ */
+
+import {
+	MMTP_EXT_TRAILER_HEADER_SIZE,
+	MMTP_EXT_TYPE_ALTA_AUTH,
+	MMTP_HEADER_SIZE,
+	MPU_HEADER_SIZE,
+	extractMFUPayload,
+	parseMPUHeader,
+	parseMMTPHeader,
+} from "@blockcast/mmt-base";
+
+/** A single parsed symbol from a decoded FEC block */
+export interface ParsedFecSymbol {
+	/** Symbol index within the block (0..K-1) */
+	index: number;
+	/** MMTP packet ID (1=video, 2=audio) */
+	packetId: number;
+	/** MMTP packet sequence number (for dedup across delivery paths) */
+	packetSequenceNumber: number;
+	/** MPU fragment_type: 0=init (ftyp+moov), 2=MFU data */
+	fragmentType: number;
+	/** MFU fragment ready for MFUReassembler.addFragment() */
+	fragment: {
+		mpuSequenceNumber: number;
+		fragmentationIndicator: number;
+		fragmentCounter: number;
+		data: Uint8Array;
+		timestamp: bigint;
+		rapFlag: boolean;
+		priority?: number;
+		sampleNumber?: number;
+		movieFragmentSequenceNumber?: number;
+		sampleOffset?: number;
+		itemId?: number;
+	};
+	/** Whether this symbol carries keyframe metadata (RAP or high MFU priority). */
+	isKeyframe: boolean;
+	/** Raw symbol data (needed for audio decode path) */
+	rawSymbol: Uint8Array;
+}
+
+/** Result of processing a decoded FEC block */
+export interface ProcessFecBlockResult {
+	/** All valid parsed symbols for the owning track, sorted by serial packet sequence. */
+	symbols: ParsedFecSymbol[];
+	/** Count of symbols that failed to parse */
+	failedCount: number;
+	/** Failure reasons keyed by category */
+	failReasons: Record<string, number>;
+}
+
+export interface ProcessFecSymbolOptions {
+	/** Symbol index within the block, used only for diagnostics. */
+	index?: number;
+	/** Keep only symbols for this packetId. */
+	ownerPacketId?: number;
+}
+
+function hasUniformPaddingFrom(data: Uint8Array, start: number): boolean {
+	if (start >= data.length) return false;
+	const pad = data[start]!;
+	if (pad !== 0x00 && pad !== 0xee) return false;
+	for (let i = start + 1; i < data.length; i++) {
+		if (data[i] !== pad) return false;
+	}
+	return true;
+}
+
+function maybeExtendAltaTrailer(symbolData: Uint8Array, packetEnd: number): number {
+	if (packetEnd + MMTP_EXT_TRAILER_HEADER_SIZE > symbolData.length) return packetEnd;
+	const view = new DataView(
+		symbolData.buffer,
+		symbolData.byteOffset + packetEnd,
+		symbolData.byteLength - packetEnd,
+	);
+	const extType = view.getUint16(0, false);
+	if (extType !== MMTP_EXT_TYPE_ALTA_AUTH) return packetEnd;
+
+	const extLen = view.getUint16(2, false);
+	const trailerEnd = packetEnd + MMTP_EXT_TRAILER_HEADER_SIZE + extLen;
+	return trailerEnd <= symbolData.length ? trailerEnd : packetEnd;
+}
+
+function trimDecodedSourceSymbol(symbolData: Uint8Array): Uint8Array | null {
+	if (symbolData.length < MMTP_HEADER_SIZE + MPU_HEADER_SIZE) return null;
+
+	const headerLength = parseMMTPHeader(symbolData).headerLength;
+	if (symbolData.length < headerLength + MPU_HEADER_SIZE) return null;
+	const payload = symbolData.subarray(headerLength);
+	const mpu = parseMPUHeader(payload);
+	const trailingMpuHeaderSize = MPU_HEADER_SIZE - 2;
+	if (mpu.payloadLength < trailingMpuHeaderSize) return null;
+
+	// Recovered source symbols are fixed-width and may be padded, but their wire
+	// boundary is still the ISO length-after-field coordinate. ALTA may extend the
+	// packet from exactly that point; no MFU-content or alternate-length guessing.
+	const declaredEnd = headerLength + 2 + mpu.payloadLength;
+	if (declaredEnd > symbolData.length) return null;
+	const packetEnd = maybeExtendAltaTrailer(symbolData, declaredEnd);
+	if (packetEnd < symbolData.length && !hasUniformPaddingFrom(symbolData, packetEnd)) {
+		return null;
+	}
+	return symbolData.subarray(0, packetEnd);
+}
+
+function emptyProcessResult(): ProcessFecBlockResult {
+	return {
+		symbols: [],
+		failedCount: 0,
+		failReasons: {},
+	};
+}
+
+function isMfuKeyframeMetadata(rapFlag: boolean, priority?: number): boolean {
+	return rapFlag || (priority ?? 0) > 0x80;
+}
+
+function comparePacketSequence(a: ParsedFecSymbol, b: ParsedFecSymbol): number {
+	// MMTP packet_sequence_number is a wrapping u32. A recovered FEC block spans
+	// far less than half the serial-number space, so the signed low 32 bits give
+	// its authored order across 0xffff_ffff -> 0. Index makes duplicate sequence
+	// values deterministic without relying on Array#sort stability.
+	const serialDelta = (a.packetSequenceNumber - b.packetSequenceNumber) | 0;
+	return serialDelta !== 0 ? serialDelta : a.index - b.index;
+}
+
+function resultFromSymbols(
+	parsed: ParsedFecSymbol[],
+	failedCount: number,
+	failReasons: Record<string, number>,
+	ownerPacketId?: number,
+): ProcessFecBlockResult {
+	// Sort by wrapping packetSequenceNumber to fix FEC interleaving scramble.
+	// Reassembler needs FI=1 before FI=2/3 for the same mpuSequenceNumber.
+	parsed.sort(comparePacketSequence);
+
+	// When ownerPacketId is set, only keep symbols matching the track that owns
+	// this FEC block. Other packetIds (including 0 from zero-padded recovery slots)
+	// are garbage and must be rejected to prevent decoder crashes.
+	const symbols = ownerPacketId != null
+		? parsed.filter((s) => s.packetId === ownerPacketId)
+		: parsed;
+
+	return { symbols, failedCount, failReasons };
+}
+
+export function processFecSymbol(
+	symbolData: Uint8Array,
+	options?: ProcessFecSymbolOptions,
+): ProcessFecBlockResult {
+	const failReasons: Record<string, number> = {};
+	let failedCount = 0;
+	const bump = (reason: string) => {
+		failedCount++;
+		failReasons[reason] = (failReasons[reason] ?? 0) + 1;
+	};
+
+	if (!symbolData || symbolData.length === 0) return emptyProcessResult();
+	if (symbolData.length < MMTP_HEADER_SIZE) {
+		bump("too_short");
+		return resultFromSymbols([], failedCount, failReasons, options?.ownerPacketId);
+	}
+	if (((symbolData[0]! >> 6) & 0x03) !== 0) {
+		bump("bad_hdr");
+		return resultFromSymbols([], failedCount, failReasons, options?.ownerPacketId);
+	}
+
+	try {
+		const hdr = parseMMTPHeader(symbolData);
+		// Only process MPU packets (packetType=0x00). Skip signaling/repair
+		// that may appear in the block due to FEC interleaving.
+		if ((hdr.packetType & 0x0f) !== 0x00) {
+			bump(`type_0x${hdr.packetType.toString(16)}`);
+			return resultFromSymbols([], failedCount, failReasons, options?.ownerPacketId);
+		}
+
+		const packetData = trimDecodedSourceSymbol(symbolData);
+		if (!packetData) {
+			bump("bad_length");
+			return resultFromSymbols([], failedCount, failReasons, options?.ownerPacketId);
+		}
+
+		// WASM-decoded source symbols retain fecType bits from the original FFmpeg
+		// packet (fecType=1 per draft-ramadan-moq-mmt-00 §3.1), but the 4-byte
+		// Source FEC Payload ID (ISO 23008-1 §C.5.2) was stripped before feeding
+		// to add_source(). Tell extractMFUPayload to skip FEC PID subtraction so it
+		// does not truncate video data.
+		const extraction = extractMFUPayload(packetData, { skipFecId: true });
+		if (!extraction) {
+			bump("extract_fail");
+			return resultFromSymbols([], failedCount, failReasons, options?.ownerPacketId);
+		}
+		const sym: ParsedFecSymbol = {
+			index: options?.index ?? 0,
+			packetId: hdr.packetId,
+			packetSequenceNumber: hdr.sequenceNumber,
+			fragmentType: extraction.fragmentType,
+			fragment: {
+				mpuSequenceNumber: extraction.mpu.mpuSequenceNumber,
+				fragmentationIndicator: extraction.mpu.fragmentationIndicator,
+				fragmentCounter: extraction.mpu.fragmentCounter,
+				data: extraction.data,
+				timestamp: hdr.timestamp,
+				rapFlag: hdr.rapFlag,
+				priority: extraction.mfuDuHeader?.priority,
+				sampleNumber: extraction.mfuDuHeader?.sampleNumber,
+				movieFragmentSequenceNumber: extraction.mfuDuHeader?.movieFragmentSequenceNumber,
+				sampleOffset: extraction.mfuDuHeader?.offset,
+				itemId: extraction.itemId ?? undefined,
+			},
+			isKeyframe: isMfuKeyframeMetadata(
+				hdr.rapFlag,
+				extraction.mfuDuHeader?.priority,
+			),
+			rawSymbol: packetData,
+		};
+
+		return resultFromSymbols([sym], failedCount, failReasons, options?.ownerPacketId);
+	} catch {
+		bump("exception");
+		return resultFromSymbols([], failedCount, failReasons, options?.ownerPacketId);
+	}
+}
+
+/**
+ * Process a decoded FEC block into individual MFU fragments.
+ *
+ * The WASM RaptorQ decoder returns ALL K source symbols concatenated
+ * (K x symbolSize bytes). This function splits them apart, parses
+ * each MMTP header, extracts MFU payload via shared extractMFUPayload,
+ * and returns structured results sorted for reassembly.
+ *
+ * @param blockData - Concatenated K source symbols from WASM decoder
+ * @param options.k - Number of source symbols (derived from blockData.length / symbolSize if omitted)
+ * @param options.symbolSize - Symbol size in bytes (default 1320)
+ */
+export function processFecBlock(
+	blockData: Uint8Array,
+	options?: { k?: number; symbolSize?: number; ownerPacketId?: number },
+): ProcessFecBlockResult {
+	const empty = emptyProcessResult();
+
+	if (!blockData || blockData.length === 0) return empty;
+
+	const symbolSize = options?.symbolSize ?? 1320;
+	const k =
+		options?.k ?? (symbolSize > 0 ? Math.round(blockData.length / symbolSize) : 0);
+	if (k === 0) return empty;
+
+	const failReasons: Record<string, number> = {};
+	let failedCount = 0;
+	const parsed: ParsedFecSymbol[] = [];
+
+	for (let i = 0; i < k; i++) {
+		const symStart = i * symbolSize;
+		if (symStart >= blockData.length) break;
+		const symEnd = Math.min(symStart + symbolSize, blockData.length);
+
+		const single = processFecSymbol(blockData.subarray(symStart, symEnd), { index: i });
+		for (const [reason, count] of Object.entries(single.failReasons)) {
+			failReasons[reason] = (failReasons[reason] ?? 0) + count;
+		}
+		failedCount += single.failedCount;
+		parsed.push(...single.symbols);
+	}
+
+	return resultFromSymbols(parsed, failedCount, failReasons, options?.ownerPacketId);
+}

package/node_modules/@blockcast/mmt-fec/src/cmaf-recovery.ts

@@ -0,0 +1,127 @@
+/**
+ * CmafFecRecovery — stateful FEC recovery manager for CMAF chunks and LOC frames.
+ *
+ * Two input paths:
+ * 1. feedSourceChunk(sbn, chunk) — intact unicast delivery. Registers symbols with FEC.
+ * 2. feedSourceSymbol(sbn, esi, symbol) — individual multicast packet. Collects for recovery.
+ * 3. feedRepairSymbol(sbn, esi, symbol) — repair track. Triggers RaptorQ recovery.
+ *
+ * Returns recovered data when a block completes, null otherwise.
+ */
+
+import { splitToSymbols, recoverFromSymbols } from "./cmaf-symbols.js";
+
+/** Minimal decoder interface supplied by the composing container/application. */
+export interface FecDecoder {
+	addSourceSymbol(sbn: number, esi: number, symbol: Uint8Array, rawLen?: number): Uint8Array | null;
+	addRepairSymbol(sbn: number, esi: number, symbol: Uint8Array): Uint8Array | null;
+	getSymbolSize(): number;
+}
+
+export interface CmafFecRecoveryConfig {
+	fecDecoder: FecDecoder;
+	symbolSize: number;
+	k: number;
+}
+
+interface BlockState {
+	originalLength?: number;
+	symbolsReceived: number;
+	recovered: boolean;
+}
+
+export class CmafFecRecovery {
+	readonly #decoder: FecDecoder;
+	readonly #symbolSize: number;
+	readonly #k: number;
+	readonly #blocks = new Map<number, BlockState>();
+
+	constructor(config: CmafFecRecoveryConfig) {
+		this.#decoder = config.fecDecoder;
+		this.#symbolSize = config.symbolSize;
+		this.#k = config.k;
+	}
+
+	/**
+	 * Feed a complete chunk/frame (intact unicast delivery).
+	 * Splits into K symbols and registers with FEC state.
+	 * Returns the chunk as-is (pass-through — no recovery needed).
+	 */
+	feedSourceChunk(sbn: number, chunk: Uint8Array): Uint8Array {
+		const symbols = splitToSymbols(chunk, { symbolSize: this.#symbolSize, k: this.#k });
+
+		// Register all symbols with FEC decoder (for cross-block repair)
+		for (let esi = 0; esi < symbols.length; esi++) {
+			this.#decoder.addSourceSymbol(sbn, esi, symbols[esi], chunk.length);
+		}
+
+		this.#blocks.set(sbn, {
+			originalLength: chunk.length,
+			symbolsReceived: this.#k,
+			recovered: true,
+		});
+
+		return chunk;
+	}
+
+	/**
+	 * Feed individual source symbol (from multicast packet).
+	 * Returns recovered chunk if block completes, null otherwise.
+	 */
+	feedSourceSymbol(sbn: number, esi: number, symbol: Uint8Array): Uint8Array | null {
+		let block = this.#blocks.get(sbn);
+		if (block?.recovered) return null; // already recovered
+
+		if (!block) {
+			block = { symbolsReceived: 0, recovered: false };
+			this.#blocks.set(sbn, block);
+		}
+		block.symbolsReceived++;
+
+		const decoded = this.#decoder.addSourceSymbol(sbn, esi, symbol);
+		return this.#handleDecoded(sbn, decoded);
+	}
+
+	/**
+	 * Feed repair symbol (from repair track).
+	 * Returns recovered chunk if block completes, null otherwise.
+	 */
+	feedRepairSymbol(sbn: number, esi: number, symbol: Uint8Array): Uint8Array | null {
+		const block = this.#blocks.get(sbn);
+		if (block?.recovered) return null;
+
+		const decoded = this.#decoder.addRepairSymbol(sbn, esi, symbol);
+		return this.#handleDecoded(sbn, decoded);
+	}
+
+	#handleDecoded(sbn: number, decoded: Uint8Array | null): Uint8Array | null {
+		if (!decoded || decoded.length === 0) return null;
+
+		const block = this.#blocks.get(sbn);
+		if (block) block.recovered = true;
+
+		// Decoded = K symbols concatenated. Recover original data.
+		const symbols: Uint8Array[] = [];
+		for (let i = 0; i < this.#k; i++) {
+			const start = i * this.#symbolSize;
+			const end = start + this.#symbolSize;
+			symbols.push(decoded.subarray(start, Math.min(end, decoded.length)));
+		}
+
+		// If we know the original length, strip padding
+		const originalLength = block?.originalLength ?? decoded.length;
+		return recoverFromSymbols(symbols, { originalLength });
+	}
+
+	/** Evict old block state to prevent unbounded memory growth. */
+	evictBefore(sbn: number): void {
+		for (const key of this.#blocks.keys()) {
+			if (key < sbn) this.#blocks.delete(key);
+		}
+	}
+
+	/** Reset all state. */
+	reset(): void {
+		this.#blocks.clear();
+	}
+}

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

@@ -0,0 +1,68 @@
+/**
+ * CMAF Symbol Splitter — split CMAF chunks into FEC source symbols.
+ *
+ * Per CARP draft §6.1: "Each chunk is divided into K source symbols of
+ * symbolSize bytes." The last symbol is zero-padded if the chunk size
+ * isn't evenly divisible.
+ *
+ * Also used for LOC frames (raw codec bitstream) — same algorithm,
+ * no container overhead to account for.
+ *
+ * Pure functions — no side effects, no state.
+ */
+
+/**
+ * Split a byte array (CMAF chunk or LOC frame) into K source symbols.
+ * Each symbol is exactly `symbolSize` bytes, zero-padded if needed.
+ */
+export function splitToSymbols(
+	data: Uint8Array,
+	config: { symbolSize: number; k: number },
+): Uint8Array[] {
+	const { symbolSize, k } = config;
+	const symbols: Uint8Array[] = [];
+
+	for (let i = 0; i < k; i++) {
+		const start = i * symbolSize;
+		const symbol = new Uint8Array(symbolSize); // zero-initialized
+		const end = Math.min(start + symbolSize, data.length);
+		if (start < data.length) {
+			symbol.set(data.subarray(start, end));
+		}
+		symbols.push(symbol);
+	}
+
+	return symbols;
+}
+
+/**
+ * Recover original data from K source symbols.
+ * Strips zero-padding using the known original length.
+ */
+export function recoverFromSymbols(
+	symbols: Uint8Array[],
+	config: { originalLength: number },
+): Uint8Array {
+	const { originalLength } = config;
+	const result = new Uint8Array(originalLength);
+	let offset = 0;
+
+	for (const sym of symbols) {
+		const copyLen = Math.min(sym.length, originalLength - offset);
+		if (copyLen > 0) {
+			result.set(sym.subarray(0, copyLen), offset);
+		}
+		offset += sym.length;
+		if (offset >= originalLength) break;
+	}
+
+	return result;
+}
+
+/**
+ * Compute K (number of source symbols) for a given data length and symbol size.
+ * K = ceil(dataLength / symbolSize)
+ */
+export function computeK(dataLength: number, symbolSize: number): number {
+	return Math.ceil(dataLength / symbolSize);
+}