import { BlobSource, ReadableStreamSource, UrlSource } from "mediabunny"; import type { CreateScrubCursorOptions } from "./create-scrub-cursor"; import { type SessionFrameSource } from "./decode-session"; import { type DecodeDimensions } from "./decode-resolution"; import type { SourceResidency } from "./source-residency"; import type { KeyframeProbe } from "./keyframe-index"; import { type ScrubTrackInfo, type VideoSampleLike } from "./scrub-cursor"; import { type DecodePath, type UrlSourceReadConfig, type UrlVideoSource, type VideoSource } from "./types"; /** * A decoded frame handle: the slice of mediabunny's WrappedCanvas the runtime * paints, caches, and extracts. Only the canvas and its presentation timestamp * matter. */ export interface WrappedCanvasLike { readonly canvas: OffscreenCanvas | HTMLCanvasElement; readonly timestamp: number; } /** * The slice of mediabunny's CanvasSink the runtime decodes through. getCanvas * does the random-access keyframe walk and GOP decode internally; canvases * streams forward for playback and stepping; canvasesAtTimestamps decodes a set * of sorted timestamps in one pass (the prefetch window and frame extraction). */ export interface CanvasFrameSource { getCanvas(timestampS: number): Promise; canvases(startS: number): AsyncGenerator; canvasesAtTimestamps(timestamps: Iterable): AsyncGenerator; } /** * The opened decode primitives for one source: resolved track facts plus the * two sinks the runtime rides. Built once by openDecodeSource, so a consumer * never imports mediabunny and stays fake-injectable under test. This seam is * shared by the playback cursors and the playback-independent AnalysisSession, * so it lives here next to its producer rather than inside any one consumer. */ export interface DecodeSourceHandle { readonly track: ScrubTrackInfo; readonly sink: CanvasFrameSource; readonly keyframeProbe: KeyframeProbe; dispose(): Promise; } /** * The slice of mediabunny's VideoSampleSink the runtime decodes through, mirror * for mirror with CanvasFrameSource but yielding live VideoSamples the zero-copy * WebGPU path imports directly. The sink yields raw samples; the cursor wraps * each in idempotentSample before emitting so the close obligation is safe to * discharge from every path. */ export interface SampleFrameSource { getSample(timestampS: number): Promise; samples(startS: number): AsyncGenerator; samplesAtTimestamps(timestamps: Iterable): AsyncGenerator; } /** * The opened decode primitives for the zero-copy sample path: the same resolved * track facts and keyframe probe as DecodeSourceHandle, with the VideoSampleSink * standing in for the CanvasSink. Built only where zeroCopyViable approves the * path, so the rest of the runtime never reaches it by accident. */ export interface SampleSourceHandle { readonly track: ScrubTrackInfo; readonly sampleSink: SampleFrameSource; readonly keyframeProbe: KeyframeProbe; dispose(): Promise; } /** * The opened decode primitives for the long-lived-decoder path: the same * resolved track facts and keyframe probe as the sink handles, with a * DecodeSession standing in for the sink. Built only where decodeSessionViable * approves the path. */ export interface SessionSourceHandle { readonly track: ScrubTrackInfo; readonly session: SessionFrameSource; readonly keyframeProbe: KeyframeProbe; dispose(): Promise; } /** * One decoded frame, tagged by which sink produced it. A canvas frame from the * CanvasSink path; a sample frame from the VideoSampleSink path, carrying a live * VideoSample the cursor owns the close of. The cursor turns each into the * matching ScrubFrame kind, so the canvas-vs-sample branch lives in one place * rather than forking every cursor method. */ export type DecodedFrame = { readonly kind: "canvas"; readonly canvas: OffscreenCanvas | HTMLCanvasElement; readonly timestamp: number; } | { readonly kind: "sample"; readonly sample: VideoSampleLike; readonly timestamp: number; }; /** * The decode seam both cursors ride, normalized over the two sink kinds: a * random-access read, a forward stream, and a sorted-timestamp batch, each * yielding a DecodedFrame. The provider also names the path it was built over, * which the scheduler reports so a human can see which machinery is decoding. */ export interface FrameProvider { resizeOutput?(dimensions: DecodeDimensions): Promise; readonly decodePath: DecodePath; readonly track: ScrubTrackInfo; readonly keyframeProbe: KeyframeProbe; getFrame(timestampS: number): Promise; frames(startS: number): AsyncGenerator; framesAt(timestamps: Iterable): AsyncGenerator; /** * Whether reaching `timestampS` would restart this provider from a keyframe * and decode everything in between. Only the long-lived decode session ever * answers true: the sink paths re-position per retrieval, so nothing they * are asked for is dearer than anything else. */ wouldReanchor(timestampS: number): boolean; /** * Decoded frames a consumer may hold ahead of the playhead. Only the * zero-copy sample sink is constrained here: each of its frames pins a slot * in a fixed pool, so a deep queue starves the decoder that fills it. The * other paths hand out frames they own, and a cushion is what stops a decode * that overruns one frame interval from starving the next paint. */ readonly playReadAhead: number; /** * Frames the decode machinery has produced since open, monotonic. On the * session path this counts every decoder output including discarded walk * pre-roll; the sink paths can only count what mediabunny yields, so their * figure is a floor, not the decoder's true output. */ framesDecoded(): number; dispose(): Promise; } /** * The forward-sample seam a batch range walk reads: the track's own timing * origin and one stream of its frames in presentation order. Both sample- * yielding paths present this shape, so the walk never branches on which decoder * it got, and every sample it hands over carries a close obligation. */ export interface WalkFrameSource { readonly track: ScrubTrackInfo; framesFrom(startS: number): AsyncGenerator; } /** A walk source and its disposal, held by whoever opened it. */ export interface WalkSourceHandle extends WalkFrameSource { dispose(): Promise; } /** Discriminates the opened-source handle shapes at the cursor boundary. */ export type AnySourceHandle = DecodeSourceHandle | SampleSourceHandle | SessionSourceHandle; /** * Wraps any opened-source handle in the unified FrameProvider. The two sample * paths wrap each yielded VideoSample in idempotentSample so the cursor can * discharge the close obligation from any path without double-free. */ export declare function openFrameProvider(handle: AnySourceHandle): FrameProvider; /** * Opens a source on the CanvasSink path, the one every decodable source * supports. Track facts are resolved here too, so the consumer receives a fully * described handle and never touches mediabunny or the resolution math. Playback * consumers call openScrubSource instead and take whatever path the source * supports; this is for consumers that want canvases specifically. */ export declare function openDecodeSource(options: CreateScrubCursorOptions): Promise; /** * Opens a source and routes it to the fastest decode path it supports: the * long-lived DecodeSession, then the zero-copy VideoSampleSink, then the * CanvasSink. * * The session's condition is the track's codec, which nothing can answer until * the container has been read, so the input opens first and the path is chosen * against what the opened track reports. The one input then serves whichever * path won. */ export declare function openScrubSource(options: CreateScrubCursorOptions): Promise; /** * Opens a source for a batch walk over its frames, on its own input and its own * decoder. A walk reads thousands of frames in a row and a playback cursor is * serving a screen, so the two never share: whatever a walk does to its read * head, no gesture is waiting behind it. * * The CanvasSink path is not offered here. It yields recycled canvases with no * duration and no close, and a walk's whole contract is real frames with the * timing they were encoded with, so a source that cannot present samples cannot * be walked. Frames arrive at the source's native resolution; nothing downscales * them on the way out. */ export declare function openWalkSource(source: VideoSource): Promise; /** * Inputs the zero-copy gate reasons over. Held as data, not probed live, so the * predicate is pure and unit-testable: the caller measures the realm once and * passes the facts in. */ export interface ZeroCopyContext { /** True when the consumer pinned the 2D renderer. */ readonly prefer2d: boolean; /** Whether decode runs at the source's native size (the strategy requests no * downscale). A downscale rules the path out: the sample arrives native, so * importing it zero-copy would paint at the wrong resolution. */ readonly decodesNative: boolean; /** Whether the worker realm has WebGPU with importExternalTexture, the API * the zero-copy import needs. */ readonly webgpuImportAvailable: boolean; } /** * The gate. True only when every condition holds: the 2D path is not pinned, the * strategy decodes at native (no downscale), and the realm offers WebGPU's * importExternalTexture. False keeps the byte-identical CanvasSink path; this is * the one place the additive path is allowed to switch on. */ export declare function zeroCopyViable(ctx: ZeroCopyContext): boolean; /** * Inputs the long-lived-decoder gate reasons over, held as data for the same * reason ZeroCopyContext is. * * Decode resolution is deliberately absent. The session owns its decoder and * always decodes at the source's native size, so a requested downscale is a * canvas and cache concern rather than a reason to refuse the path. */ export interface DecodeSessionContext { /** Whether this realm has WebCodecs. The session builds and drives its own * VideoDecoder rather than decoding through a mediabunny sink. */ readonly videoDecoderAvailable: boolean; /** The opened track's decoder config, which decides whether the session's * anchor trick applies to this bitstream. */ readonly decoderConfig: VideoDecoderConfig; } /** Platform facts used to contain decoder-output ownership to Android. * Client hints win when available so desktop UA emulation cannot accidentally * turn the expensive path on. */ export interface DecodeSessionPixelOwnershipContext { readonly clientPlatform?: string; readonly userAgent?: string; readonly offscreenCanvasAvailable: boolean; } export declare function shouldOwnDecodeSessionPixels(context: DecodeSessionPixelOwnershipContext): boolean; /** * The gate. The session reaches a non-IDR anchor by declaring it a recovery * point, which only holds for AVCC-framed H.264 carrying its parameter sets, so * every other source keeps the mediabunny sinks. */ export declare function decodeSessionViable(ctx: DecodeSessionContext): boolean; /** Whether this realm exposes the WebCodecs decoder the session constructs. */ export declare function detectVideoDecoder(): boolean; /** * Probes the worker realm for WebGPU with importExternalTexture. Checks for the * method on the prototype rather than acquiring a device, so it is synchronous * and cheap; the actual device acquisition still happens (and can still fail * back to 2D) in the renderer. */ export declare function detectWebgpuImport(): boolean; export declare function urlRequestInit(crossOrigin: UrlVideoSource["crossOrigin"]): { requestInit: RequestInit; } | undefined; export declare function toMediabunnySource(source: VideoSource, residency?: SourceResidency, urlSource?: UrlSourceReadConfig): UrlSource | BlobSource | ReadableStreamSource; /** * Whether a source can be opened a second time, which the hang-recovery path * needs to rebuild a wedged decoder. A URL re-fetches and a Blob re-reads, so * both re-open cleanly. A ReadableStream is consumed once and cannot be rewound, * so a rebuild on it would open onto an exhausted stream; the watchdog falls back * to a degraded-but-alive state instead of rebuilding for that kind. */ export declare function isReopenableSource(source: VideoSource): boolean;