Skip to content

Open source CapCut alternative.

TypeScript

feat(site): add group camera, blur and motion blur [rebuild]

David Leca3499775595
diff --git a/site/packages/effects-kit/src/camera.test.ts b/site/packages/effects-kit/src/camera.test.ts
new file mode 100644
index 00000000..ee28ce4f
--- /dev/null
+++ b/site/packages/effects-kit/src/camera.test.ts
@@ -0,0 +1,238 @@
+import { describe, expect, test } from "bun:test";
+import {
+ cameraPoint,
+ capStreak,
+ composeCamera,
+ REST_CAMERA,
+ shiftCamera,
+ STREAK_MAX,
+ STREAK_MIN,
+ STREAK_TAPS_MAX,
+ streakTaps,
+ worldPoint,
+ MOTION_BLUR_FRAME,
+} from "./camera";
+import { EASE_IDS, easeAt } from "./ease";
+import { elementLook } from "./elementFx";
+import { cameraAt, evalOverlayFrame, isOverlayAnimated, poseAt, type OverlayKey } from "./keys";
+
+const el = (over: Record<string, unknown> = {}) => ({ start: 0, end: 4, x: 0.5, y: 0.5, ...over });
+const key = (t: number, over: Partial<OverlayKey> = {}): OverlayKey => ({
+ t,
+ x: 0.5,
+ y: 0.5,
+ scale: 1,
+ rotation: 0,
+ opacity: 1,
+ ...over,
+});
+const state = (x: number, y: number) => ({ x, y, dx: 0, dy: 0, scale: 1, rotation: 0, opacity: 1 });
+
+describe("easing presets", () => {
+ test("every curve starts at 0 and lands on 1", () => {
+ for (const id of EASE_IDS) {
+ expect(easeAt(id, 0)).toBeCloseTo(0, 9);
+ expect(easeAt(id, 1)).toBeCloseTo(1, 9);
+ }
+ });
+
+ test("every curve only moves forward", () => {
+ for (const id of EASE_IDS) {
+ let last = -1;
+ for (let i = 0; i <= 50; i++) {
+ const v = easeAt(id, i / 50);
+ expect(v).toBeGreaterThanOrEqual(last - 1e-12);
+ last = v;
+ }
+ }
+ });
+
+ test("in starts slow, out starts fast, in-out passes the middle at the middle", () => {
+ expect(easeAt("power2.in", 0.25)).toBeCloseTo(0.0625);
+ expect(easeAt("power3.out", 0.25)).toBeGreaterThan(0.5);
+ for (const id of ["sine.inOut", "power2.inOut", "power3.inOut"] as const) {
+ expect(easeAt(id, 0.5)).toBeCloseTo(0.5);
+ expect(easeAt(id, 0.25) + easeAt(id, 0.75)).toBeCloseTo(1);
+ }
+ expect(easeAt(undefined, 0.3)).toBeCloseTo(0.3);
+ });
+
+ test("a key's ease shapes the pose out of it", () => {
+ const o = el({ kf: [key(0, { x: 0.2, ease: "power2.in" }), key(2, { x: 0.6 })] });
+ expect(poseAt(o, 1).x).toBeCloseTo(0.2 + 0.4 * 0.25);
+ const linear = el({ kf: [key(0, { x: 0.2 }), key(2, { x: 0.6 })] });
+ expect(poseAt(linear, 1).x).toBeCloseTo(0.4);
+ });
+});
+
+describe("camera composition", () => {
+ test("the camera at rest changes nothing", () => {
+ const s = { ...state(0.3, 0.7), dx: 5, dy: -2, scale: 1.5, rotation: 12 };
+ expect(composeCamera(s, REST_CAMERA, 16 / 9)).toEqual(s);
+ });
+
+ test("a push centers the point it looks at and spreads the rest from it", () => {
+ const cam = { x: 0.25, y: 0.3, scale: 2, rotation: 0 };
+ const at = composeCamera(state(0.25, 0.3), cam, 16 / 9);
+ expect(at.x).toBeCloseTo(0.5);
+ expect(at.y).toBeCloseTo(0.5);
+ expect(at.scale).toBeCloseTo(2);
+ const beside = composeCamera(state(0.35, 0.3), cam, 16 / 9);
+ expect(beside.x).toBeCloseTo(0.5 + 0.2);
+ });
+
+ test("a roll turns the board rigidly on a wide frame", () => {
+ const aspect = 16 / 9;
+ const cam = { x: 0.5, y: 0.5, scale: 1, rotation: 90 };
+ // A point right of center, by a frame height's worth of pixels, swings
+ // to below center by the same pixels.
+ const p = composeCamera({ ...state(0.5 + 0.2 / aspect, 0.5), dx: 10, dy: 0 }, cam, aspect);
+ expect(p.x).toBeCloseTo(0.5);
+ expect(p.y).toBeCloseTo(0.7);
+ expect(p.rotation).toBeCloseTo(90);
+ // The preset's travel turns with the world.
+ expect(p.dx).toBeCloseTo(0);
+ expect(p.dy).toBeCloseTo(10);
+ });
+
+ test("the element's own pose composes inside the camera", () => {
+ const cam = { x: 0.4, y: 0.6, scale: 1.5, rotation: 30 };
+ const own = { ...state(0.2, 0.8), scale: 2, rotation: 15 };
+ const c = composeCamera(own, cam, 1);
+ expect(c.scale).toBeCloseTo(3);
+ expect(c.rotation).toBeCloseTo(45);
+ const back = worldPoint(cam, c.x, c.y, 1);
+ expect(back.x).toBeCloseTo(0.2);
+ expect(back.y).toBeCloseTo(0.8);
+ });
+
+ test("screen and world points invert each other at any aspect", () => {
+ const cam = { x: 0.62, y: 0.41, scale: 2.7, rotation: -37 };
+ for (const aspect of [9 / 16, 1, 16 / 9]) {
+ const s = cameraPoint(cam, 0.13, 0.88, aspect);
+ const w = worldPoint(cam, s.x, s.y, aspect);
+ expect(w.x).toBeCloseTo(0.13);
+ expect(w.y).toBeCloseTo(0.88);
+ }
+ });
+
+ test("camera keys ease, and zoom moves by ratio", () => {
+ const cam = {
+ kf: [
+ { t: 0, x: 0.2, y: 0.5, scale: 1, rotation: 0, ease: "sine.inOut" as const },
+ { t: 2, x: 0.8, y: 0.5, scale: 4, rotation: 0 },
+ ],
+ };
+ const mid = cameraAt(cam, 1);
+ expect(mid.x).toBeCloseTo(0.5);
+ expect(mid.scale).toBeCloseTo(2); // the geometric middle of 1× and 4×
+ expect(cameraAt(cam, 0.5).x).toBeLessThan(0.35); // eased in
+ expect(cameraAt(cam, 9).x).toBeCloseTo(0.8); // held after the last key
+ });
+
+ test("the evaluator films a member through its group's camera", () => {
+ const o = el({ x: 0.25, y: 0.3, camera: { kf: [{ t: 0, x: 0.25, y: 0.3, scale: 2, rotation: 0 }] } });
+ expect(isOverlayAnimated(o)).toBe(true);
+ const f = evalOverlayFrame(o, 1, 16 / 9);
+ expect(f.x).toBeCloseTo(0.5);
+ expect(f.scale).toBeCloseTo(2);
+ expect(() => evalOverlayFrame(o, 1)).toThrow();
+ });
+
+ test("a shifted camera reads the same moment on a member's new clock", () => {
+ const cam = { kf: [{ t: 1, x: 0.2, y: 0.5, scale: 1, rotation: 0 }, { t: 3, x: 0.8, y: 0.5, scale: 1, rotation: 0 }] };
+ // The member's start moved 0.5s later; its keys come 0.5s sooner.
+ expect(cameraAt(shiftCamera(cam, -0.5), 1.5).x).toBeCloseTo(cameraAt(cam, 2).x);
+ });
+});
+
+describe("blur on the pose track", () => {
+ test("a key carries blur, and one without takes the element's", () => {
+ const o = el({ blur: 4, kf: [key(0, { blur: 0 }), key(2)] });
+ expect(poseAt(o, 0).blur ?? 0).toBeCloseTo(0);
+ expect(poseAt(o, 1).blur).toBeCloseTo(2);
+ expect(poseAt(o, 3).blur).toBeCloseTo(4);
+ expect(evalOverlayFrame(o, 1).blur).toBeCloseTo(2);
+ });
+
+ test("a still blurred element draws through the evaluator", () => {
+ expect(isOverlayAnimated(el({ blur: 3 }))).toBe(true);
+ expect(isOverlayAnimated(el({ blur: 0 }))).toBe(false);
+ });
+});
+
+describe("motion blur", () => {
+ const moving = (over: Record<string, unknown> = {}) =>
+ el({ motionBlur: 0.5, kf: [key(0, { x: 0.2 }), key(2, { x: 0.8 })], ...over });
+
+ test("the streak is the screen travel over the exposure", () => {
+ const aspect = 16 / 9;
+ const f = evalOverlayFrame(moving(), 1, aspect);
+ // 0.6 of a 1920-design-px frame over 2s, for half a 30fps frame.
+ const speed = (0.6 * 1080 * aspect) / 2;
+ expect(f.streak!.x).toBeCloseTo(speed * 0.5 * MOTION_BLUR_FRAME, 3);
+ expect(f.streak!.y).toBeCloseTo(0);
+ });
+
+ test("a still element stays sharp", () => {
+ expect(evalOverlayFrame(moving(), 3, 1).streak).toBeUndefined();
+ expect(evalOverlayFrame(el({ motionBlur: 0.5 }), 1, 1).streak).toBeUndefined();
+ });
+
+ test("the streak grows with speed and with the shutter", () => {
+ const slow = evalOverlayFrame(moving({ kf: [key(0, { x: 0.4 }), key(2, { x: 0.6 })] }), 1, 1).streak!.x;
+ const fast = evalOverlayFrame(moving(), 1, 1).streak!.x;
+ expect(fast / slow).toBeCloseTo(3);
+ const wide = evalOverlayFrame(moving({ motionBlur: 1 }), 1, 1).streak!.x;
+ expect(wide / fast).toBeCloseTo(2);
+ });
+
+ test("the first frame streaks like the rest", () => {
+ const a = evalOverlayFrame(moving(), 0, 1).streak!.x;
+ const b = evalOverlayFrame(moving(), 1, 1).streak!.x;
+ expect(a).toBeCloseTo(b);
+ });
+
+ test("the camera's motion blur streaks only the camera's move", () => {
+ const camera = {
+ motionBlur: 0.5,
+ kf: [
+ { t: 0, x: 0.3, y: 0.5, scale: 1, rotation: 0 },
+ { t: 2, x: 0.7, y: 0.5, scale: 1, rotation: 0 },
+ ],
+ };
+ // The element's own travel (down) is left sharp; the camera pans right,
+ // so the world slides left on screen.
+ const o = el({ camera, kf: [key(0, { y: 0.2 }), key(2, { y: 0.8 })] });
+ const f = evalOverlayFrame(o, 1, 1);
+ expect(f.streak!.x).toBeLessThan(0);
+ expect(f.streak!.y).toBeCloseTo(0);
+ // Its own switch streaks everything it does on screen.
+ const own = evalOverlayFrame({ ...o, motionBlur: 0.5 }, 1, 1);
+ expect(own.streak!.y).toBeGreaterThan(0);
+ expect(own.streak!.x).toBeLessThan(0);
+ });
+
+ test("streak length is capped and short streaks vanish", () => {
+ expect(capStreak(STREAK_MIN / 2, 0)).toBeNull();
+ const long = capStreak(1000, 1000)!;
+ expect(Math.hypot(long.x, long.y)).toBeCloseTo(STREAK_MAX);
+ expect(long.x).toBeCloseTo(long.y);
+ expect(capStreak(10, 0)).toEqual({ x: 10, y: 0 });
+ });
+
+ test("taps follow the streak length within their bounds", () => {
+ expect(streakTaps(0)).toBe(0);
+ expect(streakTaps(STREAK_MIN)).toBe(2);
+ expect(streakTaps(20)).toBeGreaterThan(streakTaps(8));
+ expect(streakTaps(STREAK_MAX)).toBe(STREAK_TAPS_MAX);
+ });
+
+ test("the look scales to output px and is null for a sharp still frame", () => {
+ expect(elementLook({}, 2)).toBeNull();
+ const look = elementLook({ blur: 3, streak: { x: 10, y: 0 } }, 2)!;
+ expect(look.blur).toBeCloseTo(6);
+ expect(look.streakX).toBeCloseTo(20);
+ expect(look.taps).toBe(streakTaps(10));
+ });
+});
diff --git a/site/packages/effects-kit/src/camera.ts b/site/packages/effects-kit/src/camera.ts
new file mode 100644
index 00000000..a1021013
--- /dev/null
+++ b/site/packages/effects-kit/src/camera.ts
@@ -0,0 +1,178 @@
+/**
+ * A camera over a world of elements, and the blur that comes with moving it.
+ *
+ * Explainer graphics are often a set of cards laid out like a board, with a
+ * camera gliding over them: it steps from one card to the next, pushes onto
+ * the one being talked about, pulls back. Moving every card's own keys to fake
+ * that is a lot of bookkeeping, and the cards drift apart the moment one key
+ * is off. So a group carries one camera pose track, and every element in the
+ * group is drawn through it — the cards keep their own places and poses, and
+ * the camera moves the whole board as one.
+ *
+ * A camera pose names the world point that sits at the frame's center (`x`,
+ * `y`, fractions of the frame, like an element's position), how far the view
+ * is zoomed in (`scale`, 2 shows the world twice as large), and how far the
+ * world is turned clockwise about the frame's center (`rotation`, degrees).
+ * The camera at rest — centered, unzoomed, level — changes nothing.
+ *
+ * Every member stores the same camera, with key times in seconds from its own
+ * start like its pose keys, so the camera travels with the group when it is
+ * moved on the timeline and every renderer reads it off the element alone.
+ */
+
+import type { EaseId } from "./ease";
+
+/** A camera pose at `t` seconds into the element. `ease` is the curve out of
+ * this key into the next. */
+export interface CameraKey {
+ t: number;
+ x: number;
+ y: number;
+ scale: number;
+ rotation: number;
+ ease?: EaseId;
+}
+
+/** A group's camera, as each member carries it. `motionBlur` streaks what the
+ * camera's movement does to the picture (shutter, 0..1; absent = off). */
+export interface GroupCamera {
+ kf: CameraKey[];
+ motionBlur?: number;
+}
+
+export interface CameraPose {
+ x: number;
+ y: number;
+ scale: number;
+ rotation: number;
+}
+
+export const REST_CAMERA: CameraPose = { x: 0.5, y: 0.5, scale: 1, rotation: 0 };
+
+/** How far the camera may pull back and push in. */
+export const CAMERA_SCALE_MIN = 0.25;
+export const CAMERA_SCALE_MAX = 8;
+
+/** The softest an element may be, design px at the 1080 short side. */
+export const ELEMENT_BLUR_MAX = 60;
+
+/** Whether the camera has any keys to move by. */
+export function hasCameraKeys(cam: GroupCamera | undefined): cam is GroupCamera {
+ return !!cam && cam.kf.length > 0;
+}
+
+/**
+ * Where a world point lands on screen under the camera. Positions are frame
+ * fractions; the turn happens in a square space (x scaled by the aspect), so
+ * the board turns rigidly on a frame of any shape.
+ */
+export function cameraPoint(
+ cam: CameraPose,
+ x: number,
+ y: number,
+ aspect: number
+): { x: number; y: number } {
+ const v = cameraVector(cam, (x - cam.x) * aspect, y - cam.y);
+ return { x: 0.5 + v.x / aspect, y: 0.5 + v.y };
+}
+
+/** A world-space offset (any unit, same on both axes) as seen on screen: the
+ * camera's zoom and turn, without its travel. */
+export function cameraVector(cam: CameraPose, dx: number, dy: number): { x: number; y: number } {
+ const r = (cam.rotation * Math.PI) / 180;
+ const c = Math.cos(r) * cam.scale;
+ const s = Math.sin(r) * cam.scale;
+ return { x: c * dx - s * dy, y: s * dx + c * dy };
+}
+
+/** The world point that shows at a screen point: the inverse of
+ * `cameraPoint`. A drag in the preview moves an element by this. */
+export function worldPoint(
+ cam: CameraPose,
+ x: number,
+ y: number,
+ aspect: number
+): { x: number; y: number } {
+ const v = worldVector(cam, (x - 0.5) * aspect, y - 0.5);
+ return { x: cam.x + v.x / aspect, y: cam.y + v.y };
+}
+
+/** A screen-space offset as a world-space one: the inverse of `cameraVector`. */
+export function worldVector(cam: CameraPose, dx: number, dy: number): { x: number; y: number } {
+ const r = (-cam.rotation * Math.PI) / 180;
+ const k = 1 / Math.max(1e-6, cam.scale);
+ const c = Math.cos(r) * k;
+ const s = Math.sin(r) * k;
+ return { x: c * dx - s * dy, y: s * dx + c * dy };
+}
+
+/**
+ * An element's frame state seen through the camera: its center moves to
+ * where the camera shows it, the preset's travel turns and grows with the
+ * world, and the camera's zoom and turn add to the element's own.
+ */
+export function composeCamera<
+ S extends { x: number; y: number; dx: number; dy: number; scale: number; rotation: number },
+>(state: S, cam: CameraPose, aspect: number): S {
+ const p = cameraPoint(cam, state.x, state.y, aspect);
+ const d = cameraVector(cam, state.dx, state.dy);
+ return {
+ ...state,
+ x: p.x,
+ y: p.y,
+ dx: d.x,
+ dy: d.y,
+ scale: state.scale * cam.scale,
+ rotation: state.rotation + cam.rotation,
+ };
+}
+
+/** The camera with every key moved `by` seconds — what keeps a member on the
+ * group's clock when its own start moves under it (a left trim, a split). */
+export function shiftCamera(cam: GroupCamera, by: number): GroupCamera {
+ return { ...cam, kf: cam.kf.map((k) => ({ ...k, t: Math.round((k.t + by) * 1000) / 1000 })) };
+}
+
+// --- Motion blur ---------------------------------------------------------
+//
+// A real shutter stays open for part of each frame, so anything that moves
+// while it is open smears along its path. Here the exposure is a share of a
+// 30fps frame — 0.5 is the classic half-open shutter — and the smear is the
+// distance the element's center travels on screen while it is open. The
+// exposure is measured in seconds, so a 24fps export, a 60fps export and the
+// preview all draw the same streak for the same move. A still frame travels
+// nowhere and stays sharp.
+
+/** The frame the shutter amount is a share of, seconds. */
+export const MOTION_BLUR_FRAME = 1 / 30;
+/** A streak shorter than this, design px, draws nothing: the frame is sharp. */
+export const STREAK_MIN = 0.75;
+/** The longest streak, design px. A whip faster than this reads as a blur
+ * either way, and the cap bounds what a frame costs to draw. */
+export const STREAK_MAX = 96;
+/** Design px between two taps along a streak. */
+export const STREAK_TAP_SPACING = 4;
+/** The most copies one streak is drawn from. */
+export const STREAK_TAPS_MAX = 24;
+
+/** The streak for a screen displacement over the exposure (design px): the
+ * displacement itself, capped in length, or null when it is too short to see. */
+export function capStreak(dx: number, dy: number): { x: number; y: number } | null {
+ const len = Math.hypot(dx, dy);
+ if (!(len >= STREAK_MIN)) return null;
+ const k = len > STREAK_MAX ? STREAK_MAX / len : 1;
+ return { x: dx * k, y: dy * k };
+}
+
+/** How many copies a streak of `len` design px is drawn from: enough that
+ * neighbours sit a few pixels apart, never fewer than two. Counted in design
+ * px so a preview and a 4K export split the same streak the same way. */
+export function streakTaps(len: number): number {
+ if (!(len >= STREAK_MIN)) return 0;
+ return Math.max(2, Math.min(STREAK_TAPS_MAX, Math.ceil(len / STREAK_TAP_SPACING) + 1));
+}
+
+/** Design px of frame for an aspect (width / height), short side 1080. */
+export function designFrame(aspect: number): { width: number; height: number } {
+ return aspect >= 1 ? { width: 1080 * aspect, height: 1080 } : { width: 1080, height: 1080 / aspect };
+}
diff --git a/site/packages/effects-kit/src/ease.ts b/site/packages/effects-kit/src/ease.ts
new file mode 100644
index 00000000..4857f3b3
--- /dev/null
+++ b/site/packages/effects-kit/src/ease.ts
@@ -0,0 +1,69 @@
+/**
+ * Named easing curves for key tracks.
+ *
+ * A key's `ease` is the curve out of that key and into the next; a key with
+ * none moves at a constant rate. The names follow the family/direction
+ * convention motion designers already speak — `sine.inOut` is the gentle
+ * glide a camera takes between two cards, `power3.out` the quick start that
+ * settles, `power3.inOut` the whip. The list is the one source the pose
+ * track, the camera, the inspector menus and the chat tools all read.
+ */
+
+export const EASE_IDS = [
+ "linear",
+ "sine.in",
+ "sine.out",
+ "sine.inOut",
+ "power2.in",
+ "power2.out",
+ "power2.inOut",
+ "power3.in",
+ "power3.out",
+ "power3.inOut",
+] as const;
+
+export type EaseId = (typeof EASE_IDS)[number];
+
+export const EASE_LABELS: Record<EaseId, string> = {
+ linear: "Linear",
+ "sine.in": "Sine in",
+ "sine.out": "Sine out",
+ "sine.inOut": "Sine in-out",
+ "power2.in": "Power2 in",
+ "power2.out": "Power2 out",
+ "power2.inOut": "Power2 in-out",
+ "power3.in": "Power3 in",
+ "power3.out": "Power3 out",
+ "power3.inOut": "Power3 in-out",
+};
+
+export const isEaseId = (v: unknown): v is EaseId => EASE_IDS.includes(v as EaseId);
+
+/** Progress `p` (0..1) through the named curve. Every curve starts at 0 and
+ * lands on 1, so a key is reached exactly on its time whatever the ease. */
+export function easeAt(id: EaseId | undefined, p: number): number {
+ const x = p <= 0 ? 0 : p >= 1 ? 1 : p;
+ switch (id) {
+ case undefined:
+ case "linear":
+ return x;
+ case "sine.in":
+ return 1 - Math.cos((x * Math.PI) / 2);
+ case "sine.out":
+ return Math.sin((x * Math.PI) / 2);
+ case "sine.inOut":
+ return -(Math.cos(Math.PI * x) - 1) / 2;
+ case "power2.in":
+ return x * x;
+ case "power2.out":
+ return 1 - (1 - x) * (1 - x);
+ case "power2.inOut":
+ return x < 0.5 ? 2 * x * x : 1 - Math.pow(-2 * x + 2, 2) / 2;
+ case "power3.in":
+ return x * x * x;
+ case "power3.out":
+ return 1 - Math.pow(1 - x, 3);
+ case "power3.inOut":
+ return x < 0.5 ? 4 * x * x * x : 1 - Math.pow(-2 * x + 2, 3) / 2;
+ }
+}
diff --git a/site/packages/effects-kit/src/elementFx.ts b/site/packages/effects-kit/src/elementFx.ts
new file mode 100644
index 00000000..3bd8e4a9
--- /dev/null
+++ b/site/packages/effects-kit/src/elementFx.ts
@@ -0,0 +1,163 @@
+/**
+ * Drawing an element soft: its blur and its motion streak.
+ *
+ * Both act on the element's posed picture as it lands on screen, so every
+ * renderer does the same three steps: pose the element into a scratch surface
+ * the size of the target, smear that along the streak, and lay the result on
+ * the target through a Gaussian blur. The smear is the picture drawn a few
+ * times along the streak with additive blending at 1/n strength each, which
+ * sums to the exact average of the copies — the box filter a shutter makes.
+ * Additive blending and `filter: blur()` mean the same thing on a browser
+ * canvas and on the server canvas, so the preview, the tab export and the
+ * headless renderers draw the same frame.
+ *
+ * Nothing extra runs for a sharp, still element: `begin` hands back the
+ * target itself and `end` does nothing.
+ */
+
+import { streakTaps } from "./camera";
+
+type Ctx = CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D;
+type Surface = HTMLCanvasElement | OffscreenCanvas;
+
+/** What softens one element on one frame, in output px. */
+export interface ElementLook {
+ /** Gaussian blur radius (the CSS `blur()` length). */
+ blur: number;
+ /** The streak, end to end, centered on the frame's moment. */
+ streakX: number;
+ streakY: number;
+ /** How many copies the streak is drawn from; 0 = no streak. */
+ taps: number;
+}
+
+/** A blur below this many output px is invisible and skipped. */
+const BLUR_FLOOR = 0.1;
+
+/** The look an evaluated frame asks for at `scale` output px per design px,
+ * or null when the element draws sharp. */
+export function elementLook(
+ ev: { blur?: number; streak?: { x: number; y: number } },
+ scale: number
+): ElementLook | null {
+ const blur = (ev.blur ?? 0) * scale;
+ const taps = ev.streak ? streakTaps(Math.hypot(ev.streak.x, ev.streak.y)) : 0;
+ if (blur < BLUR_FLOOR && taps === 0) return null;
+ return {
+ blur: blur < BLUR_FLOOR ? 0 : blur,
+ streakX: taps ? ev.streak!.x * scale : 0,
+ streakY: taps ? ev.streak!.y * scale : 0,
+ taps,
+ };
+}
+
+/**
+ * Draw `src` along the streak onto a cleared `ctx`, with (x, y) the place it
+ * would sit with no streak. The caller's transform applies, so a streak given
+ * in an element's own space smears in that space.
+ */
+export function drawStreak(
+ ctx: Ctx,
+ src: CanvasImageSource,
+ x: number,
+ y: number,
+ look: Pick<ElementLook, "streakX" | "streakY" | "taps">
+): void {
+ const n = look.taps;
+ if (n < 2) {
+ ctx.drawImage(src, x, y);
+ return;
+ }
+ const op = ctx.globalCompositeOperation;
+ const alpha = ctx.globalAlpha;
+ ctx.globalCompositeOperation = "lighter";
+ ctx.globalAlpha = alpha / n;
+ for (let i = 0; i < n; i++) {
+ const f = i / (n - 1) - 0.5;
+ ctx.drawImage(src, x + look.streakX * f, y + look.streakY * f);
+ }
+ ctx.globalCompositeOperation = op;
+ ctx.globalAlpha = alpha;
+}
+
+/**
+ * The scratch a renderer keeps for soft elements: two surfaces, made on first
+ * use and reused frame after frame at the target's size.
+ */
+export class ElementFx {
+ private picture: Surface | null = null;
+ private smear: Surface | null = null;
+ private look: ElementLook | null = null;
+
+ constructor(private make: (w: number, h: number) => Surface) {}
+
+ private fit(s: Surface | null, w: number, h: number): Surface {
+ const width = Math.max(1, Math.round(w));
+ const height = Math.max(1, Math.round(h));
+ if (!s) return this.make(width, height);
+ if (s.width !== width || s.height !== height) {
+ s.width = width;
+ s.height = height;
+ }
+ return s;
+ }
+
+ /** Where to paint the posed element: `ctx` itself when it draws sharp, or a
+ * cleared scratch the size of the target, with an identity transform. */
+ begin(ctx: Ctx, width: number, height: number, look: ElementLook | null): Ctx {
+ this.look = look;
+ if (!look) return ctx;
+ this.picture = this.fit(this.picture, width, height);
+ const c = this.picture.getContext("2d") as Ctx;
+ c.setTransform(1, 0, 0, 1, 0, 0);
+ c.globalAlpha = 1;
+ c.globalCompositeOperation = "source-over";
+ if ("filter" in c) c.filter = "none";
+ c.clearRect(0, 0, this.picture.width, this.picture.height);
+ return c;
+ }
+
+ /** Lay the painted element onto `ctx` with its streak and blur. */
+ end(ctx: Ctx): void {
+ const look = this.look;
+ this.look = null;
+ if (!look || !this.picture) return;
+ let src: Surface = this.picture;
+ if (look.taps >= 2) {
+ this.smear = this.fit(this.smear, src.width, src.height);
+ const s = this.smear.getContext("2d") as Ctx;
+ s.setTransform(1, 0, 0, 1, 0, 0);
+ s.globalAlpha = 1;
+ s.globalCompositeOperation = "source-over";
+ if ("filter" in s) s.filter = "none";
+ s.clearRect(0, 0, this.smear.width, this.smear.height);
+ drawStreak(s, src, 0, 0, look);
+ src = this.smear;
+ }
+ ctx.save();
+ ctx.setTransform(1, 0, 0, 1, 0, 0);
+ ctx.globalAlpha = 1;
+ ctx.globalCompositeOperation = "source-over";
+ if (look.blur > 0 && "filter" in ctx) ctx.filter = `blur(${look.blur.toFixed(2)}px)`;
+ ctx.drawImage(src, 0, 0);
+ ctx.restore();
+ }
+
+ /** Bytes the scratch surfaces hold, for a host's memory report. */
+ bytes(): number {
+ let n = 0;
+ for (const s of [this.picture, this.smear]) if (s) n += s.width * s.height * 4;
+ return n;
+ }
+
+ /** Give the scratch memory back. */
+ dispose(): void {
+ for (const s of [this.picture, this.smear]) {
+ if (!s) continue;
+ s.width = 1;
+ s.height = 1;
+ }
+ this.picture = null;
+ this.smear = null;
+ }
+}
diff --git a/site/packages/effects-kit/src/index.ts b/site/packages/effects-kit/src/index.ts
index 282b8539..c8401276 100644
--- a/site/packages/effects-kit/src/index.ts
+++ b/site/packages/effects-kit/src/index.ts
@@ -6,6 +6,9 @@ export * from "./motion/types";
export * from "./motion/evaluate";
export * from "./motion/catalog";
export * from "./keys";
+export * from "./ease";
+export * from "./camera";
+export * from "./elementFx";
export * from "./mask";
export * from "./shapePath";
export * from "./render";
diff --git a/site/packages/effects-kit/src/keys.ts b/site/packages/effects-kit/src/keys.ts
index 32d4e5b1..96aba2e5 100644
--- a/site/packages/effects-kit/src/keys.ts
+++ b/site/packages/effects-kit/src/keys.ts
@@ -22,6 +22,18 @@ import {
type GlyphPhase,
type OverlayAnim,
} from "./anim";
+import {
+ capStreak,
+ composeCamera,
+ designFrame,
+ hasCameraKeys,
+ MOTION_BLUR_FRAME,
+ REST_CAMERA,
+ type CameraKey,
+ type CameraPose,
+ type GroupCamera,
+} from "./camera";
+import { easeAt, type EaseId } from "./ease";
/** A pose captured at `t` seconds into the element. Values are absolute, in
* the same units as the element's own fields — `scale` multiplies the
@@ -33,6 +45,10 @@ export interface OverlayKey {
scale: number;
rotation: number; // degrees clockwise
opacity: number; // 0..1
+ /** Gaussian blur, px at the 1080 short side; absent = the element's own. */
+ blur?: number;
+ /** The curve out of this key into the next; absent = constant rate. */
+ ease?: EaseId;
}
/** What an element looks like at one moment, before presets compose over it. */
@@ -42,6 +58,8 @@ export interface OverlayPose {
scale: number;
rotation: number;
opacity: number;
+ /** Absent = sharp. */
+ blur?: number;
}
/** The fields `evalOverlayFrame` reads — every overlay kind has them. The
@@ -60,6 +78,9 @@ interface Posable {
anim?: OverlayAnim;
kf?: OverlayKey[];
mask?: { kf?: { t: number }[] };
+ blur?: number;
+ motionBlur?: number;
+ camera?: GroupCamera;
}
/** Two keys closer than this are the same key. Half a frame at 30fps, so a
@@ -74,6 +95,7 @@ export function restingPose(o: Posable): OverlayPose {
scale: 1,
rotation: o.rotation ?? 0,
opacity: o.opacity ?? 1,
+ ...(o.blur ? { blur: o.blur } : {}),
};
}
@@ -82,11 +104,18 @@ export function hasOverlayKeys(o: Posable): boolean {
return !!o.kf && o.kf.length > 0;
}
-/** Whether anything about the element moves — a preset, pose keys, or a
- * keyframed mask. An element that does not move renders as one still
- * picture. */
+/** Whether the element is drawn through the per-frame evaluator: something
+ * moves it (a preset, pose keys, its group's camera, a keyframed mask), or it
+ * is blurred, which every renderer applies to the posed picture as it draws.
+ * Any other element renders as one still picture. */
export function isOverlayAnimated(o: Posable): boolean {
- return hasOverlayAnim(o.anim) || hasOverlayKeys(o) || !!(o.mask?.kf && o.mask.kf.length > 0);
+ return (
+ hasOverlayAnim(o.anim) ||
+ hasOverlayKeys(o) ||
+ hasCameraKeys(o.camera) ||
+ (o.blur ?? 0) > 0 ||
+ !!(o.mask?.kf && o.mask.kf.length > 0)
+ );
}
/** Keys in play order. Callers may hand them over unsorted (a key added at the
@@ -100,7 +129,7 @@ export function sortedKeys<K extends { t: number }>(keys: K[]): K[] {
* hold flat outside them, and hand the pair to `mix`. The pose track and the
* mask track are both thin wrappers over this.
*/
-export function lerpKeys<K extends { t: number }>(
+export function lerpKeys<K extends { t: number; ease?: EaseId }>(
keys: K[],
tLocal: number,
mix: (a: K, b: K, p: number) => K
@@ -115,7 +144,8 @@ export function lerpKeys<K extends { t: number }>(
const b = ks[i + 1];
const span = b.t - a.t;
const p = span > 1e-6 ? (tLocal - a.t) / span : 0;
- return mix(a, b, p);
+ // The first key's curve carries the move out of it into the next.
+ return mix(a, b, a.ease ? easeAt(a.ease, p) : p);
}
/** The pose at `tLocal` seconds into the element: interpolated between the
@@ -123,8 +153,11 @@ export function lerpKeys<K extends { t: number }>(
export function poseAt(o: Posable, tLocal: number): OverlayPose {
const keys = o.kf;
if (!keys || keys.length === 0) return restingPose(o);
+ // A key with no blur of its own takes the element's.
+ const rest = o.blur ?? 0;
const k = lerpKeys(keys, tLocal, (a, b, p) => {
const mix = (u: number, v: number) => u + (v - u) * p;
+ const blur = mix(a.blur ?? rest, b.blur ?? rest);
return {
t: mix(a.t, b.t),
x: mix(a.x, b.x),
@@ -134,9 +167,10 @@ export function poseAt(o: Posable, tLocal: number): OverlayPose {
// turns 20° forward instead of 340° back.
rotation: a.rotation + shortestTurn(a.rotation, b.rotation) * p,
opacity: mix(a.opacity, b.opacity),
+ ...(blur > 0 ? { blur } : {}),
};
});
- return poseOf(k);
+ return poseOf(k, rest);
}
/** The signed short-way-around turn from one angle to another, degrees. */
@@ -147,8 +181,16 @@ export function shortestTurn(from: number, to: number): number {
return d;
}
-function poseOf(k: OverlayKey): OverlayPose {
- return { x: k.x, y: k.y, scale: k.scale, rotation: k.rotation, opacity: k.opacity };
+function poseOf(k: OverlayKey, restBlur = 0): OverlayPose {
+ const blur = k.blur ?? restBlur;
+ return {
+ x: k.x,
+ y: k.y,
+ scale: k.scale,
+ rotation: k.rotation,
+ opacity: k.opacity,
+ ...(blur > 0 ? { blur } : {}),
+ };
}
/** A key holding the element's pose at `t`, ready to be added. Capturing the
@@ -158,6 +200,26 @@ export function keyAt(o: Posable, t: number): OverlayKey {
return { t, ...poseAt(o, t) };
}
+/** The camera's pose at `tLocal` seconds into the element: eased between the
+ * surrounding keys, held outside them. Zoom moves by ratio, so a push from 1×
+ * to 4× feels as even as one from 2× to 8×. */
+export function cameraAt(cam: GroupCamera | undefined, tLocal: number): CameraPose {
+ if (!hasCameraKeys(cam)) return REST_CAMERA;
+ const k = lerpKeys<CameraKey>(cam.kf, tLocal, (a, b, p) => {
+ const mix = (u: number, v: number) => u + (v - u) * p;
+ const sa = Math.max(1e-3, a.scale);
+ const sb = Math.max(1e-3, b.scale);
+ return {
+ t: mix(a.t, b.t),
+ x: mix(a.x, b.x),
+ y: mix(a.y, b.y),
+ scale: sa * Math.pow(sb / sa, p),
+ rotation: a.rotation + shortestTurn(a.rotation, b.rotation) * p,
+ };
+ });
+ return { x: k.x, y: k.y, scale: k.scale, rotation: k.rotation };
+}
+
/** Insert or replace a key, keeping the list in play order. A key dropped on
* top of an existing one (within `KEY_EPSILON`) replaces it. */
export function upsertKey<K extends { t: number }>(keys: K[] | undefined, key: K): K[] {
@@ -194,9 +256,59 @@ export interface OverlayFrameState extends OverlayPose {
glyphLoop?: GlyphLoopPhase;
/** How far the view has flown into the element's deepest ink (dive). */
dive?: number;
+ /** The motion blur streak: how far the element's center travels on screen
+ * while the shutter is open, design px, centered on this moment. Absent
+ * when motion blur is off or the element is still. */
+ streak?: { x: number; y: number };
+ /** Whether the typing bar is lit; absent when the element has none. */
+ caret?: boolean;
+ /** Multiplies the element's colors (a hit that darkens); absent = 1. */
+ brightness?: number;
+}
+
+/**
+ * The element's frame state at `tLocal`, as every renderer draws it: the
+ * pose, the presets over it, its group's camera over both, and the motion
+ * blur streak. `aspect` (frame width / height) is required once a camera or
+ * motion blur is in play, since both work in on-screen distances.
+ */
+export function evalOverlayFrame(o: Posable, tLocal: number, aspect?: number): OverlayFrameState {
+ const own = ownFrame(o, tLocal);
+ const cam = hasCameraKeys(o.camera) ? o.camera : undefined;
+ const shutter = o.motionBlur || cam?.motionBlur || 0;
+ if (!cam && !shutter) return own;
+ if (!aspect || !Number.isFinite(aspect)) {
+ throw new Error("A camera or motion blur needs the frame's aspect to evaluate.");
+ }
+ const placed = cam ? composeCamera(own, cameraAt(cam, tLocal), aspect) : own;
+ if (!shutter) return placed;
+ // The element's own motion blur streaks its whole move on screen; the
+ // camera's streaks only what the camera does, with the element held still.
+ const whole = !!o.motionBlur;
+ const exposure = shutter * MOTION_BLUR_FRAME;
+ const dur = Math.max(0.1, o.end - o.start);
+ const t0 = Math.max(0, tLocal - exposure / 2);
+ const t1 = Math.min(dur, tLocal + exposure / 2);
+ if (t1 - t0 < 1e-6) return placed;
+ const at = (t: number) => {
+ const s = whole ? ownFrame(o, t) : own;
+ return cam ? composeCamera(s, cameraAt(cam, t), aspect) : s;
+ };
+ const a = at(t0);
+ const b = at(t1);
+ const f = designFrame(aspect);
+ // Velocity over the window that fits inside the element, scaled to the
+ // whole exposure, so the first and last frames streak like the rest.
+ const k = exposure / (t1 - t0);
+ const streak = capStreak(
+ ((b.x - a.x) * f.width + (b.dx - a.dx)) * k,
+ ((b.y - a.y) * f.height + (b.dy - a.dy)) * k
+ );
+ return streak ? { ...placed, streak } : placed;
}
-export function evalOverlayFrame(o: Posable, tLocal: number): OverlayFrameState {
+/** The element's own frame state: its pose with the presets over it. */
+function ownFrame(o: Posable, tLocal: number): OverlayFrameState {
const dur = Math.max(0.1, o.end - o.start);
const pose = poseAt(o, tLocal);
const ev = evalOverlayAnim(o.anim, tLocal, dur, (o.kind ?? "text") === "text");
@@ -226,7 +338,7 @@ export function poseExtent(o: Posable): {
y1: number;
scale: number;
} {
- const poses = hasOverlayKeys(o) ? sortedKeys(o.kf!).map(poseOf) : [restingPose(o)];
+ const poses = hasOverlayKeys(o) ? sortedKeys(o.kf!).map((k) => poseOf(k)) : [restingPose(o)];
return {
x0: Math.min(...poses.map((p) => p.x)),
y0: Math.min(...poses.map((p) => p.y)),
diff --git a/site/packages/effects-kit/src/render.ts b/site/packages/effects-kit/src/render.ts
index 231f1e7c..fb5b2091 100644
--- a/site/packages/effects-kit/src/render.ts
+++ b/site/packages/effects-kit/src/render.ts
@@ -20,6 +20,8 @@ import {
import { diveView, slotReel, slotSeed, type DiveFocus, type DiveView } from "./dive";
import { presetExtent } from "./motion/evaluate";
import { evalOverlayFrame, hasOverlayKeys, poseAt, poseExtent, sortedKeys, type OverlayFrameState } from "./keys";
+import { ELEMENT_BLUR_MAX, hasCameraKeys, STREAK_MAX } from "./camera";
+import { ElementFx, elementLook } from "./elementFx";
import { applyMaskToCanvas, isMaskAnimated } from "./mask";
import { tracePolyShape } from "./shapePath";
import type { LottieHandle } from "./lottie";
@@ -1268,22 +1270,37 @@ export async function renderOverlayFrames(
// A dive flies into the element until it fills the frame, so its flight
// takes the whole frame.
const focus = divesAt(anim) ? await measureDiveFocus(overlay, width / height, env) : null;
- const x0 = focus ? 0 : Math.max(0, Math.floor(extent.x0 * width - halfW));
- const y0 = focus ? 0 : Math.max(0, Math.floor(extent.y0 * height - halfH));
- const x1 = focus ? width : Math.min(width, Math.ceil(extent.x1 * width + halfW));
- const y1 = focus ? height : Math.min(height, Math.ceil(extent.y1 * height + halfH));
+ // A camera can carry the element anywhere in the frame at any size, so its
+ // pictures take the whole frame too.
+ const filmed = hasCameraKeys(overlay.camera);
+ const whole = !!focus || filmed;
+ // Blur spills about three radii past the ink; a streak reaches half its
+ // longest length either side.
+ const blurs = [overlay.blur ?? 0, ...(overlay.kf ?? []).map((k) => k.blur ?? 0)];
+ const spill =
+ Math.min(ELEMENT_BLUR_MAX, Math.max(...blurs)) * 3 * scale +
+ (overlay.motionBlur ? (STREAK_MAX / 2) * scale : 0);
+ halfW += spill;
+ halfH += spill;
+ const x0 = whole ? 0 : Math.max(0, Math.floor(extent.x0 * width - halfW));
+ const y0 = whole ? 0 : Math.max(0, Math.floor(extent.y0 * height - halfH));
+ const x1 = whole ? width : Math.min(width, Math.ceil(extent.x1 * width + halfW));
+ const y1 = whole ? height : Math.min(height, Math.ceil(extent.y1 * height + halfH));
const rw = Math.max(2, x1 - x0);
const rh = Math.max(2, y1 - y0);
const canvas = newCanvas(env, rw, rh);
- const ctx = canvas.getContext("2d")!;
+ const target = canvas.getContext("2d")!;
const maskScratch = overlay.mask ? newCanvas(env, 1, 1) : null;
+ // Blur and motion blur paint the posed element into a scratch first.
+ const fx = new ElementFx((w, h) => newCanvas(env, w, h));
const drawAt = async (tLocal: number): Promise<Blob> => {
- ctx.setTransform(1, 0, 0, 1, 0, 0);
- ctx.clearRect(0, 0, rw, rh);
- const ev = evalOverlayFrame(overlay, tLocal);
+ target.setTransform(1, 0, 0, 1, 0, 0);
+ target.clearRect(0, 0, rw, rh);
+ const ev = evalOverlayFrame(overlay, tLocal, width / height);
if (ev.opacity <= 0.001) return pngBlob(canvas, env); // fully transparent frame
+ const ctx = fx.begin(target, rw, rh, elementLook(ev, scale)) as CanvasRenderingContext2D;
ctx.globalAlpha = ev.opacity;
ctx.translate(-x0, -y0);
// The pose places the element; the preset's travel rides on top of it.
diff --git a/site/packages/effects-kit/src/types.ts b/site/packages/effects-kit/src/types.ts
index 711a873a..19797f85 100644
--- a/site/packages/effects-kit/src/types.ts
+++ b/site/packages/effects-kit/src/types.ts
@@ -6,6 +6,7 @@
*/
import type { OverlayAnim } from "./anim";
+import type { GroupCamera } from "./camera";
import type { EffectOverlay } from "./effects";
import type { OverlayKey } from "./keys";
import type { Mask } from "./mask";
@@ -42,6 +43,15 @@ export interface OverlayBase {
/** Coverage that trims the element's pixels to a shape or to the person in
* the shot (see mask.ts); absent = the whole element shows. */
mask?: Mask;
+ /** Gaussian blur at rest, px at the 1080 design short side; pose keys may
+ * carry their own. Absent = sharp. */
+ blur?: number;
+ /** Motion blur: the shutter, 0..1 of a 30fps frame, streaking the
+ * element's whole on-screen movement. Absent = off. */
+ motionBlur?: number;
+ /** The camera of the group this element belongs to (see camera.ts), the
+ * same on every member, key times from this element's start. */
+ camera?: GroupCamera;
}
/** A custom drop shadow. Every field is optional — absent ones take the
diff --git a/site/src/cut/components/AnimationTiles.tools.ts b/site/src/cut/components/AnimationTiles.tools.ts
index ce89aa01..880fe3b9 100644
--- a/site/src/cut/components/AnimationTiles.tools.ts
+++ b/site/src/cut/components/AnimationTiles.tools.ts
@@ -100,6 +100,8 @@ export const OVERLAY_ANIMATION_TOOLS = [
scale: num("Size multiplier, 1 = the element's own size (0.1..4)"),
rotation: num("Degrees clockwise, -180..180"),
opacity: num("0..1"),
+ blur: num(`Blur, px at the 1080 short side, 0..${ELEMENT_BLUR_MAX}`),
+ ease: { type: "string", enum: [...EASE_IDS], description: "Curve into the next key" },
},
["t"]
),
diff --git a/site/src/cut/components/AnimationTiles.tsx b/site/src/cut/components/AnimationTiles.tsx
index 5acd5d4a..30e72418 100644
--- a/site/src/cut/components/AnimationTiles.tsx
+++ b/site/src/cut/components/AnimationTiles.tsx
@@ -249,6 +249,7 @@ function LiveName({
el.style.transformOrigin = "";
el.style.opacity = "";
el.style.clipPath = "";
+ el.style.filter = "";
letters().forEach((kid, i) => {
kid.style.transform = "";
kid.style.opacity = "";
@@ -641,11 +642,13 @@ export function AnimationTiles({
}
const ids: string[] =
- slot === "move"
- ? HOLD_IDS
- : slot === "loop"
- ? OVERLAY_LOOP_STYLE_IDS
- : OVERLAY_ANIM_STYLE_IDS.filter((s) => isText || !TEXT_ONLY_ANIM_STYLE_IDS.includes(s));
+ slot === "hit"
+ ? OVERLAY_HIT_STYLE_IDS
+ : slot === "move"
+ ? HOLD_IDS
+ : slot === "loop"
+ ? OVERLAY_LOOP_STYLE_IDS
+ : OVERLAY_ANIM_STYLE_IDS.filter((s) => isText || !TEXT_ONLY_ANIM_STYLE_IDS.includes(s));
return (
<div className="grid grid-cols-2 gap-[9px]">
diff --git a/site/src/cut/components/GroupPanel.tools.ts b/site/src/cut/components/GroupPanel.tools.ts
new file mode 100644
index 00000000..ede64da4
--- /dev/null
+++ b/site/src/cut/components/GroupPanel.tools.ts
@@ -0,0 +1,42 @@
+/**
+ * The assistant's group tools — the camera a group's elements are filmed
+ * through, the Camera section of `GroupPanel`. The catalog spreads this list
+ * into the model's toolset and `aiTools.ts` keys its handlers on
+ * `GroupPanelToolName`.
+ */
+
+import { CAMERA_SCALE_MAX, CAMERA_SCALE_MIN, EASE_IDS } from "@donkeycut/effects-kit";
+import { bool, num, obj, str, type AiToolDef } from "@/cut/lib/aiToolDef";
+
+export const GROUP_PANEL_TOOLS = [
+ {
+ name: "set_group_camera",
+ description: `Give a group of elements (titles, shapes, stickers) one camera that moves over them as a single world: steps from card to card, pushes onto the one being talked about, pulls back, whips. Each key is a camera pose at a time in seconds from the group's start (its earliest element): x/y is the world point at the frame's center (frame fractions, where the elements' own x/y live), scale is the zoom (1 = as laid out, 2.5 = a card a few tenths of the frame wide fills it; ${CAMERA_SCALE_MIN}..${CAMERA_SCALE_MAX}), rotation turns the whole world clockwise about the frame center. ease is the curve out of a key into the next (${EASE_IDS.join(", ")}; default linear): sine.inOut glides between cards, power3.out lands a push, power3.inOut over a short gap is a whip. Every element keeps its own keyframes and animation, composed inside the camera. To focus a card, push onto it and blur and dim its neighbours with set_overlay_keyframes keys (blur, opacity) at the same moments. motion_blur streaks what the camera's movement does (shutter sets how hard); an element's own motion_blur (update_overlay) streaks its whole on-screen movement instead. Name the group by group_id or by any member ids. Omitted fields on a key take the camera's pose at that moment; keys replace the whole track; an empty list clears the camera. Lay the cards out across the frame first (group_items groups them), then key the camera.`,
+ inputSchema: obj(
+ {
+ group_id: str("Group id (from editor_state groupCameras or an element's groupId)"),
+ ids: { type: "array", items: { type: "string" }, description: "Member ids, in place of group_id: their group takes the camera" },
+ keys: {
+ type: "array",
+ description: "Camera keys in any order; two at the same time collapse to one",
+ items: obj(
+ {
+ t: num("Seconds from the group's start"),
+ x: num("World point at the frame center, fraction of frame width"),
+ y: num("World point at the frame center, fraction of frame height"),
+ scale: num(`Zoom, ${CAMERA_SCALE_MIN}..${CAMERA_SCALE_MAX} (1 = as laid out)`),
+ rotation: num("Degrees the world turns clockwise, -180..180"),
+ ease: { type: "string", enum: [...EASE_IDS], description: "Curve into the next key" },
+ },
+ ["t"]
+ ),
+ },
+ motion_blur: bool("Streak the camera's moves (true starts at the default shutter); false switches it off"),
+ shutter: num("Motion blur shutter, 0.05..1 of a 30fps frame (0.5 is the usual half-open shutter); setting it switches motion blur on"),
+ },
+ []
+ ),
+ },
+] as const satisfies readonly AiToolDef[];
+
+export type GroupPanelToolName = (typeof GROUP_PANEL_TOOLS)[number]["name"];
diff --git a/site/src/cut/components/GroupPanel.tsx b/site/src/cut/components/GroupPanel.tsx
index ab5122e1..a53e584d 100644
--- a/site/src/cut/components/GroupPanel.tsx
+++ b/site/src/cut/components/GroupPanel.tsx
@@ -7,6 +7,7 @@ import { ColorField } from "@/cut/components/ColorField";
import { FontPicker } from "@/cut/components/FontPicker";
import { LETTER_SPACINGS, LINE_HEIGHTS, SoundQualityPanel, SoundQualityRow, TEXT_WIDTHS, StylePresetsRow } from "@/cut/components/Inspector";
import { NumberField } from "@/cut/components/NumberField";
+import { GroupCameraSection, GroupMotionRows } from "@/cut/components/MotionControls";
import { Field, Row, Section, SegGroup, SegToggle, useSliderCheckpoint, Value } from "@/cut/components/panelBits";
import { parseNumberInput, parsePercentInput, parseSecondsInput, parseSpeedInput, ScrubValue } from "@/cut/components/ScrubValue";
import { ValueSlider } from "@/cut/components/ValueSlider";
@@ -113,6 +114,8 @@ export function GroupPanel({ selection }: { selection: readonly NonNullable<Sele
{!items.overlays.length && <SoundRows clips={items.clips} audios={items.audios} onOpenSound={() => setView("sound")} />}
{onlyClips && <ClipPictureRows clips={items.clips} />}
<TransformRows items={items} />
+ {items.overlays.length > 0 && !items.clips.length && !items.audios.length && <GroupMotionRows overlays={items.overlays} />}
+ {!group.mixed && group.value && <GroupCameraSection groupId={group.value} />}
{onlyClips && <ClipBorderRows clips={items.clips} />}
{onlyClips && <ClipShadowRows clips={items.clips} />}
</div>
diff --git a/site/src/cut/components/Inspector.tools.ts b/site/src/cut/components/Inspector.tools.ts
index 544d67bc..271aafff 100644
--- a/site/src/cut/components/Inspector.tools.ts
+++ b/site/src/cut/components/Inspector.tools.ts
@@ -26,6 +26,7 @@ import {
SPEED_CURVE_MIN,
SPEED_CURVE_PRESET_IDS,
speedCurvePresetCatalogText,
+ ELEMENT_BLUR_MAX,
MASK_FEATHER_MAX,
MASK_KINDS,
MASK_RADIUS_MAX,
@@ -99,7 +100,7 @@ export const INSPECTOR_TOOLS = [
{
name: "update_overlay",
description:
- "Update any overlay element — title, shape, or sticker — by id (from the selection or state). Titles take text/size/font/weight/color/shadow/plate; shapes take w/h/fill/fill_opacity/radius/stroke; stickers take w/h. Every kind takes name, timing, position, rotation, opacity, hidden. This is the tool for 'make this text better' requests too. Pass ids to land one change on several elements at once (a group, every title in a run): fields a kind lacks are skipped on that element, and the whole write is one undo step.",
+ "Update any overlay element — title, shape, or sticker — by id (from the selection or state). Titles take text/size/font/weight/color/shadow/plate; shapes take w/h/fill/fill_opacity/radius/stroke; stickers take w/h. Every kind takes name, timing, position, rotation, opacity, blur, motion blur, hidden. This is the tool for 'make this text better' requests too. Pass ids to land one change on several elements at once (a group, every title in a run): fields a kind lacks are skipped on that element, and the whole write is one undo step.",
inputSchema: obj({
id: str("Overlay element id"),
ids: { type: "array", items: { type: "string" }, description: "Several element ids to change together (instead of id)" },
@@ -129,6 +130,9 @@ export const INSPECTOR_TOOLS = [
stroke_width: num("Outline width: em for titles (0..0.15), px at 1080 for shapes; 0 removes it"),
rotation: num("Degrees clockwise, -180..180 (0 clears)"),
opacity: num("Whole-element opacity 0..1 (1 clears)"),
+ blur: num(`Blur at rest, px at the 1080 short side, 0..${ELEMENT_BLUR_MAX} (0 clears); keys can carry their own (set_overlay_keyframes)`),
+ motion_blur: bool("Streak the element along its own on-screen movement while it moves (true starts at the default shutter); still frames stay sharp"),
+ shutter: num("Motion blur shutter, 0.05..1 of a 30fps frame (0.5 is the usual half-open shutter); setting it switches motion blur on"),
hidden: bool("Hide the element without deleting it"),
lane: num("Move the element to another row (0 = the front row, drawn over every higher row). Elements on one row never overlap — a title over a shape needs a lower row than the shape."),
}, []),
diff --git a/site/src/cut/components/Inspector.tsx b/site/src/cut/components/Inspector.tsx
index 4d9cae4c..9930a781 100644
--- a/site/src/cut/components/Inspector.tsx
+++ b/site/src/cut/components/Inspector.tsx
@@ -3305,6 +3305,7 @@ function TransformRows({ overlay: o }: { overlay: Overlay }) {
}}
/>
</Row>
+ <ElementMotionRows overlay={o} />
<HiddenRow overlay={o} />
</Section>
);
diff --git a/site/src/cut/components/MotionControls.tsx b/site/src/cut/components/MotionControls.tsx
new file mode 100644
index 00000000..cda0237e
--- /dev/null
+++ b/site/src/cut/components/MotionControls.tsx
@@ -0,0 +1,371 @@
+"use client";
+
+import { useMemo } from "react";
+import {
+ CAMERA_SCALE_MAX,
+ CAMERA_SCALE_MIN,
+ EASE_IDS,
+ EASE_LABELS,
+ ELEMENT_BLUR_MAX,
+ hasOverlayKeys,
+ keyIndexAt,
+ poseAt,
+ removeKeyAt,
+ upsertKey,
+ type CameraKey,
+ type EaseId,
+} from "@donkeycut/effects-kit";
+import { KeyRow } from "@/cut/components/Inspector";
+import { Row, Section, useSliderCheckpoint, Value } from "@/cut/components/panelBits";
+import { parseNumberInput, parsePercentInput, ScrubValue } from "@/cut/components/ScrubValue";
+import { ValueSlider } from "@/cut/components/ValueSlider";
+import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from "@/components/ui/select";
+import { Switch } from "@/components/ui/switch";
+import { groupCameraOf, groupCameraPoseAt } from "@/cut/lib/groupCamera";
+import { sharedNumber, sharedValue } from "@/cut/lib/groupEdit";
+import { cutMotion } from "@/cut/lib/motionSettings";
+import { usePreviewTime } from "@/cut/lib/playhead";
+import { useEditor } from "@/cut/lib/store";
+import { isEffectOverlay, type Overlay } from "@/cut/lib/types";
+
+/**
+ * The motion rows an element, a selection of elements, and a group's camera
+ * share: blur, the ease out of a key, motion blur, and the camera's own key
+ * track. The chat tools write the same fields (update_overlay,
+ * set_overlay_keyframes, set_group_camera).
+ */
+
+const st = () => useEditor.getState();
+const SLIDER = { sliderClassName: "data-horizontal:w-24", valueClassName: "w-9 text-muted-foreground" };
+const EASE_ITEMS = Object.fromEntries(EASE_IDS.map((id) => [id, EASE_LABELS[id]]));
+const local = (o: { start: number; end: number }, now: number) =>
+ Math.max(0, Math.min(now - o.start, Math.max(0.1, o.end - o.start)));
+
+/** The curve out of the key under the playhead. */
+function EaseRow({ ease, onPick }: { ease: EaseId | undefined; onPick: (ease: EaseId | undefined) => void }) {
+ return (
+ <Row label="Ease">
+ <Select value={ease ?? "linear"} items={EASE_ITEMS} onValueChange={(id) => onPick(id === "linear" ? undefined : (id as EaseId))}>
+ <SelectTrigger className="h-8 w-36 text-[12px]">
+ <SelectValue />
+ </SelectTrigger>
+ <SelectContent>
+ {EASE_IDS.map((id) => (
+ <SelectItem key={id} value={id} className="text-[12px]">
+ {EASE_LABELS[id]}
+ </SelectItem>
+ ))}
+ </SelectContent>
+ </Select>
+ </Row>
+ );
+}
+
+/** Motion blur: the switch, and the shutter once it is on. */
+function MotionBlurRows({
+ shutter,
+ onChange,
+ ck,
+}: {
+ shutter: { value: number; mixed: boolean } | null;
+ onChange: (motionBlur: number | undefined, phase: "draft" | "commit" | "once") => void;
+ ck: ReturnType<typeof useSliderCheckpoint>;
+}) {
+ return (
+ <>
+ <Row label="Motion blur">
+ {shutter?.mixed && <Value className="text-muted-foreground italic">Mixed</Value>}
+ <Switch
+ checked={!!shutter && !shutter.mixed}
+ onCheckedChange={(on) => onChange(on ? cutMotion().motionBlur : undefined, "once")}
+ aria-label="Motion blur"
+ />
+ </Row>
+ {shutter && (
+ <Row label="Shutter">
+ <ValueSlider
+ label="Shutter"
+ {...SLIDER}
+ value={shutter.value}
+ mixed={shutter.mixed}
+ min={0.05}
+ max={1}
+ step={0.01}
+ snap={[0.5]}
+ format={(v) => `${Math.round(v * 100)}%`}
+ parse={parsePercentInput}
+ onDraft={(v) => {
+ ck.begin();
+ onChange(v, "draft");
+ }}
+ onCommit={(v) => {
+ ck.begin();
+ onChange(v, "commit");
+ ck.end();
+ }}
+ />
+ </Row>
+ )}
+ </>
+ );
+}
+
+function BlurRow({
+ blur,
+ onSet,
+ ck,
+}: {
+ blur: { value: number; mixed: boolean };
+ onSet: (v: number) => void;
+ ck: ReturnType<typeof useSliderCheckpoint>;
+}) {
+ return (
+ <Row label="Blur">
+ <ValueSlider
+ label="Blur"
+ {...SLIDER}
+ value={blur.value}
+ mixed={blur.mixed}
+ min={0}
+ max={ELEMENT_BLUR_MAX}
+ step={0.5}
+ format={(v) => `${Math.round(v * 10) / 10}`}
+ parse={parseNumberInput}
+ onDraft={(v) => {
+ ck.begin();
+ onSet(v);
+ }}
+ onCommit={(v) => {
+ ck.begin();
+ onSet(v);
+ ck.end();
+ }}
+ />
+ </Row>
+ );
+}
+
+/**
+ * One element's blur, the ease of its key under the playhead, and its motion
+ * blur. Blur is part of the pose: with keys in play it edits the key at the
+ * playhead, like position and opacity do.
+ */
+export function ElementMotionRows({ overlay: o }: { overlay: Overlay }) {
+ const now = usePreviewTime();
+ const blurCk = useSliderCheckpoint();
+ const shutterCk = useSliderCheckpoint();
+ const keyed = hasOverlayKeys(o);
+ const tLocal = local(o, now);
+ const pose = poseAt(o, tLocal);
+ const here = keyed ? keyIndexAt(o.kf, tLocal) : -1;
+ const key = here >= 0 ? o.kf![here] : undefined;
+ const setBlur = (v: number) => {
+ const blur = Math.max(0, Math.min(ELEMENT_BLUR_MAX, v));
+ if (keyed) return st().setOverlayKey(o.id, tLocal, { blur }, { transient: true });
+ st().updateOverlayTransient(o.id, { blur: blur > 0.05 ? blur : undefined });
+ };
+ return (
+ <>
+ <BlurRow blur={{ value: keyed ? (pose.blur ?? 0) : (o.blur ?? 0), mixed: false }} onSet={setBlur} ck={blurCk} />
+ {key && (
+ <EaseRow
+ ease={key.ease}
+ onPick={(ease) => {
+ st().pushHistory();
+ st().setOverlayKey(o.id, key.t, { ease }, { transient: true });
+ }}
+ />
+ )}
+ <MotionBlurRows
+ shutter={o.motionBlur ? { value: o.motionBlur, mixed: false } : null}
+ ck={shutterCk}
+ onChange={(motionBlur, phase) => {
+ if (phase === "once") st().pushHistory();
+ st().updateOverlayTransient(o.id, { motionBlur });
+ }}
+ />
+ </>
+ );
+}
+
+/** Blur and motion blur over several elements at once, one undo step per
+ * gesture; a keyed element takes the blur at the playhead. */
+export function GroupMotionRows({ overlays }: { overlays: readonly Overlay[] }) {
+ const now = usePreviewTime();
+ const blurCk = useSliderCheckpoint();
+ const shutterCk = useSliderCheckpoint();
+ const posed = overlays.filter((o) => !isEffectOverlay(o));
+ if (!posed.length) return null;
+ const blurOf = (o: Overlay) => (hasOverlayKeys(o) ? (poseAt(o, local(o, now)).blur ?? 0) : (o.blur ?? 0));
+ const blur = sharedNumber(posed.map(blurOf));
+ const on = sharedValue(posed.map((o) => !!o.motionBlur));
+ const shutter = sharedNumber(posed.map((o) => o.motionBlur ?? 0));
+ const setBlur = (v: number) => {
+ const b = Math.max(0, Math.min(ELEMENT_BLUR_MAX, v));
+ for (const o of posed) {
+ if (hasOverlayKeys(o)) st().setOverlayKey(o.id, local(o, now), { blur: b }, { transient: true });
+ else st().updateOverlayTransient(o.id, { blur: b > 0.05 ? b : undefined });
+ }
+ };
+ return (
+ <>
+ <BlurRow blur={blur} onSet={setBlur} ck={blurCk} />
+ <MotionBlurRows
+ shutter={on.mixed ? { value: shutter.value, mixed: true } : on.value ? shutter : null}
+ ck={shutterCk}
+ onChange={(motionBlur, phase) => {
+ if (phase === "once") st().pushHistory();
+ st().updateOverlaysTransient(posed.map((o) => ({ id: o.id, patch: { motionBlur } })));
+ }}
+ />
+ </>
+ );
+}
+
+/**
+ * A group's camera: its key track over the group's span, the pose at the
+ * playhead (where the frame's center looks, the zoom, the roll), the ease out
+ * of the key here, and the camera's motion blur. Editing a row with keys in
+ * play edits the key at the playhead; with none, it sets the first key.
+ */
+export function GroupCameraSection({ groupId }: { groupId: string }) {
+ const overlays = useEditor((s) => s.overlays);
+ const seek = useEditor((s) => s.seek);
+ const now = usePreviewTime();
+ const posCk = useSliderCheckpoint();
+ const zoomCk = useSliderCheckpoint();
+ const rollCk = useSliderCheckpoint();
+ const shutterCk = useSliderCheckpoint();
+ const view = useMemo(() => groupCameraOf(overlays, groupId), [overlays, groupId]);
+ if (!view) return null;
+ const tGroup = local({ start: 0, end: view.end - view.start }, now - view.start);
+ const pose = groupCameraPoseAt(view, tGroup);
+ const here = keyIndexAt(view.keys, tGroup);
+ const key = here >= 0 ? view.keys[here] : undefined;
+ const write = (keys: CameraKey[], motionBlur = view.motionBlur) =>
+ st().setGroupCamera(groupId, { keys, ...(motionBlur ? { motionBlur } : {}) }, { transient: true });
+ // Read the live track at each write, so a drag layers on its own frames.
+ const live = () => groupCameraOf(st().overlays, groupId) ?? view;
+ const setKey = (patch: Partial<Omit<CameraKey, "t">>) => {
+ const cur = live();
+ const existing = cur.keys[keyIndexAt(cur.keys, tGroup)];
+ const base = existing ?? { t: tGroup, ...groupCameraPoseAt(cur, tGroup) };
+ write(upsertKey(cur.keys, { ...base, ...patch, t: existing?.t ?? tGroup }), cur.motionBlur);
+ };
+ const keys = view.keys;
+ return (
+ <Section title="Camera">
+ <KeyRow
+ element={{ start: view.start, end: view.end }}
+ now={now}
+ keys={keys}
+ onAdd={(t) => {
+ st().pushHistory();
+ const cur = live();
+ write(upsertKey(cur.keys, { t, ...groupCameraPoseAt(cur, t) }), cur.motionBlur);
+ }}
+ onRemove={(t) => {
+ st().pushHistory();
+ const cur = live();
+ write(removeKeyAt(cur.keys, t), cur.motionBlur);
+ }}
+ onSeek={seek}
+ />
+ <Row label="Look at">
+ {(["x", "y"] as const).map((axis) => (
+ <span key={axis} className="flex items-center gap-1">
+ <span className="text-[11px] text-muted-foreground/70 uppercase">{axis}</span>
+ <ScrubValue
+ label={`Camera ${axis.toUpperCase()}`}
+ className="w-9 text-muted-foreground"
+ value={pose[axis] * 100}
+ min={-100}
+ max={200}
+ step={0.5}
+ keyStep={1}
+ snap={[50]}
+ format={(v) => String(Math.round(v))}
+ parse={parseNumberInput}
+ onScrub={(v) => {
+ posCk.begin();
+ setKey({ [axis]: v / 100 });
+ }}
+ onCommit={(v) => {
+ posCk.begin();
+ setKey({ [axis]: v / 100 });
+ posCk.end();
+ }}
+ />
+ </span>
+ ))}
+ </Row>
+ <Row label="Zoom">
+ <ValueSlider
+ label="Camera zoom"
+ {...SLIDER}
+ valueClassName="w-12 text-muted-foreground"
+ value={pose.scale}
+ min={CAMERA_SCALE_MIN}
+ max={4}
+ scrubMin={CAMERA_SCALE_MIN}
+ scrubMax={CAMERA_SCALE_MAX}
+ step={0.01}
+ snap={[1]}
+ keyStep={0.05}
+ format={(v) => `${Math.round(v * 100)}%`}
+ parse={parsePercentInput}
+ onDraft={(v) => {
+ zoomCk.begin();
+ setKey({ scale: v });
+ }}
+ onCommit={(v) => {
+ zoomCk.begin();
+ setKey({ scale: v });
+ zoomCk.end();
+ }}
+ />
+ </Row>
+ <Row label="Roll">
+ <ValueSlider
+ label="Camera roll"
+ {...SLIDER}
+ value={pose.rotation}
+ min={-180}
+ max={180}
+ step={1}
+ snap={[-90, 0, 90]}
+ format={(v) => `${Math.round(v)}°`}
+ parse={parseNumberInput}
+ onDraft={(v) => {
+ rollCk.begin();
+ setKey({ rotation: Math.round(v) });
+ }}
+ onCommit={(v) => {
+ rollCk.begin();
+ setKey({ rotation: Math.round(v) });
+ rollCk.end();
+ }}
+ />
+ </Row>
+ {key && (
+ <EaseRow
+ ease={key.ease}
+ onPick={(ease) => {
+ st().pushHistory();
+ const cur = live();
+ const k = cur.keys[keyIndexAt(cur.keys, key.t)];
+ if (k) write(upsertKey(cur.keys, { ...k, ease }), cur.motionBlur);
+ }}
+ />
+ )}
+ <MotionBlurRows
+ shutter={view.motionBlur ? { value: view.motionBlur, mixed: false } : null}
+ ck={shutterCk}
+ onChange={(motionBlur, phase) => {
+ if (phase === "once") st().pushHistory();
+ write(live().keys, motionBlur);
+ }}
+ />
+ </Section>
+ );
+}
diff --git a/site/src/cut/components/OverlayLayer.tsx b/site/src/cut/components/OverlayLayer.tsx
index f49c302c..8c4154e1 100644
--- a/site/src/cut/components/OverlayLayer.tsx
+++ b/site/src/cut/components/OverlayLayer.tsx
@@ -18,6 +18,11 @@ import {
subtitleLaneCount,
trackPos,
} from "@/cut/lib/subtitles";
+import { drawStreak, elementAtMoment, paintElementCrop, streakTaps } from "@donkeycut/effects-kit";
+import { holdMemory } from "@/cut/lib/memoryBudget";
+import { elementCameraAt } from "@/cut/lib/groupCamera";
+import { cameraPoint, worldPoint } from "@donkeycut/effects-kit";
+import { CARET_GAP_EM, CARET_HEIGHT_EM, CARET_WIDTH_EM, typeCaret } from "@donkeycut/effects-kit";
import { diveView, evalOverlayFrame, glyphStateAt, measureDiveFocus, paintElementInto, slotReel, slotSeed, hasGlyphMotion, hasMaskKeys, hasOverlayKeys, isOverlayAnimated, lineLikeShape, MASK_FEATHER_MAX, MASK_RADIUS_MAX, maskFrameAt, maskHasRadius, maskInverts, maskOutlinePathD, maskSizeAxes, overlayWords, paintMaskCoverage, PEN_MIN_POINTS, penClosed, resolveShadow, shapeMetrics, shapePathD, WORD_ACCENT_DEFAULT, wordDrawsAt, type LottieHandle, type Mask, type MaskKey, type DiveFocus, type MaskPoint, type OverlayFrameState, type WordDraw } from "@donkeycut/effects-kit";
import {
LINE_HEIGHT,
@@ -405,6 +410,7 @@ function WordText({
</span>
);
})}
+ {li === lines.length - 1 && tail}
</span>
))}
</>
@@ -632,7 +638,8 @@ function OverlayItem({
isOverlayAnimated(o) && rehearsal !== "rest" && (running !== null || !ghost)
? evalOverlayFrame(
running ? { ...o, anim: running.anim } : o,
- running ? running.tLocal : Math.max(0, t - o.start)
+ running ? running.tLocal : Math.max(0, t - o.start),
+ frame.w / frame.h
)
: null;
// The pose's own zoom is kept apart from the rest of the chain: the element
@@ -679,12 +686,51 @@ function OverlayItem({
// keeps an invisible hit target (and the selection chrome) so editing
// still works.
const behindHidden = behindSubjectOverlay(o) && !editing;
+ // The typing bar, lit or dark by the evaluator's blink. It takes no room
+ // in the line — its negative margin gives back its width — so the text
+ // sits exactly where the painter, which draws the bar over nothing, puts it.
+ const caretWidth = `max(${2 * scale}px, ${CARET_WIDTH_EM}em)`;
+ const caretBar =
+ isText && !editing && live?.caret ? (
+ <span
+ aria-hidden
+ style={{
+ display: "inline-block",
+ width: caretWidth,
+ height: `${CARET_HEIGHT_EM}em`,
+ marginLeft: `${CARET_GAP_EM}em`,
+ marginRight: `calc(-1 * (${CARET_GAP_EM}em + ${caretWidth}))`,
+ verticalAlign: "middle",
+ background: typeCaret(o.anim)?.color ?? o.color,
+ }}
+ />
+ ) : null;
// A dive flies the view into the element's deepest ink. Zoomed fifty times,
// the few pixels the DOM and the canvas disagree on where a line's middle
// sits become the width of the frame, so while it dives the element is
// drawn by the kit's own painter — the picture the export draws.
const diving = !!live?.dive && !editing && !behindHidden;
+ // Blur is a CSS filter inside the box, so the box's zoom would grow it:
+ // it is divided back out to land the radius every renderer draws.
+ const blurPx = (((live ? live.blur : o.blur) ?? 0) * scale) / poseZoom;
+ // A hit that darkens dims the element's own pixels, the same multiply the
+ // painters run; blur softens them. The DOM content, the dive canvas and the
+ // streak canvas all carry the one filter.
+ const blur = blurPx >= 0.1 ? `blur(${blurPx.toFixed(2)}px)` : "";
+ const dim = live?.brightness !== undefined ? `brightness(${live.brightness})` : "";
+ const blurFilter = blur && dim ? `${blur} ${dim}` : blur || dim || undefined;
+ // The dive canvas sits on the stage outside the box, so its blur takes the
+ // radius undivided.
+ const diveBlurPx = blurPx * poseZoom;
+ const diveFilter =
+ [diveBlurPx >= 0.1 ? `blur(${diveBlurPx.toFixed(2)}px)` : "", dim].filter(Boolean).join(" ") || undefined;
+ // Motion blur: while the element moves, the kit paints it and smears the
+ // picture along its streak; at rest the element is the plain DOM box.
+ const streakable =
+ !!(o.motionBlur || o.camera?.motionBlur) && !editing && !behindHidden && !diving && !ghost;
+ const [streakReady, setStreakReady] = useState(false);
+ const streaking = streakable && !!live?.streak && streakReady;
const tLocal = Math.max(0, t - o.start);
// The mask clips the content wrapper only, never the box itself — the
@@ -763,7 +809,8 @@ function OverlayItem({
})()
: {}),
...(maskCss ?? {}),
- ...(diving ? { visibility: "hidden" as const } : {}),
+ ...(blurFilter ? { filter: blurFilter } : {}),
+ ...(diving || streaking ? { visibility: "hidden" as const } : {}),
...(reveal !== undefined
? { clipPath: `inset(0 ${(1 - Math.min(1, Math.max(0, reveal))) * 100}% 0 0)` }
: {}),
@@ -993,7 +1040,10 @@ function OverlayItem({
liveRotation = rotation;
setSpin(rotation);
rotationGuide(locked === null ? null : { clientX: cx, clientY: cy, quarter: locked });
- writeTransform([{ id: o.id, patch: { rotation: rotation === 0 ? undefined : rotation } }]);
+ // The handle reads the angle on screen; a group camera's roll is
+ // the world's, so the element keeps the rest.
+ const own = Math.round(normDeg(rotation - (elementCameraAt(o, tLocal)?.rotation ?? 0)));
+ writeTransform([{ id: o.id, patch: { rotation: own === 0 ? undefined : own } }]);
return;
}
let delta = normDeg(angleAt(ev) - start0);
@@ -1061,8 +1111,18 @@ function OverlayItem({
// rest follow by the same delta.
const members = groupSnapshot().map((m) => ({ id: m.id, x: m.x, y: m.y }));
const self = members.find((m) => m.id === o.id) ?? { id: o.id, x: o.x, y: o.y };
+ // Under a group camera the pointer moves the element on screen; the
+ // members move by that much of their world.
+ const cam = elementCameraAt(o, tLocal);
+ const aspect = frame.w / frame.h;
+ const seen = cam ? cameraPoint(cam, self.x, self.y, aspect) : null;
startDrag(e, {
onMove: (dx, dy, ev) => {
+ if (cam && seen) {
+ const w = worldPoint(cam, seen.x + dx / stageWidth, seen.y + dy / stageHeight, aspect);
+ writeTransform(members.map((m) => ({ id: m.id, patch: { x: m.x + w.x - self.x, y: m.y + w.y - self.y } })));
+ return;
+ }
const p = snap(o.id, self.x + dx / stageWidth, self.y + dy / stageHeight, ev);
const ddx = clampPos(p.x) - self.x;
const ddy = clampPos(p.y) - self.y;
@@ -1128,7 +1188,7 @@ function OverlayItem({
return (
<>
{diving && live && (
- <DiveCanvas o={o} live={live} stageWidth={stageWidth} stageHeight={stageHeight} />
+ <DiveCanvas o={o} live={live} stageWidth={stageWidth} stageHeight={stageHeight} filter={diveFilter} />
)}
<div
ref={boxRef}
@@ -1181,6 +1241,19 @@ function OverlayItem({
<StickerView sticker={o} stageWidth={stageWidth} stageHeight={stageHeight} t={t} />
) : null}
</div>
+ {streakable && live && (
+ <StreakCanvas
+ o={o}
+ live={live}
+ tLocal={running ? running.tLocal : tLocal}
+ stageWidth={stageWidth}
+ stageHeight={stageHeight}
+ poseZoom={poseZoom}
+ filter={blurFilter}
+ mask={o.mask?.kind === "subject" ? maskCss : undefined}
+ onReady={setStreakReady}
+ />
+ )}
{/* The twin can't mount until its size is read, so the in-box chrome
holds through that first frame — a select never blinks. */}
{!chromeLifted && chrome}
@@ -1343,6 +1416,7 @@ function GlyphText({
return (
<span key={li} style={{ display: "block", minHeight: "1em" }}>
{chars}
+ {li === lineCount - 1 && tail}
</span>
);
})}
@@ -1360,11 +1434,13 @@ function DiveCanvas({
live,
stageWidth,
stageHeight,
+ filter,
}: {
o: Overlay;
live: OverlayFrameState;
stageWidth: number;
stageHeight: number;
+ filter?: string;
}) {
const ref = useRef<HTMLCanvasElement>(null);
const assets = useEditor((s) => (o.kind === "sticker" ? s.assets : null));
@@ -1410,11 +1486,165 @@ function DiveCanvas({
width: stageWidth,
height: stageHeight,
opacity: live.opacity,
+ filter,
}}
/>
);
}
+/**
+ * A moving element with motion blur, painted by the kit and smeared along its
+ * streak: the picture every export draws. It rides inside the element's box,
+ * which carries the pose, so the on-screen streak is turned back into the
+ * box's own space (unrotated, unzoomed) before the smear. The element's
+ * picture is painted once, cropped to its ink, and repainted only while its
+ * pixels change on their own (typing, a wipe, a per-glyph move, words, a
+ * Lottie); each moving frame then costs a few element-sized draws. At rest it
+ * draws nothing and the box shows the element itself.
+ */
+function StreakCanvas({
+ o,
+ live,
+ tLocal,
+ stageWidth,
+ stageHeight,
+ poseZoom,
+ filter,
+ mask,
+ onReady,
+}: {
+ o: Overlay;
+ live: OverlayFrameState;
+ tLocal: number;
+ stageWidth: number;
+ stageHeight: number;
+ poseZoom: number;
+ filter?: string;
+ /** A front subject mask's CSS, laid over the stage-sized frame. */
+ mask?: CSSProperties;
+ onReady: (ready: boolean) => void;
+}) {
+ const ref = useRef<HTMLCanvasElement>(null);
+ const raster = useRef<{ canvas: HTMLCanvasElement; x: number; y: number } | null>(null);
+ const [painted, setPainted] = useState(0);
+ const assets = useEditor((s) => (o.kind === "sticker" ? s.assets : null));
+ const dpr = typeof window === "undefined" ? 1 : Math.min(2, window.devicePixelRatio || 1);
+ const w = Math.max(1, Math.round(stageWidth * dpr));
+ const h = Math.max(1, Math.round(stageHeight * dpr));
+ // Pixels that change on their own repaint every frame; the rest paint once.
+ const selfMoving =
+ !!live.glyphs ||
+ !!live.glyphLoop ||
+ live.reveal !== undefined ||
+ live.textProgress !== undefined ||
+ !!overlayWords(o) ||
+ (o.kind === "sticker" && !!o.lottie);
+ const paintAt = selfMoving ? tLocal : 0;
+ const pending = useRef<number | null>(null);
+ const busy = useRef(false);
+ useEffect(() => {
+ pending.current = paintAt;
+ if (busy.current) return;
+ busy.current = true;
+ const env = cutRenderEnv(assets ?? []);
+ void (async () => {
+ try {
+ while (pending.current !== null) {
+ const at = pending.current;
+ pending.current = null;
+ const ev = evalOverlayFrame(o, at, w / h);
+ const { el, phase } = elementAtMoment(o, at, ev);
+ const canvas = raster.current?.canvas ?? document.createElement("canvas");
+ const origin = await paintElementCrop(canvas, el, w, h, env, { t: at, phase });
+ raster.current = { canvas, ...origin };
+ }
+ setPainted((n) => n + 1);
+ } finally {
+ busy.current = false;
+ }
+ })();
+ }, [o, paintAt, w, h, assets]);
+ // The picture and the smear canvas count toward the memory report.
+ useEffect(() => {
+ const release = holdMemory("overlayRasters", () => {
+ const r = raster.current?.canvas;
+ const c = ref.current;
+ return (r ? r.width * r.height * 4 : 0) + (c ? c.width * c.height * 4 : 0);
+ });
+ return () => {
+ release();
+ const r = raster.current?.canvas;
+ if (r) r.width = r.height = 1;
+ raster.current = null;
+ onReady(false);
+ };
+ }, [onReady]);
+ const streak = live.streak;
+ useLayoutEffect(() => {
+ const canvas = ref.current;
+ const pic = raster.current;
+ if (!canvas || !pic) return;
+ const ctx = canvas.getContext("2d");
+ if (!ctx) return;
+ if (!streak) {
+ // At rest the box shows the element; the canvas empties once.
+ if (canvas.style.display !== "none") {
+ canvas.style.display = "none";
+ ctx.clearRect(0, 0, canvas.width, canvas.height);
+ onReady(false);
+ }
+ return;
+ }
+ // The on-screen streak in device px, turned into the box's own space.
+ const px = Math.min(w, h) / 1080;
+ const sx = streak.x * px;
+ const sy = streak.y * px;
+ const r = (-live.rotation * Math.PI) / 180;
+ const lx = (Math.cos(r) * sx - Math.sin(r) * sy) / poseZoom;
+ const ly = (Math.sin(r) * sx + Math.cos(r) * sy) / poseZoom;
+ // Grows in steps and never shrinks while mounted, so a changing streak
+ // does not reallocate the canvas every frame.
+ const cw = Math.max(canvas.width, Math.ceil((pic.canvas.width + Math.abs(lx) + 4) / 64) * 64);
+ const ch = Math.max(canvas.height, Math.ceil((pic.canvas.height + Math.abs(ly) + 4) / 64) * 64);
+ if (canvas.width !== cw) canvas.width = cw;
+ if (canvas.height !== ch) canvas.height = ch;
+ const ox = Math.floor((cw - pic.canvas.width) / 2);
+ const oy = Math.floor((ch - pic.canvas.height) / 2);
+ ctx.setTransform(1, 0, 0, 1, 0, 0);
+ ctx.globalAlpha = 1;
+ ctx.globalCompositeOperation = "source-over";
+ ctx.clearRect(0, 0, cw, ch);
+ drawStreak(ctx, pic.canvas, ox, oy, {
+ streakX: lx,
+ streakY: ly,
+ taps: streakTaps(Math.hypot(streak.x, streak.y)),
+ });
+ canvas.style.display = "";
+ canvas.style.left = `${(pic.x - ox) / dpr}px`;
+ canvas.style.top = `${(pic.y - oy) / dpr}px`;
+ canvas.style.width = `${cw / dpr}px`;
+ canvas.style.height = `${ch / dpr}px`;
+ onReady(true);
+ }, [streak, live.rotation, poseZoom, painted, w, h, dpr, onReady]);
+ return (
+ <div
+ className="pointer-events-none absolute"
+ style={{
+ left: "50%",
+ top: "50%",
+ width: stageWidth,
+ height: stageHeight,
+ // The stage in the element's unposed frame, as the dive canvas sits.
+ transform: `translate(${-o.x * stageWidth}px, ${-o.y * stageHeight}px)`,
+ filter,
+ ...(mask ? { ...mask, maskPosition: "0px 0px", WebkitMaskPosition: "0px 0px" } : {}),
+ }}
+ >
+ <canvas ref={ref} width={1} height={1} className="absolute" style={{ display: "none" }} />
+ </div>
+ );
+}
+
function useMaskCss(
o: Overlay,
boxRef: React.RefObject<HTMLDivElement | null>,
diff --git a/site/src/cut/components/inspectorToolFields.test.ts b/site/src/cut/components/inspectorToolFields.test.ts
index be9ff5d3..3a4ff9dc 100644
--- a/site/src/cut/components/inspectorToolFields.test.ts
+++ b/site/src/cut/components/inspectorToolFields.test.ts
@@ -166,10 +166,13 @@ describe("inspector tool fields", () => {
const rendered = (token: string) => new RegExp(`\\b${token}\\b`).test(panels);
const tools = [
...INSPECTOR_TOOLS,
+ ...CAMERA_CARD_TOOLS,
...OVERLAY_ANIMATION_TOOLS,
...TRANSITIONS_TOOLS,
...EFFECTS_TOOLS,
...TIMELINE_TOOLS,
+ ...GROUP_PANEL_TOOLS,
+ ...SUBTITLES_TOOLS,
].filter((t) => ITEM_TOOLS.has(t.name));
expect(tools.map((t) => t.name).sort()).toEqual([...ITEM_TOOLS].sort());
const missing: string[] = [];
diff --git a/site/src/cut/lib/aiContext.ts b/site/src/cut/lib/aiContext.ts
index c456f5b5..5e5f9576 100644
--- a/site/src/cut/lib/aiContext.ts
+++ b/site/src/cut/lib/aiContext.ts
@@ -680,6 +680,21 @@ function describeState(
// Every overlay element on the title lanes: titles, shapes, stickers —
// each entry carries its `kind`.
overlays: s.overlays.map((o) => ({ id: o.id, ...describeOverlay(o) })),
+ // Each group's camera once, keys in seconds from the group's start
+ // (set_group_camera); the members carry only their groupId.
+ ...(() => {
+ const cams = groupCameras(s.overlays);
+ return cams.length
+ ? {
+ groupCameras: cams.map((c) => ({
+ groupId: c.groupId,
+ start: r(c.start),
+ keys: c.keys.map((k) => ({ ...k, t: r(k.t), x: r(k.x), y: r(k.y), scale: r(k.scale), rotation: r(k.rotation) })),
+ ...(c.motionBlur ? { motionBlur: r(c.motionBlur) } : {}),
+ })),
+ }
+ : {};
+ })(),
subtitles: {
count: s.subtitles.cues.length,
showOnVideo: s.subtitles.showOnVideo,
@@ -841,6 +856,8 @@ function describeOverlay(o: Overlay) {
y: r(o.y),
...(o.rotation ? { rotation: o.rotation } : {}),
...(o.opacity !== undefined ? { opacity: r(o.opacity) } : {}),
+ ...(o.blur ? { blur: r(o.blur) } : {}),
+ ...(o.motionBlur ? { motionBlur: r(o.motionBlur) } : {}),
...(hasOverlayAnim(o.anim) ? { anim: o.anim } : {}),
...(o.kf?.length
? { keyframes: o.kf.map((k) => ({ ...k, t: r(k.t), x: r(k.x), y: r(k.y) })) }
diff --git a/site/src/cut/lib/aiTools.ts b/site/src/cut/lib/aiTools.ts
index f53fcd35..2a6d4a06 100644
--- a/site/src/cut/lib/aiTools.ts
+++ b/site/src/cut/lib/aiTools.ts
@@ -88,12 +88,17 @@ import {
import type { AiPanelToolName } from "@/cut/components/AiPanel.tools";
import type { OverlayAnimationToolName } from "@/cut/components/AnimationTiles.tools";
import type { AudioToolName } from "@/cut/components/AudioPanel.tools";
+import type { CameraCardToolName } from "@/cut/components/CameraCardSection.tools";
import type { EditorToolName } from "@/cut/components/Editor.tools";
import type { EffectsToolName } from "@/cut/components/EffectsPanel.tools";
import { SHAPE_KINDS, type ElementsToolName } from "@/cut/components/ElementsPanel.tools";
import type { VideoGenToolName } from "@/cut/components/GeneratePanel.tools";
import type { ImageGenToolName } from "@/cut/components/ImageGenPanel.tools";
import type { InspectorToolName } from "@/cut/components/Inspector.tools";
+import type { GroupPanelToolName } from "@/cut/components/GroupPanel.tools";
+import { CAMERA_SCALE_MAX, CAMERA_SCALE_MIN, ELEMENT_BLUR_MAX, isEaseId, upsertKey as upsertCameraKey, type CameraKey } from "@donkeycut/effects-kit";
+import { groupCameraOf, groupCameraPoseAt } from "@/cut/lib/groupCamera";
+import { cutMotion } from "@/cut/lib/motionSettings";
import type { LibraryToolName } from "@/cut/components/LibraryView.tools";
import type { PreviewToolName } from "@/cut/components/Preview.tools";
import type { RemovalToolName } from "@/cut/components/RemovalPanel.tools";
@@ -700,6 +705,8 @@ const toolRuns: Record<BrowserToolName, ToolRun> = {
...(isNum(k.scale) ? { scale: clamp(k.scale, 0.1, 4) } : {}),
...(isNum(k.rotation) ? { rotation: clamp(Math.round(k.rotation), -180, 180) } : {}),
...(isNum(k.opacity) ? { opacity: clamp(k.opacity, 0, 1) } : {}),
+ ...(isNum(k.blur) ? { blur: clamp(k.blur, 0, ELEMENT_BLUR_MAX) } : {}),
+ ...(k.ease !== undefined ? { ease: easeInput(k.ease) } : {}),
},
{ transient: true }
);
@@ -709,6 +716,53 @@ const toolRuns: Record<BrowserToolName, ToolRun> = {
return { id: o.id, keys: (kf ?? []).map((k) => ({ ...k, t: round2(k.t) })) };
},
+ set_group_camera: (s, input) => {
+ const memberIds = Array.isArray(input.ids) ? input.ids.map(String) : [];
+ const groupId =
+ typeof input.group_id === "string" && input.group_id
+ ? input.group_id
+ : memberIds.map((id) => s.overlays.find((o) => o.id === id)?.groupId).find(Boolean);
+ if (!groupId) throw new ToolError("Pass group_id, or ids of elements in a group (group_items makes one).");
+ const view = groupCameraOf(s.overlays, groupId);
+ if (!view) throw new ToolError(`Group ${groupId} has no titles, shapes or stickers for a camera to film.`);
+ let keys = view.keys;
+ if (input.keys !== undefined) {
+ if (!Array.isArray(input.keys)) throw new ToolError("keys must be a list.");
+ keys = [];
+ for (const k of input.keys as Record<string, unknown>[]) {
+ if (!isNum(k.t)) throw new ToolError("Every key needs a time `t`.");
+ const t = clamp(k.t, 0, Math.max(0.1, view.end - view.start));
+ // Omitted fields hold the camera where it already was at that time.
+ const was = groupCameraPoseAt(view, t);
+ const key: CameraKey = {
+ t,
+ x: isNum(k.x) ? clamp(k.x, -1, 2) : was.x,
+ y: isNum(k.y) ? clamp(k.y, -1, 2) : was.y,
+ scale: isNum(k.scale) ? clamp(k.scale, CAMERA_SCALE_MIN, CAMERA_SCALE_MAX) : was.scale,
+ rotation: isNum(k.rotation) ? clamp(k.rotation, -180, 180) : was.rotation,
+ ...(k.ease !== undefined && easeInput(k.ease) ? { ease: easeInput(k.ease) } : {}),
+ };
+ keys = upsertCameraKey(keys, key);
+ }
+ }
+ const motionBlur =
+ isNum(input.shutter) && input.shutter > 0
+ ? clamp(input.shutter, 0.05, 1)
+ : input.motion_blur === true
+ ? view.motionBlur ?? cutMotion().motionBlur
+ : input.motion_blur === false || (isNum(input.shutter) && input.shutter <= 0)
+ ? undefined
+ : view.motionBlur;
+ s.setGroupCamera(groupId, { keys, ...(motionBlur ? { motionBlur } : {}) });
+ const next = groupCameraOf(useEditor.getState().overlays, groupId)!;
+ return {
+ groupId,
+ start: round2(next.start),
+ keys: next.keys.map((k) => ({ ...k, t: round2(k.t), x: round2(k.x), y: round2(k.y), scale: round2(k.scale) })),
+ motionBlur: next.motionBlur ?? null,
+ };
+ },
+
set_clip_keyframes: (s, input) => {
const clip = requireItem(s.clips, input.clipId, "video clip");
const raw = input.keys;
@@ -6332,6 +6386,13 @@ async function launchVideoJob(
* position, rotation, opacity, hidden) plus the target kind's own fields.
* Outline width is em for text (scales with the type) and design px for
* shapes, so the interpretation follows the element being patched. */
+/** A key's ease from a call: a known curve, or linear (no ease) for
+ * "linear" and anything else. */
+function easeInput(v: unknown) {
+ if (!isEaseId(v)) throw new ToolError("ease must be one of the listed curves.");
+ return v === "linear" ? undefined : v;
+}
+
function overlayPatch(input: Record<string, unknown>, kind: "text" | "shape" | "sticker" | "effect") {
const patch: Record<string, unknown> = {};
if (isNum(input.start)) patch.start = Math.max(0, input.start);
@@ -6343,6 +6404,12 @@ function overlayPatch(input: Record<string, unknown>, kind: "text" | "shape" | "
patch.rotation = Math.round(clamp(input.rotation, -180, 180)) || undefined;
if (isNum(input.opacity))
patch.opacity = input.opacity >= 0.995 ? undefined : clamp(input.opacity, 0, 1);
+ if (kind !== "effect") {
+ if (isNum(input.blur)) patch.blur = input.blur <= 0.05 ? undefined : clamp(input.blur, 0, ELEMENT_BLUR_MAX);
+ if (isNum(input.shutter)) patch.motionBlur = input.shutter <= 0 ? undefined : clamp(input.shutter, 0.05, 1);
+ else if (input.motion_blur === true) patch.motionBlur = cutMotion().motionBlur;
+ if (input.motion_blur === false) patch.motionBlur = undefined;
+ }
if (typeof input.hidden === "boolean") patch.hidden = input.hidden || undefined;
if (typeof input.name === "string") patch.name = input.name.trim().slice(0, 60) || undefined;
diff --git a/site/src/cut/lib/behindPass.ts b/site/src/cut/lib/behindPass.ts
index a3e0ecf4..a526892a 100644
--- a/site/src/cut/lib/behindPass.ts
+++ b/site/src/cut/lib/behindPass.ts
@@ -20,8 +20,12 @@ import {
hasGlyphMotion,
maskComposite,
overlayWords,
+ paintElementInto,
wordSampleWindows,
+ type OverlayFrameState,
+ type PaintPhase,
} from "@donkeycut/effects-kit";
+import { ElementFx, elementLook } from "@donkeycut/effects-kit";
import { personSegmenter, segmentSubjectAlpha } from "./cutout";
import { allowance, holdMemory } from "./memoryBudget";
import { createRasterCanvas } from "./raster";
diff --git a/site/src/cut/lib/exportRender.ts b/site/src/cut/lib/exportRender.ts
index 9f97f2e8..baed59ec 100644
--- a/site/src/cut/lib/exportRender.ts
+++ b/site/src/cut/lib/exportRender.ts
@@ -42,12 +42,15 @@ import type { InputVideoTrack, WrappedCanvas } from "mediabunny";
import { allowance, canvasBytes, holdMemory } from "./memoryBudget";
import { getClipSpans, overlayLayers, projectDuration, spanSequence } from "./store";
import { captionStyle, cueOverlay, cueWordFrames, laneCues, laneHidden, subtitleLaneCount, trackPos } from "./subtitles";
+import { ElementFx, elementLook } from "@donkeycut/effects-kit";
+import { darkenCanvas } from "@donkeycut/effects-kit";
import { applyEffectToCanvas, diveView, divesAt, evalOverlayFrame, measureDiveFocus, retimeOf, grainTile, smoothsAt, isAudioEffect, isMaskAnimated, isOverlayAnimated, maskFrameAt, MATTE_FPS, matteLumaToAlpha, planAnimatedLayers, type DiveFocus, type LottieHandle, type OverlayAnim, type PaintPhase } from "@donkeycut/effects-kit";
import { backdropStill, loadBackdropStill } from "./backdropStills";
import { hasSubjectOverlays, SubjectMaskCompositor } from "./behindPass";
import { createRasterCanvas, type RasterSurface } from "./raster";
import { exportFrameSynth, SYNTH_EDGE, synthWeight, type FrameSynth } from "./frameSynth";
import { cutRenderEnv, renderElementCanvas, renderElementPng } from "./textRender";
+import { cardMatteKey } from "./cameraCard";
import { assetIsSilent, behindSubjectOverlay, clipCovers, frameOf, frontSubjectOverlay, isEffectOverlay, isTextOverlay, laneOf, overlayAnimStyle, projectBackground, rectOf, removalActive } from "./types";
import type { ClipAnim, ClipSpan, EffectOverlay, MediaAsset, Overlay, StickerOverlay } from "./types";
import type { ExportDoc } from "./renderSnapshot";
@@ -952,6 +955,26 @@ export function mixSpecFor(doc: ExportDoc, resolve: (asset: MediaAsset) => strin
};
}
+/**
+ * The mix spec of one stem: the video clips' sound, or one soundtrack lane.
+ * Everything else is left out, while the duck envelope still comes from the
+ * whole mix — a music lane printed alone still dips under the voiceover the
+ * way it does in the mix — and the effect elements treat every stem over
+ * their own windows.
+ */
+export function stemMixSpec(spec: MixSpec, stem: StemDef): MixSpec {
+ const ducks = duckWindows(spec.items);
+ if (stem.lane === null) {
+ return { ...spec, items: spec.items.filter((i) => i.lane === undefined), ducks };
+ }
+ return {
+ ...spec,
+ clips: [{ file: "", in: 0, out: spec.duration, muted: true }],
+ items: spec.items.filter((i) => i.lane === stem.lane),
+ ducks,
+ };
+}
+
/** Whether a mix spec has anything audible in it — the same test the mixer
* uses to decide which spans it decodes. */
export function mixHasSound(spec: MixSpec): boolean {
diff --git a/site/src/cut/lib/groupCamera.test.ts b/site/src/cut/lib/groupCamera.test.ts
new file mode 100644
index 00000000..fade47cd
--- /dev/null
+++ b/site/src/cut/lib/groupCamera.test.ts
@@ -0,0 +1,42 @@
+import { describe, expect, test } from "bun:test";
+import { evalOverlayFrame } from "@donkeycut/effects-kit";
+import { groupCameraOf, groupCameras, withGroupCamera } from "./groupCamera";
+import type { Overlay } from "./types";
+
+const card = (id: string, start: number, x: number): Overlay =>
+ ({ id, kind: "text", text: id, start, end: start + 4, x, y: 0.5, groupId: "g1" }) as Overlay;
+
+const keys = [
+ { t: 0, x: 0.2, y: 0.5, scale: 1, rotation: 0 },
+ { t: 2, x: 0.8, y: 0.5, scale: 2, rotation: 0 },
+];
+
+describe("group camera clocks", () => {
+ test("each member stores the keys on its own clock and the group reads them back", () => {
+ const board = withGroupCamera([card("a", 1, 0.2), card("b", 2, 0.8)], "g1", { keys, motionBlur: 0.5 });
+ expect(board[0].camera!.kf.map((k) => k.t)).toEqual([0, 2]);
+ expect(board[1].camera!.kf.map((k) => k.t)).toEqual([-1, 1]);
+ const view = groupCameraOf(board, "g1")!;
+ expect(view.start).toBe(1);
+ expect(view.keys).toEqual(keys);
+ expect(view.motionBlur).toBe(0.5);
+ expect(groupCameras(board).map((v) => v.groupId)).toEqual(["g1"]);
+ });
+
+ test("every member sees the same camera at the same timeline moment", () => {
+ const [a, b] = withGroupCamera([card("a", 1, 0.2), card("b", 2, 0.8)], "g1", { keys });
+ // Timeline 2.5s: a is 1.5s in, b is 0.5s in. Both look through one camera,
+ // so their screen gap is their world gap times the zoom.
+ const fa = evalOverlayFrame(a, 1.5, 1);
+ const fb = evalOverlayFrame(b, 0.5, 1);
+ expect(fa.scale).toBeCloseTo(fb.scale);
+ expect(fb.x - fa.x).toBeCloseTo(0.6 * fa.scale);
+ });
+
+ test("clearing removes the field from every member", () => {
+ const board = withGroupCamera([card("a", 1, 0.2), card("b", 2, 0.8)], "g1", { keys });
+ const cleared = withGroupCamera(board, "g1", { keys: [] });
+ expect(cleared.every((o) => !("camera" in o))).toBe(true);
+ expect(groupCameras(cleared)).toEqual([]);
+ });
+});
diff --git a/site/src/cut/lib/groupCamera.ts b/site/src/cut/lib/groupCamera.ts
new file mode 100644
index 00000000..b429688b
--- /dev/null
+++ b/site/src/cut/lib/groupCamera.ts
@@ -0,0 +1,96 @@
+import { cameraAt, hasCameraKeys, type CameraKey, type CameraPose, type GroupCamera } from "@donkeycut/effects-kit";
+import type { Overlay } from "./types";
+
+/**
+ * A group's camera as the editor and the assistant see it: one key track in
+ * seconds from the group's start. Each element member stores its own copy
+ * with times from its own start (see the kit's camera.ts), so this module is
+ * the one place that converts between the two clocks.
+ */
+export interface GroupCameraView {
+ groupId: string;
+ /** Timeline seconds the group's elements start and end. */
+ start: number;
+ end: number;
+ /** Keys in seconds from `start`, in play order. */
+ keys: CameraKey[];
+ motionBlur?: number;
+}
+
+/** The elements a group's camera films: every member with a pose. */
+export function cameraMembers(overlays: readonly Overlay[], groupId: string): Overlay[] {
+ return overlays.filter((o) => o.groupId === groupId && o.kind !== "effect");
+}
+
+const round3 = (v: number) => Math.round(v * 1000) / 1000;
+
+/** The group's camera, read off its earliest member; null when the group has
+ * no elements. A group with no camera reads as an empty track. */
+export function groupCameraOf(overlays: readonly Overlay[], groupId: string): GroupCameraView | null {
+ const members = cameraMembers(overlays, groupId);
+ if (!members.length) return null;
+ const start = Math.min(...members.map((m) => m.start));
+ const end = Math.max(...members.map((m) => m.end));
+ const holder = [...members].sort((a, b) => a.start - b.start).find((m) => m.camera);
+ const cam = holder?.camera;
+ return {
+ groupId,
+ start,
+ end,
+ keys: cam ? [...cam.kf].map((k) => ({ ...k, t: round3(k.t + holder.start - start) })).sort((a, b) => a.t - b.t) : [],
+ ...(cam?.motionBlur ? { motionBlur: cam.motionBlur } : {}),
+ };
+}
+
+/** Every group that carries a camera. */
+export function groupCameras(overlays: readonly Overlay[]): GroupCameraView[] {
+ const ids = new Set(overlays.flatMap((o) => (o.camera && o.groupId ? [o.groupId] : [])));
+ return [...ids].flatMap((id) => {
+ const view = groupCameraOf(overlays, id);
+ return view && (view.keys.length || view.motionBlur) ? [view] : [];
+ });
+}
+
+/** The overlays with the group's camera written onto every element member,
+ * each on its own clock. `null`, or no keys and no motion blur, removes it. */
+export function withGroupCamera(
+ overlays: readonly Overlay[],
+ groupId: string,
+ cam: { keys: CameraKey[]; motionBlur?: number } | null
+): Overlay[] {
+ const members = cameraMembers(overlays, groupId);
+ if (!members.length) return [...overlays];
+ const start = Math.min(...members.map((m) => m.start));
+ const ids = new Set(members.map((m) => m.id));
+ const live = cam && (cam.keys.length > 0 || !!cam.motionBlur) ? cam : null;
+ return overlays.map((o) => {
+ if (!ids.has(o.id)) return o;
+ if (!live) return withoutCamera(o);
+ const camera: GroupCamera = {
+ kf: [...live.keys]
+ .sort((a, b) => a.t - b.t)
+ .map((k) => ({ ...k, t: round3(k.t + start - o.start) })),
+ ...(live.motionBlur ? { motionBlur: live.motionBlur } : {}),
+ };
+ return { ...o, camera } as Overlay;
+ });
+}
+
+/** An element with no camera field at all. */
+export function withoutCamera<O extends { camera?: GroupCamera }>(o: O): O {
+ if (!("camera" in o)) return o;
+ const { camera: _drop, ...rest } = o;
+ void _drop;
+ return rest as O;
+}
+
+/** The camera's pose at `tGroup` seconds into the group. */
+export function groupCameraPoseAt(view: Pick<GroupCameraView, "keys">, tGroup: number): CameraPose {
+ return cameraAt({ kf: view.keys }, tGroup);
+}
+
+/** The camera an element is filmed through at `tLocal` seconds into it, or
+ * null when its group has none. */
+export function elementCameraAt(o: { camera?: GroupCamera }, tLocal: number): CameraPose | null {
+ return hasCameraKeys(o.camera) ? cameraAt(o.camera, tLocal) : null;
+}
diff --git a/site/src/cut/lib/itemKinds.ts b/site/src/cut/lib/itemKinds.ts
index 91c17033..775b23ba 100644
--- a/site/src/cut/lib/itemKinds.ts
+++ b/site/src/cut/lib/itemKinds.ts
@@ -156,7 +156,8 @@ export const ITEM_KINDS: { [K in ItemKind]: ItemKindDef<K> } = {
duration: (o) => o.end - o.start,
lane: (o) => o.lane ?? 0,
at: (o, start) => ({ ...o, start, end: start + o.end - o.start }),
- split: (o, at) => [{ ...o, end: at }, { ...o, start: at }],
+ // The tail keeps filming on the group camera's clock.
+ split: (o, at) => [{ ...o, end: at }, { ...o, start: at, ...(o.camera ? { camera: shiftCamera(o.camera, o.start - at) } : {}) }],
clone: deep,
assetIds: (o) => {
if (isStickerOverlay(o)) return o.assetId ? [o.assetId] : [];
diff --git a/site/src/cut/lib/laneTracks.ts b/site/src/cut/lib/laneTracks.ts
index 5b482aa3..314957d1 100644
--- a/site/src/cut/lib/laneTracks.ts
+++ b/site/src/cut/lib/laneTracks.ts
@@ -1,6 +1,7 @@
"use client";
import { retimeOf, type Retimable, type SpeedNode } from "@donkeycut/effects-kit";
+import { shiftCamera } from "@donkeycut/effects-kit";
/**
* The lane-track coordinator: the one place for how items on the timeline's
@@ -293,7 +294,12 @@ const textAdapter: LaneAdapter<Overlay> = {
view: (o) => ({ id: o.id, start: o.start, len: ITEM_KINDS.overlay.duration(o), lane: ITEM_KINDS.overlay.lane(o) }),
apply: (patches) => useEditor.getState().updateOverlaysTransient(patches),
movePatch: (o, start) => ({ id: o.id, patch: ITEM_KINDS.overlay.at(o, start) }),
- trimLeftPatch: (o, newStart) => ({ id: o.id, patch: { start: newStart } }),
+ // A left trim moves the element's clock; its group camera shifts with it so
+ // the camera stays on the group's time.
+ trimLeftPatch: (o, newStart) => ({
+ id: o.id,
+ patch: { start: newStart, ...(o.camera ? { camera: shiftCamera(o.camera, o.start - newStart) } : {}) },
+ }),
trimRightPatch: (o, newEnd) => ({ id: o.id, patch: { end: newEnd } }),
leftFloor: () => 0,
maxLen: () => Infinity,
diff --git a/site/src/cut/lib/motionSettings.ts b/site/src/cut/lib/motionSettings.ts
new file mode 100644
index 00000000..2c34092c
--- /dev/null
+++ b/site/src/cut/lib/motionSettings.ts
@@ -0,0 +1,17 @@
+import { SETTINGS, type Settings } from "@/lib/config/registry";
+
+// Motion tunables — the shutter a newly switched-on motion blur starts at —
+// bound once at session start from account config (the tab) or the global
+// setting (a worker job). The value is written onto the item when the blur is
+// switched on, so every renderer draws from the item alone.
+
+let motion: Settings["cutMotion"] = SETTINGS.cutMotion.default;
+
+export function bindCutMotion(value: unknown): void {
+ const parsed = SETTINGS.cutMotion.schema.safeParse(value);
+ if (parsed.success) motion = parsed.data;
+}
+
+export function cutMotion(): Settings["cutMotion"] {
+ return motion;
+}
diff --git a/site/src/cut/lib/previewSelection.ts b/site/src/cut/lib/previewSelection.ts
index 09d0e943..36f72ea5 100644
--- a/site/src/cut/lib/previewSelection.ts
+++ b/site/src/cut/lib/previewSelection.ts
@@ -1,8 +1,10 @@
import { textBoxSize } from "@/cut/lib/textFit";
import { PLATE_PAD_X, hasOverlayKeys, keyAt, upsertKey, type OverlayKey } from "@donkeycut/effects-kit";
+import { cameraPoint, worldPoint, type CameraPose } from "@donkeycut/effects-kit";
+import { elementCameraAt } from "@/cut/lib/groupCamera";
import { clipLen, type EditorState } from "@/cut/lib/store";
import { frameOf, clampOverlayPos, clipKeyed, clipPoseAt, isShapeOverlay, isTextOverlay, rectOf, type FrameRect, type OverlayPatch, type Selection } from "@/cut/lib/types";
-import { captionStyle, laneHidden, trackPos } from "@/cut/lib/subtitles";
+import { captionStyle, cueAnchor, laneHidden, trackPos } from "@/cut/lib/subtitles";
export const SELECTABLE_ITEM_KINDS = ["clip", "audio", "overlay", "cue"] as const;
@@ -23,12 +25,25 @@ type Position = {
lane?: number;
/** The item's angle at the gesture's start, degrees clockwise. */
rotation: number;
+ /** A caption with its own spot moves that spot; the rest move their
+ * track's. */
+ own?: boolean;
/** What a scale gesture grows: a shape or sticker's box, a title's size or
* wrapping width, a clip's frame. A keyed item scales its key instead. */
box?: { w: number; h?: number };
text?: { size: number; wrapWidth?: number; width: number };
+ /** The group camera filming the item: its x, y and rotation above are on
+ * screen, and every write turns them back into the world. */
+ cam?: { pose: CameraPose; aspect: number };
};
+/** A screen pose back in the item's own world; unchanged with no camera. */
+function toWorld(p: Position, x: number, y: number, rotation?: number) {
+ if (!p.cam) return { x, y, rotation };
+ const w = worldPoint(p.cam.pose, x, y, p.cam.aspect);
+ return { x: w.x, y: w.y, rotation: rotation === undefined ? undefined : Math.round(normDeg(rotation - p.cam.pose.rotation)) };
+}
+
/** Into (-180, 180], the range every rotation is stored in. */
export const normDeg = (deg: number) => ((((deg + 180) % 360) + 360) % 360) - 180;
@@ -39,10 +54,16 @@ export function previewSelectionSnapshot(s: EditorState, t: number): Position[]
const positions: Position[] = [];
for (const o of s.overlays) {
if (!selected.has(`overlay:${o.id}`) || o.hidden || o.kind === "effect") continue;
- const key = hasOverlayKeys(o) ? keyAt(o, Math.max(0, Math.min(t - o.start, Math.max(0.1, o.end - o.start)))) : undefined;
+ const tl = Math.max(0, Math.min(t - o.start, Math.max(0.1, o.end - o.start)));
+ const key = hasOverlayKeys(o) ? keyAt(o, tl) : undefined;
+ // A filmed element is gestured where it shows: on screen, through its camera.
+ const pose = elementCameraAt(o, tl);
+ const frame = frameOf(s.aspect);
+ const cam = pose ? { pose, aspect: frame.w / frame.h } : undefined;
+ const seen = cam ? cameraPoint(cam.pose, key?.x ?? o.x, key?.y ?? o.y, cam.aspect) : { x: key?.x ?? o.x, y: key?.y ?? o.y };
positions.push({
- kind: "overlay", id: o.id, x: key?.x ?? o.x, y: key?.y ?? o.y, key, keys: o.kf,
- rotation: key?.rotation ?? o.rotation ?? 0,
+ kind: "overlay", id: o.id, x: seen.x, y: seen.y, key, keys: o.kf, cam,
+ rotation: (key?.rotation ?? o.rotation ?? 0) + (cam?.pose.rotation ?? 0),
box: isShapeOverlay(o) || o.kind === "sticker" ? { w: o.w, h: o.h } : undefined,
text: isTextOverlay(o) ? { size: o.size, wrapWidth: o.wrapWidth, width: (textBoxSize(o, frameOf(s.aspect).w).width - (o.plate ? 2 * PLATE_PAD_X * o.size : 0)) / frameOf(s.aspect).w } : undefined,
});
@@ -79,6 +100,8 @@ export function previewSelectionSnapshot(s: EditorState, t: number): Position[]
export function movePreviewSelection(s: EditorState, positions: Position[], dx: number, dy: number) {
let minX = -Infinity, maxX = Infinity, minY = -Infinity, maxY = Infinity;
for (const p of positions) {
+ // A filmed element may sit off screen while the camera is pushed in.
+ if (p.cam) continue;
const f = p.kind === "clip" && !p.key ? p.frame : undefined;
minX = Math.max(minX, Math.min(0, (f ? 0.05 - f.w : 0.02) - p.x));
maxX = Math.min(maxX, Math.max(0, (f ? 0.95 : 0.98) - p.x));
@@ -89,10 +112,11 @@ export function movePreviewSelection(s: EditorState, positions: Position[], dx:
dy = Math.max(minY, Math.min(maxY, dy));
const patches: Parameters<EditorState["updateDocTransient"]>[0] = { clips: [], overlays: [] };
for (const p of positions) {
- const x = p.x + dx, y = p.y + dy;
+ const { x, y } = toWorld(p, p.x + dx, p.y + dy);
const keyed = p.key ? { kf: upsertKey(p.keys, { ...p.key, x, y }) } : null;
if (p.kind === "overlay") patches.overlays!.push({ id: p.id, patch: keyed ?? { x, y } });
else if (p.kind === "clip") patches.clips!.push({ id: p.id, patch: keyed ?? { frame: { ...p.frame!, x, y } } });
+ else if (p.own) s.setCuePosition(p.id, { x, y });
else s.setSubtitleTrackMeta(p.lane!, { x, y });
}
if (patches.clips!.length || patches.overlays!.length) s.updateDocTransient(patches);
@@ -165,7 +189,7 @@ export function scalePreviewSelection(s: EditorState, positions: Position[], anc
? { size: Math.max(8, p.text.size * k), wrapWidth: p.text.wrapWidth === undefined ? undefined : p.text.wrapWidth * k }
: { size: p.text.size, wrapWidth: Math.max(0.01, Math.min(2, (p.text.wrapWidth ?? p.text.width) * kx)) };
}
- return { p, x: clampOverlayPos(cx), y: clampOverlayPos(cy), own };
+ return { p, x: p.cam ? cx : clampOverlayPos(cx), y: p.cam ? cy : clampOverlayPos(cy), own };
}));
}
diff --git a/site/src/cut/lib/store.ts b/site/src/cut/lib/store.ts
index 38cee33b..822e7283 100644
--- a/site/src/cut/lib/store.ts
+++ b/site/src/cut/lib/store.ts
@@ -61,6 +61,8 @@ import type {
} from "./types";
import type { VideoProject } from "./genvideo/types";
import { expandTimelineGroups, reorderTimelineClip, selectedGroupIds, setTimelineGroup } from "./timelineGroups";
+import { groupCameraOf, withGroupCamera, withoutCamera } from "./groupCamera";
+import type { CameraKey } from "@donkeycut/effects-kit";
import { mapTimelineItems, pasteTimelineItems, splitTimelineItems, shiftedTimelineItems, timelineCopies, timelinePlacementDelta, timelineRange } from "./timelineItems";
import { fillSlot } from "./genvideo/fillSlot";
import { apiFetch, apiJson, getBackend, hasLocalCompute } from "./backend";
@@ -955,6 +957,13 @@ export interface EditorState {
groupSelection: () => string | null;
moveTimelineSelection: (delta: number) => number;
ungroupSelection: () => void;
+ /** Write a group's camera onto every element member, keys in seconds from
+ * the group's start; null removes it. */
+ setGroupCamera: (
+ groupId: string,
+ cam: { keys: CameraKey[]; motionBlur?: number } | null,
+ opts?: { transient?: boolean }
+ ) => void;
/** ⌘/⇧-click: add the item to the selection (or remove it if already in),
* making it the new primary. */
toggleSelect: (sel: NonNullable<Selection>) => void;
@@ -1046,6 +1055,7 @@ function rebaseShared(snaps: DocSnapshot[], then: SharedFields, now: SharedField
new Set([...b].filter(([id, v]) => a.has(id) && a.get(id) !== v).map(([id]) => id));
const beats = moved(then.beats, now.beats);
const profiles = moved(then.profiles, now.profiles);
+ const sounds = moved(then.sounds, now.sounds);
for (const snap of snaps) {
if (now.guideLines !== then.guideLines) snap.guideLines = { v: [...now.guideLines.v], h: [...now.guideLines.h] };
if (now.colorSpace !== then.colorSpace) snap.colorSpace = now.colorSpace;
@@ -2795,7 +2805,7 @@ export const useEditor = create<EditorState>((baseSet, get, api) => {
!st.clips.some((c) => c.assetId === id) &&
!st.audioClips.some((c) => c.assetId === id)
) {
- set((s) => ({ assets: s.assets.filter((a) => a.id !== id), timelines: timelinesWithout(s.timelines, id) }));
+ set((s) => ({ assets: remaining(s.assets), timelines: timelinesWithout(s.timelines, id) }));
dropFile();
return;
}
@@ -2810,7 +2820,7 @@ export const useEditor = create<EditorState>((baseSet, get, api) => {
(sel.kind === "audio" && goneAudio.has(sel.id)));
const multiSelection = s.multiSelection.filter(keep);
return {
- assets: s.assets.filter((a) => a.id !== id),
+ assets: remaining(s.assets),
clips: s.clips.filter((c) => c.assetId !== id),
audioClips: s.audioClips.filter((c) => c.assetId !== id),
timelines: timelinesWithout(s.timelines, id),
@@ -4225,7 +4235,21 @@ export const useEditor = create<EditorState>((baseSet, get, api) => {
push();
const groupId = uid();
const grouped = setTimelineGroup(s, members, groupId);
- set({ ...grouped, subtitles: { ...s.subtitles, cues: grouped.subtitles.cues }, multiSelection: members });
+ // A camera one of the old groups carried films the new one: the
+ // earliest such group's track, on the new group's clock.
+ const filmed = [...selectedGroupIds(s, members)]
+ .map((id) => groupCameraOf(s.overlays, id))
+ .filter((v) => !!v && (v.keys.length > 0 || !!v.motionBlur))
+ .sort((a, b) => a!.start - b!.start)[0];
+ const fresh = grouped.overlays.map((o) => (o.groupId === groupId ? withoutCamera(o) : o));
+ const overlays = filmed
+ ? (() => {
+ const start = Math.min(...fresh.filter((o) => o.groupId === groupId && o.kind !== "effect").map((o) => o.start));
+ const keys = filmed.keys.map((k) => ({ ...k, t: k.t + filmed.start - start }));
+ return withGroupCamera(fresh, groupId, { keys, motionBlur: filmed.motionBlur });
+ })()
+ : fresh;
+ set({ ...grouped, overlays, subtitles: { ...s.subtitles, cues: grouped.subtitles.cues }, multiSelection: members });
return groupId;
},
diff --git a/site/src/cut/server/ai/catalog.ts b/site/src/cut/server/ai/catalog.ts
index 96e6836d..d6ac364d 100644
--- a/site/src/cut/server/ai/catalog.ts
+++ b/site/src/cut/server/ai/catalog.ts
@@ -78,10 +78,12 @@ export const AI_TOOLS: AiToolDef[] = [
...PREVIEW_TOOLS,
...TIMELINE_TOOLS,
...INSPECTOR_TOOLS,
+ ...CAMERA_CARD_TOOLS,
...REMOVAL_TOOLS,
...ELEMENTS_TOOLS,
...EFFECTS_TOOLS,
...OVERLAY_ANIMATION_TOOLS,
+ ...GROUP_PANEL_TOOLS,
...TRANSITIONS_TOOLS,
...SUBTITLES_TOOLS,
...AUDIO_TOOLS,
@@ -120,8 +122,8 @@ export const TOOL_AREAS: Record<string, { blurb: string; tools: AiToolDef[] }> =
},
inspector: {
blurb:
- "the selected item's settings: an overlay's text, position, size and style; masks; clip and overlay keyframes; a clip's audio, volume and sound; framing, clip style, speed",
- tools: INSPECTOR_TOOLS.filter((t) => !COLOR_TOOL.test(t.name)),
+ "the selected item's settings: an overlay's text, position, size and style; masks; clip and overlay keyframes; a clip's audio, volume and sound; framing, clip style, speed; the camera-card split layout",
+ tools: [...INSPECTOR_TOOLS.filter((t) => !COLOR_TOOL.test(t.name)), ...CAMERA_CARD_TOOLS],
},
color: {
blurb: "color grading: a clip's color stats, grades, presets, curves, wheels, HSL, LUTs, source color (log/HDR footage), matching a reference's grade, copying a grade to other clips, saved grades",
@@ -140,8 +142,8 @@ export const TOOL_AREAS: Record<string, { blurb: string; tools: AiToolDef[] }> =
tools: [...EFFECTS_TOOLS],
},
animation: {
- blurb: "an overlay element's entrance, exit and loop animations and keyframed motion",
- tools: [...OVERLAY_ANIMATION_TOOLS],
+ blurb: "an overlay element's entrance, exit and loop animations, keyframed motion, blur and motion blur; a group's camera moving over its elements",
+ tools: [...OVERLAY_ANIMATION_TOOLS, ...GROUP_PANEL_TOOLS],
},
transitions: {
blurb: "transitions between clips, and a clip's own in and out animation",
@@ -561,6 +563,38 @@ How to decide the details the user left open. Make the call, apply it, and state
- One treatment at a time. A single look, one accent element per scene, effect amounts under 0.5. Text asked for as text gets one plain face where the words belong; a design goes on when the user asks for one. Every added treatment must serve the footage; when in doubt, leave it out — restraint reads as confidence.
- "Make it cool / cinematic / better" is a request for your judgment: choose one specific treatment that fits this footage, apply it, and name it. A menu of options is an answer only when two readings genuinely diverge.`,
+ "talking-head-videos": `# Talking-head videos
+A raw recording of someone speaking to camera, made into the video the person asked for — any length, any frame. The ask sets the scope: "tighten my takes" is steps 1–3, "add captions" is the caption step, "make this into a finished video" is everything below. Each step is how that part is done well; take the steps the ask needs, in this order, and make every judgement call inside them yourself (which take, which layout, which graphic), naming the calls in a line or two when you finish. Work in the project's frame; every position below is a fraction of it, read against the layout on screen.
+
+**1. Read the recording.** A separate clean recording of the voice (a mic or recorder file beside the camera file) is bound to the camera video with sync_audio before anything else: every clip of that video then plays the clean sound, and every cut, measurement and transcript reads it. subtitles_generate gives the transcript with word timings. watch_video the recording end to end, noting each take with note_source: what it says, and where the speaker's eyes are. A long recording is swept coarse first and watched closely where the takes are (watching-and-cutting skill).
+
+**2. Keep the last good take.** People re-record a line until it lands, so the transcript repeats itself. Group the cues into lines; where a line was said more than once, keep the last complete take, and reach back to an earlier one only when the last has a defect in the words — a stutter, a clipped or wrong word, a restart mid-sentence. Cut the restarts, self-corrections, the "okay"s between takes and the muttered asides; find_filler catches the ums and stutters.
+
+**3. Cut tight.** split_at and delete_item the waves, close the gaps, then refine_speech_cuts on every recut clip — pace fast for a short or a punchy piece, natural for a longer one that should breathe. Pauses longer than the pace's beat come down to it; short natural pauses stay. Every picture cut is a hard cut, and each joint gets a J-cut in the sound: set_split_edit with lead 0.05 on the incoming clip, so its first sound arrives a breath before its picture. listen_audio across every joint: each first and last word arrives whole, and no joint leaves dead air — a bad joint is fixed by cutting earlier or leading more, never by adding silence. The speaker's own footage holds still — no zooms, punch-ins or moves on it; the layout changes carry the variety.
+
+**4. Camera on eye contact.** The camera shows while the speaker looks into the lens. Where they look away mid-line (reading notes, a glance off), the camera leaves at the last on-lens frame — split at the nearest word boundary before the turn — and a full visual covers the rest. A take read off to the side the whole way through is a full visual. Re-watch around each head turn at interval_seconds 0.5 to find the frame.
+
+**5. Three layouts, planned first.** Write the plan as runs tiling the whole cut before building any graphic.
+- Camera: the speaker filling the frame — set_framing fill, panned to hold the face.
+- Split: the speaker in a rounded card with their head rising out of its top edge, the graphic filling the rest of the frame behind; the card's side follows the frame's shape unless the layout wants another. The speaker's cut stays on track 0 with its sound; over the run, the graphic (an image or a screen recording) goes on track 1, and the run's footage again on track 2 — add_overlay_video of the same source, then update_overlay_video to the run's start and trim, muted — with set_camera_card on that copy. Titles, shapes and stickers draw over every video row, so on a split they stay in the part of the frame the card and the head leave free.
+- Visual: a graphic over the whole frame — an image or recording on a track above the speaker, or element cards over a full-frame shape.
+The opening line (the hook) is a split. The call to action and everything after it is camera, as is a line said straight to the viewer — an opinion, a punchline. Screen recordings, web pages and product walk-throughs are visuals. A single screenshot, a logo, a number or a short list is a split. A run holds one idea and two neighbouring runs never share a layout; all three appear. Pace the runs to the piece: in a short no run lasts much over ~8s, and a longer video lets a run hold its idea as long as it takes.
+
+**6. Graphics.** One look across the video: one background, one face, one accent color, held from the first graphic to the last. Each graphic has one dominant subject and at most one supporting cue. Show the thing being talked about — the person's own screenshots and screen recordings first (from media), then stock_search, or generate_image for an illustration or a clean card. The captions carry the words, so a graphic holds no labels restating the narration; a headline at most.
+- Facts: check_facts every figure, date and release the narration states before it goes on screen. Something that happened shows through the person's own screenshot of its source; a source they gave no screenshot of is named in the closing message with the page the check found. A figure that disagrees with its sources is reported there too.
+- Motion: lay a visual's cards out as one world (titles, shapes, stickers placed across and beyond the frame), group_items them, and move a camera over it with set_group_camera — a glide (sine.inOut, zoom change ≤ 0.04), a step to the next card (0.5s power3.inOut, starting 0.25s before the word that names it), a push onto the card being talked about (1.2–2s power2.inOut, up to ~1.6×), a pull back to show the whole, and at most one whip per run (out over 0.45s power3.in, in over 0.6s power3.out). motion_blur on the camera streaks its moves and leaves every frame at rest sharp. Each run's first frame is the camera at rest.
+- Focus: as the camera pushes, the card being read stays sharp and its neighbours take set_overlay_keyframes keys of blur ~14 and opacity ~0.7; a word the viewer has to read is never blurred.
+- A graphic's content keeps clear of the caption band and, on a split, of the card and the head.
+
+**7. Cover, captions, call to action.**
+- Cover: a short opens on its title — add_title on the first frame only (start 0, end 0.04), bold and large, dark on a light rounded add_shape box in the upper part of the frame — written from the hook when the person gave none. A longer video skips it unless asked.
+- Captions: when the cut is final, subtitles_generate again so the captions come from the finished speech. set_caption_look style punchy, a few words per caption (words_per_cue 2 in a short, more in a longer piece), white with a dark outline. set_caption_emphasis marks one or two meaningful words — a product name, a number, a benefit, the call-to-action keyword — after every 2–3 plain captions, never two emphasized captions in a row and never a function word; the look's emphasis style carries them. Position follows the layout, each caption placed with update_cue x/y inside project.safeZones: on a split, in the free band between the graphic's content and the card; on camera, the lower band under the face; on a visual, the band its content leaves free; on the outro, clear of the call to action. A caption never covers the face, the card edge or a visual's content.
+- Call to action: on the outro, a comment box in the lower part of the frame — a white rounded add_shape, the keyword from the call-to-action line as an add_title typed in with a typewriter entrance and a blinking caret (set_overlay_animation caret), then a small Post button (shape and title, grouped) pressed with hit_style press once the keyword is typed. Nothing else on it.
+
+**8. Sound.** set_clip_sound preset studio on the voice. Sound effects come from stock_search kind sound, one per meaningful visible event: a soft click on a button press or tap (the Post press included), a light keyboard tick on typing, a soft pop when a card or device lands, a chime on an answer or confirmation, and a low whoosh only on a camera whip, its loudest moment on the whip's midpoint (at most one per run, varied). Layout cuts, glides, steps and pushes get no sound. A riser of ~2–3s ends exactly on the join where the hook hands to the first point. Music is generate_music instrumental — modern, minimal, warm, 100–120 BPM, no lead melody, length "song" for a video over a minute — trimmed to the cut with a 0.8s fade-out at the end and one flat level throughout (no duck). measure_level sets every level from numbers: the music's integratedLufs 10 LU under the voice's; clicks, pops and chimes peaking ~10 dB under the voice's truePeakDbtp, whooshes ~9, ticks ~16, the riser ~14.
+
+**9. Check before handing it over.** capture_frame both sides of every joint (the new take shows from its first frame), the first frame of every split (the head is there), and a frame in each run (captions clear of the face and the graphic, content inside its zone, a short's first frame a clean cover). listen_audio every joint and every effect: each lands on its visual event, the riser ends on the hook's join. measure_level with mix true confirms the whole video. Fix what fails and check again.`,
+
"media-and-library": `# Media, Library & organizing
Project media (\`media\` in editor_state) is every file in the open project. The Media panel shows the user's own imports — assets with no origin tag; created media (origin generated, voiceover, stock, chat, freeze, recording, block) lives where it was made until filed away.
- add_clip / add_overlay_video place a project asset on the timeline, and add_clip's \`blocks\` lays a cut out ahead of its footage — one block per shot on track 0, the length that shot runs, labelled with what the person supplies; replace_item fills one of those blocks, or swaps any clip's, soundtrack clip's or sticker's source, in place; listen_audio plays an asset's sound to you — an audio asset, or a video/clip's own track; watch_video is the visual sibling.
@@ -610,7 +644,7 @@ Rules:
- Edits are undoable (unlimited undo), so prefer doing over asking; only ask when the request is genuinely ambiguous. Ambiguous means the target itself is unresolvable — "shorten that clip" with nothing selected and several clips gets "Which clip?" and no edit; guessing a target and editing it is worse than the question. The existing cut is the user's work: adding media adds — never delete, trim, or reorder a timeline clip unless the user said to. Read "change it / make it X / try again / closer to the original" as a fresh take that lands on its own card beside the old, never as license to delete the old clip first; only an explicit "replace / delete / remove this" clears what's already there. Items you placed yourself while working the current ask are your own scaffolding: revise, retime, or delete them freely until the result matches the ask — tearing down your own misstep and rebuilding is part of doing the job. The guardrail covers the user's media and the settled work of earlier turns. Generation is different: undo removes the clip but the credits stay spent, so be certain the user asked for the media before calling a generation tool. Removing media is different too — delete_asset and library_organize deletes don't come back with undo, so they take an explicit ask naming the media.
- Times are seconds. A \`@1:34\` in the user's message is a moment on the timeline — minutes and seconds — that they marked while writing it; it is kept pointing at the same picture as the cut changes, so read it as the timeline second it names right now. The frame follows project.aspect in editor_state — any "W:H" ratio, short side 1080px; project.frame has the exact pixels. The frame is the user's setting: work within the shape they chose, and change it only when they ask for a different one. A generation that renders in another shape letterboxes inside their frame — mention that if it matters, and leave the choice to them.
- project.safeZones in editor_state gives, for this frame, the safe area of every guide preset (frame fractions, x/y/w/h) and the keepOut boxes where TikTok, Reels and Shorts draw their own UI or crop the frame's sides — known whether or not a guide shows. When the user names a platform, asks for a safe zone, or wants graphics kept clear of the app's UI, place every title, sticker and caption inside safeZones.shortform.safeArea and check with capture_frame; safeZones.margins is the general 5% inset. A safeArea is a rect — x/y its top-left corner, w/h its size — while an element's x/y is its center: centered in the safe area means x + w/2, y + h/2, and an element of width ew stays inside while its center is between x + ew/2 and x + w − ew/2. Guides are a view: set_guides shows one when the user asks to see it, and showing one changes nothing in the cut.
-- Exercise judgment on details the user left open, and state the choice you made. Judgment fills in the parameters of the asked-for change (style, length, placement); the scope stays the ask, and extra tools, tracks, or treatments beyond it wait for the user to ask. Editing defaults: a hard cut at every joint; when transitions are asked for, one style family per video at 0.4–0.6s. The editing-taste skill carries the full doctrine.
+- Exercise judgment on details the user left open, and state the choice you made. Judgment fills in the parameters of the asked-for change (style, length, placement); the scope stays the ask, and extra tools, tracks, or treatments beyond it wait for the user to ask. Editing defaults: a hard cut at every joint; when transitions are asked for, one style family per video at 0.4–0.6s. The editing-taste skill carries the full doctrine. Editing a recording of someone speaking to camera is the talking-head-videos skill; the ask decides which of its steps run.
- Styling is part of the ask, never a bonus. Words the user asked to put on screen — a title, the lines from the audio, a caption run — go on in one plain readable face at one place, timed to what they are for. Per-line typefaces, tilts, color cards, moves, word effects and a repainted frame are a design, and a design is something the user asks for: a lyric video, kinetic type, a named style or vibe, a reference to match, "make it fun". Call add_text_sequence with no \`look\` for the plain job, and leave the caption styling and the background as you found them.
- A skill attached to the message (<skill_relevance>) is the reference for its area: read it before touching that area's settings. It never changes which tool the ask maps to — the tool descriptions decide that ("a better version" is a render, whatever skill rode along). list_skills / read_skill cover an area the attachment left out.
- A reference image or clip the user attaches ("do this", "put our video in this style") carries one of two asks — decide which before acting. When its footage's look is the point (color, lighting, film grade), route to color grading — match_color_grade computes the grade from the reference's own pixels, then the grading tools refine (color-grading skill) — or to look effects or restyle when the reference is a stylized treatment. When it demonstrates an editing device — a tile grid, a mosaic reveal, a split layout, an animated title treatment — the ask is to construct that device on the user's own footage: read the graphics skill's composite-builds section and build it with overlay tracks, masks, and keyframes. Your tools compose into effects far beyond the preset lists, so reach for construction before declaring something out of reach. Construction is free and undoable; a whole-look re-render (restyle_scene) spends credits — when the reading is ambiguous, say what each path would do and let the user pick.
@@ -653,6 +687,8 @@ export const AI_SKILL_BLURBS: Record<string, string> = {
"ai-generation": "Getting footage the user lacks: stock, URL import, hosted image, video and music generation and their settings; a better version or another take of a clip is a fresh render.",
"scene-productions": "Planning and rendering a narrated multi-shot scene: the plan card, approval, look references, revisions.",
"editing-taste": "Deciding details the user left open: joints, transition families, pacing, when to add and when to leave alone.",
+ "talking-head-videos":
+ "Editing a raw recording of someone speaking to camera into the video the person asked for: syncing a separate mic, picking takes, tight speech cuts, camera, split and full-visual layouts, captions, graphics, sound effects and music.",
"media-and-library": "Project media versus the Media panel, filing assets, the library, organizing and templates.",
"replicating-a-project": "Reading another Donkey Cut project or share link as a document and bringing its edit or items over.",
"replicating-a-video":
diff --git a/site/src/cut/server/exportPipeline.test.ts b/site/src/cut/server/exportPipeline.test.ts
index 58074ba3..f990c567 100644
--- a/site/src/cut/server/exportPipeline.test.ts
+++ b/site/src/cut/server/exportPipeline.test.ts
@@ -1474,3 +1474,100 @@ describe("an HDR delivery", () => {
expect(written.some((w) => w.file.endsWith("graphics.cube"))).toBe(false);
});
});
+
+describe("a mastered delivery", () => {
+ test("the encode pass writes the picture and the raw mix apart; the master joins them", async () => {
+ const runs = await runsFor({ clips: [clip("a.mp4")], loudness: -14, truePeakCeiling: -1 });
+ const enc = runs.find((a) => a.includes("-filter_complex"))!;
+ // The video output carries no audio map of its own.
+ const videoOut = enc.findIndex((a) => a.endsWith("encode.mp4"));
+ expect(enc.slice(0, videoOut).filter((a) => a === "-map")).toHaveLength(1);
+ const mixAt = enc.indexOf("/tmp/graph-test/mix.f32");
+ expect(enc.slice(videoOut, mixAt)).toContain("pcm_f32le");
+ expect(mastered).toEqual([
+ {
+ input: "/tmp/graph-test/mix.f32",
+ output: "/tmp/graph-test/master.f32",
+ opts: { sampleRate: 44100, channels: 2, targetLufs: -14, ceilingDbtp: -1 },
+ },
+ ]);
+ const mux = runs[runs.length - 1];
+ expect(mux).toContain("/tmp/graph-test/master.f32");
+ expect(arg(mux, "-c:v")).toBe("copy");
+ expect(arg(mux, "-c:a")).toBe("aac");
+ expect(mux[mux.length - 1]).toBe("/tmp/graph-test/out.mp4");
+ });
+
+ test("an unmastered delivery keeps its one-pass sound and plain remux", async () => {
+ const runs = await runsFor({ clips: [clip("a.mp4")] });
+ expect(mastered).toEqual([]);
+ expect(arg(runs[runs.length - 1], "-c")).toBe("copy");
+ });
+});
+
+describe("stems", () => {
+ const stemSpec: Partial<ExportSpec> = {
+ clips: [clip("a.mp4")],
+ overlayVideos: [{ file: "b.mp4", in: 0, out: 2, start: 1, track: 1, muted: false }],
+ audio: [
+ { file: "vo.mp3", in: 0, out: 2, start: 0, volume: 1, duck: 0.3 },
+ { file: "song.mp3", in: 0, out: 4, start: 0, volume: 0.5, lane: 1 },
+ ],
+ stemPlan: [
+ { name: "Dialogue", lane: null, file: "1 Dialogue.wav" },
+ { name: "Voiceover", lane: 0, file: "2 Voiceover.wav" },
+ { name: "Music", lane: 1, file: "3 Music.wav" },
+ ],
+ };
+
+ test("every stream the mix sums is split once into its stem, and the mix still sums them all", async () => {
+ const graph = await graphFor(stemSpec);
+ const splits = graph.filter((l) => /asplit=2\[[^\]]+m\]\[[^\]]+s\]$/.test(l));
+ // Track-0 sound, the upper-track clip's, the voiceover and the song.
+ expect(splits).toHaveLength(4);
+ const mix = graph.find((l) => l.endsWith("[amix]"))!;
+ expect(mix).toContain("amix=inputs=4");
+ expect(mix.match(/m\]/g)).toHaveLength(4);
+ });
+
+ test("each stem runs the delivery's length and lands as a 24-bit WAV, then packs into the zip", async () => {
+ const runs = await runsFor({ ...stemSpec, duration: 4 });
+ const enc = runs.find((a) => a.includes("-filter_complex"))!;
+ const graph = arg(enc, "-filter_complex").split(";");
+ for (let i = 0; i < 3; i++) {
+ expect(graph.some((l) => l.endsWith(`apad=whole_dur=4.000,atrim=0:4.000[stem${i}]`))).toBe(true);
+ expect(enc).toContain(`/tmp/graph-test/stem_${i}.wav`);
+ }
+ expect(enc.filter((a) => a === "pcm_s24le")).toHaveLength(3);
+ expect(packed).toEqual([
+ {
+ output: "/tmp/graph-test/out stems.zip",
+ files: [
+ { path: "/tmp/graph-test/stem_0.wav", name: "1 Dialogue.wav" },
+ { path: "/tmp/graph-test/stem_1.wav", name: "2 Voiceover.wav" },
+ { path: "/tmp/graph-test/stem_2.wav", name: "3 Music.wav" },
+ ],
+ },
+ ]);
+ });
+
+ test("an audio effect treats every stem as it treats the mix", async () => {
+ const graph = await graphFor({
+ ...stemSpec,
+ duration: 4,
+ effects: [{ effect: "echo", start: 0, end: 4 }],
+ });
+ expect(graph.some((l) => l.endsWith("[afx0]"))).toBe(true);
+ for (let i = 0; i < 3; i++) expect(graph.some((l) => l.endsWith(`[afxs${i}_0]`))).toBe(true);
+ });
+
+ test("a range cuts every stem to the delivered window", async () => {
+ const graph = await graphFor({ ...stemSpec, duration: 4, range: { start: 1, end: 3 } });
+ expect(graph.find((l) => l.endsWith("[stem2]"))).toContain("atrim=start=1.000:end=3.000");
+ });
+
+ test("a spec that asks for stems renders even when its source could copy", async () => {
+ const runs = await runsFor({ ...stemSpec, sourceSegments: [{ file: "a.mp4", from: 0, to: 4 }], target: "export" });
+ expect(runs.some((a) => a.includes("-filter_complex"))).toBe(true);
+ });
+});
diff --git a/site/src/cut/server/exportPipeline.ts b/site/src/cut/server/exportPipeline.ts
index 0c49db29..9e2eb602 100644
--- a/site/src/cut/server/exportPipeline.ts
+++ b/site/src/cut/server/exportPipeline.ts
@@ -35,6 +35,18 @@ function crossExpr(cut: number, half: number, rising: boolean): string {
return `${rising ? "sin" : "cos"}(${p}*PI/2)`;
}
+/** A split edit's ramp as a `volume` factor over its stream: the stretch
+ * `[from, from + len]` past the picture, opening from silence over `fade`
+ * at its start (a lead) or closing to silence over `fade` at its end (a
+ * tail); 1 everywhere else. */
+function splitExpr(from: number, len: number, fade: number, opening: boolean): string {
+ const f = Math.min(fade, len);
+ if (!(f > 0.0005)) return "";
+ return opening
+ ? `clip((t-(${num(from)}))/${num(f)},0,1)`
+ : `clip(((${num(from + len)})-t)/${num(f)},0,1)`;
+}
+
/** The expressions folded into one `volume` filter, quoted so the graph
* parser carries their commas whole.
*
@@ -662,7 +674,11 @@ export function narrowSpecToRange(spec: ExportSpec): ExportSpec {
...spec,
clips,
...(spec.overlayVideos
- ? { overlayVideos: spec.overlayVideos.filter((o) => inside(o.start, o.start + spanLen(o))) }
+ ? {
+ overlayVideos: spec.overlayVideos.filter((o) =>
+ inside(o.start - (o.soundBack ?? 0), o.start + spanLen(o) + (o.soundAhead ?? 0))
+ ),
+ }
: {}),
audio: spec.audio.filter((a) => inside(a.start, a.start + spanLen(a))),
overlays: spec.overlays.filter((o) => inside(o.start, o.end)),
@@ -1027,7 +1043,7 @@ export async function runExport(
...overlayVideos.filter((o) => !o.image),
]
.map((c) => c.file)
- .filter((f) => f && !turned.has(f))
+ .filter((f) => f && !turned.has(f) && !twinFiles.has(f))
),
];
const audioPresence = new Map<string, boolean>();
@@ -2142,8 +2158,8 @@ export async function runExport(
crossExpr(dur, crossHalf[j + 1] ?? 0, false),
]);
filters.push(
- audioRead(c, 0, dur) +
- `${toStereo(c.file)}${vol}` +
+ audioRead(snd, 0, dur) +
+ `${toStereo(snd.file)}${vol}` +
`apad=whole_dur=${num(dur)},atrim=0:${num(dur)}${afades}[a${j}]`
);
} else {
@@ -2241,11 +2257,12 @@ export async function runExport(
expr: string
) => {
if (toT - fromT <= 0.01 || src.muted || src.hidden || src.image) return;
- if (!audioPresence.get(src.file)) return;
+ const snd = sounding(src);
+ if (!snd || !audioPresence.get(snd.file)) return;
const lab = `xh${key}`;
filters.push(
- audioRead(src, fromT, toT) +
- toStereo(src.file) +
+ audioRead(snd, fromT, toT) +
+ toStereo(snd.file) +
`${soundChain(src.sound)}` +
`${(src.volume ?? 1) !== 1 ? `volume=${num(src.volume ?? 1)},` : ""}anull${crossFilters([expr])},` +
`adelay=${Math.max(0, Math.round(at * 1000))}:all=1[${lab}]`
@@ -2511,13 +2528,17 @@ export async function runExport(
} else {
filters.push(`[${onto}][${seg}]overlay=${pos}:${enable}:eof_action=pass${ovl}[${next}]`);
}
- if (!oc.muted && audioPresence.get(oc.file)) {
+ const osnd = sounding(oc);
+ if (!oc.muted && osnd && audioPresence.get(osnd.file)) {
const vol = (oc.volume ?? 1) !== 1 ? `volume=${num(oc.volume ?? 1)},` : "";
- // A cross dissolve reaches into the handle either side of its cut, so
- // this stream starts before the clip's own head and runs past its tail;
- // everything timed inside it shifts by that head reach.
- const back = Math.min(oc.soundBack ?? 0, hs, headRoom(oc));
- const ahead = Math.min(oc.soundAhead ?? 0, ts);
+ // A cross dissolve or a split edit reaches into the handle either side
+ // of the clip, so this stream starts before its own head and runs past
+ // its tail; everything timed inside it shifts by that head reach.
+ const lead = Math.min(oc.soundLead ?? 0, oc.start);
+ const back = Math.min(oc.soundBack ?? 0, Math.max(hs, lead), headRoom(osnd));
+ const ahead = Math.min(oc.soundAhead ?? 0, Math.max(ts, oc.soundTail ?? 0));
+ const splitIn = Math.min(lead, back);
+ const splitOut = Math.min(oc.soundTail ?? 0, ahead);
// The picture's fade edges carry the sound with them; zoom edges don't.
// A cross dissolve's ramps are equal-power and reach half level on the
// cut, so they are a volume expression rather than a fade to silence.
@@ -2529,12 +2550,14 @@ export async function runExport(
const crosses = crossFilters([
crossExpr(back, hs, true),
crossExpr(back + olen, ts, false),
+ splitIn > 0.01 ? splitExpr(back - splitIn, splitIn, oc.splitFade ?? 0, true) : "",
+ splitOut > 0.01 ? splitExpr(back + olen, splitOut, oc.splitFade ?? 0, false) : "",
]);
const delayMs = Math.max(0, Math.round((oc.start - back) * 1000));
const lab = `ovs${k}`;
filters.push(
- audioRead(oc, -back, olen + ahead) +
- toStereo(oc.file) +
+ audioRead(osnd, -back, olen + ahead) +
+ toStereo(osnd.file) +
`${soundChain(oc.sound)}${vol}${afades}anull` +
`${crosses},adelay=${delayMs}:all=1[${lab}]`
);
@@ -2734,49 +2757,56 @@ export async function runExport(
// back between the untreated pieces. The treated piece is padded and
// trimmed back to the length it went in at, so a chain that rings past its
// input cannot push the rest of the sound late.
- (spec.effects ?? [])
- .filter((e) => isAudioEffect(e.effect))
- .sort((a, b) => a.start - b.start)
- .forEach((e, k) => {
- const chain = audioFxFilters(e.effect, e.amount);
- const from = Math.max(0, e.start);
- const to = Math.min(e.end, spec.duration);
- if (!chain || !(to > from)) return;
- const len = to - from;
- const fit = `${chain},apad=whole_dur=${num(len)},atrim=0:${num(len)},asetpts=PTS-STARTPTS`;
- const head = from > 0.001;
- const tail = to < spec.duration - 0.001;
- // An effect covering the whole mix is the chain itself; nothing to splice.
- if (!head && !tail) {
- filters.push(`[${aLabel}]${fit}[afx${k}]`);
- aLabel = `afx${k}`;
- return;
- }
- const branches = 1 + (head ? 1 : 0) + (tail ? 1 : 0);
- filters.push(
- `[${aLabel}]asplit=${branches}` +
- (head ? `[afxsh${k}]` : "") +
- `[afxsw${k}]` +
- (tail ? `[afxst${k}]` : "")
- );
- const parts: string[] = [];
- if (head) {
- filters.push(`[afxsh${k}]atrim=0:${num(from)},asetpts=PTS-STARTPTS[afxh${k}]`);
- parts.push(`afxh${k}`);
- }
- filters.push(
- `[afxsw${k}]atrim=${num(from)}:${num(to)},asetpts=PTS-STARTPTS,${fit}[afxw${k}]`
- );
- parts.push(`afxw${k}`);
- if (tail) {
- filters.push(`[afxst${k}]atrim=start=${num(to)},asetpts=PTS-STARTPTS[afxt${k}]`);
- parts.push(`afxt${k}`);
- }
- filters.push(
- `${parts.map((l) => `[${l}]`).join("")}concat=n=${parts.length}:v=0:a=1[afx${k}]`
- );
- aLabel = `afx${k}`;
- });
+ // The same treatment runs on every stem, each labelled by its own `tag`.
+ const treatAudio = (input: string, tag: string): string => {
+ let label = input;
+ (spec.effects ?? [])
+ .filter((e) => isAudioEffect(e.effect))
+ .sort((a, b) => a.start - b.start)
+ .forEach((e, n) => {
+ const k = `${tag}${n}`;
+ const chain = audioFxFilters(e.effect, e.amount);
+ const from = Math.max(0, e.start);
+ const to = Math.min(e.end, spec.duration);
+ if (!chain || !(to > from)) return;
+ const len = to - from;
+ const fit = `${chain},apad=whole_dur=${num(len)},atrim=0:${num(len)},asetpts=PTS-STARTPTS`;
+ const head = from > 0.001;
+ const tail = to < spec.duration - 0.001;
+ // An effect covering the whole mix is the chain itself; nothing to splice.
+ if (!head && !tail) {
+ filters.push(`[${label}]${fit}[afx${k}]`);
+ label = `afx${k}`;
+ return;
+ }
+ const branches = 1 + (head ? 1 : 0) + (tail ? 1 : 0);
+ filters.push(
+ `[${label}]asplit=${branches}` +
+ (head ? `[afxsh${k}]` : "") +
+ `[afxsw${k}]` +
+ (tail ? `[afxst${k}]` : "")
+ );
+ const parts: string[] = [];
+ if (head) {
+ filters.push(`[afxsh${k}]atrim=0:${num(from)},asetpts=PTS-STARTPTS[afxh${k}]`);
+ parts.push(`afxh${k}`);
+ }
+ filters.push(
+ `[afxsw${k}]atrim=${num(from)}:${num(to)},asetpts=PTS-STARTPTS,${fit}[afxw${k}]`
+ );
+ parts.push(`afxw${k}`);
+ if (tail) {
+ filters.push(`[afxst${k}]atrim=start=${num(to)},asetpts=PTS-STARTPTS[afxt${k}]`);
+ parts.push(`afxt${k}`);
+ }
+ filters.push(
+ `${parts.map((l) => `[${l}]`).join("")}concat=n=${parts.length}:v=0:a=1[afx${k}]`
+ );
+ label = `afx${k}`;
+ });
+ return label;
+ };
+ aLabel = treatAudio(aLabel, "");
// A PQ delivery: the finished HLG composite through the BT.2100 OOTF at
// 1000 nits and the ST 2084 curve, one fixed lattice, then back to video.
diff --git a/site/src/lib/config/registry.ts b/site/src/lib/config/registry.ts
index ff3768e5..906cc055 100644
--- a/site/src/lib/config/registry.ts
+++ b/site/src/lib/config/registry.ts
@@ -338,6 +338,67 @@ export const SETTINGS = defineSettings({
description:
"The color LUT sizes a clip is rendered through (standard, wide-gamut and the draft drawn mid-drag), the preview proxy's size and quality, and the largest LUT file the library takes.",
},
+ cutSound: {
+ schema: z
+ .object({
+ // The ramp at the outer end of a split edit's sound, so the sound
+ // that leads or trails the picture never starts or stops on a click.
+ splitFadeSeconds: z.number().min(0).max(1),
+ // How much clearer the best alignment of a separate recording has to
+ // be than the runner-up before it is bound.
+ syncMinConfidence: z.number().min(1).max(10),
+ // How much of the camera's own sound the alignment listens to.
+ syncProbeSeconds: z.number().min(5).max(600),
+ // The longest recording searched end to end.
+ syncMaxSeconds: z.number().min(60).max(4 * 3600),
+ })
+ .strict(),
+ default: {
+ splitFadeSeconds: 0.03,
+ syncMinConfidence: 1.4,
+ syncProbeSeconds: 90,
+ syncMaxSeconds: 2 * 3600,
+ },
+ public: true,
+ title: "Sound editing",
+ description:
+ "The ramp on the sound a split edit carries past its picture, and how lining up a separately recorded sound listens, how sure it must be, and how long a recording it searches.",
+ },
+ cutMotion: {
+ schema: z.object({ motionBlur: z.number().min(0.05).max(1) }).strict(),
+ default: { motionBlur: 0.5 },
+ public: true,
+ title: "Motion blur",
+ description:
+ "The shutter a newly switched-on motion blur starts at, as a share of a 30fps frame. 0.5 is the half-open shutter of most filmed footage; higher streaks harder.",
+ },
+ cutLoudness: {
+ schema: z
+ .object({
+ // The integrated loudness each named target masters to, LUFS.
+ targets: z
+ .object({
+ social: z.number().min(-36).max(-5),
+ podcast: z.number().min(-36).max(-5),
+ broadcast: z.number().min(-36).max(-5),
+ })
+ .strict(),
+ // The target an export starts on; "off" leaves the mix as mixed.
+ defaultTarget: z.enum(["off", "social", "podcast", "broadcast"]),
+ // What a mastered mix's true peak is held under, dBTP.
+ truePeakCeiling: z.number().min(-9).max(0),
+ })
+ .strict(),
+ default: {
+ targets: { social: -14, podcast: -16, broadcast: -23 },
+ defaultTarget: "off",
+ truePeakCeiling: -1,
+ },
+ public: true,
+ title: "Export loudness",
+ description:
+ "The loudness each export target masters to (social, podcast, broadcast), the target an export starts on, and the true-peak ceiling a mastered mix is limited under.",
+ },
experimentResults: {
schema: z
.object({