@pixerate/editor 0.87.0 → 0.89.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";
@@ -1424,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;
@@ -1447,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). */
@@ -1480,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`. */
@@ -1573,6 +1696,8 @@ interface VideoPreviewSource {
     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 {
@@ -1620,6 +1745,13 @@ interface VideoPreviewOptions {
      * 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
@@ -1643,6 +1775,9 @@ declare class VideoPreviewEngine {
     private readonly pixelsTarget;
     private drawn;
     private complete;
+    private readonly lutCache;
+    private readonly unsubscribeLuts;
+    private scratchCanvas;
     constructor(source: VideoPreviewSource, canvas: {
         width: number;
         height: number;
@@ -1660,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;
@@ -1680,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 {
@@ -1721,6 +1861,8 @@ declare class VideoEditorController {
     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;
@@ -2082,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_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 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 VideoGradePreset, 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 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 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, 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, 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, videoGradePreset, videoGradeStepMatrix, videoGradeStepSvgValues, videoGradeSteps, videoGradeSvgDefs, videoGradeSvgFilter, videoHistogram, videoHistogramImage, videoHourFrames, videoIrisRadius, videoIssueKey, videoKeyframeBreakpoints, videoKeyframeFfmpegExpr, videoKeyframeRows, videoKeyframeToggleEdit, videoKeyframeValueEdit, videoKeysOf, videoLuma, videoLumaWaveform, 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 };
+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 };

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

@@ -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";
@@ -1424,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;
@@ -1447,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). */
@@ -1480,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`. */
@@ -1573,6 +1696,8 @@ interface VideoPreviewSource {
     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 {
@@ -1620,6 +1745,13 @@ interface VideoPreviewOptions {
      * 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
@@ -1643,6 +1775,9 @@ declare class VideoPreviewEngine {
     private readonly pixelsTarget;
     private drawn;
     private complete;
+    private readonly lutCache;
+    private readonly unsubscribeLuts;
+    private scratchCanvas;
     constructor(source: VideoPreviewSource, canvas: {
         width: number;
         height: number;
@@ -1660,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;
@@ -1680,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 {
@@ -1721,6 +1861,8 @@ declare class VideoEditorController {
     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;
@@ -2082,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_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 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 VideoGradePreset, 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 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 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, 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, 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, videoGradePreset, videoGradeStepMatrix, videoGradeStepSvgValues, videoGradeSteps, videoGradeSvgDefs, videoGradeSvgFilter, videoHistogram, videoHistogramImage, videoHourFrames, videoIrisRadius, videoIssueKey, videoKeyframeBreakpoints, videoKeyframeFfmpegExpr, videoKeyframeRows, videoKeyframeToggleEdit, videoKeyframeValueEdit, videoKeysOf, videoLuma, videoLumaWaveform, 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 };
+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 };