import type { MediaClock } from "./clock"; import type { RendererName } from "./diagnostics"; import { type FrameQuality, type ScrubCursor, type ScrubFrame } from "./scrub-cursor"; import type { PresentationMode } from "./types"; export declare function setDiagnosticsEnabled(enabled: boolean): void; /** Per-rAF realtime needles, collected only while diagnostics are enabled. ticks * is every loop turn; paints is every frame drawn; lateFrames is a playing frame * more than one interval behind the clock; stalls is a playing tick with no frame * to paint; catchUpMs is how far the clock has run past the last painted frame. * playQueueDepth is the decode-ahead buffer's current length: a live read, not a * per-tick accumulator, so 0 while playing means the pipeline ran dry. */ export interface RealtimeStats { readonly ticks: number; readonly paints: number; readonly lateFrames: number; readonly stalls: number; readonly catchUpMs: number; readonly playQueueDepth: number; readonly endedFired: boolean; /** Decoded frames thrown away before reaching the canvas: ones that arrived * for a position playback had left, buffered ones overtaken by the clock * moving backwards, and the ones the present cadence declines once the rate * asks for more frames a second than it. All three cost a full decode. The * first two are decode bandwidth spent on nothing; the third is the cadence * doing its job, and at a high rate it dominates the count. */ readonly droppedFrames: number; /** Same fact accumulated over the source's lifetime for the pipeline * ledger, so it can sit beside the other monotonic counters. */ readonly droppedFramesTotal: number; /** Whether the attached play walk decodes sync samples only. */ readonly keyframeWalk: boolean; } /** * Render loop. One rAF tick. Mode-aware: * * - Playing: the catch-up loop from the mediabunny media-player example. * On each tick read clock.now(); if the stashed nextFrame's timestamp * has arrived, paint it, then pull forward from the cursor in a * while-loop. Late frames paint immediately; the first future-timestamped * frame is stashed for the next tick. This matches Vanilagy's reference * pattern and prevents visible skips when the decoder lags behind the clock. * * - Paused: the cursor's most recent emission is whatever the latest * seek landed on. Tick paints it once, nulls nextFrame, and never * touches the iterator. Subsequent user input that calls seekTo * emits a fresh frame, the listener stashes it, and the next tick * paints it. * * No backup setInterval. rAF is enough: tab backgrounding will pause the * loop, but pause is the right behavior because nothing should advance * media time while the surface is not visible. * * Runs worker-side. It renders frames through a Renderer (the 2D canvas path * today, swappable for WebGPU behind the same seam); the cursor owns the frame * cache and fills it as it decodes, so this loop only reads it through * peekCached. The only way out is the onPaint callback, which EngineCore turns * into serializable state emits. No DOM, no React, no main-thread reference * ever reaches this loop. */ export interface ScrubControllerDeps { cursor: ScrubCursor; clock: MediaClock; /** catchUpMs is supplied only while diagnostics are enabled and playing, so * the engine can fold it onto the broadcast frame event; undefined otherwise. * presented carries the pixels when the sink handed them out instead of * painting them, and transfers ownership of that frame with the call. */ onPaint: (frame: ScrubFrame, catchUpMs?: number, presented?: VideoFrame | null) => void; /** Fired when playback runs past the source duration so the engine can * transition to Ended status. Without this the iterator yields done * forever and the play UI stays stuck on Playing while the canvas freezes. */ onEnded: () => void; /** Cache lookups whose resolved entry is closer than this to whatever * the visible canvas already shows are rejected. Forces a fresh decode * on small movements (frame-step gestures) so the user sees the actual * next/prev frame, not the cached neighbor. */ cacheSkipNearMs: number; /** Pin the 2D renderer; unset prefers WebGPU, falling back to 2D when unavailable. */ prefer2d?: boolean; /** Defaults to "canvas". Under "frames" the loop binds no canvas and every * paint yields its pixels to onPaint instead. */ presentation?: PresentationMode; } export declare class ScrubController { private readonly deps; private rafHandle; /** Paused/seek path: the single most-recent landed frame. */ private nextFrame; /** Playing path: a bounded decode-ahead buffer so a decode that overruns a * frame interval does not starve the next tick. Drained one frame per tick, * refilled toward the read-ahead depth. */ private playQueue; private sink; /** The canvas the latest bind targeted; guards the async renderer race. */ private boundCanvas; private disposed; private unsub; /** Milliseconds-rounded timestamp of whatever the visible canvas * currently shows. Updated on every paint (cursor emit OR cache hit). * Drives the skip-near-current check in tryPaintFromCache. */ private lastPaintedMs; /** Quality of what the canvas shows, so a repaint can be judged on sharpness * as well as position. */ private lastPaintedQuality; /** Set true when runTick detects clock past duration so we only emit * the onEnded transition once per playback session. */ private endedFired; private ticks; private paints; private lateFrames; private stalls; private catchUpMs; private droppedFrames; /** Lifetime companion to droppedFrames for the pipeline ledger: never reset * by a play session and not gated on diagnostics, so the ledger is honest * even about what happened before the HUD opened. */ private droppedFramesTotal; /** False from every attach of the play walk until its first frame paints. * The bootstrap pull is async, so the opening ticks find nextFrame null * and would each book a stall the user never saw. */ private paintedSincePlay; /** Whether a play session the user started is still running. A seek while * playing re-attaches the walk through endPlay and beginPlay without ever * stopping the transport, and a drag stops the transport for the length of * the gesture and walks the playhead across the source under it. Neither is * the user putting the picture down, and the per-session needles count the * session the user is watching, not the walk. */ private playSessionLive; /** Clock reading the transport stopped at, or null while it runs. A stopped * clock moves only by being seeked, so a stopped tick reading anything else * is a seek, which is why the comparison against it is exact. */ private stoppedAtS; /** Media time the current play session was attached at, which is what makes * a frame produced for a position the session has left recognisable. */ private playAnchorS; /** Media time the previous playing tick read, so a tick can price its own * span in source frames. Null until the session's second tick. */ private lastTickS; /** Clock reading at the play walk's last delivery, or null when no walk is * attached. Set at the attach too, so the walk's opening frame is priced * against the wait for it. */ private lastDeliveryS; /** Source frames this tick may pull past the one it paints, refreshed per * tick from the span the clock covered. Sourced from ticks so a loop that * stops (a hidden tab parks rAF) takes the pull chain down with it. */ private catchUpBudget; /** Clock reading at the last paint this play session put on screen, which is * what the wall-time gap between presents is measured from. Null until the * session's first paint, so an opening frame is never held for cadence. */ private lastPresentTickS; /** The share of the rate's demand the pump allows itself to present. Held as * a share rather than a frames-a-second figure so it survives a rate change * as the same statement about the machine: a pipeline that was keeping up * at 1x opens 4x at everything 4x asks for, with no ramp to climb. */ private presentShare; /** Frames the running play walk has delivered into the queue, and the two * readings the cadence loop last took: the clock, and that same count. * Between them a tick knows what it asked the pipeline for and what it got. */ private walkDelivered; private cadenceTickS; private cadenceDeliveredAt; /** Frames the pipeline owes the playhead since the cadence last moved: what * the clock has asked for, less what the walk delivered. Zeroed on every * move, so it holds the evidence for the next one rather than the ground * lost over the session. */ private cadenceBacklog; /** Wall seconds the walk has held a frame the clock has not run past, without * a break, which is the only evidence a pipeline can offer that it has room * to spare. */ private cadenceCushionS; /** Whether the attached walk decodes sync samples only. See PLAYBACK. */ private keyframeWalk; /** The lowest rate this play session has seen the full walk fall behind at, * or null until it has. Every rate from it up takes the keyframe walk. Like * the present share, it belongs to the session that measured it. */ private fullWalkShortRate; /** Wall seconds every frame the full walk delivered has arrived further * behind the clock than PLAYBACK.KEYFRAME_WALK_TRAIL_MS, without a break. */ private fullWalkTrailingS; /** Clock reading of the previous late delivery, or null before the first. */ private fullWalkLastLateS; /** Media time of the frame the walk delivered last, or null since the walk * was attached. */ private lastDeliveredFrameS; /** Widest gap between two frames the keyframe walk delivered, which is how * far apart frames legitimately arrive on it. */ private keyframeSpanS; constructor(deps: ScrubControllerDeps); /** * Routes an arriving frame. While playing it appends to the decode-ahead * queue and chains another pull until the read-ahead depth is reached (the * cursor's one-in-flight latch makes the extra pulls free no-ops). While * paused it replaces the single stashed frame, closing the superseded one * when it is an unpainted sample so a fast drag does not leak VideoSamples. */ private stash; /** * Decoded frames to keep queued ahead of the playhead. The decode path * decides it, not the shape of the frame: reading it off the frame treated * every sample-carrying path as pool-bound, which the long-lived decode * session is not, so the default path ran with a queue of one and no cushion * at all. A cushion is the whole point, it is what stops a decode that * overruns one frame interval from starving the next paint. */ private readAhead; /** * Whether a frame arriving while the clock runs belongs to the running play * session. The controller receives every frame the cursor emits, not only * the ones its own pulls asked for, so a seek still landing when playback * resumes delivers a frame for a position the session has already left. * Queued, that frame sits at the head never due, which blocks the paint and * the refill alike, and playback resumes only once the clock has run all the * way to it: exactly as long as the jump the user just made. */ private belongsToPlaySession; /** * Whether a queued frame is further ahead of the clock than playback can * legitimately buffer. Play frames come from an iterator anchored at the * playhead, so the buffer leads the clock by its own depth and no more. A * frame past that either arrived for a position the session has left, or was * overtaken when the clock moved backwards under the queue, which a step or * a seek during playback both do. */ private beyondPlayHorizon; /** * How far apart the walk's frames legitimately arrive: one source frame on * the full walk, and the widest gap between two sync samples it has seen on * the keyframe walk. A cursor that walks every frame even when asked for * keyframes delivers source frames, and then the two figures agree. */ private walkSpanS; /** * Whether the walk is handing out frames further apart than the source's * own. A keyframe walk over a source whose every frame is a sync sample * delivers a full walk's stream, and the present cadence still has a full * walk's surplus to ration. */ private sparseWalk; /** * Whether the rate in force calls for the keyframe walk. See PLAYBACK for the * three thresholds: a floor under which motion matters more than the rate, a * demand no decoder follows frame by frame, and the rate the full walk has * been measured falling behind at. */ private wantsKeyframeWalk; /** * Prices a full-walk delivery against the clock, and books the rate in force * as one the full walk cannot keep once every delivery for * PLAYBACK.KEYFRAME_WALK_EVIDENCE_MS has arrived further behind than * PLAYBACK.KEYFRAME_WALK_TRAIL_MS. Both are wall time, the media gap over the * rate, so one lag decides at every rate. The opening frame is left out: it * carries the attach's pre-roll, which is not a rate the walk runs at. */ private observeFullWalk; /** Attaches the walk the rate calls for at startS. */ private attachWalk; /** * Moves a running session onto the other walk at the clock, when a rate * change or the full walk's own lag calls for it, and reports whether it did. * Nothing the old walk queued belongs to the new one: full-walk frames are * the backlog being abandoned, and keyframes are too sparse to fill a picture * the full walk is about to paint frame by frame. */ private switchWalk; /** * Discards every queued frame the clock has already run past except the last * one, which is the frame that belongs on screen now. * * A tick can only present one frame, so whenever more than one falls due in * the same tick the surplus has nowhere to go. Serving them one a tick * instead makes the picture drift further behind the playhead every tick, * which is what a rate past display-refresh over source-fps produces on a * pipeline that is otherwise keeping up perfectly. Skipping keeps the picture * on the playhead and charges the difference to the dropped-frame ledger, * where a consumer can see what the rate cost. */ private dropFramesTheClockHasPassed; /** * Source frames this tick may pull past the one it paints, measured as the * span the clock covered. One of them covers that span, which is what a rate * demanding more than a frame per tick needs and cannot get from a queue * bounded by read-ahead depth; the rest work off a backlog, so a pipeline a * slow stretch knocked behind can return to the playhead. */ private catchUpAllowance; /** * Presents a wall second the pump allows itself right now: the rate's demand * cut to the share the machine has been paying for, and never under the * source's own frame rate. Rate 1 asks for exactly the source rate, so its * floor and its demand are the same figure and no share can come between * them, which is what leaves 1x painting every frame of every source. */ private presentCadence; /** Forgets what the cadence loop had gathered. The walk is about to be * attached somewhere else, and a span across that move charges the pipeline * for frames it was never asked to have ready. */ private resetCadenceTracking; /** * Prices this tick against the pipeline and moves the share one step once * either reading has gathered the evidence a step takes. * * What takes the share down is a running bill, in frames, between what the * clock passed and what the play walk delivered over the same span. * Accumulating rather than thresholding each tick is what tells a shortfall * from noise: counting whole frames against a fractional demand leaves every * tick out by up to one either way and those cancel, while a machine that * cannot sustain the rate falls short every tick and adds up. A machine that * can sustain it has no way to run the bill up, since the queue only takes a * frame as the clock passes one and catch-up pulls repay any span the walk * came up short on, which bounds the bill by the depth being held. * * What puts the share back is the walk holding a frame the clock has not run * past, unbroken for the wall time the source takes to produce that many. * Nothing else would do, since a machine at equilibrium delivers exactly what * the clock asks for however much headroom it has, so a surplus never appears * in the bill to be read. * * Neither reading is the depth of the decode-ahead queue, which belongs to * the decode path and not to the machine: on the zero-copy path, which * buffers one frame, a single frame in hand is full depth and one tick from * empty alike. * * Nothing either reading is made of knows what the panel refreshes at, so one * machine lands on one cadence on any panel; a present the share declines * hands its time back to decode, so the loop this closes is a negative one; * and zeroing both on each step makes the next one gather its own evidence, * which is what a share sitting at the machine's limit needs to stop it * pulsing. */ private observePresentCadence; /** * Whether the frame that is due arrives too soon after the last painted one * to earn the screen. Wall time, read as the media span over the clock's * slope, so the same gap decides at every rate. The pump paints at most one * frame per display tick, so it can only decline one on a panel whose ticks * fall closer together than the interval it compares against. * * A cadence sitting at its ceiling never reaches the wall-time test, so a * machine keeping up declines nothing at any rate, and the ceiling equals the * demand at rate 1, which paints every frame of every source. A clock that * moved backwards under the pump reads as a non-positive span and paints, * which is what stops a step or a seek during playback from holding the * picture for the length of the jump it made. */ private skipsForPresentCadence; /** * Re-anchors the playback walk when the clock ran further past the previous * tick than a loop that was actually running could have let it, and reports * whether it did. * * A hidden tab parks rAF while the clock keeps wall time, so the tick that * resumes finds a backlog as deep as the whole absence. Walked, it costs one * decode per frame nobody was there to see, and the picture replays the * absence at decode rate on its way to the playhead: 30 seconds hidden * measured 4961ms of 8x fast-forward. Anchoring at the playhead lands the * frame that walk was travelling toward for one keyframe seek, flat in how * far the clock went. * * Dividing the span by the clock's slope is what makes the reading wall time, * so a high rate legitimately moving the clock several frames per tick is not * read as a loop nobody was driving. */ private reanchorParkedWalk; /** * Puts the clock back onto the frame a starved walk has just delivered. * * A seek onto unbuffered ground leaves the render loop ticking with nothing * to paint, so no tick gap ever opens and reanchorParkedWalk never sees it; * what stopped is the walk. The clock runs through the whole wait, so the * frame the viewer asked for arrives that far behind it, and a walk left to * catch up spends the wait replaying it at decode speed: the position they * asked to see, flashed past on the way to one they did not. */ private reanchorStarvedWalk; /** * Whether the newest decoded frame is already older than the clock, which * makes the queue a backlog and the next pull catch-up. Read-ahead depth * cannot bound catch-up as well: a path that holds one frame consumes one * source frame per tick, which pins the picture to tick rate over source fps * whatever rate was commanded. */ private trailsTheClock; /** Drops every queued play frame, closing any that are unpainted samples. */ private clearPlayQueue; bindCanvas(el: OffscreenCanvas | null): void; /** The active render backend, for diagnostics; null until it resolves. */ rendererName(): RendererName | null; private attachRenderer; dispose(): void; /** Drops the stashed frame, closing it if it is an unpainted sample. */ private clearStash; /** * Millisecond timestamp of whatever the visible canvas currently shows. * Engine.step uses this as the base for "next frame after current" so * step lands on the actual neighbor frame, not on a 1/fps arithmetic * guess from store.timeMs (which holds user intent during scrub). */ getLastPaintedMs(): number | null; getLastPaintedQuality(): FrameQuality; /** * Called by the engine on play(), and again by a seek that re-anchors a walk * already running. Attaches the cursor's forward iterator at the current * media time and kicks the bootstrap pull. Also clears the EOF latch so a * play-restart from past-end can fire onEnded again the next time the clock * crosses the duration. */ beginPlay(startS: number): void; /** Called by the engine on pause(), and by a seek re-anchoring a running * walk. Detaches the iterator and drops the read-ahead so paused ticks * never paint a stale play frame. */ endPlay(): void; holdOutput(): void; releaseOutput(): void; /** * Cache lookup helper used by the engine on scrub. Asks the cursor for a * cached frame near the target and, if it is far enough from what the canvas * already shows, paints it and returns true. Either way the engine still * calls cursor.seekTo to land the full-res frame; the cursor's emit listener * stashes it for the next tick. * * Nearby approximate hits respect cacheSkipNearMs. An exact hit for the * requested frame can advance immediately, without waiting for a decode. */ tryPaintFromCache(timestampMs: number): boolean; /** A new commit needs its own presentation even when its exact pixels were * already shown by the preceding scrub. Approximate neighbors cannot answer it. */ presentExactFromCache(timestampMs: number): boolean; private paintCached; private start; private runTick; private paint; /** Frame interval in seconds; the source rate when known, else a 30fps * fallback. Used to decide whether a playing frame painted late. */ private frameIntervalS; /** Realtime needles for the diagnostics snapshot. Plain reads; the worker * broadcaster calls this synchronously. */ getRealtimeStats(): RealtimeStats; private stop; }