import type { DecodeResolutionStrategy, DisplayBoxResolutionOptions } from "./decode-resolution"; import type { DiagnosticsSnapshot, EngineDiagnostics } from "./diagnostics"; import { type FrameId, type FrameLanding } from "./frame-timeline"; import type { SeekIntent } from "./scrub-cursor"; import type { EngineTrace } from "./trace-recorder"; import { type EngineChannel, type EngineReadySnapshot, type PaintSeq, type PlaybackState, PlaybackStatus, type PresentationMode, type UrlSourceReadConfig, type VideoSource } from "./types"; import { type EngineCommand, type EngineEvent, type PresentedFrame, type SourceResidencyConfig } from "./worker-protocol"; /** * Where a caller wants the playhead: a frame of the source, or a position in * milliseconds. A pointer only ever has the second kind; anything the engine * published carries the first, and handing that back needs no conversion. */ export type SeekTarget = number | FrameId; export interface WebVideoEngineOptions { source: VideoSource; /** * Creates the worker that hosts decode and presentation. Omit it to use the * embedded Blob worker. A host whose Content Security Policy disallows * `blob:` workers can return a Worker created from the separately exported * `supervision/web-video-engine/worker` URL instead. */ workerFactory?: () => Worker; /** * Who owns the pixels, fixed for the life of the engine. Default "canvas": * the engine holds the display canvas bindCanvas transfers to it and paints * every frame that earns the screen. Under "frames" it holds no canvas, * paints nothing, and hands those frames to onPresentedFrame instead, for a * host compositor to draw; bindCanvas then throws. */ presentation?: PresentationMode; /** * Cache strategy for instant scrub feedback. Default "tiered" keeps a * downscaled preview history plus a RAM-bounded full-resolution tier; * "none" disables caching (the cursor decodes every seek from scratch). */ cacheStrategy?: "tiered" | "none"; /** Preview-tier capacity (frames). Ignored when cacheStrategy is "none". */ previewCapacity?: number; /** * Preview-tier entry width in pixels. Default 320, limited to the fitted * display pixels for a displayBox strategy. An explicit width stays fixed * across display changes. Ignored when cacheStrategy is "none". */ previewWidth?: number; /** * Cache lookups whose nearest hit lies within this many milliseconds of * what the canvas already shows are rejected, forcing a full-res decode. * See constants.FRAME_CACHE.SKIP_NEAR_MS for the default and tuning notes. */ cacheSkipNearMs?: number; /** * Decides the resolution preview frames decode to. Defaults to native, so a * consumer that says nothing keeps full source resolution and pays for it in * paint work and frame-cache slots. Governs the live preview only; never the * timestamps a consumer extracts. * * Which strategy fits follows from `presentation`. Under "canvas" the engine * measures the box it was handed, so viewportResolution() reads it. Under * "frames" nothing binds a canvas and there is no box to read, so * viewportResolution() resolves to native there and displayBoxResolution() * is how that consumer states the size it composites into. */ decodeStrategy?: DecodeResolutionStrategy; /** * Pin the 2D renderer instead of WebGPU. WebGPU is the default; leaving this * unset prefers it and falls back to the 2D renderer only when WebGPU is * unavailable, so unset is not a guarantee of WebGPU. Both renderers paint * the same already-decoded frames on the same cadence (the render loop draws * a frame only when a new one is decoded). The 2D path is one canvas blit * per frame, not a re-decode and not a per-tick CPU repaint; the two differ * only in where a frame is composited, the GPU versus a 2D context. */ prefer2d?: boolean; /** * Hold the source's bytes in this process and serve the demuxer's reads from * them, so a position read once is read locally ever after. Off by default: * it spends memory the host has to be willing to spend, and prefetching * spends the viewer's link on bytes they may never watch. * * Only a `SourceKind.Url` source can use this. A Blob source is already local * and a Stream source is consumed once, so neither has anything to hold. */ sourceResidency?: SourceResidencyConfig; /** * Read tuning handed to mediabunny for a `SourceKind.Url` source: how many * range requests it may run at once, and how many bytes its own reader keeps. * Nothing here is read for a Blob or Stream source. */ urlSource?: UrlSourceReadConfig; } /** * The slice of a Worker this facade depends on. A real Worker is structurally * assignable, so production passes one through createEngineWorker; tests * pass a fake port that hosts an EngineCore in-process. */ export interface EngineWorkerPort { postMessage(message: EngineCommand, transfer: Transferable[]): void; addEventListener(type: "message", listener: (event: MessageEvent) => void): void; terminate(): void; } /** * Main-thread facade for the worker-hosted web video engine. Owns the worker * (spawned lazily on the first command), the mirror store React reads through * useSyncExternalStore, and the imperative handle. The decode + render loop runs * in the worker (EngineCore); this class never touches a cursor or clock directly. * * Three planes cross the worker boundary (see workerProtocol): commands go out, * broadcast state comes back as MirrorEvents fed into the store, and the display * canvas is transferred once on bindCanvas. Awaitable commands carry a requestId * the worker echoes back so each call settles its own promise. * * Time has two owners, gated by playback. While playing, the worker emits time; * while paused, the main thread owns the position: scrub/commit/step write it * optimistically so a late worker paint never yanks it back. Consumers render the * playhead by reading getTimeMs/getDurationMs at their own cadence. * * Engine outlives a single React render. Recreate the engine only when the * source identity changes. */ export declare class WebVideoEngine { private readonly options; private readonly store; private readonly diagnosticsStore; private readonly createWorker; private port; private disposed; private lastTrace; private traceArmed; private readonly pending; private presentationVisible; private listeningForPresentationVisibility; private readonly onPresentationVisibilityChange; private nextRequestId; private metadata; /** The loaded source's frame table, held here so a gesture is resolved to a * frame in the tick it arrives, with no worker round trip. */ private timeline; private transferredCanvas; private presentedFrameHandler; private navigationIntent; private stepIntent; /** Deliveries counted toward the one frame-ownership check, frozen past it, * and the frame that check reads. Weak, so watching costs the frame no * lifetime: a host that closes and drops it leaves nothing to find, which is * itself the answer. */ private presentedDeliveries; private watchedFrame; private cachedHandle; /** WebGPU support is a main-thread fact the worker cannot cheaply probe, so * the facade fills it onto each diagnostics snapshot for the warning rules. */ private readonly webgpuAvailable; constructor(options: WebVideoEngineOptions, createWorker?: () => EngineWorkerPort); /** * Loads the configured source. A stream source is transferred on this call, * so a repeat load has nothing left to hand over and rejects. */ load(): Promise; /** * Transfers the display canvas to the worker exactly once. The transfer is * permanent (it neuters the element's 2D/GPU context), so a repeat call with * the same element, or a null detach, is a no-op; the binding lives until * dispose terminates the worker. The viewport box is measured here, where * layout lives, and shipped so a viewport-aware decode strategy can size the * sink worker-side. */ bindCanvas: (el: HTMLCanvasElement | null) => void; play: () => Promise; /** Changes frames-mode display output and default scrub-preview sizing * without reopening the video. Resolves with true after replacement delivery, * or false when decode and preview sizes are unchanged. The host still * acknowledges its actual presentation. */ setDisplay: (display: DisplayBoxResolutionOptions) => Promise; pause: () => void; togglePlayback: () => void; /** * Forward playback speed, in media seconds per wall second. Takes effect at * once while playing and on the next play while paused; either way it * survives pause, seek, interactive-seek, and replay from the end, because * it is the clock's slope and none of those touch it. * * Throws synchronously on a rate outside the supported forward range, * including any reverse rate. The refusal has to happen here: the command is * fire-and-forget, so a worker-side throw would reach no caller. */ setPlaybackRate: (rate: number) => void; getPlaybackRate(): number; /** * Fire-and-forget seek: latest-wins, does not await idle. A pointer position * is not a frame time and never can be, so it is resolved to the frame * covering it before it reaches the store or the worker; the table lives on * this thread, so the playhead lands on a frame in the same tick the gesture * arrives, with no round trip. * * intent steers what the cache prepares next. Ignored when cacheStrategy is * "none": that backend has no access modes to switch and no prefetch to aim. */ scrub: (target: SeekTarget, intent?: SeekIntent) => void; /** * Pause-during-drag entry point. Consumers that handle pointer-driven * scrub gestures call this on pointerdown so playback freezes and the * decoder is not continuously chasing the cursor; the corresponding * endInteractiveSeek call on pointerup resumes play if the engine was * playing when the drag started. Matches the way native