@blockcast/mmt-fec 0.1.0

package/dist/fec-client.d.ts

@@ -0,0 +1,191 @@
+/**
+ * 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
+ */
+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 declare class FecClient {
+    private fecDecoder;
+    private options;
+    private initialized;
+    private greenFillCount;
+    private cleanupInterval;
+    private wasmModule;
+    constructor(options?: FecClientOptions);
+    /**
+     * Set WASM module (call before init)
+     */
+    setWasmModule(module: FecWasmModule): void;
+    /**
+     * Initialize the WASM FEC decoder
+     */
+    init(wasmModule?: FecWasmModule): Promise<void>;
+    /**
+     * Check if initialized
+     */
+    isInitialized(): boolean;
+    /**
+     * Configure FEC parameters from OTI (Object Transmission Information)
+     * Per RFC 6330 (RaptorQ)
+     */
+    configure(oti: Uint8Array): void;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * Cleanup expired blocks
+     * Returns green-fill frame data for expired blocks if green-fill is enabled
+     */
+    cleanup(): void;
+    /**
+     * Get number of pending blocks
+     */
+    getPendingBlocks(): number;
+    /**
+     * Get current FEC statistics
+     */
+    getStats(): FecProcessingStats;
+    /**
+     * Get current FEC configuration
+     * Returns the configured interleave depth (OTI params set via configure())
+     */
+    getConfig(): FecConfig;
+    /**
+     * Reset statistics
+     */
+    resetStats(): void;
+    /**
+     * Dispose of resources
+     */
+    dispose(): void;
+}
+export declare function getSharedFecClient(wasmModule: FecWasmModule, options?: FecClientOptions): Promise<FecClient>;
+export declare function resetSharedFecClient(): void;
+export {};
+//# sourceMappingURL=fec-client.d.ts.map

package/dist/fec-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fec-client.d.ts","sourceRoot":"","sources":["../src/fec-client.ts"],"names":[],"mappings":"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"}

package/dist/fec-client.js

@@ -0,0 +1,233 @@
+/**
+ * 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
+ */
+/**
+ * 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 {
+    fecDecoder = null;
+    options;
+    initialized = false;
+    greenFillCount = 0;
+    cleanupInterval = null;
+    // WASM module references (set via setWasmModule or init)
+    wasmModule = null;
+    constructor(options = {}) {
+        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) {
+        this.wasmModule = module;
+    }
+    /**
+     * Initialize the WASM FEC decoder
+     */
+    async init(wasmModule) {
+        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() {
+        return this.initialized;
+    }
+    /**
+     * Configure FEC parameters from OTI (Object Transmission Information)
+     * Per RFC 6330 (RaptorQ)
+     */
+    configure(oti) {
+        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, esi, data, timestamp) {
+        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, esi, data, timestamp) {
+        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, timestamp) {
+        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() {
+        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() {
+        return this.fecDecoder?.pending_blocks() ?? 0;
+    }
+    /**
+     * Get current FEC statistics
+     */
+    getStats() {
+        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() {
+        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() {
+        this.fecDecoder?.reset_stats();
+        this.greenFillCount = 0;
+    }
+    /**
+     * Dispose of resources
+     */
+    dispose() {
+        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 = null;
+export async function getSharedFecClient(wasmModule, options) {
+    if (!sharedFecClient) {
+        sharedFecClient = new FecClient(options);
+        await sharedFecClient.init(wasmModule);
+    }
+    return sharedFecClient;
+}
+export function resetSharedFecClient() {
+    if (sharedFecClient) {
+        sharedFecClient.dispose();
+        sharedFecClient = null;
+    }
+}
+//# sourceMappingURL=fec-client.js.map

package/dist/fec-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fec-client.js","sourceRoot":"","sources":["../src/fec-client.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @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
+ * import { FecClient } from '@mmt/fec';
+ * import * as wasmModule from '@mmt/wasm';
+ *
+ * const client = new FecClient({ interleaveDepth: 30 });
+ * await client.init(wasmModule);
+ *
+ * // Configure from OTI
+ * client.configure(otiBytes);
+ *
+ * // Add source/repair symbols
+ * const recovered = client.addRepair(sbn, esi, data, timestamp);
+ * ```
+ */
+export { FecClient, getSharedFecClient, resetSharedFecClient, type FecConfig, type FecClientOptions, type FecProcessingStats, type FecWasmModule, } from "./fec-client.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EACN,SAAS,EACT,kBAAkB,EAClB,oBAAoB,EACpB,KAAK,SAAS,EACd,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,EACvB,KAAK,aAAa,GAClB,MAAM,iBAAiB,CAAC"}

package/dist/index.js

@@ -0,0 +1,23 @@
+/**
+ * @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
+ * import { FecClient } from '@mmt/fec';
+ * import * as wasmModule from '@mmt/wasm';
+ *
+ * const client = new FecClient({ interleaveDepth: 30 });
+ * await client.init(wasmModule);
+ *
+ * // Configure from OTI
+ * client.configure(otiBytes);
+ *
+ * // Add source/repair symbols
+ * const recovered = client.addRepair(sbn, esi, data, timestamp);
+ * ```
+ */
+export { FecClient, getSharedFecClient, resetSharedFecClient, } from "./fec-client.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EACN,SAAS,EACT,kBAAkB,EAClB,oBAAoB,GAKpB,MAAM,iBAAiB,CAAC"}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@blockcast/mmt-fec",
+  "version": "0.1.0",
+  "description": "Container-agnostic FEC client for RaptorQ (RFC 6330) decoding via WASM",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "clean": "rm -rf dist",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "mmt-wasm": "file:../../mmt-wasm/pkg"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.0",
+    "vitest": "^1.0.0"
+  },
+  "keywords": [
+    "fec",
+    "raptorq",
+    "rfc6330",
+    "wasm",
+    "forward-error-correction",
+    "streaming"
+  ],
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Blockcast/libmmt.git",
+    "directory": "packages/fec"
+  }
+}

package/src/fec-client.test.ts

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

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

package/src/index.ts

@@ -0,0 +1,31 @@
+/**
+ * @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
+ * import { FecClient } from '@mmt/fec';
+ * import * as wasmModule from '@mmt/wasm';
+ *
+ * const client = new FecClient({ interleaveDepth: 30 });
+ * await client.init(wasmModule);
+ *
+ * // Configure from OTI
+ * client.configure(otiBytes);
+ *
+ * // Add source/repair symbols
+ * const recovered = client.addRepair(sbn, esi, data, timestamp);
+ * ```
+ */
+
+export {
+	FecClient,
+	getSharedFecClient,
+	resetSharedFecClient,
+	type FecConfig,
+	type FecClientOptions,
+	type FecProcessingStats,
+	type FecWasmModule,
+} from "./fec-client.js";