import type { DecodeDimensions } from "./decode-resolution"; import { type AnySourceHandle } from "./decode-source"; import { FrameCache } from "./frame-cache"; import type { FrameId } from "./frame-timeline"; import { type KeyframeWalk, type ScrubCursor, ScrubCursorState, type ScrubFrame, type ScrubFrameListener, type ScrubTrackInfo, type SchedulerStats, type SeekIntent } from "./scrub-cursor"; import { type Sec, WebVideoEngineError } from "./types"; export interface DecodeSchedulerOptions { readonly source: AnySourceHandle; readonly cache: FrameCache; /** A cache hit within this of the target serves a crisp frame; default 50. */ readonly exactToleranceMs?: number; /** A coarse hit within this of the target serves a preview; default 250. */ readonly previewToleranceMs?: number; /** Millisecond time source for latency stats; defaults to performance.now. */ readonly now?: () => number; /** Delay before scrub-neighbor prefetch; overridable for deterministic tests. */ readonly scrubPrefetchQuietMs?: number; /** * Opens a fresh source handle to replace a wedged decoder, or null when the * source cannot be re-opened (a one-shot stream). mediabunny decodes take no * AbortSignal, so a hung decode is uncancellable; the watchdog disposes the * dead provider and rebuilds from this seam so later decodes work. Omitted in * tests that do not exercise recovery, where the scheduler degrades instead. */ readonly reopen?: (() => Promise) | null; /** * Hang ceiling for one random-access decode; defaults to the runtime * constant. A decode that outruns it is treated as failed and triggers * provider recovery. Overridable so a test can drive it with fake timers at a * small value. */ readonly decodeHangTimeoutMs?: number; /** * Hang ceiling for the first-frame seed; defaults to the runtime constant, * which is tighter than the one above. Overridable so a test can drive it * with fake timers at a small value. */ readonly seedHangTimeoutMs?: number; /** * Called once, with the failure, when the decoder is judged unable to decode * this source at all. Nothing else tells a consumer: a stalled decoder still * accepts every command and answers none of them, so without this the * transport reads as playing over a canvas that will never change again. */ readonly onDecodeFailure?: (error: WebVideoEngineError) => void; } /** Bounds the clone payload while preserving the first and last discovered * anchors and sampling the interior evenly. GOP statistics still use the full * index; only the diagnostic lane is thinned. */ export declare function boundedKeyframeTimestamps(keyframesS: readonly number[]): number[]; /** * Caching scrub cursor. Wraps the same decode primitives as CanvasSinkScrubCursor * but routes every random-access seek through a two-tier FrameCache and prefetches * a decode window around the playhead so the next move is already in hand. * * A scrub first reads the cache. An exact hit needs no decode. A preview hit * paints a coarse frame at once, then a crisp decode follows. A miss decodes * straight away. Once the foreground frame settles, a background sweep fills the * cache around the playhead, shaped by how the consumer is moving: neighbor * frames while scrubbing or stepping, a coarse keyframe pass while idle. * * A new gesture signals the sweep to bail and proceeds without waiting for it, so * speculative work never sits on the critical path; mediabunny builds a decoder * per iterator, so a sweep still unwinding alongside a foreground decode costs * memory, not correctness. Every decoded frame is copied into the cache, never * held as a raw VideoFrame, so the decoder is never pinned. */ export declare class DecodeScheduler implements ScrubCursor { private provider; private cache; private keyframeIndex; private trackInfo; private outputGeneration; private resizingOutput; private readonly outputReads; private readonly exactTolMs; private readonly previewTolMs; private readonly now; private readonly scrubPrefetchQuietMs; /** Re-opens the source after a hung decode, or null when it cannot be re-opened. */ private readonly reopen; private readonly decodeHangTimeoutMs; private readonly seedHangTimeoutMs; /** Single-flight latch: a watchdog recovery already running. A second hang * during the rebuild awaits the same recovery rather than racing a second * dispose/rebuild of the provider. */ private recovering; /** True once a hang hit a non-re-openable source: the provider is dead and * could not be rebuilt, so decodes no-op rather than hang. Surfaced via stats * so a consumer can show a degraded state instead of a silent freeze. */ private decoderDead; /** Consecutive failed rebuilds. One is a transient read; a run of them is a * source that cannot be re-opened, which is what decoderDead describes. */ private failedRebuilds; /** True once the decoder is judged unable to decode this source at all. See * SchedulerStats.decoderStalled; latched, and it stops the rebuild loop. */ private decoderStalled; /** The failure markStalled latched, so a caller still awaiting a decode is * handed the same one the consumer was told about rather than a parallel * account of it. */ private stallFailure; /** Decode requests the live provider has left unanswered in a row; see * MAX_UNANSWERED_DECODES. */ private unansweredDecodes; private readonly onDecodeFailure; private iterator; /** The keyframe walk the play iterator was attached with, if any, so a * rebuild re-derives the same walk rather than a full one. */ private playKeyframeWalk; private nextInFlight; private nextPending; private currentState; private readonly listeners; private idleResolvers; private settleResolvers; private pendingSeekTargetS; private pendingSeekKeyOnly; private seekDraining; private closed; private lastEmittedFrame; private mode; /** Recent scrub motion. Only its heading is read, which is what decides the * side of the playhead a scrub window spends most of its budget on. */ private readonly trajectory; /** Outstanding background prefetch chain, or null once it unwinds. Awaited * only by close(), so teardown cannot outrun a sweep still holding a decoder. */ private prefetchTask; /** True only while a sweep is decoding, not while scrub prefetch is parked. */ private prefetchDecoding; /** Bumped when a running prefetch is cancelled; that prefetch bails when it * sees the token move, which is how cancellation propagates. */ private prefetchGen; /** Whether a sweep is still depending on the live token. Cleared both by the * cancellation that supersedes the sweep and by the sweep finishing. */ private prefetchArmed; /** Woken when the token moves, so a sweep parked on a decode unwinds at the * gesture rather than at the end of the decode it is parked on. */ private abandonResolvers; private scrubSamples; private scrubSumMs; private scrubMaxMs; private scrubLastMs; /** Ring of recent scrub-decode latencies for p50/p95. Overwrite-oldest so the * percentile tracks the recent region, not an all-time tail. One push/seek. */ private readonly scrubLatencyRing; private scrubLatencyCount; private scrubLatencyHead; private targetVsLandedLastMs; private timeToCrispLastMs; private foregroundDecodes; private prefetchExactFrames; private prefetchPreviewFrames; private keyframeAnchoredEmits; private exactSeeks; private keySeeks; private seekCoalesceOverwrites; constructor(options: DecodeSchedulerOptions); get state(): ScrubCursorState; get track(): ScrubTrackInfo; get playReadAhead(): number; /** Every path this scheduler drives can probe sync samples and decode one * on its own. */ readonly walksKeyframes = true; get isIdle(): boolean; resizeOutput({ width, height }: DecodeDimensions): Promise; open(): Promise; /** * The first frame, on the seed ceiling and its own attempt budget. * * A decoder that accepts this decode and never answers it is the one failure * the rest of the machinery cannot see: nothing has been asked of it twice * yet, so no request budget can run out, and open() is what the load path * awaits, so the wait ends only when the caller above gives up on the whole * worker. Bounding it here turns that into a decoder failure named at the * point it happened. * * Attempts are spent against rebuilt providers wherever the source can be * re-opened, so exhausting them means the source was re-opened that many * times and the first frame never arrived. */ private seedFirstFrame; /** * Synchronous best-effort lookup the render loop calls on scrub to paint a * frame this same tick. Pure: it reads the cache and returns a paintable * frame without touching decode or cursor state. */ peekCached(timeMs: number): ScrubFrame | null; /** * Resolves once foreground work has settled and any background prefetch * kicked by that settle has drained. The plain idle() contract excludes * prefetch so commits resolve promptly; this awaits full quiescence. */ whenSettled(): Promise; /** * Walks the whole track's keyframes into the index, metadata only, so the * diagnostics keyframe lane fills out across the entire file. Decoder-less * (it rides the EncodedPacketSink probe, never the frame sink), so it does * not contend with the foreground decode. Idempotent and best-effort: a * failure just leaves the lane as sparse as the lazy probes made it. */ ensureKeyframeIndex(): Promise; getStats(): SchedulerStats; /** Percentile over the bounded recent-latency ring. Copies the live samples * into a small scratch array and sorts; bounded by SCRUB_LATENCY_RING, and * this runs only at snapshot time, never per seek. */ private scrubPercentile; /** The targets the next prefetch sweep would decode for the current mode * and position; a pure recompute from existing state. The Idle plan is * built from the keyframes discovered so far, so it grows as the index * learns, exactly like the sweep it predicts. */ private prefetchPlanMs; seekTo(timestamp: Sec, intent?: SeekIntent): void; seekToKey(timestamp: Sec): void; /** Floors a seek target to the track's first timestamp. A seek below the * origin (an offset/trimmed clip) has no sample to land on, so it would * emit nothing; clamping lands it on the first frame instead. */ private clampToOrigin; /** Motion sampled across a pause, a step, or a stretch of playback describes * no hand still on the timeline, so leaving a scrub drops the gesture. */ private enterMode; attachPlay(startS: number, keyframeWalk?: KeyframeWalk): void; /** * The keyframe walk: it opens on the frame it was attached at, as the full * walk does, then decodes sync samples only, each on its own, the first after * the later of the one handed out last and the playhead. Every one is a fresh * anchor, so a decode costs the sync sample and whatever the decoder must be * fed past it to give it up, never the frames that depend on it. * * The opening frame is what a seek during playback waits on: the engine * settles a seek on the paint of the frame it named, and a walk that opened * on the next sync sample would never paint it. It costs the decode from the * sync sample before it, which is what opening the full walk there costs. * * Probing half a frame past a position puts the probe inside the span that * position opens, so the keyframe just handed out, or one a float round trip * lands a hair before, is never answered a second time. A walk that stops * advancing ends rather than repeating itself. */ private keyframeFrames; detachPlay(): void; next(): void; /** * Decodes one named frame of the source and emits it. * * The retrieval is at-or-before a time the frame table produced, and the * demuxer normalises that back to the same integer tick it came from, so it * lands on that frame and no other. Nothing here walks, compares or skips, * so a step across a frame boundary needs no epsilon, and a burst of steps * reuses whatever decode position the session already holds, with no * iterator opened per press. */ seekToFrame(frame: FrameId, isPresentationCurrent?: () => boolean): Promise; idle(): Promise; seekSettled(): Promise; subscribe(listener: ScrubFrameListener): () => void; close(): Promise; private drainSeek; private runSeek; private runExactSeek; /** * Whether a decode that outlived its target still improves the picture, * judged from where the gesture has since reached. A drag that outruns the * decoder supersedes every decode it starts, and the screen holds something * older than all of them, so refusing the lot pins the picture at whatever * was up when the drag began. * * Only a gesture reads this way. A jump has one destination and no * intermediate positions worth showing, so a superseded decode there is * work for a place nobody is looking. */ private gainsOnTarget; /** * Whether a cached frame earns the screen over what is already on it. A * crisp frame always does. A coarse stand-in exists to bridge the wait for a * decode, so it earns the screen only by landing closer to the target than * what is showing: replacing a crisp frame with a blurry one at the same * position is a visible drop in quality for nothing, and on a slow drag, * where each step lands within a frame of the last, it repeats several times * a second and reads as the picture flickering between sharp and soft. */ private worthPainting; private runKeySeek; private pullForwardOne; /** * Bounds a decode so a hung mediabunny decode (which takes no AbortSignal and * cannot be cancelled) never wedges the caller. On timeout it returns null and * kicks provider recovery; the orphaned decode promise is abandoned, since * there is no handle to cancel it. The healthy path resolves before the timer * and behaves exactly as a bare await: the loser timer is cleared, so it adds * no work to a decode that lands in time. * * A rejected decode takes the same route as a hung one. Every caller here is * mid-gesture with no way to answer a decode failure other than to try again * on a working decoder, and a throw would escape the fire-and-forget seek * drain and the play pull chain as an unhandled rejection. Taking that route * is also why an unanswered decode has to be counted here: the failure is * absorbed at this one point, so this is the only place that can tell a * decoder having a bad moment from one that will never answer again. */ private withDecodeWatchdog; private trackOutputRead; /** * The same watchdog over a container metadata read. Deliberately unbooked: * the keyframe probe never touches the decoder, so its answer is no evidence * that decoding works, and clearing the stall budget on one would keep a * background sweep forgiving a decoder that answers nothing. */ private withProbeWatchdog; private watchdogged; private raceWatchdog; /** * Books one decode the live provider failed to answer, and decides whether * to rebuild or to give up. A decoder that refuses outright says so in the * rejection and there is nothing to rebuild toward; otherwise the runtime * rebuilds until the request budget runs out, which is what stops a source * that re-opens cleanly and then decodes nothing from being rebuilt forever * while every surface reads as healthy. */ private noteUnanswered; /** Latches the terminal decoder failure and hands it out exactly once. */ private markStalled; /** * Rebuilds the decoder after a hung decode. The old provider is wedged on an * uncancellable decode, so it is disposed and a fresh source opened in its * place; the keyframe index is repointed at the new probe since disposing the * old input invalidated the old one. Single-flight: a second hang during the * rebuild awaits the same recovery. When the source cannot be re-opened (a * one-shot stream), the decoder is marked dead so later decodes no-op rather * than hang, leaving the engine degraded but alive instead of frozen. */ private recoverDecoder; /** * The only writer of the generation token, so no bump can move it without * also waking the sweep it cancels. A running sweep bails at its next * checkpoint and is never joined: joining it puts an unbounded background * walk on the critical path of every seek and play pull. The task handle * stays so close() can await teardown. */ private abandonPrefetch; /** Resolves the moment `gen` stops being the live prefetch generation. */ private whenAbandoned; /** * Kicks a background sweep around `aroundS` for the current access mode. * Fire-and-forget: it waits for any prior sweep to tear down so the decoder * is never used twice at once, then runs under a captured generation token. */ private schedulePrefetch; private runPrefetch; private runExactWindow; private runPreviewSweep; private residentPreviewAt; private decodeInto; /** * One sweep pull, ended by abandonment rather than by the decode it is * waiting on. A native async generator serializes its request queue, so the * return() that cancellation would issue is queued behind the in-flight * next() and lands only once that walk finishes; the pull itself cannot be * called back. The sweep therefore stops awaiting it and leaves it orphaned, * closing the sample it may still deliver, which the cache will never own. */ private pullSwept; private windowTimestamps; /** * How a window's slots divide between the way the gesture is heading and the * way it came from. An unmoving gesture has no direction to favour, so it * splits evenly, which is also what a step or an idle settle wants. */ private splitByHeading; /** * Whether reaching `t` backwards is worth it, measured in frames the walk * from its keyframe would decode. The index is what the runtime knows so far, * so an empty one is no evidence and does not veto: guessing a source has no * keyframes would throw away every backward slot on a source that has plenty. */ private walkToTargetAffordable; /** * Per-side neighbor count for the current mode, clamped so the whole window * (both sides plus the center already in hand) fits the exact tier. A window * wider than the tier would evict its own freshly decoded frames, so a * re-scrub into the swept region would still miss. */ private perSideWindowFrames; private frameIntervalS; private currentPositionS; /** The timeline's name for a decoded frame, which is what the exact cache * tier stores it under. Two decodes of one frame land on one identity * however their microsecond timestamps differ, and two frames never share * one however close together the source puts them. */ private frameIdOf; /** The timeline identity of the frame covering a presentation time. */ private frameAtTime; private emitDecoded; /** Puts a decoded frame in both tiers without painting it, and releases it. * For a frame worth keeping whose moment to be seen has passed. */ private cacheDecoded; private emitCached; private emit; private frameFromCache; private recordScrubLatency; private flushIdleResolvers; private flushSettleResolvers; }