@pixerate/editor 0.91.0 → 0.92.0

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

@@ -330,7 +330,28 @@ interface VideoColorClip extends VideoClipBase {
     type: 'color';
     color: string;
 }
-type VideoClip = VideoMediaClip | VideoTextClip | VideoColorClip;
+/**
+ * A compound clip: a nested sequence (see `VideoProject.sequences`) played as one picture and one
+ * sound. It plays the sequence's own time from `in`, at normal speed. Its opacity, transform, blend,
+ * grade, fades, transitions and animations apply to the sequence's composite, not to each of its
+ * clips; its volume and fades apply to the sequence's mixed sound.
+ */
+interface VideoSequenceClip extends VideoClipBase {
+    type: 'sequence';
+    /** The id of the sequence it plays (in `project.sequences`). */
+    sequence: string;
+    /** Where in the sequence's time it starts (ms, default 0). */
+    in?: number;
+    /** Gain on the sequence's sound (1 = unchanged, default 1), or keyframes. */
+    volume?: VideoAnimatable;
+    /** Silences the sequence's sound. */
+    muted?: boolean;
+    /** Shape of the sound's fade in (default linear). */
+    fadeInCurve?: VideoFadeCurve;
+    /** Shape of the sound's fade out (default linear). */
+    fadeOutCurve?: VideoFadeCurve;
+}
+type VideoClip = VideoMediaClip | VideoTextClip | VideoColorClip | VideoSequenceClip;
 type VideoClipType = VideoClip['type'];
 /**
  * How a clip is placed where others already are: `refuse` an overlap (the default), `overwrite`
@@ -339,7 +360,7 @@ type VideoClipType = VideoClip['type'];
  */
 type VideoPlacementMode = 'refuse' | 'overwrite' | 'insert';
 declare const VIDEO_PLACEMENT_MODES: readonly ["refuse", "overwrite", "insert"];
-declare const VIDEO_CLIP_TYPES: readonly ["media", "text", "color"];
+declare const VIDEO_CLIP_TYPES: readonly ["media", "text", "color", "sequence"];
 interface VideoMarker {
     id: string;
     time: number;
@@ -347,6 +368,17 @@ interface VideoMarker {
     /** CSS colour. */
     color?: string;
 }
+/**
+ * A nested sequence: tracks of clips with their own timeline from 0, played inside the project by
+ * compound clips (`type: 'sequence'`). Its frame is the project's frame size, transparent where no
+ * clip covers it. A sequence may hold compound clips of other sequences, but never itself (directly
+ * or through others).
+ */
+interface VideoSequence {
+    id: string;
+    name?: string;
+    tracks: VideoTrack[];
+}
 interface VideoProject {
     version: 1;
     name?: string;
@@ -359,6 +391,8 @@ interface VideoProject {
     background?: string;
     assets: VideoAsset[];
     tracks: VideoTrack[];
+    /** Nested sequences that compound clips play (see `VideoSequence`). */
+    sequences?: VideoSequence[];
     markers?: VideoMarker[];
 }
 
@@ -387,11 +421,14 @@ declare function parseVideoAsset(v: unknown, path?: string): VideoAsset;
 declare function parseVideoAssetProxies(v: unknown, path: string): VideoAssetProxy[] | undefined;
 declare function parseVideoClip(v: unknown, path?: string): VideoClip;
 declare function parseVideoTrack(v: unknown, path?: string): VideoTrack;
+/** A nested sequence `{ id, name, tracks }` (see `VideoSequence`). */
+declare function parseVideoSequence(v: unknown, path?: string): VideoSequence;
 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
+ * within assets, tracks, sequences, clips (across the project and its sequences) and markers.
+ * Overlaps, missing media and sequences, and sequences that contain themselves are left to
  * `checkVideoProject`, so a project with problems can still be opened and fixed.
  */
 declare function parseVideoProject(input: unknown): VideoProject;
@@ -415,7 +452,10 @@ declare const videoClipEnd: (clip: VideoClip) => number;
 declare const videoTrackSyncLocked: (track: VideoTrack) => boolean;
 /** 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. */
+/**
+ * The stretch of source a media clip plays (ms), or of its sequence's time a compound plays; `null`
+ * for titles and colours.
+ */
 declare function videoClipSourceRange(clip: VideoClip): {
     in: number;
     out: number;
@@ -449,6 +489,22 @@ 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>;
+declare function videoSequenceMap(project: VideoProject): Map<string, VideoSequence>;
+/** A sequence's length: the end of its last clip (ms). */
+declare function videoSequenceDuration(sequence: Pick<VideoSequence, 'tracks'>): number;
+/** The sequences a sequence's compound clips play directly (ids, in order, without repeats). */
+declare const videoSequenceChildren: (sequence: Pick<VideoSequence, "tracks">) => string[];
+/**
+ * A path of sequence ids that leads from `id` back to itself through compound clips (`[a, b, a]`),
+ * or `null` when it contains no cycle. Evaluating and exporting skip a compound that would close
+ * one, and `checkVideoProject` reports it.
+ */
+declare function findVideoSequenceCycle(project: VideoProject, id: string): string[] | null;
+/** Every track with its sequence (`undefined` for the project's own), the project's first. */
+declare function allVideoTracks(project: VideoProject): {
+    sequence?: string;
+    track: VideoTrack;
+}[];
 /** A track's clips in timeline order. */
 declare function sortedVideoClips(track: VideoTrack): VideoClip[];
 interface VideoClipLocation {
@@ -459,7 +515,14 @@ interface VideoClipLocation {
     index: number;
 }
 declare function findVideoClip(project: VideoProject, id: string): VideoClipLocation | null;
+/** Every clip id in the project, its sequences' clips included (ids are unique across them). */
 declare function allVideoClipIds(project: VideoProject): string[];
+/** The sequence a clip inside a sequence belongs to, with its track; `null` for clips of the project's own tracks (or no clip). */
+declare function findVideoSequenceClip(project: VideoProject, id: string): {
+    sequence: VideoSequence;
+    track: VideoTrack;
+    clip: VideoClip;
+} | null;
 /** 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. */
@@ -469,9 +532,10 @@ declare function videoClipAfter(track: VideoTrack, clip: VideoClip): VideoClip |
 /**
  * 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.
+ * whose length is unknown. A compound's handles are its sequence's time before `in` and after its
+ * out point (pass `sequences`; without them they count as unlimited).
  */
-declare function videoClipHandles(clip: VideoClip, assets: Map<string, VideoAsset>): {
+declare function videoClipHandles(clip: VideoClip, assets: Map<string, VideoAsset>, sequences?: Map<string, VideoSequence>): {
     before: number;
     after: number;
 };
@@ -519,13 +583,15 @@ 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", "animations-too-long", "animation-keyed", "keyframes-outside-clip", "unknown-duration", "unused-asset", "marker-past-end", "empty"];
+declare const VIDEO_ISSUE_CODES: readonly ["missing-asset", "missing-sequence", "sequence-cycle", "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", "unused-sequence", "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;
+    /** The sequence whose track it is about (absent for the project's own tracks). */
+    sequence?: string;
     track?: string;
     clip?: string;
     asset?: string;
@@ -537,7 +603,8 @@ 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.
+ * past the end). Sequences' tracks are checked the same way, and compound clips must play a
+ * sequence that exists, does not contain itself and is long enough. Edits never add errors (see `applyVideoEdits`), so errors only come from a loaded file.
  */
 declare function checkVideoProject(project: VideoProject): VideoIssue[];
 
@@ -754,15 +821,29 @@ interface VideoRect {
 }
 /** 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. */
+    /**
+     * The clip it comes from, or `transition:<clip>` for a dip's colour. Inside a compound clip it is
+     * the path of clip ids from the project's own track (`compound/inner`), so the same sequence
+     * played twice gives distinct layers.
+     */
     clip: string;
+    /** The track it is on (inside a compound: the sequence's track). */
     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;
+    /** For media: the moment of the source to show (ms); for a compound: the moment of its sequence. */
     sourceTime?: number;
+    /** For a compound: the sequence it plays. */
+    sequence?: string;
+    /**
+     * For a compound: the sequence's frame at `sourceTime`, back to front in the sequence's own frame
+     * (the project's size, transparent where nothing covers it). They are drawn together as one
+     * picture, which this layer's rect, rotation, opacity, blend, grade, wipe and iris then apply to.
+     */
+    layers?: VideoLayer[];
     /** 0–1, after fades and transitions. */
     opacity: number;
     /** Where the fitted picture sits before rotation (its centre is the rotation centre). */
@@ -796,13 +877,15 @@ interface VideoLayer {
 }
 /** One sound playing at a moment. */
 interface VideoAudioSource {
+    /** The clip it comes from (inside a compound: the path of clip ids, `compound/inner`). */
     clip: string;
+    /** The track it is on (inside a compound: the sequence's track). */
     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 after clip and track volume, fades and transitions, and those of any compound it plays in (0 = silent). */
     gain: number;
     speed: number;
 }
@@ -844,16 +927,23 @@ 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
+ * A media or compound 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
- * project and the time, so previews, exporters and agents all agree on every frame.
+ * project and the time, so previews, exporters and agents all agree on every frame. A compound
+ * clip is one layer holding its sequence's frame (`layers`), and its sounds are mixed in with the
+ * compound's volume, fades and transitions.
  */
 declare function videoFrameAt(project: VideoProject, time: number): VideoFrame;
+/**
+ * Every layer of a frame that draws a picture of its own, compounds opened up (each compound's
+ * layers in place of it), back to front. Hosts use it to find the media a frame needs.
+ */
+declare function videoFrameLeafLayers(layers: readonly VideoLayer[]): VideoLayer[];
 
 /**
  * Sound levels of a piece of audio, small enough to keep for every asset: a pyramid of min / max
@@ -1549,7 +1639,11 @@ interface VideoSvgOptions {
     /** 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. */
+/**
+ * A frame as standalone SVG: images and posters as `<image>`, video without one as a labelled box.
+ * A compound clip is a `<g>` (isolated, so blends inside it mix only with its own layers) holding
+ * its sequence's layers scaled into its rect, with its opacity, blend, grade filter and clips on it.
+ */
 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;
@@ -1571,7 +1665,10 @@ 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. */
+/**
+ * An offscreen canvas `drawVideoFrame` draws on: a compound clip's layers before laying them on the
+ * frame as one picture, or a LUT-graded layer before running its pixels through the LUT.
+ */
 interface VideoScratchCanvas {
     canvas: CanvasImageSource;
     ctx: VideoCanvasContext & Pick<CanvasRenderingContext2D, 'getImageData' | 'putImageData' | 'clearRect'>;
@@ -1581,8 +1678,13 @@ interface VideoDrawOptions {
     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;
+    /**
+     * An offscreen canvas of the given canvas-pixel size, for compound clips and LUT layers; `slot`
+     * numbers the ones in use at once (a compound inside a compound needs its own), so return the
+     * same canvas for the same slot and a different one for each slot. Without it LUTs are left out
+     * and a compound's layers are drawn straight onto the frame, without its opacity, blend and grade.
+     */
+    scratch?: (width: number, height: number, slot: number) => VideoScratchCanvas | null;
 }
 /**
  * Draws a frame on a 2D canvas scaled by `scale` (canvas pixels per frame pixel). `sourceFor`
@@ -1591,7 +1693,8 @@ interface VideoDrawOptions {
  * 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). 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.
+ * the result is laid on the frame with the layer's opacity and blend. A compound clip's layers are
+ * drawn on a scratch canvas of their own (transparent), which is then drawn like a picture.
  */
 declare function drawVideoFrame(ctx: VideoCanvasContext, frame: VideoFrame, sourceFor: (layer: VideoLayer) => CanvasImageSource | null, scale?: number, options?: VideoDrawOptions): void;
 
@@ -1608,8 +1711,8 @@ interface VideoEdlOptions {
 /**
  * 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 (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.
+ * wipes (`W001`), `M2` lines for speed changes, and `* FROM CLIP NAME` comments. Titles, colour
+ * clips and compound clips (not flattened yet) become black (`BL`) events.
  */
 declare function toVideoEdl(project: VideoProject, options?: VideoEdlOptions): string;
 interface VideoFfmpegOptions {
@@ -2005,10 +2108,11 @@ interface VideoPreviewOptions {
     /** 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.
+     * Makes an offscreen canvas compound clips and LUT-graded layers are drawn on (default: a
+     * `<canvas>` with `willReadFrequently`), once per `slot` (see `VideoDrawOptions.scratch`). LUTs
+     * run on the CPU, so a lower `resolution` keeps playback smooth.
      */
-    createScratch?: (width: number, height: number) => VideoScratchCanvas | null;
+    createScratch?: (width: number, height: number, slot: number) => VideoScratchCanvas | null;
 }
 /**
  * Plays a project in the browser: keeps one `<video>` or `<audio>` element per playing clip in step
@@ -2039,7 +2143,7 @@ declare class VideoPreviewEngine {
     private playing;
     private fps;
     private readonly unsubscribeLuts;
-    private scratchCanvas;
+    private readonly scratchCanvases;
     constructor(source: VideoPreviewSource, canvas: {
         width: number;
         height: number;
@@ -2254,8 +2358,320 @@ interface VideoEditorToolProviderOptions {
     /** How long `get_video_scopes` waits for the preview to finish drawing a frame (ms, default 5000). */
     framePixelsTimeout?: number;
 }
-/** A project as agents see it: settings, assets, and each track's clips in order with their times. */
+/** A sequence as agents see it: its length, the sequences it nests, who plays it, and (with `tracks`) its tracks and clips. */
+declare function describeVideoSequence(project: VideoProject, sequence: VideoSequence, tracks?: boolean): {
+    tracks: {
+        clips: ({
+            source?: {
+                in: number;
+                out: number;
+            } | null | undefined;
+            end: number;
+            type: "media";
+            asset: string;
+            in?: number;
+            speed?: number;
+            timeRemap?: VideoKeyframes;
+            volume?: VideoAnimatable;
+            muted?: boolean;
+            fadeInCurve?: VideoFadeCurve;
+            fadeOutCurve?: VideoFadeCurve;
+            id: string;
+            name?: string;
+            start: number;
+            duration: number;
+            opacity?: VideoAnimatable;
+            transform?: VideoTransform;
+            fit?: VideoFit;
+            blend?: VideoBlendMode;
+            grade?: VideoGrade;
+            animateIn?: VideoClipAnimation;
+            animateOut?: VideoClipAnimation;
+            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?: VideoAnimatable;
+            transform?: VideoTransform;
+            fit?: VideoFit;
+            blend?: VideoBlendMode;
+            grade?: VideoGrade;
+            animateIn?: VideoClipAnimation;
+            animateOut?: VideoClipAnimation;
+            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?: VideoAnimatable;
+            transform?: VideoTransform;
+            fit?: VideoFit;
+            blend?: VideoBlendMode;
+            grade?: VideoGrade;
+            animateIn?: VideoClipAnimation;
+            animateOut?: VideoClipAnimation;
+            fadeIn?: number;
+            fadeOut?: number;
+            transition?: VideoTransition;
+        } | {
+            source?: {
+                in: number;
+                out: number;
+            } | null | undefined;
+            end: number;
+            type: "sequence";
+            sequence: string;
+            in?: number;
+            volume?: VideoAnimatable;
+            muted?: boolean;
+            fadeInCurve?: VideoFadeCurve;
+            fadeOutCurve?: VideoFadeCurve;
+            id: string;
+            name?: string;
+            start: number;
+            duration: number;
+            opacity?: VideoAnimatable;
+            transform?: VideoTransform;
+            fit?: VideoFit;
+            blend?: VideoBlendMode;
+            grade?: VideoGrade;
+            animateIn?: VideoClipAnimation;
+            animateOut?: VideoClipAnimation;
+            fadeIn?: number;
+            fadeOut?: number;
+            transition?: VideoTransition;
+        })[];
+        volume?: number | undefined;
+        syncLocked?: boolean | undefined;
+        locked?: boolean | undefined;
+        hidden?: boolean | undefined;
+        muted?: boolean | undefined;
+        name?: string | undefined;
+        id: string;
+        kind: VideoTrackKind;
+        index: number;
+    }[];
+    cycle?: string[] | undefined;
+    duration: number;
+    clipCount: number;
+    nests: string[];
+    usedBy: {
+        track: string;
+        start: number;
+        end: number;
+        source: {
+            in: number;
+            out: number;
+        };
+        inSequence?: string | undefined;
+        clip: string;
+    }[];
+    name?: string | undefined;
+    id: string;
+} | {
+    trackCount: number;
+    cycle?: string[] | undefined;
+    duration: number;
+    clipCount: number;
+    nests: string[];
+    usedBy: {
+        track: string;
+        start: number;
+        end: number;
+        source: {
+            in: number;
+            out: number;
+        };
+        inSequence?: string | undefined;
+        clip: string;
+    }[];
+    name?: string | undefined;
+    id: string;
+};
+/** A project as agents see it: settings, assets, each track's clips in order with their times, and a summary of each sequence. */
 declare function describeVideoProject(project: VideoProject): {
+    markers: VideoMarker[];
+    sequences?: ({
+        tracks: {
+            clips: ({
+                source?: {
+                    in: number;
+                    out: number;
+                } | null | undefined;
+                end: number;
+                type: "media";
+                asset: string;
+                in?: number;
+                speed?: number;
+                timeRemap?: VideoKeyframes;
+                volume?: VideoAnimatable;
+                muted?: boolean;
+                fadeInCurve?: VideoFadeCurve;
+                fadeOutCurve?: VideoFadeCurve;
+                id: string;
+                name?: string;
+                start: number;
+                duration: number;
+                opacity?: VideoAnimatable;
+                transform?: VideoTransform;
+                fit?: VideoFit;
+                blend?: VideoBlendMode;
+                grade?: VideoGrade;
+                animateIn?: VideoClipAnimation;
+                animateOut?: VideoClipAnimation;
+                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?: VideoAnimatable;
+                transform?: VideoTransform;
+                fit?: VideoFit;
+                blend?: VideoBlendMode;
+                grade?: VideoGrade;
+                animateIn?: VideoClipAnimation;
+                animateOut?: VideoClipAnimation;
+                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?: VideoAnimatable;
+                transform?: VideoTransform;
+                fit?: VideoFit;
+                blend?: VideoBlendMode;
+                grade?: VideoGrade;
+                animateIn?: VideoClipAnimation;
+                animateOut?: VideoClipAnimation;
+                fadeIn?: number;
+                fadeOut?: number;
+                transition?: VideoTransition;
+            } | {
+                source?: {
+                    in: number;
+                    out: number;
+                } | null | undefined;
+                end: number;
+                type: "sequence";
+                sequence: string;
+                in?: number;
+                volume?: VideoAnimatable;
+                muted?: boolean;
+                fadeInCurve?: VideoFadeCurve;
+                fadeOutCurve?: VideoFadeCurve;
+                id: string;
+                name?: string;
+                start: number;
+                duration: number;
+                opacity?: VideoAnimatable;
+                transform?: VideoTransform;
+                fit?: VideoFit;
+                blend?: VideoBlendMode;
+                grade?: VideoGrade;
+                animateIn?: VideoClipAnimation;
+                animateOut?: VideoClipAnimation;
+                fadeIn?: number;
+                fadeOut?: number;
+                transition?: VideoTransition;
+            })[];
+            volume?: number | undefined;
+            syncLocked?: boolean | undefined;
+            locked?: boolean | undefined;
+            hidden?: boolean | undefined;
+            muted?: boolean | undefined;
+            name?: string | undefined;
+            id: string;
+            kind: VideoTrackKind;
+            index: number;
+        }[];
+        cycle?: string[] | undefined;
+        duration: number;
+        clipCount: number;
+        nests: string[];
+        usedBy: {
+            track: string;
+            start: number;
+            end: number;
+            source: {
+                in: number;
+                out: number;
+            };
+            inSequence?: string | undefined;
+            clip: string;
+        }[];
+        name?: string | undefined;
+        id: string;
+    } | {
+        trackCount: number;
+        cycle?: string[] | undefined;
+        duration: number;
+        clipCount: number;
+        nests: string[];
+        usedBy: {
+            track: string;
+            start: number;
+            end: number;
+            source: {
+                in: number;
+                out: number;
+            };
+            inSequence?: string | undefined;
+            clip: string;
+        }[];
+        name?: string | undefined;
+        id: string;
+    })[] | undefined;
     assets: ({
         id: string;
         kind: VideoAssetKind;
@@ -2359,6 +2775,33 @@ declare function describeVideoProject(project: VideoProject): {
             fadeIn?: number;
             fadeOut?: number;
             transition?: VideoTransition;
+        } | {
+            source?: {
+                in: number;
+                out: number;
+            } | null | undefined;
+            end: number;
+            type: "sequence";
+            sequence: string;
+            in?: number;
+            volume?: VideoAnimatable;
+            muted?: boolean;
+            fadeInCurve?: VideoFadeCurve;
+            fadeOutCurve?: VideoFadeCurve;
+            id: string;
+            name?: string;
+            start: number;
+            duration: number;
+            opacity?: VideoAnimatable;
+            transform?: VideoTransform;
+            fit?: VideoFit;
+            blend?: VideoBlendMode;
+            grade?: VideoGrade;
+            animateIn?: VideoClipAnimation;
+            animateOut?: VideoClipAnimation;
+            fadeIn?: number;
+            fadeOut?: number;
+            transition?: VideoTransition;
         })[];
         volume?: number | undefined;
         syncLocked?: boolean | undefined;
@@ -2370,7 +2813,6 @@ declare function describeVideoProject(project: VideoProject): {
         kind: VideoTrackKind;
         index: number;
     }[];
-    markers: VideoMarker[];
     background?: string | undefined;
     width: number;
     height: number;
@@ -2415,8 +2857,8 @@ 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;
+/** A short label for a clip on the timeline (pass the sequence a compound clip plays, for its name). */
+declare function videoClipLabel(clip: VideoClip, asset?: VideoAsset, sequence?: VideoSequence): string;
 type VideoClipDragMode = 'move' | 'trim-start' | 'trim-end';
 interface VideoClipDragInput {
     clip: string;
@@ -2514,4 +2956,4 @@ declare function videoKeyframeToggleEdit(project: VideoProject, clipId: string,
  */
 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_LUT_MAX_SIZE, VIDEO_PEAK_BLOCK, VIDEO_PLACEMENT_MODES, VIDEO_PREVIEW_SCALE_OPTIONS, VIDEO_PROXY_SCALES, 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 VideoAssetProxy, type VideoAudioLevel, type VideoAudioPeaks, VideoAudioPeaksCache, type VideoAudioPeaksLoader, type VideoAudioSource, type VideoBlendMode, type VideoCacheEntryInfo, type VideoCanvasContext, type VideoClip, type VideoClipAnimation, type VideoClipAnimationEffect, type VideoClipDragInput, type VideoClipDragMode, type VideoClipDragPlan, type VideoClipLocation, type VideoClipType, type VideoColorClip, type VideoDecodedFrame, 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, VideoFrameCache, type VideoFrameCacheOptions, type VideoFrameCacheStats, type VideoFrameDecoder, type VideoFrameRequest, 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 VideoPreviewScale, type VideoPreviewSnapshot, type VideoPreviewSource, type VideoProject, type VideoProxyCommand, type VideoProxyOptions, 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, createVideoElementDecoder, createVideoProject, decodeVideoAudioPeaks, describeVideoProject, drawVideoFrame, ffmpegFilterValue, findVideoAudioSilences, findVideoClip, findVideoFillers, findVideoGaps, findVideoTranscriptPauses, findVideoTranscriptText, formatVideoSeconds, formatVideoTimecode, formatVideoTimecodeFrames, isVideoDropFrameRate, isVideoKeyframes, mergeVideoRanges, nextFreeVideoSlot, normalizeVideoGrade, normalizeVideoGradeLut, normalizeVideoWord, parseVideoAnimatable, parseVideoAsset, parseVideoAssetProxies, parseVideoClip, parseVideoClipAnimation, parseVideoCubeLut, parseVideoGrade, parseVideoGradeLut, parseVideoKeyframes, parseVideoLoudnessMeasurement, parseVideoMarker, parseVideoPreviewScale, parseVideoProject, parseVideoTimeRemap, parseVideoTrack, parseVideoTranscript, parseVideoTranscriptWords, parseVideoTransform, parseVideoTransition, placeVideoRect, planVideoClipDrag, planVideoPrefetch, probeVideoMedia, readVideoScopesPanel, removeVideoKey, resolveVideoPreviewScale, retimeVideoAnimatable, setVideoKey, snapToVideoFrame, snapVideoTime, sortVideoKeys, sortedVideoClips, splitVideoAnimatable, summarizeVideoScopes, toVideoEdl, toVideoFfmpeg, toVideoLoudnessMeasure, videoAssetDropEdit, videoAssetHasSound, videoAssetKindOf, videoAssetMap, videoAssetProxy, videoAudioLevels, videoAudioPeakRange, videoAudioPeakSpans, videoAudioPeaksDuration, videoCacheEvictions, 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, videoFrameCacheKey, videoFrameDuration, videoFrameRequestsAt, 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, videoPreviewSrc, videoProjectDuration, videoProjectHasProxies, videoProjectSvg, videoProxyFfmpeg, videoProxyName, videoProxyPlan, videoRemoveRangesEdits, videoRulerTicks, videoScopeImage, videoShellQuote, videoSlowMotionRamp, videoSnapPoints, videoSourceFrame, videoSourceFrameTime, 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_PREVIEW_SCALE_OPTIONS, VIDEO_PROXY_SCALES, 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 VideoAssetProxy, type VideoAudioLevel, type VideoAudioPeaks, VideoAudioPeaksCache, type VideoAudioPeaksLoader, type VideoAudioSource, type VideoBlendMode, type VideoCacheEntryInfo, type VideoCanvasContext, type VideoClip, type VideoClipAnimation, type VideoClipAnimationEffect, type VideoClipDragInput, type VideoClipDragMode, type VideoClipDragPlan, type VideoClipLocation, type VideoClipType, type VideoColorClip, type VideoDecodedFrame, 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, VideoFrameCache, type VideoFrameCacheOptions, type VideoFrameCacheStats, type VideoFrameDecoder, type VideoFrameRequest, 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 VideoPreviewScale, type VideoPreviewSnapshot, type VideoPreviewSource, type VideoProject, type VideoProxyCommand, type VideoProxyOptions, type VideoRect, type VideoRulerTick, type VideoScopeImage, type VideoScopeKind, type VideoScopeOptions, type VideoScopeSummary, type VideoScopesPanelReading, type VideoScratchCanvas, type VideoSequence, type VideoSequenceClip, 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, allVideoTracks, applyVideoEdits, applyVideoGrade, applyVideoLut, applyVideoLutToPixels, buildVideoAudioPeaks, checkVideoProject, checkVideoTimeRemap, createVideoEditorToolProvider, createVideoElementDecoder, createVideoProject, decodeVideoAudioPeaks, describeVideoProject, describeVideoSequence, drawVideoFrame, ffmpegFilterValue, findVideoAudioSilences, findVideoClip, findVideoFillers, findVideoGaps, findVideoSequenceClip, findVideoSequenceCycle, findVideoTranscriptPauses, findVideoTranscriptText, formatVideoSeconds, formatVideoTimecode, formatVideoTimecodeFrames, isVideoDropFrameRate, isVideoKeyframes, mergeVideoRanges, nextFreeVideoSlot, normalizeVideoGrade, normalizeVideoGradeLut, normalizeVideoWord, parseVideoAnimatable, parseVideoAsset, parseVideoAssetProxies, parseVideoClip, parseVideoClipAnimation, parseVideoCubeLut, parseVideoGrade, parseVideoGradeLut, parseVideoKeyframes, parseVideoLoudnessMeasurement, parseVideoMarker, parseVideoPreviewScale, parseVideoProject, parseVideoSequence, parseVideoTimeRemap, parseVideoTrack, parseVideoTranscript, parseVideoTranscriptWords, parseVideoTransform, parseVideoTransition, placeVideoRect, planVideoClipDrag, planVideoPrefetch, probeVideoMedia, readVideoScopesPanel, removeVideoKey, resolveVideoPreviewScale, retimeVideoAnimatable, setVideoKey, snapToVideoFrame, snapVideoTime, sortVideoKeys, sortedVideoClips, splitVideoAnimatable, summarizeVideoScopes, toVideoEdl, toVideoFfmpeg, toVideoLoudnessMeasure, videoAssetDropEdit, videoAssetHasSound, videoAssetKindOf, videoAssetMap, videoAssetProxy, videoAudioLevels, videoAudioPeakRange, videoAudioPeakSpans, videoAudioPeaksDuration, videoCacheEvictions, 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, videoFrameCacheKey, videoFrameDuration, videoFrameLeafLayers, videoFrameRequestsAt, 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, videoPreviewSrc, videoProjectDuration, videoProjectHasProxies, videoProjectSvg, videoProxyFfmpeg, videoProxyName, videoProxyPlan, videoRemoveRangesEdits, videoRulerTicks, videoScopeImage, videoSequenceChildren, videoSequenceDuration, videoSequenceMap, videoShellQuote, videoSlowMotionRamp, videoSnapPoints, videoSourceFrame, videoSourceFrameTime, 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 };