@blockcast/mmt-fec 0.1.0 → 0.3.0

package/src/repair-group.ts

@@ -0,0 +1,195 @@
+/**
+ * MoQ repair group ids for `iso-ssbg1-v1` FEC blocks (BLO-35597, decision D2(a)).
+ *
+ * SS_ID and SS_Start are 32-bit wire fields that wrap at 2^32 (ISO/IEC
+ * 23008-1 C.5.2, C.5.3; RFC 1982 serial arithmetic). A MoQ group id is a
+ * 62-bit unsigned integer that must never go backwards, so the repair group
+ * of an `iso-ssbg1-v1` block is the wrap-epoch-extended SS_Start:
+ *
+ *   ext(SS_Start) = (wrap_epoch << 32) | SS_Start
+ *
+ * Repair group ids are therefore sparse (one per block, at the block's first
+ * SS_ID) and strictly increasing. A receiver that lost SS_ID x in a block it
+ * has not delimited FETCHes the absolute group range of draft-ramadan-moq-fec
+ * §7.5 (`repairFetchRange`); the last group that range returns is the block
+ * containing x.
+ *
+ * A receiver establishes its wrap-epoch reference from the Group ID of a
+ * repair object it received over MoQ, from the Largest Location a
+ * TRACK_STATUS for a repair track reports, or as epoch 0 when it observed the
+ * instance from its first block (draft-ramadan-moq-fec §7.5). The first two
+ * take the epoch from a Group ID itself (`groupId >> 32`): the publisher
+ * assigns repair Group IDs and MoQ delivers them unaltered, so a delivered
+ * Group ID is the epoch reference, on the same footing as the Largest
+ * Location, not a candidate for this module to verify. Nothing a receiver
+ * holds before its first reference can check an epoch: without one,
+ * `repairGroupIdMatches` checks only the low 32 bits, and its `true` means
+ * "this object can be this block's", never "this epoch is verified". It
+ * screens out an object to discard; it does not confirm an epoch. No other
+ * value is an epoch reference: not a group id computed from a 32-bit SS_ID,
+ * and not one carried in a payload rather than as an object's MoQ Group ID.
+ *
+ * All values are bigint: 62-bit group ids exceed Number's 2^53 exact range.
+ */
+import { SERIAL32_HALF, SERIAL32_SPAN, serial32Distance } from "@blockcast/mmt-base";
+
+/** Bits of a MoQ group id above the 32-bit SS_Start: 62 - 32. */
+const WRAP_EPOCH_BITS = 30n;
+/** 2^32 as a bigint: the SS_ID wrap and the shift of the wrap epoch. */
+const SS_ID_SPAN = BigInt(SERIAL32_SPAN);
+/** Exclusive bound of the wrap epoch: 2^30. */
+const WRAP_EPOCH_SPAN = 1n << WRAP_EPOCH_BITS;
+/** Exclusive bound of a MoQ group id: 2^62. */
+const MOQ_GROUP_ID_SPAN = WRAP_EPOCH_SPAN * SS_ID_SPAN;
+
+function assertSsId(value: number, name: string): void {
+	if (!Number.isInteger(value) || value < 0 || value >= SERIAL32_SPAN) {
+		throw new RangeError(`${name} must be a uint32 SS_ID (got ${value})`);
+	}
+}
+
+function assertGroupId(value: bigint, name: string): void {
+	if (typeof value !== "bigint" || value < 0n || value >= MOQ_GROUP_ID_SPAN) {
+		throw new RangeError(`${name} must be a 62-bit MoQ group id in [0, 2^62) (got ${String(value)})`);
+	}
+}
+
+/**
+ * The MoQ repair group id of an `iso-ssbg1-v1` block: `(wrapEpoch << 32) | ssStart`.
+ *
+ * @param wrapEpoch - How many times SS_ID has wrapped before this block, in `[0, 2^30)`
+ * @param ssStart - The block's SS_Start (uint32) from its Repair FEC Payload ID
+ * @returns The 62-bit repair group id
+ * @throws RangeError unless `ssStart` is a uint32 and `wrapEpoch` a bigint in `[0, 2^30)`
+ */
+export function extSsStart(wrapEpoch: bigint, ssStart: number): bigint {
+	if (typeof wrapEpoch !== "bigint" || wrapEpoch < 0n || wrapEpoch >= WRAP_EPOCH_SPAN) {
+		throw new RangeError(`wrap epoch must be a bigint in [0, 2^30) (got ${String(wrapEpoch)})`);
+	}
+	assertSsId(ssStart, "ssStart");
+	return (wrapEpoch << 32n) | BigInt(ssStart);
+}
+
+/**
+ * Extend a 32-bit SS_ID to the 62-bit value congruent to it mod 2^32 that is
+ * nearest `reference` in RFC 1982 serial order: forward when `ssId` follows
+ * the reference's low 32 bits serially, backward when it precedes them, and
+ * `reference` itself when they are equal.
+ *
+ * @param reference - A 62-bit extended SS_ID or repair group id the receiver already holds
+ * @param ssId - The 32-bit SS_ID (or SS_Start) to extend
+ * @returns The extended 62-bit value
+ * @throws RangeError when `ssId` lies exactly 2^31 from the reference's low
+ *   32 bits (RFC 1982 leaves that pair unordered, so no direction exists), or
+ *   when the extension falls outside `[0, 2^62)`
+ */
+export function extendSsId(reference: bigint, ssId: number): bigint {
+	assertGroupId(reference, "reference");
+	assertSsId(ssId, "ssId");
+	const low = Number(reference & (SS_ID_SPAN - 1n));
+	const forward = serial32Distance(low, ssId);
+	if (forward === SERIAL32_HALF) {
+		throw new RangeError(
+			`SS_ID ${ssId} is exactly 2^31 from ${low}; RFC 1982 leaves the pair unordered`,
+		);
+	}
+	const extended = forward < SERIAL32_HALF
+		? reference + BigInt(forward)
+		: reference - BigInt(SERIAL32_SPAN - forward);
+	if (extended < 0n || extended >= MOQ_GROUP_ID_SPAN) {
+		throw new RangeError(
+			`SS_ID ${ssId} extends from ${String(reference)} to ${String(extended)}, outside [0, 2^62)`,
+		);
+	}
+	return extended;
+}
+
+/** An absolute, inclusive MoQ group range for a repair FETCH. */
+export interface RepairFetchRange {
+	/** First group of the FETCH. */
+	readonly startGroup: bigint;
+	/** Last group of the FETCH: the extended lost SS_ID. */
+	readonly endGroup: bigint;
+}
+
+/** What a lost SS_ID is extended from (draft-ramadan-moq-fec §7.5). */
+export type RepairFetchAnchor =
+	/** ext(S_prev): the extended SS_Start of the last block the receiver
+	 *  delimited that ends before the lost SS_ID. The caller vouches for that
+	 *  ordering; only a lost SS_ID at or before the block's start is
+	 *  detectable here, since the block's length is not an input. */
+	| { readonly previousBlockStart: bigint }
+	/** The reference value r of the receiver's wrap epoch, when it has
+	 *  delimited no block that ends before the lost SS_ID. */
+	| { readonly reference: bigint };
+
+/**
+ * The repair FETCH for a lost SS_ID x whose block the receiver has not
+ * delimited (draft-ramadan-moq-fec §7.5): the absolute, inclusive group range
+ *
+ *   [max(ext(S_prev) + 1, ext(x) - (K - 1)), ext(x)]
+ *
+ * or, with no S_prev, `[max(ext(x) - (K - 1), 0), ext(x)]`, where ext(x) is x
+ * extended relative to ext(S_prev), or else to the epoch reference r. Repair
+ * group ids sit at block starts and no block holds more than K source symbols,
+ * so the block containing x starts at most K - 1 SS_IDs before x and is the
+ * last group the range returns. The range is never empty.
+ *
+ * @param lostSsId - The lost 32-bit SS_ID x
+ * @param kMax - K: the instance's catalog `sourceSymbols`, the largest
+ *   SSB_length a block can have
+ * @param anchor - ext(S_prev), or the epoch reference r without one
+ * @throws RangeError when `kMax` is not a positive safe integer, when x does
+ *   not extend past `previousBlockStart`, or whenever {@link extendSsId} throws
+ */
+export function repairFetchRange(lostSsId: number, kMax: number, anchor: RepairFetchAnchor): RepairFetchRange {
+	if (!Number.isSafeInteger(kMax) || kMax <= 0) {
+		throw new RangeError(`kMax must be a positive integer (got ${kMax})`);
+	}
+	let floor: bigint;
+	let endGroup: bigint;
+	if ("previousBlockStart" in anchor) {
+		assertGroupId(anchor.previousBlockStart, "previousBlockStart");
+		floor = anchor.previousBlockStart + 1n;
+		endGroup = extendSsId(anchor.previousBlockStart, lostSsId);
+		if (endGroup < floor) {
+			throw new RangeError(
+				`lost SS_ID ${lostSsId} extends to ${String(endGroup)}, not after the previous block at ${String(anchor.previousBlockStart)}`,
+			);
+		}
+	} else {
+		floor = 0n;
+		endGroup = extendSsId(anchor.reference, lostSsId);
+	}
+	const reach = endGroup - BigInt(kMax - 1);
+	return { startGroup: reach > floor ? reach : floor, endGroup };
+}
+
+/**
+ * Whether a repair object received over MoQ may be used: its Group ID must
+ * agree with the SS_Start of its Repair FEC Payload ID, which is authoritative
+ * (draft-ramadan-moq-fec §7.5). The Group ID must equal SS_Start modulo 2^32
+ * and, once the receiver holds an epoch reference, equal ext(SS_Start)
+ * extended relative to it. A receiver discards a repair object for which this
+ * is false, leaving every block's state unchanged, and never takes its Group
+ * ID as an epoch reference. An SS_Start that cannot be extended (exactly 2^31
+ * from the reference) cannot be checked, so it does not match either.
+ *
+ * @param groupId - The repair object's MoQ Group ID
+ * @param ssStart - The SS_Start of its Repair FEC Payload ID
+ * @param reference - The receiver's epoch reference r, once it holds one
+ * @throws RangeError unless `ssStart` is a uint32 or `reference` (when given)
+ *   a 62-bit group id
+ */
+export function repairGroupIdMatches(groupId: bigint, ssStart: number, reference?: bigint): boolean {
+	assertSsId(ssStart, "ssStart");
+	if (reference !== undefined) assertGroupId(reference, "reference");
+	if (typeof groupId !== "bigint" || groupId < 0n || groupId >= MOQ_GROUP_ID_SPAN) return false;
+	if ((groupId & (SS_ID_SPAN - 1n)) !== BigInt(ssStart)) return false;
+	if (reference === undefined) return true;
+	try {
+		return extendSsId(reference, ssStart) === groupId;
+	} catch {
+		return false;
+	}
+}

package/dist/fec-client.d.ts

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

@@ -1 +0,0 @@
-{"version":3,"file":"fec-client.d.ts","sourceRoot":"","sources":["../src/fec-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,UAAU,cAAc;IACvB,SAAS,CAAC,GAAG,EAAE,UAAU,GAAG,IAAI,CAAC;IACjC,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,CAAC;IAClG,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,CAAC;IAClG,OAAO,CAAC,YAAY,EAAE,MAAM,GAAG,UAAU,CAAC;IAC1C,SAAS,IAAI,YAAY,CAAC;IAC1B,WAAW,IAAI,IAAI,CAAC;IACpB,KAAK,IAAI,IAAI,CAAC;IACd,WAAW,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IACtC,cAAc,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IACvC,cAAc,IAAI,MAAM,CAAC;CACzB;AAED,UAAU,YAAY;IACrB,cAAc,EAAE,MAAM,CAAC;IACvB,cAAc,EAAE,MAAM,CAAC;IACvB,eAAe,EAAE,MAAM,CAAC;IACxB,gBAAgB,EAAE,MAAM,CAAC;IACzB,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,IAAI,MAAM,CAAC;CACxB;AAED,UAAU,gBAAgB;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;CACZ;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IAClC,8BAA8B;IAC9B,aAAa,EAAE,MAAM,CAAC;IACtB,8BAA8B;IAC9B,aAAa,EAAE,MAAM,CAAC;IACtB,qDAAqD;IACrD,cAAc,EAAE,MAAM,CAAC;IACvB,+BAA+B;IAC/B,eAAe,EAAE,MAAM,CAAC;IACxB,oCAAoC;IACpC,YAAY,EAAE,MAAM,CAAC;IACrB,6BAA6B;IAC7B,YAAY,EAAE,MAAM,CAAC;IACrB,uEAAuE;IACvE,eAAe,EAAE,MAAM,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IACzB,+BAA+B;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,kCAAkC;IAClC,YAAY,EAAE,MAAM,CAAC;IACrB,uDAAuD;IACvD,SAAS,EAAE,MAAM,CAAC;IAClB,2DAA2D;IAC3D,SAAS,EAAE,MAAM,CAAC;IAClB,kEAAkE;IAClE,eAAe,EAAE,MAAM,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAChC,8DAA8D;IAC9D,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,oDAAoD;IACpD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,0DAA0D;IAC1D,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,8CAA8C;IAC9C,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC;IAC5D,oCAAoC;IACpC,WAAW,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC;IAC1C,gCAAgC;IAChC,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,kBAAkB,KAAK,IAAI,CAAC;CACpD;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC7B,IAAI,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;IAC7B,aAAa,EAAE,KAAK,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,KAAK,cAAc,CAAC;IACvE,oBAAoB,EAAE,CAAC,IAAI,EAAE,UAAU,KAAK,gBAAgB,CAAC;IAC7D,eAAe,EAAE,MAAM,OAAO,CAAC;CAC/B;AAED;;;;;GAKG;AACH,qBAAa,SAAS;IACrB,OAAO,CAAC,UAAU,CAA+B;IACjD,OAAO,CAAC,OAAO,CAA6B;IAC5C,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,cAAc,CAAK;IAC3B,OAAO,CAAC,eAAe,CAA+C;IAGtE,OAAO,CAAC,UAAU,CAA8B;gBAEpC,OAAO,GAAE,gBAAqB;IAW1C;;OAEG;IACH,aAAa,CAAC,MAAM,EAAE,aAAa,GAAG,IAAI;IAI1C;;OAEG;IACG,IAAI,CAAC,UAAU,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;IA0BrD;;OAEG;IACH,aAAa,IAAI,OAAO;IAIxB;;;OAGG;IACH,SAAS,CAAC,GAAG,EAAE,UAAU,GAAG,IAAI;IAOhC;;;;;;;;OAQG;IACH,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI;IAK3F;;;;;;;;OAQG;IACH,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI;IAkB3F;;;;;;;OAOG;IACH,mBAAmB,CAAC,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI;IAc9E;;;OAGG;IACH,OAAO,IAAI,IAAI;IAgBf;;OAEG;IACH,gBAAgB,IAAI,MAAM;IAI1B;;OAEG;IACH,QAAQ,IAAI,kBAAkB;IAc9B;;;OAGG;IACH,SAAS,IAAI,SAAS;IAUtB;;OAEG;IACH,UAAU,IAAI,IAAI;IAKlB;;OAEG;IACH,OAAO,IAAI,IAAI;CAQf;AAOD,wBAAsB,kBAAkB,CACvC,UAAU,EAAE,aAAa,EACzB,OAAO,CAAC,EAAE,gBAAgB,GACxB,OAAO,CAAC,SAAS,CAAC,CAMpB;AAED,wBAAgB,oBAAoB,IAAI,IAAI,CAK3C"}

package/dist/fec-client.js

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

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