@blockcast/mmt-fec 0.1.0 → 0.3.0

package/src/fec-client.test.ts

@@ -1,158 +0,0 @@
-/**
- * Tests for shared FecClient
- *
- * Note: Full WASM integration is tested in mmt-wasm.
- * These tests cover the TypeScript wrapper behavior.
- */
-
-import { describe, expect, it, beforeEach } from "vitest";
-import { FecClient, type FecConfig, type FecProcessingStats } from "./fec-client.js";
-
-describe("FecConfig interface", () => {
-	it("should have correct shape for RFC 6330 OTI parameters", () => {
-		const config: FecConfig = {
-			symbolSize: 1280,
-			sourceBlocks: 1,
-			subBlocks: 1,
-			alignment: 8,
-			interleaveDepth: 30,
-		};
-
-		expect(config.symbolSize).toBe(1280);
-		expect(config.sourceBlocks).toBe(1);
-		expect(config.subBlocks).toBe(1);
-		expect(config.alignment).toBe(8);
-		expect(config.interleaveDepth).toBe(30);
-	});
-});
-
-describe("FecProcessingStats interface", () => {
-	it("should have correct shape", () => {
-		const stats: FecProcessingStats = {
-			sourcePackets: 100,
-			repairPackets: 30,
-			blocksComplete: 10,
-			blocksRecovered: 2,
-			blocksFailed: 0,
-			recoveryRate: 100,
-			greenFillFrames: 0,
-		};
-
-		expect(stats.sourcePackets).toBe(100);
-		expect(stats.repairPackets).toBe(30);
-		expect(stats.blocksComplete).toBe(10);
-		expect(stats.blocksRecovered).toBe(2);
-		expect(stats.blocksFailed).toBe(0);
-		expect(stats.recoveryRate).toBe(100);
-		expect(stats.greenFillFrames).toBe(0);
-	});
-});
-
-describe("FecClient", () => {
-	let client: FecClient;
-
-	beforeEach(() => {
-		client = new FecClient({
-			interleaveDepth: 30,
-			blockTimeoutMs: 2000,
-			greenFillEnabled: true,
-		});
-	});
-
-	it("should create with default options", () => {
-		const defaultClient = new FecClient();
-		expect(defaultClient.isInitialized()).toBe(false);
-	});
-
-	it("should not be initialized without calling init()", () => {
-		expect(client.isInitialized()).toBe(false);
-	});
-
-	it("should throw when configuring without initialization", () => {
-		expect(() => client.configure(new Uint8Array(12))).toThrow(
-			"FecClient not initialized"
-		);
-	});
-
-	it("should return default stats when not initialized", () => {
-		const stats = client.getStats();
-
-		expect(stats.sourcePackets).toBe(0);
-		expect(stats.repairPackets).toBe(0);
-		expect(stats.blocksComplete).toBe(0);
-		expect(stats.blocksRecovered).toBe(0);
-		expect(stats.blocksFailed).toBe(0);
-		expect(stats.recoveryRate).toBe(100);
-		expect(stats.greenFillFrames).toBe(0);
-	});
-
-	it("should return default config when not initialized", () => {
-		const config = client.getConfig();
-
-		expect(config.symbolSize).toBe(1280);
-		expect(config.sourceBlocks).toBe(1);
-		expect(config.subBlocks).toBe(1);
-		expect(config.alignment).toBe(8);
-		expect(config.interleaveDepth).toBe(30);
-	});
-
-	it("should no-op setInterleaveDepth when not initialized", () => {
-		client.setInterleaveDepth(10);
-		const config = client.getConfig();
-		expect(config.interleaveDepth).toBe(30); // Unchanged since not init'd
-	});
-
-	it("should return empty array from cleanupByInterleave when not initialized", () => {
-		const expired = client.cleanupByInterleave(100);
-		expect(expired).toEqual([]);
-	});
-
-	it("should return null from addRepair when not initialized", () => {
-		const result = client.addRepair(0, 0, new Uint8Array(100), 0);
-		expect(result).toBeNull();
-	});
-
-	it("should return null from addSource when not initialized", () => {
-		const result = client.addSource(0, 0, new Uint8Array(100), 0);
-		expect(result).toBeNull();
-	});
-
-	it("should return null from processRepairPacket when not initialized", () => {
-		const result = client.processRepairPacket(new Uint8Array(10), 0);
-		expect(result).toBeNull();
-	});
-
-	it("should return null from processRepairPacket with short payload", () => {
-		const result = client.processRepairPacket(new Uint8Array(3), 0);
-		expect(result).toBeNull();
-	});
-
-	it("should dispose cleanly without initialization", () => {
-		client.dispose();
-		expect(client.isInitialized()).toBe(false);
-	});
-
-	it("should reset stats when not initialized", () => {
-		client.resetStats();
-		const stats = client.getStats();
-		expect(stats.greenFillFrames).toBe(0);
-	});
-
-	it("should throw when init without WASM module", async () => {
-		await expect(client.init()).rejects.toThrow(
-			"WASM module not set"
-		);
-	});
-});
-
-describe("FecClient callbacks", () => {
-	it("should store callbacks from options", () => {
-		const client = new FecClient({
-			onRecovered: () => {},
-			onGreenFill: () => {},
-			onStatsUpdate: () => {},
-		});
-
-		expect(client.isInitialized()).toBe(false);
-	});
-});

package/src/fec-client.ts

@@ -1,354 +0,0 @@
-/**
- * Container-Agnostic FEC Client
- *
- * Provides RaptorQ-based Forward Error Correction (RFC 6330) that works with:
- * - MMTP (MMT Protocol) containers
- * - LOC (Low Overhead Container)
- * - Raw NAL units with FEC_CONFIG
- * - MoQ (Media over QUIC)
- *
- * Transport independent - works over both:
- * - Unicast (MOQ/QUIC/WebTransport)
- * - Multicast (SSM/AMT via window.Multicast API)
- *
- * Based on draft-ramadan-moq-fec-00
- */
-
-// WASM module types - matches mmt-wasm MmtFecDecoder
-interface WasmFecDecoder {
-	configure(oti: Uint8Array): void;
-	add_repair(sbn: number, esi: number, data: Uint8Array, timestamp: number): Uint8Array | undefined;
-	add_source(sbn: number, esi: number, data: Uint8Array, timestamp: number): Uint8Array | undefined;
-	cleanup(current_time: number): Uint8Array;
-	get_stats(): WasmFecStats;
-	reset_stats(): void;
-	flush(): void;
-	set_timeout(timeout_ms: number): void;
-	set_green_fill(enabled: boolean): void;
-	pending_blocks(): number;
-}
-
-interface WasmFecStats {
-	source_packets: bigint;
-	repair_packets: bigint;
-	blocks_complete: bigint;
-	blocks_recovered: bigint;
-	blocks_failed: bigint;
-	recovery_rate(): number;
-}
-
-interface WasmFecPayloadId {
-	sbn: number;
-	esi: number;
-}
-
-/**
- * FEC processing statistics (transport & container independent)
- */
-export interface FecProcessingStats {
-	/** Source packets received */
-	sourcePackets: number;
-	/** Repair packets received */
-	repairPackets: number;
-	/** Blocks completed (received all source symbols) */
-	blocksComplete: number;
-	/** Blocks recovered via FEC */
-	blocksRecovered: number;
-	/** Blocks that failed to recover */
-	blocksFailed: number;
-	/** Recovery rate (0-100%) */
-	recoveryRate: number;
-	/** Green-fill frames (unrecoverable data replaced with placeholder) */
-	greenFillFrames: number;
-}
-
-/**
- * FEC configuration parameters (RFC 6330 OTI)
- */
-export interface FecConfig {
-	/** 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;
-}
-
-/**
- * Options for FecClient
- */
-export interface FecClientOptions {
-	/** Interleave depth for FEC (default: 30 for ~1s at 30fps) */
-	interleaveDepth?: number;
-	/** Block timeout in milliseconds (default: 2000) */
-	blockTimeoutMs?: number;
-	/** Enable green-fill for failed frames (default: true) */
-	greenFillEnabled?: boolean;
-	/** Callback when data is recovered via FEC */
-	onRecovered?: (data: Uint8Array, timestamp: bigint) => void;
-	/** Callback for green-fill event */
-	onGreenFill?: (timestamp: bigint) => void;
-	/** Callback for stats update */
-	onStatsUpdate?: (stats: FecProcessingStats) => void;
-}
-
-/**
- * WASM module interface for FecClient
- * Matches mmt-wasm module exports
- */
-export interface FecWasmModule {
-	init: () => Promise<unknown>;
-	MmtFecDecoder: new (interleaveDepth?: number | null) => WasmFecDecoder;
-	parse_fec_payload_id: (data: Uint8Array) => WasmFecPayloadId;
-	is_simd_enabled: () => boolean;
-}
-
-/**
- * Container-Agnostic FEC Client
- *
- * Provides RaptorQ FEC decoding for any container format.
- * The actual container parsing (MMTP, LOC, etc.) is handled separately.
- */
-export class FecClient {
-	private fecDecoder: WasmFecDecoder | null = null;
-	private options: Required<FecClientOptions>;
-	private initialized = false;
-	private greenFillCount = 0;
-	private cleanupInterval: ReturnType<typeof setInterval> | null = null;
-
-	// WASM module references (set via setWasmModule or init)
-	private wasmModule: FecWasmModule | null = null;
-
-	constructor(options: FecClientOptions = {}) {
-		this.options = {
-			interleaveDepth: options.interleaveDepth ?? 30,
-			blockTimeoutMs: options.blockTimeoutMs ?? 2000,
-			greenFillEnabled: options.greenFillEnabled ?? true,
-			onRecovered: options.onRecovered ?? (() => {}),
-			onGreenFill: options.onGreenFill ?? (() => {}),
-			onStatsUpdate: options.onStatsUpdate ?? (() => {}),
-		};
-	}
-
-	/**
-	 * Set WASM module (call before init)
-	 */
-	setWasmModule(module: FecWasmModule): void {
-		this.wasmModule = module;
-	}
-
-	/**
-	 * Initialize the WASM FEC decoder
-	 */
-	async init(wasmModule?: FecWasmModule): Promise<void> {
-		if (this.initialized) return;
-
-		if (wasmModule) {
-			this.wasmModule = wasmModule;
-		}
-
-		if (!this.wasmModule) {
-			throw new Error("WASM module not set. Call setWasmModule() or pass module to init()");
-		}
-
-		await this.wasmModule.init();
-
-		this.fecDecoder = new this.wasmModule.MmtFecDecoder(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(`[FecClient] Initialized (SIMD: ${this.wasmModule.is_simd_enabled()})`);
-	}
-
-	/**
-	 * Check if initialized
-	 */
-	isInitialized(): boolean {
-		return this.initialized;
-	}
-
-	/**
-	 * Configure FEC parameters from OTI (Object Transmission Information)
-	 * Per RFC 6330 (RaptorQ)
-	 */
-	configure(oti: Uint8Array): void {
-		if (!this.fecDecoder) {
-			throw new Error("FecClient not initialized");
-		}
-		this.fecDecoder.configure(oti);
-	}
-
-	/**
-	 * Add a source symbol to the FEC decoder
-	 *
-	 * @param sbn - Source Block Number
-	 * @param esi - Encoding Symbol ID (< K for source symbols)
-	 * @param data - Symbol data
-	 * @param timestamp - Packet timestamp for ordering
-	 * @returns Decoded data if block is complete, null otherwise
-	 */
-	addSource(sbn: number, esi: number, data: Uint8Array, timestamp: number): Uint8Array | null {
-		if (!this.fecDecoder) return null;
-		return this.fecDecoder.add_source(sbn, esi, data, timestamp) ?? null;
-	}
-
-	/**
-	 * Add a repair symbol to the FEC decoder
-	 *
-	 * @param sbn - Source Block Number
-	 * @param esi - Encoding Symbol ID (>= K for repair symbols)
-	 * @param data - Repair symbol data
-	 * @param timestamp - Packet timestamp for ordering
-	 * @returns Recovered data if FEC decoding succeeded, null otherwise
-	 */
-	addRepair(sbn: number, esi: number, data: Uint8Array, timestamp: number): Uint8Array | null {
-		if (!this.fecDecoder) return null;
-
-		try {
-			const decoded = this.fecDecoder.add_repair(sbn, esi, data, timestamp);
-
-			if (decoded && decoded.length > 0) {
-				const recovered = new Uint8Array(decoded);
-				this.options.onRecovered(recovered, BigInt(timestamp));
-				return recovered;
-			}
-		} catch (e) {
-			console.warn("[FecClient] Repair processing error:", e);
-		}
-
-		return null;
-	}
-
-	/**
-	 * Process a repair packet with FEC payload ID header
-	 * Per draft-ramadan-moq-fec-00 Section 6.1
-	 *
-	 * @param payload - Repair packet payload (4-byte header + repair symbols)
-	 * @param timestamp - Packet timestamp
-	 * @returns Recovered data if FEC decoding succeeded, null otherwise
-	 */
-	processRepairPacket(payload: Uint8Array, timestamp: number): Uint8Array | null {
-		if (!this.fecDecoder || !this.wasmModule || payload.length < 4) return null;
-
-		try {
-			const { sbn, esi } = this.wasmModule.parse_fec_payload_id(payload.subarray(0, 4));
-			const data = payload.subarray(4);
-
-			return this.addRepair(sbn, esi, data, timestamp);
-		} catch (e) {
-			console.warn("[FecClient] FEC payload parse error:", e);
-			return null;
-		}
-	}
-
-	/**
-	 * Cleanup expired blocks
-	 * Returns green-fill frame data for expired blocks if green-fill is enabled
-	 */
-	cleanup(): void {
-		if (!this.fecDecoder) return;
-
-		const greenFillData = this.fecDecoder.cleanup(performance.now());
-
-		// greenFillData is a Uint8Array returned by WASM for expired blocks
-		if (greenFillData && greenFillData.length > 0 && this.options.greenFillEnabled) {
-			// Count green-fills based on data returned
-			const greenFillsTriggered = Math.ceil(greenFillData.length / 8);
-			if (greenFillsTriggered > 0) {
-				this.greenFillCount += greenFillsTriggered;
-				this.options.onGreenFill(BigInt(performance.now()));
-			}
-		}
-	}
-
-	/**
-	 * Get number of pending blocks
-	 */
-	getPendingBlocks(): number {
-		return this.fecDecoder?.pending_blocks() ?? 0;
-	}
-
-	/**
-	 * Get current FEC statistics
-	 */
-	getStats(): FecProcessingStats {
-		const fecStats = this.fecDecoder?.get_stats();
-
-		return {
-			sourcePackets: Number(fecStats?.source_packets ?? 0n),
-			repairPackets: Number(fecStats?.repair_packets ?? 0n),
-			blocksComplete: Number(fecStats?.blocks_complete ?? 0n),
-			blocksRecovered: Number(fecStats?.blocks_recovered ?? 0n),
-			blocksFailed: Number(fecStats?.blocks_failed ?? 0n),
-			recoveryRate: fecStats?.recovery_rate() ?? 100,
-			greenFillFrames: this.greenFillCount,
-		};
-	}
-
-	/**
-	 * Get current FEC configuration
-	 * Returns the configured interleave depth (OTI params set via configure())
-	 */
-	getConfig(): FecConfig {
-		return {
-			symbolSize: 1280, // Default, configured via OTI
-			sourceBlocks: 1, // Default, configured via OTI
-			subBlocks: 1, // Default, configured via OTI
-			alignment: 8, // Default, configured via OTI
-			interleaveDepth: this.options.interleaveDepth,
-		};
-	}
-
-	/**
-	 * Reset statistics
-	 */
-	resetStats(): void {
-		this.fecDecoder?.reset_stats();
-		this.greenFillCount = 0;
-	}
-
-	/**
-	 * Dispose of resources
-	 */
-	dispose(): void {
-		if (this.cleanupInterval) {
-			clearInterval(this.cleanupInterval);
-			this.cleanupInterval = null;
-		}
-		this.fecDecoder?.flush();
-		this.initialized = false;
-	}
-}
-
-/**
- * Create a shared FEC client instance (singleton pattern)
- */
-let sharedFecClient: FecClient | null = null;
-
-export async function getSharedFecClient(
-	wasmModule: FecWasmModule,
-	options?: FecClientOptions
-): Promise<FecClient> {
-	if (!sharedFecClient) {
-		sharedFecClient = new FecClient(options);
-		await sharedFecClient.init(wasmModule);
-	}
-	return sharedFecClient;
-}
-
-export function resetSharedFecClient(): void {
-	if (sharedFecClient) {
-		sharedFecClient.dispose();
-		sharedFecClient = null;
-	}
-}