/** * READ_AHEAD_CANVAS is the playback decode-ahead depth: how many decoded frames * the controller keeps queued ahead of the playhead so a decode that overruns a * frame interval does not starve the next tick (the cause of stutter even on * small, well-encoded clips, where playback otherwise pulls one frame per paint * with no cushion). Applies to canvas blits, which are independent and cheap to * hold; sample (zero-copy) frames pin a decoder slot each, so the controller * keeps those at a depth of one to spare the WebCodecs pool. * * REANCHOR_STALL_MS is the wall time past which a picture standing still stops * being a hitch to work through and becomes a stretch to re-anchor across. Two * gaps are measured against it, and they settle in opposite directions. * * A gap between playing render ticks is a loop nothing was driving, which a * hidden tab produces. Nobody was watching, so the clock is the truth and the * walk seeks forward onto the playhead. * * A gap between the walk's deliveries is a pipeline with nothing to show while * the loop ran, which a seek onto unbuffered ground produces. The viewer sat * through it waiting on a position they asked for, so the frame is the truth * and the clock is pulled back onto it. Left to catch up instead, the walk * replays the whole wait at decode speed on its way to the playhead: measured * against the deployed demo over six seeks, a mean 2.4x for a second, peaking * at 24x, with 44 source frames flashed past. * * Wall time is the reading in both, so a high rate legitimately moving the * media clock several frames per gap is not read as an absence. * * Half a second is where the tick-gap costs cross at 1x. A backlog costs one * decode per source frame in it, measured at 240 frames a second on the 30fps * demo clip (4.2ms each), against a keyframe-anchored seek at p95 47ms on the * same clip: half a second of 30fps backlog is 15 frames, so 63ms of decode * against that 47ms, and every higher rate puts more frames in the same gap. It * clears the worst legitimate gap of either kind by the same order: a foreground * loop leaves a long task or a GC pause to the frame-by-frame path, and forty * seconds of network-fed playback of the demo clip held its picture still for at * most 51ms. * * The present cadence is how often playback puts a frame on screen: the rate's * whole demand cut to the share of it the machine has been paying for, and never * under the source's own frame rate. At a full share the pump declines nothing, * which is where a machine with headroom stays at every rate. * A step moves the share by PRESENT_CADENCE_STEP, taking a quarter off it when * the pipeline has fallen behind the playhead and putting that same quarter back * when it has room to spare. The share bottoms out at one over * PLAYBACK_RATE.MAX, which is the deepest cut that means anything: below it even * the fastest rate asks for less than the source rate the cadence floors at. * * What takes the share down is a running bill, in frames, between what the clock * asked the pipeline for and what the play walk delivered. The bill accumulates * rather than being read per tick, which 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. Measured over 100ms windows on an M3 * Max at rates 2x to 8x, a pipeline with headroom stayed inside 1.5 frames of * its demand either way, so a bill of PRESENT_CADENCE_EVIDENCE_FRAMES frames is * one it cannot run up. * * 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 frames. * That is the only evidence a pipeline can offer that it has room to spare: a * machine at equilibrium delivers exactly what the clock asks for however much * headroom it has, so waiting for a surplus in the bill would leave every * machine at whatever its worst stretch measured. It is a live reading and the * bill is a cumulative one, which is why each takes one direction: ground lost * still reads lost once the walk is keeping up again, and catch-up pulls are * what carry the walk back onto the playhead. * * 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 pins a * decoder slot per queued frame and so buffers one, a single frame in hand is * full depth and one tick from empty alike. * * How far behind the machine is therefore sets the pace rather than the size of * the step: the bigger the shortfall the sooner the bill reaches that figure and * the sooner the next step lands. Zeroing on each step makes the next one gather * its own evidence, which is what stops a share sitting at the machine's limit * from pulsing. * * Frames the clock passed, frames the walk delivered and wall time on the * playhead: nothing either reading is made of knows what the panel refreshes at, * so one machine lands on one cadence on any panel. A faster panel offers more * slots and a machine with the headroom fills them; what it cannot do is hold * the pump above what the machine pays for, because the share comes down until * the pipeline is back on the playhead. * * PRESENT_CADENCE_SLACK is how far under the interval still counts as a full * one. Presents land on display ticks, so a panel refreshing at the ceiling * measures each gap as one interval give or take rAF jitter, and an exact * comparison would decline every second frame there. A quarter leaves 4.2ms of * jitter room at 60Hz. * * PRESENT_CADENCE_HZ is the demand above which frames the pump culled or * declined dominate the dropped-frame ledger, so the discarded-frames rule in * evaluateWarnings stands down rather than reading a count it cannot attribute. * * The keyframe walk is how a rate past the decoder still lands on the clock. * The full walk decodes every frame, because every frame between two sync * samples is built on the one before it, so rate r costs r x nativeFps decodes * a second whatever the cadence presents. Past what the decoder sustains, the * picture drifts behind the playhead for as long as playback runs. The keyframe * walk decodes sync samples alone, each on its own, so the bill becomes r over * the GOP length: 64x of the horse clip, a sync sample every 0.93s, is about 70 * decodes a second against the full walk's 1,920. What it gives up is every * picture between two sync samples, which is why it is the walk a rate falls * back to and never the one it starts on when the full walk can keep up. * * KEYFRAME_WALK_MIN_RATE is the rate below which the full walk is kept however * far behind it runs. Near 1x a viewer is watching motion, and one picture a GOP * is not motion; at 2x a source the decoder cannot follow is better shown on * time than smooth. * * KEYFRAME_WALK_DEMAND_HZ is the decode rate past which the full walk is not * tried at all: 32x of a 30fps source, 16x of a 60fps one. The fastest full * walk measured on this engine held 480 decodes a second (16x of a 1504x2016 * HEVC clip on an M-series Mac), so twice that is past any decoder the engine * runs on, and trying it first would only show the drift it is about to cure. * * Below that demand the full walk is tried and the keyframe walk taken only on * evidence: every frame the full walk delivers for KEYFRAME_WALK_EVIDENCE_MS of * wall time arrives more than KEYFRAME_WALK_TRAIL_MS of wall time behind the * clock. Wall time, the media gap over the rate, so the same lag decides at * every rate. A one-off gap is not that: a stretch of network starvation or a * re-anchor's pre-roll recovers through catch-up pulls once it ends, and one * longer than REANCHOR_STALL_MS has the clock pulled back onto the frame. */ export declare const PLAYBACK: { readonly READ_AHEAD_CANVAS: 3; readonly PRESENT_CADENCE_EVIDENCE_FRAMES: 3; readonly REANCHOR_STALL_MS: 500; readonly PRESENT_CADENCE_STEP: 0.75; readonly PRESENT_CADENCE_SLACK: 0.25; readonly PRESENT_CADENCE_HZ: 60; readonly KEYFRAME_WALK_MIN_RATE: 2; readonly KEYFRAME_WALK_DEMAND_HZ: 960; readonly KEYFRAME_WALK_TRAIL_MS: 250; readonly KEYFRAME_WALK_EVIDENCE_MS: 500; }; /** * Forward playback-rate range the engine accepts. Reverse playback needs a * backwards decode strategy the runtime does not have, so zero and negative * rates are refused rather than approximated. * * MAX is an API bound, not a promise that every source plays every frame * there. Sustaining rate r frame by frame means decoding r x nativeFps frames a * second, so past what a source's frame size and encode allow, playback moves * to the keyframe walk (see PLAYBACK) and keeps the rate by showing sync * samples only. What the walk cannot cure is a GOP so long that one decode per * sync sample is still too many, and the engine measures that rather than * guessing: DiagnosticsSnapshot carries the commanded rate beside the presented * one, and PLAYBACK_RATE_NOT_SUSTAINED fires when they diverge. * SUSTAINED_SHORTFALL is the share of the commanded rate the presented one has * to hold to count as sustained. * * Sixty-four is the keyframe walk's reach on ordinary footage: a sync sample a * second asks for 64 decodes a second, well inside what a hardware decoder * sustains, and a 70s clip passes in about a second. */ export declare const PLAYBACK_RATE: { readonly MIN: 0.25; readonly MAX: 64; readonly SUSTAINED_SHORTFALL: 0.8; }; /** * CanvasSink frame-pool size: how many decoded canvases the sink recycles * round-robin. The pool has no backpressure (a new decode overwrites the oldest * slot rather than blocking), and the playback queue hands the raw pool canvas * straight to the painter, so the pool must outnumber every canvas outstanding at * once: the full play read-ahead, the one in flight, and the one being painted. * Sized below that, a fresh decode stomps the pixels of a still-queued frame * before it paints (silent tearing). The cache is unaffected; it copies into its * own OffscreenCanvas. Derived from the read-ahead so the two cannot drift. */ export declare const SCRUB: { readonly DEFAULT_POOL_SIZE: number; }; /** * Bounds on building a track's frame timeline, the presentation-order table of * every frame's timestamp in the container's own integer grain. * * MAX_FRAMES caps the metadata walk that builds it. A 70-second 30fps source * walks 2113 packets in a measured 5.7ms; the cap is four hundred times that, * which no ordinary file reaches and a fragmented or endless source does. Past * it the load fails, so nothing silently runs without frame identity. * * FALLBACK_TICK_RATE is for a track backing that cannot state its grain. A * microsecond is the finest timestamp WebCodecs carries, so no real timestamp is * lost at that rate; what is lost is the guarantee that every timestamp is a * whole tick. */ export declare const FRAME_TIMELINE: { readonly MAX_FRAMES: 1000000; readonly FALLBACK_TICK_RATE: 1000000; }; /** * Tiered frame-cache tunables. Both tiers hold OffscreenCanvas blits, never * VideoFrames: a raw-frame cache pins decoder output, stalling the decoder and * growing VRAM without bound. The exact tier holds crisp full-resolution frames * around the scrub playhead; the preview tier is the coarse downscaled history * that answers a scrub anywhere else instantly while a crisp decode lands. * * Only the exact tier's window is worth holding at full resolution. A crisp * frame the playhead has moved off is one re-anchored decode away: on the * session path that is a probe plus a walk from the enclosing sync sample, * measured at 49ms mean / 80ms worst on a 2840x2840 15fps source, flat in how * far the jump travelled. Coverage past the window is worth having, not worth * having crisp, so it lives in the smaller preview tier. * * resolveCacheBudgets turns these into a per-source budget from * navigator.deviceMemory and the decode frame size. A crisp slot costs * decodeWidth x decodeHeight x 4 bytes, which spans two orders of magnitude * across sources: 0.9MB for a 640x360 decode, 32.3MB for a square 8MP native * decode. So a byte figure alone sets the slot count only for small frames. For * large ones any byte figure worth spending buys fewer slots than the access * pattern needs, and a slot floor sets the count with the bytes following from * it. The exact tier is therefore both: EXACT_BUDGET_BYTES_PER_GB times reported * RAM clamped to [MIN, MAX], raised to whatever MIN_EXACT_SLOTS costs at this * frame size. * * MIN_EXACT_SLOTS: the scrub prefetch window, a center frame plus * SCRUB_WINDOW_FRAMES each side. DecodeScheduler narrows its window to whatever * the exact tier holds, so this floor is what keeps an 8MP source at the full * window width, and slots past it would be speculative history the preview tier * already answers. * * PREVIEW_SLOTS_MAX: the preview slot count is its byte budget over the * downscaled frame size, capped here. No floor pairs with it: raising a starved * count means overspending the byte budget, when the frame width is what a wide * preview has to give up. A 320px square preview costs about a 79th of an * 8MP crisp slot, so that source keeps coarse history beyond its exact window. * * SKIP_NEAR_MS: cache lookups that resolve to a frame within this many * milliseconds of what the visible canvas already shows are rejected so the * consumer falls through to a full-res decode. Keeps a frame-step gesture from * snapping back to the already-painted neighbor. Fixed in ms, so it spans one * frame at 15fps and three at 30fps. * * DEFAULT_BUCKET_MS: timestamp-bucket size when the source frame rate is * unknown. Finer than the frame interval at any rate up to 30fps, so distinct * frames never collapse onto one slot. * * DEFAULT_DEVICE_MEMORY_GB: the RAM assumed for every browser that reports * none, which is all of them outside Chromium and any page off a secure * context. It is a guess, and the byte clamps above are what bound a wrong * one: at 8 the exact tier sits on its ceiling and the preview tier at two * thirds of its own. */ export declare const FRAME_CACHE: { readonly PREVIEW_WIDTH_PX: 320; readonly SKIP_NEAR_MS: 100; readonly DEFAULT_BUCKET_MS: 33; readonly MIN_EXACT_SLOTS: 13; readonly DEFAULT_DEVICE_MEMORY_GB: 8; readonly EXACT_BUDGET_BYTES_PER_GB: number; readonly EXACT_BUDGET_BYTES_MIN: number; readonly EXACT_BUDGET_BYTES_MAX: number; readonly PREVIEW_BUDGET_BYTES_PER_GB: number; readonly PREVIEW_BUDGET_BYTES_MIN: number; readonly PREVIEW_BUDGET_BYTES_MAX: number; readonly PREVIEW_SLOTS_MAX: 512; }; /** * Diagnostics instrument tunables. Inert unless a consumer opts in: the worker * broadcasts a snapshot at BROADCAST_HZ only while subscribed, the trace rings * allocate only while armed, and SCRUB_LATENCY_RING bounds the percentile sample. */ export declare const DIAGNOSTICS: { readonly BROADCAST_HZ: 10; readonly TRACE_EVENT_CAP: 2000; readonly TRACE_SNAPSHOT_CAP: 600; readonly SCRUB_LATENCY_RING: 64; readonly KEYFRAME_TIMESTAMPS_CAP: 512; }; /** * What an armed capture actually keeps. The snapshot ring is fed at the fixed * broadcast rate, so its capacity converts to a wall-clock window; the event * ring is fed by paints and gestures at no fixed rate, so its bound is a count * and nothing more. A readout that states one number for "the capture" is * describing neither ring. */ export declare const TRACE_RING_BOUNDS: { readonly snapshotWindowMs: number; readonly snapshotCap: 600; readonly eventCap: 2000; }; export declare const HANG_RECOVERY: { readonly DECODE_HANG_TIMEOUT_MS: 30000; readonly SEED_HANG_TIMEOUT_MS: 8000; readonly SEED_DECODE_ATTEMPTS: 3; /** * A movement whose decode settled without a matching crisp paint is ended * here, while the worker can still return its specific failure through the * command channel. The remaining margin belongs to message delivery and * main-thread scheduling; without it the facade replaces the useful verdict * with its generic worker-command timeout. */ readonly PRESENTATION_LATCH_TIMEOUT_MS: number; readonly WORKER_COMMAND_TIMEOUT_MS: number; };