@pixerate/editor 0.78.0 → 0.79.0

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

@@ -5,6 +5,84 @@ import '../easing-lM0Xo9Ni.cjs';
 import '../types-DsiXGmjo.cjs';
 import '../schema-Di0CS6Pe.cjs';
 
+/**
+ * Keyframes for a clip's opacity, volume and transform. A property is either a plain number or
+ * `{ keys }`: values at clip-relative times (ms from the clip's start), each with the easing of the
+ * segment that leaves it. Pure functions only, so previews, renders and exports agree.
+ *
+ * Easing is stored as CSS `cubic-bezier(x1, y1, x2, y2)` control points (named easings are the CSS
+ * ones), which is also what After Effects / Lottie speed-and-influence handles convert to exactly.
+ */
+/** How a segment moves from its key to the next: a named curve, `hold` (jump at the next key) or CSS cubic-bezier points. */
+type VideoEase = 'linear' | 'hold' | 'ease-in' | 'ease-out' | 'ease-in-out' | [number, number, number, number];
+declare const VIDEO_EASE_NAMES: readonly ["linear", "hold", "ease-in", "ease-out", "ease-in-out"];
+interface VideoKey {
+    /** Clip-relative time (ms from the clip's start). */
+    t: number;
+    v: number;
+    /** The segment from this key to the next (default linear). Ignored on the last key. */
+    ease?: VideoEase;
+}
+interface VideoKeyframes {
+    /** In time order, at least one. */
+    keys: VideoKey[];
+}
+/** A number, or keyframes for it. */
+type VideoAnimatable = number | VideoKeyframes;
+/** The clip properties that can be keyframed: `opacity`, `volume` (media) and the transform's fields. */
+type VideoKeyframeProperty = 'opacity' | 'volume' | 'x' | 'y' | 'scale' | 'rotation';
+declare const VIDEO_KEYFRAME_PROPERTIES: readonly ["opacity", "volume", "x", "y", "scale", "rotation"];
+declare const VIDEO_TRANSFORM_PROPERTIES: readonly ["x", "y", "scale", "rotation"];
+/** Each property's default and allowed range. */
+declare const VIDEO_KEYFRAME_LIMITS: Record<VideoKeyframeProperty, {
+    default: number;
+    min?: number;
+    max?: number;
+}>;
+declare const isVideoKeyframes: (v: unknown) => v is VideoKeyframes;
+/** The cubic-bezier points for an ease (`null` for linear and hold). */
+declare function videoEaseBezier(ease: VideoEase | undefined): [number, number, number, number] | null;
+/** How far (0–1 in, any y out) an ease has got at progress `p` (0–1) through its segment. */
+declare function videoEaseProgress(ease: VideoEase | undefined, p: number): number;
+/**
+ * A property's value at clip-relative time `clipTime` (ms): the number itself, or the keys
+ * interpolated (held before the first and after the last). `fallback` is used when it is unset.
+ */
+declare function videoValueAt(prop: VideoAnimatable | undefined, clipTime: number, fallback?: number): number;
+/** A property's keys (a plain number or unset gives none). */
+declare const videoKeysOf: (prop: VideoAnimatable | undefined) => VideoKey[];
+/** Shifts every key by `dt` ms (or scales times by `k` first); numbers pass through. */
+declare function retimeVideoAnimatable<T extends VideoAnimatable | undefined>(prop: T, dt: number, k?: number): T;
+/**
+ * Splits keyframes at clip time `at`: the keys before it (with a key added at `at`) and the keys
+ * after it, moved to start at 0 (with a key added at 0). Eased segments across the cut are split
+ * into two curves that trace the same path, so the two halves play exactly as the whole did.
+ */
+declare function splitVideoAnimatable<T extends VideoAnimatable | undefined>(prop: T, at: number): [T, T];
+/** The keys sorted by time, refusing two at the same time. */
+declare function sortVideoKeys(keys: readonly VideoKey[]): VideoKey[];
+/**
+ * Keys with one set (or replaced) at `t`: a plain value becomes keys holding it and the new one.
+ * For a keyframe toggle or "add key at playhead".
+ */
+declare function setVideoKey(prop: VideoAnimatable | undefined, key: VideoKey, fallback: number): VideoKeyframes;
+/** Keys with the one at `t` removed; the value it then holds when none are left. */
+declare function removeVideoKey(prop: VideoKeyframes, t: number): VideoAnimatable;
+/**
+ * Breakpoints `[clipTime, value]` tracing a property as straight lines: linear segments as they
+ * are, holds as steps, eased segments sampled every `step` ms (about two frames).
+ */
+declare function videoKeyframeBreakpoints(prop: VideoKeyframes, step: number): {
+    points: [number, number][];
+    holds: Set<number>;
+};
+/**
+ * An ffmpeg expression for a property, given `time`: an expression for the clip-relative time in
+ * ms (e.g. `(t*1000-1500)`). Piecewise linear `if(lt(…))` chains; eased segments are baked to
+ * breakpoints every `step` ms.
+ */
+declare function videoKeyframeFfmpegExpr(prop: VideoAnimatable | undefined, time: string, fallback: number, step: number): string;
+
 /**
  * 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.
@@ -12,6 +90,7 @@ import '../schema-Di0CS6Pe.cjs';
  * 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 {
@@ -45,15 +124,15 @@ interface VideoTrack {
     volume?: number;
     clips: VideoClip[];
 }
-/** Where a picture sits in the frame, after it has been fitted. */
+/** Where a picture sits in the frame, after it has been fitted. Each field may be keyframed. */
 interface VideoTransform {
     /** Offset of the centre from the frame's centre, in pixels (default 0). */
-    x?: number;
-    y?: number;
+    x?: VideoAnimatable;
+    y?: VideoAnimatable;
     /** 1 = fitted size (default 1). */
-    scale?: number;
+    scale?: VideoAnimatable;
     /** Degrees clockwise (default 0). */
-    rotation?: number;
+    rotation?: VideoAnimatable;
 }
 /** How a picture is fitted to the frame before its transform: like CSS `object-fit`. */
 type VideoFit = 'contain' | 'cover' | 'fill' | 'none';
@@ -83,8 +162,8 @@ interface VideoClipBase {
     start: number;
     /** How long it lasts on the timeline (ms). */
     duration: number;
-    /** 0–1 (default 1). */
-    opacity?: number;
+    /** 0–1 (default 1), or keyframes (`{ keys: [{ t, v, ease }] }`, `t` in ms from the clip's start). */
+    opacity?: VideoAnimatable;
     transform?: VideoTransform;
     /** Default contain. */
     fit?: VideoFit;
@@ -103,8 +182,8 @@ interface VideoMediaClip extends VideoClipBase {
     in?: number;
     /** Playback speed (default 1): it uses `duration × speed` of the source. */
     speed?: number;
-    /** Gain (1 = unchanged, default 1). */
-    volume?: number;
+    /** Gain (1 = unchanged, default 1), or keyframes. */
+    volume?: VideoAnimatable;
     /** Silences this clip. */
     muted?: boolean;
 }
@@ -153,6 +232,20 @@ interface VideoProject {
     markers?: VideoMarker[];
 }
 
+/**
+ * Keyframes `{ keys: [{ t, v, ease }] }`: at least one key, in strictly increasing time (clip-relative
+ * ms), each value within `range`.
+ */
+declare function parseVideoKeyframes(v: unknown, path: string, { min, max }?: {
+    min?: number;
+    max?: number;
+}): VideoKeyframes;
+/** A number within `range`, or keyframes for one. */
+declare function parseVideoAnimatable(v: unknown, path: string, range?: {
+    min?: number;
+    max?: number;
+    optional?: boolean;
+}): VideoAnimatable | undefined;
 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;
@@ -264,8 +357,13 @@ declare function videoClipsAt(project: VideoProject, time: number): {
     clip: VideoClip;
 }[];
 
+/** A clip's keyframed properties (`opacity`, `volume`, `x`…) with their keys. */
+declare function videoClipKeyframes(clip: VideoClip): {
+    property: string;
+    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", "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", "keyframes-outside-clip", "unknown-duration", "unused-asset", "marker-past-end", "empty"];
 type VideoIssueCode = (typeof VIDEO_ISSUE_CODES)[number];
 interface VideoIssue {
     code: VideoIssueCode;
@@ -380,6 +478,13 @@ type VideoEdit = ({
     op: 'set_transition';
     clip: string;
     transition: VideoTransition | null;
+}
+/** Keys for one property (in any order; clip-relative ms), or null to stop animating it and keep its value at the clip's start. */
+ | {
+    op: 'set_keyframes';
+    clip: string;
+    property: VideoKeyframeProperty;
+    keys: VideoKey[] | null;
 } | {
     op: 'close_gaps';
     track: string;
@@ -493,22 +598,31 @@ interface VideoFrame {
     layers: VideoLayer[];
     audio: VideoAudioSource[];
 }
-/** Places a picture of `size` in the frame by `fit`, then the clip's transform. */
+/** A transform's values at clip-relative time `clipTime` (ms), keyframes resolved and defaults filled in. */
+declare function videoTransformAt(transform: VideoClip['transform'], clipTime?: number): {
+    x: number;
+    y: number;
+    scale: number;
+    rotation: number;
+};
+/** Places a picture of `size` in the frame by `fit`, then the clip's transform at clip-relative `clipTime` (ms). */
 declare function placeVideoRect(frame: {
     width: number;
     height: number;
 }, size: {
     width: number;
     height: number;
-}, fit?: VideoFit, transform?: VideoClip['transform']): VideoRect;
+}, fit?: VideoFit, transform?: VideoClip['transform'], clipTime?: number): 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.
+ * A keyframed transform is placed as it is at `clipTime` (the export passes titles with keyframed
+ * transforms without them, and moves the image itself).
  */
-declare function videoTitleFrame(project: VideoProject, clip: VideoTextClip): VideoFrame;
+declare function videoTitleFrame(project: VideoProject, clip: VideoTextClip, clipTime?: number): 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
@@ -854,13 +968,13 @@ declare function describeVideoProject(project: VideoProject): {
             asset: string;
             in?: number;
             speed?: number;
-            volume?: number;
+            volume?: VideoAnimatable;
             muted?: boolean;
             id: string;
             name?: string;
             start: number;
             duration: number;
-            opacity?: number;
+            opacity?: VideoAnimatable;
             transform?: VideoTransform;
             fit?: VideoFit;
             fadeIn?: number;
@@ -883,7 +997,7 @@ declare function describeVideoProject(project: VideoProject): {
             name?: string;
             start: number;
             duration: number;
-            opacity?: number;
+            opacity?: VideoAnimatable;
             transform?: VideoTransform;
             fit?: VideoFit;
             fadeIn?: number;
@@ -901,7 +1015,7 @@ declare function describeVideoProject(project: VideoProject): {
             name?: string;
             start: number;
             duration: number;
-            opacity?: number;
+            opacity?: VideoAnimatable;
             transform?: VideoTransform;
             fit?: VideoFit;
             fadeIn?: number;
@@ -999,5 +1113,38 @@ declare function videoAssetKindOf(typeOrName: string): VideoAssetKind | null;
  * `<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>;
+/** One animatable property of a clip as an inspector shows it at the playhead. */
+interface VideoKeyframeRow {
+    property: VideoKeyframeProperty;
+    label: string;
+    /** Its value at the playhead (the playhead held inside the clip). */
+    value: number;
+    /** Whether it has keyframes. */
+    keyed: boolean;
+    /** How many keys it has. */
+    keys: number;
+    /** Whether a key sits at the playhead. */
+    onKey: boolean;
+    /** The playhead in clip time (ms), where new keys go. */
+    clipTime: number;
+    step: number;
+    min?: number;
+    max?: number;
+}
+/**
+ * The clip's animatable properties for an inspector at timeline `time`: opacity and the transform
+ * for pictures, volume for sound, each with its value there and whether it is keyed.
+ */
+declare function videoKeyframeRows(project: VideoProject, clipId: string, time: number): VideoKeyframeRow[];
+/**
+ * Typing a value in an inspector: on a keyed property it sets (or moves) the key at the playhead;
+ * otherwise it sets the plain value (`undefined` resets it).
+ */
+declare function videoKeyframeValueEdit(project: VideoProject, clipId: string, property: VideoKeyframeProperty, time: number, value: number | undefined): VideoEdit | null;
+/**
+ * The keyframe toggle: adds a key at the playhead holding the current value (the first key turns
+ * the plain value into keys), or removes the key there (the last one leaves its value plain).
+ */
+declare function videoKeyframeToggleEdit(project: VideoProject, clipId: string, property: VideoKeyframeProperty, time: number): VideoEdit | null;
 
-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 };
+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_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, 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, videoDropTracks, videoEaseBezier, videoEaseProgress, videoFrameAt, videoFrameDuration, videoFrameToSvg, videoFrames, videoIssueKey, videoKeyframeBreakpoints, videoKeyframeFfmpegExpr, videoKeyframeRows, videoKeyframeToggleEdit, videoKeyframeValueEdit, videoKeysOf, videoOverlap, videoProjectDuration, videoProjectSvg, videoRulerTicks, videoSnapPoints, videoTextStyle, videoTitleFrame, videoTransformAt, videoValueAt, videoWipeRect };

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

@@ -5,6 +5,84 @@ import '../easing-lM0Xo9Ni.js';
 import '../types-DsiXGmjo.js';
 import '../schema-Di0CS6Pe.js';
 
+/**
+ * Keyframes for a clip's opacity, volume and transform. A property is either a plain number or
+ * `{ keys }`: values at clip-relative times (ms from the clip's start), each with the easing of the
+ * segment that leaves it. Pure functions only, so previews, renders and exports agree.
+ *
+ * Easing is stored as CSS `cubic-bezier(x1, y1, x2, y2)` control points (named easings are the CSS
+ * ones), which is also what After Effects / Lottie speed-and-influence handles convert to exactly.
+ */
+/** How a segment moves from its key to the next: a named curve, `hold` (jump at the next key) or CSS cubic-bezier points. */
+type VideoEase = 'linear' | 'hold' | 'ease-in' | 'ease-out' | 'ease-in-out' | [number, number, number, number];
+declare const VIDEO_EASE_NAMES: readonly ["linear", "hold", "ease-in", "ease-out", "ease-in-out"];
+interface VideoKey {
+    /** Clip-relative time (ms from the clip's start). */
+    t: number;
+    v: number;
+    /** The segment from this key to the next (default linear). Ignored on the last key. */
+    ease?: VideoEase;
+}
+interface VideoKeyframes {
+    /** In time order, at least one. */
+    keys: VideoKey[];
+}
+/** A number, or keyframes for it. */
+type VideoAnimatable = number | VideoKeyframes;
+/** The clip properties that can be keyframed: `opacity`, `volume` (media) and the transform's fields. */
+type VideoKeyframeProperty = 'opacity' | 'volume' | 'x' | 'y' | 'scale' | 'rotation';
+declare const VIDEO_KEYFRAME_PROPERTIES: readonly ["opacity", "volume", "x", "y", "scale", "rotation"];
+declare const VIDEO_TRANSFORM_PROPERTIES: readonly ["x", "y", "scale", "rotation"];
+/** Each property's default and allowed range. */
+declare const VIDEO_KEYFRAME_LIMITS: Record<VideoKeyframeProperty, {
+    default: number;
+    min?: number;
+    max?: number;
+}>;
+declare const isVideoKeyframes: (v: unknown) => v is VideoKeyframes;
+/** The cubic-bezier points for an ease (`null` for linear and hold). */
+declare function videoEaseBezier(ease: VideoEase | undefined): [number, number, number, number] | null;
+/** How far (0–1 in, any y out) an ease has got at progress `p` (0–1) through its segment. */
+declare function videoEaseProgress(ease: VideoEase | undefined, p: number): number;
+/**
+ * A property's value at clip-relative time `clipTime` (ms): the number itself, or the keys
+ * interpolated (held before the first and after the last). `fallback` is used when it is unset.
+ */
+declare function videoValueAt(prop: VideoAnimatable | undefined, clipTime: number, fallback?: number): number;
+/** A property's keys (a plain number or unset gives none). */
+declare const videoKeysOf: (prop: VideoAnimatable | undefined) => VideoKey[];
+/** Shifts every key by `dt` ms (or scales times by `k` first); numbers pass through. */
+declare function retimeVideoAnimatable<T extends VideoAnimatable | undefined>(prop: T, dt: number, k?: number): T;
+/**
+ * Splits keyframes at clip time `at`: the keys before it (with a key added at `at`) and the keys
+ * after it, moved to start at 0 (with a key added at 0). Eased segments across the cut are split
+ * into two curves that trace the same path, so the two halves play exactly as the whole did.
+ */
+declare function splitVideoAnimatable<T extends VideoAnimatable | undefined>(prop: T, at: number): [T, T];
+/** The keys sorted by time, refusing two at the same time. */
+declare function sortVideoKeys(keys: readonly VideoKey[]): VideoKey[];
+/**
+ * Keys with one set (or replaced) at `t`: a plain value becomes keys holding it and the new one.
+ * For a keyframe toggle or "add key at playhead".
+ */
+declare function setVideoKey(prop: VideoAnimatable | undefined, key: VideoKey, fallback: number): VideoKeyframes;
+/** Keys with the one at `t` removed; the value it then holds when none are left. */
+declare function removeVideoKey(prop: VideoKeyframes, t: number): VideoAnimatable;
+/**
+ * Breakpoints `[clipTime, value]` tracing a property as straight lines: linear segments as they
+ * are, holds as steps, eased segments sampled every `step` ms (about two frames).
+ */
+declare function videoKeyframeBreakpoints(prop: VideoKeyframes, step: number): {
+    points: [number, number][];
+    holds: Set<number>;
+};
+/**
+ * An ffmpeg expression for a property, given `time`: an expression for the clip-relative time in
+ * ms (e.g. `(t*1000-1500)`). Piecewise linear `if(lt(…))` chains; eased segments are baked to
+ * breakpoints every `step` ms.
+ */
+declare function videoKeyframeFfmpegExpr(prop: VideoAnimatable | undefined, time: string, fallback: number, step: number): string;
+
 /**
  * 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.
@@ -12,6 +90,7 @@ import '../schema-Di0CS6Pe.js';
  * 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 {
@@ -45,15 +124,15 @@ interface VideoTrack {
     volume?: number;
     clips: VideoClip[];
 }
-/** Where a picture sits in the frame, after it has been fitted. */
+/** Where a picture sits in the frame, after it has been fitted. Each field may be keyframed. */
 interface VideoTransform {
     /** Offset of the centre from the frame's centre, in pixels (default 0). */
-    x?: number;
-    y?: number;
+    x?: VideoAnimatable;
+    y?: VideoAnimatable;
     /** 1 = fitted size (default 1). */
-    scale?: number;
+    scale?: VideoAnimatable;
     /** Degrees clockwise (default 0). */
-    rotation?: number;
+    rotation?: VideoAnimatable;
 }
 /** How a picture is fitted to the frame before its transform: like CSS `object-fit`. */
 type VideoFit = 'contain' | 'cover' | 'fill' | 'none';
@@ -83,8 +162,8 @@ interface VideoClipBase {
     start: number;
     /** How long it lasts on the timeline (ms). */
     duration: number;
-    /** 0–1 (default 1). */
-    opacity?: number;
+    /** 0–1 (default 1), or keyframes (`{ keys: [{ t, v, ease }] }`, `t` in ms from the clip's start). */
+    opacity?: VideoAnimatable;
     transform?: VideoTransform;
     /** Default contain. */
     fit?: VideoFit;
@@ -103,8 +182,8 @@ interface VideoMediaClip extends VideoClipBase {
     in?: number;
     /** Playback speed (default 1): it uses `duration × speed` of the source. */
     speed?: number;
-    /** Gain (1 = unchanged, default 1). */
-    volume?: number;
+    /** Gain (1 = unchanged, default 1), or keyframes. */
+    volume?: VideoAnimatable;
     /** Silences this clip. */
     muted?: boolean;
 }
@@ -153,6 +232,20 @@ interface VideoProject {
     markers?: VideoMarker[];
 }
 
+/**
+ * Keyframes `{ keys: [{ t, v, ease }] }`: at least one key, in strictly increasing time (clip-relative
+ * ms), each value within `range`.
+ */
+declare function parseVideoKeyframes(v: unknown, path: string, { min, max }?: {
+    min?: number;
+    max?: number;
+}): VideoKeyframes;
+/** A number within `range`, or keyframes for one. */
+declare function parseVideoAnimatable(v: unknown, path: string, range?: {
+    min?: number;
+    max?: number;
+    optional?: boolean;
+}): VideoAnimatable | undefined;
 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;
@@ -264,8 +357,13 @@ declare function videoClipsAt(project: VideoProject, time: number): {
     clip: VideoClip;
 }[];
 
+/** A clip's keyframed properties (`opacity`, `volume`, `x`…) with their keys. */
+declare function videoClipKeyframes(clip: VideoClip): {
+    property: string;
+    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", "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", "keyframes-outside-clip", "unknown-duration", "unused-asset", "marker-past-end", "empty"];
 type VideoIssueCode = (typeof VIDEO_ISSUE_CODES)[number];
 interface VideoIssue {
     code: VideoIssueCode;
@@ -380,6 +478,13 @@ type VideoEdit = ({
     op: 'set_transition';
     clip: string;
     transition: VideoTransition | null;
+}
+/** Keys for one property (in any order; clip-relative ms), or null to stop animating it and keep its value at the clip's start. */
+ | {
+    op: 'set_keyframes';
+    clip: string;
+    property: VideoKeyframeProperty;
+    keys: VideoKey[] | null;
 } | {
     op: 'close_gaps';
     track: string;
@@ -493,22 +598,31 @@ interface VideoFrame {
     layers: VideoLayer[];
     audio: VideoAudioSource[];
 }
-/** Places a picture of `size` in the frame by `fit`, then the clip's transform. */
+/** A transform's values at clip-relative time `clipTime` (ms), keyframes resolved and defaults filled in. */
+declare function videoTransformAt(transform: VideoClip['transform'], clipTime?: number): {
+    x: number;
+    y: number;
+    scale: number;
+    rotation: number;
+};
+/** Places a picture of `size` in the frame by `fit`, then the clip's transform at clip-relative `clipTime` (ms). */
 declare function placeVideoRect(frame: {
     width: number;
     height: number;
 }, size: {
     width: number;
     height: number;
-}, fit?: VideoFit, transform?: VideoClip['transform']): VideoRect;
+}, fit?: VideoFit, transform?: VideoClip['transform'], clipTime?: number): 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.
+ * A keyframed transform is placed as it is at `clipTime` (the export passes titles with keyframed
+ * transforms without them, and moves the image itself).
  */
-declare function videoTitleFrame(project: VideoProject, clip: VideoTextClip): VideoFrame;
+declare function videoTitleFrame(project: VideoProject, clip: VideoTextClip, clipTime?: number): 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
@@ -854,13 +968,13 @@ declare function describeVideoProject(project: VideoProject): {
             asset: string;
             in?: number;
             speed?: number;
-            volume?: number;
+            volume?: VideoAnimatable;
             muted?: boolean;
             id: string;
             name?: string;
             start: number;
             duration: number;
-            opacity?: number;
+            opacity?: VideoAnimatable;
             transform?: VideoTransform;
             fit?: VideoFit;
             fadeIn?: number;
@@ -883,7 +997,7 @@ declare function describeVideoProject(project: VideoProject): {
             name?: string;
             start: number;
             duration: number;
-            opacity?: number;
+            opacity?: VideoAnimatable;
             transform?: VideoTransform;
             fit?: VideoFit;
             fadeIn?: number;
@@ -901,7 +1015,7 @@ declare function describeVideoProject(project: VideoProject): {
             name?: string;
             start: number;
             duration: number;
-            opacity?: number;
+            opacity?: VideoAnimatable;
             transform?: VideoTransform;
             fit?: VideoFit;
             fadeIn?: number;
@@ -999,5 +1113,38 @@ declare function videoAssetKindOf(typeOrName: string): VideoAssetKind | null;
  * `<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>;
+/** One animatable property of a clip as an inspector shows it at the playhead. */
+interface VideoKeyframeRow {
+    property: VideoKeyframeProperty;
+    label: string;
+    /** Its value at the playhead (the playhead held inside the clip). */
+    value: number;
+    /** Whether it has keyframes. */
+    keyed: boolean;
+    /** How many keys it has. */
+    keys: number;
+    /** Whether a key sits at the playhead. */
+    onKey: boolean;
+    /** The playhead in clip time (ms), where new keys go. */
+    clipTime: number;
+    step: number;
+    min?: number;
+    max?: number;
+}
+/**
+ * The clip's animatable properties for an inspector at timeline `time`: opacity and the transform
+ * for pictures, volume for sound, each with its value there and whether it is keyed.
+ */
+declare function videoKeyframeRows(project: VideoProject, clipId: string, time: number): VideoKeyframeRow[];
+/**
+ * Typing a value in an inspector: on a keyed property it sets (or moves) the key at the playhead;
+ * otherwise it sets the plain value (`undefined` resets it).
+ */
+declare function videoKeyframeValueEdit(project: VideoProject, clipId: string, property: VideoKeyframeProperty, time: number, value: number | undefined): VideoEdit | null;
+/**
+ * The keyframe toggle: adds a key at the playhead holding the current value (the first key turns
+ * the plain value into keys), or removes the key there (the last one leaves its value plain).
+ */
+declare function videoKeyframeToggleEdit(project: VideoProject, clipId: string, property: VideoKeyframeProperty, time: number): VideoEdit | null;
 
-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 };
+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_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, 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, videoDropTracks, videoEaseBezier, videoEaseProgress, videoFrameAt, videoFrameDuration, videoFrameToSvg, videoFrames, videoIssueKey, videoKeyframeBreakpoints, videoKeyframeFfmpegExpr, videoKeyframeRows, videoKeyframeToggleEdit, videoKeyframeValueEdit, videoKeysOf, videoOverlap, videoProjectDuration, videoProjectSvg, videoRulerTicks, videoSnapPoints, videoTextStyle, videoTitleFrame, videoTransformAt, videoValueAt, videoWipeRect };