@pixerate/editor 0.123.0 → 0.124.1

package/dist/video-editor/index.js

@@ -4,6 +4,7 @@ import {
   VIDEO_CLIP_ANIMATION_EFFECTS,
   VIDEO_CLIP_TYPES,
   VIDEO_EASE_NAMES,
+  VIDEO_EFFECT_PLACES,
   VIDEO_FADE_CURVES,
   VIDEO_FITS,
   VIDEO_GRADE_CONTROLS,
@@ -17,12 +18,15 @@ import {
   VIDEO_TRANSFORM_PROPERTIES,
   VIDEO_TRANSITION_TYPES,
   VIDEO_WIPE_DIRECTIONS,
+  VideoEffectsEngine,
   VideoLutCache,
   allVideoClipIds,
   allVideoTracks,
   applyVideoGrade,
   applyVideoLut,
   applyVideoLutToPixels,
+  checkVideoEffectPlace,
+  checkVideoEffectValues,
   checkVideoTimeRemap,
   drawVideoFrame,
   ffmpegFilterValue,
@@ -35,13 +39,16 @@ import {
   formatVideoTimecodeFrames,
   isVideoDropFrameRate,
   isVideoKeyframes,
+  mixEffectPixels,
   nextFreeVideoSlot,
   normalizeVideoGrade,
   normalizeVideoGradeLut,
+  overEffectPixels,
   parseVideoCubeLut,
   parseVideoLoudnessMeasurement,
   placeVideoRect,
   removeVideoKey,
+  renderVideoFrameExact,
   retimeVideoAnimatable,
   setVideoKey,
   snapToVideoFrame,
@@ -59,6 +66,7 @@ import {
   videoClipAnimationProperties,
   videoClipAnimationSpans,
   videoClipBefore,
+  videoClipEffectUses,
   videoClipEnd,
   videoClipHandles,
   videoClipOverhang,
@@ -71,7 +79,11 @@ import {
   videoContactSheetSvg,
   videoEaseBezier,
   videoEaseProgress,
+  videoEffectFrameTime,
+  videoEffectLayerKey,
+  videoEffectValuesAt,
   videoFadeCurveGain,
+  videoFfmpegUnsupportedEffects,
   videoFrameAt,
   videoFrameDuration,
   videoFrameLeafLayers,
@@ -93,12 +105,15 @@ import {
   videoKeyframeBreakpoints,
   videoKeyframeFfmpegExpr,
   videoKeysOf,
+  videoLayersUseEffects,
+  videoLayersWithoutTransitionEffects,
   videoLutFromFunction,
   videoLutSvgApproximation,
   videoLutSvgPrimitives,
   videoLutToCube,
   videoOverlap,
   videoProjectDuration,
+  videoProjectEffects,
   videoProjectSvg,
   videoSequenceChildren,
   videoSequenceDuration,
@@ -119,7 +134,15 @@ import {
   videoTransitionEase,
   videoValueAt,
   videoWipeRect
-} from "../chunk-IPFRWILU.js";
+} from "../chunk-ORHMVUR6.js";
+import {
+  createEffectToolProvider
+} from "../chunk-JRXJTPES.js";
+import {
+  EffectsSlot,
+  isEffectError
+} from "../chunk-QEG3GRN2.js";
+import "../chunk-4FX5ACVG.js";
 import {
   namedWithSuggestion
 } from "../chunk-INZJALPY.js";
@@ -239,13 +262,52 @@ function parseVideoGradeLut(v, path) {
 function parseVideoTransition(v, path) {
   if (v === void 0) return void 0;
   if (!isObject(v)) return fail(path, "must be an object { type, duration }");
+  const type = oneOf(v.type, VIDEO_TRANSITION_TYPES, `${path}.type`, false);
+  if (type === "effect" && v.effect === void 0) fail(`${path}.effect`, 'is required for an effect transition: { effect: "<effect id>", values }');
+  if (type !== "effect" && v.effect !== void 0) fail(`${path}.effect`, 'is only for transitions of type "effect"');
   return compact({
-    type: oneOf(v.type, VIDEO_TRANSITION_TYPES, `${path}.type`, false),
+    type,
     duration: num(v.duration, `${path}.duration`, { positive: true }),
     color: str(v.color, `${path}.color`, true),
     direction: oneOf(v.direction, VIDEO_WIPE_DIRECTIONS, `${path}.direction`),
-    audioCurve: oneOf(v.audioCurve, VIDEO_FADE_CURVES, `${path}.audioCurve`)
+    audioCurve: oneOf(v.audioCurve, VIDEO_FADE_CURVES, `${path}.audioCurve`),
+    effect: v.effect === void 0 ? void 0 : parseVideoEffectRef(v.effect, `${path}.effect`, false)
+  });
+}
+var isEffectValue = (x) => typeof x === "string" || typeof x === "boolean" || typeof x === "number" && Number.isFinite(x) || Array.isArray(x) && x.every((n) => typeof n === "number" && Number.isFinite(n));
+function parseVideoEffectValues(v, path, keyframes = true) {
+  if (v === void 0) return void 0;
+  if (!isObject(v)) return fail(path, "must be an object of control values from describe_effect");
+  const out = {};
+  for (const [k, x] of Object.entries(v)) {
+    if (isEffectValue(x)) out[k] = Array.isArray(x) ? [...x] : x;
+    else if (keyframes && isObject(x)) out[k] = parseVideoKeyframes(x, `${path}.${k}`);
+    else fail(`${path}.${k}`, keyframes ? "must be a number, string, true / false, a list of numbers, or keyframes { keys }" : "must be a number, string, true / false or a list of numbers");
+  }
+  return out;
+}
+function parseVideoEffectRef(v, path, keyframes = true) {
+  if (!isObject(v)) return fail(path, "must be an object { effect, values }");
+  const unknown = Object.keys(v).find((k) => !["effect", "provider", "name", "values"].includes(k));
+  if (unknown) fail(`${path}.${unknown}`, "is not an effect field; use effect, provider, name, values");
+  return compact({ effect: str(v.effect, `${path}.effect`), provider: str(v.provider, `${path}.provider`, true), name: str(v.name, `${path}.name`, true), values: parseVideoEffectValues(v.values, `${path}.values`, keyframes) });
+}
+function parseVideoClipEffects(v, path) {
+  if (v === void 0) return void 0;
+  if (!Array.isArray(v)) return fail(path, "must be a list of effects { id, effect, values }");
+  const ids = /* @__PURE__ */ new Set();
+  const out = v.map((e, i) => {
+    const at = `${path}[${i}]`;
+    if (!isObject(e)) return fail(at, "must be an object { id, effect, values }");
+    const unknown = Object.keys(e).find((k) => !["id", "effect", "provider", "name", "values", "enabled", "opacity"].includes(k));
+    if (unknown) fail(`${at}.${unknown}`, "is not a clip effect field; use id, effect, provider, name, values, enabled, opacity");
+    const id = str(e.id, `${at}.id`);
+    if (ids.has(id)) fail(`${at}.id`, `repeats "${id}"; each effect on a clip needs its own id`);
+    ids.add(id);
+    const { effect, provider, name, values } = parseVideoEffectRef({ effect: e.effect, provider: e.provider, name: e.name, values: e.values }, at);
+    return compact({ id, effect, provider, name, values, enabled: bool(e.enabled, `${at}.enabled`), opacity: parseVideoAnimatable(e.opacity, `${at}.opacity`, { optional: true, min: 0, max: 1 }) });
   });
+  return out.length ? out : void 0;
 }
 function parseVideoTranscriptWords(v, path) {
   if (v === void 0) return void 0;
@@ -316,7 +378,8 @@ function parseVideoClip(v, path = "clip") {
     animateOut: parseVideoClipAnimation(v.animateOut, `${path}.animateOut`),
     fadeIn: num(v.fadeIn, `${path}.fadeIn`, { optional: true, min: 0 }),
     fadeOut: num(v.fadeOut, `${path}.fadeOut`, { optional: true, min: 0 }),
-    transition: parseVideoTransition(v.transition, `${path}.transition`)
+    transition: parseVideoTransition(v.transition, `${path}.transition`),
+    effects: parseVideoClipEffects(v.effects, `${path}.effects`)
   };
   if (type === "media")
     return compact({
@@ -356,6 +419,10 @@ function parseVideoClip(v, path = "clip") {
       fontWeight: num(v.fontWeight, `${path}.fontWeight`, { optional: true, min: 100, max: 1e3 }),
       background: str(v.background, `${path}.background`, true)
     });
+  if (type === "effect") {
+    const ref = parseVideoEffectRef({ effect: v.effect, provider: v.provider, name: v.name === void 0 ? void 0 : v.name, values: v.values }, path);
+    return compact({ type, ...base, ...ref, name: base.name });
+  }
   return compact({ type, ...base, color: str(v.color, `${path}.color`) });
 }
 function parseVideoTrack(v, path = "track") {
@@ -653,7 +720,7 @@ function retimeClipKeys(clip, fn) {
     if (isVideoKeyframes(v)) a.set(fn(v));
   }
 }
-var OPTIONAL_CLIP_FIELDS = ["name", "opacity", "transform", "fit", "blend", "grade", "animateIn", "animateOut", "fadeIn", "fadeOut", "fadeInCurve", "fadeOutCurve", "transition", "in", "speed", "timeRemap", "volume", "muted", "color", "fontSize", "fontFamily", "fontWeight", "background"];
+var OPTIONAL_CLIP_FIELDS = ["name", "effects", "values", "provider", "opacity", "transform", "fit", "blend", "grade", "animateIn", "animateOut", "fadeIn", "fadeOut", "fadeInCurve", "fadeOutCurve", "transition", "in", "speed", "timeRemap", "volume", "muted", "color", "fontSize", "fontFamily", "fontWeight", "background"];
 var TIME_FIELDS = { slip_clip: ["delta"], roll_edit: ["delta"], slide_clip: ["delta"], lift_range: ["from", "to"], extract_range: ["from", "to"], split_at: ["at"] };
 var Editor = class {
   constructor(p) {
@@ -1099,7 +1166,7 @@ var Editor = class {
         const { track, clip } = this.clip(e.clip);
         this.unlocked(track);
         if (clip.type === "sequence") refuse(`Clip "${clip.id}" is a compound clip, which plays its sequence at normal speed; ramp the clips inside the sequence instead.`);
-        if (clip.type !== "media") refuse(`Clip "${clip.id}" is a ${clip.type === "text" ? "title" : "colour"}, so it has no source to ramp; only video and audio clips change speed.`);
+        if (clip.type !== "media") refuse(`Clip "${clip.id}" is a ${clip.type === "text" ? "title" : clip.type === "effect" ? "effect clip" : "colour"}, so it has no source to ramp; only video and audio clips change speed.`);
         const asset = this.asset(clip.asset);
         if (asset.kind === "image") refuse(`Clip "${clip.id}" is a still ("${asset.id}"), so it has no motion to ramp.`);
         const media = clip;
@@ -1156,7 +1223,7 @@ var Editor = class {
       case "slip_clip": {
         const { track, clip } = this.clip(e.clip);
         this.unlocked(track);
-        if (clip.type !== "media" && clip.type !== "sequence") refuse(`Clip "${clip.id}" is a ${clip.type === "text" ? "title" : "colour"}, so it has no source to slip; only video, audio and compound clips slip.`);
+        if (clip.type !== "media" && clip.type !== "sequence") refuse(`Clip "${clip.id}" is a ${clip.type === "text" ? "title" : clip.type === "effect" ? "effect clip" : "colour"}, so it has no source to slip; only video, audio and compound clips slip.`);
         const source = clip.type === "sequence" ? `sequence "${clip.sequence}"` : `"${this.asset(clip.asset).id}"`;
         if (clip.type === "media" && this.asset(clip.asset).kind === "image") refuse(`Clip "${clip.id}" is a still ("${clip.asset}"), so it has no source to slip; only video and audio clips slip.`);
         const handles = videoClipHandles(clip, videoAssetMap(this.p), videoSequenceMap(this.p));
@@ -2451,6 +2518,9 @@ var VideoPreviewEngine = class {
     this.frameCache = options.frameCache !== void 0 ? options.frameCache : source.frameCache ?? null;
     this.unsubscribeFrames = this.frameCache ? this.frameCache.subscribe(() => this.redraw()) : () => {
     };
+    this.effects = options.effects !== void 0 ? options.effects : source.effectsEngine ?? null;
+    this.unsubscribeEffects = this.effects ? this.effects.subscribe(() => this.redraw()) : () => {
+    };
     const pixels = options.pixels !== void 0 ? options.pixels : source.previewPixels;
     this.detachPixels = pixels ? pixels.attach(() => this.readPixels()) : () => {
     };
@@ -2480,6 +2550,8 @@ var VideoPreviewEngine = class {
   fps = 30;
   unsubscribeLuts;
   scratchCanvases = /* @__PURE__ */ new Map();
+  effects;
+  unsubscribeEffects;
   /** The canvas's pixels and the frame they show, or `null` when its context cannot be read. */
   readPixels() {
     const ctx = this.ctx;
@@ -2568,14 +2640,22 @@ var VideoPreviewEngine = class {
     }
     for (const a of sounding.values()) sync(a.clip, a.src, "audio", a.sourceTime, a.speed, a.gain);
     for (const entry of [...this.media.values()]) if (!active.has(entry.clip)) this.release(entry);
-    this.draw(frame);
+    this.draw(this.drawable(project, frame));
+  }
+  /** With effects, the frame is drawn at the start of its frame, so effect pictures are cached once per frame. */
+  drawable(project, frame) {
+    if (!this.effects?.available || !videoLayersUseEffects(frame.layers)) return frame;
+    const at = videoEffectFrameTime(frame.time, project.fps);
+    return at === frame.time ? frame : { ...videoFrameAt(project, at), time: frame.time };
   }
   redraw() {
     if (this.scheduled || this.destroyed) return;
     this.scheduled = true;
     queueMicrotask(() => {
       this.scheduled = false;
-      if (!this.destroyed) this.draw(videoFrameAt(this.source.getState().project, this.source.getState().time));
+      if (this.destroyed) return;
+      const { project, time } = this.source.getState();
+      this.draw(this.drawable(project, videoFrameAt(project, time)));
     });
   }
   sourceFor = (layer) => {
@@ -2613,11 +2693,20 @@ var VideoPreviewEngine = class {
     if (this.canvas.height !== h) this.canvas.height = h;
     this.complete = true;
     const sourceFor = (layer) => {
+      if (layer.type === "effect") return null;
       const source = this.sourceFor(layer);
       if (!source) this.complete = false;
       return source;
     };
-    drawVideoFrame(this.ctx, frame, sourceFor, resolution, { defineSvgFilter: this.defineSvgFilter, lutFor: this.lutFor, scratch: this.scratch });
+    drawVideoFrame(this.ctx, frame, sourceFor, resolution, {
+      defineSvgFilter: this.defineSvgFilter,
+      lutFor: this.lutFor,
+      scratch: this.scratch,
+      effects: this.effects,
+      onEffectWaiting: () => {
+        this.complete = false;
+      }
+    });
     this.drawn = { time: frame.time, complete: this.complete };
     this.options.onFrame?.(frame);
     this.pixelsTarget?.drawn(frame.time, this.complete);
@@ -2668,6 +2757,7 @@ var VideoPreviewEngine = class {
     this.detachPixels();
     this.unsubscribeLuts();
     this.unsubscribeFrames();
+    this.unsubscribeEffects();
     this.filterHost?.remove();
     this.filterHost = null;
     this.filters.clear();
@@ -2689,6 +2779,10 @@ var VideoEditorController = class {
   luts;
   /** The host's frame cache, if it gave one (the preview fills and reads it). */
   frameCache;
+  /** The effects provider slot (see `setEffectsProvider`). */
+  effects;
+  /** Rendered effect pictures for the preview and frame-exact exports. */
+  effectsEngine;
   project;
   issues;
   selection = [];
@@ -2706,6 +2800,9 @@ var VideoEditorController = class {
     this.audioPeaks = options.audioPeaks instanceof VideoAudioPeaksCache ? options.audioPeaks : new VideoAudioPeaksCache(options.audioPeaks);
     this.luts = options.luts instanceof VideoLutCache ? options.luts : new VideoLutCache(options.luts);
     this.frameCache = options.frameCache ?? null;
+    this.effects = new EffectsSlot();
+    if (options.effects) this.effects.set(options.effects);
+    this.effectsEngine = new VideoEffectsEngine({ slot: this.effects });
     this.project = options.project ? parseVideoProject(options.project) : createVideoProject();
     this.issues = checkVideoProject(this.project);
     this.readOnly = options.readOnly ?? false;
@@ -2721,12 +2818,14 @@ var VideoEditorController = class {
       this.player.subscribe(() => this.notify()),
       this.history.subscribe(() => {
         if (!this.applying) this.notify();
-      })
+      }),
+      this.effects.subscribe(() => this.notify())
     );
   }
   /** Pauses and stops listening to the player and history. Subscribing again reconnects (React StrictMode). */
   destroy() {
     this.player.pause();
+    this.effectsEngine.reset();
     this.unsubscribers.splice(0).forEach((u) => u());
   }
   getState = () => this.state;
@@ -2760,6 +2859,7 @@ var VideoEditorController = class {
       undoLabel: h.undoName,
       redoLabel: h.redoName,
       previewScale: this.previewScale,
+      effectsProvider: this.effects.provider,
       revision: this.revision
     };
   }
@@ -2789,7 +2889,7 @@ var VideoEditorController = class {
     this.notify();
     this.onChange?.(project);
   }
-  commit(label, next) {
+  commit(label, next, merge) {
     const before = this.project;
     this.error = null;
     if (next === before) {
@@ -2803,7 +2903,8 @@ var VideoEditorController = class {
       undo: () => this.setProject(before),
       redo: () => this.setProject(next)
     };
-    this.history.execute(command);
+    if (merge) this.history.executeMerged(command, { key: merge });
+    else this.history.execute(command);
   }
   refuse(message) {
     this.error = message;
@@ -2816,14 +2917,15 @@ var VideoEditorController = class {
   }
   /**
    * 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, label = "Edit video", options = {}) {
     const reason = this.readOnlyReason();
     if (reason) return this.refuse(reason);
     const result = applyVideoEdits(this.project, edits);
     if (!result.ok) return options.dryRun ? result : this.refuse(result.error);
-    if (!options.dryRun) this.commit(label, result.project);
+    if (!options.dryRun) this.commit(label, result.project, options.merge);
     return result;
   }
   /** Opens a project (JSON or object). `clearHistory` drops the undo stack (opening a file); otherwise it is one undo step. */
@@ -2923,6 +3025,181 @@ var VideoEditorController = class {
     if (!this.selection.length) return this.refuse("Select clips to delete first.");
     return this.apply({ op: "delete_clips", clips: [...this.selection], ripple: options.ripple }, options.ripple ? "Ripple delete" : "Delete clips");
   }
+  // -----------------------------------------------------------------------------------------
+  // Effects
+  // -----------------------------------------------------------------------------------------
+  /** The registered effects provider, or `null`. */
+  get effectsProvider() {
+    return this.effects.provider;
+  }
+  /** Registers (or with `null` removes) the effects provider. Not an edit: no undo step. */
+  setEffectsProvider(provider) {
+    this.effects.set(provider);
+  }
+  /** Registers `provider` and returns a function that removes it again (if it is still the one set). */
+  useEffects(provider) {
+    return this.effects.use(provider);
+  }
+  /** The provider's description of an effect, checked for `place` (rejects without a provider or for an unknown id). */
+  async describeEffect(effect, place) {
+    const d = await this.effects.require().describe(effect);
+    if (place) checkVideoEffectPlace(d, place);
+    return d;
+  }
+  refused(message) {
+    return this.refuse(message);
+  }
+  async effectEdit(run, merge) {
+    const reason = this.readOnlyReason();
+    if (reason) return this.refused(reason);
+    let plan;
+    try {
+      plan = await run();
+    } catch (error) {
+      if (isEffectError(error) || error instanceof Error) return this.refused(error.message);
+      throw error;
+    }
+    const result = this.apply(plan.edit, plan.label, { merge });
+    if (!result.ok) return result;
+    return { ...result, clip: plan.clip, ...plan.effect ? { effect: plan.effect() } : {} };
+  }
+  clipOrThrow(id) {
+    const at = findVideoClip(this.project, id);
+    if (!at) throw new Error(`There is no clip "${id}"; list_applied_effects or get_video_project lists the clips.`);
+    return at.clip;
+  }
+  /**
+   * 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, effect, options = {}) {
+    return this.effectEdit(async () => {
+      const current = this.clipOrThrow(clip);
+      const d = await this.describeEffect(effect, "clip");
+      const values = checkVideoEffectValues(d, options.values, { keyframes: true });
+      const stack = [...current.effects ?? []];
+      const taken = new Set(stack.map((e) => e.id));
+      let n = 1;
+      while (taken.has(`fx${n}`)) n++;
+      const added = { id: `fx${n}`, effect: d.id, provider: this.effects.require().id, name: d.name, values };
+      if (options.enabled === false) added.enabled = false;
+      if (options.opacity !== void 0) added.opacity = options.opacity;
+      const index = options.index ?? stack.length;
+      if (!(Number.isInteger(index) && index >= 0 && index <= stack.length)) throw new Error(`"index" must be a whole number from 0 to ${stack.length}.`);
+      stack.splice(index, 0, added);
+      return { edit: { op: "update_clip", clip, set: { effects: stack } }, label: `Add effect ${d.name}`, clip, effect: () => added };
+    });
+  }
+  /**
+   * 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, instance, changes, options = {}) {
+    return this.effectEdit(async () => {
+      const current = this.clipOrThrow(clip);
+      const stack = [...current.effects ?? []];
+      const i = stack.findIndex((e) => e.id === instance);
+      if (i < 0) throw new Error(`Clip "${clip}" has no effect "${instance}"; its effects are ${stack.map((e) => `"${e.id}" (${e.name ?? e.effect})`).join(", ") || "none"}.`);
+      const was = stack[i];
+      const next = { ...was };
+      if (changes.values) {
+        const d = await this.describeEffect(was.effect);
+        const reset = Object.keys(changes.values).filter((k) => changes.values[k] === null);
+        const given = Object.fromEntries(Object.entries(changes.values).filter(([, v]) => v !== null));
+        const base = { ...was.values ?? {} };
+        for (const k of reset) {
+          if (!(k in d.controls.properties)) throw new Error(`"${k}" is not a control of "${d.id}"; its controls are ${Object.keys(d.controls.properties).join(", ")}.`);
+          base[k] = d.defaults[k];
+        }
+        next.values = checkVideoEffectValues(d, given, { base, keyframes: true });
+      }
+      if (changes.enabled !== void 0) {
+        if (changes.enabled) delete next.enabled;
+        else next.enabled = false;
+      }
+      if (changes.opacity !== void 0) next.opacity = changes.opacity;
+      stack.splice(i, 1);
+      const index = changes.index ?? i;
+      if (!(Number.isInteger(index) && index >= 0 && index <= stack.length)) throw new Error(`"index" must be a whole number from 0 to ${stack.length}.`);
+      stack.splice(index, 0, next);
+      return { edit: { op: "update_clip", clip, set: { effects: stack } }, label: `Change effect ${was.name ?? was.effect}`, clip, effect: () => next };
+    }, options.merge);
+  }
+  /** Removes an effect from a clip's stack (works without a provider, so placeholders can be cleared). One undo step. */
+  removeClipEffect(clip, instance) {
+    const reason = this.readOnlyReason();
+    if (reason) return this.refused(reason);
+    const at = findVideoClip(this.project, clip);
+    if (!at) return this.refused(`There is no clip "${clip}".`);
+    const stack = at.clip.effects ?? [];
+    const was = stack.find((e) => e.id === instance);
+    if (!was) return this.refused(`Clip "${clip}" has no effect "${instance}"; its effects are ${stack.map((e) => `"${e.id}"`).join(", ") || "none"}.`);
+    const rest = stack.filter((e) => e !== was);
+    const result = rest.length ? this.apply({ op: "update_clip", clip, set: { effects: rest } }, `Remove effect ${was.name ?? was.effect}`) : this.apply({ op: "update_clip", clip, remove: ["effects"] }, `Remove effect ${was.name ?? was.effect}`);
+    return result.ok ? { ...result, clip, effect: was } : result;
+  }
+  /**
+   * 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, effect, options = {}) {
+    return this.effectEdit(async () => {
+      this.clipOrThrow(clip);
+      const d = await this.describeEffect(effect, "transition");
+      const values = checkVideoEffectValues(d, options.values);
+      const duration = options.duration ?? d.duration ?? 1e3;
+      return { edit: { op: "set_transition", clip, transition: { type: "effect", duration, effect: { effect: d.id, provider: this.effects.require().id, name: d.name, values } } }, label: `Transition ${d.name}`, clip };
+    });
+  }
+  /**
+   * 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, effect, options = {}) {
+    return this.effectEdit(async () => {
+      const d = await this.describeEffect(effect, "generator");
+      const values = checkVideoEffectValues(d, options.values, { keyframes: true });
+      const duration = options.duration ?? d.duration ?? 5e3;
+      const label = `Add ${d.name}`;
+      const clipId = options.id ?? "";
+      return {
+        edit: { op: "add_clip", track, mode: options.mode, ripple: options.ripple, clip: { type: "effect", ...options.id ? { id: options.id } : {}, effect: d.id, provider: this.effects.require().id, name: options.name ?? d.name, values, start: options.start, duration } },
+        label,
+        clip: clipId
+      };
+    }).then((r) => r.ok && !r.clip ? { ...r, clip: r.outcomes[0]?.clip ?? "" } : r);
+  }
+  /**
+   * 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, part, values, options = {}) {
+    return this.effectEdit(async () => {
+      const current = this.clipOrThrow(clip);
+      if (part === "generator") {
+        if (current.type !== "effect") throw new Error(`Clip "${clip}" is not an effect clip.`);
+        const d2 = await this.describeEffect(current.effect);
+        return { edit: { op: "update_clip", clip, set: { values: checkVideoEffectValues(d2, values, { base: current.values ?? {}, keyframes: true }) } }, label: `Change ${current.name ?? d2.name}`, clip };
+      }
+      const t = current.transition;
+      if (t?.type !== "effect" || !t.effect) throw new Error(`Clip "${clip}" has no effect transition.`);
+      const d = await this.describeEffect(t.effect.effect);
+      const merged = checkVideoEffectValues(d, values, { base: t.effect.values ?? {} });
+      return { edit: { op: "set_transition", clip, transition: { ...t, effect: { ...t.effect, values: merged } } }, label: `Change transition ${d.name}`, clip };
+    }, options.merge);
+  }
+  /** 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, instance, control, keys) {
+    const current = findVideoClip(this.project, clip)?.clip;
+    const was = current?.effects?.find((e) => e.id === instance);
+    const value = was?.values?.[control];
+    const plain = keys === null ? isVideoKeyframes(value) ? value.keys[0]?.v : value : { keys: [...keys].sort((a, b) => a.t - b.t) };
+    return this.updateClipEffect(clip, instance, { values: { [control]: plain ?? null } });
+  }
   /** What plays at `time` (default: the playhead). */
   frame(time = this.player.currentTime) {
     return videoFrameAt(this.project, time);
@@ -2983,7 +3260,8 @@ var VIDEO_TRANSITION_LABELS = {
   wipe: "Wipe",
   push: "Push",
   slide: "Slide",
-  iris: "Iris"
+  iris: "Iris",
+  effect: "Effect"
 };
 var videoTransitionHasDirection = (type) => type === "wipe" || type === "push" || type === "slide";
 var VIDEO_BLEND_MODE_LABELS = {
@@ -3012,6 +3290,7 @@ function videoClipTint(clip, asset) {
   if (clip.type === "text") return "#a855f7";
   if (clip.type === "sequence") return "#0d9488";
   if (clip.type === "color") return clip.color;
+  if (clip.type === "effect") return "#db2777";
   if (!asset) return "#ef4444";
   return asset.kind === "audio" ? "#10b981" : asset.kind === "image" ? "#f59e0b" : "#3b82f6";
 }
@@ -3020,6 +3299,7 @@ function videoClipLabel(clip, asset, sequence) {
   if (clip.type === "text") return clip.text.split("\n")[0];
   if (clip.type === "color") return clip.color;
   if (clip.type === "sequence") return `Compound: ${sequence?.name ?? clip.sequence}`;
+  if (clip.type === "effect") return `Effect: ${clip.effect}`;
   const base = asset?.name ?? asset?.src.replace(/^.*[\\/]/, "") ?? clip.asset;
   const speed = videoClipSpeed(clip);
   return speed !== 1 ? `${base} (${Math.round(speed * 100)}%)` : base;
@@ -3226,7 +3506,7 @@ var TRANSFORM = object(
 );
 var TRANSITION = object(
   {
-    type: { type: "string", enum: [...VIDEO_TRANSITION_TYPES], description: "crossfade (this clip fades up over the one before), dip (down into a colour and up out of it), wipe (an edge travels across revealing this clip), push (this clip slides in and pushes the one before out), slide (this clip slides in over the one before) or iris (a circle opens from the centre)." },
+    type: { type: "string", enum: VIDEO_TRANSITION_TYPES.filter((t) => t !== "effect"), description: "crossfade (this clip fades up over the one before), dip (down into a colour and up out of it), wipe (an edge travels across revealing this clip), push (this clip slides in and pushes the one before out), slide (this clip slides in over the one before) or iris (a circle opens from the centre). For a transition effect from the effects provider use set_video_effect_transition." },
     duration: { type: "number", exclusiveMinimum: 0, description: "Length in ms, centred on the cut. Every type but dip needs half of it in media past the cut on both sides (handles); a dip needs none." },
     color: COLOR("For dip: the colour passed through (default black)"),
     direction: { type: "string", enum: [...VIDEO_WIPE_DIRECTIONS], description: "For wipe, push and slide: the way the edge or picture travels (default right, coming in from the left)." },
@@ -4007,7 +4287,7 @@ function createVideoEditorToolProvider(controller, options = {}) {
     if (!at) throw new Error(`There is no clip "${id}"; get_video_project lists the clips.`);
     const { clip } = at;
     if (clip.type === "sequence") throw new Error(`Clip "${id}" is a compound clip, which plays its sequence at normal speed; change the speed of the clips inside the sequence instead.`);
-    if (clip.type !== "media") throw new Error(`Clip "${id}" is a ${clip.type === "text" ? "title" : "colour"}, so it has no source to change the speed of; use a video or audio clip.`);
+    if (clip.type !== "media") throw new Error(`Clip "${id}" is a ${clip.type === "text" ? "title" : clip.type === "effect" ? "effect clip" : "colour"}, so it has no source to change the speed of; use a video or audio clip.`);
     if (project().assets.find((a) => a.id === clip.asset)?.kind === "image") throw new Error(`Clip "${id}" is a still, so it has no motion to change the speed of.`);
     return clip;
   };
@@ -4355,6 +4635,178 @@ function createVideoEditorToolProvider(controller, options = {}) {
     }
   };
 }
+
+// src/video-editor/effect-tools.ts
+function videoClipAppliedEffects(clip) {
+  const out = [];
+  const ref = (r) => ({ effect: r.effect, ...r.name ? { name: r.name } : {}, ...r.provider ? { provider: r.provider } : {} });
+  if (clip.type === "effect") out.push({ id: "generator", ...ref(clip), role: "effect clip", enabled: true, values: clip.values ?? {} });
+  if (clip.transition?.type === "effect" && clip.transition.effect) out.push({ id: "transition", ...ref(clip.transition.effect), role: "transition", enabled: true, values: { ...clip.transition.effect.values ?? {} }, duration: clip.transition.duration });
+  (clip.effects ?? []).forEach((e, index) => out.push({ id: e.id, ...ref(e), role: "clip effect", enabled: e.enabled !== false, ...e.opacity !== void 0 ? { opacity: e.opacity } : {}, values: e.values ?? {}, index }));
+  return out;
+}
+var MS2 = (what) => ({ type: "number", minimum: 0, description: `${what}, in milliseconds.` });
+var KEYS2 = {
+  type: "array",
+  minItems: 1,
+  items: {
+    type: "object",
+    properties: {
+      t: { type: "number", description: "Clip-relative time in ms (0 = the clip's start)." },
+      v: { type: "number", description: "The control's value at t, within its range from describe_effect." },
+      ease: { anyOf: [{ type: "string", enum: [...VIDEO_EASE_NAMES] }, { type: "array", items: { type: "number" }, minItems: 4, maxItems: 4 }], description: "How the value moves to the next key: linear (default), hold, ease-in, ease-out, ease-in-out, or CSS cubic-bezier [x1, y1, x2, y2]." }
+    },
+    required: ["t", "v"],
+    additionalProperties: false
+  },
+  description: "Keys in any order (sorted for you), one per time."
+};
+function createVideoEffectsToolProvider(controller, options = {}) {
+  const readOnlyReason = () => {
+    const ro = typeof options.readOnly === "function" ? options.readOnly() : options.readOnly;
+    if (ro) return typeof ro === "string" ? ro : "The video project is read-only.";
+    return controller.readOnlyReason();
+  };
+  const clipOf = (id) => {
+    const at = findVideoClip(controller.getProject(), id);
+    if (!at) {
+      const ids = controller.getProject().tracks.flatMap((t) => t.clips.map((c) => c.id));
+      throw new Error(`There is no clip "${id}"; the clips are ${ids.map((c) => `"${c}"`).join(", ") || "none"} (get_video_project lists them).`);
+    }
+    return at.clip;
+  };
+  const result = (r, target, instance, extra = {}) => {
+    if (!r.ok) throw new Error(r.error);
+    const effects = videoClipAppliedEffects(clipOf(target));
+    const effect = effects.find((e) => e.id === (instance ?? r.effect?.id)) ?? (r.effect ? { id: r.effect.id, effect: r.effect.effect, role: "clip effect", enabled: r.effect.enabled !== false, values: r.effect.values ?? {} } : effects[0]);
+    return { target, effect, effects, ...extra };
+  };
+  return createEffectToolProvider({
+    id: options.id ?? "video-effects",
+    namespace: options.namespace,
+    target: { noun: "clip", id: 'A clip id from get_video_project (e.g. "c1").' },
+    applyUses: ["filter", "overlay"],
+    applyDetails: "Filters change the clip's picture and overlays draw over it, in stack order, on the picture as it comes from the source, before the clip's grade, placement, opacity and blend; numbers may be keyframed (clip-relative ms). Transitions go through set_video_effect_transition and generators or titles through add_video_effect_clip. The preview renders them frame by frame; the ffmpeg export then needs rendered frames (see export_video_ffmpeg).",
+    provider: () => controller.effectsProvider,
+    readOnlyReason,
+    list: (target) => {
+      const clips = target ? [clipOf(target)] : controller.getProject().tracks.flatMap((t) => t.clips);
+      return clips.map((c) => ({ target: c.id, ...c.name ? { name: c.name } : {}, effects: videoClipAppliedEffects(c) })).filter((t) => target || t.effects.length);
+    },
+    apply: async (target, effect, args) => {
+      clipOf(target);
+      return result(await controller.applyClipEffect(target, effect, { values: args.values, index: args.index, enabled: args.enabled, opacity: args.opacity }), target);
+    },
+    update: async (target, instance, changes) => {
+      clipOf(target);
+      if (instance === "generator" || instance === "transition") {
+        const extra = ["enabled", "opacity", "index"].filter((k) => changes[k] !== void 0);
+        if (extra.length) throw new Error(`An ${instance === "generator" ? "effect clip" : "effect transition"} only takes values; change its ${extra.join(", ")} with update_video_clip${instance === "transition" ? " or set_video_effect_transition" : ""}.`);
+        const values = Object.fromEntries(Object.entries(changes.values ?? {}).filter(([, v]) => v !== null));
+        return result(await controller.updateEffectValues(target, instance, values), target, instance);
+      }
+      return result(await controller.updateClipEffect(target, instance, changes), target, instance);
+    },
+    remove: async (target, instance) => {
+      const clip = clipOf(target);
+      const was = videoClipAppliedEffects(clip).find((e) => e.id === instance);
+      if (!was) throw new Error(`Clip "${target}" has no effect "${instance}"; its effects are ${videoClipAppliedEffects(clip).map((e) => `"${e.id}"`).join(", ") || "none"}.`);
+      if (instance === "generator") throw new Error(`"${target}" is an effect clip: its effect is the clip itself. Delete the clip with delete_video_clips.`);
+      if (instance === "transition") {
+        const r2 = controller.apply({ op: "set_transition", clip: target, transition: null }, "Remove transition");
+        if (!r2.ok) throw new Error(r2.error);
+        return { target, effect: was, effects: videoClipAppliedEffects(clipOf(target)) };
+      }
+      const r = controller.removeClipEffect(target, instance);
+      if (!r.ok) throw new Error(r.error);
+      return { target, effect: was, effects: videoClipAppliedEffects(clipOf(target)) };
+    },
+    subscribe: (notify) => controller.subscribe(() => notify()),
+    extraTools: (ctx) => [
+      {
+        name: "add_video_effect_clip",
+        title: "Add an effect clip",
+        description: "Adds a clip drawn by a provider generator, title or overlay effect (search_effects with use generator, title or overlay), filling the frame like a colour clip; transparent effects show the tracks beneath. It can be moved, trimmed, faded, graded and given clip effects like any clip. One undo step. Returns the new clip id and its effect. The ffmpeg export then needs rendered frames.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            track: { type: "string", minLength: 1, description: 'A video track id from get_video_project (e.g. "v1"); earlier tracks draw on top.' },
+            effect: ctx.effectIdSchema(["generator", "title", "overlay"]),
+            start: MS2("Where it starts on the timeline (default: the end of the track)"),
+            duration: { type: "number", exclusiveMinimum: 0, description: "Length in ms (default: the effect's own length, else 5000)." },
+            values: ctx.valuesSchema("Control values over the effect's defaults", true),
+            name: { type: "string", minLength: 1, description: "A label for the clip (default: the effect's name)." },
+            mode: { type: "string", enum: [...VIDEO_PLACEMENT_MODES], description: "What to do with clips already there: refuse (default), overwrite or insert." }
+          },
+          required: ["track", "effect"],
+          additionalProperties: false
+        },
+        annotations: { title: "Add an effect clip", ...ctx.annotations.write },
+        handler: async (args) => {
+          ctx.requireProvider();
+          const r = await controller.addEffectClip(args.track, args.effect, { start: args.start, duration: args.duration, values: args.values, name: args.name, mode: args.mode });
+          if (!r.ok) throw new Error(r.error);
+          return { clip: r.clip, track: args.track, effects: videoClipAppliedEffects(clipOf(r.clip)) };
+        }
+      },
+      {
+        name: "set_video_effect_transition",
+        title: "Set an effect transition",
+        description: `Sets a provider transition effect (search_effects with use transition) into a clip from the clip that ends where it starts on the same track, centred on the cut; like a crossfade it needs half its length in media past the cut on both sides. Replaces any transition there. One undo step. Returns the clip's effects. Remove it with remove_effect (effect "transition") or set_video_transition null.`,
+        inputSchema: {
+          type: "object",
+          properties: {
+            clip: { type: "string", minLength: 1, description: "The incoming clip (the one after the cut), from get_video_project." },
+            effect: ctx.effectIdSchema(["transition"]),
+            duration: { type: "number", exclusiveMinimum: 0, description: "Length in ms, centred on the cut (default: the effect's own length, else 1000)." },
+            values: ctx.valuesSchema("Control values over the effect's defaults (plain values; transitions cannot be keyframed)")
+          },
+          required: ["clip", "effect"],
+          additionalProperties: false
+        },
+        annotations: { title: "Set an effect transition", ...ctx.annotations.writeIdempotent },
+        handler: async (args) => {
+          ctx.requireProvider();
+          const r = await controller.setEffectTransition(args.clip, args.effect, { duration: args.duration, values: args.values });
+          if (!r.ok) throw new Error(r.error);
+          return { clip: args.clip, transition: clipOf(args.clip).transition, effects: videoClipAppliedEffects(clipOf(args.clip)) };
+        }
+      },
+      {
+        name: "set_video_effect_keyframes",
+        title: "Keyframe an effect control",
+        description: "Animates one number control of a clip effect or an effect clip with keys at clip-relative times (ms), or with keys null stops animating it, keeping its value at the clip's start. Values are checked against the control's range from describe_effect. One undo step. Returns the effect.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            clip: { type: "string", minLength: 1, description: "A clip id from list_applied_effects." },
+            effect: { type: "string", minLength: 1, description: `The effect's id on the clip ("fx1", or "generator" for an effect clip's own effect).` },
+            control: { type: "string", minLength: 1, description: "A number control name from describe_effect." },
+            keys: { anyOf: [KEYS2, { type: "null" }], description: "The keys, or null to stop animating the control." }
+          },
+          required: ["clip", "effect", "control", "keys"],
+          additionalProperties: false
+        },
+        annotations: { title: "Keyframe an effect control", ...ctx.annotations.writeIdempotent },
+        handler: async (args) => {
+          ctx.requireProvider();
+          const keys = args.keys;
+          let r;
+          if (args.effect === "generator") {
+            const clip = clipOf(args.clip);
+            if (clip.type !== "effect") throw new Error(`Clip "${args.clip}" is not an effect clip; give the id of one of its effects (list_applied_effects).`);
+            const was = clip.values?.[args.control];
+            const plain = keys === null ? isVideoKeyframes(was) ? was.keys[0]?.v : was : { keys: [...keys].sort((a, b) => a.t - b.t) };
+            if (plain === void 0) throw new Error(`"${args.control}" has no value to keep; give keys instead.`);
+            r = await controller.updateEffectValues(args.clip, "generator", { [args.control]: plain });
+          } else r = await controller.setClipEffectKeyframes(args.clip, args.effect, args.control, keys);
+          if (!r.ok) throw new Error(r.error);
+          return { clip: args.clip, effect: videoClipAppliedEffects(clipOf(args.clip)).find((e) => e.id === args.effect) };
+        }
+      }
+    ]
+  });
+}
 export {
   VIDEO_BLEND_MODES,
   VIDEO_BLEND_MODE_LABELS,
@@ -4367,6 +4819,7 @@ export {
   VIDEO_DEFAULT_TITLE_DURATION,
   VIDEO_EASE_NAMES,
   VIDEO_EDIT_OPS,
+  VIDEO_EFFECT_PLACES,
   VIDEO_FADE_CURVES,
   VIDEO_FADE_CURVE_LABELS,
   VIDEO_FITS,
@@ -4390,6 +4843,7 @@ export {
   VIDEO_WIPE_DIRECTIONS,
   VideoAudioPeaksCache,
   VideoEditorController,
+  VideoEffectsEngine,
   VideoFrameCache,
   VideoLutCache,
   VideoPreviewEngine,
@@ -4401,9 +4855,12 @@ export {
   applyVideoLut,
   applyVideoLutToPixels,
   buildVideoAudioPeaks,
+  checkVideoEffectPlace,
+  checkVideoEffectValues,
   checkVideoProject,
   checkVideoTimeRemap,
   createVideoEditorToolProvider,
+  createVideoEffectsToolProvider,
   createVideoElementDecoder,
   createVideoProject,
   decodeVideoAudioPeaks,
@@ -4425,16 +4882,21 @@ export {
   isVideoDropFrameRate,
   isVideoKeyframes,
   mergeVideoRanges,
+  mixEffectPixels,
   nextFreeVideoSlot,
   normalizeVideoGrade,
   normalizeVideoGradeLut,
   normalizeVideoWord,
+  overEffectPixels,
   parseVideoAnimatable,
   parseVideoAsset,
   parseVideoAssetProxies,
   parseVideoClip,
   parseVideoClipAnimation,
+  parseVideoClipEffects,
   parseVideoCubeLut,
+  parseVideoEffectRef,
+  parseVideoEffectValues,
   parseVideoGrade,
   parseVideoGradeLut,
   parseVideoKeyframes,
@@ -4455,6 +4917,7 @@ export {
   probeVideoMedia,
   readVideoScopesPanel,
   removeVideoKey,
+  renderVideoFrameExact,
   resolveVideoPreviewScale,
   retimeVideoAnimatable,
   setVideoKey,
@@ -4482,7 +4945,9 @@ export {
   videoClipAnimated,
   videoClipAnimationProperties,
   videoClipAnimationSpans,
+  videoClipAppliedEffects,
   videoClipBefore,
+  videoClipEffectUses,
   videoClipEnd,
   videoClipHandles,
   videoClipKeyframes,
@@ -4503,9 +4968,13 @@ export {
   videoDropTracks,
   videoEaseBezier,
   videoEaseProgress,
+  videoEffectFrameTime,
+  videoEffectLayerKey,
+  videoEffectValuesAt,
   videoExposureNotes,
   videoExposureStats,
   videoFadeCurveGain,
+  videoFfmpegUnsupportedEffects,
   videoFrameAt,
   videoFrameCacheKey,
   videoFrameDuration,
@@ -4535,6 +5004,8 @@ export {
   videoKeyframeToggleEdit,
   videoKeyframeValueEdit,
   videoKeysOf,
+  videoLayersUseEffects,
+  videoLayersWithoutTransitionEffects,
   videoLuma,
   videoLumaWaveform,
   videoLutEdits,
@@ -4546,6 +5017,7 @@ export {
   videoPeakDb,
   videoPreviewSrc,
   videoProjectDuration,
+  videoProjectEffects,
   videoProjectHasProxies,
   videoProjectSvg,
   videoProxyFfmpeg,