import type { DecodeResolutionStrategy } from "./decode-resolution"; import type { ScrubCursorFactory } from "./scrub-cursor"; import type { SourceResidency } from "./source-residency"; import type { PresentationMode } from "./types"; import type { UrlSourceReadConfig, WebVideoEngineError, VideoSource } from "./types"; /** On-screen canvas measurements the decode strategy reasons over. */ export interface ScrubViewport { /** CSS-pixel width of the canvas box, or null when unmeasured. */ displayWidth: number | null; devicePixelRatio: number; } /** * Cache tuning passed through to the scheduler. Frame dimensions are filled from * the resolved track. The budgets are optional overrides: omitted, they are * resolved per source from device memory and frame size by resolveCacheBudgets. */ export interface ScrubCacheConfig { previewWidth: number; fitPreviewToOutput?: boolean; previewCapacity?: number; exactBudgetBytes?: number; } export interface CreateScrubCursorOptions { source: VideoSource; /** How decoded pixels leave the worker. Host-frame presentation keeps samples * available until the selected output can be copied for transfer. */ presentation?: PresentationMode; /** * Decides the resolution frames are held and painted at: the display canvas * backing store and every cache blit. Combined with the viewport and the * track's native dimensions; defaults to native resolution when omitted. * On the CanvasSink path it also sizes the sink's own output, but a path * that owns its decoder decodes native and scales into these dimensions. */ decodeStrategy?: DecodeResolutionStrategy; /** On-screen box the decodeStrategy may scale to. Native when omitted. */ viewport?: ScrubViewport; /** CanvasSink frame-pool size. */ poolSize?: number; /** Cache tuning. Omit or pass null for the uncached cursor. */ cache?: ScrubCacheConfig | null; /** Pin the 2D renderer. Mirrors the controller flag; rules out the zero-copy * sample path so a 2D consumer keeps the byte-identical CanvasSink path. */ prefer2d?: boolean; /** * Called once when the decoder is judged unable to decode this source at * all. A failure after open() cannot surface as a rejected promise, since by * then nobody is awaiting one; this is how it reaches the transport. */ onDecodeFailure?: (error: WebVideoEngineError) => void; /** Serves the demuxer's byte reads from what this process already holds. */ sourceResidency?: SourceResidency; /** Read tuning for a URL source, passed through to mediabunny. */ urlSource?: UrlSourceReadConfig; signal?: AbortSignal; } /** * Opens the decode source and chooses the cursor backend: the caching * DecodeScheduler when a cache config is given, otherwise the uncached * CanvasSinkScrubCursor. The returned cursor is already seeded with its first * frame, so callers receive a ready cursor with track metadata resolved. * * This is the single place the backend is chosen, so the gate is one branch and * both backends share the same opened source. */ export declare const createScrubCursor: ScrubCursorFactory;