import { type DecodeSourceHandle } from "./decode-source"; import type { DecodeResolutionStrategy } from "./decode-resolution"; import type { VideoSource } from "./types"; /** * Playback-independent analysis over a video source: metadata, keyframe * discovery, and frame extraction at arbitrary timestamps. It rides the same * opened decode source as the playback cursor but spins no worker, binds no * canvas, and runs no clock, so a consumer can pull thumbnails or build a * contact sheet without standing up a player. * * Extracted frames are copied into their own canvases before the next decode, * because the underlying sink recycles a small pool round-robin; the copy is * what makes a returned frame safe to hold. */ export interface AnalysisOptions { source: VideoSource; /** * Output frame resolution: it sizes the decode sink, so frames decode (and * paint, and copy) at this width with height following native aspect. Native * when omitted; a capped strategy makes a thumbnail pass cheaper end to end * rather than decoding native and scaling down afterward. */ decodeStrategy?: DecodeResolutionStrategy; poolSize?: number; } export interface AnalysisMetadata { readonly durationS: number; readonly width: number; readonly height: number; /** Resolution extracted frames are sized to, after the decode strategy. */ readonly frameWidth: number; readonly frameHeight: number; readonly nativeFps: number | null; } export interface ExtractedFrame { readonly timestampS: number; readonly canvas: OffscreenCanvas; readonly width: number; readonly height: number; } export declare class AnalysisSession { private readonly sink; private readonly keyframeIndex; private readonly track; private readonly disposeSource; private closed; constructor(source: DecodeSourceHandle); /** Opens a source for analysis. The returned session owns the source. */ static open(options: AnalysisOptions): Promise; get metadata(): AnalysisMetadata; /** * Keyframe timestamps (seconds) whose GOP overlaps the range, resolved * lazily through the container. Useful for a contact sheet that lands on * real I-frames, which decode without a GOP walk. */ keyframeTimestamps(startS?: number, endS?: number): Promise; /** * Decodes a frame for each requested timestamp and returns a stable copy of * each. Timestamps are sorted so the sink decodes each packet at most once; * a timestamp with no frame is skipped rather than yielding a gap. */ extractFrames(timestampsS: readonly number[]): Promise; /** * One frame per requested timestamp, in the order asked for, `null` where no * frame covers it, so a caller pairing frames with its own indices keeps the * gaps attributable. Timestamps that climb decode in a single pass over the * track: one seek and GOP walk for the whole set. * * A consumer that finishes with each frame before pulling the next holds one * frame of memory; {@link extractFrames} holds the whole set. */ framesAtTimestamps(timestampsS: readonly number[]): AsyncGenerator; close(): Promise; private copyFrame; }