@blockcast/mmt-container 0.1.0 → 0.3.0

package/dist/mmtp-decode-pipeline.d.ts

@@ -0,0 +1,138 @@
+/**
+ * MmtpDecodePipeline — unified MMTP decode pipeline for MoQ and multicast paths.
+ *
+ * Wraps MmtpContainerParser with optional FEC client integration and a keyframe gate.
+ * Designed for the MoQ decode path (hang-mmt-fec audio/video decoders).
+ *
+ * Two entry points:
+ * - feedMoqObject(): raw MMTP packets from MoQ QUIC streams
+ * - feedAssembledFrame(): pre-assembled codec frames from multicast (post-reassembly)
+ */
+import { type FrameMeta, type MmtpReorderStats } from './mmtp-container-parser.js';
+import type { MfuReassemblerBackend, MmtpDeliveryProvenance } from './mfu-reassembler.js';
+import type { MfuReassemblyPolicy } from './mfu-reassembly-policy.js';
+/**
+ * Minimal FEC client interface for source symbol feeding.
+ *
+ * `addSourceSymbol` sees each MoQ object before the parser does, and the
+ * header parsed for it is reused for the parser's feed, so it must not modify
+ * the bytes it is given.
+ */
+export interface PipelineFecClient {
+    addSourceSymbol?(ssId: number, data: Uint8Array): Uint8Array | null;
+}
+export interface PipelineConfig {
+    codec: string;
+    /** Catalog video cadence exposed to downstream media stages. */
+    framerate?: number;
+    /** Catalog MMTP group duration exposed to downstream media stages. */
+    groupDurationMs?: number;
+    /** MMTP packet_id for this track — from catalog. When omitted, parser accepts all packetIds. */
+    packetId?: number;
+    description?: Uint8Array;
+    reorderWindow?: number;
+    /**
+     * MFU reassembly timeout (ms). Caller derives from catalog `fec.interleaveDepthMs`,
+     * already in milliseconds (FFmpeg `moqenc_mmt.c` converts depth-in-frames →
+     * `depth_ms = fec_depth * (1000/fps)` before set_fec_config). Defaults to
+     * 1000ms when omitted. Pass null for reliable, clock-free MoQ streams;
+     * incomplete MFUs then remain bounded by the reassembler's memory limit.
+     */
+    mfuTimeoutMs?: number | null;
+    /** Explicit transport policy; preferred over mfuTimeoutMs. */
+    reassemblyPolicy?: MfuReassemblyPolicy;
+    /** Shared Rust/WASM backend for browser playback. */
+    reassembler?: MfuReassemblerBackend;
+    maxBufferedMfus?: number;
+}
+type FrameCallback = (data: Uint8Array, meta: FrameMeta) => void;
+type InitCallback = (data: Uint8Array, packetId: number) => void;
+/**
+ * Snapshot of one pipeline's feed tallies.
+ *
+ * These counters were console-only, and a player builds one pipeline per track,
+ * so two instances logged indistinguishably and the audio receive path could not
+ * be read at all from a harness artifact. Expose them as a producer-owned typed
+ * counter — logs are diagnostic output, not an acceptance API.
+ */
+export interface MmtpFeedStats {
+    /** Track identity, so a consumer can tell two concurrent pipelines apart. */
+    trackType: 'video' | 'audio' | null;
+    codec: string | null;
+    fedObjects: number;
+    emitted: number;
+    gateDropped: number;
+    /**
+     * feed() exit-path tallies, keyed by record kind, with
+     * 'null(parse-or-extract-failed)' for the early returns and 'threw' when
+     * parseHeader()/feed() raises. Mutually exclusive: the values sum to
+     * fedObjects on every path (the throw bucket is tallied in a finally), which
+     * is what makes a frozen media bucket beside a still-climbing non-media
+     * bucket a readable signal.
+     */
+    outcomes: Record<string, number>;
+}
+export declare class MmtpDecodePipeline {
+    #private;
+    /** Configure the inner parser. Call before feedMoqObject(). */
+    configure(config: PipelineConfig): void;
+    /** Inject a FEC client for source symbol feeding on the MoQ path. */
+    setFecClient(client: PipelineFecClient): void;
+    /** Register frame output callback. */
+    onFrame(cb: FrameCallback): void;
+    /** Register init segment callback. */
+    onInit(cb: InitCallback): void;
+    /** Current shared-parser ordering/drop telemetry. */
+    get reorderStats(): Readonly<MmtpReorderStats> | null;
+    /**
+     * Feed tallies for this track. A fresh snapshot per call, not a live view.
+     *
+     * Unlike reorderStats this never returns null: the counters belong to the
+     * pipeline rather than the parser, so they survive dispose(). That is
+     * deliberate — a wedged pipeline is usually read after teardown, which is
+     * exactly when the parser is already gone.
+     */
+    get feedStats(): Readonly<MmtpFeedStats>;
+    /**
+     * Feed a raw MoQ object payload (one MMTP packet per MoQ object).
+     * Optionally feeds source symbols to FEC client before parsing.
+     */
+    feedMoqObject(packet: Uint8Array): void;
+    /**
+     * Feed a pre-assembled codec frame (from multicast, post-reassembly).
+     * Bypasses MMTP parsing — emits directly through the keyframe gate.
+     *
+     * Callers MUST supply:
+     *   - packetSequenceNumber: unique per-AU identifier (typically the MMTP
+     *     packet_sequence_number of the first fragment). Required for
+     *     deterministic dedup against duplicates arriving via other paths.
+     *   - packetId: MMTP packet_id of the track (1=video, 2=audio by convention).
+     */
+    feedAssembledFrame(data: Uint8Array, meta: {
+        timestamp: number;
+        /** Raw MMTP short-NTP header timestamp; timing telemetry only. */
+        mmtpTimestamp?: bigint;
+        keyframe: boolean;
+        packetSequenceNumber: number;
+        packetId: number;
+        sourceDiscontinuity?: boolean;
+        recovered?: boolean;
+        /**
+         * Whole-frame delivery provenance, when the caller knows it. Absent means
+         * the caller never told us — which is NOT the same as 'unknown', a
+         * verdict the caller reached and is asserting. Keep them distinguishable.
+         */
+        deliveryProvenance?: MmtpDeliveryProvenance;
+    }): void;
+    /** Request keyframe — gates output until a keyframe arrives. */
+    requestKeyframe(): void;
+    /** Emit buffered ordered frames. Finite consumers call this before dispose(). */
+    flush(): void;
+    /** Clean up the pipeline. Finite inputs pass flush=true at EOS; live
+     * cancellation keeps the default drop-only teardown behavior. */
+    dispose(options?: {
+        flush?: boolean;
+    }): void;
+}
+export {};
+//# sourceMappingURL=mmtp-decode-pipeline.d.ts.map

package/dist/mmtp-decode-pipeline.d.ts.map

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