supervision-js
    Preparing search index...

    Interface VideoEngineMediaSourceOptions

    interface VideoEngineMediaSourceOptions {
        display?: DisplayBoxResolutionOptions;
        frameDecodeStrategy?: DecodeResolutionStrategy;
        source: VideoSource;
        cacheStrategy?: "tiered" | "none";
        previewCapacity?: number;
        previewWidth?: number;
        cacheSkipNearMs?: number;
        decodeStrategy?: DecodeResolutionStrategy;
        prefer2d?: boolean;
        sourceResidency?: SourceResidencyConfig;
        urlSource?: UrlSourceReadConfig;
    }

    Hierarchy

    • Omit<VideoEngineOptions, "presentation">
      • VideoEngineMediaSourceOptions
    Index
    display? frameDecodeStrategy? source cacheStrategy? previewCapacity? previewWidth? cacheSkipNearMs? decodeStrategy? prefer2d? sourceResidency? urlSource?
    display?: DisplayBoxResolutionOptions

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

    frameDecodeStrategy?: DecodeResolutionStrategy

    Sizes the frames the pull path decodes. The inherited decodeStrategy sizes what the engine decodes for its own presentation.

    source: VideoSource
    cacheStrategy?: "tiered" | "none"

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

    previewCapacity?: number

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

    previewWidth?: number

    Preview-tier entry width in CSS pixels. Ignored when cacheStrategy is "none".

    cacheSkipNearMs?: 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.

    decodeStrategy?: DecodeResolutionStrategy

    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.

    prefer2d?: boolean

    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.

    sourceResidency?: SourceResidencyConfig

    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.

    urlSource?: UrlSourceReadConfig

    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.

    Settings
    Member Visibility

    On This Page
    Properties