@pixerate/editor 0.123.0 → 0.124.0

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

@@ -1,11 +1,19 @@
-import { V as VideoProject, a as VideoAnimatable, b as VideoAsset, c as VideoAssetProxy, d as VideoClip, e as VideoClipAnimation, f as VideoGrade, g as VideoGradeLut, h as VideoKeyframes, i as VideoMarker, j as VideoSequence, k as VideoTrack, l as VideoTranscriptWord, m as VideoTransform, n as VideoTransition, v as videoKeysOf, o as VideoTrackKind, p as VideoPlacementMode, q as VideoKeyframeProperty, r as VideoKey, s as VideoWipeDirection, t as VideoBlendMode, u as VideoFit, w as VideoFadeCurve, x as VideoTextClip, y as VideoMediaClip, z as VideoFfmpegOptions, A as VideoFfmpegExport, B as VideoEdlOptions, C as VideoAssetKind, D as VideoClipAnimationEffect, E as VideoTransitionType } from '../export-Dv0-ZVrV.cjs';
-export { F as VIDEO_BLEND_MODES, G as VIDEO_CLIP_ANIMATION_EFFECTS, H as VIDEO_CLIP_TYPES, I as VIDEO_EASE_NAMES, J as VIDEO_FADE_CURVES, K as VIDEO_FITS, L as VIDEO_KEYFRAME_LIMITS, M as VIDEO_KEYFRAME_PROPERTIES, N as VIDEO_PLACEMENT_MODES, O as VIDEO_TRANSFORM_PROPERTIES, P as VIDEO_TRANSITION_TYPES, Q as VIDEO_WIPE_DIRECTIONS, R as VideoClipType, S as VideoColorClip, T as VideoEase, U as VideoLoudnessMeasurement, W as VideoLoudnessTarget, X as VideoSequenceClip, Y as ffmpegFilterValue, Z as isVideoKeyframes, _ as parseVideoLoudnessMeasurement, $ as removeVideoKey, a0 as retimeVideoAnimatable, a1 as setVideoKey, a2 as sortVideoKeys, a3 as splitVideoAnimatable, a4 as toVideoEdl, a5 as toVideoFfmpeg, a6 as toVideoLoudnessMeasure, a7 as videoEaseBezier, a8 as videoEaseProgress, a9 as videoKeyframeBreakpoints, aa as videoKeyframeFfmpegExpr, ab as videoShellQuote, ac as videoTransitionAudioCurve, ad as videoValueAt } from '../export-Dv0-ZVrV.cjs';
-import { c as AnimationPlayer, C as Clock, b as AnimationLoopMode } from '../player-DrcP2xqj.cjs';
+import { V as VideoProject, a as VideoAnimatable, b as VideoAsset, c as VideoAssetProxy, d as VideoClip, e as VideoClipAnimation, f as VideoClipEffect, g as VideoEffectRef, h as VideoEffectValues, i as VideoGrade, j as VideoGradeLut, k as VideoKeyframes, l as VideoMarker, m as VideoSequence, n as VideoTrack, o as VideoTranscriptWord, p as VideoTransform, q as VideoTransition, v as videoKeysOf, r as VideoTrackKind, s as VideoPlacementMode, t as VideoKeyframeProperty, u as VideoKey, w as VideoMediaClip, x as VideoEffectsEngine, y as VideoLayer, z as VideoFrame, A as VideoRect, B as VideoEffectPlace, C as VideoFfmpegOptions, D as VideoFfmpegExport, E as VideoEdlOptions, F as VideoFadeCurve, G as VideoFit, H as VideoBlendMode, I as VideoAssetKind, J as VideoClipAnimationEffect, K as VideoTransitionType } from '../export-BzSRXyH6.cjs';
+export { L as VIDEO_BLEND_MODES, M as VIDEO_CLIP_ANIMATION_EFFECTS, N as VIDEO_CLIP_TYPES, O as VIDEO_EASE_NAMES, P as VIDEO_EFFECT_PLACES, Q as VIDEO_FADE_CURVES, R as VIDEO_FITS, S as VIDEO_KEYFRAME_LIMITS, T as VIDEO_KEYFRAME_PROPERTIES, U as VIDEO_PLACEMENT_MODES, W as VIDEO_TRANSFORM_PROPERTIES, X as VIDEO_TRANSITION_TYPES, Y as VIDEO_WIPE_DIRECTIONS, Z as VideoAudioSource, _ as VideoClipType, $ as VideoColorClip, a0 as VideoEase, a1 as VideoEffectClip, a2 as VideoEffectJob, a3 as VideoEffectUse, a4 as VideoEffectsEngineOptions, a5 as VideoLayerEffect, a6 as VideoLoudnessMeasurement, a7 as VideoLoudnessTarget, a8 as VideoSequenceClip, a9 as VideoTextClip, aa as VideoWipeDirection, ab as checkVideoEffectPlace, ac as checkVideoEffectValues, ad as ffmpegFilterValue, ae as isVideoKeyframes, af as mixEffectPixels, ag as overEffectPixels, ah as parseVideoLoudnessMeasurement, ai as placeVideoRect, aj as removeVideoKey, ak as retimeVideoAnimatable, al as setVideoKey, am as sortVideoKeys, an as splitVideoAnimatable, ao as toVideoEdl, ap as toVideoFfmpeg, aq as toVideoLoudnessMeasure, ar as videoClipEffectUses, as as videoClipSoundGain, at as videoEaseBezier, au as videoEaseProgress, av as videoEffectFrameTime, aw as videoEffectLayerKey, ax as videoEffectValuesAt, ay as videoFadeCurveGain, az as videoFfmpegUnsupportedEffects, aA as videoFrameAt, aB as videoFrameLeafLayers, aC as videoKeyframeBreakpoints, aD as videoKeyframeFfmpegExpr, aE as videoLayersUseEffects, aF as videoLayersWithoutTransitionEffects, aG as videoProjectEffects, aH as videoShellQuote, aI as videoTextStyle, aJ as videoTitleFrame, aK as videoTransformAt, aL as videoTransitionAudioCurve, aM as videoTransitionEase, aN as videoValueAt } from '../export-BzSRXyH6.cjs';
+import { A as AnimationPlayer, C as Clock } from '../player-CBtEoU2x.cjs';
+import { b as AnimationLoopMode } from '../evaluate-2S3vSPLy.cjs';
 import { H as HistoryManager } from '../HistoryManager-DeQQMBCj.cjs';
+import { v as EffectsSlot, E as EffectProvider, e as EffectDescription, d as EffectValue } from '../helpers-777mC6dc.cjs';
 import { a as AgentToolProvider } from '../registry-BqA1AZt0.cjs';
+import { A as AppliedEffectInfo } from '../tools-DHKGHiSK.cjs';
 import '../easing-lM0Xo9Ni.cjs';
 import '../types-DsiXGmjo.cjs';
 import '../schema-Di0CS6Pe.cjs';
+import '../flair-D7BxyBwL.cjs';
+import '../behavior-Ymbld6jL.cjs';
+import '../types-CznabG7m.cjs';
+import '../gradient-KDfCvhuj.cjs';
+import '../types-CwMPoRMU.cjs';
 
 /**
  * Keyframes `{ keys: [{ t, v, ease }] }`: at least one key, in strictly increasing time (clip-relative
@@ -27,6 +35,16 @@ declare function parseVideoClipAnimation(v: unknown, path: string): VideoClipAni
 declare function parseVideoGrade(v: unknown, path: string): VideoGrade | undefined;
 declare function parseVideoGradeLut(v: unknown, path: string): VideoGradeLut | undefined;
 declare function parseVideoTransition(v: unknown, path: string): VideoTransition | undefined;
+/**
+ * Effect control values: plain values (numbers, strings, switches, number lists) or, when
+ * `keyframes` is allowed, keyframes for numbers. Only their shape is checked here; the effect's
+ * control schema needs the provider (`resolveEffectValues`).
+ */
+declare function parseVideoEffectValues(v: unknown, path: string, keyframes?: boolean): VideoEffectValues | undefined;
+/** `{ effect, provider, name, values }`. */
+declare function parseVideoEffectRef(v: unknown, path: string, keyframes?: boolean): VideoEffectRef;
+/** A clip's effect stack: unique ids, each `{ id, effect, provider, name, enabled, opacity, values }`. */
+declare function parseVideoClipEffects(v: unknown, path: string): VideoClipEffect[] | undefined;
 declare function parseVideoTranscriptWords(v: unknown, path: string): VideoTranscriptWord[] | undefined;
 declare function parseVideoAsset(v: unknown, path?: string): VideoAsset;
 declare function parseVideoAssetProxies(v: unknown, path: string): VideoAssetProxy[] | undefined;
@@ -423,139 +441,6 @@ declare const VIDEO_DEFAULT_TITLE_DURATION = 3000;
  */
 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. 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). */
-    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 an iris: only a circle on the frame's centre shows, its radius `progress` (0–1) of the way to the frame's corners. */
-    iris?: {
-        progress: number;
-    };
-    /** For text: what to draw. */
-    text?: {
-        text: string;
-        color: string;
-        fontSize: number;
-        fontFamily: string;
-        fontWeight: number;
-        background?: string;
-    };
-    /** For colour clips and dips. */
-    color?: string;
-    /** How it mixes with the layers beneath (absent = normal). */
-    blend?: VideoBlendMode;
-    /** Colour correction (absent = none). */
-    grade?: VideoGrade;
-}
-/** One sound playing at a moment. */
-interface VideoAudioSource {
-    /** 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, and those of any compound it plays in (0 = silent). */
-    gain: number;
-    speed: number;
-}
-interface VideoFrame {
-    time: number;
-    width: number;
-    height: number;
-    background: string;
-    layers: VideoLayer[];
-    audio: VideoAudioSource[];
-}
-/** 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'], 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, clipTime?: number): VideoFrame;
-/** How far a push or slide has moved at `progress` (0–1): eased in and out, (1 − cos πp) / 2. */
-declare const videoTransitionEase: (progress: number) => number;
-/** Gain of a fade shape `x` of the way up (0–1); a fade out uses the time left, so it mirrors the fade in. */
-declare function videoFadeCurveGain(curve: VideoFadeCurve | undefined, x: number): number;
-/**
- * A media 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. 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
  * sample values. Level 0 holds one min / max pair per `blockSize` samples; each level above merges
@@ -1252,6 +1137,8 @@ interface VideoSvgOptions {
 }
 /**
  * A frame as standalone SVG: images and posters as `<image>`, video without one as a labelled box.
+ * Provider effects cannot be drawn in SVG: clips show without their effects, effect clips as a
+ * labelled box and effect transitions as crossfades.
  * 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.
  */
@@ -1296,6 +1183,16 @@ interface VideoDrawOptions {
      * 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;
+    /**
+     * Provider effects (clip effects, effect clips, effect transitions) come from this engine's
+     * cache. A picture not rendered yet is requested and the layer drawn without its effects
+     * meanwhile (`onEffectWaiting` is called); without an engine or a provider, clips draw without
+     * their effects, effect clips as placeholders and effect transitions as crossfades. Needs
+     * `scratch` to read the pictures effects start from.
+     */
+    effects?: VideoEffectsEngine | null;
+    /** Called when the frame waits for an effect picture still rendering. */
+    onEffectWaiting?: () => void;
 }
 /**
  * Draws a frame on a 2D canvas scaled by `scale` (canvas pixels per frame pixel). `sourceFor`
@@ -1308,6 +1205,27 @@ interface VideoDrawOptions {
  * 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;
+interface VideoExactFrameOptions extends VideoDrawOptions {
+    /** Canvas pixels per frame pixel (default 1). */
+    scale?: number;
+    /** Most draws before giving up on effects still rendering (default 8; nested effects take one each). */
+    maxPasses?: number;
+}
+interface VideoExactFrame {
+    /** The frame drawn (at the start of the frame `time` falls in). */
+    frame: VideoFrame;
+    /** False when a media picture was missing or an effect never arrived. */
+    complete: boolean;
+    /** Effect renders that failed for this frame (their layers were drawn without them). */
+    failures: Error[];
+}
+/**
+ * Draws the frame `time` falls in with every provider effect rendered: frame-exact, the same
+ * drawing as the preview, for exports and agents. `sourceFor` must return ready pictures (decode
+ * the media first: `videoFrameRequestsAt` lists what a frame needs). Draws, waits for the effect
+ * pictures it asked for, and draws again until none is missing.
+ */
+declare function renderVideoFrameExact(ctx: VideoCanvasContext, project: VideoProject, time: number, sourceFor: (layer: VideoLayer) => CanvasImageSource | null, options?: VideoExactFrameOptions): Promise<VideoExactFrame>;
 
 /**
  * How large a picture the preview plays: `full` (the original), a fraction (0.5 = half size, using
@@ -1553,6 +1471,8 @@ interface VideoPreviewSource {
     luts?: VideoLutCache;
     /** Decoded source frames with prefetch (a controller has one when the host gives it). */
     frameCache?: VideoFrameCache | null;
+    /** Provider effect pictures (a controller has one; it draws nothing until a provider is set). */
+    effectsEngine?: VideoEffectsEngine | null;
 }
 /** The parts of a media element the preview drives (so tests can pass fakes). */
 interface VideoPreviewMedia {
@@ -1615,6 +1535,8 @@ interface VideoPreviewOptions {
      * run on the CPU, so a lower `resolution` keeps playback smooth.
      */
     createScratch?: (width: number, height: number, slot: number) => VideoScratchCanvas | null;
+    /** Where provider effect pictures come from (default: the source's `effectsEngine`; `null` draws none). */
+    effects?: VideoEffectsEngine | null;
 }
 /**
  * Plays a project in the browser: keeps one `<video>` or `<audio>` element per playing clip in step
@@ -1646,6 +1568,8 @@ declare class VideoPreviewEngine {
     private fps;
     private readonly unsubscribeLuts;
     private readonly scratchCanvases;
+    private readonly effects;
+    private readonly unsubscribeEffects;
     constructor(source: VideoPreviewSource, canvas: {
         width: number;
         height: number;
@@ -1660,6 +1584,8 @@ declare class VideoPreviewEngine {
     private release;
     /** Brings the media elements in step with the editor and draws the frame. */
     update(): void;
+    /** With effects, the frame is drawn at the start of its frame, so effect pictures are cached once per frame. */
+    private drawable;
     private redraw;
     private sourceFor;
     /** Canvas pixels per frame pixel: the option, else the displayed width at the device pixel ratio (at most 1). */
@@ -1697,7 +1623,22 @@ interface VideoEditorOptions {
      * stepping then show cached frames at once. Host-side and optional (default none).
      */
     frameCache?: VideoFrameCache;
+    /**
+     * An effects provider (see `@pixerate/editor/effects`) for clip effects, effect transitions and
+     * effect clips. Optional: without one the editor behaves as before, and projects that use
+     * effects keep them, drawn as placeholders. Set or change it later with `setEffectsProvider`.
+     */
+    effects?: EffectProvider | null;
 }
+/** What `applyClipEffect` and the other effect edits return: the edit result plus what they made or changed. */
+type VideoEffectEditResult = (VideoEditResult & {
+    ok: true;
+    clip: string;
+    effect?: VideoClipEffect;
+}) | {
+    ok: false;
+    error: string;
+};
 /** A snapshot of the editor. The same object is returned until something changes. */
 interface VideoEditorState {
     project: VideoProject;
@@ -1722,6 +1663,8 @@ interface VideoEditorState {
     redoLabel: string;
     /** How large a picture the preview plays: `auto`, `full` or a fraction that picks a proxy. */
     previewScale: VideoPreviewScale;
+    /** The registered effects provider, or `null` (effects are then drawn as placeholders and cannot be added). */
+    effectsProvider: EffectProvider | null;
     /** Bumped on every change. */
     revision: number;
 }
@@ -1744,6 +1687,10 @@ declare class VideoEditorController {
     readonly luts: VideoLutCache;
     /** The host's frame cache, if it gave one (the preview fills and reads it). */
     readonly frameCache: VideoFrameCache | null;
+    /** The effects provider slot (see `setEffectsProvider`). */
+    readonly effects: EffectsSlot;
+    /** Rendered effect pictures for the preview and frame-exact exports. */
+    readonly effectsEngine: VideoEffectsEngine;
     private project;
     private issues;
     private selection;
@@ -1773,10 +1720,12 @@ declare class VideoEditorController {
     readOnlyReason(): string | null;
     /**
      * Applies edits as one undo step, all or nothing (see `applyVideoEdits`). With `dryRun` it
-     * reports what would happen and changes nothing.
+     * reports what would happen and changes nothing. Edits with the same `merge` key in a row
+     * (a slider drag) fold into one undo step.
      */
     apply(edits: VideoEdit | readonly VideoEdit[], label?: string, options?: {
         dryRun?: boolean;
+        merge?: string;
     }): 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?: {
@@ -1821,6 +1770,77 @@ declare class VideoEditorController {
     deleteSelection(options?: {
         ripple?: boolean;
     }): VideoEditResult;
+    /** The registered effects provider, or `null`. */
+    get effectsProvider(): EffectProvider | null;
+    /** Registers (or with `null` removes) the effects provider. Not an edit: no undo step. */
+    setEffectsProvider(provider: EffectProvider | null): void;
+    /** Registers `provider` and returns a function that removes it again (if it is still the one set). */
+    useEffects(provider: EffectProvider): () => void;
+    /** The provider's description of an effect, checked for `place` (rejects without a provider or for an unknown id). */
+    describeEffect(effect: string, place?: VideoEffectPlace): Promise<EffectDescription>;
+    private refused;
+    private effectEdit;
+    private clipOrThrow;
+    /**
+     * Adds a filter or overlay effect to a clip's effect stack (at `index`, default the end: applied
+     * last), with `values` over the effect's defaults (numbers may be keyframes). One undo step.
+     * Returns the effect with its new id.
+     */
+    applyClipEffect(clip: string, effect: string, options?: {
+        values?: VideoEffectValues;
+        index?: number;
+        enabled?: boolean;
+        opacity?: VideoAnimatable;
+    }): Promise<VideoEffectEditResult>;
+    /**
+     * Changes an effect on a clip: `values` (merged over its current ones; numbers may be
+     * keyframes, `null` resets a control to its default), `enabled`, `opacity` or its place in the
+     * stack (`index`). Values are checked against the provider's controls. One undo step.
+     */
+    updateClipEffect(clip: string, instance: string, changes: {
+        values?: Record<string, EffectValue | {
+            keys: VideoKey[];
+        } | null>;
+        enabled?: boolean;
+        opacity?: VideoAnimatable;
+        index?: number;
+    }, options?: {
+        merge?: string;
+    }): Promise<VideoEffectEditResult>;
+    /** Removes an effect from a clip's stack (works without a provider, so placeholders can be cleared). One undo step. */
+    removeClipEffect(clip: string, instance: string): VideoEffectEditResult;
+    /**
+     * Sets a provider transition into `clip` from the clip that ends where it starts (centred on the
+     * cut, `duration` ms, default the effect's own length or 1000). One undo step.
+     */
+    setEffectTransition(clip: string, effect: string, options?: {
+        duration?: number;
+        values?: Record<string, EffectValue>;
+    }): Promise<VideoEffectEditResult>;
+    /**
+     * Adds an effect clip: a generator, title or overlay effect drawn over the whole frame for
+     * `duration` ms (default the effect's own length, else 5 s) at `start` (default the end of the
+     * track). One undo step. Returns the new clip's id.
+     */
+    addEffectClip(track: string, effect: string, options?: {
+        start?: number;
+        duration?: number;
+        values?: VideoEffectValues;
+        name?: string;
+        mode?: VideoPlacementMode;
+        ripple?: boolean;
+        id?: string;
+    }): Promise<VideoEffectEditResult>;
+    /**
+     * Changes the values of an effect clip's picture (`target` its id) or of the effect transition
+     * into a clip, merged over the current ones and checked against the provider's controls.
+     * Transition values cannot be keyframed. One undo step.
+     */
+    updateEffectValues(clip: string, part: 'generator' | 'transition', values: VideoEffectValues, options?: {
+        merge?: string;
+    }): Promise<VideoEffectEditResult>;
+    /** Keys for one numeric control of a clip effect (clip-relative ms), or `null` to stop animating it (keeping its value at the clip's start). */
+    setClipEffectKeyframes(clip: string, instance: string, control: string, keys: VideoKey[] | null): Promise<VideoEffectEditResult>;
     /** What plays at `time` (default: the playhead). */
     frame(time?: number): VideoFrame;
     /** The frame at `time` (default: the playhead) as SVG. */
@@ -1892,6 +1912,7 @@ declare function describeVideoSequence(project: VideoProject, sequence: VideoSeq
             fadeIn?: number;
             fadeOut?: number;
             transition?: VideoTransition;
+            effects?: VideoClipEffect[];
         } | {
             source?: {
                 in: number;
@@ -1919,6 +1940,7 @@ declare function describeVideoSequence(project: VideoProject, sequence: VideoSeq
             fadeIn?: number;
             fadeOut?: number;
             transition?: VideoTransition;
+            effects?: VideoClipEffect[];
         } | {
             source?: {
                 in: number;
@@ -1941,6 +1963,7 @@ declare function describeVideoSequence(project: VideoProject, sequence: VideoSeq
             fadeIn?: number;
             fadeOut?: number;
             transition?: VideoTransition;
+            effects?: VideoClipEffect[];
         } | {
             source?: {
                 in: number;
@@ -1968,6 +1991,32 @@ declare function describeVideoSequence(project: VideoProject, sequence: VideoSeq
             fadeIn?: number;
             fadeOut?: number;
             transition?: VideoTransition;
+            effects?: VideoClipEffect[];
+        } | {
+            source?: {
+                in: number;
+                out: number;
+            } | null | undefined;
+            end: number;
+            type: "effect";
+            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;
+            effects?: VideoClipEffect[];
+            effect: string;
+            provider?: string;
+            values?: VideoEffectValues;
         })[];
         volume?: number | undefined;
         syncLocked?: boolean | undefined;
@@ -2050,6 +2099,7 @@ declare function describeVideoProject(project: VideoProject): {
                 fadeIn?: number;
                 fadeOut?: number;
                 transition?: VideoTransition;
+                effects?: VideoClipEffect[];
             } | {
                 source?: {
                     in: number;
@@ -2077,6 +2127,7 @@ declare function describeVideoProject(project: VideoProject): {
                 fadeIn?: number;
                 fadeOut?: number;
                 transition?: VideoTransition;
+                effects?: VideoClipEffect[];
             } | {
                 source?: {
                     in: number;
@@ -2099,6 +2150,7 @@ declare function describeVideoProject(project: VideoProject): {
                 fadeIn?: number;
                 fadeOut?: number;
                 transition?: VideoTransition;
+                effects?: VideoClipEffect[];
             } | {
                 source?: {
                     in: number;
@@ -2126,6 +2178,32 @@ declare function describeVideoProject(project: VideoProject): {
                 fadeIn?: number;
                 fadeOut?: number;
                 transition?: VideoTransition;
+                effects?: VideoClipEffect[];
+            } | {
+                source?: {
+                    in: number;
+                    out: number;
+                } | null | undefined;
+                end: number;
+                type: "effect";
+                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;
+                effects?: VideoClipEffect[];
+                effect: string;
+                provider?: string;
+                values?: VideoEffectValues;
             })[];
             volume?: number | undefined;
             syncLocked?: boolean | undefined;
@@ -2228,6 +2306,7 @@ declare function describeVideoProject(project: VideoProject): {
             fadeIn?: number;
             fadeOut?: number;
             transition?: VideoTransition;
+            effects?: VideoClipEffect[];
         } | {
             source?: {
                 in: number;
@@ -2255,6 +2334,7 @@ declare function describeVideoProject(project: VideoProject): {
             fadeIn?: number;
             fadeOut?: number;
             transition?: VideoTransition;
+            effects?: VideoClipEffect[];
         } | {
             source?: {
                 in: number;
@@ -2277,6 +2357,7 @@ declare function describeVideoProject(project: VideoProject): {
             fadeIn?: number;
             fadeOut?: number;
             transition?: VideoTransition;
+            effects?: VideoClipEffect[];
         } | {
             source?: {
                 in: number;
@@ -2304,6 +2385,32 @@ declare function describeVideoProject(project: VideoProject): {
             fadeIn?: number;
             fadeOut?: number;
             transition?: VideoTransition;
+            effects?: VideoClipEffect[];
+        } | {
+            source?: {
+                in: number;
+                out: number;
+            } | null | undefined;
+            end: number;
+            type: "effect";
+            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;
+            effects?: VideoClipEffect[];
+            effect: string;
+            provider?: string;
+            values?: VideoEffectValues;
         })[];
         volume?: number | undefined;
         syncLocked?: boolean | undefined;
@@ -2333,6 +2440,26 @@ declare function describeVideoProject(project: VideoProject): {
  */
 declare function createVideoEditorToolProvider(controller: VideoEditorController, options?: VideoEditorToolProviderOptions): AgentToolProvider;
 
+/**
+ * Agent tools for provider effects in the video editor: the shared effect tools
+ * (`search_effects`, `describe_effect`, `list_applied_effects`, `apply_effect`, `update_effect`,
+ * `remove_effect`) on clips, plus `add_video_effect_clip`, `set_video_effect_transition` and
+ * `set_video_effect_keyframes`.
+ */
+
+interface VideoEffectsToolProviderOptions {
+    /** Provider id (unique per registry). Default `video-effects`. */
+    id?: string;
+    /** Always prefix tool names with `<namespace>__`. */
+    namespace?: string;
+    /** The project cannot be edited: write tools are hidden. A string is the reason. */
+    readOnly?: boolean | string | (() => boolean | string);
+}
+/** A clip's effects as the tools report them: its effect clip picture, its effect transition, then its stack. */
+declare function videoClipAppliedEffects(clip: VideoClip): AppliedEffectInfo[];
+/** The effect tools for a video editor (see the module comment). */
+declare function createVideoEffectsToolProvider(controller: VideoEditorController, options?: VideoEffectsToolProviderOptions): AgentToolProvider;
+
 interface VideoRulerTick {
     time: number;
     /** Pixels from the timeline's left edge. */
@@ -2458,4 +2585,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_MODE_LABELS, VIDEO_CLIP_ANIMATION_DURATION, VIDEO_CLIP_ANIMATION_LABELS, VIDEO_DEFAULT_FILLERS, VIDEO_DEFAULT_STILL_DURATION, VIDEO_DEFAULT_TITLE_DURATION, VIDEO_EDIT_OPS, VIDEO_FADE_CURVE_LABELS, VIDEO_GRADE_CONTROLS, VIDEO_GRADE_PRESETS, VIDEO_GRADE_PRESET_NAMES, VIDEO_ISSUE_CODES, VIDEO_LUT_MAX_SIZE, VIDEO_PEAK_BLOCK, VIDEO_PREVIEW_SCALE_OPTIONS, VIDEO_PROXY_SCALES, VIDEO_SCOPE_KINDS, VIDEO_TIME_EPSILON, VIDEO_TRANSITION_LABELS, VIDEO_VECTORSCOPE_TARGETS, VideoAnimatable, VideoAsset, VideoAssetKind, VideoAssetProxy, type VideoAudioLevel, type VideoAudioPeaks, VideoAudioPeaksCache, type VideoAudioPeaksLoader, type VideoAudioSource, VideoBlendMode, type VideoCacheEntryInfo, type VideoCanvasContext, VideoClip, VideoClipAnimation, VideoClipAnimationEffect, type VideoClipDragInput, type VideoClipDragMode, type VideoClipDragPlan, type VideoClipLocation, type VideoDecodedFrame, type VideoDrawOptions, type VideoEdit, type VideoEditOp, type VideoEditOutcome, type VideoEditResult, VideoEditorController, type VideoEditorOptions, type VideoEditorState, type VideoEditorToolProviderOptions, VideoEdlOptions, type VideoExposureOptions, type VideoExposureStats, VideoFadeCurve, VideoFfmpegExport, VideoFfmpegOptions, VideoFit, type VideoFrame, VideoFrameCache, type VideoFrameCacheOptions, type VideoFrameCacheStats, type VideoFrameDecoder, type VideoFrameRequest, type VideoGap, VideoGrade, type VideoGradeControl, VideoGradeLut, type VideoGradePreset, type VideoGradeSetting, type VideoGradeStep, type VideoHistogram, type VideoIssue, type VideoIssueCode, type VideoIssueSeverity, VideoKey, VideoKeyframeProperty, type VideoKeyframeRow, VideoKeyframes, type VideoLayer, type VideoLut, VideoLutCache, type VideoLutLoader, type VideoLutSvgApproximation, VideoMarker, VideoMediaClip, type VideoMediaProbe, type VideoPauseOptions, type VideoPixels, VideoPlacementMode, VideoPreviewEngine, type VideoPreviewImage, type VideoPreviewMedia, type VideoPreviewOptions, VideoPreviewPixels, type VideoPreviewScale, type VideoPreviewSnapshot, type VideoPreviewSource, VideoProject, type VideoProxyCommand, type VideoProxyOptions, type VideoRect, type VideoRulerTick, type VideoScopeImage, type VideoScopeKind, type VideoScopeOptions, type VideoScopeSummary, type VideoScopesPanelReading, type VideoScratchCanvas, VideoSequence, type VideoSilenceOptions, type VideoSnapOptions, type VideoSpeedSegment, type VideoSvgOptions, VideoTextClip, type VideoTimelineWord, VideoTrack, VideoTrackKind, type VideoTranscriptRange, VideoTranscriptWord, VideoTransform, VideoTransition, VideoTransitionType, type VideoVectorscope, type VideoWaveform, type VideoWaveformMode, VideoWipeDirection, allVideoClipIds, allVideoTracks, applyVideoEdits, applyVideoGrade, applyVideoLut, applyVideoLutToPixels, buildVideoAudioPeaks, checkVideoProject, checkVideoTimeRemap, createVideoEditorToolProvider, createVideoElementDecoder, createVideoProject, decodeVideoAudioPeaks, describeVideoProject, describeVideoSequence, drawVideoFrame, findVideoAudioSilences, findVideoClip, findVideoFillers, findVideoGaps, findVideoSequenceClip, findVideoSequenceCycle, findVideoTranscriptPauses, findVideoTranscriptText, formatVideoSeconds, formatVideoTimecode, formatVideoTimecodeFrames, isVideoDropFrameRate, mergeVideoRanges, nextFreeVideoSlot, normalizeVideoGrade, normalizeVideoGradeLut, normalizeVideoWord, parseVideoAnimatable, parseVideoAsset, parseVideoAssetProxies, parseVideoClip, parseVideoClipAnimation, parseVideoCubeLut, parseVideoGrade, parseVideoGradeLut, parseVideoKeyframes, parseVideoMarker, parseVideoPreviewScale, parseVideoProject, parseVideoSequence, parseVideoTimeRemap, parseVideoTrack, parseVideoTranscript, parseVideoTranscriptWords, parseVideoTransform, parseVideoTransition, placeVideoRect, planVideoClipDrag, planVideoPrefetch, probeVideoMedia, readVideoScopesPanel, resolveVideoPreviewScale, snapToVideoFrame, snapVideoTime, sortedVideoClips, summarizeVideoScopes, 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, 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, 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, videoSlowMotionRamp, videoSnapPoints, videoSourceFrame, videoSourceFrameTime, videoSpeedRampEdit, videoSpeedRampKeys, videoTextStyle, videoTimeRemapBreakpoints, videoTimeRemapSpan, videoTimecodeFrames, videoTimelineTranscript, videoTitleFrame, videoTrackSyncLocked, videoTranscriptEdit, videoTranscriptTrack, videoTransformAt, videoTransitionEase, videoTransitionHasDirection, videoVectorscope, videoVectorscopeAngle, videoVectorscopeImage, videoVectorscopePoint, videoWaveformImage, videoWaveformPath, videoWipeRect, videoWordAt, videoWordsRange };
+export { type CreateVideoProjectOptions, type NewVideoClip, VIDEO_BLEND_MODE_LABELS, VIDEO_CLIP_ANIMATION_DURATION, VIDEO_CLIP_ANIMATION_LABELS, VIDEO_DEFAULT_FILLERS, VIDEO_DEFAULT_STILL_DURATION, VIDEO_DEFAULT_TITLE_DURATION, VIDEO_EDIT_OPS, VIDEO_FADE_CURVE_LABELS, VIDEO_GRADE_CONTROLS, VIDEO_GRADE_PRESETS, VIDEO_GRADE_PRESET_NAMES, VIDEO_ISSUE_CODES, VIDEO_LUT_MAX_SIZE, VIDEO_PEAK_BLOCK, VIDEO_PREVIEW_SCALE_OPTIONS, VIDEO_PROXY_SCALES, VIDEO_SCOPE_KINDS, VIDEO_TIME_EPSILON, VIDEO_TRANSITION_LABELS, VIDEO_VECTORSCOPE_TARGETS, VideoAnimatable, VideoAsset, VideoAssetKind, VideoAssetProxy, type VideoAudioLevel, type VideoAudioPeaks, VideoAudioPeaksCache, type VideoAudioPeaksLoader, VideoBlendMode, type VideoCacheEntryInfo, type VideoCanvasContext, VideoClip, VideoClipAnimation, VideoClipAnimationEffect, type VideoClipDragInput, type VideoClipDragMode, type VideoClipDragPlan, VideoClipEffect, type VideoClipLocation, type VideoDecodedFrame, type VideoDrawOptions, type VideoEdit, type VideoEditOp, type VideoEditOutcome, type VideoEditResult, VideoEditorController, type VideoEditorOptions, type VideoEditorState, type VideoEditorToolProviderOptions, VideoEdlOptions, type VideoEffectEditResult, VideoEffectPlace, VideoEffectRef, VideoEffectValues, VideoEffectsEngine, type VideoEffectsToolProviderOptions, type VideoExactFrame, type VideoExactFrameOptions, type VideoExposureOptions, type VideoExposureStats, VideoFadeCurve, VideoFfmpegExport, VideoFfmpegOptions, VideoFit, VideoFrame, VideoFrameCache, type VideoFrameCacheOptions, type VideoFrameCacheStats, type VideoFrameDecoder, type VideoFrameRequest, type VideoGap, VideoGrade, type VideoGradeControl, VideoGradeLut, type VideoGradePreset, type VideoGradeSetting, type VideoGradeStep, type VideoHistogram, type VideoIssue, type VideoIssueCode, type VideoIssueSeverity, VideoKey, VideoKeyframeProperty, type VideoKeyframeRow, VideoKeyframes, VideoLayer, type VideoLut, VideoLutCache, type VideoLutLoader, type VideoLutSvgApproximation, VideoMarker, VideoMediaClip, type VideoMediaProbe, type VideoPauseOptions, type VideoPixels, VideoPlacementMode, VideoPreviewEngine, type VideoPreviewImage, type VideoPreviewMedia, type VideoPreviewOptions, VideoPreviewPixels, type VideoPreviewScale, type VideoPreviewSnapshot, type VideoPreviewSource, VideoProject, type VideoProxyCommand, type VideoProxyOptions, VideoRect, type VideoRulerTick, type VideoScopeImage, type VideoScopeKind, type VideoScopeOptions, type VideoScopeSummary, type VideoScopesPanelReading, type VideoScratchCanvas, VideoSequence, type VideoSilenceOptions, type VideoSnapOptions, type VideoSpeedSegment, type VideoSvgOptions, type VideoTimelineWord, VideoTrack, VideoTrackKind, type VideoTranscriptRange, VideoTranscriptWord, VideoTransform, VideoTransition, VideoTransitionType, type VideoVectorscope, type VideoWaveform, type VideoWaveformMode, allVideoClipIds, allVideoTracks, applyVideoEdits, applyVideoGrade, applyVideoLut, applyVideoLutToPixels, buildVideoAudioPeaks, checkVideoProject, checkVideoTimeRemap, createVideoEditorToolProvider, createVideoEffectsToolProvider, createVideoElementDecoder, createVideoProject, decodeVideoAudioPeaks, describeVideoProject, describeVideoSequence, drawVideoFrame, findVideoAudioSilences, findVideoClip, findVideoFillers, findVideoGaps, findVideoSequenceClip, findVideoSequenceCycle, findVideoTranscriptPauses, findVideoTranscriptText, formatVideoSeconds, formatVideoTimecode, formatVideoTimecodeFrames, isVideoDropFrameRate, mergeVideoRanges, nextFreeVideoSlot, normalizeVideoGrade, normalizeVideoGradeLut, normalizeVideoWord, parseVideoAnimatable, parseVideoAsset, parseVideoAssetProxies, parseVideoClip, parseVideoClipAnimation, parseVideoClipEffects, parseVideoCubeLut, parseVideoEffectRef, parseVideoEffectValues, parseVideoGrade, parseVideoGradeLut, parseVideoKeyframes, parseVideoMarker, parseVideoPreviewScale, parseVideoProject, parseVideoSequence, parseVideoTimeRemap, parseVideoTrack, parseVideoTranscript, parseVideoTranscriptWords, parseVideoTransform, parseVideoTransition, planVideoClipDrag, planVideoPrefetch, probeVideoMedia, readVideoScopesPanel, renderVideoFrameExact, resolveVideoPreviewScale, snapToVideoFrame, snapVideoTime, sortedVideoClips, summarizeVideoScopes, videoAssetDropEdit, videoAssetHasSound, videoAssetKindOf, videoAssetMap, videoAssetProxy, videoAudioLevels, videoAudioPeakRange, videoAudioPeakSpans, videoAudioPeaksDuration, videoCacheEvictions, videoChroma, videoClipAfter, videoClipAnimated, videoClipAnimationProperties, videoClipAnimationSpans, videoClipAppliedEffects, videoClipBefore, videoClipEnd, videoClipHandles, videoClipKeyframes, videoClipLabel, videoClipOverhang, videoClipShowsWaveform, videoClipSourceRange, videoClipSourceTime, videoClipSpeed, videoClipSpeedAt, videoClipTint, videoClipWaveform, videoClipWaveformPath, videoClipsAt, videoContactSheetSvg, videoDragLabel, videoDropTracks, videoExposureNotes, videoExposureStats, videoFrameCacheKey, videoFrameDuration, videoFrameRequestsAt, videoFrameToSvg, videoFrames, videoFreezeFrameEdit, videoGradeCssFilter, videoGradeFfmpegFilters, videoGradeGainsFilterId, videoGradeLook, videoGradePreset, videoGradeStepMatrix, videoGradeStepSvgValues, videoGradeSteps, videoGradeSvgDefs, videoGradeSvgFilter, videoHistogram, videoHistogramImage, videoHourFrames, videoIrisRadius, videoIssueKey, 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, videoSlowMotionRamp, videoSnapPoints, videoSourceFrame, videoSourceFrameTime, videoSpeedRampEdit, videoSpeedRampKeys, videoTimeRemapBreakpoints, videoTimeRemapSpan, videoTimecodeFrames, videoTimelineTranscript, videoTrackSyncLocked, videoTranscriptEdit, videoTranscriptTrack, videoTransitionHasDirection, videoVectorscope, videoVectorscopeAngle, videoVectorscopeImage, videoVectorscopePoint, videoWaveformImage, videoWaveformPath, videoWipeRect, videoWordAt, videoWordsRange };