@pixerate/editor 0.86.0 → 0.88.0

package/dist/video-editor/index.d.cts

@@ -191,9 +191,18 @@ declare const videoTransitionAudioCurve: (t: VideoTransition) => VideoFadeCurve;
  */
 type VideoBlendMode = 'normal' | 'multiply' | 'screen' | 'overlay' | 'darken' | 'lighten' | 'color-dodge' | 'color-burn' | 'hard-light' | 'soft-light' | 'difference' | 'exclusion' | 'add';
 declare const VIDEO_BLEND_MODES: readonly ["normal", "multiply", "screen", "overlay", "darken", "lighten", "color-dodge", "color-burn", "hard-light", "soft-light", "difference", "exclusion", "add"];
+/** A 3D LUT a grade applies after its other steps (see `VideoGrade.lut`). */
+interface VideoGradeLut {
+    /** A `.cube` file: whatever the host can load (URL, path) and the exporter can open. */
+    src: string;
+    /** How much of the LUT's change to apply, 0–1 (default 1). */
+    strength?: number;
+    /** A label for the look (default the file's TITLE or name). */
+    name?: string;
+}
 /**
  * Colour correction for a clip's picture (see `VIDEO_GRADE_CONTROLS` for ranges). Applied in a fixed
- * order: exposure, contrast, saturation, hue, then white balance (temperature and tint).
+ * order: exposure, contrast, saturation, hue, white balance (temperature and tint), then the LUT.
  */
 interface VideoGrade {
     /** Stops: +1 doubles every channel (default 0). */
@@ -208,6 +217,8 @@ interface VideoGrade {
     temperature?: number;
     /** -1 (green) to 1 (magenta); default 0. */
     tint?: number;
+    /** A 3D LUT (a `.cube` file) applied last, mixed in at its `strength`. */
+    lut?: VideoGradeLut;
 }
 /**
  * How a clip enters or leaves: `fade`; `rise` (up into place) or `drop` (down into place);
@@ -354,6 +365,7 @@ declare function parseVideoTransform(v: unknown, path: string): VideoTransform |
 declare function parseVideoTimeRemap(v: unknown, speed: unknown, path: string): VideoKeyframes | undefined;
 declare function parseVideoClipAnimation(v: unknown, path: string): VideoClipAnimation | undefined;
 declare function parseVideoGrade(v: unknown, path: string): VideoGrade | undefined;
+declare function parseVideoGradeLut(v: unknown, path: string): VideoGradeLut | undefined;
 declare function parseVideoTransition(v: unknown, path: string): VideoTransition | undefined;
 declare function parseVideoTranscriptWords(v: unknown, path: string): VideoTranscriptWord[] | undefined;
 declare function parseVideoAsset(v: unknown, path?: string): VideoAsset;
@@ -931,6 +943,83 @@ declare class VideoAudioPeaksCache {
     private emit;
 }
 
+/**
+ * 3D LUTs for grades: `.cube` files read into a lattice and applied with tetrahedral
+ * interpolation, as ffmpeg's `lut3d=interp=tetrahedral` and grading apps apply them, so the
+ * preview and the export agree. A grade's LUT (`VideoGrade.lut`) runs after its other steps and is
+ * mixed with the picture before it by `strength`.
+ */
+/** A 3D LUT: `size`³ output colours, red changing fastest, then green, then blue (the `.cube` order). */
+interface VideoLut {
+    title?: string;
+    size: number;
+    /** Input values mapped to the first and last lattice points, per channel (default 0 and 1). */
+    domainMin: [number, number, number];
+    domainMax: [number, number, number];
+    /** `size³ × 3` output values. */
+    data: Float32Array;
+}
+/** Largest `LUT_3D_SIZE` read (129³ rows is about 2 million). */
+declare const VIDEO_LUT_MAX_SIZE = 129;
+/** Reads a `.cube` file's 3D table. Errors give the line and what is wrong. */
+declare function parseVideoCubeLut(text: string): VideoLut;
+/** A LUT of `size` points a side built from a colour function (each channel 0–1 in and out). */
+declare function videoLutFromFunction(size: number, fn: (rgb: [number, number, number]) => readonly [number, number, number], title?: string): VideoLut;
+/** A LUT as `.cube` text. */
+declare function videoLutToCube(lut: VideoLut): string;
+/**
+ * A colour (each channel 0–1) through a LUT with tetrahedral interpolation: the lattice cube
+ * around the colour is split into six tetrahedra along its grey diagonal, and the colour is mixed
+ * from the four corners of the one it falls in. Greys stay on the diagonal, unlike trilinear.
+ */
+declare function applyVideoLut(lut: VideoLut, rgb: readonly [number, number, number], out?: [number, number, number]): [number, number, number];
+/** Runs RGBA pixels (0–255, as `ImageData` has them) through a LUT in place, mixed with the originals by `strength` (0–1). Transparent pixels are left alone. */
+declare function applyVideoLutToPixels(lut: VideoLut, data: {
+    length: number;
+    [i: number]: number;
+}, strength?: number): void;
+/**
+ * An SVG approximation of a LUT for SVG frames, which have no 3D tables: per-channel curves taken
+ * along the LUT's grey axis (`feComponentTransfer` tables), then the colour matrix that best fits
+ * the rest (least squares over the lattice). Exact for LUTs that are curves or a matrix; close for
+ * most looks. The preview and the export apply the LUT itself.
+ */
+interface VideoLutSvgApproximation {
+    /** Per-channel curve tables (`tableValues`), each 0–1. */
+    tables: [number[], number[], number[]];
+    /** A 3 × 4 matrix (rows r, g, b; columns r, g, b, offset) applied after the curves. */
+    matrix: number[][];
+}
+declare function videoLutSvgApproximation(lut: VideoLut): VideoLutSvgApproximation;
+/** Where LUT files come from: their text for a `src` (default: `fetch`). */
+type VideoLutLoader = (src: string) => Promise<string | VideoLut>;
+/**
+ * Loaded LUTs by `src`, read once and shared by the preview, SVG frames and agent tools
+ * (`VideoEditorController.luts`). Listeners hear when one loads or fails.
+ */
+declare class VideoLutCache {
+    private readonly loader;
+    private readonly ready;
+    private readonly pending;
+    private readonly failed;
+    private readonly listeners;
+    constructor(loader?: VideoLutLoader);
+    /** The LUT if loaded, without starting to load it. */
+    peek(src: string): VideoLut | undefined;
+    /** The LUT if loaded; otherwise `undefined`, and loading starts (once) unless it failed. */
+    get(src: string): VideoLut | undefined;
+    /** Why loading a LUT failed, if it did. */
+    error(src: string): string | undefined;
+    /** The LUT, loading and reading it if needed. Rejects with a readable error. */
+    load(src: string): Promise<VideoLut>;
+    /** Uses a LUT the host already has (`.cube` text or a parsed LUT), under `src`. */
+    set(src: string, lut: VideoLut | string): VideoLut;
+    /** Forgets a failure so the next `get` tries again. */
+    retry(src: string): void;
+    subscribe(fn: () => void): () => void;
+    private emit;
+}
+
 /**
  * Colour correction as a fixed series of colour-matrix steps on gamma-encoded sRGB, each clamped
  * to 0–1, in the same order everywhere: exposure, contrast, saturation, hue, then white balance.
@@ -939,8 +1028,10 @@ declare class VideoAudioPeaksCache {
  * formulas, so the preview, SVG frames and the export agree.
  */
 /** One slider of a grade: its range, default and step, for schemas, inspectors and clamping. */
+/** The numeric settings of a grade (everything but its LUT). */
+type VideoGradeSetting = Exclude<keyof VideoGrade, 'lut'>;
 interface VideoGradeControl {
-    key: keyof VideoGrade;
+    key: VideoGradeSetting;
     label: string;
     min: number;
     max: number;
@@ -984,10 +1075,14 @@ declare const VIDEO_GRADE_PRESETS: {
 };
 type VideoGradePreset = keyof typeof VIDEO_GRADE_PRESETS;
 declare const VIDEO_GRADE_PRESET_NAMES: VideoGradePreset[];
+/** A LUT setting with its strength clamped to 0–1 (and 1 left out); `undefined` without a `src` or at strength 0. */
+declare function normalizeVideoGradeLut(lut: VideoGradeLut | undefined): VideoGradeLut | undefined;
 /** A grade with every value clamped to its range and zero values left out; `undefined` when nothing is left. */
 declare function normalizeVideoGrade(grade: VideoGrade | undefined): VideoGrade | undefined;
 /** A preset at `amount` (0–1, default 1) of its strength. */
 declare function videoGradePreset(name: VideoGradePreset, amount?: number): VideoGrade | undefined;
+/** A preset look on a grade, keeping the grade's LUT (a look replaces only the settings). */
+declare function videoGradeLook(current: VideoGrade | undefined, name: VideoGradePreset, amount?: number): VideoGrade | undefined;
 /** One step of a grade. */
 type VideoGradeStep = {
     kind: 'brightness';
@@ -1014,12 +1109,23 @@ declare function videoGradeSteps(grade: VideoGrade | undefined): VideoGradeStep[
  * Filter Effects spec gives for `saturate` and `hue-rotate`.
  */
 declare function videoGradeStepMatrix(step: VideoGradeStep): number[][];
-/** An RGB colour (0–255 each) through a grade, as the preview and export draw it. */
-declare function applyVideoGrade(grade: VideoGrade | undefined, rgb: readonly [number, number, number]): [number, number, number];
+/**
+ * An RGB colour (0–255 each) through a grade, as the preview and export draw it. A grade's LUT is
+ * applied when its table is passed as `lut` (else it is left out).
+ */
+declare function applyVideoGrade(grade: VideoGrade | undefined, rgb: readonly [number, number, number], lut?: VideoLut | null): [number, number, number];
 /** The `values` of an SVG `feColorMatrix type="matrix"` for a step. */
 declare function videoGradeStepSvgValues(step: VideoGradeStep): string;
-/** An SVG `<filter>` applying a grade, steps in order (each clamps, as CSS filters do). */
-declare function videoGradeSvgFilter(id: string, grade: VideoGrade | undefined): string;
+/**
+ * SVG filter primitives approximating a LUT (see `videoLutSvgApproximation`) on the result of the
+ * primitives before them, mixed with it by `strength`.
+ */
+declare function videoLutSvgPrimitives(lut: VideoLut, strength?: number): string;
+/**
+ * An SVG `<filter>` applying a grade, steps in order (each clamps, as CSS filters do). With the
+ * grade's LUT table (`lut`), an approximation of it follows (SVG has no 3D tables).
+ */
+declare function videoGradeSvgFilter(id: string, grade: VideoGrade | undefined, lut?: VideoLut | null): string;
 /** Id of the SVG filter for a white-balance step: the same gains always get the same id. */
 declare const videoGradeGainsFilterId: (step: Extract<VideoGradeStep, {
     kind: "gains";
@@ -1038,6 +1144,223 @@ declare function videoGradeSvgDefs(grade: VideoGrade | undefined): {
 /** A grade as ffmpeg filters on RGB, in order: `lutrgb` for exposure and contrast, `colorchannelmixer` for the rest. */
 declare function videoGradeFfmpegFilters(grade: VideoGrade | undefined): string[];
 
+/**
+ * Colour scopes: a histogram, a luma waveform and a vectorscope, worked out from a frame's pixels,
+ * plus exposure and clipping figures. Pure functions on RGBA pixels as `ImageData` holds them, so
+ * the same numbers come from a preview canvas, a decoded export frame or a test.
+ *
+ * Luma and chroma use the Rec. 709 weights on the gamma-encoded values (Y′, Cb, Cr), as broadcast
+ * scopes do: luma 0 is black and 1 white; Cb and Cr run from −0.5 to 0.5.
+ */
+/** RGBA pixels, 4 values (0–255) a pixel, rows top to bottom: an `ImageData` fits. */
+interface VideoPixels {
+    width: number;
+    height: number;
+    data: ArrayLike<number>;
+}
+type VideoScopeKind = 'histogram' | 'waveform' | 'vectorscope';
+declare const VIDEO_SCOPE_KINDS: readonly ["histogram", "waveform", "vectorscope"];
+/** Rec. 709 luma of gamma-encoded RGB (each 0–1). */
+declare const videoLuma: (r: number, g: number, b: number) => number;
+/** Rec. 709 chroma (Cb, Cr), each −0.5 to 0.5, of gamma-encoded RGB (each 0–1). */
+declare function videoChroma(r: number, g: number, b: number): [number, number];
+interface VideoScopeOptions {
+    /**
+     * Read at most about this many pixels, evenly spaced (default 262 144, a 512 × 512 picture), so
+     * a large frame costs no more than a small one. Counts are of the pixels read.
+     */
+    maxPixels?: number;
+}
+/** How many pixels fall in each of `bins` equal steps of red, green, blue and luma (bin 0 is darkest). */
+interface VideoHistogram {
+    bins: number;
+    r: number[];
+    g: number[];
+    b: number[];
+    luma: number[];
+    /** Pixels counted. */
+    total: number;
+}
+declare function videoHistogram(pixels: VideoPixels, options?: VideoScopeOptions & {
+    bins?: number;
+}): VideoHistogram;
+/**
+ * A luma waveform: the picture split into `columns` vertical strips, left to right, each counting
+ * its pixels at each of `levels` luma steps. `data[column * levels + level]`; level 0 is black.
+ */
+interface VideoWaveform {
+    columns: number;
+    levels: number;
+    data: Uint32Array;
+    /** The largest count, for scaling a drawing. */
+    peak: number;
+}
+declare function videoLumaWaveform(pixels: VideoPixels, options?: VideoScopeOptions & {
+    columns?: number;
+    levels?: number;
+}): VideoWaveform;
+/**
+ * A vectorscope: pixels counted on a `size` × `size` grid by chroma, Cb across (left −0.5, right
+ * +0.5) and Cr up (top +0.5). The centre is grey; the further out, the more saturated; the angle
+ * is the hue. `data[row * size + column]`.
+ */
+interface VideoVectorscope {
+    size: number;
+    data: Uint32Array;
+    peak: number;
+}
+/** Where chroma (Cb, Cr) falls on a vectorscope of `size` pixels, as `[column, row]`. */
+declare const videoVectorscopePoint: (cb: number, cr: number, size: number) => [number, number];
+declare function videoVectorscope(pixels: VideoPixels, options?: VideoScopeOptions & {
+    size?: number;
+}): VideoVectorscope;
+/** Exposure and colour figures for a frame (see `videoExposureStats`). Luma and levels run 0–1. */
+interface VideoExposureStats {
+    /** Pixels read. */
+    pixels: number;
+    luma: {
+        mean: number;
+        median: number;
+        min: number;
+        max: number;
+        p1: number;
+        p99: number;
+    };
+    /** Share (0–1) of pixels crushed to black (luma at or below `shadowLevel`) or blown to white (at or above `highlightLevel`). */
+    clipped: {
+        shadows: number;
+        highlights: number;
+        r: number;
+        g: number;
+        b: number;
+    };
+    /** Mean and highest chroma, 0 (grey) to 1 (a full primary). */
+    saturation: {
+        mean: number;
+        max: number;
+    };
+    /** The mean colour as `#rrggbb`: far from grey means a colour cast. */
+    average: string;
+}
+interface VideoExposureOptions extends VideoScopeOptions {
+    /** Luma (0–1) at or below which a pixel counts as crushed (default 0.02). */
+    shadowLevel?: number;
+    /** Luma or channel (0–1) at or above which a pixel counts as blown (default 0.98). */
+    highlightLevel?: number;
+}
+declare function videoExposureStats(pixels: VideoPixels, options?: VideoExposureOptions): VideoExposureStats;
+/** What a scope reading says in words: exposure, clipping and colour cast worth fixing. */
+declare function videoExposureNotes(stats: VideoExposureStats): string[];
+/** A compact reading of a frame for agents: exposure figures, notes, and coarse histogram, waveform and vectorscope summaries. */
+interface VideoScopeSummary {
+    stats: VideoExposureStats;
+    notes: string[];
+    /** Share of pixels (0–1) in each of `bins` equal luma and channel steps, darkest first. */
+    histogram: {
+        bins: number;
+        luma: number[];
+        r: number[];
+        g: number[];
+        b: number[];
+    };
+    /** The picture in vertical strips, left to right: each strip's luma spread (0–1). */
+    waveform: {
+        start: number;
+        end: number;
+        min: number;
+        median: number;
+        max: number;
+    }[];
+    /** The chroma of the most saturated tenth of the picture: its main hue (degrees on the vectorscope, red ≈ 103°) and strength (0–1). */
+    vectorscope: {
+        hue: number | null;
+        strength: number;
+        spread: number;
+    };
+}
+/** Vectorscope angle (degrees, anticlockwise from +Cb) of chroma. */
+declare const videoVectorscopeAngle: (cb: number, cr: number) => number;
+declare function summarizeVideoScopes(pixels: VideoPixels, options?: VideoExposureOptions & {
+    bins?: number;
+    columns?: number;
+}): VideoScopeSummary;
+/** Where the six 75% colour-bar targets sit on a vectorscope: name, Cb and Cr. */
+declare const VIDEO_VECTORSCOPE_TARGETS: readonly {
+    name: string;
+    rgb: [number, number, number];
+    cb: number;
+    cr: number;
+}[];
+/** RGBA pixels of a drawn scope, ready for `new ImageData(data, width, height)`. */
+interface VideoScopeImage {
+    width: number;
+    height: number;
+    data: Uint8ClampedArray<ArrayBuffer>;
+}
+/** A histogram drawn `width` × `height`: red, green and blue added together, with luma as a white outline. */
+declare function videoHistogramImage(h: VideoHistogram, width?: number, height?: number): VideoScopeImage;
+/** A luma waveform drawn `width` × `height`: white at the top, black at the bottom, lines at each quarter. */
+declare function videoWaveformImage(w: VideoWaveform, width?: number, height?: number): VideoScopeImage;
+/** A vectorscope drawn `size` × `size`, with its outer circle, the skin-tone line and the colour-bar targets. */
+declare function videoVectorscopeImage(v: VideoVectorscope, size?: number): VideoScopeImage;
+/** One scope of a frame drawn `width` × `height` (a vectorscope is square: the smaller side). */
+declare function videoScopeImage(kind: VideoScopeKind, pixels: VideoPixels, width?: number, height?: number, options?: VideoScopeOptions): VideoScopeImage;
+/** A frame the preview drew: when, whether every picture in it had loaded, and its pixels. */
+interface VideoPreviewSnapshot {
+    time: number;
+    /** False while a picture is still loading or seeking (the frame shows a placeholder or a stale picture). */
+    complete: boolean;
+    pixels: VideoPixels;
+}
+/**
+ * Where a preview's pixels can be read, for scopes and agents: a `VideoPreviewEngine` attaches its
+ * canvas and says each time it draws. `VideoEditorController.previewPixels` is one, so a preview,
+ * a scopes panel and the agent tools of one editor find each other without wiring.
+ */
+declare class VideoPreviewPixels {
+    private reader;
+    private drawnAt;
+    private readonly listeners;
+    /** Gives the canvas to read (the latest preview wins). Returns a function that takes it away again. */
+    attach(reader: () => VideoPreviewSnapshot | null): () => void;
+    /** Whether a preview is attached. */
+    get attached(): boolean;
+    /** The preview drew the frame at `time`; `complete` is false while a picture was missing or stale. */
+    drawn(time: number, complete: boolean): void;
+    /** The last frame drawn, with its pixels; `null` without a preview. Throws when the canvas cannot be read. */
+    read(): VideoPreviewSnapshot | null;
+    /** Called after each frame the preview draws. */
+    subscribe(listener: () => void): () => void;
+    /**
+     * The frame at `time` once it is complete: now, if the last frame drawn was it, else the next
+     * complete drawing of it. Fails after `timeout` ms (default 5000).
+     */
+    next(time: number, timeout?: number): Promise<VideoPreviewSnapshot>;
+    private emit;
+}
+/** What a scopes panel shows for the preview's latest frame (see `readVideoScopesPanel`). */
+type VideoScopesPanelReading = {
+    ok: true;
+    time: number;
+    complete: boolean;
+    images: Partial<Record<VideoScopeKind, VideoScopeImage>>;
+    stats: VideoExposureStats;
+    notes: string[];
+} | {
+    ok: false;
+    message: string;
+};
+/**
+ * The preview's latest frame as a scopes panel draws it: an image per scope `kinds`, each
+ * `width` × `height` (vectorscopes square), and the exposure figures. Reads at most `maxPixels`
+ * (default 65 536) so it keeps up with playback. Says why when there is nothing to show.
+ */
+declare function readVideoScopesPanel(feed: VideoPreviewPixels, kinds?: readonly VideoScopeKind[], options?: {
+    width?: number;
+    height?: number;
+    maxPixels?: number;
+}): VideoScopesPanelReading;
+
 /** Default length of an entrance or exit animation (ms). */
 declare const VIDEO_CLIP_ANIMATION_DURATION = 500;
 declare const PROPS: readonly ["opacity", "x", "y", "scale"];
@@ -1207,6 +1530,8 @@ interface VideoSvgOptions {
     imageFor?: (layer: VideoLayer, frame: VideoFrame) => string | null;
     /** Frame rate for the timecode on placeholders (default 30). */
     fps?: number;
+    /** The loaded table of a grade's LUT `src`; drawn as an approximation (curves and a matrix). Without it LUTs are left out. */
+    lutFor?: (src: string) => VideoLut | null | undefined;
 }
 /** A frame as standalone SVG: images and posters as `<image>`, video without one as a labelled box. */
 declare function videoFrameToSvg(frame: VideoFrame, options?: VideoSvgOptions, assets?: VideoProject['assets']): string;
@@ -1230,16 +1555,29 @@ type VideoCanvasContext = Pick<CanvasRenderingContext2D, 'save' | 'restore' | 'f
     lineWidth: number;
     strokeRect(x: number, y: number, w: number, h: number): void;
 };
+/** An offscreen canvas `drawVideoFrame` draws a LUT-graded layer on before running its pixels through the LUT. */
+interface VideoScratchCanvas {
+    canvas: CanvasImageSource;
+    ctx: VideoCanvasContext & Pick<CanvasRenderingContext2D, 'getImageData' | 'putImageData' | 'clearRect'>;
+}
+interface VideoDrawOptions {
+    /** Puts an SVG filter (white balance) in the page, so the canvas's `filter: url(#id)` finds it. */
+    defineSvgFilter?: (id: string, markup: string) => void;
+    /** The loaded table of a grade's LUT `src`, or nothing while it loads (the layer is drawn without it). */
+    lutFor?: (src: string) => VideoLut | null | undefined;
+    /** A cleared-on-use offscreen canvas of the given canvas-pixel size, for LUT layers (none: LUTs are left out). */
+    scratch?: (width: number, height: number) => VideoScratchCanvas | null;
+}
 /**
  * Draws a frame on a 2D canvas scaled by `scale` (canvas pixels per frame pixel). `sourceFor`
  * returns what to draw for a media layer (a `<video>` seeked to `layer.sourceTime`, an `<img>`,
  * an `ImageBitmap`…) or `null` for a placeholder box. Grades become the context's `filter`; white
  * balance there refers to an SVG filter, which `options.defineSvgFilter` is given to put in the page
- * (without it, white balance is left out of the canvas).
+ * (without it, white balance is left out of the canvas). A grade's LUT needs `options.lutFor` and
+ * `options.scratch`: the layer is drawn on the scratch canvas, its pixels run through the LUT, and
+ * the result is laid on the frame with the layer's opacity and blend.
  */
-declare function drawVideoFrame(ctx: VideoCanvasContext, frame: VideoFrame, sourceFor: (layer: VideoLayer) => CanvasImageSource | null, scale?: number, options?: {
-    defineSvgFilter?: (id: string, markup: string) => void;
-}): void;
+declare function drawVideoFrame(ctx: VideoCanvasContext, frame: VideoFrame, sourceFor: (layer: VideoLayer) => CanvasImageSource | null, scale?: number, options?: VideoDrawOptions): void;
 
 interface VideoEdlOptions {
     /** Track to export (default: the bottom video track, V1 in most NLEs). */
@@ -1263,6 +1601,8 @@ interface VideoFfmpegOptions {
     output?: string;
     /** The path or URL ffmpeg should open for an asset (default its `src`). */
     resolve?: (asset: VideoAsset) => string;
+    /** The path ffmpeg's `lut3d` should read for a grade's LUT `src` (default the `src`; it must be a local file). */
+    resolveLut?: (src: string) => string;
     /** Default `libx264`. */
     videoCodec?: string;
     /** Default `aac`. */
@@ -1354,6 +1694,10 @@ interface VideoPreviewSource {
         playing: boolean;
     };
     subscribe(listener: () => void): () => void;
+    /** Where to publish the drawn pixels (a controller has one), for scopes and agents. */
+    previewPixels?: VideoPreviewPixels;
+    /** Where grades' LUTs load from (a controller has one). */
+    luts?: VideoLutCache;
 }
 /** The parts of a media element the preview drives (so tests can pass fakes). */
 interface VideoPreviewMedia {
@@ -1363,6 +1707,8 @@ interface VideoPreviewMedia {
     volume: number;
     muted: boolean;
     paused: boolean;
+    /** True while a seek is under way (the element still shows the old frame). */
+    seeking?: boolean;
     readyState: number;
     preload: string;
     play(): Promise<void> | void;
@@ -1394,6 +1740,18 @@ interface VideoPreviewOptions {
      * it. Default: a hidden `<svg>` added to `document.body`. `null` leaves white balance out.
      */
     defineSvgFilter?: ((id: string, markup: string) => void) | null;
+    /**
+     * Where to publish the canvas's pixels after each frame, for scopes and the `get_video_scopes`
+     * tool (default: the source's `previewPixels`). `null` publishes nothing.
+     */
+    pixels?: VideoPreviewPixels | null;
+    /** Where grades' LUTs load from (default: the source's `luts`). Without one, LUTs are left out. */
+    luts?: VideoLutCache | null;
+    /**
+     * Makes the offscreen canvas LUT-graded layers are drawn on (default: a `<canvas>` with
+     * `willReadFrequently`). LUTs run on the CPU, so a lower `resolution` keeps playback smooth.
+     */
+    createScratch?: (width: number, height: number) => VideoScratchCanvas | null;
 }
 /**
  * Plays a project in the browser: keeps one `<video>` or `<audio>` element per playing clip in step
@@ -1413,12 +1771,21 @@ declare class VideoPreviewEngine {
     private destroyed;
     private filterHost;
     private readonly filters;
+    private readonly detachPixels;
+    private readonly pixelsTarget;
+    private drawn;
+    private complete;
+    private readonly lutCache;
+    private readonly unsubscribeLuts;
+    private scratchCanvas;
     constructor(source: VideoPreviewSource, canvas: {
         width: number;
         height: number;
         clientWidth?: number;
         getContext?: (id: '2d') => unknown;
     }, options?: VideoPreviewOptions);
+    /** The canvas's pixels and the frame they show, or `null` when its context cannot be read. */
+    readPixels(): VideoPreviewSnapshot | null;
     private createMedia;
     private image;
     private entry;
@@ -1428,6 +1795,9 @@ declare class VideoPreviewEngine {
     private redraw;
     private sourceFor;
     private draw;
+    /** A grade's LUT once loaded; while it loads (or if it fails) the frame is drawn without it and counts as incomplete. */
+    private readonly lutFor;
+    private readonly scratch;
     private readonly defineSvgFilter;
     /** Stops following the editor and releases every media element. */
     destroy(): void;
@@ -1448,6 +1818,8 @@ interface VideoEditorOptions {
      * loader for one (default: fetch and decode each asset's `src` with Web Audio, in a browser).
      */
     audioPeaks?: VideoAudioPeaksCache | VideoAudioPeaksLoader;
+    /** Where grades' LUT files (`.cube`) come from: a shared cache, or a loader (default: `fetch` each `src`). */
+    luts?: VideoLutCache | VideoLutLoader;
 }
 /** A snapshot of the editor. The same object is returned until something changes. */
 interface VideoEditorState {
@@ -1487,6 +1859,10 @@ declare class VideoEditorController {
     readonly player: AnimationPlayer;
     /** Sound levels per asset, loaded on demand for waveforms and agents. */
     readonly audioPeaks: VideoAudioPeaksCache;
+    /** The pixels the preview last drew, for scopes and `get_video_scopes` (a `VideoPreviewEngine` fills it). */
+    readonly previewPixels: VideoPreviewPixels;
+    /** Grades' LUTs, loaded on demand for the preview, SVG frames and agents. */
+    readonly luts: VideoLutCache;
     private project;
     private issues;
     private selection;
@@ -1587,6 +1963,14 @@ interface VideoEditorToolProviderOptions {
         data: string;
         mimeType: string;
     };
+    /**
+     * The rendered pixels of the frame at `time` (ms), for `get_video_scopes` (e.g. a frame decoded
+     * by ffmpeg on a server). Default: what the editor's `<VideoPreview>` draws, through
+     * `controller.previewPixels`, seeking it there and back when `time` is not the playhead.
+     */
+    framePixels?: (time: number) => VideoPixels | null | Promise<VideoPixels | null>;
+    /** How long `get_video_scopes` waits for the preview to finish drawing a frame (ms, default 5000). */
+    framePixelsTimeout?: number;
 }
 /** A project as agents see it: settings, assets, and each track's clips in order with their times. */
 declare function describeVideoProject(project: VideoProject): {
@@ -1840,5 +2224,10 @@ declare function videoKeyframeValueEdit(project: VideoProject, clipId: string, p
  * the plain value into keys), or removes the key there (the last one leaves its value plain).
  */
 declare function videoKeyframeToggleEdit(project: VideoProject, clipId: string, property: VideoKeyframeProperty, time: number): VideoEdit | null;
+/**
+ * Edits giving clips a grade LUT (keeping their other grade settings), or taking it off with
+ * `null`. Clips without a grade change are left out; one `controller.apply` makes it one undo step.
+ */
+declare function videoLutEdits(project: VideoProject, clips: readonly string[], lut: VideoGradeLut | null): VideoEdit[];
 
-export { type CreateVideoProjectOptions, type NewVideoClip, VIDEO_BLEND_MODES, VIDEO_BLEND_MODE_LABELS, VIDEO_CLIP_ANIMATION_DURATION, VIDEO_CLIP_ANIMATION_EFFECTS, VIDEO_CLIP_ANIMATION_LABELS, VIDEO_CLIP_TYPES, VIDEO_DEFAULT_FILLERS, VIDEO_DEFAULT_STILL_DURATION, VIDEO_DEFAULT_TITLE_DURATION, VIDEO_EASE_NAMES, VIDEO_EDIT_OPS, VIDEO_FADE_CURVES, VIDEO_FADE_CURVE_LABELS, VIDEO_FITS, VIDEO_GRADE_CONTROLS, VIDEO_GRADE_PRESETS, VIDEO_GRADE_PRESET_NAMES, VIDEO_ISSUE_CODES, VIDEO_KEYFRAME_LIMITS, VIDEO_KEYFRAME_PROPERTIES, VIDEO_PEAK_BLOCK, VIDEO_PLACEMENT_MODES, VIDEO_TIME_EPSILON, VIDEO_TRANSFORM_PROPERTIES, VIDEO_TRANSITION_LABELS, VIDEO_TRANSITION_TYPES, VIDEO_WIPE_DIRECTIONS, type VideoAnimatable, type VideoAsset, type VideoAssetKind, type VideoAudioLevel, type VideoAudioPeaks, VideoAudioPeaksCache, type VideoAudioPeaksLoader, type VideoAudioSource, type VideoBlendMode, type VideoCanvasContext, type VideoClip, type VideoClipAnimation, type VideoClipAnimationEffect, type VideoClipDragInput, type VideoClipDragMode, type VideoClipDragPlan, type VideoClipLocation, type VideoClipType, type VideoColorClip, type VideoEase, type VideoEdit, type VideoEditOp, type VideoEditOutcome, type VideoEditResult, VideoEditorController, type VideoEditorOptions, type VideoEditorState, type VideoEditorToolProviderOptions, type VideoEdlOptions, type VideoFadeCurve, type VideoFfmpegExport, type VideoFfmpegOptions, type VideoFit, type VideoFrame, type VideoGap, type VideoGrade, type VideoGradeControl, type VideoGradePreset, type VideoGradeStep, type VideoIssue, type VideoIssueCode, type VideoIssueSeverity, type VideoKey, type VideoKeyframeProperty, type VideoKeyframeRow, type VideoKeyframes, type VideoLayer, type VideoLoudnessMeasurement, type VideoLoudnessTarget, type VideoMarker, type VideoMediaClip, type VideoMediaProbe, type VideoPauseOptions, type VideoPlacementMode, VideoPreviewEngine, type VideoPreviewImage, type VideoPreviewMedia, type VideoPreviewOptions, type VideoPreviewSource, type VideoProject, type VideoRect, type VideoRulerTick, type VideoSilenceOptions, type VideoSnapOptions, type VideoSpeedSegment, type VideoSvgOptions, type VideoTextClip, type VideoTimelineWord, type VideoTrack, type VideoTrackKind, type VideoTranscriptRange, type VideoTranscriptWord, type VideoTransform, type VideoTransition, type VideoTransitionType, type VideoWaveformMode, type VideoWipeDirection, allVideoClipIds, applyVideoEdits, applyVideoGrade, buildVideoAudioPeaks, checkVideoProject, checkVideoTimeRemap, createVideoEditorToolProvider, createVideoProject, decodeVideoAudioPeaks, describeVideoProject, drawVideoFrame, ffmpegFilterValue, findVideoAudioSilences, findVideoClip, findVideoFillers, findVideoGaps, findVideoTranscriptPauses, findVideoTranscriptText, formatVideoSeconds, formatVideoTimecode, formatVideoTimecodeFrames, isVideoDropFrameRate, isVideoKeyframes, mergeVideoRanges, nextFreeVideoSlot, normalizeVideoGrade, normalizeVideoWord, parseVideoAnimatable, parseVideoAsset, parseVideoClip, parseVideoClipAnimation, parseVideoGrade, parseVideoKeyframes, parseVideoLoudnessMeasurement, parseVideoMarker, parseVideoProject, parseVideoTimeRemap, parseVideoTrack, parseVideoTranscript, parseVideoTranscriptWords, parseVideoTransform, parseVideoTransition, placeVideoRect, planVideoClipDrag, probeVideoMedia, removeVideoKey, retimeVideoAnimatable, setVideoKey, snapToVideoFrame, snapVideoTime, sortVideoKeys, sortedVideoClips, splitVideoAnimatable, toVideoEdl, toVideoFfmpeg, toVideoLoudnessMeasure, videoAssetDropEdit, videoAssetHasSound, videoAssetKindOf, videoAssetMap, videoAudioLevels, videoAudioPeakRange, videoAudioPeakSpans, videoAudioPeaksDuration, videoClipAfter, videoClipAnimated, videoClipAnimationProperties, videoClipAnimationSpans, videoClipBefore, videoClipEnd, videoClipHandles, videoClipKeyframes, videoClipLabel, videoClipOverhang, videoClipShowsWaveform, videoClipSoundGain, videoClipSourceRange, videoClipSourceTime, videoClipSpeed, videoClipSpeedAt, videoClipTint, videoClipWaveform, videoClipWaveformPath, videoClipsAt, videoContactSheetSvg, videoDragLabel, videoDropTracks, videoEaseBezier, videoEaseProgress, videoFadeCurveGain, videoFrameAt, videoFrameDuration, videoFrameToSvg, videoFrames, videoFreezeFrameEdit, videoGradeCssFilter, videoGradeFfmpegFilters, videoGradeGainsFilterId, videoGradePreset, videoGradeStepMatrix, videoGradeStepSvgValues, videoGradeSteps, videoGradeSvgDefs, videoGradeSvgFilter, videoHourFrames, videoIrisRadius, videoIssueKey, videoKeyframeBreakpoints, videoKeyframeFfmpegExpr, videoKeyframeRows, videoKeyframeToggleEdit, videoKeyframeValueEdit, videoKeysOf, videoOverlap, videoPeakDb, videoProjectDuration, videoProjectSvg, videoRemoveRangesEdits, videoRulerTicks, videoSlowMotionRamp, videoSnapPoints, videoSpeedRampEdit, videoSpeedRampKeys, videoTextStyle, videoTimeRemapBreakpoints, videoTimeRemapSpan, videoTimecodeFrames, videoTimelineTranscript, videoTitleFrame, videoTrackSyncLocked, videoTranscriptEdit, videoTranscriptTrack, videoTransformAt, videoTransitionAudioCurve, videoTransitionEase, videoTransitionHasDirection, videoValueAt, videoWaveformPath, videoWipeRect, videoWordAt, videoWordsRange };
+export { type CreateVideoProjectOptions, type NewVideoClip, VIDEO_BLEND_MODES, VIDEO_BLEND_MODE_LABELS, VIDEO_CLIP_ANIMATION_DURATION, VIDEO_CLIP_ANIMATION_EFFECTS, VIDEO_CLIP_ANIMATION_LABELS, VIDEO_CLIP_TYPES, VIDEO_DEFAULT_FILLERS, VIDEO_DEFAULT_STILL_DURATION, VIDEO_DEFAULT_TITLE_DURATION, VIDEO_EASE_NAMES, VIDEO_EDIT_OPS, VIDEO_FADE_CURVES, VIDEO_FADE_CURVE_LABELS, VIDEO_FITS, VIDEO_GRADE_CONTROLS, VIDEO_GRADE_PRESETS, VIDEO_GRADE_PRESET_NAMES, VIDEO_ISSUE_CODES, VIDEO_KEYFRAME_LIMITS, VIDEO_KEYFRAME_PROPERTIES, VIDEO_LUT_MAX_SIZE, VIDEO_PEAK_BLOCK, VIDEO_PLACEMENT_MODES, VIDEO_SCOPE_KINDS, VIDEO_TIME_EPSILON, VIDEO_TRANSFORM_PROPERTIES, VIDEO_TRANSITION_LABELS, VIDEO_TRANSITION_TYPES, VIDEO_VECTORSCOPE_TARGETS, VIDEO_WIPE_DIRECTIONS, type VideoAnimatable, type VideoAsset, type VideoAssetKind, type VideoAudioLevel, type VideoAudioPeaks, VideoAudioPeaksCache, type VideoAudioPeaksLoader, type VideoAudioSource, type VideoBlendMode, type VideoCanvasContext, type VideoClip, type VideoClipAnimation, type VideoClipAnimationEffect, type VideoClipDragInput, type VideoClipDragMode, type VideoClipDragPlan, type VideoClipLocation, type VideoClipType, type VideoColorClip, type VideoDrawOptions, type VideoEase, type VideoEdit, type VideoEditOp, type VideoEditOutcome, type VideoEditResult, VideoEditorController, type VideoEditorOptions, type VideoEditorState, type VideoEditorToolProviderOptions, type VideoEdlOptions, type VideoExposureOptions, type VideoExposureStats, type VideoFadeCurve, type VideoFfmpegExport, type VideoFfmpegOptions, type VideoFit, type VideoFrame, type VideoGap, type VideoGrade, type VideoGradeControl, type VideoGradeLut, type VideoGradePreset, type VideoGradeSetting, type VideoGradeStep, type VideoHistogram, type VideoIssue, type VideoIssueCode, type VideoIssueSeverity, type VideoKey, type VideoKeyframeProperty, type VideoKeyframeRow, type VideoKeyframes, type VideoLayer, type VideoLoudnessMeasurement, type VideoLoudnessTarget, type VideoLut, VideoLutCache, type VideoLutLoader, type VideoLutSvgApproximation, type VideoMarker, type VideoMediaClip, type VideoMediaProbe, type VideoPauseOptions, type VideoPixels, type VideoPlacementMode, VideoPreviewEngine, type VideoPreviewImage, type VideoPreviewMedia, type VideoPreviewOptions, VideoPreviewPixels, type VideoPreviewSnapshot, type VideoPreviewSource, type VideoProject, type VideoRect, type VideoRulerTick, type VideoScopeImage, type VideoScopeKind, type VideoScopeOptions, type VideoScopeSummary, type VideoScopesPanelReading, type VideoScratchCanvas, type VideoSilenceOptions, type VideoSnapOptions, type VideoSpeedSegment, type VideoSvgOptions, type VideoTextClip, type VideoTimelineWord, type VideoTrack, type VideoTrackKind, type VideoTranscriptRange, type VideoTranscriptWord, type VideoTransform, type VideoTransition, type VideoTransitionType, type VideoVectorscope, type VideoWaveform, type VideoWaveformMode, type VideoWipeDirection, allVideoClipIds, applyVideoEdits, applyVideoGrade, applyVideoLut, applyVideoLutToPixels, buildVideoAudioPeaks, checkVideoProject, checkVideoTimeRemap, createVideoEditorToolProvider, createVideoProject, decodeVideoAudioPeaks, describeVideoProject, drawVideoFrame, ffmpegFilterValue, findVideoAudioSilences, findVideoClip, findVideoFillers, findVideoGaps, findVideoTranscriptPauses, findVideoTranscriptText, formatVideoSeconds, formatVideoTimecode, formatVideoTimecodeFrames, isVideoDropFrameRate, isVideoKeyframes, mergeVideoRanges, nextFreeVideoSlot, normalizeVideoGrade, normalizeVideoGradeLut, normalizeVideoWord, parseVideoAnimatable, parseVideoAsset, parseVideoClip, parseVideoClipAnimation, parseVideoCubeLut, parseVideoGrade, parseVideoGradeLut, parseVideoKeyframes, parseVideoLoudnessMeasurement, parseVideoMarker, parseVideoProject, parseVideoTimeRemap, parseVideoTrack, parseVideoTranscript, parseVideoTranscriptWords, parseVideoTransform, parseVideoTransition, placeVideoRect, planVideoClipDrag, probeVideoMedia, readVideoScopesPanel, removeVideoKey, retimeVideoAnimatable, setVideoKey, snapToVideoFrame, snapVideoTime, sortVideoKeys, sortedVideoClips, splitVideoAnimatable, summarizeVideoScopes, toVideoEdl, toVideoFfmpeg, toVideoLoudnessMeasure, videoAssetDropEdit, videoAssetHasSound, videoAssetKindOf, videoAssetMap, videoAudioLevels, videoAudioPeakRange, videoAudioPeakSpans, videoAudioPeaksDuration, videoChroma, videoClipAfter, videoClipAnimated, videoClipAnimationProperties, videoClipAnimationSpans, videoClipBefore, videoClipEnd, videoClipHandles, videoClipKeyframes, videoClipLabel, videoClipOverhang, videoClipShowsWaveform, videoClipSoundGain, videoClipSourceRange, videoClipSourceTime, videoClipSpeed, videoClipSpeedAt, videoClipTint, videoClipWaveform, videoClipWaveformPath, videoClipsAt, videoContactSheetSvg, videoDragLabel, videoDropTracks, videoEaseBezier, videoEaseProgress, videoExposureNotes, videoExposureStats, videoFadeCurveGain, videoFrameAt, videoFrameDuration, videoFrameToSvg, videoFrames, videoFreezeFrameEdit, videoGradeCssFilter, videoGradeFfmpegFilters, videoGradeGainsFilterId, videoGradeLook, videoGradePreset, videoGradeStepMatrix, videoGradeStepSvgValues, videoGradeSteps, videoGradeSvgDefs, videoGradeSvgFilter, videoHistogram, videoHistogramImage, videoHourFrames, videoIrisRadius, videoIssueKey, videoKeyframeBreakpoints, videoKeyframeFfmpegExpr, videoKeyframeRows, videoKeyframeToggleEdit, videoKeyframeValueEdit, videoKeysOf, videoLuma, videoLumaWaveform, videoLutEdits, videoLutFromFunction, videoLutSvgApproximation, videoLutSvgPrimitives, videoLutToCube, videoOverlap, videoPeakDb, videoProjectDuration, videoProjectSvg, videoRemoveRangesEdits, videoRulerTicks, videoScopeImage, videoSlowMotionRamp, videoSnapPoints, videoSpeedRampEdit, videoSpeedRampKeys, videoTextStyle, videoTimeRemapBreakpoints, videoTimeRemapSpan, videoTimecodeFrames, videoTimelineTranscript, videoTitleFrame, videoTrackSyncLocked, videoTranscriptEdit, videoTranscriptTrack, videoTransformAt, videoTransitionAudioCurve, videoTransitionEase, videoTransitionHasDirection, videoValueAt, videoVectorscope, videoVectorscopeAngle, videoVectorscopeImage, videoVectorscopePoint, videoWaveformImage, videoWaveformPath, videoWipeRect, videoWordAt, videoWordsRange };