@pixerate/editor 0.82.0 → 0.84.0

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

@@ -142,8 +142,16 @@ interface VideoTransform {
 /** How a picture is fitted to the frame before its transform: like CSS `object-fit`. */
 type VideoFit = 'contain' | 'cover' | 'fill' | 'none';
 declare const VIDEO_FITS: readonly ["contain", "cover", "fill", "none"];
-type VideoTransitionType = 'crossfade' | 'dip' | 'wipe';
-declare const VIDEO_TRANSITION_TYPES: readonly ["crossfade", "dip", "wipe"];
+/**
+ * - `crossfade`: this clip fades up over the one before.
+ * - `dip`: down into a colour and up out of it.
+ * - `wipe`: an edge travels across, revealing this clip.
+ * - `push`: this clip slides in, pushing the one before out.
+ * - `slide`: this clip slides in over the one before, which stays put.
+ * - `iris`: a circle opens from the centre, revealing this clip.
+ */
+type VideoTransitionType = 'crossfade' | 'dip' | 'wipe' | 'push' | 'slide' | 'iris';
+declare const VIDEO_TRANSITION_TYPES: readonly ["crossfade", "dip", "wipe", "push", "slide", "iris"];
 type VideoWipeDirection = 'left' | 'right' | 'up' | 'down';
 declare const VIDEO_WIPE_DIRECTIONS: readonly ["left", "right", "up", "down"];
 /**
@@ -157,8 +165,54 @@ interface VideoTransition {
     duration: number;
     /** For dip: the colour passed through (default black). */
     color?: string;
-    /** For wipe: the way the edge travels (default right, revealing from the left). */
+    /** For wipe, push and slide: the way the edge or picture travels (default right: in from the left). */
     direction?: VideoWipeDirection;
+    /**
+     * Shape of the sound's fades through the transition (see `VideoFadeCurve`). Default
+     * `equal-power` for crossfades and wipes, where two sounds overlap and a linear mix dips in
+     * loudness halfway; `linear` for dips, where one sound fades out before the other fades in.
+     */
+    audioCurve?: VideoFadeCurve;
+}
+/** The curve a transition's sound fades follow (its `audioCurve`, else the default for its type). */
+declare const videoTransitionAudioCurve: (t: VideoTransition) => VideoFadeCurve;
+/**
+ * How a clip's picture mixes with what is beneath it, as in CSS `mix-blend-mode` (`add` sums the
+ * colours, `plus-lighter` in CSS). These are the modes the canvas preview, SVG frames and ffmpeg's
+ * `blend` filter all share.
+ */
+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"];
+/**
+ * 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).
+ */
+interface VideoGrade {
+    /** Stops: +1 doubles every channel (default 0). */
+    exposure?: number;
+    /** -1 (flat grey) to 1 (twice as steep), around mid grey (default 0). */
+    contrast?: number;
+    /** -1 (black and white) to 1 (twice as saturated); default 0. */
+    saturation?: number;
+    /** Hue rotation in degrees (default 0). */
+    hue?: number;
+    /** -1 (cool) to 1 (warm); default 0. */
+    temperature?: number;
+    /** -1 (green) to 1 (magenta); default 0. */
+    tint?: number;
+}
+/**
+ * How a clip enters or leaves: `fade`; `rise` (up into place) or `drop` (down into place);
+ * `slide-left` / `slide-right` (in moving that way); `zoom` (grows into place); `pop` (grows past its
+ * size and settles). Each also fades. An exit plays the same movement backwards.
+ */
+type VideoClipAnimationEffect = 'fade' | 'rise' | 'drop' | 'slide-left' | 'slide-right' | 'zoom' | 'pop';
+declare const VIDEO_CLIP_ANIMATION_EFFECTS: readonly ["fade", "rise", "drop", "slide-left", "slide-right", "zoom", "pop"];
+/** An entrance or exit animation (see `VideoClipAnimationEffect`). */
+interface VideoClipAnimation {
+    effect: VideoClipAnimationEffect;
+    /** Length (ms, default 500). */
+    duration?: number;
 }
 interface VideoClipBase {
     id: string;
@@ -172,6 +226,14 @@ interface VideoClipBase {
     transform?: VideoTransform;
     /** Default contain. */
     fit?: VideoFit;
+    /** How the picture mixes with what is beneath it (default normal). */
+    blend?: VideoBlendMode;
+    /** Colour correction of the picture. */
+    grade?: VideoGrade;
+    /** How the picture enters, from the clip's start (on top of any fade in). */
+    animateIn?: VideoClipAnimation;
+    /** How the picture leaves, up to the clip's end. */
+    animateOut?: VideoClipAnimation;
     /** Fade in from nothing over this long (ms), pictures and sound. */
     fadeIn?: number;
     /** Fade out over this long (ms). */
@@ -179,6 +241,17 @@ interface VideoClipBase {
     /** Transition from the clip before (see `VideoTransition`). */
     transition?: VideoTransition;
 }
+/**
+ * The shape of a sound fade, the same curves ffmpeg's `afade` draws, so previews and exports agree.
+ * With `x` running 0→1 through a fade in (1→0 through a fade out), the gain is:
+ * - `linear`: x (ffmpeg `tri`). Dips in loudness in the middle of a crossfade.
+ * - `equal-power`: sin(x·π/2) (`qsin`). Keeps loudness steady; the usual choice for crossfades.
+ * - `s-curve`: (1 − cos(x·π))/2 (`hsin`). Gentle at both ends.
+ * - `exponential`: x³ (`cub`). Slow start; a natural-sounding fade in from silence.
+ * - `logarithmic`: 1 − (1 − x)² (`ipar`). Fast start, slow finish.
+ */
+type VideoFadeCurve = 'linear' | 'equal-power' | 's-curve' | 'exponential' | 'logarithmic';
+declare const VIDEO_FADE_CURVES: readonly ["linear", "equal-power", "s-curve", "exponential", "logarithmic"];
 /** A stretch of an asset. */
 interface VideoMediaClip extends VideoClipBase {
     type: 'media';
@@ -191,6 +264,10 @@ interface VideoMediaClip extends VideoClipBase {
     volume?: VideoAnimatable;
     /** Silences this clip. */
     muted?: boolean;
+    /** Shape of the sound's fade in (default linear). The picture always fades linearly. */
+    fadeInCurve?: VideoFadeCurve;
+    /** Shape of the sound's fade out (default linear). */
+    fadeOutCurve?: VideoFadeCurve;
 }
 /** A title. */
 interface VideoTextClip extends VideoClipBase {
@@ -259,6 +336,8 @@ declare function parseVideoAnimatable(v: unknown, path: string, range?: {
     optional?: boolean;
 }): VideoAnimatable | undefined;
 declare function parseVideoTransform(v: unknown, path: string): VideoTransform | undefined;
+declare function parseVideoClipAnimation(v: unknown, path: string): VideoClipAnimation | undefined;
+declare function parseVideoGrade(v: unknown, path: string): VideoGrade | undefined;
 declare function parseVideoTransition(v: unknown, path: string): VideoTransition | undefined;
 declare function parseVideoAsset(v: unknown, path?: string): VideoAsset;
 declare function parseVideoClip(v: unknown, path?: string): VideoClip;
@@ -302,10 +381,28 @@ declare const videoFrameDuration: (fps: number) => number;
 declare function snapToVideoFrame(time: number, fps: number): number;
 /** Whole frames in `time` at `fps` (rounded). */
 declare const videoFrames: (time: number, fps: number) => number;
-/** Non-drop SMPTE timecode `HH:MM:SS:FF` for a time (ms). */
-declare function formatVideoTimecode(time: number, fps: number): string;
+/**
+ * Whether `fps` is an NTSC rate that SMPTE counts in drop-frame timecode: 29.97 (30000/1001) or
+ * 59.94 (60000/1001). Other fractional rates (23.976) have no drop-frame form.
+ */
+declare function isVideoDropFrameRate(fps: number): boolean;
+/** Frames elapsed in `time` (ms), counted at the exact rate behind a rounded NTSC rate. */
+declare const videoTimecodeFrames: (time: number, fps: number) => number;
+/**
+ * SMPTE timecode for a time (ms): `HH:MM:SS:FF`, or `HH:MM:SS;FF` in drop-frame, which skips frame
+ * numbers 0 and 1 (0–3 at 59.94) at the start of every minute except each tenth, so the clock keeps
+ * up with real time at NTSC rates. `dropFrame` defaults to on at 29.97 and 59.94 and is ignored at
+ * rates without a drop-frame form.
+ */
+declare function formatVideoTimecode(time: number, fps: number, dropFrame?: boolean): string;
+/** SMPTE timecode for a frame count (see `formatVideoTimecode`). */
+declare function formatVideoTimecodeFrames(frames: number, fps: number, dropFrame?: boolean): string;
+/** Frames up to timecode `01:00:00:00` (`;00` in drop-frame), where record timecode usually starts. */
+declare const videoHourFrames: (fps: number, dropFrame?: boolean) => number;
 /** Readable time for messages: `2.50 s`. */
 declare const formatVideoSeconds: (time: number) => string;
+/** Whether an asset carries sound: audio, or video not marked `hasAudio: false`. */
+declare const videoAssetHasSound: (asset: VideoAsset | undefined) => boolean;
 declare function videoAssetMap(project: VideoProject): Map<string, VideoAsset>;
 /** A track's clips in timeline order. */
 declare function sortedVideoClips(track: VideoTrack): VideoClip[];
@@ -377,7 +474,7 @@ declare function videoClipKeyframes(clip: VideoClip): {
     keys: ReturnType<typeof videoKeysOf>;
 }[];
 type VideoIssueSeverity = 'error' | 'warning' | 'note';
-declare const VIDEO_ISSUE_CODES: readonly ["missing-asset", "wrong-track", "overlap", "source-overrun", "transition-without-cut", "transition-too-long", "transition-handles", "fades-too-long", "keyframes-outside-clip", "unknown-duration", "unused-asset", "marker-past-end", "empty"];
+declare const VIDEO_ISSUE_CODES: readonly ["missing-asset", "wrong-track", "overlap", "source-overrun", "transition-without-cut", "transition-too-long", "transition-handles", "fades-too-long", "animations-too-long", "animation-keyed", "keyframes-outside-clip", "unknown-duration", "unused-asset", "marker-past-end", "empty"];
 type VideoIssueCode = (typeof VIDEO_ISSUE_CODES)[number];
 interface VideoIssue {
     code: VideoIssueCode;
@@ -620,6 +717,10 @@ interface VideoLayer {
         direction: VideoWipeDirection;
         progress: number;
     };
+    /** For an iris: only a circle on the frame's centre shows, its radius `progress` (0–1) of the way to the frame's corners. */
+    iris?: {
+        progress: number;
+    };
     /** For text: what to draw. */
     text?: {
         text: string;
@@ -631,6 +732,10 @@ interface VideoLayer {
     };
     /** For colour clips and dips. */
     color?: string;
+    /** How it mixes with the layers beneath (absent = normal). */
+    blend?: VideoBlendMode;
+    /** Colour correction (absent = none). */
+    grade?: VideoGrade;
 }
 /** One sound playing at a moment. */
 interface VideoAudioSource {
@@ -677,6 +782,15 @@ declare function videoTextStyle(clip: VideoTextClip): NonNullable<VideoLayer['te
  * transforms without them, and moves the image itself).
  */
 declare function videoTitleFrame(project: VideoProject, clip: VideoTextClip, clipTime?: number): VideoFrame;
+/** How far a push or slide has moved at `progress` (0–1): eased in and out, (1 − cos πp) / 2. */
+declare const videoTransitionEase: (progress: number) => number;
+/** Gain of a fade shape `x` of the way up (0–1); a fade out uses the time left, so it mirrors the fade in. */
+declare function videoFadeCurveGain(curve: VideoFadeCurve | undefined, x: number): number;
+/**
+ * A media clip's own gain at clip time `clipTime` (ms): its volume (or volume keyframes) times its
+ * shaped fades. Leaves out track volume and transitions, which depend on the timeline around it.
+ */
+declare function videoClipSoundGain(clip: VideoClip, clipTime: number): number;
 /**
  * What plays at `time` (ms): the pictures to draw, back to front, with their placement, opacity
  * and the moment of source each shows, and the sounds with their gain. A pure function of the
@@ -684,6 +798,241 @@ declare function videoTitleFrame(project: VideoProject, clip: VideoTextClip, cli
  */
 declare function videoFrameAt(project: VideoProject, time: number): VideoFrame;
 
+/**
+ * Sound levels of a piece of audio, small enough to keep for every asset: a pyramid of min / max
+ * sample values. Level 0 holds one min / max pair per `blockSize` samples; each level above merges
+ * four blocks of the one below, so the min / max of any stretch costs a handful of reads at any
+ * zoom. Channels are folded together (the loudest of them counts). Plain data: hosts can compute
+ * it once (`buildVideoAudioPeaks`) and store it.
+ */
+interface VideoAudioPeaks {
+    /** Samples per second of the decoded audio. */
+    sampleRate: number;
+    /** Samples in the audio (per channel). */
+    length: number;
+    /** Samples per level-0 block. */
+    blockSize: number;
+    /** `levels[k]` is `[min, max, min, max, …]`, one pair per block of `blockSize × 4^k` samples. */
+    levels: Float32Array[];
+}
+/** Samples per level-0 block (well under a millisecond at common rates). */
+declare const VIDEO_PEAK_BLOCK = 32;
+/** Builds the peak pyramid for decoded audio (one `Float32Array` of samples per channel). */
+declare function buildVideoAudioPeaks(channels: readonly Float32Array[], sampleRate: number, blockSize?: number): VideoAudioPeaks;
+/** Length of the audio (ms). */
+declare const videoAudioPeaksDuration: (peaks: VideoAudioPeaks) => number;
+/**
+ * The lowest and highest sample between two times (ms) in the audio, to the nearest block (so a
+ * stretch can read up to a block wider). `{ min: 0, max: 0 }` outside the audio.
+ */
+declare function videoAudioPeakRange(peaks: VideoAudioPeaks, from: number, to: number): {
+    min: number;
+    max: number;
+};
+/** `columns` min / max pairs (`[min, max, …]`) evenly across `from`..`to` ms, e.g. one per pixel. */
+declare function videoAudioPeakSpans(peaks: VideoAudioPeaks, from: number, to: number, columns: number): Float32Array;
+/**
+ * What a media clip plays as `columns` min / max pairs across its length: each column reads the
+ * stretch of source under it (through the in point and speed) and is scaled by the clip's volume and
+ * fades, so the waveform shows what is heard.
+ */
+declare function videoClipWaveform(clip: VideoMediaClip, peaks: VideoAudioPeaks, columns: number): Float32Array;
+/**
+ * An SVG path (`d`) of a waveform filling `width` × `height`: the top edge along the maxima, back
+ * along the minima. Values are clamped to ±1, so anything louder than full scale touches the edge.
+ */
+declare function videoWaveformPath(spans: Float32Array, width: number, height: number): string;
+/**
+ * The SVG path of a media clip's waveform drawn `width` × `height` pixels (one column per 2 px), as
+ * `videoClipWaveform` reads it: what timelines draw inside an audio clip.
+ */
+declare function videoClipWaveformPath(clip: VideoMediaClip, peaks: VideoAudioPeaks, width: number, height: number): string;
+/** A sample value as dBFS, floored at -100 (silence). */
+declare const videoPeakDb: (value: number) => number;
+interface VideoAudioLevel {
+    /** Start of the bucket (ms, in the clock the caller asked in). */
+    start: number;
+    end: number;
+    /** Peak level in dBFS (0 = full scale, -100 = silence). */
+    peakDb: number;
+}
+/** Peak level in `buckets` equal stretches of `from`..`to` ms of the audio. */
+declare function videoAudioLevels(peaks: VideoAudioPeaks, from: number, to: number, buckets: number): VideoAudioLevel[];
+interface VideoSilenceOptions {
+    /** Quieter than this peak level counts as silence (dBFS, default -40). */
+    thresholdDb?: number;
+    /** Shortest silence to report (ms, default 300). */
+    minDuration?: number;
+    /** Resolution of the scan (ms, default 10). */
+    resolution?: number;
+}
+/** Stretches of `from`..`to` ms of the audio that stay below a level, at least `minDuration` long. */
+declare function findVideoAudioSilences(peaks: VideoAudioPeaks, from: number, to: number, options?: VideoSilenceOptions): {
+    start: number;
+    end: number;
+}[];
+/** Fetches and decodes a media file's sound into peaks, in a browser (Web Audio). */
+declare function decodeVideoAudioPeaks(src: string, options?: {
+    signal?: AbortSignal;
+}): Promise<VideoAudioPeaks>;
+/** Loads the peaks of an asset's sound. */
+type VideoAudioPeaksLoader = (asset: VideoAsset) => Promise<VideoAudioPeaks>;
+/**
+ * Peaks per asset, loaded once each (by `src`) and shared by the timeline and agent tools.
+ * `get` returns what is ready and starts loading the rest; `subscribe` hears when more is ready.
+ */
+declare class VideoAudioPeaksCache {
+    private readonly loader;
+    private readonly ready;
+    private readonly pending;
+    private readonly failed;
+    private readonly listeners;
+    constructor(loader?: VideoAudioPeaksLoader);
+    /** The peaks if ready, without starting to load them. */
+    peek(asset: VideoAsset): VideoAudioPeaks | undefined;
+    /** The peaks if ready; otherwise `undefined`, and loading starts (once) unless it failed. */
+    get(asset: VideoAsset): VideoAudioPeaks | undefined;
+    /** Why loading an asset's peaks failed, if it did. */
+    error(asset: VideoAsset): string | undefined;
+    /** The peaks, loading them if needed. Rejects with a readable error. */
+    load(asset: VideoAsset): Promise<VideoAudioPeaks>;
+    /** Uses peaks the host already has (computed earlier or stored). */
+    set(src: string, peaks: VideoAudioPeaks): 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.
+ * Every step is one the browser has (CSS `brightness`, `contrast`, `saturate`, `hue-rotate`; white
+ * balance as an SVG `feColorMatrix`) and ffmpeg has (`lutrgb`, `colorchannelmixer`), with the same
+ * 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. */
+interface VideoGradeControl {
+    key: keyof VideoGrade;
+    label: string;
+    min: number;
+    max: number;
+    step: number;
+    /** What the number means, for tool descriptions. */
+    description: string;
+}
+declare const VIDEO_GRADE_CONTROLS: readonly VideoGradeControl[];
+/** Named looks. Apply them at a strength with `videoGradePreset`. */
+declare const VIDEO_GRADE_PRESETS: {
+    readonly warm: {
+        readonly temperature: 0.4;
+        readonly saturation: 0.1;
+    };
+    readonly cool: {
+        readonly temperature: -0.4;
+        readonly tint: -0.05;
+    };
+    readonly punchy: {
+        readonly contrast: 0.25;
+        readonly saturation: 0.3;
+    };
+    readonly faded: {
+        readonly exposure: 0.15;
+        readonly contrast: -0.3;
+        readonly saturation: -0.3;
+    };
+    readonly 'black-and-white': {
+        readonly saturation: -1;
+        readonly contrast: 0.15;
+    };
+    readonly 'bleach-bypass': {
+        readonly saturation: -0.6;
+        readonly contrast: 0.4;
+    };
+    readonly 'day-for-night': {
+        readonly exposure: -1.5;
+        readonly saturation: -0.4;
+        readonly temperature: -0.6;
+    };
+};
+type VideoGradePreset = keyof typeof VIDEO_GRADE_PRESETS;
+declare const VIDEO_GRADE_PRESET_NAMES: VideoGradePreset[];
+/** 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;
+/** One step of a grade. */
+type VideoGradeStep = {
+    kind: 'brightness';
+    amount: number;
+} | {
+    kind: 'contrast';
+    amount: number;
+} | {
+    kind: 'saturate';
+    amount: number;
+} | {
+    kind: 'hue-rotate';
+    degrees: number;
+} | {
+    kind: 'gains';
+    r: number;
+    g: number;
+    b: number;
+};
+/** The steps a grade applies, in order, leaving out those that change nothing. */
+declare function videoGradeSteps(grade: VideoGrade | undefined): VideoGradeStep[];
+/**
+ * A step as a 3 × 4 matrix (rows r, g, b; columns r, g, b, offset), with the coefficients the CSS
+ * 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];
+/** 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;
+/** 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";
+}>) => string;
+/**
+ * A grade as a CSS / canvas `filter`: CSS functions for every step, and `url(#id)` for white balance,
+ * which CSS has no function for (see `videoGradeGainsFilterId`; the host puts that filter in the page).
+ * `''` when the grade changes nothing.
+ */
+declare function videoGradeCssFilter(grade: VideoGrade | undefined): string;
+/** The white-balance SVG filters a grade's CSS filter refers to, as `{ id, markup }`. */
+declare function videoGradeSvgDefs(grade: VideoGrade | undefined): {
+    id: string;
+    markup: string;
+}[];
+/** 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[];
+
+/** Default length of an entrance or exit animation (ms). */
+declare const VIDEO_CLIP_ANIMATION_DURATION = 500;
+declare const PROPS: readonly ["opacity", "x", "y", "scale"];
+type Prop = (typeof PROPS)[number];
+/** The properties an animation moves (each also fades: opacity is always one). */
+declare function videoClipAnimationProperties(animation: VideoClipAnimation): Prop[];
+/** Entrance and exit lengths (ms), shortened in proportion when together they are longer than the clip. */
+declare function videoClipAnimationSpans(clip: VideoClip): {
+    in: number;
+    out: number;
+};
+/**
+ * The clip with its entrance and exit animations written out as keyframes on opacity, x, y and
+ * scale, so previews, SVG frames and the ffmpeg export all play them the same way. A property the
+ * clip already keys itself is left alone (`checkVideoProject` notes it). Returns the clip unchanged
+ * when it has no animations.
+ */
+declare function videoClipAnimated(clip: VideoClip, project: Pick<VideoProject, 'width' | 'height'>): VideoClip;
+
+/** Radius of an iris `progress` (0–1) open: from nothing to the frame's corners. */
+declare const videoIrisRadius: (frame: {
+    width: number;
+    height: number;
+}, progress: number) => number;
 /** The part of a rect a wipe shows. */
 declare function videoWipeRect(rect: VideoRect, wipe: NonNullable<VideoLayer['wipe']>): VideoRect;
 interface VideoSvgOptions {
@@ -705,8 +1054,10 @@ declare function videoContactSheetSvg(project: VideoProject, times: readonly num
     width?: number;
 }): string;
 /** The subset of `CanvasRenderingContext2D` `drawVideoFrame` uses (so tests and workers can pass their own). */
-type VideoCanvasContext = Pick<CanvasRenderingContext2D, 'save' | 'restore' | 'fillRect' | 'drawImage' | 'translate' | 'rotate' | 'beginPath' | 'rect' | 'clip' | 'fillText' | 'measureText' | 'setTransform'> & {
+type VideoCanvasContext = Pick<CanvasRenderingContext2D, 'save' | 'restore' | 'fillRect' | 'drawImage' | 'translate' | 'rotate' | 'beginPath' | 'rect' | 'arc' | 'clip' | 'fillText' | 'measureText' | 'setTransform'> & {
     globalAlpha: number;
+    globalCompositeOperation: GlobalCompositeOperation;
+    filter?: string;
     fillStyle: string | CanvasGradient | CanvasPattern;
     font: string;
     textAlign: CanvasTextAlign;
@@ -718,21 +1069,27 @@ type VideoCanvasContext = Pick<CanvasRenderingContext2D, 'save' | 'restore' | 'f
 /**
  * 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.
+ * 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).
  */
-declare function drawVideoFrame(ctx: VideoCanvasContext, frame: VideoFrame, sourceFor: (layer: VideoLayer) => CanvasImageSource | null, scale?: number): void;
+declare function drawVideoFrame(ctx: VideoCanvasContext, frame: VideoFrame, sourceFor: (layer: VideoLayer) => CanvasImageSource | null, scale?: number, options?: {
+    defineSvgFilter?: (id: string, markup: string) => void;
+}): void;
 
 interface VideoEdlOptions {
     /** Track to export (default: the bottom video track, V1 in most NLEs). */
     track?: string;
-    /** Record timecode of the timeline's start (ms, default 1 hour, the usual 01:00:00:00). */
+    /** Record timecode of the timeline's start (ms; default timecode 01:00:00:00, the usual start). */
     recordStart?: number;
     /** Title line (default: the project's name). */
     title?: string;
+    /** Drop-frame timecode (default on at 29.97 and 59.94 fps, where it is the norm; ignored at other rates). */
+    dropFrame?: boolean;
 }
 /**
  * One track as a CMX 3600 edit decision list, for conforming in another NLE: an event per clip with
- * source and record timecode at the project's frame rate, dissolves (`D`) for crossfades, dips and
+ * source and record timecode at the project's frame rate (drop-frame at 29.97 and 59.94), dissolves (`D`) for crossfades, dips and
  * wipes (`W001`), `M2` lines for speed changes, and `* FROM CLIP NAME` comments. Titles and colour
  * clips become black (`BL`) events.
  */
@@ -760,7 +1117,42 @@ interface VideoFfmpegOptions {
         width: number;
         height: number;
     }) => string;
+    /** Normalise the mix's loudness with ffmpeg's `loudnorm` (EBU R128). */
+    loudness?: VideoLoudnessTarget;
 }
+/** A loudness to normalise the mix to (`loudnorm`'s I, TP and LRA). */
+interface VideoLoudnessTarget {
+    /** Integrated loudness, in LUFS (default -14, as streaming services play; -16 for podcasts, -23 for EBU R128 broadcast). */
+    integrated?: number;
+    /** Highest true peak, in dBTP (default -1). */
+    truePeak?: number;
+    /** Loudness range, in LU (default 11). */
+    range?: number;
+    /**
+     * The mix as a first pass measured it (`toVideoLoudnessMeasure` then
+     * `parseVideoLoudnessMeasurement`). With it the second pass applies one fixed gain where it can
+     * (linear), so the dynamics are kept; without it `loudnorm` adjusts as it goes in one pass.
+     */
+    measured?: VideoLoudnessMeasurement;
+}
+/** What a measuring pass found (`loudnorm`'s input_i, input_tp, input_lra, input_thresh and target_offset). */
+interface VideoLoudnessMeasurement {
+    /** Integrated loudness (LUFS). */
+    integrated: number;
+    /** True peak (dBTP). */
+    truePeak: number;
+    /** Loudness range (LU). */
+    range: number;
+    /** Gating threshold (LUFS). */
+    threshold: number;
+    /** Offset for the second pass (LU). */
+    offset: number;
+}
+/**
+ * Reads the loudness a measuring pass printed (the JSON `loudnorm` writes to stderr at the end of
+ * `toVideoLoudnessMeasure`'s command). Throws when there is none, or when the mix is silent.
+ */
+declare function parseVideoLoudnessMeasurement(output: string): VideoLoudnessMeasurement;
 interface VideoFfmpegExport {
     /** Arguments after `ffmpeg` (pass to `spawn('ffmpeg', args)`; no shell quoting needed). */
     args: string[];
@@ -782,6 +1174,13 @@ declare const ffmpegFilterValue: (s: string) => string;
  * mixed and trimmed to the project's length. Render on a server or with ffmpeg.wasm.
  */
 declare function toVideoFfmpeg(project: VideoProject, options?: VideoFfmpegOptions): VideoFfmpegExport;
+/**
+ * The first pass of a two-pass loudness normalisation: an ffmpeg command that mixes only the sound,
+ * as `toVideoFfmpeg` would, and prints its loudness as JSON on stderr instead of writing a file.
+ * Read it with `parseVideoLoudnessMeasurement` and pass it as `loudness.measured` to
+ * `toVideoFfmpeg`. Throws when nothing on the timeline makes a sound.
+ */
+declare function toVideoLoudnessMeasure(project: VideoProject, options?: Pick<VideoFfmpegOptions, 'resolve' | 'loudness'>): VideoFfmpegExport;
 
 /** What a preview follows: a `VideoEditorController` fits. */
 interface VideoPreviewSource {
@@ -826,6 +1225,11 @@ interface VideoPreviewOptions {
     context?: VideoCanvasContext | null;
     /** Called after each frame is drawn. */
     onFrame?: (frame: VideoFrame) => void;
+    /**
+     * Puts an SVG filter (white balance in a grade) where the canvas's `filter: url(#id)` can find
+     * it. Default: a hidden `<svg>` added to `document.body`. `null` leaves white balance out.
+     */
+    defineSvgFilter?: ((id: string, markup: string) => void) | null;
 }
 /**
  * Plays a project in the browser: keeps one `<video>` or `<audio>` element per playing clip in step
@@ -843,6 +1247,8 @@ declare class VideoPreviewEngine {
     private readonly unsubscribe;
     private scheduled;
     private destroyed;
+    private filterHost;
+    private readonly filters;
     constructor(source: VideoPreviewSource, canvas: {
         width: number;
         height: number;
@@ -858,6 +1264,7 @@ declare class VideoPreviewEngine {
     private redraw;
     private sourceFor;
     private draw;
+    private readonly defineSvgFilter;
     /** Stops following the editor and releases every media element. */
     destroy(): void;
 }
@@ -872,6 +1279,11 @@ interface VideoEditorOptions {
     readOnly?: boolean;
     /** Called after every change to the project (not on playback or selection). */
     onChange?: (project: VideoProject) => void;
+    /**
+     * Where sound levels for waveforms and `get_video_audio_levels` come from: a shared cache, or a
+     * loader for one (default: fetch and decode each asset's `src` with Web Audio, in a browser).
+     */
+    audioPeaks?: VideoAudioPeaksCache | VideoAudioPeaksLoader;
 }
 /** A snapshot of the editor. The same object is returned until something changes. */
 interface VideoEditorState {
@@ -909,6 +1321,8 @@ interface VideoEditorState {
 declare class VideoEditorController {
     readonly history: HistoryManager;
     readonly player: AnimationPlayer;
+    /** Sound levels per asset, loaded on demand for waveforms and agents. */
+    readonly audioPeaks: VideoAudioPeaksCache;
     private project;
     private issues;
     private selection;
@@ -985,6 +1399,8 @@ declare class VideoEditorController {
     toSvg(time?: number, options?: VideoSvgOptions): string;
     /** The project as an ffmpeg command. */
     toFfmpeg(options?: VideoFfmpegOptions): VideoFfmpegExport;
+    /** The ffmpeg command that measures the mix's loudness (see `toVideoLoudnessMeasure`). */
+    toLoudnessMeasure(options?: Pick<VideoFfmpegOptions, 'resolve' | 'loudness'>): VideoFfmpegExport;
     /** One track as a CMX 3600 EDL. */
     toEdl(options?: VideoEdlOptions): string;
 }
@@ -1024,6 +1440,8 @@ declare function describeVideoProject(project: VideoProject): {
             speed?: number;
             volume?: VideoAnimatable;
             muted?: boolean;
+            fadeInCurve?: VideoFadeCurve;
+            fadeOutCurve?: VideoFadeCurve;
             id: string;
             name?: string;
             start: number;
@@ -1031,6 +1449,10 @@ declare function describeVideoProject(project: VideoProject): {
             opacity?: VideoAnimatable;
             transform?: VideoTransform;
             fit?: VideoFit;
+            blend?: VideoBlendMode;
+            grade?: VideoGrade;
+            animateIn?: VideoClipAnimation;
+            animateOut?: VideoClipAnimation;
             fadeIn?: number;
             fadeOut?: number;
             transition?: VideoTransition;
@@ -1054,6 +1476,10 @@ declare function describeVideoProject(project: VideoProject): {
             opacity?: VideoAnimatable;
             transform?: VideoTransform;
             fit?: VideoFit;
+            blend?: VideoBlendMode;
+            grade?: VideoGrade;
+            animateIn?: VideoClipAnimation;
+            animateOut?: VideoClipAnimation;
             fadeIn?: number;
             fadeOut?: number;
             transition?: VideoTransition;
@@ -1072,6 +1498,10 @@ declare function describeVideoProject(project: VideoProject): {
             opacity?: VideoAnimatable;
             transform?: VideoTransform;
             fit?: VideoFit;
+            blend?: VideoBlendMode;
+            grade?: VideoGrade;
+            animateIn?: VideoClipAnimation;
+            animateOut?: VideoClipAnimation;
             fadeIn?: number;
             fadeOut?: number;
             transition?: VideoTransition;
@@ -1116,6 +1546,20 @@ interface VideoRulerTick {
 /** Ruler ticks for `[0, duration]` at `pxPerSecond`: a major tick at least every ~80 px, labelled with timecode. */
 declare function videoRulerTicks(duration: number, pxPerSecond: number, fps: number): VideoRulerTick[];
 /** Fill colour a timeline uses for a clip, by what it is. */
+/** Which clips a timeline draws waveforms in: audio files only (default), anything with sound, or none. */
+type VideoWaveformMode = 'audio' | 'all' | 'none';
+/** Whether a timeline in `mode` draws a waveform in this clip. */
+declare function videoClipShowsWaveform(clip: VideoClip, asset: VideoAsset | undefined, mode?: VideoWaveformMode): asset is VideoAsset;
+/** Names for the entrance and exit animations, for menus. */
+declare const VIDEO_CLIP_ANIMATION_LABELS: Readonly<Record<VideoClipAnimationEffect, string>>;
+/** Names for the transitions, for menus. */
+declare const VIDEO_TRANSITION_LABELS: Readonly<Record<VideoTransitionType, string>>;
+/** Whether a transition type takes a `direction`. */
+declare const videoTransitionHasDirection: (type: VideoTransitionType) => boolean;
+/** Names for the blend modes, for menus. */
+declare const VIDEO_BLEND_MODE_LABELS: Readonly<Record<VideoBlendMode, string>>;
+/** Names for the sound fade curves, for menus. */
+declare const VIDEO_FADE_CURVE_LABELS: Readonly<Record<VideoFadeCurve, string>>;
 declare function videoClipTint(clip: VideoClip, asset?: VideoAsset): string;
 /** A short label for a clip on the timeline. */
 declare function videoClipLabel(clip: VideoClip, asset?: VideoAsset): string;
@@ -1211,4 +1655,4 @@ declare function videoKeyframeValueEdit(project: VideoProject, clipId: string, p
  */
 declare function videoKeyframeToggleEdit(project: VideoProject, clipId: string, property: VideoKeyframeProperty, time: number): VideoEdit | null;
 
-export { type CreateVideoProjectOptions, type NewVideoClip, VIDEO_CLIP_TYPES, VIDEO_DEFAULT_STILL_DURATION, VIDEO_DEFAULT_TITLE_DURATION, VIDEO_EASE_NAMES, VIDEO_EDIT_OPS, VIDEO_FITS, VIDEO_ISSUE_CODES, VIDEO_KEYFRAME_LIMITS, VIDEO_KEYFRAME_PROPERTIES, VIDEO_PLACEMENT_MODES, VIDEO_TIME_EPSILON, VIDEO_TRANSFORM_PROPERTIES, VIDEO_TRANSITION_TYPES, VIDEO_WIPE_DIRECTIONS, type VideoAnimatable, type VideoAsset, type VideoAssetKind, type VideoAudioSource, type VideoCanvasContext, type VideoClip, 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 VideoFfmpegExport, type VideoFfmpegOptions, type VideoFit, type VideoFrame, type VideoGap, type VideoIssue, type VideoIssueCode, type VideoIssueSeverity, type VideoKey, type VideoKeyframeProperty, type VideoKeyframeRow, type VideoKeyframes, type VideoLayer, type VideoMarker, type VideoMediaClip, type VideoMediaProbe, type VideoPlacementMode, VideoPreviewEngine, type VideoPreviewImage, type VideoPreviewMedia, type VideoPreviewOptions, type VideoPreviewSource, type VideoProject, type VideoRect, type VideoRulerTick, type VideoSnapOptions, type VideoSvgOptions, type VideoTextClip, type VideoTrack, type VideoTrackKind, type VideoTransform, type VideoTransition, type VideoTransitionType, type VideoWipeDirection, allVideoClipIds, applyVideoEdits, checkVideoProject, createVideoEditorToolProvider, createVideoProject, describeVideoProject, drawVideoFrame, ffmpegFilterValue, findVideoClip, findVideoGaps, formatVideoSeconds, formatVideoTimecode, isVideoKeyframes, nextFreeVideoSlot, parseVideoAnimatable, parseVideoAsset, parseVideoClip, parseVideoKeyframes, parseVideoMarker, parseVideoProject, parseVideoTrack, parseVideoTransform, parseVideoTransition, placeVideoRect, planVideoClipDrag, probeVideoMedia, removeVideoKey, retimeVideoAnimatable, setVideoKey, snapToVideoFrame, snapVideoTime, sortVideoKeys, sortedVideoClips, splitVideoAnimatable, toVideoEdl, toVideoFfmpeg, videoAssetDropEdit, videoAssetKindOf, videoAssetMap, videoClipAfter, videoClipBefore, videoClipEnd, videoClipHandles, videoClipKeyframes, videoClipLabel, videoClipOverhang, videoClipSourceRange, videoClipSpeed, videoClipTint, videoClipsAt, videoContactSheetSvg, videoDragLabel, videoDropTracks, videoEaseBezier, videoEaseProgress, videoFrameAt, videoFrameDuration, videoFrameToSvg, videoFrames, videoIssueKey, videoKeyframeBreakpoints, videoKeyframeFfmpegExpr, videoKeyframeRows, videoKeyframeToggleEdit, videoKeyframeValueEdit, videoKeysOf, videoOverlap, videoProjectDuration, videoProjectSvg, videoRulerTicks, videoSnapPoints, videoTextStyle, videoTitleFrame, videoTrackSyncLocked, videoTransformAt, videoValueAt, videoWipeRect };
+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_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 VideoPlacementMode, VideoPreviewEngine, type VideoPreviewImage, type VideoPreviewMedia, type VideoPreviewOptions, type VideoPreviewSource, type VideoProject, type VideoRect, type VideoRulerTick, type VideoSilenceOptions, type VideoSnapOptions, type VideoSvgOptions, type VideoTextClip, type VideoTrack, type VideoTrackKind, type VideoTransform, type VideoTransition, type VideoTransitionType, type VideoWaveformMode, type VideoWipeDirection, allVideoClipIds, applyVideoEdits, applyVideoGrade, buildVideoAudioPeaks, checkVideoProject, createVideoEditorToolProvider, createVideoProject, decodeVideoAudioPeaks, describeVideoProject, drawVideoFrame, ffmpegFilterValue, findVideoAudioSilences, findVideoClip, findVideoGaps, formatVideoSeconds, formatVideoTimecode, formatVideoTimecodeFrames, isVideoDropFrameRate, isVideoKeyframes, nextFreeVideoSlot, normalizeVideoGrade, parseVideoAnimatable, parseVideoAsset, parseVideoClip, parseVideoClipAnimation, parseVideoGrade, parseVideoKeyframes, parseVideoLoudnessMeasurement, parseVideoMarker, parseVideoProject, parseVideoTrack, 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, videoClipSpeed, videoClipTint, videoClipWaveform, videoClipWaveformPath, videoClipsAt, videoContactSheetSvg, videoDragLabel, videoDropTracks, videoEaseBezier, videoEaseProgress, videoFadeCurveGain, videoFrameAt, videoFrameDuration, videoFrameToSvg, videoFrames, videoGradeCssFilter, videoGradeFfmpegFilters, videoGradeGainsFilterId, videoGradePreset, videoGradeStepMatrix, videoGradeStepSvgValues, videoGradeSteps, videoGradeSvgDefs, videoGradeSvgFilter, videoHourFrames, videoIrisRadius, videoIssueKey, videoKeyframeBreakpoints, videoKeyframeFfmpegExpr, videoKeyframeRows, videoKeyframeToggleEdit, videoKeyframeValueEdit, videoKeysOf, videoOverlap, videoPeakDb, videoProjectDuration, videoProjectSvg, videoRulerTicks, videoSnapPoints, videoTextStyle, videoTimecodeFrames, videoTitleFrame, videoTrackSyncLocked, videoTransformAt, videoTransitionAudioCurve, videoTransitionEase, videoTransitionHasDirection, videoValueAt, videoWaveformPath, videoWipeRect };