@blockcast/mmt-transport 0.2.0

package/src/fec-client.ts

@@ -0,0 +1,1097 @@
+/**
+ * @blockcast/transport - MMT FEC Client
+ *
+ * MMT FEC Client for Browser Players
+ *
+ * Integrates libmmt WASM FEC decoder with:
+ * - MFU fragment reassembly
+ * - window.Multicast API from pim-multicast-gateway
+ * - Green-fill fallback for unrecoverable frames
+ *
+ * Designed for hang and moqtail players.
+ */
+
+import type {
+	MfuFragment,
+	ReassembledMfu,
+	ProcessingStats,
+	MmtFecClientOptions,
+} from "./types.js";
+
+/**
+ * MFU Reassembler (TypeScript implementation for WASM compatibility)
+ */
+class MfuReassembler {
+	private fragmentBuffers = new Map<number, MfuFragment[]>();
+	private timeouts = new Map<number, ReturnType<typeof setTimeout>>();
+	private readonly timeoutMs: number;
+	private readonly maxMfus: number;
+
+	public stats = {
+		complete: 0,
+		reassembled: 0,
+		timedOut: 0,
+	};
+
+	constructor(maxMfus = 100, timeoutMs = 1000) {
+		this.maxMfus = maxMfus;
+		this.timeoutMs = timeoutMs;
+	}
+
+	addFragment(fragment: MfuFragment): ReassembledMfu | null {
+		const { mpuSequenceNumber, fragmentationIndicator } = fragment;
+
+		// FI=0: Complete MFU in single packet
+		if (fragmentationIndicator === 0) {
+			this.stats.complete++;
+			return {
+				mpuSequenceNumber,
+				data: fragment.data,
+				timestamp: fragment.timestamp,
+				fragmentCount: 1,
+				recoveredViaFec: false,
+			};
+		}
+
+		// Get or create buffer for this MPU
+		let fragments = this.fragmentBuffers.get(mpuSequenceNumber);
+		if (!fragments) {
+			fragments = [];
+			this.fragmentBuffers.set(mpuSequenceNumber, fragments);
+			this.setTimeout(mpuSequenceNumber);
+		}
+
+		// Check for duplicate
+		const existingIdx = fragments.findIndex((f) => f.fragmentCounter === fragment.fragmentCounter);
+		if (existingIdx >= 0) {
+			fragments[existingIdx] = fragment;
+		} else {
+			fragments.push(fragment);
+		}
+
+		// Enforce memory limit
+		this.enforceLimit();
+
+		// Try to reassemble
+		return this.tryReassemble(mpuSequenceNumber);
+	}
+
+	private tryReassemble(mpuSeq: number): ReassembledMfu | null {
+		const fragments = this.fragmentBuffers.get(mpuSeq);
+		if (!fragments || fragments.length === 0) return null;
+
+		// Sort by FI
+		fragments.sort((a, b) => a.fragmentationIndicator - b.fragmentationIndicator);
+
+		const first = fragments[0].fragmentationIndicator;
+		const last = fragments[fragments.length - 1].fragmentationIndicator;
+
+		// Need FI=1 (first) and FI=3 (last)
+		if (first !== 1 || last !== 3) return null;
+
+		// Verify middles are FI=2
+		for (let i = 1; i < fragments.length - 1; i++) {
+			if (fragments[i].fragmentationIndicator !== 2) return null;
+		}
+
+		// Reassemble
+		const totalSize = fragments.reduce((sum, f) => sum + f.data.length, 0);
+		const reassembled = new Uint8Array(totalSize);
+		let offset = 0;
+		for (const fragment of fragments) {
+			reassembled.set(fragment.data, offset);
+			offset += fragment.data.length;
+		}
+
+		// Cleanup
+		this.clearTimeout(mpuSeq);
+		this.fragmentBuffers.delete(mpuSeq);
+		this.stats.reassembled++;
+
+		return {
+			mpuSequenceNumber: mpuSeq,
+			data: reassembled,
+			timestamp: fragments[0].timestamp,
+			fragmentCount: fragments.length,
+			recoveredViaFec: false,
+		};
+	}
+
+	private setTimeout(mpuSeq: number): void {
+		const id = setTimeout(() => this.onTimeout(mpuSeq), this.timeoutMs);
+		this.timeouts.set(mpuSeq, id);
+	}
+
+	private clearTimeout(mpuSeq: number): void {
+		const id = this.timeouts.get(mpuSeq);
+		if (id !== undefined) {
+			clearTimeout(id);
+			this.timeouts.delete(mpuSeq);
+		}
+	}
+
+	private onTimeout(mpuSeq: number): void {
+		this.fragmentBuffers.delete(mpuSeq);
+		this.timeouts.delete(mpuSeq);
+		this.stats.timedOut++;
+	}
+
+	private enforceLimit(): void {
+		if (this.fragmentBuffers.size <= this.maxMfus) return;
+
+		const sequences = Array.from(this.fragmentBuffers.keys()).sort((a, b) => a - b);
+		const toRemove = sequences.slice(0, sequences.length - this.maxMfus);
+
+		for (const seq of toRemove) {
+			this.clearTimeout(seq);
+			this.fragmentBuffers.delete(seq);
+			this.stats.timedOut++;
+		}
+	}
+
+	flush(): void {
+		for (const seq of this.fragmentBuffers.keys()) {
+			this.clearTimeout(seq);
+		}
+		this.fragmentBuffers.clear();
+		this.timeouts.clear();
+	}
+}
+
+/**
+ * FEC decoder configuration parameters (RFC 6330 OTI)
+ * This is distinct from the high-level FecConfig in types.ts which is for enabling/configuring FEC.
+ */
+export interface FecDecoderConfig {
+	/** Symbol size in bytes (T) */
+	symbolSize: number;
+	/** Number of source blocks (Z) */
+	sourceBlocks: number;
+	/** Number of sub-blocks (N) - used for large blocks */
+	subBlocks: number;
+	/** Symbol alignment (Al) - typically 8 for byte-aligned */
+	alignment: number;
+	/** Interleave depth - number of blocks that can be "in flight" */
+	interleaveDepth: number;
+}
+
+/**
+ * FEC Decoder interface (WASM module)
+ */
+interface FecDecoder {
+	configure(oti: Uint8Array): void;
+	add_repair(sbn: number, esi: number, data: Uint8Array, timestamp: number): Uint8Array | null;
+	cleanup(timestamp: number): number[];
+	cleanup_by_interleave(current_sbn: number): number[];
+	get_stats(): {
+		source_packets: bigint;
+		repair_packets: bigint;
+		blocks_complete: bigint;
+		blocks_recovered: bigint;
+		blocks_failed: bigint;
+		recovery_rate(): number;
+	};
+	reset_stats(): void;
+	flush(): void;
+	set_timeout(ms: number): void;
+	set_green_fill(enabled: boolean): void;
+	set_interleave_depth(depth: number): void;
+	get_interleave_depth(): number;
+	get_symbol_size(): number;
+	get_source_blocks(): number;
+	get_sub_blocks(): number;
+	get_alignment(): number;
+}
+
+/**
+ * FEC Payload ID parser interface
+ */
+interface FecPayloadId {
+	sbn: number;
+	esi: number;
+}
+
+/**
+ * MMT FEC Client
+ *
+ * Combines WASM FEC decoder with MFU reassembler for complete
+ * MMT packet processing in browser players.
+ */
+export class MmtFecClient {
+	private fecDecoder: FecDecoder | null = null;
+	private mfuReassembler: MfuReassembler;
+	private options: Required<MmtFecClientOptions>;
+	private initialized = false;
+	private greenFillCount = 0;
+	private cleanupInterval: ReturnType<typeof setInterval> | null = null;
+
+	// WASM module references (set via init)
+	private wasmInit?: () => Promise<void>;
+	private wasmFecDecoder?: new (interleaveDepth: number) => FecDecoder;
+	private wasmParseFecPayloadId?: (data: Uint8Array) => FecPayloadId;
+	private wasmIsSimdEnabled?: () => boolean;
+
+	constructor(options: MmtFecClientOptions = {}) {
+		this.options = {
+			interleaveDepth: options.interleaveDepth ?? 30,
+			blockTimeoutMs: options.blockTimeoutMs ?? 2000,
+			mfuTimeoutMs: options.mfuTimeoutMs ?? 1000,
+			greenFillEnabled: options.greenFillEnabled ?? true,
+			onMfuReady: options.onMfuReady ?? (() => {}),
+			onGreenFill: options.onGreenFill ?? (() => {}),
+			onStatsUpdate: options.onStatsUpdate ?? (() => {}),
+		};
+
+		this.mfuReassembler = new MfuReassembler(100, this.options.mfuTimeoutMs);
+	}
+
+	/**
+	 * Set WASM module functions (called before init)
+	 */
+	setWasmModule(module: {
+		init: () => Promise<void>;
+		MmtFecDecoder: new (interleaveDepth: number) => FecDecoder;
+		parse_fec_payload_id: (data: Uint8Array) => FecPayloadId;
+		is_simd_enabled: () => boolean;
+	}): void {
+		this.wasmInit = module.init;
+		this.wasmFecDecoder = module.MmtFecDecoder;
+		this.wasmParseFecPayloadId = module.parse_fec_payload_id;
+		this.wasmIsSimdEnabled = module.is_simd_enabled;
+	}
+
+	/**
+	 * Initialize the WASM module
+	 */
+	async init(): Promise<void> {
+		if (this.initialized) return;
+
+		if (!this.wasmInit || !this.wasmFecDecoder) {
+			throw new Error("WASM module not set. Call setWasmModule() first.");
+		}
+
+		await this.wasmInit();
+
+		this.fecDecoder = new this.wasmFecDecoder(this.options.interleaveDepth);
+		this.fecDecoder.set_timeout(this.options.blockTimeoutMs);
+		this.fecDecoder.set_green_fill(this.options.greenFillEnabled);
+
+		// Start periodic cleanup
+		this.cleanupInterval = setInterval(() => {
+			this.cleanup();
+		}, 500);
+
+		this.initialized = true;
+		console.log(`[MmtFecClient] Initialized (SIMD: ${this.wasmIsSimdEnabled?.() ?? false})`);
+	}
+
+	/**
+	 * Configure FEC from OTI
+	 */
+	configureFec(oti: Uint8Array): void {
+		if (!this.fecDecoder) {
+			throw new Error("MmtFecClient not initialized");
+		}
+		this.fecDecoder.configure(oti);
+	}
+
+	/**
+	 * Process an MMTP packet
+	 *
+	 * Handles FEC and MFU reassembly automatically.
+	 * Calls onMfuReady when a complete MFU is available.
+	 */
+	processPacket(packet: Uint8Array): void {
+		if (!this.fecDecoder) {
+			throw new Error("MmtFecClient not initialized");
+		}
+
+		const timestamp = performance.now();
+
+		// Parse MMTP header (12 bytes minimum)
+		if (packet.length < 12) return;
+
+		const fecType = (packet[0] >> 3) & 0x03;
+		const mmtpTimestamp = BigInt((packet[4] << 24) | (packet[5] << 16) | (packet[6] << 8) | packet[7]);
+
+		const payload = packet.subarray(12);
+		if (payload.length < 8) return;
+
+		// Check if FEC packet
+		if (fecType !== 0) {
+			this.processFecPacket(payload, timestamp, mmtpTimestamp);
+			return;
+		}
+
+		// Parse MPU header
+		const mpuSeq = (payload[0] << 24) | (payload[1] << 16) | (payload[2] << 8) | payload[3];
+		const fi = payload[5] & 0x03;
+		const fragCounter = (payload[6] << 8) | payload[7];
+
+		// MFU DU header present for FI=0 (complete) or FI=1 (first)
+		const hasMfuHeader = fi === 0 || fi === 1;
+		const headerSize = 8 + (hasMfuHeader ? 14 : 0);
+
+		if (payload.length < headerSize) return;
+
+		const data = payload.subarray(headerSize);
+
+		// Add fragment to reassembler
+		const fragment: MfuFragment = {
+			mpuSequenceNumber: mpuSeq,
+			fragmentationIndicator: fi,
+			fragmentCounter: fragCounter,
+			data: new Uint8Array(data),
+			timestamp: mmtpTimestamp,
+		};
+
+		const mfu = this.mfuReassembler.addFragment(fragment);
+		if (mfu) {
+			this.options.onMfuReady(mfu);
+		}
+	}
+
+	/**
+	 * Process FEC repair packet
+	 */
+	private processFecPacket(payload: Uint8Array, timestamp: number, mmtpTimestamp: bigint): void {
+		if (!this.fecDecoder || !this.wasmParseFecPayloadId || payload.length < 4) return;
+
+		try {
+			const { sbn, esi } = this.wasmParseFecPayloadId(payload.subarray(0, 4));
+			const data = payload.subarray(4);
+
+			// Add repair packet to FEC decoder
+			const decoded = this.fecDecoder.add_repair(sbn, esi, data, timestamp);
+
+			if (decoded && decoded.length > 0) {
+				// FEC recovery successful - create MFU from decoded data
+				const mfu: ReassembledMfu = {
+					mpuSequenceNumber: sbn, // Use SBN as sequence
+					data: new Uint8Array(decoded),
+					timestamp: mmtpTimestamp,
+					fragmentCount: 0,
+					recoveredViaFec: true,
+				};
+				this.options.onMfuReady(mfu);
+			}
+		} catch (e) {
+			console.warn("[MmtFecClient] FEC packet parse error:", e);
+		}
+	}
+
+	/**
+	 * Cleanup expired blocks and MFUs
+	 */
+	cleanup(): void {
+		if (!this.fecDecoder) return;
+
+		const greenFills = this.fecDecoder.cleanup(performance.now());
+
+		if (greenFills.length > 0 && this.options.greenFillEnabled) {
+			this.greenFillCount++;
+			this.options.onGreenFill(BigInt(performance.now()));
+		}
+	}
+
+	/**
+	 * Get current statistics
+	 */
+	getStats(): ProcessingStats {
+		const fecStats = this.fecDecoder?.get_stats();
+		const mfuStats = this.mfuReassembler.stats;
+
+		return {
+			mfuComplete: mfuStats.complete,
+			mfuReassembled: mfuStats.reassembled,
+			mfuTimedOut: mfuStats.timedOut,
+			fecSourcePackets: Number(fecStats?.source_packets ?? 0n),
+			fecRepairPackets: Number(fecStats?.repair_packets ?? 0n),
+			fecBlocksComplete: Number(fecStats?.blocks_complete ?? 0n),
+			fecBlocksRecovered: Number(fecStats?.blocks_recovered ?? 0n),
+			fecBlocksFailed: Number(fecStats?.blocks_failed ?? 0n),
+			fecRecoveryRate: fecStats?.recovery_rate() ?? 100,
+			greenFillFrames: this.greenFillCount,
+		};
+	}
+
+	/**
+	 * Reset statistics
+	 */
+	resetStats(): void {
+		this.fecDecoder?.reset_stats();
+		this.greenFillCount = 0;
+	}
+
+	/**
+	 * Get current FEC configuration
+	 * Returns the OTI parameters and interleave depth
+	 */
+	getConfig(): FecDecoderConfig {
+		return {
+			symbolSize: this.fecDecoder?.get_symbol_size() ?? 1280,
+			sourceBlocks: this.fecDecoder?.get_source_blocks() ?? 1,
+			subBlocks: this.fecDecoder?.get_sub_blocks() ?? 1,
+			alignment: this.fecDecoder?.get_alignment() ?? 8,
+			interleaveDepth: this.fecDecoder?.get_interleave_depth() ?? this.options.interleaveDepth,
+		};
+	}
+
+	/**
+	 * Set interleave depth
+	 *
+	 * The interleave depth determines how many blocks can be "in flight" at once.
+	 * Higher values provide better burst loss protection but increase latency.
+	 *
+	 * @param depth - Number of interleaved blocks (min: 1, typical: 30 for ~1s at 30fps)
+	 */
+	setInterleaveDepth(depth: number): void {
+		if (!this.fecDecoder) return;
+		this.fecDecoder.set_interleave_depth(Math.max(1, depth));
+		this.options.interleaveDepth = Math.max(1, depth);
+	}
+
+	/**
+	 * Cleanup blocks that are too old based on interleave depth
+	 *
+	 * This method expires blocks that are more than `interleaveDepth` behind
+	 * the current block number. Call this when processing a new source block
+	 * to maintain memory bounds.
+	 *
+	 * @param currentSbn - Current source block number being processed
+	 * @returns Array of expired block numbers
+	 */
+	cleanupByInterleave(currentSbn: number): number[] {
+		if (!this.fecDecoder) return [];
+		return Array.from(this.fecDecoder.cleanup_by_interleave(currentSbn));
+	}
+
+	/**
+	 * Check if initialized
+	 */
+	isInitialized(): boolean {
+		return this.initialized;
+	}
+
+	/**
+	 * Dispose of resources
+	 */
+	dispose(): void {
+		if (this.cleanupInterval) {
+			clearInterval(this.cleanupInterval);
+		}
+		this.mfuReassembler.flush();
+		this.fecDecoder?.flush();
+		this.initialized = false;
+	}
+}
+
+/**
+ * Integration with window.Multicast API (pim-multicast-gateway)
+ */
+export function createMulticastFecHandler(
+	client: MmtFecClient,
+	options?: { onPacket?: (data: ArrayBuffer) => void },
+): (data: ArrayBuffer) => void {
+	return (data: ArrayBuffer) => {
+		const packet = new Uint8Array(data);
+		client.processPacket(packet);
+		options?.onPacket?.(data);
+	};
+}
+
+/**
+ * Quick setup for hang/moqtail integration
+ */
+export async function setupMmtFec(options?: MmtFecClientOptions): Promise<MmtFecClient> {
+	const client = new MmtFecClient(options);
+
+	// Integrate with window.Multicast if available
+	if (typeof window !== "undefined" && (window as unknown as { Multicast?: unknown }).Multicast) {
+		console.log("[MmtFecClient] window.Multicast detected, ready for integration");
+	}
+
+	return client;
+}
+
+// =============================================================================
+// MoQ FEC Client (for WebTransport)
+// =============================================================================
+
+/**
+ * MoQ FEC configuration
+ */
+export interface MoqFecClientConfig {
+	/** Symbol size in bytes (typically 1280 for MTU) */
+	symbolSize: number;
+	/** Source symbols per block (K) */
+	k: number;
+	/** Repair symbols per block (P) */
+	p: number;
+	/** Interleave depth for burst loss protection */
+	interleaveDepth: number;
+}
+
+/**
+ * MoQ FEC statistics for ABR
+ */
+export interface MoqFecClientStats {
+	/** Blocks successfully decoded */
+	blocksComplete: number;
+	/** Blocks with some symbols but not yet complete */
+	blocksIncomplete: number;
+	/** Total symbols received */
+	totalSymbolsReceived: number;
+	/** Source symbols per block (K) */
+	k: number;
+	/** Repair symbols per block (P) */
+	p: number;
+	/** Interleave depth */
+	interleaveDepth: number;
+	/** Effective loss rate after FEC recovery (0.0-1.0) */
+	effectiveLossRate: number;
+	/** Recovery rate (0.0-1.0) */
+	recoveryRate: number;
+}
+
+/**
+ * MoQ FEC Encoder interface (WASM module)
+ */
+interface WasmMoqFecEncoder {
+	encodeBlock(data: Uint8Array): {
+		block_id: number;
+		original_len: number;
+		k: number;
+		p: number;
+		getOti(): Uint8Array;
+		sourceSymbolCount(): number;
+		getSourceSymbol(index: number): Uint8Array | null;
+		repairSymbolCount(): number;
+		getRepairSymbol(index: number): Uint8Array | null;
+	};
+	blockCount(): number;
+	getOti(): Uint8Array;
+}
+
+/**
+ * MoQ FEC Decoder interface (WASM module)
+ */
+interface WasmMoqFecDecoder {
+	addSourceSymbol(
+		blockId: number,
+		esi: number,
+		symbol: Uint8Array,
+		originalLen?: number,
+	): Uint8Array | null;
+	addRepairSymbol(blockId: number, esi: number, symbol: Uint8Array): Uint8Array | null;
+	isBlockComplete(blockId: number): boolean;
+	getBlockData(blockId: number): Uint8Array;
+	resetBlock(blockId: number): void;
+	getStats(): {
+		blocksComplete: number;
+		blocksIncomplete: number;
+		totalSymbolsReceived: number;
+		k: number;
+		p: number;
+		interleaveDepth: number;
+		effectiveLossRate(): number;
+		recoveryRate(): number;
+	};
+}
+
+/**
+ * MoQ FEC Config interface (WASM module)
+ */
+interface WasmMoqFecConfig {
+	maxBlockSize(): number;
+	overheadRatio(): number;
+	symbol_size: number;
+	k: number;
+	p: number;
+	interleaveDepth: number;
+}
+
+/**
+ * MoQ FEC Client
+ *
+ * Wraps mmt-wasm MoQ FEC bindings for use in TypeScript applications.
+ * Designed for WebTransport-based MoQ streaming with FEC protection.
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * import { MoqFecClient } from '@blockcast/ssm-transport';
+ *
+ * const client = new MoqFecClient({
+ *   symbolSize: 1280,
+ *   k: 10,
+ *   p: 3,
+ *   interleaveDepth: 30,
+ * });
+ *
+ * await client.init();
+ *
+ * // Encoder (publisher side)
+ * const encoded = client.encodeBlock(groupData);
+ * encoded.sourceSymbols.forEach((symbol, esi) => {
+ *   sendSourceSymbol(encoded.blockId, esi, symbol);
+ * });
+ * encoded.repairSymbols.forEach((symbol, i) => {
+ *   sendRepairSymbol(encoded.blockId, encoded.k + i, symbol);
+ * });
+ *
+ * // Decoder (subscriber side)
+ * client.setOti(encoded.oti);
+ * onSourceSymbol((blockId, esi, symbol) => {
+ *   const decoded = client.addSourceSymbol(blockId, esi, symbol);
+ *   if (decoded) processGroup(decoded);
+ * });
+ * ```
+ */
+// Global WASM module cache
+let wasmModuleCache: {
+	init: () => Promise<void>;
+	MoqFecConfig: new (symbolSize: number, k: number, p: number, interleaveDepth: number) => WasmMoqFecConfig;
+	MoqFecEncoder: new (config: WasmMoqFecConfig) => WasmMoqFecEncoder;
+	MoqFecDecoder: new (config: WasmMoqFecConfig, oti: Uint8Array) => WasmMoqFecDecoder;
+} | null = null;
+
+/**
+ * Load the mmt-wasm module dynamically
+ *
+ * @param wasmPath - Path to the mmt-wasm module (default: tries common locations)
+ * @returns The loaded WASM module
+ */
+export async function loadMmtWasm(wasmPath?: string): Promise<typeof wasmModuleCache> {
+	if (wasmModuleCache) {
+		return wasmModuleCache;
+	}
+
+	// Try multiple paths to find the WASM module
+	const paths = wasmPath
+		? [wasmPath]
+		: [
+				// NPM package names (preferred - resolved by bundler/node)
+				"mmt-wasm",
+				"@mmt/wasm",
+				"@blockcast/mmt-wasm",
+				// Relative paths from common project structures
+				"../mmt-wasm/pkg/mmt_wasm.js",
+				"../../mmt-wasm/pkg/mmt_wasm.js",
+				"../../../libmmt/mmt-wasm/pkg/mmt_wasm.js",
+				// Absolute paths for web serving
+				"/libs/mmt-wasm/pkg/mmt_wasm.js",
+				"/mmt-wasm/pkg/mmt_wasm.js",
+				"/pkg/mmt_wasm.js",
+				"./mmt_wasm.js",
+			];
+
+	for (const path of paths) {
+		try {
+			// Dynamic import
+			const module = await import(/* webpackIgnore: true */ path);
+
+			// Check if it has the expected exports
+			if (module.MoqFecConfig && module.MoqFecEncoder && module.MoqFecDecoder) {
+				// Initialize the WASM module
+				if (module.default) {
+					await module.default();
+				}
+
+				wasmModuleCache = {
+					init: async () => {
+						/* already initialized */
+					},
+					MoqFecConfig: module.MoqFecConfig,
+					MoqFecEncoder: module.MoqFecEncoder,
+					MoqFecDecoder: module.MoqFecDecoder,
+				};
+
+				console.log(`[MoqFecClient] Loaded mmt-wasm from ${path}`);
+				return wasmModuleCache;
+			}
+		} catch {
+			// Try next path
+			continue;
+		}
+	}
+
+	throw new Error(
+		`Failed to load mmt-wasm module. Tried paths: ${paths.join(", ")}. ` +
+			`Make sure mmt-wasm is built and accessible.`,
+	);
+}
+
+/**
+ * Create a MoqFecClient with auto-loaded WASM module
+ *
+ * @param config - FEC configuration
+ * @param wasmPath - Optional path to mmt-wasm module
+ * @returns Initialized MoqFecClient
+ */
+export async function createMoqFecClient(
+	config: Partial<MoqFecClientConfig> = {},
+	wasmPath?: string,
+): Promise<MoqFecClient> {
+	const client = new MoqFecClient(config);
+
+	try {
+		const wasmModule = await loadMmtWasm(wasmPath);
+		if (wasmModule) {
+			client.setWasmModule(wasmModule);
+			await client.init();
+		}
+	} catch (err) {
+		console.warn("[MoqFecClient] Failed to auto-load WASM module:", err);
+		// Client is created but not initialized - caller can set WASM module manually
+	}
+
+	return client;
+}
+
+export class MoqFecClient {
+	private config: MoqFecClientConfig;
+	private encoder: WasmMoqFecEncoder | null = null;
+	private decoder: WasmMoqFecDecoder | null = null;
+	private wasmConfig: WasmMoqFecConfig | null = null;
+	private oti: Uint8Array | null = null;
+	private initialized = false;
+
+	// Callbacks for decoded blocks
+	private onBlockDecoded?: (blockId: number, data: Uint8Array) => void;
+
+	// WASM module references
+	private wasmInit?: () => Promise<void>;
+	private wasmMoqFecConfig?: new (
+		symbolSize: number,
+		k: number,
+		p: number,
+		interleaveDepth: number,
+	) => WasmMoqFecConfig;
+	private wasmMoqFecEncoder?: new (config: WasmMoqFecConfig) => WasmMoqFecEncoder;
+	private wasmMoqFecDecoder?: new (config: WasmMoqFecConfig, oti: Uint8Array) => WasmMoqFecDecoder;
+
+	constructor(config: Partial<MoqFecClientConfig> = {}) {
+		this.config = {
+			symbolSize: config.symbolSize ?? 1280,
+			k: config.k ?? 10,
+			p: config.p ?? 3,
+			interleaveDepth: config.interleaveDepth ?? 30,
+		};
+	}
+
+	/**
+	 * Create and initialize a MoqFecClient with auto-loaded WASM
+	 *
+	 * This is a convenience static method that handles WASM loading automatically.
+	 *
+	 * @param config - FEC configuration
+	 * @param wasmPath - Optional path to mmt-wasm module
+	 * @returns Initialized MoqFecClient
+	 */
+	static async create(config: Partial<MoqFecClientConfig> = {}, wasmPath?: string): Promise<MoqFecClient> {
+		return createMoqFecClient(config, wasmPath);
+	}
+
+	/**
+	 * Set WASM module functions (called before init)
+	 */
+	setWasmModule(module: {
+		init: () => Promise<void>;
+		MoqFecConfig: new (
+			symbolSize: number,
+			k: number,
+			p: number,
+			interleaveDepth: number,
+		) => WasmMoqFecConfig;
+		MoqFecEncoder: new (config: WasmMoqFecConfig) => WasmMoqFecEncoder;
+		MoqFecDecoder: new (config: WasmMoqFecConfig, oti: Uint8Array) => WasmMoqFecDecoder;
+	}): void {
+		this.wasmInit = module.init;
+		this.wasmMoqFecConfig = module.MoqFecConfig;
+		this.wasmMoqFecEncoder = module.MoqFecEncoder;
+		this.wasmMoqFecDecoder = module.MoqFecDecoder;
+	}
+
+	/**
+	 * Initialize the WASM module and create encoder
+	 */
+	async init(): Promise<void> {
+		if (this.initialized) return;
+
+		if (!this.wasmInit || !this.wasmMoqFecConfig || !this.wasmMoqFecEncoder) {
+			throw new Error("WASM module not set. Call setWasmModule() first.");
+		}
+
+		await this.wasmInit();
+
+		this.wasmConfig = new this.wasmMoqFecConfig(
+			this.config.symbolSize,
+			this.config.k,
+			this.config.p,
+			this.config.interleaveDepth,
+		);
+
+		this.encoder = new this.wasmMoqFecEncoder(this.wasmConfig);
+		this.oti = new Uint8Array(this.encoder.getOti());
+
+		this.initialized = true;
+		console.log(
+			`[MoqFecClient] Initialized: K=${this.config.k}, P=${this.config.p}, ` +
+				`symbolSize=${this.config.symbolSize}, depth=${this.config.interleaveDepth}`,
+		);
+	}
+
+	/**
+	 * Set OTI from encoder (required for decoder)
+	 * Call this when receiving FEC config from publisher
+	 */
+	setOti(oti: Uint8Array): void {
+		if (oti.length !== 12) {
+			throw new Error("OTI must be exactly 12 bytes");
+		}
+		this.oti = new Uint8Array(oti);
+
+		// Create decoder with OTI
+		if (this.wasmMoqFecDecoder && this.wasmConfig) {
+			this.decoder = new this.wasmMoqFecDecoder(this.wasmConfig, this.oti);
+			console.log("[MoqFecClient] Decoder initialized with OTI");
+		}
+	}
+
+	/**
+	 * Get the current OTI
+	 */
+	getOti(): Uint8Array | null {
+		return this.oti;
+	}
+
+	/**
+	 * Set callback for decoded blocks
+	 */
+	setBlockDecodedCallback(callback: (blockId: number, data: Uint8Array) => void): void {
+		this.onBlockDecoded = callback;
+	}
+
+	/**
+	 * Encode a data block (publisher side)
+	 *
+	 * @param data - The data block to encode (e.g., MoQ Group)
+	 * @returns Encoded block with source and repair symbols
+	 */
+	encodeBlock(data: Uint8Array): {
+		blockId: number;
+		originalLen: number;
+		k: number;
+		p: number;
+		oti: Uint8Array;
+		sourceSymbols: Uint8Array[];
+		repairSymbols: Uint8Array[];
+	} {
+		if (!this.encoder) {
+			throw new Error("MoqFecClient not initialized");
+		}
+
+		const encoded = this.encoder.encodeBlock(data);
+
+		// Collect source symbols
+		const sourceSymbols: Uint8Array[] = [];
+		for (let i = 0; i < encoded.sourceSymbolCount(); i++) {
+			const symbol = encoded.getSourceSymbol(i);
+			if (symbol) sourceSymbols.push(new Uint8Array(symbol));
+		}
+
+		// Collect repair symbols
+		const repairSymbols: Uint8Array[] = [];
+		for (let i = 0; i < encoded.repairSymbolCount(); i++) {
+			const symbol = encoded.getRepairSymbol(i);
+			if (symbol) repairSymbols.push(new Uint8Array(symbol));
+		}
+
+		return {
+			blockId: encoded.block_id,
+			originalLen: encoded.original_len,
+			k: encoded.k,
+			p: encoded.p,
+			oti: new Uint8Array(encoded.getOti()),
+			sourceSymbols,
+			repairSymbols,
+		};
+	}
+
+	/**
+	 * Add a source symbol (subscriber side)
+	 *
+	 * @param blockId - Block this symbol belongs to
+	 * @param esi - Encoding Symbol ID (0 to K-1)
+	 * @param symbol - Symbol data
+	 * @param originalLen - Original data length (optional)
+	 * @returns Decoded data if block is complete, null otherwise
+	 */
+	addSourceSymbol(
+		blockId: number,
+		esi: number,
+		symbol: Uint8Array,
+		originalLen?: number,
+	): Uint8Array | null {
+		if (!this.decoder) {
+			console.warn("[MoqFecClient] Decoder not initialized, call setOti() first");
+			return null;
+		}
+
+		const decoded = this.decoder.addSourceSymbol(blockId, esi, symbol, originalLen);
+
+		if (decoded) {
+			this.onBlockDecoded?.(blockId, decoded);
+		}
+
+		return decoded;
+	}
+
+	/**
+	 * Add a repair symbol (subscriber side)
+	 *
+	 * @param blockId - Block this symbol belongs to
+	 * @param esi - Encoding Symbol ID (K to K+P-1)
+	 * @param symbol - Symbol data
+	 * @returns Decoded data if block is recovered, null otherwise
+	 */
+	addRepairSymbol(blockId: number, esi: number, symbol: Uint8Array): Uint8Array | null {
+		if (!this.decoder) {
+			console.warn("[MoqFecClient] Decoder not initialized");
+			return null;
+		}
+
+		const decoded = this.decoder.addRepairSymbol(blockId, esi, symbol);
+
+		if (decoded) {
+			this.onBlockDecoded?.(blockId, decoded);
+		}
+
+		return decoded;
+	}
+
+	/**
+	 * Check if a block is complete
+	 */
+	isBlockComplete(blockId: number): boolean {
+		return this.decoder?.isBlockComplete(blockId) ?? false;
+	}
+
+	/**
+	 * Get decoded data for a complete block
+	 */
+	getBlockData(blockId: number): Uint8Array | null {
+		if (!this.decoder) return null;
+		try {
+			return this.decoder.getBlockData(blockId);
+		} catch {
+			return null;
+		}
+	}
+
+	/**
+	 * Reset a block slot for reuse
+	 */
+	resetBlock(blockId: number): void {
+		this.decoder?.resetBlock(blockId);
+	}
+
+	/**
+	 * Get FEC statistics for ABR decisions
+	 */
+	getStats(): MoqFecClientStats {
+		if (!this.decoder) {
+			return {
+				blocksComplete: 0,
+				blocksIncomplete: 0,
+				totalSymbolsReceived: 0,
+				k: this.config.k,
+				p: this.config.p,
+				interleaveDepth: this.config.interleaveDepth,
+				effectiveLossRate: 0,
+				recoveryRate: 1,
+			};
+		}
+
+		const stats = this.decoder.getStats();
+		return {
+			blocksComplete: stats.blocksComplete,
+			blocksIncomplete: stats.blocksIncomplete,
+			totalSymbolsReceived: stats.totalSymbolsReceived,
+			k: stats.k,
+			p: stats.p,
+			interleaveDepth: stats.interleaveDepth,
+			effectiveLossRate: stats.effectiveLossRate(),
+			recoveryRate: stats.recoveryRate(),
+		};
+	}
+
+	/**
+	 * Get ABR-compatible statistics
+	 * Returns stats in format suitable for ABR controller
+	 */
+	getAbrStats(): {
+		effectiveLossRate: number;
+		rawLossRate: number;
+		recoveryRate: number;
+		fecEnabled: boolean;
+	} {
+		const stats = this.getStats();
+		const totalBlocks = stats.blocksComplete + stats.blocksIncomplete;
+		const rawLossRate = totalBlocks > 0 ? stats.blocksIncomplete / totalBlocks : 0;
+
+		return {
+			effectiveLossRate: stats.effectiveLossRate,
+			rawLossRate,
+			recoveryRate: stats.recoveryRate,
+			fecEnabled: this.initialized && this.decoder !== null,
+		};
+	}
+
+	/**
+	 * Get the FEC configuration
+	 */
+	getConfig(): MoqFecClientConfig {
+		return { ...this.config };
+	}
+
+	/**
+	 * Get max block size
+	 */
+	getMaxBlockSize(): number {
+		return this.wasmConfig?.maxBlockSize() ?? this.config.k * this.config.symbolSize;
+	}
+
+	/**
+	 * Get overhead ratio (P/K)
+	 */
+	getOverheadRatio(): number {
+		return this.wasmConfig?.overheadRatio() ?? this.config.p / this.config.k;
+	}
+
+	/**
+	 * Check if initialized
+	 */
+	isInitialized(): boolean {
+		return this.initialized;
+	}
+
+	/**
+	 * Check if decoder is ready
+	 */
+	isDecoderReady(): boolean {
+		return this.decoder !== null;
+	}
+
+	/**
+	 * Dispose of resources
+	 */
+	dispose(): void {
+		this.encoder = null;
+		this.decoder = null;
+		this.wasmConfig = null;
+		this.oti = null;
+		this.initialized = false;
+	}
+}