@pixerate/editor 0.75.0 → 0.77.0

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

@@ -0,0 +1,1003 @@
+import { c as AnimationPlayer, C as Clock, b as AnimationLoopMode } from '../player-DrcP2xqj.cjs';
+import { H as HistoryManager } from '../HistoryManager-DeQQMBCj.cjs';
+import { A as AgentToolProvider } from '../registry-DIpIaCkH.cjs';
+import '../easing-lM0Xo9Ni.cjs';
+import '../types-DsiXGmjo.cjs';
+import '../schema-Di0CS6Pe.cjs';
+
+/**
+ * A video project is plain JSON: the media it uses (assets), tracks of clips placed on a timeline,
+ * and markers. Every time is in milliseconds; `fps` sets the frame grid edits snap to and exports use.
+ *
+ * Tracks are listed top to bottom as a timeline shows them: on screen, a clip on an earlier video
+ * track draws over one on a later track. Clips on one track never overlap.
+ */
+type VideoAssetKind = 'video' | 'audio' | 'image';
+/** A piece of source media. The project refers to it by id; `src` is whatever the host can load. */
+interface VideoAsset {
+    id: string;
+    kind: VideoAssetKind;
+    /** URL, blob URL, path or data URL (whatever the playback engine and exporter can open). */
+    src: string;
+    name?: string;
+    /** Length of the source (ms). Required for video and audio; images have none. */
+    duration?: number;
+    /** Intrinsic size in pixels (video and image). Placement assumes the project size when missing. */
+    width?: number;
+    height?: number;
+    /** Whether a video asset has sound (default true). */
+    hasAudio?: boolean;
+    /** A still to show for a video where its frames cannot be drawn (SVG renders, thumbnails). */
+    poster?: string;
+}
+type VideoTrackKind = 'video' | 'audio';
+interface VideoTrack {
+    id: string;
+    kind: VideoTrackKind;
+    name?: string;
+    /** Silences every clip on the track. */
+    muted?: boolean;
+    /** Leaves the track's pictures out of the frame. */
+    hidden?: boolean;
+    /** Refuses edits to the track's clips. */
+    locked?: boolean;
+    /** Gain applied to every clip on the track (1 = unchanged, default 1). */
+    volume?: number;
+    clips: VideoClip[];
+}
+/** Where a picture sits in the frame, after it has been fitted. */
+interface VideoTransform {
+    /** Offset of the centre from the frame's centre, in pixels (default 0). */
+    x?: number;
+    y?: number;
+    /** 1 = fitted size (default 1). */
+    scale?: number;
+    /** Degrees clockwise (default 0). */
+    rotation?: number;
+}
+/** 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"];
+type VideoWipeDirection = 'left' | 'right' | 'up' | 'down';
+declare const VIDEO_WIPE_DIRECTIONS: readonly ["left", "right", "up", "down"];
+/**
+ * A transition into a clip from the clip that ends where it starts on the same track. It plays over
+ * the cut, half before and half after, so both clips run past the cut into their handles (media
+ * beyond the out point of the one before, before the in point of this one).
+ */
+interface VideoTransition {
+    type: VideoTransitionType;
+    /** Length (ms), centred on the cut. */
+    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). */
+    direction?: VideoWipeDirection;
+}
+interface VideoClipBase {
+    id: string;
+    name?: string;
+    /** Where it starts on the timeline (ms). */
+    start: number;
+    /** How long it lasts on the timeline (ms). */
+    duration: number;
+    /** 0–1 (default 1). */
+    opacity?: number;
+    transform?: VideoTransform;
+    /** Default contain. */
+    fit?: VideoFit;
+    /** Fade in from nothing over this long (ms), pictures and sound. */
+    fadeIn?: number;
+    /** Fade out over this long (ms). */
+    fadeOut?: number;
+    /** Transition from the clip before (see `VideoTransition`). */
+    transition?: VideoTransition;
+}
+/** A stretch of an asset. */
+interface VideoMediaClip extends VideoClipBase {
+    type: 'media';
+    asset: string;
+    /** Where in the source it starts (ms, default 0). */
+    in?: number;
+    /** Playback speed (default 1): it uses `duration × speed` of the source. */
+    speed?: number;
+    /** Gain (1 = unchanged, default 1). */
+    volume?: number;
+    /** Silences this clip. */
+    muted?: boolean;
+}
+/** A title. */
+interface VideoTextClip extends VideoClipBase {
+    type: 'text';
+    text: string;
+    /** CSS colour (default white). */
+    color?: string;
+    /** Pixels (default 64). */
+    fontSize?: number;
+    /** Default sans-serif. */
+    fontFamily?: string;
+    /** Default 700. */
+    fontWeight?: number;
+    /** Box behind the text (CSS colour); none by default. */
+    background?: string;
+}
+/** A solid colour filling the frame. */
+interface VideoColorClip extends VideoClipBase {
+    type: 'color';
+    color: string;
+}
+type VideoClip = VideoMediaClip | VideoTextClip | VideoColorClip;
+type VideoClipType = VideoClip['type'];
+declare const VIDEO_CLIP_TYPES: readonly ["media", "text", "color"];
+interface VideoMarker {
+    id: string;
+    time: number;
+    label?: string;
+    /** CSS colour. */
+    color?: string;
+}
+interface VideoProject {
+    version: 1;
+    name?: string;
+    /** Frame size in pixels. */
+    width: number;
+    height: number;
+    /** Frames per second: the grid edits snap to and exports use. */
+    fps: number;
+    /** What shows where no clip covers the frame (default black). */
+    background?: string;
+    assets: VideoAsset[];
+    tracks: VideoTrack[];
+    markers?: VideoMarker[];
+}
+
+declare function parseVideoTransform(v: unknown, path: string): VideoTransform | 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;
+declare function parseVideoTrack(v: unknown, path?: string): VideoTrack;
+declare function parseVideoMarker(v: unknown, path?: string): VideoMarker;
+/**
+ * Reads a project from JSON text or an object, checking every field. Throws an error naming the
+ * first bad field (`tracks[0].clips[2].duration must be greater than 0.`). Ids must be unique
+ * within assets, tracks, clips and markers. Overlaps and missing media are left to
+ * `checkVideoProject`, so a project with problems can still be opened and fixed.
+ */
+declare function parseVideoProject(input: unknown): VideoProject;
+interface CreateVideoProjectOptions {
+    name?: string;
+    /** Default 1920. */
+    width?: number;
+    /** Default 1080. */
+    height?: number;
+    /** Default 30. */
+    fps?: number;
+    background?: string;
+}
+/** An empty project with one video track (`v1`) and one audio track (`a1`). */
+declare function createVideoProject(options?: CreateVideoProjectOptions): VideoProject;
+
+/** Clip edges closer than this (ms) count as touching: a cut, not a gap. */
+declare const VIDEO_TIME_EPSILON = 0.5;
+declare const videoClipEnd: (clip: VideoClip) => number;
+/** Playback speed of a clip (1 for titles and colours). */
+declare const videoClipSpeed: (clip: VideoClip) => number;
+/** The stretch of source a media clip plays (ms), or `null` for titles and colours. */
+declare function videoClipSourceRange(clip: VideoClip): {
+    in: number;
+    out: number;
+} | null;
+/** Length of one frame (ms). */
+declare const videoFrameDuration: (fps: number) => number;
+/** `time` moved to the nearest frame boundary. */
+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;
+/** Readable time for messages: `2.50 s`. */
+declare const formatVideoSeconds: (time: number) => string;
+declare function videoAssetMap(project: VideoProject): Map<string, VideoAsset>;
+/** A track's clips in timeline order. */
+declare function sortedVideoClips(track: VideoTrack): VideoClip[];
+interface VideoClipLocation {
+    track: VideoTrack;
+    trackIndex: number;
+    clip: VideoClip;
+    /** Index in `track.clips`. */
+    index: number;
+}
+declare function findVideoClip(project: VideoProject, id: string): VideoClipLocation | null;
+declare function allVideoClipIds(project: VideoProject): string[];
+/** Total length: the end of the last clip (ms). */
+declare function videoProjectDuration(project: VideoProject): number;
+/** The clip that ends where `clip` starts on its track (a cut), if any. */
+declare function videoClipBefore(track: VideoTrack, clip: VideoClip): VideoClip | null;
+/** The clip that starts where `clip` ends on its track (a cut), if any. */
+declare function videoClipAfter(track: VideoTrack, clip: VideoClip): VideoClip | null;
+/**
+ * Timeline time (ms) a clip can run past its edges into source media: before its in point
+ * (`before`) and after its out point (`after`). Unlimited for stills, titles, colours and media
+ * whose length is unknown.
+ */
+declare function videoClipHandles(clip: VideoClip, assets: Map<string, VideoAsset>): {
+    before: number;
+    after: number;
+};
+/**
+ * How far a clip plays past each edge because of transitions: `lead` before its start (its own
+ * transition in) and `tail` after its end (the next clip's transition in). Dips need neither.
+ */
+declare function videoClipOverhang(track: VideoTrack, clip: VideoClip): {
+    lead: number;
+    tail: number;
+};
+interface VideoSnapOptions {
+    /** Clip ids whose edges are not snap targets (the ones being dragged). */
+    exclude?: Iterable<string>;
+    /** Also snap to this time (usually the playhead). */
+    playhead?: number;
+}
+/** Times worth snapping to: 0, every clip edge, every marker and the playhead, ascending. */
+declare function videoSnapPoints(project: VideoProject, options?: VideoSnapOptions): number[];
+/** The snap point nearest `time` if it is within `threshold` (ms), else `time`. */
+declare function snapVideoTime(time: number, points: readonly number[], threshold: number): {
+    time: number;
+    snapped: number | null;
+};
+interface VideoGap {
+    track: string;
+    start: number;
+    end: number;
+}
+/** Empty stretches between clips (and before the first) on each track, or one track. */
+declare function findVideoGaps(project: VideoProject, trackId?: string): VideoGap[];
+/** The first clip on `track` (other than `ignore`) that overlaps `[start, end)`, if any. */
+declare function videoOverlap(track: VideoTrack, start: number, end: number, ignore?: ReadonlySet<string>): VideoClip | null;
+/** The first free stretch on `track` at or after `from` that fits `duration`. */
+declare function nextFreeVideoSlot(track: VideoTrack, from: number, duration: number, ignore?: ReadonlySet<string>): number;
+/** Clips under `time` (start inclusive, end exclusive), top track first. */
+declare function videoClipsAt(project: VideoProject, time: number): {
+    track: string;
+    clip: VideoClip;
+}[];
+
+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", "unknown-duration", "unused-asset", "marker-past-end", "empty"];
+type VideoIssueCode = (typeof VIDEO_ISSUE_CODES)[number];
+interface VideoIssue {
+    code: VideoIssueCode;
+    severity: VideoIssueSeverity;
+    /** One sentence saying what is wrong and how to fix it. */
+    message: string;
+    track?: string;
+    clip?: string;
+    asset?: string;
+    marker?: string;
+}
+/** A stable key for an issue (code and what it is about), to tell new problems from old ones. */
+declare const videoIssueKey: (i: VideoIssue) => string;
+/**
+ * Everything wrong with a project, errors first: clips pointing at missing media or sitting on the
+ * wrong kind of track, overlaps, clips running past the end of their source, transitions with no
+ * cut to play over or not enough media either side of it, and softer notes (unused assets, markers
+ * past the end). Edits never add errors (see `applyVideoEdits`), so errors only come from a loaded file.
+ */
+declare function checkVideoProject(project: VideoProject): VideoIssue[];
+
+type Settings = {
+    name?: string;
+    width?: number;
+    height?: number;
+    fps?: number;
+    background?: string;
+};
+type TrackFields = {
+    name?: string;
+    muted?: boolean;
+    hidden?: boolean;
+    locked?: boolean;
+    volume?: number;
+};
+/** A clip to add: `id` and `start` are optional (default: a fresh id, the end of the track). */
+type NewVideoClip = {
+    [K in VideoClip['type']]: Omit<Extract<VideoClip, {
+        type: K;
+    }>, 'id' | 'start' | 'duration'> & {
+        id?: string;
+        start?: number;
+        duration?: number;
+    };
+}[VideoClip['type']];
+/** One change to a project. `applyVideoEdits` applies a list of them all or nothing. */
+type VideoEdit = ({
+    op: 'set_settings';
+} & Settings) | {
+    op: 'add_asset';
+    asset: Omit<VideoAsset, 'id'> & {
+        id?: string;
+    };
+} | {
+    op: 'update_asset';
+    asset: string;
+    set?: Partial<Omit<VideoAsset, 'id'>>;
+    remove?: string[];
+} | {
+    op: 'remove_asset';
+    asset: string;
+} | {
+    op: 'add_track';
+    track: TrackFields & {
+        id?: string;
+        kind: VideoTrackKind;
+    };
+    at?: number;
+} | {
+    op: 'update_track';
+    track: string;
+    set?: TrackFields;
+    remove?: string[];
+} | {
+    op: 'remove_track';
+    track: string;
+} | {
+    op: 'move_track';
+    track: string;
+    to: number;
+} | {
+    op: 'add_clip';
+    track: string;
+    clip: NewVideoClip;
+    ripple?: boolean;
+} | {
+    op: 'move_clip';
+    clip: string;
+    start?: number;
+    track?: string;
+} | {
+    op: 'trim_clip';
+    clip: string;
+    edge: 'start' | 'end';
+    to: number;
+    ripple?: boolean;
+} | {
+    op: 'split_clip';
+    clip: string;
+    at: number;
+    id?: string;
+} | {
+    op: 'delete_clips';
+    clips: string[];
+    ripple?: boolean;
+} | {
+    op: 'update_clip';
+    clip: string;
+    set?: Record<string, unknown>;
+    remove?: string[];
+} | {
+    op: 'set_transition';
+    clip: string;
+    transition: VideoTransition | null;
+} | {
+    op: 'close_gaps';
+    track: string;
+    from?: number;
+} | {
+    op: 'add_marker';
+    marker: Omit<VideoMarker, 'id'> & {
+        id?: string;
+    };
+} | {
+    op: 'update_marker';
+    marker: string;
+    set?: Partial<Omit<VideoMarker, 'id'>>;
+    remove?: string[];
+} | {
+    op: 'remove_marker';
+    marker: string;
+} | {
+    op: 'replace_project';
+    project: VideoProject;
+};
+type VideoEditOp = VideoEdit['op'];
+declare const VIDEO_EDIT_OPS: readonly VideoEditOp[];
+/** What one op made or changed, so the next step can refer to it. */
+interface VideoEditOutcome {
+    op: VideoEditOp;
+    clip?: string;
+    clips?: string[];
+    track?: string;
+    asset?: string;
+    marker?: string;
+}
+type VideoEditResult = {
+    ok: true;
+    project: VideoProject;
+    issues: VideoIssue[];
+    outcomes: VideoEditOutcome[];
+} | {
+    ok: false;
+    error: string;
+};
+/** Default lengths (ms) for clips added without one. */
+declare const VIDEO_DEFAULT_STILL_DURATION = 5000;
+declare const VIDEO_DEFAULT_TITLE_DURATION = 3000;
+/**
+ * Applies edits in order, all or nothing: the first that fails (an unknown id, an overlap, a trim
+ * past the end of the source, a locked track) stops the lot and the project is unchanged. Edits
+ * may not add errors (`checkVideoProject`); ones already there (from a loaded file) do not block.
+ * With several edits, errors name the op (`op 2 (trim_clip): …`).
+ */
+declare function applyVideoEdits(project: VideoProject, edits: VideoEdit | readonly VideoEdit[]): VideoEditResult;
+
+/** A rectangle in frame pixels. */
+interface VideoRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** One picture in a frame, in draw order (first is at the back). */
+interface VideoLayer {
+    /** The clip it comes from, or `transition:<clip>` for a dip's colour. */
+    clip: string;
+    track: string;
+    type: VideoClip['type'];
+    /** For media: the asset, its kind and `src`, and the moment of the source to show (ms). */
+    asset?: string;
+    assetKind?: VideoAsset['kind'];
+    src?: string;
+    sourceTime?: number;
+    /** 0–1, after fades and transitions. */
+    opacity: number;
+    /** Where the fitted picture sits before rotation (its centre is the rotation centre). */
+    rect: VideoRect;
+    /** Degrees clockwise about the rect's centre. */
+    rotation: number;
+    /** For a wipe: the part shown is the `progress` (0–1) of the rect from the edge opposite `direction`. */
+    wipe?: {
+        direction: VideoWipeDirection;
+        progress: number;
+    };
+    /** For text: what to draw. */
+    text?: {
+        text: string;
+        color: string;
+        fontSize: number;
+        fontFamily: string;
+        fontWeight: number;
+        background?: string;
+    };
+    /** For colour clips and dips. */
+    color?: string;
+}
+/** One sound playing at a moment. */
+interface VideoAudioSource {
+    clip: string;
+    track: string;
+    asset: string;
+    src: string;
+    /** The moment of the source playing (ms). */
+    sourceTime: number;
+    /** Gain after clip and track volume, fades and transitions (0 = silent). */
+    gain: number;
+    speed: number;
+}
+interface VideoFrame {
+    time: number;
+    width: number;
+    height: number;
+    background: string;
+    layers: VideoLayer[];
+    audio: VideoAudioSource[];
+}
+/** Places a picture of `size` in the frame by `fit`, then the clip's transform. */
+declare function placeVideoRect(frame: {
+    width: number;
+    height: number;
+}, size: {
+    width: number;
+    height: number;
+}, fit?: VideoFit, transform?: VideoClip['transform']): VideoRect;
+/** A title's text and style with the defaults filled in. */
+declare function videoTextStyle(clip: VideoTextClip): NonNullable<VideoLayer['text']>;
+/**
+ * A frame holding only one title, fully opaque on a transparent background, placed as the preview
+ * places it: draw it with `drawVideoFrame` and save the canvas as a PNG to give the ffmpeg export
+ * titles without `drawtext` (`VideoFfmpegOptions.titleImage`). Fades and opacity are left to the export.
+ */
+declare function videoTitleFrame(project: VideoProject, clip: VideoTextClip): VideoFrame;
+/**
+ * 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
+ * project and the time, so previews, exporters and agents all agree on every frame.
+ */
+declare function videoFrameAt(project: VideoProject, time: number): VideoFrame;
+
+/** The part of a rect a wipe shows. */
+declare function videoWipeRect(rect: VideoRect, wipe: NonNullable<VideoLayer['wipe']>): VideoRect;
+interface VideoSvgOptions {
+    /**
+     * The picture for a media layer: return an href (URL or data URL) to draw, or `null` for a
+     * labelled placeholder. Default: images use `src`, videos their `poster`, else a placeholder.
+     */
+    imageFor?: (layer: VideoLayer, frame: VideoFrame) => string | null;
+    /** Frame rate for the timecode on placeholders (default 30). */
+    fps?: number;
+}
+/** 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;
+/** The project at `time` as SVG. */
+declare function videoProjectSvg(project: VideoProject, time: number, options?: VideoSvgOptions): string;
+/** Several moments in one labelled picture, `columns` a row, each frame scaled to `width` pixels. */
+declare function videoContactSheetSvg(project: VideoProject, times: readonly number[], options?: VideoSvgOptions & {
+    columns?: number;
+    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'> & {
+    globalAlpha: number;
+    fillStyle: string | CanvasGradient | CanvasPattern;
+    font: string;
+    textAlign: CanvasTextAlign;
+    textBaseline: CanvasTextBaseline;
+    strokeStyle: string | CanvasGradient | CanvasPattern;
+    lineWidth: number;
+    strokeRect(x: number, y: number, w: number, h: number): void;
+};
+/**
+ * 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.
+ */
+declare function drawVideoFrame(ctx: VideoCanvasContext, frame: VideoFrame, sourceFor: (layer: VideoLayer) => CanvasImageSource | null, scale?: number): 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). */
+    recordStart?: number;
+    /** Title line (default: the project's name). */
+    title?: string;
+}
+/**
+ * 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
+ * wipes (`W001`), `M2` lines for speed changes, and `* FROM CLIP NAME` comments. Titles and colour
+ * clips become black (`BL`) events.
+ */
+declare function toVideoEdl(project: VideoProject, options?: VideoEdlOptions): string;
+interface VideoFfmpegOptions {
+    /** Output file (default `output.mp4`). */
+    output?: string;
+    /** The path or URL ffmpeg should open for an asset (default its `src`). */
+    resolve?: (asset: VideoAsset) => string;
+    /** Default `libx264`. */
+    videoCodec?: string;
+    /** Default `aac`. */
+    audioCodec?: string;
+    /** x264 quality (default 18). */
+    crf?: number;
+    /** A font file for titles (drawtext's `fontfile`); default the system's font for the family. */
+    fontFile?: string;
+    /**
+     * Titles as images instead of `drawtext` (which needs an ffmpeg built with libfreetype; Homebrew's
+     * is not): return the path or URL of a transparent PNG the size of the frame showing the title as
+     * the preview draws it (`videoTitleFrame` + `drawVideoFrame`). It is overlaid like a still, with
+     * the title's opacity and fades.
+     */
+    titleImage?: (clip: VideoTextClip, size: {
+        width: number;
+        height: number;
+    }) => string;
+}
+interface VideoFfmpegExport {
+    /** Arguments after `ffmpeg` (pass to `spawn('ffmpeg', args)`; no shell quoting needed). */
+    args: string[];
+    /** The same as one shell command line, quoted for a POSIX shell. */
+    command: string;
+    /** The `-filter_complex` graph on its own. */
+    filterComplex: string;
+    /** Length rendered (ms). */
+    duration: number;
+    /** Anything the render only approximates. */
+    notes: string[];
+}
+/** Escapes a value for a filter option inside a filtergraph (option level, then graph level). */
+declare const ffmpegFilterValue: (s: string) => string;
+/**
+ * The project as an ffmpeg command: each clip an input trimmed to what it plays (plus transition
+ * overlap), scaled and placed as `videoFrameAt` places it, faded, and overlaid on a background in
+ * track order between its start and end; titles with `drawtext`; sound delayed into place, faded,
+ * mixed and trimmed to the project's length. Render on a server or with ffmpeg.wasm.
+ */
+declare function toVideoFfmpeg(project: VideoProject, options?: VideoFfmpegOptions): VideoFfmpegExport;
+
+/** What a preview follows: a `VideoEditorController` fits. */
+interface VideoPreviewSource {
+    getState(): {
+        project: VideoProject;
+        time: number;
+        playing: boolean;
+    };
+    subscribe(listener: () => void): () => void;
+}
+/** The parts of a media element the preview drives (so tests can pass fakes). */
+interface VideoPreviewMedia {
+    src: string;
+    currentTime: number;
+    playbackRate: number;
+    volume: number;
+    muted: boolean;
+    paused: boolean;
+    readyState: number;
+    preload: string;
+    play(): Promise<void> | void;
+    pause(): void;
+    addEventListener(type: string, listener: () => void): void;
+    removeEventListener(type: string, listener: () => void): void;
+    removeAttribute?(name: string): void;
+    load?(): void;
+}
+interface VideoPreviewImage {
+    src: string;
+    complete: boolean;
+    addEventListener(type: string, listener: () => void): void;
+}
+interface VideoPreviewOptions {
+    /** Canvas pixels per frame pixel (default: fits the canvas's displayed width at the device pixel ratio, at most 1). */
+    resolution?: number;
+    /** How far (ms) a playing element may drift from the timeline before it is re-seeked (default 200). */
+    tolerance?: number;
+    /** Makes media and image elements (default `document.createElement`). */
+    createMedia?: (kind: 'video' | 'audio') => VideoPreviewMedia;
+    createImage?: () => VideoPreviewImage;
+    /** The 2D context to draw on (default `canvas.getContext('2d')`). */
+    context?: VideoCanvasContext | null;
+    /** Called after each frame is drawn. */
+    onFrame?: (frame: VideoFrame) => void;
+}
+/**
+ * Plays a project in the browser: keeps one `<video>` or `<audio>` element per playing clip in step
+ * with the timeline (seeking when it drifts, matching speed and gain, pausing with the editor), and
+ * draws each frame (`videoFrameAt` + `drawVideoFrame`) on a canvas. Framework-free: React and Svelte
+ * wrap it in `<VideoPreview>`. Elements for clips that stop playing are paused and released.
+ */
+declare class VideoPreviewEngine {
+    private readonly source;
+    private readonly options;
+    private readonly canvas;
+    private readonly ctx;
+    private readonly media;
+    private readonly images;
+    private readonly unsubscribe;
+    private scheduled;
+    private destroyed;
+    constructor(source: VideoPreviewSource, canvas: {
+        width: number;
+        height: number;
+        clientWidth?: number;
+        getContext?: (id: '2d') => unknown;
+    }, options?: VideoPreviewOptions);
+    private createMedia;
+    private image;
+    private entry;
+    private release;
+    /** Brings the media elements in step with the editor and draws the frame. */
+    update(): void;
+    private redraw;
+    private sourceFor;
+    private draw;
+    /** Stops following the editor and releases every media element. */
+    destroy(): void;
+}
+
+interface VideoEditorOptions {
+    /** The project to open (default: an empty 1920 × 1080, 30 fps project with tracks v1 and a1). */
+    project?: VideoProject;
+    /** Shared undo history (default: a new one). */
+    history?: HistoryManager;
+    /** Time source for playback (default: requestAnimationFrame). Pass a `ManualClock` to step frames. */
+    clock?: Clock;
+    readOnly?: boolean;
+    /** Called after every change to the project (not on playback or selection). */
+    onChange?: (project: VideoProject) => void;
+}
+/** A snapshot of the editor. The same object is returned until something changes. */
+interface VideoEditorState {
+    project: VideoProject;
+    /** Total length (ms): the end of the last clip. */
+    duration: number;
+    /** Playhead (ms). */
+    time: number;
+    playing: boolean;
+    loop: AnimationLoopMode;
+    /** Selected clip ids, in the order they were selected. */
+    selection: readonly string[];
+    /** Clips under the playhead, top track first. */
+    current: readonly string[];
+    /** The project's problems (see `checkVideoProject`). */
+    issues: readonly VideoIssue[];
+    readOnly: boolean;
+    /** Why the last edit was refused, if it was. */
+    error: string | null;
+    canUndo: boolean;
+    canRedo: boolean;
+    undoLabel: string;
+    redoLabel: string;
+    /** Bumped on every change. */
+    revision: number;
+}
+/**
+ * Headless non-linear video editor: a `VideoProject` of assets and tracks of clips, edited with
+ * undoable, all-or-nothing edits (insert, ripple, trim, split, move, transitions), played on an
+ * injectable clock, with a clip selection, snapping and frames at any time. UI-agnostic: React and
+ * Svelte bind it with `useVideoEditor` / `createVideoEditor`, `VideoPreviewEngine` plays it in a
+ * browser and agents drive it through `createVideoEditorToolProvider`. `getState()` returns the same
+ * object until something changes, so it works with `useSyncExternalStore` and Svelte runes.
+ */
+declare class VideoEditorController {
+    readonly history: HistoryManager;
+    readonly player: AnimationPlayer;
+    private project;
+    private issues;
+    private selection;
+    private readOnly;
+    private error;
+    private revision;
+    private applying;
+    private readonly onChange?;
+    private readonly listeners;
+    private readonly unsubscribers;
+    private state;
+    constructor(options?: VideoEditorOptions);
+    private connect;
+    /** Pauses and stops listening to the player and history. Subscribing again reconnects (React StrictMode). */
+    destroy(): void;
+    getState: () => VideoEditorState;
+    subscribe: (listener: (state: VideoEditorState) => void) => (() => void);
+    /** The current project (immutable; edit through the controller). */
+    getProject(): VideoProject;
+    private computeState;
+    private notify;
+    private setProject;
+    private commit;
+    private refuse;
+    /** Why edits are refused now, or `null` when they are allowed. */
+    readOnlyReason(): string | null;
+    /**
+     * Applies edits as one undo step, all or nothing (see `applyVideoEdits`). With `dryRun` it
+     * reports what would happen and changes nothing.
+     */
+    apply(edits: VideoEdit | readonly VideoEdit[], label?: string, options?: {
+        dryRun?: boolean;
+    }): VideoEditResult;
+    /** Opens a project (JSON or object). `clearHistory` drops the undo stack (opening a file); otherwise it is one undo step. */
+    load(project: VideoProject | string, options?: {
+        clearHistory?: boolean;
+    }): VideoEditResult;
+    setReadOnly(readOnly: boolean): void;
+    /** Selects clips (unknown ids are dropped). `add` toggles them into the current selection. */
+    select(clips: readonly string[] | null, options?: {
+        add?: boolean;
+    }): void;
+    play(): void;
+    pause(): void;
+    toggle(): void;
+    /** Moves the playhead (ms). */
+    seek(time: number): void;
+    /** Moves the playhead by whole frames (negative steps back), pausing. */
+    step(frames: number): void;
+    setLoop(loop: AnimationLoopMode): void;
+    undo(): boolean;
+    redo(): boolean;
+    /**
+     * `time` moved to the nearest clip edge, marker or the playhead within `threshold` ms (default:
+     * 8 frames), else to the nearest frame. Clips in `exclude` (the ones being dragged) are ignored.
+     */
+    snap(time: number, options?: {
+        exclude?: Iterable<string>;
+        threshold?: number;
+        playhead?: boolean;
+    }): {
+        time: number;
+        snapped: number | null;
+    };
+    /** Splits the selected clips (or every clip) under the playhead there, as one undo step. */
+    splitAtPlayhead(): VideoEditResult;
+    /** Deletes the selected clips; `ripple` closes the gaps they leave. */
+    deleteSelection(options?: {
+        ripple?: boolean;
+    }): VideoEditResult;
+    /** What plays at `time` (default: the playhead). */
+    frame(time?: number): VideoFrame;
+    /** The frame at `time` (default: the playhead) as SVG. */
+    toSvg(time?: number, options?: VideoSvgOptions): string;
+    /** The project as an ffmpeg command. */
+    toFfmpeg(options?: VideoFfmpegOptions): VideoFfmpegExport;
+    /** One track as a CMX 3600 EDL. */
+    toEdl(options?: VideoEdlOptions): string;
+}
+
+interface VideoEditorToolProviderOptions {
+    /** Provider id (unique per registry). Default `video`. */
+    id?: string;
+    /** Always prefix tool names with `<namespace>__`. */
+    namespace?: string;
+    /** The project cannot be edited: write tools are hidden and `get_video_project` says why. A string is the reason. */
+    readOnly?: boolean | string | (() => boolean | string);
+    /** Turns SVG into PNG (e.g. `rasterizeSvg`), so `render_video_frame` can return an image. */
+    rasterize?: (svg: string, size: {
+        width: number;
+        height: number;
+    }) => Promise<{
+        data: string;
+        mimeType: string;
+    }> | {
+        data: string;
+        mimeType: string;
+    };
+}
+/** A project as agents see it: settings, assets, and each track's clips in order with their times. */
+declare function describeVideoProject(project: VideoProject): {
+    assets: VideoAsset[];
+    tracks: {
+        clips: ({
+            source?: {
+                in: number;
+                out: number;
+            } | null | undefined;
+            end: number;
+            type: "media";
+            asset: string;
+            in?: number;
+            speed?: number;
+            volume?: number;
+            muted?: boolean;
+            id: string;
+            name?: string;
+            start: number;
+            duration: number;
+            opacity?: number;
+            transform?: VideoTransform;
+            fit?: VideoFit;
+            fadeIn?: number;
+            fadeOut?: number;
+            transition?: VideoTransition;
+        } | {
+            source?: {
+                in: number;
+                out: number;
+            } | null | undefined;
+            end: number;
+            type: "text";
+            text: string;
+            color?: string;
+            fontSize?: number;
+            fontFamily?: string;
+            fontWeight?: number;
+            background?: string;
+            id: string;
+            name?: string;
+            start: number;
+            duration: number;
+            opacity?: number;
+            transform?: VideoTransform;
+            fit?: VideoFit;
+            fadeIn?: number;
+            fadeOut?: number;
+            transition?: VideoTransition;
+        } | {
+            source?: {
+                in: number;
+                out: number;
+            } | null | undefined;
+            end: number;
+            type: "color";
+            color: string;
+            id: string;
+            name?: string;
+            start: number;
+            duration: number;
+            opacity?: number;
+            transform?: VideoTransform;
+            fit?: VideoFit;
+            fadeIn?: number;
+            fadeOut?: number;
+            transition?: VideoTransition;
+        })[];
+        volume?: number | undefined;
+        locked?: boolean | undefined;
+        hidden?: boolean | undefined;
+        muted?: boolean | undefined;
+        name?: string | undefined;
+        id: string;
+        kind: VideoTrackKind;
+        index: number;
+    }[];
+    markers: VideoMarker[];
+    background?: string | undefined;
+    width: number;
+    height: number;
+    fps: number;
+    duration: number;
+    name?: string | undefined;
+};
+/**
+ * Agent tools for a `VideoEditorController`: read the project (assets, tracks with clips and their
+ * times, gaps, what plays at a moment), check it, render frames, export to ffmpeg or an EDL, and
+ * edit it a step at a time (add assets and tracks, add / move / trim / split / delete clips, ripple,
+ * transitions, markers). Every write is checked first (unknown ids with "did you mean", overlaps,
+ * trims past the source, locked tracks), applies as one undo step, and returns what it made and
+ * the resulting length and issues. Write tools are hidden while the project is read-only.
+ */
+declare function createVideoEditorToolProvider(controller: VideoEditorController, options?: VideoEditorToolProviderOptions): AgentToolProvider;
+
+interface VideoRulerTick {
+    time: number;
+    /** Pixels from the timeline's left edge. */
+    x: number;
+    /** Major ticks carry a label. */
+    major: boolean;
+    label?: string;
+}
+/** 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. */
+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;
+type VideoClipDragMode = 'move' | 'trim-start' | 'trim-end';
+interface VideoClipDragInput {
+    clip: string;
+    mode: VideoClipDragMode;
+    /** How far the pointer moved along the timeline (ms). */
+    delta: number;
+    /** For move: the track under the pointer (default the clip's own). */
+    track?: string;
+    /** Push later clips along instead of refusing overlaps (trims) — hold a modifier for it. */
+    ripple?: boolean;
+    /** Snaps a time (e.g. `controller.snap(t, { exclude: [clip] }).time`); default: none. */
+    snap?: (time: number) => number;
+}
+interface VideoClipDragPlan {
+    /** Where the clip would be: draw this while dragging. */
+    start: number;
+    duration: number;
+    track: string;
+    /** The edit to apply on release (`null` when nothing changed). */
+    edit: VideoEdit | null;
+}
+/**
+ * What dragging a clip (or one of its edges) by `delta` would do: the clip's new place for drawing
+ * while the pointer moves, and the edit to apply on release. Moves snap the edge nearer a snap
+ * point; trims snap the edge being dragged. The edit is checked when it is applied, so an overlap
+ * or a trim past the source is refused then (with the reason in the editor's state).
+ */
+declare function planVideoClipDrag(project: VideoProject, input: VideoClipDragInput): VideoClipDragPlan | null;
+/** Tracks a clip may be dragged onto: the same kind as its own, unlocked. */
+declare function videoDropTracks(project: VideoProject, clipId: string): string[];
+/** The edit that adds an asset as a clip where the person dropped it (or at the end of the first fitting track). */
+declare function videoAssetDropEdit(project: VideoProject, assetId: string, options?: {
+    track?: string;
+    start?: number;
+    ripple?: boolean;
+}): VideoEdit | null;
+/** What `probeVideoMedia` found out about a file. */
+interface VideoMediaProbe {
+    kind: VideoAssetKind;
+    duration?: number;
+    width?: number;
+    height?: number;
+}
+/** The asset kind for a MIME type or file name, or `null` when it is not media. */
+declare function videoAssetKindOf(typeOrName: string): VideoAssetKind | null;
+/**
+ * Reads a media file's length and size in the browser by loading its metadata into a detached
+ * `<video>`, `<audio>` or `<img>`. Rejects with a readable error when it cannot be loaded.
+ */
+declare function probeVideoMedia(src: string, kind: VideoAssetKind, timeout?: number): Promise<VideoMediaProbe>;
+
+export { type CreateVideoProjectOptions, type NewVideoClip, VIDEO_CLIP_TYPES, VIDEO_DEFAULT_STILL_DURATION, VIDEO_DEFAULT_TITLE_DURATION, VIDEO_EDIT_OPS, VIDEO_FITS, VIDEO_ISSUE_CODES, VIDEO_TIME_EPSILON, VIDEO_TRANSITION_TYPES, VIDEO_WIPE_DIRECTIONS, type VideoAsset, type VideoAssetKind, type VideoAudioSource, type VideoCanvasContext, type VideoClip, type VideoClipDragInput, type VideoClipDragMode, type VideoClipDragPlan, type VideoClipLocation, type VideoClipType, type VideoColorClip, 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 VideoLayer, type VideoMarker, type VideoMediaClip, type VideoMediaProbe, 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, nextFreeVideoSlot, parseVideoAsset, parseVideoClip, parseVideoMarker, parseVideoProject, parseVideoTrack, parseVideoTransform, parseVideoTransition, placeVideoRect, planVideoClipDrag, probeVideoMedia, snapToVideoFrame, snapVideoTime, sortedVideoClips, toVideoEdl, toVideoFfmpeg, videoAssetDropEdit, videoAssetKindOf, videoAssetMap, videoClipAfter, videoClipBefore, videoClipEnd, videoClipHandles, videoClipLabel, videoClipOverhang, videoClipSourceRange, videoClipSpeed, videoClipTint, videoClipsAt, videoContactSheetSvg, videoDropTracks, videoFrameAt, videoFrameDuration, videoFrameToSvg, videoFrames, videoIssueKey, videoOverlap, videoProjectDuration, videoProjectSvg, videoRulerTicks, videoSnapPoints, videoTextStyle, videoTitleFrame, videoWipeRect };