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

package/dist/multicast-manager.d.ts

@@ -0,0 +1,669 @@
+/**
+ * Facade composing FECManager + MmtpRouter + MulticastTransport.
+ *
+ * Public methods delegate to the decomposed components. Applications that
+ * need individual layers can use them directly:
+ * - FECManager  — codec-agnostic FEC decode
+ * - MmtpRouter  — MMTP packet parsing + frame routing
+ * - MulticastTransport — SSM join/socket/watchdog
+ */
+import { type FecBlockProfile } from "@blockcast/mmt-base";
+import { FECManager, type FECManagerConfig, type WasmFecDecoder, type FecDecoderUnavailableReason, type FecFallbackDecoder, type MulticastSymbolDelivery, type RepairVia } from "./fec-manager.js";
+import { type BlockClass, type ClassifierMode, type ClassifierReason, type FrameGapDecision, type ReclassificationEvidence, type RepairPriority, type TrackKind } from "./block-policy.js";
+import type { RepairPriorityReason, RepairSkipReason, RepairSubscribeCallback } from "./repair-fetch.js";
+import { MmtpRouter, type FrameCallback, type ManifestIdentityResolver, type MmtpIngressContext, type MmtpStreamIdentity, type StreamSwitchCommit, type TrackPacketCallback } from "./mmtp-router.js";
+import { MulticastTransport, type MulticastFailbackReason, type MulticastJoinOutcome, type MulticastJoinStats } from "./multicast-transport.js";
+import type { FecTrackStats, FecWorkerClient } from "@blockcast/fec-worker";
+import type { MfuReassemblerBackend } from "./mfu-reassembler.js";
+import type { MfuReassemblyPolicy } from "./mfu-reassembly-policy.js";
+import type { ManifestObjectIdentity, ManifestVerifier } from "@blockcast/mmt-manifest-verify";
+import type { BlockAssemblerConfig, CmafBlockSample } from "./cmaf-block-assembler.js";
+export interface MulticastEndpointConfig {
+    sourceAddress: string;
+    groupAddress: string;
+    port: number;
+    /** Explicit gateway transport policy. Omitted means gateway-selected auto mode. */
+    mode?: 'auto' | 'native' | 'tunnel';
+    /** AMT relay hostname/IP from catalog endpoint. */
+    relayAddress?: string;
+    /** AMT relay port from catalog endpoint. */
+    relayPort?: number;
+    /** AMT relay hostname/IP from player/UI overrides. Wins over `relayAddress`. */
+    amtRelay?: string;
+    /** AMT relay port from player/UI overrides. Wins over `relayPort`. */
+    amtRelayPort?: number;
+    /** MMTP packet IDs to forward before data enters the page transport queue. */
+    packetIds?: number[];
+    /** Exact catalog tracks carried by this physical multicast endpoint. */
+    tracks?: MmtpIngressContext["tracks"];
+    /**
+     * The catalog `fec.blockProfile` (BLO-35597): `k-padded-v1` or
+     * `iso-ssbg1-v1`. Required for per-track FEC configuration; never defaulted.
+     */
+    fecBlockProfile?: FecBlockProfile;
+    fecK?: number;
+    /** Number of repair symbols per FEC block (P). Used to size recovery reorder latency. */
+    fecRepairSymbols?: number;
+    /** Symbol size in bytes (T). NOT repair count. */
+    fecSymbolSize?: number;
+    /** Catalog fec.reorderToleranceMs — signaled jitter/reorder allowance, ADDED
+     *  to the derived delivery window. Never a multiplier on the span, so one
+     *  network yields the same slack on a wide video span and a narrow audio one.
+     *
+     *  Absence widens the window by zero rather than throwing, unlike the datagram
+     *  MFU deadline in hang-mmt-fec. The distinction is which way absence fails:
+     *  there the tolerance IS the deadline's slack term and guessing one invents
+     *  a reorder budget, so it must fail loud; here the window is already fully
+     *  derived from other catalog values and the tolerance only widens it, so
+     *  adding nothing is the identity and errs toward earlier failback. Do not
+     *  "harmonize" this into a throw, and do not turn the zero into a default. */
+    fecReorderToleranceMs?: number;
+    fecInterleaveDepthMs?: number;
+    /** Aggregate endpoint bandwidth in bits per second from the multicast catalog. */
+    bandwidth?: number;
+    fps?: number;
+    /** Track media kind (repair class `audio` vs video block classification). */
+    trackKind?: TrackKind;
+    /** Catalog codec string (video conceal mode, codec-aware RAP checks). */
+    codec?: string;
+    /** Catalog track timescale for `keyframeIntervalTicks`. */
+    timescale?: number;
+    /** Raw catalog `keyframeIntervalTicks` (never a resolved cadence). */
+    keyframeIntervalTicks?: number;
+    /** Raw catalog `keyframeIntervalMs` (never a resolved cadence). */
+    keyframeIntervalMs?: number;
+    /** Catalog-derived lower bound for packet-silence failback (for example, keyframe repair cadence). */
+    minimumFailbackWindowMs?: number;
+}
+export interface MulticastManagerOptions {
+    /**
+     * MFU reassembly timeout (ms). Threaded to the inner MmtpRouter (and its
+     * MmtpContainerParser). Caller derives from catalog `fec.interleaveDepthMs`,
+     * which is already in milliseconds — `moqenc_mmt.c` converts
+     * `depth_ms = fec_depth * (1000/fps)` before populating the catalog.
+     * Defaults to 1000ms (with parser warning) when omitted.
+     */
+    mfuTimeoutMs?: number;
+    reassemblyPolicy?: MfuReassemblyPolicy;
+    reassembler?: MfuReassemblerBackend;
+    maxBufferedMfus?: number;
+    manifestVerifier?: ManifestVerifier;
+    manifestVerifierOwnership?: "caller" | "router";
+    resolveManifestIdentity?: (packetId: number, sbn: number, esi: number, catalogTrackName?: string) => ManifestObjectIdentity | null;
+    resolveManifestIdentityForRoute?: ManifestIdentityResolver;
+    /**
+     * Also write every repair lifecycle event to the console as one
+     * `REPAIR_LIFECYCLE_LOG_PREFIX` JSON line. Off unless asked for: the lines
+     * are serialized on the page thread for every failed block and repair step
+     * (and again for an attached inspector), and addRepairLifecycleObserver is
+     * the lifecycle API. Enable only for interactive debugging (BLO-36599).
+     */
+    logRepairLifecycle?: boolean;
+}
+/**
+ * An in-place video rendition switch on the live join: MulticastManager
+ * .switchRendition. Every rendition of a ladder can share one SSM group and
+ * differ only by MMTP packet ID, so the switch remaps packet IDs at a RAP
+ * instead of leaving and re-joining the group.
+ */
+export interface RenditionSwitchRequest {
+    /** The rendition playing now: an ingress track of the live join. */
+    readonly from: MmtpStreamIdentity;
+    /**
+     * The rendition replacing it, already registered as video with everything
+     * it plays through (setPacketIdType, setTrackCodec, configureTrackFec, its
+     * FEC decoder, frame and init callbacks, MSE assembler, repair owner).
+     */
+    readonly to: MmtpStreamIdentity;
+    /**
+     * The live join's complete ingress once the switch commits: every track
+     * that stays admitted (audio, repair legs) plus `to` and its repair legs.
+     * It must carry `to`, nothing on `from`'s packet ID (the commit retires
+     * it), and no live packet ID under another name.
+     */
+    readonly tracks: MmtpIngressContext["tracks"];
+    /**
+     * The allow-list once the switch commits, when it changes: an allow-list
+     * scoped to the active rendition. Omit it for a rendition-stable allow-list
+     * that already admits `to`; the live allow-list is then kept unchanged.
+     */
+    readonly packetIds?: readonly number[];
+    /**
+     * Called synchronously at the commit, inside the frame path, after `from`
+     * is retired and the admission narrowed, and before `to`'s newest init and
+     * its RAP are delivered: reconfigure the decoder here. Throwing fails the
+     * switch (`commit-failed`): `from` cannot be restored, so `to` is retired
+     * as well and none of it is delivered.
+     */
+    readonly onCommit: (commit: StreamSwitchCommit) => void;
+    /** Called once when the switch ends without a completed commit. */
+    readonly onCancel: (cancel: RenditionSwitchCancel) => void;
+}
+/**
+ * Why a staged rendition switch ended without a completed commit.
+ *
+ * - `cancelled`: RenditionSwitch.cancel().
+ * - `superseded`: join() or dispose() replaced the admission it was staged on.
+ * - `provider-refused`: the subscription refused to widen its packet filter to
+ *   `to`, so `to` can never arrive.
+ * - `commit-failed`: `onCommit` threw. `from` was already retired, so `to` is
+ *   retired as well and the subscription now delivers neither rendition;
+ *   recover with join().
+ */
+export type RenditionSwitchCancel = {
+    readonly reason: "cancelled";
+} | {
+    readonly reason: "superseded";
+} | {
+    readonly reason: "provider-refused";
+    readonly error: unknown;
+} | {
+    readonly reason: "commit-failed";
+    readonly error: unknown;
+};
+export type RenditionSwitchState = "staged" | "committed" | "cancelled" | "failed";
+/** A rendition switch MulticastManager.switchRendition staged. */
+export interface RenditionSwitch {
+    readonly state: RenditionSwitchState;
+    /**
+     * Abandon the switch before it commits: the pre-switch admission is
+     * restored and `to` is retired (its router registrations and FEC state
+     * released). Returns false once the switch committed or ended.
+     */
+    cancel(): boolean;
+}
+export interface RepairStreamIdentity {
+    readonly packetId: number;
+    /** Non-empty catalog identity, or null when the producer has no track name. */
+    readonly catalogTrackName: string | null;
+}
+export interface RepairBlockIdentity extends RepairStreamIdentity {
+    readonly sbn: number;
+}
+interface RepairSymbolCounts {
+    readonly multicast: number;
+    readonly moq: number;
+}
+/**
+ * Typed repair lifecycle, version 2 (keyframe-protected FEC policy). One
+ * clean cut from version 1: there is no v1 emit and no alias.
+ *
+ * - `requested`: a block short of its source at the repair deadline; its
+ *   class sets the QUIC repair priority (P0 keyframe/unknown, P1 audio,
+ *   P2 delta).
+ * - `reclassified`: new evidence (or a disabled classifier) changed a block's
+ *   class.
+ * - `recovered` / `failed`: every block that could not complete from its
+ *   first-arrival source symbols resolves with exactly one of these.
+ * - `repair-preempted` / `repair-deferred`: the scheduler aborted a delta
+ *   repair for keyframe work, or never ran it before its block resolved.
+ * - `repair-priority`: the catalog could not supply the SUBSCRIBER_PRIORITY a
+ *   repair FETCH must carry (draft-ramadan-moq-fec §11.4.5), so the FETCH was
+ *   sent without the parameter (`omitted`, keyframe/unknown blocks) or not
+ *   sent at all (`declined`, delta/audio blocks).
+ * - `classifier`: a video stream's classifier mode and why.
+ * - `gap`: the stall/conceal decision attached to the first frame released
+ *   after a lossy gap — the very object carried as `gapBefore`.
+ * - `decoder-unavailable`: a stream's Worker decoder left routing.
+ */
+export type RepairLifecycleEvent = {
+    readonly version: 2;
+    readonly type: "requested";
+    readonly block: RepairBlockIdentity;
+    readonly blockClass: BlockClass;
+    readonly priority: RepairPriority;
+} | {
+    readonly version: 2;
+    readonly type: "reclassified";
+    readonly block: RepairBlockIdentity;
+    readonly from: BlockClass;
+    readonly to: BlockClass;
+    readonly evidence: ReclassificationEvidence;
+} | {
+    readonly version: 2;
+    readonly type: "recovered";
+    readonly block: RepairBlockIdentity;
+    readonly blockClass: BlockClass;
+    readonly via: RepairVia;
+    readonly symbols: RepairSymbolCounts;
+} | {
+    readonly version: 2;
+    readonly type: "failed";
+    readonly block: RepairBlockIdentity;
+    readonly blockClass: BlockClass;
+    readonly symbols: RepairSymbolCounts;
+} | {
+    readonly version: 2;
+    readonly type: "repair-preempted" | "repair-deferred";
+    readonly block: RepairBlockIdentity;
+} | {
+    readonly version: 2;
+    /**
+     * The scheduler sent no FETCH for a requested block (BLO-35597): the
+     * measured reliable-path RTT could not come back before the block's
+     * presentation deadline, the path offered no RTT, or the player gave
+     * no presentation delay. `rttMs` is null when unmeasured; `budgetMs` is
+     * the time that was left to the deadline.
+     */
+    readonly type: "repair-skipped";
+    readonly block: RepairBlockIdentity;
+    readonly reason: RepairSkipReason;
+    readonly rttMs: number | null;
+    readonly budgetMs: number;
+} | {
+    readonly version: 2;
+    readonly type: "repair-priority";
+    readonly block: RepairBlockIdentity;
+    readonly blockClass: BlockClass;
+    readonly action: "omitted" | "declined";
+    readonly reason: RepairPriorityReason;
+} | {
+    readonly version: 2;
+    readonly type: "classifier";
+    readonly stream: RepairStreamIdentity;
+    readonly mode: ClassifierMode;
+    readonly reason: ClassifierReason | null;
+} | FrameGapDecision | {
+    readonly version: 2;
+    /**
+     * The stream's Worker decoder left routing (FECManager.clearFecWorker,
+     * or a disposed client evicted on its next symbol). `fallbackDecoder`
+     * says what still decodes the stream: 'sync' when a synchronous WASM
+     * decoder registered for the same stream keeps serving it, 'none' when
+     * nothing does. Only 'none' means the stream's symbols reach no decoder
+     * until a host registers one again; consumers fail closed on that
+     * instead of reading the following silence as a clean stream.
+     */
+    readonly type: "decoder-unavailable";
+    readonly stream: RepairStreamIdentity;
+    readonly reason: FecDecoderUnavailableReason;
+    readonly fallbackDecoder: FecFallbackDecoder;
+};
+/**
+ * Keyframe-protected repair policy counters for one catalog track. Reset
+ * whenever the track's epoch changes (catalog geometry change or reset).
+ *
+ * "Protected" means the block was short of its source at the repair deadline
+ * with class `keyframe` or `unknown`. The `keyframe*` recovered/failed
+ * counters cover every P0 block (class `keyframe` or `unknown`).
+ */
+export interface BlockPolicyStats {
+    readonly packetId: number;
+    readonly catalogTrackName: string | null;
+    readonly epoch: number;
+    classifierMode: ClassifierMode | null;
+    classifierReason: ClassifierReason | null;
+    keyframeBlocksProtected: number;
+    unknownBlocksProtected: number;
+    keyframeBlocksRecoveredInband: number;
+    keyframeBlocksRecoveredQuic: number;
+    keyframeBlocksFailed: number;
+    deltaBlocksShort: number;
+    deltaBlocksRecoveredInband: number;
+    deltaBlocksRecoveredQuic: number;
+    deltaRepairsPreempted: number;
+    deltaRepairsDeferred: number;
+    /** Repair requests sent no FETCH (see the `repair-skipped` event). */
+    repairsSkipped: number;
+    deltaBlocksFailed: number;
+    audioBlocksRecoveredInband: number;
+    audioBlocksRecoveredQuic: number;
+    audioBlocksFailed: number;
+    stalls: number;
+    concealedBlocks: number;
+    concealedGaps: number;
+    concealedFrames: number;
+    concealedAudioMs: number;
+    vanishedBlocks: number;
+}
+export type RepairLifecycleObserver = (event: RepairLifecycleEvent) => void;
+export interface RepairLifecycleSource {
+    addRepairLifecycleObserver(observer: RepairLifecycleObserver): () => void;
+}
+/** Minimal event shape accepted by application-owned event targets. */
+export interface RepairLifecycleApplicationEvent {
+    readonly type: string;
+    readonly detail: RepairLifecycleEvent;
+}
+/** DOM EventTarget event shape, including the Node 18 Event fallback. */
+export interface RepairLifecycleDomEvent extends Event {
+    readonly detail: RepairLifecycleEvent;
+}
+/** Structural target contract shared by DOM and Closure-style event targets. */
+export interface RepairLifecycleEventTarget<TEvent extends RepairLifecycleApplicationEvent> {
+    dispatchEvent(event: TEvent): unknown;
+}
+export interface RepairLifecycleEventOptions<TEvent extends RepairLifecycleApplicationEvent = RepairLifecycleDomEvent> {
+    bubbles?: boolean;
+    composed?: boolean;
+    createEvent?: RepairLifecycleEventFactory<TEvent>;
+}
+export type RepairLifecycleEventFactory<TEvent extends RepairLifecycleApplicationEvent = RepairLifecycleDomEvent> = (type: typeof REPAIR_LIFECYCLE_EVENT_TYPE, detail: RepairLifecycleEvent, options: Readonly<{
+    bubbles: boolean;
+    composed: boolean;
+}>) => TEvent;
+/** Public EventTarget event carrying an immutable RepairLifecycleEvent detail. */
+export declare const REPAIR_LIFECYCLE_EVENT_TYPE = "repairlifecycle";
+/** Diagnostic JSON-lines prefix. Never consume logs as a lifecycle API. */
+export declare const REPAIR_LIFECYCLE_LOG_PREFIX = "[MulticastManager] repair-lifecycle ";
+/** Runtime guard for observer, DOM-event, and cross-realm consumers. */
+export declare function isRepairLifecycleEvent(value: unknown): value is RepairLifecycleEvent;
+/**
+ * Forward typed repair lifecycle observations through an application-owned
+ * EventTarget. The adapter retains no history; the returned function detaches
+ * the observer.
+ */
+export declare function forwardRepairLifecycleEvents<TEvent extends RepairLifecycleApplicationEvent>(source: RepairLifecycleSource, target: RepairLifecycleEventTarget<TEvent>, options: RepairLifecycleEventOptions<TEvent> & {
+    createEvent: RepairLifecycleEventFactory<TEvent>;
+}): () => void;
+export declare function forwardRepairLifecycleEvents(source: RepairLifecycleSource, target: EventTarget, options?: RepairLifecycleEventOptions): () => void;
+/** Catalog track descriptor for configureMultiTrack(). */
+export interface MultiTrackCatalogTrack {
+    name: string;
+    altGroup?: number;
+    framerate?: number;
+    fec?: unknown;
+    /** PacketId for testability — in production, learned at subscribe time (Plan 03). */
+    packetId?: number;
+    /** `"fec-repair"` marks a self-describing repair track (draft-ramadan-moq-fec
+     *  §6.3). Absent on media tracks and on naming-era catalogs. */
+    packaging?: string;
+    /** The one source track this repair track carries repair symbols for. Layers
+     *  1..n and a keyframe overlay are reachable only through `depends`; layer 0
+     *  is additionally named by the source's `fec.repairTrack`. */
+    depends?: string[];
+    /** Base layer index. Absent on a keyframe overlay, which is a separate FEC
+     *  instance rather than a member of the layer chain. */
+    repairLayer?: number;
+    /** `"keyframe"` on an overlay track. */
+    scope?: string;
+}
+/** Multi-track catalog shape accepted by configureMultiTrack(). */
+export interface MultiTrackCatalog {
+    tracks: MultiTrackCatalogTrack[];
+}
+/** Creates one stateful synchronous FEC decoder per physical catalog stream. */
+export type WasmFecDecoderFactory = (track: Readonly<MultiTrackCatalogTrack>) => WasmFecDecoder;
+export declare class MulticastManager {
+    #private;
+    constructor(options?: MulticastManagerOptions);
+    get fecManager(): FECManager;
+    get router(): MmtpRouter;
+    get transport(): MulticastTransport<MmtpIngressContext>;
+    get reassembler(): MfuReassemblerBackend;
+    get diagnostics(): {
+        _fec: {
+            timeoutMs: number;
+            activeBlocks: number;
+            completedBlocks: number;
+            cleanlyCompletedBlocks: number;
+            pendingCounts: {
+                [k: string]: number;
+            };
+            fpsDetected: boolean;
+            interleaveDepthMs: number;
+            startupAlignedPackets: number[];
+            startupPartialBlocks: number;
+            startupRepairReadyPackets: number[];
+            startupRepairFailOpenPackets: number[];
+            pendingWorkerCleanups: number;
+            decoderUnavailableEvents: number;
+            repairTrackedBlocks: number;
+            multicastSymbolDelivery: MulticastSymbolDelivery;
+            orderedFrontiers: {
+                [k: string]: number;
+            };
+            orderedPendingBlocks: number;
+            lifecycleTrace: {
+                atMs: number;
+                event: "repair-requested" | "repair-arrived" | "timeout-queued" | "horizon-settled" | "cleanup-ack" | "cleanup-ack-timeout" | "recovered" | "failed" | "decoder-unavailable";
+                packetId: number;
+                sbn: number;
+                catalogTrackName?: string;
+                sourceCount: number;
+                sourceEsis: number[];
+                repairRsIds: number[];
+                decoderPath: "worker" | "sync" | "none";
+                deadlineRemainingMs?: number;
+                pendingCleanup: boolean;
+                rsId?: number;
+            }[];
+        };
+    };
+    get stats(): import("./multicast-transport.js").MulticastTransportStats;
+    /**
+     * See MulticastTransport.lastJoinOutcome: how the newest join() to resolve
+     * did, and the typed reason it resolved false. join() here adds no false
+     * path of its own, so every false it returns is named there; a join() that
+     * rejects (catalog FEC configuration that configureFec refuses, for one)
+     * records nothing.
+     */
+    get lastJoinOutcome(): MulticastJoinOutcome | undefined;
+    /** See MulticastTransport.joinStats: join() calls by how they resolved. */
+    get joinStats(): MulticastJoinStats;
+    /**
+     * Accepted bytes for these MMTP packet_ids, cumulative like
+     * `stats.bytesReceived`; see MulticastTransport.bytesReceivedForPacketIds.
+     * Scopes an ABR throughput sample to the active tier when the join admits
+     * more packet_ids than that tier's. Monotonic only while the set is fixed:
+     * re-baseline when the queried set changes (e.g. on a tier switch).
+     */
+    bytesReceivedForPacketIds(packetIds: ReadonlySet<number>): number;
+    get fecStats(): import("./fec-manager.js").FecStats;
+    /** The raw WASM decoder for stats access */
+    get wasmDecoder(): WasmFecDecoder | null;
+    setFecDecoder(packetId: number, client: WasmFecDecoder, k: number, trackType?: "video" | "audio", config?: FECManagerConfig, catalogTrackName?: string): void;
+    /**
+     * Register a Worker-backed FEC decoder for a specific packetId (track).
+     * Worker-backed tracks decode asynchronously — recovered frames arrive via
+     * FECManager.onBlockRecovered callback instead of feedSourceSymbol return value.
+     */
+    setFecWorker(packetId: number, client: FecWorkerClient, trackType: "video" | "audio", config: FECManagerConfig, catalogTrackName?: string): void;
+    /**
+     * Stop routing a stream's symbols to its Worker decoder. Returns false when
+     * none is registered; on success one `decoder-unavailable` repair lifecycle
+     * event with reason 'cleared' reaches every observer, carrying whether a
+     * synchronous WASM decoder still serves the stream. The packet mapping and
+     * track type are untouched: the track still exists, it just has no Worker
+     * decoder. Call this before disposing the client.
+     */
+    clearFecWorker(packetId: number, catalogTrackName?: string): boolean;
+    /** Register callback for Worker-level FecTrackStats updates. */
+    setOnFecStatsUpdate(cb: (packetId: number, stats: FecTrackStats) => void): void;
+    setFramerate(fps: number): void;
+    /**
+     * Configure one track's FEC geometry, block mapper, and block-inactivity
+     * deadline from that track's own catalog values, then re-reduce the
+     * stream-global deadlines across every registered track.
+     *
+     * This is the packet-specific replacement for the global `configureFec`
+     * side effects: per-track concerns stay per-track, and the genuinely
+     * stream-global ones (transport failback, router MFU timeout, router reorder
+     * window) become an explicit max reduction instead of a last-caller-wins race
+     * in which whichever track configured last silently set the whole stream's
+     * timing.
+     *
+     * `catalogTrackName` scopes the block-classifier geometry (kind, fps,
+     * interleave, cadence) to that one stream. Pass it whenever ABR rungs can
+     * share this packetId: each rung then classifies with its own framerate
+     * and GOP, and a rung on the packetId that was never configured this way
+     * runs all-protected (`stream-geometry-absent`) instead of borrowing a
+     * sibling's geometry. K, T and the delivery timing stay per packetId.
+     */
+    configureTrackFec(packetId: number, config: Pick<MulticastEndpointConfig, "fecBlockProfile" | "fecK" | "fecRepairSymbols" | "fecSymbolSize" | "fecInterleaveDepthMs" | "fecReorderToleranceMs" | "fps" | "bandwidth" | "minimumFailbackWindowMs" | "trackKind" | "codec" | "timescale" | "keyframeIntervalTicks" | "keyframeIntervalMs">, catalogTrackName?: string): void;
+    configureFec(config: Pick<MulticastEndpointConfig, "fecBlockProfile" | "fecK" | "fecRepairSymbols" | "fecSymbolSize" | "fecInterleaveDepthMs" | "fecReorderToleranceMs" | "fps" | "bandwidth" | "minimumFailbackWindowMs">): void;
+    /** Register callback for track type discovery (from init data / inline signaling). */
+    onTrackTypeDiscovered(cb: (packetId: number, trackType: "video" | "audio") => void): void;
+    setPacketIdType(packetId: number, trackType: "video" | "audio"): void;
+    /**
+     * Set the keyframe loss timeout on the inner MmtpRouter (Phase 13).
+     * Applies only to tracks WITHOUT FEC: an FEC track never arms the timer,
+     * because its vanished blocks resolve through catalog-derived block
+     * deadlines and the release gate's stall decision.
+     * Must be called BEFORE setPacketIdType('video'). A reader is passed
+     * through; see MmtpRouter.setKeyframeLostTimeoutMs.
+     */
+    setKeyframeLostTimeoutMs(ms: number | (() => number)): void;
+    setMfuTimeoutMs(ms: number): void;
+    setTrackCodec(packetId: number, codec: string): void;
+    onVideoFrame(cb: FrameCallback): void;
+    onAudioFrame(cb: FrameCallback): void;
+    onTrackFrame(packetId: number, cb: FrameCallback): void;
+    onTrackPacket(packetId: number, cb: TrackPacketCallback): void;
+    onInitSegment(cb: (data: Uint8Array) => void): void;
+    onTrackInit(packetId: number, cb: (data: Uint8Array) => void): void;
+    onFecBlockStarted(cb: (sbn: number, packetId: number) => void): void;
+    /** Unrecoverable-FEC-block signal. Players drive decoder recovery from this
+     *  (a starved decoder cannot resync on its own once the block is abandoned). */
+    onFecBlockFailed(cb: (sbn: number, packetId: number, catalogTrackName?: string) => void): void;
+    enableMseAssembler(packetId: number, config: Omit<BlockAssemblerConfig, "k">, catalogTrackName?: string): import("./cmaf-block-assembler.js").CmafBlockAssembler;
+    onMseSegment(packetId: number, cb: (segment: Uint8Array) => void, catalogTrackName?: string): void;
+    onMseSample(packetId: number, cb: (sample: CmafBlockSample) => void, catalogTrackName?: string): void;
+    onMseInitSegment(packetId: number, cb: (init: Uint8Array) => void, catalogTrackName?: string): void;
+    emitMseInit(packetId: number, catalogTrackName?: string): void;
+    markExternalVideoSync(packetId?: number, catalogTrackName?: string): void;
+    onTakeover(cb: () => void): void;
+    onFailback(cb: (reason: MulticastFailbackReason) => void): void;
+    /** See MulticastTransport.onDataPlaneLive: the join's first accepted packet. */
+    onDataPlaneLive(cb: () => void): void;
+    confirmVideo(): void;
+    confirmAudio(): void;
+    static isAvailable(): boolean;
+    join(config: MulticastEndpointConfig): Promise<boolean>;
+    /**
+     * Switch the live join from one video rendition to another in place: the
+     * subscription (socket, group membership, AMT tunnel) is kept, and the
+     * packet-ID remap commits atomically at a RAP of the incoming rendition.
+     *
+     * Staging widens the admission to carry both renditions: the ingress
+     * tracks become the live ones plus `tracks`, and, when `packetIds` is
+     * given, the allow-list becomes the live one plus `packetIds` (a provider
+     * that cannot widen in place is refused here, before anything changes).
+     * The incoming rendition's packets then feed its FEC and parser while the
+     * outgoing rendition keeps playing, and MmtpRouter.stageStreamSwitch
+     * withholds every incoming frame and its init until the commit.
+     *
+     * The commit is one synchronous step inside the frame path, at the
+     * incoming RAP (see MmtpRouter.stageStreamSwitch for where exactly): the
+     * outgoing packet ID is retired from the router, the admission becomes
+     * exactly `tracks` (and `packetIds`), the outgoing stream's FEC and repair
+     * state is released (FECManager.releasePacket; repair fetches in flight are
+     * aborted through the track-reset observers), `onCommit` runs, and then the
+     * incoming init and RAP are delivered. No outgoing frame is delivered after
+     * it and no incoming frame before it. No timer is armed: the switch waits
+     * on RAPs and on the outgoing stream's own frames.
+     *
+     * Exactly one of `onCommit` and `onCancel` is called per switch. One switch
+     * may be staged at a time.
+     */
+    switchRendition(request: RenditionSwitchRequest): RenditionSwitch;
+    /** Feed a raw packet from an external source (AMT tunnel, ASM subscription).
+     *
+     *  For MoQ-unicast-fallback mode (no SSM bridge), call
+     *  `manager.router.feedPacket(packet, "moq")` directly to bypass
+     *  MulticastTransport's takeover/watchdog/failback gates while preserving
+     *  transport attribution in FEC path counters.
+     *  The `router` accessor above is already public.
+     */
+    feedPacket(data: ArrayBuffer | Uint8Array, ingress?: MmtpIngressContext): void;
+    /**
+     * Declare how packets given to feedPacket() reach this manager. A consumer
+     * that owns the multicast socket itself declares its own leg; join()
+     * applies what the window.multicast subscription declares instead.
+     */
+    setMulticastSymbolDelivery(delivery: MulticastSymbolDelivery): void;
+    /** Process a repair packet from MoQ (reliable QUIC). */
+    processRepairFromMoQ(packet: Uint8Array, ownerPacketId?: number, catalogTrackName?: string): void;
+    /** Route a Worker-recovered FEC block through the MMTP parser + dedup pipeline. */
+    routeRecoveredBlock(blockId: number, data: Uint8Array, packetId: number, catalogTrackName?: string): void;
+    /** Route one Worker-recovered source symbol through the MMTP parser + dedup pipeline. */
+    routeRecoveredSymbol(blockId: number, data: Uint8Array, packetId: number, esi?: number, catalogTrackName?: string): void;
+    /**
+     * Configure the manager for a multi-track (base/delta/repair) CMAF switching set.
+     *
+     * D-04: Validates completeness via validateSwitchingSet — throws if incomplete.
+     * D-07: Applies per-track FEC configs (base+delta get decoders; repair does not).
+     * D-17: Builds altGroup → track-name index for getSwitchingSet().
+     * D-26: Registers packetId → TrackRole on MmtpRouter for block-complete fanout.
+     *
+     * @param catalog - Multi-track catalog (tracks array with name, altGroup, fec, packetId).
+     * @param wasmDecoderSource - One WASM FEC decoder for a single FEC stream, or
+     *                            a factory returning a distinct decoder per stream.
+     */
+    configureMultiTrack(catalog: MultiTrackCatalog, wasmDecoderSource?: WasmFecDecoder | WasmFecDecoderFactory): void;
+    /**
+     * Return the track names belonging to the given altGroup switching set.
+     * D-17: altGroup groups base+delta+repair into one switching set.
+     *
+     * @param altGroup - The altGroup number to look up.
+     * @returns Array of track names in that switching set (empty if none).
+     */
+    getSwitchingSet(altGroup: number): string[];
+    /**
+     * Register callback fired when a repair fetch should be issued for an FEC block.
+     *
+     * D-28: At most one outstanding repair fetch per (packetId, sbn) block.
+     * clearRepairForBlock fires automatically when the block resolves (via
+     * FECManager.onRepairResolved); call it manually only on fetch failure
+     * paths the FEC layer cannot observe (fetch error, range not retained,
+     * transport timeout) so a stuck fetch cannot wedge the block's slot.
+     *
+     * Registering also arms the FEC repair deadline: each block gets a one-shot
+     * timer for the derived K-symbol source-production horizon; a block still
+     * short of K when it fires requests repair here. Failure accounting timing
+     * is unchanged.
+     */
+    onRepairSubscribe(cb: RepairSubscribeCallback): void;
+    /**
+     * Record a repair request whose SUBSCRIBER_PRIORITY the catalog could not
+     * supply (draft-ramadan-moq-fec §11.4.5): sent without the parameter, or
+     * not sent. Emits one `repair-priority` lifecycle event.
+     */
+    noteRepairPriority(action: "omitted" | "declined", reason: RepairPriorityReason, blockClass: BlockClass, sbn: number, packetId: number, catalogTrackName?: string): void;
+    /** Record a repair request the scheduler sent no FETCH for. */
+    noteRepairSkipped(reason: RepairSkipReason, measurement: {
+        readonly rttMs: number | null;
+        readonly budgetMs: number;
+    }, sbn: number, packetId: number, catalogTrackName?: string): void;
+    /**
+     * Record a repair-scheduler decision about a delta block: preempted for
+     * keyframe/audio work, or never dispatched before its block resolved.
+     */
+    noteRepairScheduling(type: "repair-preempted" | "repair-deferred", sbn: number, packetId: number, catalogTrackName?: string): void;
+    /** Catalog/reset epoch of a packet's streams; gap decisions carry it. */
+    epochFor(packetId: number): number;
+    /**
+     * Keyframe-protected repair policy counters, keyed by catalog track name
+     * (`packetId:<n>` for a stream with no catalog name). Each track's
+     * counters reset with its epoch.
+     */
+    getBlockPolicyStats(): Record<string, BlockPolicyStats>;
+    /**
+     * Observe causal repair lifecycle events without retaining snapshots in the
+     * transport. Returns an unsubscribe function.
+     */
+    addRepairLifecycleObserver(observer: RepairLifecycleObserver): () => void;
+    /** Observe per-stream epoch resets (used by repair transports to abort I/O). */
+    addTrackResetObserver(observer: (packetId: number, catalogTrackName: string) => void): () => void;
+    /** Begin a fresh retained-replay epoch for one physical media stream. */
+    resetTrack(packetId: number, catalogTrackName: string): void;
+    /**
+     * Request a repair-track fetch for the given FEC block.
+     *
+     * D-28: duplicate requests for the same (packetId, sbn) are suppressed
+     * until clearRepairForBlock is called.
+     *
+     * @param sbn - Source Block Number identifying the FEC block needing repair.
+     * @param packetId - MMTP packet_id owning the block (video/audio tracks have
+     *   independent SBN spaces, so the in-flight key must be composite).
+     */
+    requestRepairForBlock(sbn: number, packetId: number, catalogTrackName: string | undefined, blockClass: BlockClass): void;
+    /**
+     * Clear in-flight repair state for the given block.
+     * Fired automatically when the block resolves; safe to call redundantly.
+     */
+    clearRepairForBlock(sbn: number, packetId: number, catalogTrackName?: string): void;
+    dispose(): void;
+}
+export {};
+//# sourceMappingURL=multicast-manager.d.ts.map