@blockcast/mmt-container 0.1.0-main.149f78a4adae

package/dist/mfu-reassembly-policy.js

@@ -0,0 +1,99 @@
+// src/mfu-reassembly-policy.ts
+function validateReliableMoqOptionShape(value) {
+  const unsupported = Object.keys(value).filter(
+    (key) => key !== "transport" && key !== "startsAtRandomAccessGroup"
+  );
+  if (unsupported.length > 0) {
+    if (unsupported.includes("maxRacingGroups")) {
+      throw new Error(
+        "[MFU reassembly] maxRacingGroups was removed; reliable MoQ completion is transport-owned"
+      );
+    }
+    throw new Error(
+      `[MFU reassembly] unsupported reliable MoQ option(s): ${unsupported.join(", ")}`
+    );
+  }
+  const startsAtRandomAccessGroup = value["startsAtRandomAccessGroup"];
+  if (typeof startsAtRandomAccessGroup !== "boolean" && startsAtRandomAccessGroup !== void 0) {
+    throw new Error("[MFU reassembly] startsAtRandomAccessGroup must be boolean");
+  }
+}
+function reliableMoqMfuReassembly(options = {}) {
+  if (arguments.length > 1 || typeof options !== "object" || options === null || Array.isArray(options)) {
+    throw new Error(
+      "[MFU reassembly] the positional maxRacingGroups API was removed; pass a reliable MoQ options object"
+    );
+  }
+  validateReliableMoqOptionShape(options);
+  return options.startsAtRandomAccessGroup ? {
+    transport: "reliable-moq",
+    startsAtRandomAccessGroup: true
+  } : { transport: "reliable-moq" };
+}
+function assertValidDatagramDeadline(deadlineMs) {
+  if (typeof deadlineMs !== "number" || !Number.isFinite(deadlineMs) || deadlineMs <= 0) {
+    throw new Error("[MFU reassembly] datagram deadlineMs must be a finite number > 0");
+  }
+}
+function datagramMfuReassembly(deadlineMs) {
+  assertValidDatagramDeadline(deadlineMs);
+  return { transport: "datagram", deadlineMs };
+}
+function assertValidMfuReassemblyPolicy(policy) {
+  if (typeof policy !== "object" || policy === null || Array.isArray(policy)) {
+    throw new Error("[MFU reassembly] policy must be an object");
+  }
+  const value = policy;
+  if (value["transport"] === "reliable-moq") {
+    validateReliableMoqOptionShape(value);
+    if (value["startsAtRandomAccessGroup"] === false) {
+      throw new Error(
+        "[MFU reassembly] startsAtRandomAccessGroup must be true when present in a policy"
+      );
+    }
+    return;
+  }
+  if (value["transport"] === "datagram") {
+    const unsupported = Object.keys(value).filter(
+      (key) => key !== "transport" && key !== "deadlineMs"
+    );
+    if (unsupported.length > 0) {
+      throw new Error(
+        `[MFU reassembly] unsupported datagram option(s): ${unsupported.join(", ")}`
+      );
+    }
+    assertValidDatagramDeadline(value["deadlineMs"]);
+    return;
+  }
+  throw new Error(
+    `[MFU reassembly] unsupported transport: ${String(value["transport"])}`
+  );
+}
+function mfuReassemblyTimeoutMs(policy) {
+  assertValidMfuReassemblyPolicy(policy);
+  return policy.transport === "reliable-moq" ? null : policy.deadlineMs;
+}
+function mmtpFrameReorderWindowFrames(policy, configuredWindow = 0) {
+  assertValidMfuReassemblyPolicy(policy);
+  if (!Number.isFinite(configuredWindow) || configuredWindow < 0) {
+    throw new Error("[MFU reassembly] configuredWindow must be a finite number >= 0");
+  }
+  const requested = Math.ceil(configuredWindow);
+  if (policy.transport === "reliable-moq") {
+    if (requested > 0) {
+      throw new Error(
+        "[MFU reassembly] reliable MoQ paths do not accept a frame reorder window in the parser"
+      );
+    }
+    return 0;
+  }
+  return requested;
+}
+export {
+  assertValidMfuReassemblyPolicy,
+  datagramMfuReassembly,
+  mfuReassemblyTimeoutMs,
+  mmtpFrameReorderWindowFrames,
+  reliableMoqMfuReassembly
+};
+//# sourceMappingURL=mfu-reassembly-policy.js.map

package/dist/mfu-reassembly-policy.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/mfu-reassembly-policy.ts"],
+  "sourcesContent": ["export type MfuReassemblyPolicy =\n  | ReliableMoqReassemblyPolicy\n  | { transport: 'datagram'; deadlineMs: number }\n\nexport interface ReliableMoqReassemblyPolicy {\n  transport: 'reliable-moq'\n  startsAtRandomAccessGroup?: true\n}\n\nexport type MmtpTrackType = 'video' | 'audio' | null\n\nexport interface ReliableMoqReassemblyOptions {\n  /**\n   * The transport starts at a complete independently decodable media group.\n   * The parser still requires an observed RAP before decoder startup.\n   */\n  startsAtRandomAccessGroup?: boolean\n}\n\nfunction validateReliableMoqOptionShape(value: Record<string, unknown>): void {\n  const unsupported = Object.keys(value).filter(\n    key => key !== 'transport' && key !== 'startsAtRandomAccessGroup',\n  )\n  if (unsupported.length > 0) {\n    if (unsupported.includes('maxRacingGroups')) {\n      throw new Error(\n        '[MFU reassembly] maxRacingGroups was removed; reliable MoQ completion is transport-owned',\n      )\n    }\n    throw new Error(\n      `[MFU reassembly] unsupported reliable MoQ option(s): ${unsupported.join(', ')}`,\n    )\n  }\n  const startsAtRandomAccessGroup = value['startsAtRandomAccessGroup']\n  if (\n    typeof startsAtRandomAccessGroup !== 'boolean' &&\n    startsAtRandomAccessGroup !== undefined\n  ) {\n    throw new Error('[MFU reassembly] startsAtRandomAccessGroup must be boolean')\n  }\n}\n\nexport function reliableMoqMfuReassembly(\n  options: ReliableMoqReassemblyOptions = {},\n): ReliableMoqReassemblyPolicy {\n  if (\n    arguments.length > 1 ||\n    typeof options !== 'object' ||\n    options === null ||\n    Array.isArray(options)\n  ) {\n    throw new Error(\n      '[MFU reassembly] the positional maxRacingGroups API was removed; pass a reliable MoQ options object',\n    )\n  }\n  validateReliableMoqOptionShape(options as Record<string, unknown>)\n  return options.startsAtRandomAccessGroup\n    ? {\n        transport: 'reliable-moq',\n        startsAtRandomAccessGroup: true,\n      }\n    : { transport: 'reliable-moq' }\n}\n\nfunction assertValidDatagramDeadline(deadlineMs: unknown): asserts deadlineMs is number {\n  if (typeof deadlineMs !== 'number' || !Number.isFinite(deadlineMs) || deadlineMs <= 0) {\n    throw new Error('[MFU reassembly] datagram deadlineMs must be a finite number > 0')\n  }\n}\n\nexport function datagramMfuReassembly(deadlineMs: number): MfuReassemblyPolicy {\n  assertValidDatagramDeadline(deadlineMs)\n  return { transport: 'datagram', deadlineMs }\n}\n\n/** Validate the complete runtime shape even when a caller bypasses the policy factories. */\nexport function assertValidMfuReassemblyPolicy(policy: MfuReassemblyPolicy): void {\n  if (typeof policy !== 'object' || policy === null || Array.isArray(policy)) {\n    throw new Error('[MFU reassembly] policy must be an object')\n  }\n\n  const value = policy as unknown as Record<string, unknown>\n  if (value['transport'] === 'reliable-moq') {\n    validateReliableMoqOptionShape(value)\n    if (value['startsAtRandomAccessGroup'] === false) {\n      throw new Error(\n        '[MFU reassembly] startsAtRandomAccessGroup must be true when present in a policy',\n      )\n    }\n    return\n  }\n  if (value['transport'] === 'datagram') {\n    const unsupported = Object.keys(value).filter(\n      key => key !== 'transport' && key !== 'deadlineMs',\n    )\n    if (unsupported.length > 0) {\n      throw new Error(\n        `[MFU reassembly] unsupported datagram option(s): ${unsupported.join(', ')}`,\n      )\n    }\n    assertValidDatagramDeadline(value['deadlineMs'])\n    return\n  }\n  throw new Error(\n    `[MFU reassembly] unsupported transport: ${String(value['transport'])}`,\n  )\n}\n\nexport function mfuReassemblyTimeoutMs(policy: MfuReassemblyPolicy): number | null {\n  assertValidMfuReassemblyPolicy(policy)\n  return policy.transport === 'reliable-moq' ? null : policy.deadlineMs\n}\n\n/** Resolve the parser reorder window without inferring reliable-stream completion. */\nexport function mmtpFrameReorderWindowFrames(\n  policy: MfuReassemblyPolicy,\n  configuredWindow = 0,\n): number {\n  assertValidMfuReassemblyPolicy(policy)\n  if (!Number.isFinite(configuredWindow) || configuredWindow < 0) {\n    throw new Error('[MFU reassembly] configuredWindow must be a finite number >= 0')\n  }\n\n  const requested = Math.ceil(configuredWindow)\n  if (policy.transport === 'reliable-moq') {\n    if (requested > 0) {\n      throw new Error(\n        '[MFU reassembly] reliable MoQ paths do not accept a frame reorder window in the parser',\n      )\n    }\n    return 0\n  }\n  return requested\n}\n"],
+  "mappings": ";AAmBA,SAAS,+BAA+B,OAAsC;AAC5E,QAAM,cAAc,OAAO,KAAK,KAAK,EAAE;AAAA,IACrC,SAAO,QAAQ,eAAe,QAAQ;AAAA,EACxC;AACA,MAAI,YAAY,SAAS,GAAG;AAC1B,QAAI,YAAY,SAAS,iBAAiB,GAAG;AAC3C,YAAM,IAAI;AAAA,QACR;AAAA,MACF;AAAA,IACF;AACA,UAAM,IAAI;AAAA,MACR,wDAAwD,YAAY,KAAK,IAAI,CAAC;AAAA,IAChF;AAAA,EACF;AACA,QAAM,4BAA4B,MAAM,2BAA2B;AACnE,MACE,OAAO,8BAA8B,aACrC,8BAA8B,QAC9B;AACA,UAAM,IAAI,MAAM,4DAA4D;AAAA,EAC9E;AACF;AAEO,SAAS,yBACd,UAAwC,CAAC,GACZ;AAC7B,MACE,UAAU,SAAS,KACnB,OAAO,YAAY,YACnB,YAAY,QACZ,MAAM,QAAQ,OAAO,GACrB;AACA,UAAM,IAAI;AAAA,MACR;AAAA,IACF;AAAA,EACF;AACA,iCAA+B,OAAkC;AACjE,SAAO,QAAQ,4BACX;AAAA,IACE,WAAW;AAAA,IACX,2BAA2B;AAAA,EAC7B,IACA,EAAE,WAAW,eAAe;AAClC;AAEA,SAAS,4BAA4B,YAAmD;AACtF,MAAI,OAAO,eAAe,YAAY,CAAC,OAAO,SAAS,UAAU,KAAK,cAAc,GAAG;AACrF,UAAM,IAAI,MAAM,kEAAkE;AAAA,EACpF;AACF;AAEO,SAAS,sBAAsB,YAAyC;AAC7E,8BAA4B,UAAU;AACtC,SAAO,EAAE,WAAW,YAAY,WAAW;AAC7C;AAGO,SAAS,+BAA+B,QAAmC;AAChF,MAAI,OAAO,WAAW,YAAY,WAAW,QAAQ,MAAM,QAAQ,MAAM,GAAG;AAC1E,UAAM,IAAI,MAAM,2CAA2C;AAAA,EAC7D;AAEA,QAAM,QAAQ;AACd,MAAI,MAAM,WAAW,MAAM,gBAAgB;AACzC,mCAA+B,KAAK;AACpC,QAAI,MAAM,2BAA2B,MAAM,OAAO;AAChD,YAAM,IAAI;AAAA,QACR;AAAA,MACF;AAAA,IACF;AACA;AAAA,EACF;AACA,MAAI,MAAM,WAAW,MAAM,YAAY;AACrC,UAAM,cAAc,OAAO,KAAK,KAAK,EAAE;AAAA,MACrC,SAAO,QAAQ,eAAe,QAAQ;AAAA,IACxC;AACA,QAAI,YAAY,SAAS,GAAG;AAC1B,YAAM,IAAI;AAAA,QACR,oDAAoD,YAAY,KAAK,IAAI,CAAC;AAAA,MAC5E;AAAA,IACF;AACA,gCAA4B,MAAM,YAAY,CAAC;AAC/C;AAAA,EACF;AACA,QAAM,IAAI;AAAA,IACR,2CAA2C,OAAO,MAAM,WAAW,CAAC,CAAC;AAAA,EACvE;AACF;AAEO,SAAS,uBAAuB,QAA4C;AACjF,iCAA+B,MAAM;AACrC,SAAO,OAAO,cAAc,iBAAiB,OAAO,OAAO;AAC7D;AAGO,SAAS,6BACd,QACA,mBAAmB,GACX;AACR,iCAA+B,MAAM;AACrC,MAAI,CAAC,OAAO,SAAS,gBAAgB,KAAK,mBAAmB,GAAG;AAC9D,UAAM,IAAI,MAAM,gEAAgE;AAAA,EAClF;AAEA,QAAM,YAAY,KAAK,KAAK,gBAAgB;AAC5C,MAAI,OAAO,cAAc,gBAAgB;AACvC,QAAI,YAAY,GAAG;AACjB,YAAM,IAAI;AAAA,QACR;AAAA,MACF;AAAA,IACF;AACA,WAAO;AAAA,EACT;AACA,SAAO;AACT;",
+  "names": []
+}

package/dist/mmtp-container-parser.d.ts

@@ -0,0 +1,304 @@
+import { MfuReassemblyError, type MfuReassemblerBackend, type MmtpSourcePath, type MmtpDeliveryProvenance } from './mfu-reassembler.js';
+import { SampleCombineError, type SampleCombinerStats } from './sample-combiner.js';
+import { type MfuReassemblyPolicy } from './mfu-reassembly-policy.js';
+import type { AuthoredTiming } from './authored-timing.js';
+export interface TrackInfo {
+    type: 'video' | 'audio';
+    codec: string;
+    /** Catalog/in-band frame cadence available to downstream media stages. */
+    framerate?: number;
+    /** Catalog MMTP group duration available to downstream media stages. */
+    groupDurationMs?: number;
+}
+export interface MmtpParserConfig {
+    tracks?: Map<number, TrackInfo>;
+    reorderWindow?: number;
+    /** MFU reassembly timeout (ms). Derive from FEC interleaveDepthMs or frame duration.
+     *  Pass null for live clock-free operation; memory remains bounded by maxBuffered.
+     *  Defaults to 1000ms if not provided. */
+    mfuTimeoutMs?: number | null;
+    /** Explicit transport policy. Reliable MoQ is clock-free; datagrams require
+     * a catalog/in-band-derived deadline. Mutually exclusive with mfuTimeoutMs. */
+    reassemblyPolicy?: MfuReassemblyPolicy;
+    /** Max concurrent active MFUs. A new first fragment is rejected at the bound. */
+    maxBufferedMfus?: number;
+    /**
+     * Max subsample data units held for one partitioned sample (moqcast #37).
+     * A sample needs `ceil(sampleSize / (256 * maxPayload))` data units; at the
+     * ~1300-byte payloads this producer emits, one data unit spans ~327 KB, so
+     * the default admits a ~5 MB sample — beyond any 8K intra frame — while
+     * still bounding the per-insert overlap scan. Raise it only alongside a
+     * larger authored frame size, never to paper over a lost data unit.
+     */
+    maxSubsampleSegments?: number;
+    /** Alternate backend. The TypeScript and Rust/WASM implementations enforce
+     * the same authored active-DU contract. */
+    reassembler?: MfuReassemblerBackend;
+    /** Default track info for auto-discovered packetIds.
+     *  When the parser receives an MMTP packet with an unregistered packetId,
+     *  it creates a new track entry using this info. Required for correct
+     *  keyframe detection with HEVC/AV1/VP9 (without it, defaults to H.264). */
+    defaultTrack?: TrackInfo;
+}
+/** Structured result from parseHeader(). Used by MmtpRouter for two-phase parsing:
+ *  1. parseHeader() → get packetId + fecPayloadId for FEC feeding
+ *  2. feed() → MFU extraction, reassembly, keyframe detection, emit */
+export interface PacketInfo {
+    packetId: number;
+    packetType: number;
+    timestamp: bigint;
+    /** MMTP timestamp converted to monotonic microseconds for pacing/sync users. */
+    timestampUs: number;
+    sequenceNumber: number;
+    rapFlag: boolean;
+    fecType: number;
+    /** FEC source symbol ID (from 4-byte FEC Payload ID at packet end). Null if no FEC. */
+    fecPayloadId: {
+        ssId: number;
+    } | null;
+    /** True if this is a repair packet (packetType=0x03). */
+    isRepair: boolean;
+}
+export interface FrameMeta {
+    /** Authored ISO-BMFF presentation time converted to microseconds. */
+    timestamp: number;
+    /** Authored ISO-BMFF decode time converted to microseconds. */
+    decodeTimestamp?: number;
+    /** Authored ISO-BMFF sample duration converted to microseconds. */
+    duration?: number;
+    /** Exact authored decode time in mediaTimescale units. */
+    decodeTime?: bigint;
+    /** Exact authored presentation time in mediaTimescale units. */
+    presentationTime?: bigint;
+    /** Exact authored duration in mediaTimescale units. */
+    durationTicks?: number;
+    /** mdhd media timescale for the exact timing fields. */
+    mediaTimescale?: number;
+    /** Exact authored ISO-BMFF timing carried without narrowing to microseconds. */
+    authoredTiming?: AuthoredTiming;
+    keyframe: boolean;
+    packetId: number;
+    trackType: 'video' | 'audio' | null;
+    packetSequenceNumber?: number;
+    /** Every authoritative MMTP source-packet sequence that formed this frame. */
+    packetSequenceNumbers?: number[];
+    /** Subset of packetSequenceNumbers reconstructed by FEC. */
+    repairedPacketSequenceNumbers?: number[];
+    /** Immutable catalog identity supplied by the owning ingress subscription. */
+    catalogTrackName?: string;
+    /** Raw MMTP short-NTP timestamp retained for adapters that own the timeline. */
+    mmtpTimestamp?: bigint;
+    mpuSequenceNumber?: number;
+    movieFragmentSequenceNumber?: number;
+    sampleNumber?: number;
+    fragmentCount?: number;
+    rapFlag?: boolean;
+    priority?: number;
+    recovered?: boolean;
+    /** Starts a new publisher/source epoch for ordering and timestamp state. */
+    sourceDiscontinuity?: boolean;
+    /** Source of the accepted FI=1/FI=0 frame path. Absent for recovery. */
+    source?: MmtpSourcePath;
+    /**
+     * Strict whole-frame delivery provenance. Unlike `source`, which names the
+     * head fragment's transport for routing, this is folded over every
+     * contributing fragment (and, for FEC-recovered frames, over the transports
+     * that supplied the block's symbols). Only 'multicast' is evidence of
+     * multicast-exclusive delivery. Absent means no producer on this path
+     * recorded provenance — consumers MUST treat that as unproven, never as
+     * multicast.
+     */
+    deliveryProvenance?: MmtpDeliveryProvenance;
+}
+export interface MmtpReorderStats {
+    droppedBeforeStartupKeyframe: number;
+    droppedIncompleteStartupInterval: number;
+    droppedStale: number;
+    forcedWindowFlushes: number;
+    droppedOnLiveDispose: number;
+    publisherResets: number;
+    droppedOnPublisherReset: number;
+    bufferedFrames: number;
+}
+export interface MmtpReorderFrameDiagnostics {
+    timestampUs: number;
+    keyframe: boolean;
+    sequenceNumber: number;
+    packetSequenceNumber?: number;
+    movieFragmentSequenceNumber?: number;
+    sampleNumber?: number;
+    fragmentCount?: number;
+}
+export interface MmtpReorderStreamDiagnostics {
+    packetId: number;
+    bufferedFrames: number;
+    lastEmitted: MmtpReorderFrameDiagnostics | null;
+    startupKeyframe: MmtpReorderFrameDiagnostics | null;
+    head: MmtpReorderFrameDiagnostics[];
+    tail: MmtpReorderFrameDiagnostics[];
+    keyframes: MmtpReorderFrameDiagnostics[];
+}
+export type MmtpParserRecord = {
+    kind: 'repair' | 'non-media';
+    packet: PacketInfo;
+    byteLength: number;
+} | {
+    kind: 'init' | 'fragment';
+    packet: PacketInfo;
+    data: Uint8Array;
+    mpuSequenceNumber: number;
+    fragmentationIndicator: number;
+    fragmentCounter: number;
+} | {
+    kind: 'pending';
+    packet: PacketInfo;
+    mpuSequenceNumber: number;
+    fragmentationIndicator: number;
+    fragmentCounter: number;
+} | {
+    kind: 'rejected';
+    packet: PacketInfo;
+    mpuSequenceNumber: number;
+    fragmentationIndicator: number;
+    fragmentCounter: number;
+    error: {
+        /**
+         * Either a single data unit's own fragment chain was rejected, or
+         * combining reassembled data units into a sample was (moqcast #37).
+         * Both are fail-closed drops of the same packet, so they share this
+         * record; the code says which class it came from.
+         */
+        code: MfuReassemblyError['code'] | SampleCombineError['code'];
+        message: string;
+    };
+} | {
+    kind: 'frame';
+    packet: PacketInfo;
+    data: Uint8Array;
+    meta: FrameMeta;
+    mpuSequenceNumber: number;
+    fragmentCount: number;
+    rapFlag: boolean;
+    priority?: number;
+};
+type FrameCallback = (data: Uint8Array, meta: FrameMeta) => void;
+type InitCallback = (data: Uint8Array, packetId: number, catalogTrackName?: string) => void;
+export declare function isMfuKeyframeMetadata(rapFlag: boolean, priority?: number): boolean;
+/** Per-packet detached ALTA authenticator trailer (08-07 Path 2).
+ *  - `auth`: the authenticator bytes (length-prefixed at packet end).
+ *  - `payloadEnd`: byte offset within the source packet where signed
+ *     payload ends — consumers reconstruct `payload = packet[0..payloadEnd]`
+ *     for verify_detached. */
+export interface ParsedAltaTrailer {
+    auth: Uint8Array;
+    payloadEnd: number;
+}
+/** Source-symbol exposure for FEC consumers.
+ *
+ *  Fires from {@link MmtpContainerParser.feed} once per FEC-protected source
+ *  packet — after parseHeader confirms fec_payload_id is present, before MFU
+ *  extraction.
+ *
+ *  Arguments:
+ *  - `packetId`  – MMTP header `packet_id` (track identifier)
+ *  - `ssId`      – flat Source Symbol ID from the 4-byte fec_payload_id trailer
+ *  - `rawSymbol` – packet bytes minus the 4-byte fec_payload_id trailer.
+ *                  NOT zero-padded to FEC symbol size — consumer pads if needed
+ *                  (FEC symbol size is FEC-config, not parser-config).
+ *  - `alta`      – detached ALTA authenticator if present, else undefined
+ *
+ *  Designed so consumers (player, Shaka shim, upstream moqtail) can wire
+ *  source-symbol delivery to whatever FEC pipeline they own, without depending
+ *  on libmmt's MulticastManager/MmtpRouter/FECManager stack. */
+type SourceSymbolCallback = (packetId: number, ssId: number, rawSymbol: Uint8Array, alta: ParsedAltaTrailer | undefined) => void;
+export interface ParseHeaderOptions {
+    /** Recovered source symbols already had the trailing Source FEC Payload ID stripped. */
+    skipFecPayloadId?: boolean;
+    /** Mark frames emitted from this packet as FEC-recovered. */
+    recovered?: boolean;
+    /** Exact catalog track bound to this packet by its ingress subscription. */
+    catalogTrackName?: string;
+    /** Source transport for parser-owned frame attribution. */
+    source?: MmtpSourcePath;
+    /**
+     * Explicit strict provenance for the fragments this packet produces.
+     * The router sets it for FEC-recovered packets, which carry no `source`
+     * but whose FEC block's symbol provenance is known.
+     */
+    deliveryProvenance?: MmtpDeliveryProvenance;
+}
+export declare class MmtpContainerParser {
+    #private;
+    constructor(config?: MmtpParserConfig);
+    /** The MFU reassembler that buffers fragmented MFUs fed via feed().
+     *  Exposed so a co-operating FEC-recovery layer (MmtpRouter) feeds recovered
+     *  fragments into the SAME reassembler: a frame split between source-received
+     *  and FEC-recovered fragments must share one buffer to complete (BLO-8151).
+     *  Before this was shared, recovered video symbols reported "0 emitted,
+     *  pending-reassembly=N" because they landed in a separate instance. */
+    get reassembler(): MfuReassemblerBackend;
+    /**
+     * Subsample-combining counters (moqcast #37). `combinedSamples` counts
+     * samples reassembled from two or more data units and `passthroughSamples`
+     * those that arrived whole; the two are deliberately separate, so a
+     * producer that silently stopped partitioning cannot hide behind a single
+     * "samples delivered" total. This is the typed acceptance signal for
+     * large-frame playback — never parse the console for it.
+     */
+    get sampleCombinerStats(): Readonly<SampleCombinerStats>;
+    get reorderStats(): Readonly<MmtpReorderStats>;
+    get reorderDiagnostics(): ReadonlyArray<MmtpReorderStreamDiagnostics>;
+    /**
+     * Phase 1 of two-phase parsing. Returns structured header info for FEC feeding.
+     * Call this before feed() when you need to extract FEC payload ID and feed
+     * symbols to FECManager before MFU extraction.
+     * Returns null for malformed packets.
+     */
+    parseHeader(packet: Uint8Array, options?: ParseHeaderOptions): PacketInfo | null;
+    /** Feed a complete MMTP packet. For two-phase use, call parseHeader() first. */
+    feed(packet: Uint8Array, options?: ParseHeaderOptions): MmtpParserRecord | null;
+    onInit(cb: InitCallback): void;
+    onFrame(cb: FrameCallback): void;
+    /** Register a per-packet FEC source-symbol callback. Fires for each MMTP
+     *  source MPU packet that carries a Source FEC Payload ID (ISO 23008-1 §C.5.2).
+     *
+     *  Consumer responsibilities:
+     *  - Zero-pad `rawSymbol` to the FEC `symbolSize` if shorter (FEC config is
+     *    out-of-band — typically from the CMSF catalog's `fec.symbolSize`).
+     *  - Decide oversized handling (rawSymbol.length > symbolSize is not FEC-
+     *    decodable; consumer typically skips that block's source-feed).
+     *  - Look up the right FEC consumer (e.g. FecWorkerClient) by packetId.
+     *
+     *  Designed for spec-clean reuse: Shaka, upstream moqtail, or any consumer
+     *  that uses MmtpContainerParser can wire FEC source delivery without
+     *  pulling in MulticastManager/MmtpRouter/FECManager. */
+    onSourceSymbol(cb: SourceSymbolCallback): void;
+    onTrackFrame(packetId: number, cb: FrameCallback): void;
+    setTrack(packetId: number, info: TrackInfo): void;
+    /** Drop one physical stream's ordering and MFU state for retained replay. */
+    resetTrack(packetId: number, catalogTrackName: string): void;
+    setMfuTimeoutMs(ms: number | null): void;
+    setReassemblyPolicy(policy: MfuReassemblyPolicy): void;
+    setReorderWindow(windowSize: number): void;
+    /** Route an already-assembled frame through the same reorder/callback path
+     * used by source packets. FEC recovery uses this to merge recovered frames
+     * with direct source frames before the decoder sees them. */
+    routeFrame(data: Uint8Array, meta: FrameMeta): void;
+    /**
+     * Claim and return the authored timing for a recovered sample. Recovery does
+     * not pass through the ordinary `feed()` completion path, so it must retire
+     * the same bounded resolver entry once the router accepts the recovered
+     * sample. A missing entry is a fail-closed signal: callers must not replace
+     * it with an MMTP send timestamp or cadence guess.
+     */
+    consumeAuthoredTimingFor(packetId: number, mpuSequenceNumber: number, movieFragmentSequenceNumber: number | undefined, sampleNumber: number | undefined, catalogTrackName?: string): AuthoredTiming | null;
+    /** Emit all ordered frames currently buffered by the parser. Finite-stream
+     * consumers may call this before dispose(); live cancellation should not. */
+    flush(): void;
+    dispose(): void;
+    /** Authored presentation timestamp of the last emitted frame, in microseconds. */
+    lastFrameTimestamp: number | undefined;
+    static isKeyframe(data: Uint8Array, rapFlag: boolean, codec?: string): boolean;
+}
+export {};
+//# sourceMappingURL=mmtp-container-parser.d.ts.map

package/dist/mmtp-container-parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mmtp-container-parser.d.ts","sourceRoot":"","sources":["../src/mmtp-container-parser.ts"],"names":[],"mappings":"AASA,OAAO,EAEL,kBAAkB,EAClB,KAAK,qBAAqB,EAC1B,KAAK,cAAc,EACnB,KAAK,sBAAsB,EAE5B,MAAM,sBAAsB,CAAA;AAC7B,OAAO,EAEL,kBAAkB,EAGlB,KAAK,mBAAmB,EACzB,MAAM,sBAAsB,CAAA;AAE7B,OAAO,EAGL,KAAK,mBAAmB,EACzB,MAAM,4BAA4B,CAAA;AAMnC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAI1D,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,OAAO,GAAG,OAAO,CAAA;IACvB,KAAK,EAAE,MAAM,CAAA;IACb,0EAA0E;IAC1E,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,wEAAwE;IACxE,eAAe,CAAC,EAAE,MAAM,CAAA;CACzB;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,CAAA;IAC/B,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB;;8CAE0C;IAC1C,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC5B;mFAC+E;IAC/E,gBAAgB,CAAC,EAAE,mBAAmB,CAAA;IACtC,iFAAiF;IACjF,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB;;;;;;;OAOG;IACH,oBAAoB,CAAC,EAAE,MAAM,CAAA;IAC7B;+CAC2C;IAC3C,WAAW,CAAC,EAAE,qBAAqB,CAAA;IACnC;;;gFAG4E;IAC5E,YAAY,CAAC,EAAE,SAAS,CAAA;CACzB;AAED;;uEAEuE;AACvE,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,MAAM,CAAA;IAChB,UAAU,EAAE,MAAM,CAAA;IAClB,SAAS,EAAE,MAAM,CAAA;IACjB,gFAAgF;IAChF,WAAW,EAAE,MAAM,CAAA;IACnB,cAAc,EAAE,MAAM,CAAA;IACtB,OAAO,EAAE,OAAO,CAAA;IAChB,OAAO,EAAE,MAAM,CAAA;IACf,uFAAuF;IACvF,YAAY,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAA;IACrC,yDAAyD;IACzD,QAAQ,EAAE,OAAO,CAAA;CAClB;AAED,MAAM,WAAW,SAAS;IACxB,qEAAqE;IACrE,SAAS,EAAE,MAAM,CAAA;IACjB,+DAA+D;IAC/D,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,mEAAmE;IACnE,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,0DAA0D;IAC1D,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,gEAAgE;IAChE,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,uDAAuD;IACvD,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,wDAAwD;IACxD,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,gFAAgF;IAChF,cAAc,CAAC,EAAE,cAAc,CAAA;IAC/B,QAAQ,EAAE,OAAO,CAAA;IACjB,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,EAAE,OAAO,GAAG,OAAO,GAAG,IAAI,CAAA;IACnC,oBAAoB,CAAC,EAAE,MAAM,CAAA;IAC7B,8EAA8E;IAC9E,qBAAqB,CAAC,EAAE,MAAM,EAAE,CAAA;IAChC,4DAA4D;IAC5D,6BAA6B,CAAC,EAAE,MAAM,EAAE,CAAA;IACxC,8EAA8E;IAC9E,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,gFAAgF;IAChF,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B,2BAA2B,CAAC,EAAE,MAAM,CAAA;IACpC,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,4EAA4E;IAC5E,mBAAmB,CAAC,EAAE,OAAO,CAAA;IAC7B,wEAAwE;IACxE,MAAM,CAAC,EAAE,cAAc,CAAA;IACvB;;;;;;;;OAQG;IACH,kBAAkB,CAAC,EAAE,sBAAsB,CAAA;CAC5C;AAED,MAAM,WAAW,gBAAgB;IAC/B,4BAA4B,EAAE,MAAM,CAAA;IACpC,gCAAgC,EAAE,MAAM,CAAA;IACxC,YAAY,EAAE,MAAM,CAAA;IACpB,mBAAmB,EAAE,MAAM,CAAA;IAC3B,oBAAoB,EAAE,MAAM,CAAA;IAC5B,eAAe,EAAE,MAAM,CAAA;IACvB,uBAAuB,EAAE,MAAM,CAAA;IAC/B,cAAc,EAAE,MAAM,CAAA;CACvB;AAED,MAAM,WAAW,2BAA2B;IAC1C,WAAW,EAAE,MAAM,CAAA;IACnB,QAAQ,EAAE,OAAO,CAAA;IACjB,cAAc,EAAE,MAAM,CAAA;IACtB,oBAAoB,CAAC,EAAE,MAAM,CAAA;IAC7B,2BAA2B,CAAC,EAAE,MAAM,CAAA;IACpC,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,aAAa,CAAC,EAAE,MAAM,CAAA;CACvB;AAED,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,EAAE,MAAM,CAAA;IAChB,cAAc,EAAE,MAAM,CAAA;IACtB,WAAW,EAAE,2BAA2B,GAAG,IAAI,CAAA;IAC/C,eAAe,EAAE,2BAA2B,GAAG,IAAI,CAAA;IACnD,IAAI,EAAE,2BAA2B,EAAE,CAAA;IACnC,IAAI,EAAE,2BAA2B,EAAE,CAAA;IACnC,SAAS,EAAE,2BAA2B,EAAE,CAAA;CACzC;AAED,MAAM,MAAM,gBAAgB,GACxB;IACE,IAAI,EAAE,QAAQ,GAAG,WAAW,CAAA;IAC5B,MAAM,EAAE,UAAU,CAAA;IAClB,UAAU,EAAE,MAAM,CAAA;CACnB,GACD;IACE,IAAI,EAAE,MAAM,GAAG,UAAU,CAAA;IACzB,MAAM,EAAE,UAAU,CAAA;IAClB,IAAI,EAAE,UAAU,CAAA;IAChB,iBAAiB,EAAE,MAAM,CAAA;IACzB,sBAAsB,EAAE,MAAM,CAAA;IAC9B,eAAe,EAAE,MAAM,CAAA;CACxB,GACD;IACE,IAAI,EAAE,SAAS,CAAA;IACf,MAAM,EAAE,UAAU,CAAA;IAClB,iBAAiB,EAAE,MAAM,CAAA;IACzB,sBAAsB,EAAE,MAAM,CAAA;IAC9B,eAAe,EAAE,MAAM,CAAA;CACxB,GACD;IACE,IAAI,EAAE,UAAU,CAAA;IAChB,MAAM,EAAE,UAAU,CAAA;IAClB,iBAAiB,EAAE,MAAM,CAAA;IACzB,sBAAsB,EAAE,MAAM,CAAA;IAC9B,eAAe,EAAE,MAAM,CAAA;IACvB,KAAK,EAAE;QACL;;;;;WAKG;QACH,IAAI,EAAE,kBAAkB,CAAC,MAAM,CAAC,GAAG,kBAAkB,CAAC,MAAM,CAAC,CAAA;QAC7D,OAAO,EAAE,MAAM,CAAA;KAChB,CAAA;CACF,GACD;IACE,IAAI,EAAE,OAAO,CAAA;IACb,MAAM,EAAE,UAAU,CAAA;IAClB,IAAI,EAAE,UAAU,CAAA;IAChB,IAAI,EAAE,SAAS,CAAA;IACf,iBAAiB,EAAE,MAAM,CAAA;IACzB,aAAa,EAAE,MAAM,CAAA;IACrB,OAAO,EAAE,OAAO,CAAA;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB,CAAA;AAEL,KAAK,aAAa,GAAG,CAAC,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,SAAS,KAAK,IAAI,CAAA;AAChE,KAAK,YAAY,GAAG,CAAC,IAAI,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,EAAE,gBAAgB,CAAC,EAAE,MAAM,KAAK,IAAI,CAAA;AAE3F,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAElF;AAED;;;;8BAI8B;AAC9B,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,UAAU,CAAA;IAChB,UAAU,EAAE,MAAM,CAAA;CACnB;AAED;;;;;;;;;;;;;;;;gEAgBgE;AAChE,KAAK,oBAAoB,GAAG,CAC1B,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,UAAU,EACrB,IAAI,EAAE,iBAAiB,GAAG,SAAS,KAChC,IAAI,CAAA;AAET,MAAM,WAAW,kBAAkB;IACjC,wFAAwF;IACxF,gBAAgB,CAAC,EAAE,OAAO,CAAA;IAC1B,6DAA6D;IAC7D,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,4EAA4E;IAC5E,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,2DAA2D;IAC3D,MAAM,CAAC,EAAE,cAAc,CAAA;IACvB;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,sBAAsB,CAAA;CAC5C;AAkMD,qBAAa,mBAAmB;;gBAkFlB,MAAM,CAAC,EAAE,gBAAgB;IAyErC;;;;;4EAKwE;IACxE,IAAI,WAAW,IAAI,qBAAqB,CAEvC;IAED;;;;;;;OAOG;IACH,IAAI,mBAAmB,IAAI,QAAQ,CAAC,mBAAmB,CAAC,CAUvD;IAED,IAAI,YAAY,IAAI,QAAQ,CAAC,gBAAgB,CAAC,CAI7C;IAED,IAAI,kBAAkB,IAAI,aAAa,CAAC,4BAA4B,CAAC,CAMpE;IAED;;;;;OAKG;IACH,WAAW,CAAC,MAAM,EAAE,UAAU,EAAE,OAAO,CAAC,EAAE,kBAAkB,GAAG,UAAU,GAAG,IAAI;IAyBhF,gFAAgF;IAChF,IAAI,CAAC,MAAM,EAAE,UAAU,EAAE,OAAO,CAAC,EAAE,kBAAkB,GAAG,gBAAgB,GAAG,IAAI;IAoR/E,MAAM,CAAC,EAAE,EAAE,YAAY,GAAG,IAAI;IAI9B,OAAO,CAAC,EAAE,EAAE,aAAa,GAAG,IAAI;IAIhC;;;;;;;;;;;;6DAYyD;IACzD,cAAc,CAAC,EAAE,EAAE,oBAAoB,GAAG,IAAI;IAI9C,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,aAAa,GAAG,IAAI;IAIvD,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,GAAG,IAAI;IAqBjD,6EAA6E;IAC7E,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,GAAG,IAAI;IAmB5D,eAAe,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI;IAKxC,mBAAmB,CAAC,MAAM,EAAE,mBAAmB,GAAG,IAAI;IAStD,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI;IAW1C;;iEAE6D;IAC7D,UAAU,CAAC,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,SAAS,GAAG,IAAI;IAenD;;;;;;OAMG;IACH,wBAAwB,CACtB,QAAQ,EAAE,MAAM,EAChB,iBAAiB,EAAE,MAAM,EACzB,2BAA2B,EAAE,MAAM,GAAG,SAAS,EAC/C,YAAY,EAAE,MAAM,GAAG,SAAS,EAChC,gBAAgB,CAAC,EAAE,MAAM,GACxB,cAAc,GAAG,IAAI;IA4CxB;iFAC6E;IAC7E,KAAK,IAAI,IAAI;IAKb,OAAO,IAAI,IAAI;IAqJf,kFAAkF;IAClF,kBAAkB,EAAE,MAAM,GAAG,SAAS,CAAY;IAWlD,MAAM,CAAC,UAAU,CAAC,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,OAAO,EAAE,KAAK,SAAK,GAAG,OAAO;CA+E3E"}