OptionalworkerOptionalcacheCache 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).
OptionalpreviewPreview-tier capacity (frames). Ignored when cacheStrategy is "none".
OptionalpreviewPreview-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".
OptionalcacheCache 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.
OptionaldecodeDecides 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.
Optionalprefer2dPin 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.
OptionalsourceHold 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.
OptionalurlRead 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.
ReadonlysourceThe video to open. Two readers open it here, so it has to be one that can
be opened twice: the worker-backed engine decodes playback and scrubbing,
and the analysis session behind sampleSink decodes thumbnails and one-off
grabs from scratch. A URL re-fetches and a Blob re-reads. A ReadableStream
yields its bytes once, and the engine's load transfers it to the worker,
which detaches it here, so the pull path would be left with nothing to
read; pass one to WebVideoEngine directly instead.
Optional ReadonlydisplayThe box a compositor paints these frames into, in CSS pixels, with the viewer's device pixel ratio.
This source runs the engine canvas-less, so nothing on the engine side ever
measures a display box and its viewport strategy has nothing to read: left
unsaid, frames decode at the source's full resolution however small the box
is. Saying it here decodes at the size the frames are actually shown at,
which cuts per-frame paint work and buys the scrub cache more slots at the
cost of preview sharpness while scrubbing. An explicit decodeStrategy
wins over this.
Optional ReadonlyframeSizes the frames the pull path decodes. The inherited decodeStrategy
sizes what the engine decodes for its own presentation.
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 exportedsupervision/web-video-engine/workerURL instead.