@pixerate/editor 0.230.0 → 0.231.0

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

@@ -23,6 +23,7 @@ export * from './grade.cjs';
 export * from './lut.cjs';
 export * from './scopes.cjs';
 export * from './clip-animation.cjs';
+export * from './camera.cjs';
 export * from './transcript.cjs';
 export * from './transcript-controller.cjs';
 export * from './remap.cjs';
@@ -35,6 +36,7 @@ export * from './preview.cjs';
 export * from './controller.cjs';
 export * from './tools.cjs';
 export * from './effect-tools.cjs';
+export * from './camera-tools.cjs';
 export * from './dialogue-tools.cjs';
 export * from './music-tools.cjs';
 export * from './effect-authoring.cjs';

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

@@ -23,6 +23,7 @@ export * from './grade.js';
 export * from './lut.js';
 export * from './scopes.js';
 export * from './clip-animation.js';
+export * from './camera.js';
 export * from './transcript.js';
 export * from './transcript-controller.js';
 export * from './remap.js';
@@ -35,6 +36,7 @@ export * from './preview.js';
 export * from './controller.js';
 export * from './tools.js';
 export * from './effect-tools.js';
+export * from './camera-tools.js';
 export * from './dialogue-tools.js';
 export * from './music-tools.js';
 export * from './effect-authoring.js';

package/dist/video-editor/index.js

@@ -111,6 +111,7 @@ import {
   videoGradeSvgFilter,
   videoHourFrames,
   videoIrisRadius,
+  videoKeyTimesProblem,
   videoKeyframeBreakpoints,
   videoKeyframeFfmpegExpr,
   videoKeysOf,
@@ -148,15 +149,20 @@ import {
   videoTransitionEase,
   videoValueAt,
   videoWipeRect
-} from "../chunk-ONNNNGNS.js";
+} from "../chunk-CSM5T6SE.js";
 import "../chunk-EHLOCVWB.js";
 import {
   namedWithSuggestion
 } from "../chunk-TYCJGFCF.js";
 import {
+  CAMERA_MOVE_MAX_MS,
   EffectsSlot,
+  cameraMoveField,
+  cameraMoveParts,
   createEffectToolProvider,
-  isEffectError
+  isEffectError,
+  resolveCameraMoveSpec,
+  sampleEffectCameraMove
 } from "../chunk-TCZ2J7PR.js";
 import "../chunk-V2ZCJRDM.js";
 import {
@@ -228,7 +234,10 @@ function parseVideoKeyframes(v, path, { min, max } = {}) {
     for (const key of Object.keys(k)) if (!["t", "v", "ease"].includes(key)) fail(`${at}.${key}`, "is not a key field (t, v, ease)");
     return compact({ t: num(k.t, `${at}.t`), v: num(k.v, `${at}.v`, { min, max }), ease: parseVideoEase(k.ease, `${at}.ease`) });
   });
-  for (let i = 1; i < keys.length; i++) if (!(keys[i].t > keys[i - 1].t)) fail(`${path}.keys[${i}].t`, `must be later than the key before (${keys[i - 1].t} ms); keys go in time order, one per time`);
+  for (let i = 1; i < keys.length; i++) {
+    if (keys[i].t < keys[i - 1].t) fail(`${path}.keys[${i}].t`, `must not be before the key before (${keys[i - 1].t} ms); keys go in time order`);
+    if (i >= 2 && keys[i].t === keys[i - 2].t) fail(`${path}.keys[${i}].t`, `is the third key at ${keys[i].t} ms; a time takes one key, or two for a jump (the value just before, then the value after)`);
+  }
   return { keys };
 }
 function parseVideoAnimatable(v, path, range = {}) {
@@ -253,6 +262,7 @@ function parseVideoTimeRemap(v, speed, path) {
   const remap = parseVideoAnimatable(v, path, { optional: true, min: 0 });
   if (typeof remap === "number" || remap === void 0) return fail(path, "must be keyframes { keys: [{ t, v, ease }] } (v: ms of source after the in point)");
   if (speed !== void 0 && speed !== 1) fail(path, 'cannot be used with a speed; a ramp sets the speed itself (remove "speed")');
+  for (let i = 1; i < remap.keys.length; i++) if (remap.keys[i].t === remap.keys[i - 1].t) fail(`${path}.keys[${i}].t`, `must be later than the key before (${remap.keys[i - 1].t} ms); a speed ramp has one key per time`);
   try {
     checkVideoTimeRemap(remap, path);
   } catch (e) {
@@ -414,6 +424,42 @@ function parseVideoAssetProxies(v, path) {
   }
   return out.length ? out : void 0;
 }
+var CAMERA_KEYS = ["in", "during", "from", "framing", "base"];
+function parseCameraFraming(v, path) {
+  if (v === void 0) return void 0;
+  if (!isObject(v)) return fail(path, "must be an object { zoom, x, y }");
+  const unknown = Object.keys(v).find((k) => !["zoom", "x", "y"].includes(k));
+  if (unknown) fail(`${path}.${unknown}`, "is not a framing field (zoom, x, y)");
+  return compact({ zoom: num(v.zoom, `${path}.zoom`, { optional: true, positive: true }), x: num(v.x, `${path}.x`, { optional: true }), y: num(v.y, `${path}.y`, { optional: true }) });
+}
+function parseCameraMove(v, path, hold) {
+  if (v === void 0) return void 0;
+  if (typeof v === "string" && v) return v;
+  if (!isObject(v) || typeof v.move !== "string" || !v.move) return fail(path, "must be a camera move's id, or { move, ms, preset, values }");
+  const unknown = Object.keys(v).find((k) => !["move", "ms", "preset", "values"].includes(k));
+  if (unknown) fail(`${path}.${unknown}`, "is not a camera move field (move, ms, preset, values)");
+  if (hold && v.ms !== void 0) fail(`${path}.ms`, "is not for a hold move, which plays across the rest of the clip");
+  if (v.values !== void 0 && !isObject(v.values)) fail(`${path}.values`, "must be an object of the move's control values");
+  return compact({ move: v.move, ms: num(v.ms, `${path}.ms`, { optional: true, min: 0 }), preset: str(v.preset, `${path}.preset`, true), values: v.values });
+}
+function parseVideoClipCamera(v, path) {
+  if (v === void 0) return void 0;
+  if (!isObject(v)) return fail(path, "must be an object { in, during, from, framing, base }");
+  const unknown = Object.keys(v).find((k) => !CAMERA_KEYS.includes(k));
+  if (unknown) fail(`${path}.${unknown}`, `is not a camera field; use ${CAMERA_KEYS.join(", ")}`);
+  if (v.in === void 0 && v.during === void 0) fail(path, 'names no move: give "in", "during" or both, or remove the camera');
+  if (!isObject(v.base)) fail(`${path}.base`, "must be the clip's transform before the moves were baked, { x, y, scale, rotation } as numbers");
+  const base = v.base;
+  const extra = Object.keys(base).find((k) => !["x", "y", "scale", "rotation"].includes(k));
+  if (extra) fail(`${path}.base.${extra}`, "is not a transform field (x, y, scale, rotation)");
+  return compact({
+    in: parseCameraMove(v.in, `${path}.in`, false),
+    during: parseCameraMove(v.during, `${path}.during`, true),
+    from: parseCameraFraming(v.from, `${path}.from`),
+    framing: parseCameraFraming(v.framing, `${path}.framing`),
+    base: compact({ x: num(base.x, `${path}.base.x`, { optional: true }), y: num(base.y, `${path}.base.y`, { optional: true }), scale: num(base.scale, `${path}.base.scale`, { optional: true, min: 0 }), rotation: num(base.rotation, `${path}.base.rotation`, { optional: true }) })
+  });
+}
 function parseVideoClip(v, path = "clip") {
   if (!isObject(v)) return fail(path, "must be an object");
   const type = oneOf(v.type ?? "media", VIDEO_CLIP_TYPES, `${path}.type`, false);
@@ -433,7 +479,8 @@ function parseVideoClip(v, path = "clip") {
     fadeOut: num(v.fadeOut, `${path}.fadeOut`, { optional: true, min: 0 }),
     transition: parseVideoTransition(v.transition, `${path}.transition`),
     effects: parseVideoClipEffects(v.effects, `${path}.effects`),
-    mask: parseVideoClipMask(v.mask, `${path}.mask`)
+    mask: parseVideoClipMask(v.mask, `${path}.mask`),
+    camera: parseVideoClipCamera(v.camera, `${path}.camera`)
   };
   if (type === "media")
     return compact({
@@ -597,6 +644,7 @@ var VIDEO_ISSUE_CODES = [
   "animations-too-long",
   "animation-keyed",
   "keyframes-outside-clip",
+  "camera-stale",
   "unknown-duration",
   "unused-asset",
   "unused-sequence",
@@ -663,6 +711,17 @@ function checkVideoProject(project) {
         if (keyed.length)
           issues.push({ code: "animation-keyed", severity: "note", ...at, message: `Clip "${clip.id}"'s ${a.effect} ${which === "animateIn" ? "entrance" : "exit"} leaves ${keyed.join(", ")} alone, because the clip keys ${keyed.length > 1 ? "them" : "it"} itself; remove those keyframes or the animation.` });
       }
+      if (clip.camera) {
+        const last = Math.max(0, ...VIDEO_TRANSFORM_PROPERTIES.flatMap((p) => videoKeysOf(clip.transform?.[p]).map((k) => k.t)));
+        const frame = 1e3 / (project.fps || 30);
+        if (last > 0 && Math.abs(last - clip.duration) > frame + VIDEO_TIME_EPSILON)
+          issues.push({
+            code: "camera-stale",
+            severity: "warning",
+            ...at,
+            message: `Clip "${clip.id}"'s camera moves were baked for ${Math.round(last)} ms but the clip is ${Math.round(clip.duration)} ms, so ${last < clip.duration ? "the camera stops early" : "the end of the move is cut off"}; set the move again (set_clip_camera_move) to re-bake it.`
+          });
+      }
       for (const { property, keys } of videoClipKeyframes(clip)) {
         const outside = keys.filter((k) => k.t < -VIDEO_TIME_EPSILON || k.t > clip.duration + VIDEO_TIME_EPSILON);
         if (outside.length)
@@ -784,7 +843,7 @@ function retimeClipKeys(clip, fn) {
     if (isVideoKeyframes(v)) a.set(fn(v));
   }
 }
-var OPTIONAL_CLIP_FIELDS = ["name", "effects", "mask", "scope", "targetTrack", "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 OPTIONAL_CLIP_FIELDS = ["name", "effects", "mask", "camera", "scope", "targetTrack", "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) {
@@ -1256,7 +1315,7 @@ var Editor = class {
         } else {
           if (!Array.isArray(e.keys) || !e.keys.length) refuse('"keys" must be a list of at least one { t, v, ease } (or null to remove the ramp).');
           const remap = parseVideoTimeRemap({ keys: e.keys }, void 0, "keys");
-          remap.keys = sortVideoKeys(remap.keys);
+          remap.keys = sortVideoKeys(remap.keys, { jumps: false });
           checkVideoTimeRemap(remap, "keys");
           const span = videoTimeRemapSpan(remap);
           if (asset.duration !== void 0 && (media.in ?? 0) + span.to > asset.duration + VIDEO_TIME_EPSILON)
@@ -2160,7 +2219,7 @@ function planVideoEdits(project, input) {
   const result = applyVideoEdits(project, input.edits);
   if (!result.ok) return { ok: false, error: result.error };
   const known = new Set(checkVideoProject(project).map(videoIssueKey));
-  const summary = { ...diffVideoProjects(project, result.project), newIssues: result.issues.filter((i) => !known.has(videoIssueKey(i))), edits: input.edits.length };
+  const summary2 = { ...diffVideoProjects(project, result.project), newIssues: result.issues.filter((i) => !known.has(videoIssueKey(i))), edits: input.edits.length };
   const plan = {
     id: input.id ?? "plan",
     title: input.title.trim(),
@@ -2168,7 +2227,7 @@ function planVideoEdits(project, input) {
     ...input.source ? { source: input.source } : {},
     edits: structuredClone([...input.edits]),
     ...input.ranges?.length ? { ranges: input.ranges.map((r) => ({ ...r })) } : {},
-    summary
+    summary: summary2
   };
   return { ok: true, plan, project: result.project };
 }
@@ -2514,23 +2573,23 @@ var VideoPreviewPixels = class {
   next(time, timeout = 5e3) {
     const matches = () => this.drawnAt && this.drawnAt.complete && Math.abs(this.drawnAt.time - time) < 0.5;
     return new Promise((resolve, reject) => {
-      const done = (fn) => {
+      const done2 = (fn) => {
         clearTimeout(timer);
         off();
         fn();
       };
       const check = () => {
-        if (!this.reader) return done(() => reject(new Error("The preview was closed before it drew the frame.")));
+        if (!this.reader) return done2(() => reject(new Error("The preview was closed before it drew the frame.")));
         if (!matches()) return;
         try {
           const snap = this.read();
-          done(() => snap ? resolve(snap) : reject(new Error("The preview has no pixels to read.")));
+          done2(() => snap ? resolve(snap) : reject(new Error("The preview has no pixels to read.")));
         } catch (e) {
-          done(() => reject(e));
+          done2(() => reject(e));
         }
       };
       const off = this.subscribe(check);
-      const timer = setTimeout(() => done(() => reject(new Error(`The preview did not finish drawing ${Math.round(time)} ms within ${timeout} ms; its media may still be loading or may have failed to load. Try again, or check the asset sources.`))), timeout);
+      const timer = setTimeout(() => done2(() => reject(new Error(`The preview did not finish drawing ${Math.round(time)} ms within ${timeout} ms; its media may still be loading or may have failed to load. Try again, or check the asset sources.`))), timeout);
       check();
     });
   }
@@ -2555,6 +2614,88 @@ function readVideoScopesPanel(feed, kinds = VIDEO_SCOPE_KINDS, options = {}) {
   return { ok: true, time: snap.time, complete: snap.complete, images, stats, notes: videoExposureNotes(stats) };
 }
 
+// src/video-editor/camera.ts
+function videoCameraView(framing, stage) {
+  const zoom = framing?.zoom ?? 1;
+  return { zoom, scrollX: stage.width / (2 * zoom) - (stage.width / 2 + (framing?.x ?? 0)), scrollY: stage.height / (2 * zoom) - (stage.height / 2 + (framing?.y ?? 0)) };
+}
+function videoTransformOfView(view, base, stage) {
+  const cx = stage.width / 2;
+  const cy = stage.height / 2;
+  const px = (cx + (base.x ?? 0) + view.scrollX) * view.zoom - cx;
+  const py = (cy + (base.y ?? 0) + view.scrollY) * view.zoom - cy;
+  const roll = view.roll ?? 0;
+  const a = roll * Math.PI / 180;
+  const tidy = (n) => Math.round(n * 1e3) / 1e3 || 0;
+  return {
+    x: tidy(px * Math.cos(a) - py * Math.sin(a)),
+    y: tidy(px * Math.sin(a) + py * Math.cos(a)),
+    scale: tidy((base.scale ?? 1) * view.zoom),
+    rotation: tidy((base.rotation ?? 0) + roll)
+  };
+}
+function videoCameraBase(clip) {
+  if (clip.camera) return clip.camera.base;
+  const t = clip.transform ?? {};
+  const keyed = VIDEO_TRANSFORM_PROPERTIES.filter((p) => isVideoKeyframes(t[p]));
+  if (keyed.length)
+    throw new Error(`Clip "${clip.id}" keys its ${keyed.join(", ")}, which a camera move would replace; remove those keyframes first (set_video_keyframes with keys null).`);
+  return Object.fromEntries(VIDEO_TRANSFORM_PROPERTIES.flatMap((p) => typeof t[p] === "number" ? [[p, t[p]]] : []));
+}
+async function bakeVideoClipCamera(clip, camera, project, provider) {
+  const stage = { width: project.width, height: project.height };
+  const fps = project.fps > 0 ? project.fps : 30;
+  const to = videoCameraView(camera.framing, stage);
+  const notes = [];
+  const cuts = [];
+  const windows = {};
+  let keys = [];
+  let inMs = 0;
+  const moveIn = cameraMoveParts(camera.in);
+  if (moveIn) {
+    const { description } = await resolveCameraMoveSpec(provider, moveIn, "transition");
+    inMs = moveIn.ms ?? description.camera.durationMs;
+    if (inMs > clip.duration) throw new Error(`The move into clip "${clip.id}" takes ${inMs} ms, longer than the clip (${clip.duration} ms); give a shorter "ms" or lengthen the clip.`);
+    const sample = await sampleEffectCameraMove(provider, moveIn.move, { from: videoCameraView(camera.from, stage), to, ms: inMs, stage, fps, values: moveIn.values });
+    keys.push(...sample.keys);
+    if (sample.cut !== void 0) cuts.push(sample.cut);
+    windows.in = { start: 0, end: inMs };
+  }
+  const moveDuring = cameraMoveParts(camera.during);
+  const holdMs = clip.duration - inMs;
+  if (moveDuring && holdMs > 0) {
+    await resolveCameraMoveSpec(provider, moveDuring, "hold");
+    const at = keys.length ? keys[keys.length - 1].view : to;
+    const sample = await sampleEffectCameraMove(provider, moveDuring.move, { from: at, to: at, ms: holdMs, stage, fps, values: moveDuring.values });
+    const shifted = sample.keys.map((k) => ({ t: k.t + inMs, view: k.view }));
+    if (keys.length && shifted.length && sameView(keys[keys.length - 1].view, shifted[0].view)) shifted.shift();
+    keys.push(...shifted);
+    if (sample.cut !== void 0) cuts.push(sample.cut + inMs);
+    windows.during = { start: inMs, end: clip.duration };
+  } else if (moveDuring) notes.push(`The move into the clip fills it, so the hold move "${moveDuring.move}" has no time to play; shorten the move in or lengthen the clip.`);
+  if (!keys.length) keys = [{ t: 0, view: to }];
+  const flat = keys.some((k) => k.view.tilt || k.view.turn || k.view.blur && k.view.blur > 0);
+  if (flat) notes.push("A clip transform has no tilt, turn or motion blur, so those parts of the move are left out; the zoom, pan and roll are kept.");
+  const base = videoCameraBase(clip);
+  const transforms = keys.map((k) => ({ t: Math.round(k.t * 1e3) / 1e3, value: videoTransformOfView(k.view, base, stage) }));
+  const transform = {};
+  for (const p of VIDEO_TRANSFORM_PROPERTIES) {
+    const out = [];
+    for (const { t, value } of transforms) {
+      const last = out[out.length - 1];
+      const prev = out[out.length - 2];
+      if (last && prev && last.v === value[p] && prev.v === value[p] && prev.t !== last.t) out[out.length - 1] = { t, v: value[p] };
+      else out.push({ t, v: value[p] });
+    }
+    transform[p] = out.length > 1 && out.some((k) => k.v !== out[0].v) ? { keys: out } : out[0].v;
+  }
+  return { transform, cuts, windows, notes };
+}
+var sameView = (a, b) => ["zoom", "scrollX", "scrollY", "tilt", "turn", "roll", "blur"].every((k) => Math.abs((a[k] ?? 0) - (b[k] ?? 0)) < 1e-9);
+function videoClipCameraMove(clip, role) {
+  return cameraMoveParts(clip?.camera?.[role === "transition" ? "in" : "during"]);
+}
+
 // src/video-editor/transcript-controller.ts
 var TranscriptVideoController = class {
   constructor(controller, options = {}) {
@@ -3758,6 +3899,87 @@ var VideoEditorController = class _VideoEditorController {
       return { edit: { op: "update_clip", clip, set: { effects: stack } }, label: `Change effect ${was.name ?? was.effect}`, clip, effect: () => next };
     }, options.merge);
   }
+  /** The provider's camera moves for a role (`transition` into a clip, `hold` while it plays), or all of them. Empty without camera support. */
+  async cameraMoves(role) {
+    const provider = this.effects.provider;
+    if (!provider?.capabilities.supportsCamera || !provider.cameraView) return [];
+    return (await provider.list({ kind: "camera" })).filter((e) => e.kind === "camera" && e.camera && (!role || e.camera.role === role));
+  }
+  cameraClip(id) {
+    const at = findVideoClip(this.project, id);
+    if (!at) {
+      const ids = this.project.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).`);
+    }
+    if (at.track.kind === "audio") throw new Error(`Clip "${id}" is on audio track "${at.track.id}" and has no picture for a camera to move over.`);
+    if (at.clip.type === "adjustment") throw new Error(`Clip "${id}" is an adjustment clip, which has no picture of its own for a camera to move over.`);
+    return at.clip;
+  }
+  async cameraEdit(clipId, camera, label, merge) {
+    const clip = this.cameraClip(clipId);
+    const base = videoCameraBase(clip);
+    if (!camera) {
+      const restored = Object.keys(base).length ? { transform: base } : {};
+      const r2 = this.apply({ op: "update_clip", clip: clipId, set: restored, remove: ["camera", ...Object.keys(base).length ? [] : ["transform"]] }, label, { merge });
+      if (!r2.ok) return r2;
+      return { ok: true, clip: clipId, camera: null, keys: { x: 0, y: 0, scale: 0, rotation: 0 }, cuts: [], windows: {}, notes: [] };
+    }
+    const bake = await bakeVideoClipCamera(clip, camera, this.project, this.effects.require());
+    const r = this.apply({ op: "update_clip", clip: clipId, set: { camera, transform: bake.transform } }, label, { merge });
+    if (!r.ok) return r;
+    const keys = Object.fromEntries(VIDEO_TRANSFORM_PROPERTIES.map((p) => [p, videoKeysOf(bake.transform[p]).length]));
+    return { ok: true, clip: clipId, camera, keys, cuts: bake.cuts, windows: bake.windows, notes: bake.notes };
+  }
+  /**
+   * Sets the camera move a clip plays into (`transition`: from `from` to `framing` from the
+   * clip's start) or while it holds (`hold`: across the rest of the clip at `framing`), and bakes
+   * the clip's moves into its x, y, scale and rotation keys at the project's frame rate, keeping a
+   * cut's two keys. The move is checked first (role, preset, values; a preset's values and a move
+   * in's length are written out). A clip whose transform is keyed by hand is refused. One undo step.
+   */
+  async setClipCameraMove(clip, role, spec, options = {}) {
+    const reason = this.readOnlyReason();
+    if (reason) return this.refused(reason);
+    try {
+      const current = this.cameraClip(clip);
+      const { spec: parts, description } = await resolveCameraMoveSpec(this.effects.require(), spec, role);
+      const move = role === "transition" && parts.ms === void 0 ? { ...parts, ms: description.camera.durationMs } : parts;
+      const simple = move.ms === void 0 && move.preset === void 0 && move.values === void 0;
+      const camera = { ...current.camera ?? { base: videoCameraBase(current) }, [cameraMoveField(role)]: simple ? move.move : move };
+      for (const key of ["from", "framing"]) {
+        if (options[key] === null) delete camera[key];
+        else if (options[key] !== void 0) camera[key] = options[key];
+      }
+      if (camera.from && !camera.in) throw new Error('"from" is where a move in starts; set a transition move too, or leave "from" out.');
+      return await this.cameraEdit(clip, camera, `${role === "hold" ? "Hold move" : "Camera move"} ${description.name}`, options.merge);
+    } catch (error) {
+      if (isEffectError(error) || error instanceof Error) return this.refused(error.message);
+      throw error;
+    }
+  }
+  /**
+   * Removes a clip's camera move for a role and bakes what is left (which needs the provider);
+   * with no move left the transform goes back to what it was before the moves. One undo step.
+   */
+  async clearClipCameraMove(clip, role) {
+    const reason = this.readOnlyReason();
+    if (reason) return this.refused(reason);
+    try {
+      const current = this.cameraClip(clip);
+      const field = cameraMoveField(role);
+      const other = field === "in" ? "during" : "in";
+      if (current.camera?.[field] === void 0)
+        throw new Error(`Clip "${clip}" has no camera "${field}" move to clear${current.camera?.[other] !== void 0 ? `; it has a "${other}" move (role ${role === "hold" ? "transition" : "hold"})` : ""}.`);
+      const camera = { ...current.camera };
+      delete camera[field];
+      if (field === "in") delete camera.from;
+      const left = camera.in !== void 0 || camera.during !== void 0;
+      return await this.cameraEdit(clip, left ? camera : null, role === "hold" ? "Clear hold move" : "Clear camera move");
+    } catch (error) {
+      if (isEffectError(error) || error instanceof Error) return this.refused(error.message);
+      throw error;
+    }
+  }
   /** 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();
@@ -4041,7 +4263,7 @@ function probeVideoMedia(src, kind, timeout = 15e3) {
   return new Promise((resolve, reject) => {
     if (typeof document === "undefined") return reject(new Error("Media can only be probed in a browser."));
     const timer = setTimeout(() => reject(new Error(`"${src}" took too long to load.`)), timeout);
-    const done = (probe) => {
+    const done2 = (probe) => {
       clearTimeout(timer);
       resolve(probe);
     };
@@ -4051,7 +4273,7 @@ function probeVideoMedia(src, kind, timeout = 15e3) {
     };
     if (kind === "image") {
       const img = new Image();
-      img.onload = () => done({ kind, width: img.naturalWidth, height: img.naturalHeight });
+      img.onload = () => done2({ kind, width: img.naturalWidth, height: img.naturalHeight });
       img.onerror = failed;
       img.src = src;
       return;
@@ -4061,7 +4283,7 @@ function probeVideoMedia(src, kind, timeout = 15e3) {
     el.onloadedmetadata = () => {
       const duration = Number.isFinite(el.duration) ? Math.round(el.duration * 1e3) : void 0;
       const v = el;
-      done({ kind, ...duration ? { duration } : {}, ...kind === "video" && v.videoWidth ? { width: v.videoWidth, height: v.videoHeight } : {} });
+      done2({ kind, ...duration ? { duration } : {}, ...kind === "video" && v.videoWidth ? { width: v.videoWidth, height: v.videoHeight } : {} });
     };
     el.onerror = failed;
     el.src = src;
@@ -5526,6 +5748,90 @@ function createVideoEditorToolProvider(controller, options = {}) {
   }, options.playbackSurface);
 }
 
+// src/video-editor/camera-tools.ts
+var ROLE = {
+  type: "string",
+  enum: ["transition", "hold"],
+  description: 'transition: the move the camera makes into the clip from its start (a glide, whip pan, punch zoom, cut), from "from" to "framing". hold: the move it makes across the rest of the clip (a Ken Burns drift, a crash zoom), at "framing".'
+};
+var FRAMING = (what) => ({
+  anyOf: [
+    {
+      type: "object",
+      properties: {
+        zoom: { type: "number", exclusiveMinimum: 0, description: "Zoom on the picture as placed (1 = the whole picture, 2 = half of it fills the frame). Default 1." },
+        x: { type: "number", description: "Point the camera centres on, pixels right of the frame's centre. Default 0." },
+        y: { type: "number", description: "Point the camera centres on, pixels below the frame's centre. Default 0." }
+      },
+      additionalProperties: false
+    },
+    { type: "null" }
+  ],
+  description: `${what} null removes it (the whole picture). Left out, the clip keeps the one it has.`
+});
+var summary = (e) => ({ id: e.id, name: e.name, role: e.camera.role, durationMs: e.camera.durationMs, ...e.camera.cut !== void 0 ? { cut: e.camera.cut } : {}, ...e.description ? { description: e.description } : {} });
+var done = (r) => {
+  if (!r.ok) throw new Error(r.error);
+  const { ok: _ok, ...rest } = r;
+  return { ...rest, ...rest.notes.length ? {} : { notes: void 0 } };
+};
+function videoCameraMoveTools(controller, ctx) {
+  return [
+    {
+      name: "list_video_camera_moves",
+      title: "List camera moves for clips",
+      description: "Lists the effects provider's camera moves, for a role or both: { available, moves: [{ id, name, role, durationMs, cut (0\u20131 of the way through where the view jumps), description }] }. Give an id to set_clip_camera_move; describe_effect gives a move's controls and presets. Without a provider that has camera moves it returns available: false and the reason.",
+      inputSchema: { type: "object", properties: { role: ROLE }, additionalProperties: false },
+      annotations: { title: "List camera moves for clips", ...ctx.annotations.read },
+      handler: async (args) => {
+        const provider = controller.effectsProvider;
+        if (!provider?.capabilities.supportsCamera || !provider.cameraView)
+          return { available: false, reason: provider ? `${provider.name} has no camera moves (capabilities.supportsCamera is not set).` : "No effects provider is registered, so there are no camera moves.", moves: [] };
+        return { available: true, provider: provider.name, moves: (await controller.cameraMoves(args.role)).map(summary) };
+      }
+    },
+    {
+      name: "set_clip_camera_move",
+      title: "Set a clip's camera move",
+      description: `Plays a camera move from list_video_camera_moves on a clip's picture, the clip being the shot: role transition moves from "from" to "framing" over "ms" from the clip's start; role hold plays across the rest of the clip at "framing". The clip's moves are baked into its x, y, scale and rotation keys, one per frame at the project's fps, and a move that cuts keeps two keys at the cut so nothing tweens across it. A clip whose transform is keyed by hand is refused (clear those keys first). The move is checked first: a wrong-role id, an unknown preset or values outside its controls are refused with the moves or presets that fit. One undo step. Returns { clip, camera, keys (per property), cuts (clip ms), windows ({ in, during }: when each move plays), notes (what a clip transform cannot show: tilt, turn, blur) }. After trimming the clip, set the move again to re-bake it.`,
+      inputSchema: {
+        type: "object",
+        properties: {
+          clip: { type: "string", minLength: 1, description: "A clip id with a picture, from get_video_project." },
+          role: ROLE,
+          move: { type: "string", minLength: 1, description: "A camera move id of that role from list_video_camera_moves." },
+          ms: { type: "number", minimum: 0, maximum: CAMERA_MOVE_MAX_MS, description: `How long a transition takes, ms (default the move's durationMs; at most the clip's length). Not for a hold, which plays across the rest of the clip.` },
+          preset: { type: "string", minLength: 1, description: "A preset of the move by name, from describe_effect." },
+          values: ctx.valuesSchema("Control values over the move's defaults (and the preset's), from describe_effect"),
+          from: FRAMING("Where a transition starts."),
+          framing: FRAMING("Where a transition arrives and a hold plays.")
+        },
+        required: ["clip", "role", "move"],
+        additionalProperties: false
+      },
+      annotations: { title: "Set a clip's camera move", ...ctx.annotations.writeIdempotent },
+      handler: async (args) => {
+        ctx.requireProvider();
+        const spec = { move: args.move, ...args.ms !== void 0 ? { ms: args.ms } : {}, ...args.preset !== void 0 ? { preset: args.preset } : {}, ...args.values !== void 0 ? { values: args.values } : {} };
+        return done(await controller.setClipCameraMove(args.clip, args.role, spec, { from: args.from, framing: args.framing }));
+      }
+    },
+    {
+      name: "clear_clip_camera_move",
+      title: "Clear a clip's camera move",
+      description: "Removes a clip's camera move for a role and re-bakes the other one (which needs the provider); with no move left the clip's transform goes back to what it was before the moves. One undo step. Returns { clip, camera (null when none is left), keys, cuts, windows }.",
+      inputSchema: {
+        type: "object",
+        properties: { clip: { type: "string", minLength: 1, description: "A clip id from get_video_project." }, role: ROLE },
+        required: ["clip", "role"],
+        additionalProperties: false
+      },
+      annotations: { title: "Clear a clip's camera move", ...ctx.annotations.destructive },
+      handler: async (args) => done(await controller.clearClipCameraMove(args.clip, args.role))
+    }
+  ];
+}
+
 // src/video-editor/effect-tools.ts
 function videoClipAppliedEffects(clip) {
   const out = [];
@@ -5616,6 +5922,7 @@ function createVideoEffectsToolProvider(controller, options = {}) {
     },
     subscribe: (notify) => controller.subscribe(() => notify()),
     extraTools: (ctx) => [
+      ...videoCameraMoveTools(controller, ctx),
       {
         name: "add_video_effect_clip",
         title: "Add an effect clip",
@@ -6232,6 +6539,7 @@ export {
   applyVideoGrade,
   applyVideoLut,
   applyVideoLutToPixels,
+  bakeVideoClipCamera,
   buildVideoAudioPeaks,
   checkVideoEffectPlace,
   checkVideoEffectValues,
@@ -6283,6 +6591,7 @@ export {
   parseVideoAssetProxies,
   parseVideoClip,
   parseVideoClipAnimation,
+  parseVideoClipCamera,
   parseVideoClipEffects,
   parseVideoClipMask,
   parseVideoCubeLut,
@@ -6337,6 +6646,9 @@ export {
   videoAudioPeaksDuration,
   videoAuthorableEffects,
   videoCacheEvictions,
+  videoCameraBase,
+  videoCameraMoveTools,
+  videoCameraView,
   videoChroma,
   videoClipAfter,
   videoClipAnimated,
@@ -6344,6 +6656,7 @@ export {
   videoClipAnimationSpans,
   videoClipAppliedEffects,
   videoClipBefore,
+  videoClipCameraMove,
   videoClipEffectDocument,
   videoClipEffectUses,
   videoClipEnd,
@@ -6403,6 +6716,7 @@ export {
   videoHourFrames,
   videoIrisRadius,
   videoIssueKey,
+  videoKeyTimesProblem,
   videoKeyframeBreakpoints,
   videoKeyframeFfmpegExpr,
   videoKeyframeRows,
@@ -6463,6 +6777,7 @@ export {
   videoTranscriptEdit,
   videoTranscriptTrack,
   videoTransformAt,
+  videoTransformOfView,
   videoTransitionAudioCurve,
   videoTransitionEase,
   videoTransitionHasDirection,

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

@@ -17,7 +17,7 @@ export interface VideoKey {
     ease?: VideoEase;
 }
 export interface VideoKeyframes {
-    /** In time order, at least one. */
+    /** In time order, at least one. Two keys at one time make a jump: the value just before, then the value from there on. */
     keys: VideoKey[];
 }
 /** A number, or keyframes for it. */
@@ -52,8 +52,15 @@ export declare function retimeVideoAnimatable<T extends VideoAnimatable | undefi
  * into two curves that trace the same path, so the two halves play exactly as the whole did.
  */
 export declare function splitVideoAnimatable<T extends VideoAnimatable | undefined>(prop: T, at: number): [T, T];
-/** The keys sorted by time, refusing two at the same time. */
-export declare function sortVideoKeys(keys: readonly VideoKey[]): VideoKey[];
+/**
+ * The keys sorted by time. Two keys may share a time (a jump, as at a camera move's cut: the
+ * value just before, then the value from there on) unless `jumps` is false; three never can.
+ */
+export declare function sortVideoKeys(keys: readonly VideoKey[], options?: {
+    jumps?: boolean;
+}): VideoKey[];
+/** What is wrong with sorted keys' times (more than two at a time, or two when `jumps` is false), or null. */
+export declare function videoKeyTimesProblem(keys: readonly VideoKey[], jumps?: boolean): string | null;
 /**
  * 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".

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

@@ -17,7 +17,7 @@ export interface VideoKey {
     ease?: VideoEase;
 }
 export interface VideoKeyframes {
-    /** In time order, at least one. */
+    /** In time order, at least one. Two keys at one time make a jump: the value just before, then the value from there on. */
     keys: VideoKey[];
 }
 /** A number, or keyframes for it. */
@@ -52,8 +52,15 @@ export declare function retimeVideoAnimatable<T extends VideoAnimatable | undefi
  * into two curves that trace the same path, so the two halves play exactly as the whole did.
  */
 export declare function splitVideoAnimatable<T extends VideoAnimatable | undefined>(prop: T, at: number): [T, T];
-/** The keys sorted by time, refusing two at the same time. */
-export declare function sortVideoKeys(keys: readonly VideoKey[]): VideoKey[];
+/**
+ * The keys sorted by time. Two keys may share a time (a jump, as at a camera move's cut: the
+ * value just before, then the value from there on) unless `jumps` is false; three never can.
+ */
+export declare function sortVideoKeys(keys: readonly VideoKey[], options?: {
+    jumps?: boolean;
+}): VideoKey[];
+/** What is wrong with sorted keys' times (more than two at a time, or two when `jumps` is false), or null. */
+export declare function videoKeyTimesProblem(keys: readonly VideoKey[], jumps?: boolean): string | null;
 /**
  * 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".

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

@@ -1,8 +1,8 @@
 import { type VideoAnimatable, type VideoKeyframes } from './keyframes.cjs';
-import { type VideoClipMask, type VideoAsset, type VideoAssetProxy, type VideoClip, type VideoClipEffect, type VideoEffectRef, type VideoEffectValues, type VideoClipAnimation, type VideoGrade, type VideoGradeLut, type VideoMarker, type VideoProject, type VideoSequence, type VideoTrack, type VideoTranscriptWord, type VideoTransform, type VideoTransition } from './types.cjs';
+import { type VideoClipMask, type VideoClipCamera, type VideoAsset, type VideoAssetProxy, type VideoClip, type VideoClipEffect, type VideoEffectRef, type VideoEffectValues, type VideoClipAnimation, type VideoGrade, type VideoGradeLut, type VideoMarker, type VideoProject, type VideoSequence, type VideoTrack, type VideoTranscriptWord, type VideoTransform, type VideoTransition } from './types.cjs';
 /**
- * Keyframes `{ keys: [{ t, v, ease }] }`: at least one key, in strictly increasing time (clip-relative
- * ms), each value within `range`.
+ * Keyframes `{ keys: [{ t, v, ease }] }`: at least one key, in time order (clip-relative ms; two
+ * at one time make a jump), each value within `range`.
  */
 export declare function parseVideoKeyframes(v: unknown, path: string, { min, max }?: {
     min?: number;
@@ -35,6 +35,8 @@ export declare function parseVideoClipEffects(v: unknown, path: string): VideoCl
 export declare function parseVideoTranscriptWords(v: unknown, path: string): VideoTranscriptWord[] | undefined;
 export declare function parseVideoAsset(v: unknown, path?: string): VideoAsset;
 export declare function parseVideoAssetProxies(v: unknown, path: string): VideoAssetProxy[] | undefined;
+/** A clip's camera moves `{ in, during, from, framing, base }` (see `VideoClipCamera`). */
+export declare function parseVideoClipCamera(v: unknown, path: string): VideoClipCamera | undefined;
 export declare function parseVideoClip(v: unknown, path?: string): VideoClip;
 export declare function parseVideoTrack(v: unknown, path?: string): VideoTrack;
 /** A nested sequence `{ id, name, tracks }` (see `VideoSequence`). */