@openmoq/playback 0.0.0-stage → 0.6.0

package/dist/pipeline.d.ts

@@ -0,0 +1,215 @@
+/**
+ * Playback pipeline orchestrator.
+ *
+ * Wires jitter-buffer + gap-detector + decoder-state + sync together.
+ * Accepts MoqtObject + LocHeaders, emits DecoderCommand + PlaybackEvent.
+ *
+ * Sans-I/O: no WebCodecs, no Canvas, no AudioContext — just pure logic.
+ * The browser adapter consumes the emitted DecoderCommands.
+ *
+ * @see draft-ietf-moq-loc-01 §4.2 (decode order)
+ * @see draft-ietf-moq-transport-16 §10.2.1.1 (Object Status)
+ * @module
+ */
+import type { MoqtObject } from '@openmoq/transport';
+import type { LocHeaders } from '@openmoq/loc';
+import { SyncController } from './sync.js';
+import type { RecoveryController } from './recovery.js';
+import type { ClockSource, DecoderCommand, PlaybackEvent, PlaybackConfig, DecoderFeedback } from './types.js';
+/**
+ * Pipeline constructor options.
+ */
+export interface PipelineOptions {
+    readonly mediaType: 'video' | 'audio';
+    readonly config: PlaybackConfig;
+    readonly clock: ClockSource;
+    readonly sync: SyncController;
+    readonly onCommand: (cmd: DecoderCommand) => void;
+    readonly onEvent: (evt: PlaybackEvent) => void;
+    /** Optional recovery controller for escalation decisions. */
+    readonly recovery?: RecoveryController;
+    /** Video-only mode: set video reference from first CaptureTimestamp. */
+    readonly videoOnly?: boolean;
+    /** Live stream: enables bounded release + backlog shedding. Default: true. */
+    readonly isLive?: boolean;
+}
+/**
+ * Playback pipeline orchestrator.
+ *
+ * @see draft-ietf-moq-loc-01 §4.2
+ */
+export declare class PlaybackPipeline {
+    private readonly mediaType;
+    private readonly clock;
+    private readonly sync;
+    private readonly onCommand;
+    private readonly onEvent;
+    private readonly recovery;
+    private readonly buffer;
+    private readonly gapDetector;
+    private readonly decoderState;
+    /** Headers stored alongside objects, keyed by "groupId:objectId". */
+    private readonly headerMap;
+    /** Group reference counts in the jitter buffer. */
+    private readonly bufferedGroupCounts;
+    /** Next expected objectId within the current group for contiguity check. */
+    private nextExpectedObjectId;
+    /** Highest group from which at least one object was consumed. -1n = nothing consumed yet. */
+    private lastConsumedGroupId;
+    /** Groups for which END_OF_GROUP has been observed. */
+    private readonly endedGroups;
+    /** Timestamp when we first started waiting for active group completion. */
+    private activeGroupWaitStartUs;
+    /**
+ * Minimum group ID accepted by pushObject().
+ * Set after SKIP_FORWARD to reject stale objects from pre-skip groups
+ * that arrive late due to async QUIC stream delivery.
+ */
+    private minAcceptGroupId;
+    /** Last group for which keyframe_waiting was emitted (dedup). */
+    private lastKeyframeWaitingGroupId;
+    /**
+ * When true, the first tick syncs to whatever group is available
+ * without gap detection — avoids cascading recovery on initial
+ * live join or after pause→resume on a live stream.
+ *
+ * Starts `true` so the first arriving group is accepted as the
+ * starting point (joining mid-broadcast is not a gap).
+ */
+    private resetPending;
+    /** True once track_ended has been emitted — prevents re-emission on every tick. */
+    private _trackEnded;
+    /** Last emitted playback rate — dedup to avoid spamming commands. */
+    private _lastEmittedRate;
+    /**
+ * Throttle flag — set by decoder feedback when queue depth is high.
+ * While true, tick() evaluates gaps but does NOT drain the buffer.
+ * Objects still enter the jitter buffer (needed for gap detection).
+ */
+    private _throttled;
+    /** Adaptive jitter tolerance controller (null if disabled). */
+    private readonly adaptiveTolerance;
+    /** Max objects to release per tick (video only). 0 = unlimited. */
+    private readonly maxReleasePerTick;
+    /** Max groups before shedding old ones. 0 = unlimited. */
+    private readonly maxBacklogGroups;
+    /** Video codec string from catalog (e.g., 'avc1.42c01f'). Used for keyframe validation. */
+    private _videoCodec;
+    private _videoOnly;
+    constructor(opts: PipelineOptions);
+    /**
+ * Set the video codec string for keyframe payload validation.
+ *
+ * @param codec Codec string from catalog (e.g., 'avc1.42c01f', 'hvc1', 'av01.0.08M.10')
+ * @see draft-ietf-moq-loc-01 §4.2 (decode order)
+ */
+    setCodec(codec: string): void;
+    /**
+ * Current effective gap timeout in microseconds.
+ * When adaptive tolerance is enabled, this is auto-calibrated from jitter.
+ * Otherwise, returns the fixed configured value.
+ */
+    get effectiveGapTimeoutUs(): number;
+    /** Last consumed group ID — for track switch subscription filters. */
+    get currentGroupId(): bigint;
+    /** Number of distinct groups currently in the jitter buffer. */
+    get bufferedGroupCount(): number;
+    /** Whether draining is throttled due to decoder backpressure. */
+    get throttled(): boolean;
+    /**
+ * Handle feedback from browser adapters (decoder queue, errors, drift).
+ *
+ * @see draft-ietf-moq-loc-01 §2.3.1.1 (drift detection)
+ */
+    handleFeedback(fb: DecoderFeedback): void;
+    /**
+ * Provide codec configuration (from catalog or initial headers).
+ *
+ * This is also triggered automatically when a LOC object carries the
+ * matching config property: Video Config for video, Audio Config for
+ * audio.
+ *
+ * @param config Codec-specific configuration bytes
+ */
+    configure(config: Uint8Array): void;
+    /**
+ * Push an object into the pipeline.
+ *
+ * Data objects are buffered. Gap objects notify the gap detector.
+ *
+ * @param obj The MoqtObject (data or gap)
+ * @param headers Parsed LocHeaders (only meaningful for data objects)
+ */
+    pushObject(obj: MoqtObject, headers?: LocHeaders): void;
+    /**
+ * Reset pipeline state for pause→resume or seek.
+ *
+ * Clears the jitter buffer, gap detector, and decoder FSM so the first
+ * arriving group after resume is accepted cleanly without cascading
+ * gap-recovery escalation from the stale pre-pause position.
+ *
+ * Emits a decoder 'reset' command so the WebCodecs decoder clears its
+ * queue and waits for the next keyframe (video) or resumes immediately
+ * (audio — Opus/AAC-LC frames are independently decodable).
+ *
+ * @param targetGroupId When seeking, set this to the target group ID.
+ *   Objects from groups before this ID are rejected — prevents stale
+ *   in-flight objects from corrupting the post-seek decoder state.
+ *   @see draft-ietf-moq-transport-16 §9.11.1 — "it might still receive
+ *   Objects outside the new range if the publisher sent them before the
+ *   update was processed."
+ */
+    /**
+ * Reset for a track switch — clears jitter buffer (old-track objects
+ * use the same groupIds as new-track per altGroup alignment), resets
+ * gap detector and group tracking. Does NOT reset decoder state or
+ * emit flush/reset commands — already-decoded frames in the renderer
+ * queue play out naturally for seamless visual transition.
+ *
+ * @param firstGroupId The first group ID from the new track — sets
+ *   lastConsumedGroupId to firstGroupId-1 so the gap detector doesn't
+ *   see a gap and trigger skip_forward (which would reset sync).
+ */
+    resetForTrackSwitch(firstGroupId: bigint): void;
+    reset(targetGroupId?: bigint): void;
+    /**
+ * Process buffered objects: evaluate gaps, feed decoder FSM, emit commands.
+ *
+ * Call this on a regular interval (e.g., requestAnimationFrame or timer).
+ */
+    tick(): void;
+    /**
+ * Drop oldest whole groups when backlog exceeds maxBacklogGroups.
+ * Keeps the newest maxBacklogGroups groups, discards the rest.
+ * After shedding, notifies decoder that a gap occurred (needs keyframe).
+ */
+    private shedBacklog;
+    /**
+ * Whether late encoded VIDEO may be discarded before it reaches the decoder.
+ *
+ * Only explicitly discardable, non-independent frames may be. Everything
+ * else is NOT PROVEN SAFE TO DISCARD and is therefore preserved
+ * conservatively: RFC 9626 §3.1 defines D=1 as the sender asserting the
+ * frame can be removed while the stream stays decodable, so D=0 does not
+ * prove the frame is a reference — it means the receiver has no assurance
+ * that discarding it is safe. Absent marking is treated the same way, and
+ * an independent frame is preserved even if it also claims to be
+ * discardable.
+ *
+ * Lateness of decoded OUTPUT remains the output stage's decision.
+ *
+ * @see draft-ietf-moq-loc-01 §2.3.2.2 (Video Frame Marking)
+ */
+    private isPreDecodeDroppable;
+    /**
+ * Attempt to evict a lower-importance object to make room.
+ * @returns true if the incoming object was inserted.
+ * @see draft-ietf-moq-transport-16 §7 (Priority-based dropping)
+ */
+    private tryEvictAndInsert;
+    private processDataObject;
+    private emitFsmDecision;
+    private discardBefore;
+    private decrementGroupCount;
+}
+//# sourceMappingURL=pipeline.d.ts.map

package/dist/pipeline.d.ts.map

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