@blockcast/mmt-container 0.1.0 → 0.3.0-main.d9354616fdf2

package/dist/mmtp-router.d.ts

@@ -0,0 +1,679 @@
+/**
+ * MMTP packet processing and frame routing layer.
+ *
+ * Delegates MMTP header parsing, MFU extraction, reassembly, and keyframe
+ * detection to MmtpContainerParser while owning FEC orchestration, sync
+ * gating, CMAF assembly, and callback routing.
+ *
+ * Extracted from MulticastManager — this module owns MMTP-layer concerns:
+ * FEC symbol feeding, sync gating, MSE segment assembly, and frame routing.
+ * It does NOT own network I/O, watchdog timers, or multicast join/leave.
+ *
+ * @packageDocumentation
+ */
+import { type FecBlockProfile } from "@blockcast/mmt-base";
+import type { IsoHeldSource } from "./fec-manager.js";
+import type { IsoRepairPlacement } from "./iso-block-locator.js";
+import type { MfuReassemblerBackend, MmtpSourcePath, MmtpDeliveryProvenance } from "./mfu-reassembler.js";
+import type { MfuReassemblyPolicy } from "./mfu-reassembly-policy.js";
+import { type AuthoredTiming } from "./authored-timing.js";
+import { FecBlockMapper } from "@blockcast/mmt-fec";
+import { CmafBlockAssembler, type BlockAssemblerConfig, type CmafBlockSample } from "./cmaf-block-assembler.js";
+import { type TrackRole } from "./carp-catalog.js";
+import { type BlockClass, type ClassifierMode, type ClassifierReason, type FrameGapDecision, type SourceSymbolEvidence } from "./block-policy.js";
+import { type DuplicateHorizon } from "./duplicate-ledger.js";
+import type { ManifestAuthMode, ManifestObjectIdentity, ManifestTrackContext, ManifestVerifier } from "@blockcast/mmt-manifest-verify";
+/**
+ * Keyframe loss timeout slack factor (Phase 13, tracks WITHOUT FEC only).
+ *
+ * FEC tracks never arm the keyframe-lost timer: vanished FEC blocks are
+ * materialised from SBN evidence and resolve through their catalog-derived
+ * repair and fail deadlines, and the stall/conceal decision rides on the
+ * first frame released after the gap (`RoutedFrameMeta.gapBefore`).
+ *
+ * Derivation: The keyframe loss timer must fire after one full keyframe group
+ * has been missed. Group duration must come from explicit catalog timing; FEC
+ * sourceSymbols is a block width, not a GOP length. Multicast jitter means the
+ * last packet of a group may arrive up to ~0.5 group durations late (network
+ * reordering + FEC recovery latency). The total timeout is therefore:
+ *
+ *   timeout = group_duration * (1.0 + 0.5_jitter) = group_duration * 1.5
+ *
+ * The 0.5 jitter margin covers: (a) FEC interleave recovery window (up to D
+ * frames), (b) network reordering within one interleave depth, and (c) OS
+ * socket buffer draining latency. This is tight enough to detect loss within
+ * one missing group while avoiding false positives from normal jitter.
+ */
+export declare const KEYFRAME_LOST_TIMEOUT_SLACK = 1.5;
+export type RoutedFrameMeta = {
+    /** Authored ISO-BMFF presentation timestamp, in microseconds. */
+    timestamp: number;
+    /**
+     * Raw MMTP short-NTP header timestamp. This is transport timing metadata
+     * only; it is deliberately separate from the authored media timestamp.
+     */
+    mmtpTimestamp?: bigint;
+    keyframe: boolean;
+    /** Exact ISO-BMFF timing in the media track's native timescale. */
+    authoredTiming?: AuthoredTiming;
+    /** Transport that supplied the accepted FI=1 head (or complete FI=0 frame). */
+    source?: MmtpSourcePath;
+    /**
+     * Whole-frame delivery verdict folded across every contributing fragment.
+     *
+     * Distinct from `source` on purpose. `source` answers a routing question —
+     * which transport's copy is this — and deliberately lets the head fragment
+     * decide. This answers an evidence question: did every byte of this frame
+     * physically arrive over multicast? A frame can be routed as 'multicast'
+     * and still be 'mixed'.
+     */
+    deliveryProvenance?: MmtpDeliveryProvenance;
+    packetId?: number;
+    packetSequenceNumber?: number;
+    /** Every authoritative MMTP source-packet sequence that formed this frame. */
+    packetSequenceNumbers?: number[];
+    /** Subset of packetSequenceNumbers reconstructed by FEC. */
+    repairedPacketSequenceNumbers?: number[];
+    /** Native MMTP MPU group coordinate. */
+    mpuSequenceNumber?: number;
+    /**
+     * Timed-MFU sample identity `(movie_fragment_sequence_number, sample_number)`
+     * from the MFU data-unit header. Absent when the MFU header is untimed.
+     */
+    movieFragmentSequenceNumber?: number;
+    sampleNumber?: number;
+    /** Immutable catalog identity supplied by the owning ingress subscription. */
+    catalogTrackName?: string;
+    recovered?: boolean;
+    /**
+     * True when this frame opens playback after the router suppressed earlier
+     * video deltas while waiting for a sync keyframe. Downstream decoders can
+     * use this to treat the following dependency chain as provisional.
+     */
+    sourceDiscontinuity?: boolean;
+    /**
+     * Stall/conceal decision for the first frame released after a gap: its
+     * FEC blocks resolved with lost media, or authored decode time shows a
+     * missing sample. Sinks act on it in order, on this frame. It is the same
+     * object the manager emits as its `gap` event.
+     */
+    gapBefore?: FrameGapDecision;
+};
+export interface MmtpIngressContext {
+    tracks: readonly Readonly<{
+        name: string;
+        packetId: number;
+    }>[];
+}
+/** One physical stream: an MMTP packet ID and the catalog track it carries. */
+export interface MmtpStreamIdentity {
+    readonly packetId: number;
+    readonly catalogTrackName: string;
+}
+/**
+ * Where a staged stream switch committed, relative to the outgoing stream.
+ *
+ * - `outgoing-reached-rap`: the outgoing stream was about to deliver a frame
+ *   at or past the incoming RAP's presentation time. The splice is exact:
+ *   the outgoing stream delivered every frame before the RAP that reached
+ *   the router, and none at or after it. An MSE assembler is the one
+ *   exception, since its flush is unbounded (see `stageStreamSwitch`).
+ * - `outgoing-ahead`: when the incoming RAP arrived, the outgoing stream had
+ *   already delivered a frame at or past it. The switch commits on that RAP
+ *   at once; incoming frames up to `outgoingHighWater` cover media time the
+ *   outgoing stream already delivered.
+ * - `outgoing-overdue`: the incoming stream reached its next RAP before the
+ *   outgoing stream reached the one held for it, so the outgoing stream is at
+ *   least a GOP behind (stalled, or losing media) and waiting longer only
+ *   widens the gap. The switch commits on the held RAP: the held GOP is
+ *   delivered, then the newer RAP. It overlaps nothing, since every outgoing
+ *   frame delivered was compared against the held RAP and is before it.
+ */
+export type StreamSwitchCommitReason = "outgoing-reached-rap" | "outgoing-ahead" | "outgoing-overdue";
+/** Presentation position of one frame, in the router's frame vocabulary. */
+export interface StreamSwitchPosition {
+    /** Authored presentation timestamp, in microseconds. */
+    readonly timestamp: number;
+    /** Exact authored timing, when the frame carried it. */
+    readonly authoredTiming?: Readonly<AuthoredTiming>;
+}
+/** A staged stream switch, at the moment it commits. */
+export interface StreamSwitchCommit {
+    readonly from: MmtpStreamIdentity;
+    readonly to: MmtpStreamIdentity;
+    /** The incoming RAP the switch commits on: the first `to` frame delivered. */
+    readonly rap: StreamSwitchPosition & {
+        readonly mpuSequenceNumber?: number;
+    };
+    /**
+     * The furthest-presented outgoing frame delivered before the commit,
+     * counting the gap fills the commit released, or undefined when the
+     * outgoing stream delivered none.
+     */
+    readonly outgoingHighWater: StreamSwitchPosition | undefined;
+    readonly reason: StreamSwitchCommitReason;
+    /**
+     * Incoming frames never delivered: the deltas before the incoming stream's
+     * first RAP (the GOP it was admitted into mid-way), and a held GOP a reset
+     * of the incoming stream invalidated.
+     */
+    readonly droppedIncomingFrames: number;
+}
+/** What MmtpRouter.stageStreamSwitch needs. */
+export interface StreamSwitchOptions {
+    /** The stream being replaced: a registered video packet ID. */
+    readonly from: MmtpStreamIdentity;
+    /** The replacing stream: a registered video packet ID other than `from`'s. */
+    readonly to: MmtpStreamIdentity;
+    /**
+     * Called synchronously at the commit, after `from`'s packet ID is retired
+     * and before `to`'s withheld init and its RAP are delivered. Throwing fails
+     * the commit closed: `to` is retired as well and nothing of it is
+     * delivered, since `from` can no longer be restored.
+     */
+    readonly onCommit: (commit: StreamSwitchCommit) => void;
+}
+/** A switch MmtpRouter.stageStreamSwitch staged. */
+export interface StagedStreamSwitch {
+    /**
+     * Abandon the switch before it commits: `to` is no longer withheld and its
+     * withheld init is dropped. Returns false when the switch already committed
+     * or was cancelled.
+     */
+    cancel(): boolean;
+}
+/** Callback for decoded video/audio frames. */
+export type FrameCallback = (data: Uint8Array, meta: RoutedFrameMeta) => void;
+/** Metadata accompanying an accepted raw MMTP source packet. */
+export type RoutedPacketMeta = {
+    packetId: number;
+    packetSequenceNumber: number;
+    /** True when FEC reconstructed this source packet. */
+    recovered: boolean;
+    /** True when the packet has no trailing Source FEC Payload ID. */
+    skipFecPayloadId: boolean;
+    /** Immutable catalog identity supplied by the owning ingress subscription. */
+    catalogTrackName?: string;
+    /**
+     * Strict provenance for the fragments this packet produces. Set for
+     * FEC-recovered packets, which carry no `source` of their own but inherit
+     * their FEC block's symbol provenance.
+     */
+    deliveryProvenance?: MmtpDeliveryProvenance;
+};
+/** Callback for accepted raw MMTP source packets. */
+export type TrackPacketCallback = (packet: Uint8Array, meta: RoutedPacketMeta) => void;
+type ParserDiagnostics = {
+    packets: number;
+    frames: number;
+    initSegments: number;
+    noFragment: number;
+    fragments: number;
+    reassembled: number;
+    pendingBuffers: number;
+    pendingFragments: number;
+    pendingSamples?: unknown[];
+    lastPacketLength: number;
+    lastSequenceNumber: number;
+    lastFecSsId?: number;
+    lastFrameTimestamp?: number;
+    directAudioSourceEmitted: number;
+    directAudioSourceRegressions: number;
+    directAudioRecoveredQueued: number;
+    directAudioRecoveredDrained: number;
+    directAudioRecoveredStaleDropped: number;
+};
+/**
+ * FECManager interface — the contract MmtpRouter expects for FEC
+ * source/repair symbol processing and block lifecycle events.
+ *
+ * Concrete implementation: `FECManager` class in `./fec-manager.ts`.
+ * MmtpRouter only interacts with FEC through this interface.
+ */
+export interface FECManagerLike {
+    /** Feed a source symbol to the FEC decoder for a given track.
+     *  Returns recovered block bytes if recovery completes, else null.
+     *
+     *  `symbolData` is the complete MMTP packet without its Source FEC Payload
+     *  ID, unpadded and possibly a view into the received packet. The manager
+     *  zero-pads it to the packet's own symbol size T.
+     *
+     *  Optional `alta` carries the detached ALTA authenticator extracted from
+     *  the MMTP header-extension trailer (08-07 Path 2) — present on signed
+     *  source packets, absent on relay-reassembled / unsigned streams. When
+     *  provided, the fec-worker runs verify_detached instead of counting the
+     *  symbol as `altaPending`. */
+    feedSourceSymbol(packetId: number, ssId: number, symbolData: Uint8Array, alta?: {
+        auth: Uint8Array;
+        payloadEnd: number;
+    }, catalogTrackName?: string): Uint8Array | null;
+    /** Feed a repair symbol to the FEC decoder for a given track.
+     *  Returns recovered block bytes if recovery completes, else null. */
+    feedRepairSymbol(packetId: number, ssStart: number, ssbLength: number, rsId: number, repairData: Uint8Array, catalogTrackName?: string): Uint8Array | null;
+    /** Delivery-gap sample for one multicast packet (FECManager.noteMulticastArrival). */
+    noteMulticastArrival?(packetId: number, packetSequenceNumber: number): void;
+    /** Record a transport symbol for first-arrival-wins dedup and path counters. */
+    feedSymbolFromSource(packetId: number, sbn: number, esi: number, data: Uint8Array, source: "multicast" | "moq", catalogTrackName?: string): boolean;
+    /** Strict provenance for a block: 'multicast' only when no symbol arrived
+     *  over MoQ. Recovered bytes inherit it, since a recovered symbol is a
+     *  function of every symbol that entered the block. */
+    blockDeliveryProvenance?(sbn: number, packetId: number, catalogTrackName?: string): MmtpDeliveryProvenance;
+    /** Track a first-arrival network source symbol for block completion and
+     *  classification. Refreshes the inactivity deadline and marks clean when
+     *  K arrive. */
+    trackBlock(sbn: number, packetId: number, catalogTrackName: string | undefined, esi: number, evidence: SourceSymbolEvidence): void;
+    /** True once the packetId has a per-track FEC configuration. */
+    isTrackConfigured?(packetId: number): boolean;
+    /** Lifecycle resolution of one block for in-order frame release. */
+    blockResolution?(sbn: number, packetId: number, catalogTrackName?: string): "pending" | "complete" | "failed" | "untracked";
+    /** Highest SBN seen for a stream in the current epoch. */
+    highestSbn?(packetId: number, catalogTrackName?: string): number | undefined;
+    /** Catalog/reset epoch of a packet's streams. */
+    epochFor?(packetId: number): number;
+    /**
+     * Catalog `fec.interleaveDepthMs` (§5.1 full block span) of a packetId; 0
+     * when the stream has none.
+     */
+    interleaveDepthMsForPacket?(packetId: number): number;
+    /**
+     * How long a terminal block stays authoritative before it retires to
+     * untracked. The release gate holds a frame at most this long, so its loss
+     * scan never reads a retired, delivered block as lost. Required whenever
+     * blockResolution is.
+     */
+    terminalRetentionMsForPacket?(packetId: number): number;
+    /** Configured codec of a packetId. */
+    codecFor?(packetId: number): string | undefined;
+    /** Current classifier mode of a stream. */
+    classifierModeFor?(packetId: number, catalogTrackName?: string): {
+        mode: ClassifierMode;
+        reason: ClassifierReason | null;
+    };
+    /** Whether an MPU boundary still bounds the stream's RAPs. */
+    mpuBoundsRapsFor?(packetId: number, catalogTrackName?: string): boolean;
+    /** Record a RAP released in order (RAP-spacing invariant). */
+    noteReleasedRap?(packetId: number, catalogTrackName: string | undefined, mpu: number, presentationTime: bigint, mediaTimescale: number): void;
+    /** Refresh the block inactivity deadline after accepted repair progress. */
+    noteBlockActivity?(sbn: number, packetId: number, catalogTrackName?: string): void;
+    /** Cancel block timeout (block completed via clean or FEC recovery). */
+    cancelBlockTimeout(sbn: number, packetId?: number, catalogTrackName?: string): void;
+    /** Check if a block is already completed (clean or recovered). */
+    isBlockCompleted(sbn: number, packetId?: number, catalogTrackName?: string): boolean;
+    /** Mark a block as completed externally (after routing recovered data). */
+    markBlockCompleted(sbn: number, packetId?: number, catalogTrackName?: string): void;
+    /** Increment blocksRecovered stat (called after routing recovery). */
+    countRecovery(packetId?: number, sbn?: number, catalogTrackName?: string): void;
+    /**
+     * The configured catalog `fec.blockProfile` of a packetId, or undefined
+     * while it is unconfigured. Required: a Source or Repair FEC Payload ID is
+     * read under exactly one profile, and the router never guesses it.
+     */
+    blockProfileForPacket(packetId: number): FecBlockProfile | undefined;
+    /** iso-ssbg1-v1: whether a protected packet fits one ssbg_mode1 symbol. */
+    isoSourceFits?(packetId: number, packetLength: number): boolean;
+    /** iso-ssbg1-v1: locate a source in a block a repair already stated. */
+    locateIsoSource?(packetId: number, catalogTrackName: string | undefined, ssId: number): {
+        sbn: number;
+        esi: number;
+    } | null;
+    /** iso-ssbg1-v1: hold a first-arrival source until a repair states its block. */
+    holdIsoSource?(packetId: number, catalogTrackName: string | undefined, ssId: number, source: IsoHeldSource): boolean;
+    /** iso-ssbg1-v1: state a repair's block and hand back the held sources it places. */
+    placeIsoRepair?(packetId: number, catalogTrackName: string | undefined, ssStart: number, ssbLength: number): IsoRepairPlacement<IsoHeldSource>;
+    /** iso-ssbg1-v1: resolution of the SS_IDs strictly between two released frames. */
+    isoSpanResolution?(packetId: number, catalogTrackName: string | undefined, fromSsId: number, toSsId: number): readonly number[] | null;
+    /** FEC source symbol count K per block. */
+    readonly k: number;
+    kForPacket?(packetId: number): number;
+    /**
+     * The longest a block stays open after its last symbol (inactivity fail
+     * bound plus D-28 repair grace). With interleaveDepthMsForPacket it bounds
+     * how long the router keeps a stream's duplicate ledgers.
+     */
+    blockLifetimeMsForPacket?(packetId: number): number;
+    /** FEC symbol size T in bytes (0 = unknown / no FEC). */
+    readonly symbolSize: number;
+    symbolSizeForPacket?(packetId: number): number;
+    /** Update framerate — used to refine FEC block timeout. */
+    setFramerate(fps: number): void;
+    /** Per-block state snapshot for FecBlockGrid visualization. */
+    getBlockStates(): Array<{
+        sbn: number;
+        packetId?: number;
+        state: "collecting" | "complete" | "failed";
+        sourceCount: number;
+        k: number;
+        progress: number;
+    }>;
+    /** FEC statistics snapshot. */
+    readonly fecStats: {
+        sourcePackets: number;
+        repairPackets: number;
+        blocksClean: number;
+        blocksRecovered: number;
+        blocksFailed: number;
+    };
+    /** Called when a block receives its first source symbol. */
+    onBlockStarted: ((sbn: number, packetId: number, catalogTrackName?: string) => void) | null;
+    /** Called when a block completes cleanly (all K sources arrived). */
+    onBlockComplete: ((sbn: number, packetId: number, catalogTrackName?: string) => void) | null;
+    /** Called when a block times out (unrecoverable), with its class. */
+    onBlockFailed: ((sbn: number, packetId: number, catalogTrackName: string | undefined, blockClass: BlockClass) => void) | null;
+    /** Called when a block reaches any terminal state. */
+    onBlockResolved?: ((sbn: number, packetId: number, catalogTrackName: string | undefined) => void) | null;
+    /** Called when a stream's FEC source restarted (SBN discontinuity). */
+    onSourceDiscontinuity?: ((packetId: number, catalogTrackName: string | undefined) => void) | null;
+    /** Dispose timers and state. */
+    dispose(): void;
+}
+export interface ManifestIdentityResolutionInput {
+    packetId: number;
+    sbn: number;
+    esi: number;
+    /**
+     * The packet's SS_ID and its MPU's mpu_sequence_number. Under
+     * iso-ssbg1-v1 blocks vary in length, so a packet's media group comes from
+     * its own MPU header, never from SBN arithmetic (BLO-35597 D2a).
+     */
+    ssId?: number;
+    mpuSequenceNumber?: number;
+    catalogTrackName?: string;
+    recovered: boolean;
+    sourceSymbolFormat: "full-mmtp-packet" | "fec-padded-recovery";
+}
+export type ManifestIdentityResolver = (input: ManifestIdentityResolutionInput) => ManifestObjectIdentity | null;
+export declare class MmtpRouter {
+    #private;
+    constructor(config?: {
+        fecManager?: FECManagerLike;
+        fecMapper?: FecBlockMapper;
+        /** MFU reassembly timeout (ms) for FEC recovery path. Derive from FEC interleaveDepthMs. */
+        mfuTimeoutMs?: number;
+        reassemblyPolicy?: MfuReassemblyPolicy;
+        reassembler?: MfuReassemblerBackend;
+        maxBufferedMfus?: number;
+        /** Catalog-derived keyframe loss timeout (ms). Derive from explicit
+         *  keyframe/group duration; do not use FEC sourceSymbols as GOP length.
+         *  Pass a reader when its inputs are measured later; see
+         *  setKeyframeLostTimeoutMs. */
+        keyframeLostTimeoutMs?: number | (() => number);
+        manifestVerifier?: ManifestVerifier;
+        /** Existing behavior is router ownership; shared browser plans opt into caller ownership. */
+        manifestVerifierOwnership?: "caller" | "router";
+        resolveManifestIdentity?: (packetId: number, sbn: number, esi: number, catalogTrackName?: string) => ManifestObjectIdentity | null;
+        resolveManifestIdentityForRoute?: ManifestIdentityResolver;
+        /** Internal terminal-failure sink owned by the composing transport. */
+        onBlockFailed?: (sbn: number, packetId: number, catalogTrackName: string | undefined, blockClass: BlockClass) => void;
+        /** Internal gap-decision sink owned by the composing transport. */
+        onFrameGap?: (decision: FrameGapDecision) => void;
+        /**
+         * Called when a multicast stream's publisher restarted its wire counters,
+         * after the router reset its own state for the stream, so the composing
+         * transport can reset what it holds (FEC blocks, repair I/O) before the
+         * packet that revealed the restart is processed.
+         */
+        onPublisherRestart?: (packetId: number, catalogTrackName: string) => void;
+    });
+    get fecManager(): FECManagerLike | null;
+    /**
+     * How long this router keeps a packet ID's duplicate ledgers, derived from
+     * the FEC manager's geometry for it (see duplicate-ledger.ts), or why no
+     * horizon is derivable (the stream then keeps count-bounded ledgers, or none
+     * without an FEC manager). A stream reads this when it moves to a new FEC
+     * block, so a catalog change applies from the next block.
+     */
+    duplicateHorizonFor(packetId: number): DuplicateHorizon;
+    /** Publisher restarts detected on the multicast leg since construction. */
+    get publisherRestartCount(): number;
+    /**
+     * Packets whose Source or Repair FEC Payload ID was left unread because
+     * their (owner) packetId had no configured `fec.blockProfile`: FEC not
+     * configured yet for a track whose packets already flow, or a track whose
+     * catalog FEC was unusable. Such a source packet's media is routed as on a
+     * track without FEC; such a repair packet is dropped. Neither is read as a
+     * block coordinate under a guessed profile, and neither touches FEC state.
+     */
+    get fecPayloadIdsWithoutProfile(): number;
+    get reassembler(): MfuReassemblerBackend;
+    getDiagnostics(): Record<number, ParserDiagnostics>;
+    /** Register callback for keyframe loss detection.
+     *  Fires when no complete keyframe is emitted within keyframeLostTimeoutMs.
+     *  Argument: next expected groupId (lastKeyframeGroupId + 1). */
+    onKeyframeLost(cb: (expectedGroupId: number) => void): void;
+    /**
+     * Set the keyframe loss timeout after construction.
+     * Must be called BEFORE setPacketIdType('video').
+     * A fixed timeout derives from explicit keyframe/group duration:
+     * Math.ceil(groupDurationMs * KEYFRAME_LOST_TIMEOUT_SLACK).
+     * A timeout whose inputs are measured after configuration (e.g. keyframe
+     * cadence plus measured playout lateness) is passed as a reader, evaluated
+     * each time the timer is armed. Both forms pass the same check at each arm:
+     * a throw, or a value that is not finite, positive and within the timer
+     * maximum, leaves that keyframe unarmed (fail closed per keyframe, not per
+     * session). A fixed NaN, e.g. derived from a catalog without a group
+     * duration, therefore never reaches setTimeout.
+     */
+    setKeyframeLostTimeoutMs(ms: number | (() => number)): void;
+    /** Update MFU reassembly timeout. Source and FEC-recovery paths share the
+     *  parser's single reassembler (BLO-8151), so one update covers both. */
+    setMfuTimeoutMs(ms: number): void;
+    /** Update parser frame reordering for unordered multicast delivery.
+     *  Callers derive this from the catalog FEC block span (§5.1 — the
+     *  interleave value IS the span): positive round-half-up of span / frameMs. */
+    setReorderWindow(windowSize: number): void;
+    /** Register MMTP packetId → track type mapping.
+     *  Call BEFORE packets arrive to ensure correct routing from the first packet.
+     *  If keyframeLostTimeoutMs is not provided, Phase 13 keyframe repair is
+     *  disabled (video still routes/decodes normally). framerate is OPTIONAL per
+     *  draft-ietf-moq-catalogformat-01 §3.2.23, so we can't require the timeout. */
+    setPacketIdType(packetId: number, trackType: "video" | "audio"): void;
+    /** Media kind registered for a packetId, if any. */
+    trackKindFor(packetId: number): "video" | "audio" | undefined;
+    /** Register codec string for a packetId — enables codec-aware keyframe detection.
+     *  Without this, only H.264 IDR (NAL type 5) is detected as keyframe fallback.
+     *  AV1 (OBU_SEQUENCE_HEADER) and VP9 (frame_type bit) require the codec string. */
+    setTrackCodec(packetId: number, codec: string): void;
+    /** @deprecated Use onTrackFrame(packetId, cb) for per-track routing */
+    onVideoFrame(cb: FrameCallback): void;
+    /** @deprecated Use onTrackFrame(packetId, cb) for per-track routing */
+    onAudioFrame(cb: FrameCallback): void;
+    /** Register a frame callback for a specific MMTP packetId (track).
+     *  When a legacy callback (onVideoFrame/onAudioFrame) also exists for this
+     *  packetId's type, both fire: per-track first, then legacy. This ensures
+     *  element.ts wiring (confirmAudio, feedMulticast) continues working when
+     *  TrackPipeline registers per-track sources. */
+    onTrackFrame(packetId: number, cb: FrameCallback): void;
+    /** Register a raw MMTP source-packet callback for one track.
+     *
+     * Direct packets retain their original bytes, including a Source FEC Payload
+     * ID when present. FEC-recovered packets are the recovered source-symbol
+     * bytes and set `skipFecPayloadId` because that trailer is not part of the
+     * protected symbol. Repair packets are never delivered here.
+     */
+    onTrackPacket(packetId: number, cb: TrackPacketCallback): void;
+    /** Register an init segment callback (ftyp+moov from MMTP MPU metadata). */
+    onInitSegment(cb: (data: Uint8Array) => void): void;
+    /** Register an init segment callback for a specific MMTP packetId.
+     *  Called when FT=0 init arrives via direct source or FEC recovery. */
+    onTrackInit(packetId: number, cb: (data: Uint8Array) => void): void;
+    /** Create a CMAF block assembler for MSE mode on a specific track.
+     *  When active, source frames are buffered per FEC block and emitted as
+     *  multi-sample CMAF segments instead of per-frame callbacks. */
+    enableMseAssembler(packetId: number, config: Omit<BlockAssemblerConfig, "k">, catalogTrackName?: string): CmafBlockAssembler;
+    /** Register a segment callback for a track's MSE assembler.
+     *  Called with complete moof+mdat CMAF segments on block completion. */
+    onMseSegment(packetId: number, cb: (segment: Uint8Array) => void, catalogTrackName?: string): void;
+    /** Register a raw-sample callback for a track's MSE assembler.
+     *  Use this when the caller already owns the fMP4/MSE timeline and only wants
+     *  FEC recovery, keyframe gating, and dedup from the assembler. */
+    onMseSample(packetId: number, cb: (sample: CmafBlockSample) => void, catalogTrackName?: string): void;
+    /** Register an init segment callback for a track's MSE assembler. */
+    onMseInitSegment(packetId: number, cb: (init: Uint8Array) => void, catalogTrackName?: string): void;
+    /** Build and emit init segment for a track's MSE assembler from catalog config. */
+    emitMseInit(packetId: number, catalogTrackName?: string): void;
+    /** Mark a video track as synchronized by an external path.
+     *  This opens the MMTP/FEC pre-sync gates without waiting for a multicast
+     *  keyframe, for MSE timelines already seeded by MoQ with the same track. */
+    markExternalVideoSync(packetId?: number, catalogTrackName?: string): void;
+    /** Register callback for FEC blocks when the first source symbol arrives. */
+    onFecBlockStarted(cb: (sbn: number, packetId: number) => void): void;
+    /** Register a diagnostic callback for FEC blocks that fail. A failure is
+     *  not a decoder instruction: act on `RoutedFrameMeta.gapBefore`. */
+    onFecBlockFailed(cb: (sbn: number, packetId: number, catalogTrackName: string | undefined, blockClass: BlockClass) => void): void;
+    /**
+     * Register a TrackRole for a specific packetId.
+     *
+     * D-26: Enables per-role block-complete fanout — delta-role packetIds fire
+     * onDeltaBlockComplete when their FEC block completes or fails.
+     * Composite callback preserved: legacy onVideoFrame/onAudioFrame still fire
+     * (MEMORY.md "prevents callback stealing").
+     *
+     * Valid roles: 'base' | 'delta' | 'repair' | 'single'.
+     * Throws on unknown role (error on bad init, CLAUDE.md).
+     */
+    setPacketIdRole(packetId: number, role: TrackRole): void;
+    /** Replace catalog-derived repair ownership before a catalog reconfiguration. */
+    clearRepairPacketIdOwners(): void;
+    /** Bind one dedicated repair-track PID to its authoritative media PID. */
+    setRepairPacketIdOwner(repairPacketId: number, ownerPacketId: number): void;
+    /**
+     * Register callback fired when a delta-track FEC block completes or fails.
+     *
+     * @param cb - (packetId, failed) — packetId identifies the delta track,
+     *             failed=false means clean/recovered, failed=true means unrecoverable.
+     *
+     * Called from both onBlockComplete (failed=false) and onBlockFailed (failed=true)
+     * for every packetId registered with role='delta' via setPacketIdRole().
+     */
+    onDeltaBlockComplete(cb: (packetId: number, failed: boolean) => void): void;
+    /** Update framerate — delegates to FECManager for timeout refinement. */
+    setFramerate(fps: number): void;
+    /** Set FEC block mapper (created when FEC config becomes known via configureFec). */
+    setFecMapper(mapper: FecBlockMapper, packetId?: number): void;
+    registerManifestTrack(context: ManifestTrackContext): void;
+    feedManifestFrame(trackName: string, frame: Uint8Array): void;
+    setManifestAuthMode(mode: ManifestAuthMode): void;
+    /**
+     * Main entry point: feed a raw MMTP packet for processing.
+     *
+     * Source packets are played immediately AND fed to FECManager for recovery.
+     * Repair packets are fed to FECManager only (no direct playback).
+     */
+    /**
+     * Feed one MMTP source packet.
+     *
+     * `source` is REQUIRED. It used to default to "multicast", which meant any
+     * caller that forgot it silently attributed its bytes to a multicast socket
+     * they may never have crossed — and that attribution is what the physical-
+     * delivery evidence path is built on. Absence is not multicast; say which.
+     */
+    feedPacket(packet: Uint8Array, source: "multicast" | "moq", manifestIdentity?: ManifestObjectIdentity, ingress?: MmtpIngressContext): void;
+    /**
+     * Feed a reliable MoQ duplicate of a source packet that the multicast leg
+     * also carries, during make-before-break overlap.
+     *
+     * The copy is parsed for playback (attributed to "moq") so a pending
+     * multicast decoder can warm. For an FEC-tagged packet the router keeps a
+     * per-symbol (SBN/ESI) parse ledger, so whichever of it and its multicast
+     * twin arrives first is parsed and the second is not. The MFU reassembler
+     * cannot be that dedup: complete (FI=0) MFUs bypass its #emitted set.
+     *
+     * The ledger exists only where a symbol coordinate does: a packet with no
+     * FEC payload ID, or a router with no FEC manager, has none, so it and its
+     * twin are BOTH parsed. On an audio track that delivers the sample twice
+     * (#emitDirectSourceAudio counts the regression and still emits). The
+     * intended deployment is safe because the multicast leg is FEC-protected,
+     * so its media packets carry the ID; the untagged timing packets
+     * (init/moof) take this path too, where a re-parse is benign. Do not feed
+     * untagged media through here.
+     *
+     * The copy never enters FEC
+     * accounting: no `feedSymbolFromSource`, `trackBlock` or
+     * `feedSourceSymbol`. Block completion and the repair deadline therefore
+     * follow the multicast leg alone, and a multicast erasure still starves its
+     * block and requests repair. Feeding the copy through `feedPacket` instead
+     * would let it close the block, hiding exactly the loss repair exists for.
+     *
+     * MoQ unicast fallback is not an overlap copy: it is the only source, so it
+     * uses `feedPacket(packet, "moq")` and counts toward completion.
+     */
+    feedOverlapCopy(packet: Uint8Array, ingress?: MmtpIngressContext): void;
+    /**
+     * Feed a repair packet from MoQ (reliable QUIC) — parses MMTP repair
+     * header and delegates to FECManager for FEC recovery.
+     */
+    feedRepairPacket(packet: Uint8Array, ownerPacketIdHint?: number, catalogTrackName?: string): void;
+    /** Route a recovered FEC block through the parser + dedup pipeline.
+     *  Sync WASM decoders return K fixed-width source symbols concatenated. */
+    routeRecoveredBlock(blockId: number, data: Uint8Array, packetId: number, catalogTrackName?: string): void;
+    /** Route a single recovered source symbol through the parser + dedup pipeline.
+     *  Worker-backed decoders emit one padded source symbol per frame event. */
+    routeRecoveredSymbol(blockId: number, data: Uint8Array, packetId: number, esi?: number, catalogTrackName?: string): void;
+    /** Cancel the active keyframe loss timer.
+     *  Call on failbackToMoq to prevent a stale timer from firing
+     *  onKeyframeLost after multicast is no longer the active source. */
+    cancelKeyframeLostTimer(): void;
+    /** Emit parser frames buffered for a finite input before teardown. */
+    flush(): void;
+    /** Drop one rendition's parser/router/CMAF epoch without touching peers. */
+    resetTrack(packetId: number, catalogTrackName: string): void;
+    /**
+     * Retire one packet ID, drop-only: remove every registration of it (media
+     * kind, codec, frame/packet/init callbacks, FEC mapper, role, repair
+     * ownership) and every stream state kept for it (sync gates, emission
+     * cursors, duplicate ledgers, queued recovered frames, MSE assemblers,
+     * parser buffers and authored timing, MFU reassembly per catalog stream).
+     * Nothing buffered is delivered, as on live dispose. A dedicated repair
+     * packet ID that this packet ID alone owned loses its repair role with it.
+     *
+     * Afterwards the packet ID is unknown to the router: its packets and
+     * frames are dropped until it is registered again. FEC state lives in the
+     * FEC manager and is released there (FECManager.releasePacket).
+     */
+    retirePacketId(packetId: number): void;
+    /**
+     * Stage an in-place switch from one video stream to another, committed at
+     * a RAP of the incoming stream without leaving the multicast group.
+     *
+     * Until the commit the outgoing stream (`from`) is delivered as usual and
+     * the incoming stream (`to`) is not: its packets are parsed and feed FEC,
+     * so its first RAP arrives FEC-protected, but none of its frames, and not
+     * its init, reach any callback or MSE assembler. Incoming deltas before its
+     * first RAP are dropped. When that RAP arrives:
+     *
+     * - if the outgoing stream already delivered a frame at or past the RAP's
+     *   presentation time, the switch commits on it (`outgoing-ahead`);
+     * - otherwise the RAP and the incoming frames after it are held, and the
+     *   switch commits when the outgoing stream is about to deliver a frame at
+     *   or past the RAP (`outgoing-reached-rap`): that outgoing frame, and every
+     *   later one, is never delivered, so the splice is exact. If the incoming
+     *   stream reaches its next RAP first, the outgoing stream is a GOP or more
+     *   behind: the switch commits on the held RAP and delivers the held GOP
+     *   and then the newer RAP (`outgoing-overdue`), the smallest gap left once
+     *   the outgoing stream stops. The hold is bounded by the incoming stream's
+     *   own RAP cadence, so no timer is involved.
+     *
+     * The commit is one synchronous transition inside the frame path: the
+     * outgoing stream's already-admitted frames are released (its queued FEC
+     * gap fills only up to the RAP, since recovery can queue a frame ahead of
+     * the source cursor; its MSE assembler's ordering queue whole, as
+     * CmafBlockAssembler.flush has no bound, so on the MSE path a recovered
+     * outgoing frame at or past the RAP can still be emitted), its packet ID
+     * is retired
+     * (retirePacketId), `onCommit` runs, and then the incoming stream's newest
+     * init and its RAP are delivered, followed by any held frames. No outgoing
+     * frame is delivered after the commit and no incoming frame before it. If
+     * `onCommit` throws, `to` is retired too and none of it is delivered.
+     *
+     * Both packet IDs must be registered video streams; the commit reads RAPs.
+     * Admission (the transport allow-list and ingress tracks) is the caller's:
+     * MulticastManager.switchRendition drives both.
+     */
+    stageStreamSwitch(options: StreamSwitchOptions): StagedStreamSwitch;
+    /** Live teardown is drop-only. Finite inputs must opt into a final flush. */
+    dispose(options?: {
+        flush?: boolean;
+    }): void;
+}
+export {};
+//# sourceMappingURL=mmtp-router.d.ts.map