Interface WebVideoEngineOptions

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.

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.

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).

Preview-tier capacity (frames). Ignored when cacheStrategy is "none".

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".

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.

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.

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.

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.

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.