Skip to content

Open source CapCut alternative.

TypeScript

feat(site): open the shutter past one frame [rebuild]

David Leaa268893dff7
diff --git a/site/packages/effects-kit/src/camera.test.ts b/site/packages/effects-kit/src/camera.test.ts
index 093a8725..857b4ab9 100644
--- a/site/packages/effects-kit/src/camera.test.ts
+++ b/site/packages/effects-kit/src/camera.test.ts
@@ -5,6 +5,7 @@ import {
composeCamera,
REST_CAMERA,
shiftCamera,
+ SHUTTER_MAX,
STREAK_MAX,
STREAK_MIN,
STREAK_TAPS_MAX,
@@ -221,6 +222,23 @@ describe("motion blur", () => {
expect(capStreak(10, 0)).toEqual({ x: 10, y: 0 });
});
+ test("a long exposure lengthens the cap with its shutter", () => {
+ // Up to one frame the cap holds; three frames of shutter allow three times
+ // the smear, so a whip settling in a few frames still streaks hard.
+ expect(Math.hypot(...Object.values(capStreak(1000, 0, 1)!))).toBeCloseTo(STREAK_MAX);
+ expect(capStreak(1000, 0, 3)!.x).toBeCloseTo(3 * STREAK_MAX);
+ expect(capStreak(1000, 0, SHUTTER_MAX)!.x).toBeCloseTo(SHUTTER_MAX * STREAK_MAX);
+ });
+
+ test("an element's long shutter streaks past one frame of travel", () => {
+ // A 7-frame whip settle: at three frames of shutter the first frame
+ // smears three times what a one-frame shutter shows.
+ const o = el({ kf: [key(0, { y: 0.6, ease: "power3.out" }), key(7 / 30, { y: 0.5 })] });
+ const one = evalOverlayFrame({ ...o, motionBlur: 1 }, 0.05, 16 / 9).streak!;
+ const three = evalOverlayFrame({ ...o, motionBlur: 3 }, 0.05, 16 / 9).streak!;
+ expect(Math.abs(three.y)).toBeGreaterThan(2.5 * Math.abs(one.y));
+ });
+
test("taps follow the streak length within their bounds", () => {
expect(streakTaps(0)).toBe(0);
expect(streakTaps(STREAK_MIN)).toBe(2);
diff --git a/site/packages/effects-kit/src/camera.ts b/site/packages/effects-kit/src/camera.ts
index b1c829f3..80c80695 100644
--- a/site/packages/effects-kit/src/camera.ts
+++ b/site/packages/effects-kit/src/camera.ts
@@ -34,7 +34,8 @@ export interface CameraKey {
}
/** 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). */
+ * camera's movement does to the picture (shutter, SHUTTER_MIN..SHUTTER_MAX;
+ * absent = off). */
export interface GroupCamera {
kf: CameraKey[];
motionBlur?: number;
@@ -143,26 +144,39 @@ export function shiftCamera(cam: GroupCamera, by: number): GroupCamera {
// 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.
+// nowhere and stays sharp. A shutter past one frame is a stylized long
+// exposure: the smear a whip cut wears while the shot settles.
/** The frame the shutter amount is a share of, seconds. */
export const MOTION_BLUR_FRAME = 1 / 30;
+/** The shutter's range, in frames: a sliver of one up to a long exposure. */
+export const SHUTTER_MIN = 0.05;
+export const SHUTTER_MAX = 4;
/** 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. */
+/** The longest streak a one-frame shutter draws, design px. A whip faster
+ * than this reads as a blur either way, and the cap bounds what a frame
+ * costs to draw. A longer shutter lengthens the cap in step (`streakCap`). */
export const STREAK_MAX = 96;
/** Design px between two taps along a streak. */
const STREAK_TAP_SPACING = 4;
/** The most copies one streak is drawn from. */
export const STREAK_TAPS_MAX = 24;
+/** The longest streak `shutter` draws, design px: one frame's cap, or that
+ * cap times the frames a long exposure stays open. */
+export function streakCap(shutter = 1): number {
+ return STREAK_MAX * Math.max(1, shutter);
+}
+
/** 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 {
+ * displacement itself, capped in length for the shutter, or null when it is
+ * too short to see. */
+export function capStreak(dx: number, dy: number, shutter = 1): { 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;
+ const cap = streakCap(shutter);
+ const k = len > cap ? cap / len : 1;
return { x: dx * k, y: dy * k };
}
diff --git a/site/packages/effects-kit/src/keys.ts b/site/packages/effects-kit/src/keys.ts
index a28ae5e5..cf1b1d51 100644
--- a/site/packages/effects-kit/src/keys.ts
+++ b/site/packages/effects-kit/src/keys.ts
@@ -380,7 +380,8 @@ export function evalOverlayFrame(o: Posable, tLocal: number, aspect?: number): O
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
+ ((b.y - a.y) * f.height + (b.dy - a.dy)) * k,
+ shutter
);
return streak ? { ...placed, streak } : placed;
}
diff --git a/site/packages/effects-kit/src/render.ts b/site/packages/effects-kit/src/render.ts
index ba2f05f4..913dec8d 100644
--- a/site/packages/effects-kit/src/render.ts
+++ b/site/packages/effects-kit/src/render.ts
@@ -32,7 +32,7 @@ import { cutAtFaces, cycleFaceTag, fontCycleCuts, fontCycleVariants, withFontCyc
import { evalWhole, presetExtent } from "./motion/evaluate";
import { countStep, countText } from "./count";
import { evalOverlayFrame, hasOverlayKeys, poseAt, poseExtent, sortedKeys, type OverlayFrameState } from "./keys";
-import { ELEMENT_BLUR_MAX, hasCameraKeys, STREAK_MAX } from "./camera";
+import { ELEMENT_BLUR_MAX, hasCameraKeys, streakCap } from "./camera";
import { ElementFx, elementLook } from "./elementFx";
import { applyMaskToCanvas, isMaskAnimated } from "./mask";
import { tracePolyShape } from "./shapePath";
@@ -1903,7 +1903,7 @@ export async function renderOverlayFrames(
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);
+ (overlay.motionBlur ? (streakCap(overlay.motionBlur) / 2) * scale : 0);
halfW += spill;
halfH += spill;
const x0 = whole ? 0 : Math.max(0, Math.floor(extent.x0 * width - halfW));
diff --git a/site/src/cut/components/GroupPanel.tools.ts b/site/src/cut/components/GroupPanel.tools.ts
index 09aa915c..4de42960 100644
--- a/site/src/cut/components/GroupPanel.tools.ts
+++ b/site/src/cut/components/GroupPanel.tools.ts
@@ -5,7 +5,7 @@
* `GroupPanelToolName`.
*/
-import { CAMERA_SCALE_MAX, CAMERA_SCALE_MIN, CAMERA_WORLD_MAX, CAMERA_WORLD_MIN, EASE_IDS } from "@donkeycut/effects-kit";
+import { CAMERA_SCALE_MAX, CAMERA_SCALE_MIN, CAMERA_WORLD_MAX, CAMERA_WORLD_MIN, EASE_IDS, SHUTTER_MAX, SHUTTER_MIN } from "@donkeycut/effects-kit";
import { bool, num, obj, str, type AiToolDef } from "@/cut/lib/aiToolDef";
export const GROUP_PANEL_TOOLS = [
@@ -32,7 +32,7 @@ export const GROUP_PANEL_TOOLS = [
),
},
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"),
+ shutter: num(`Motion blur shutter in 30fps frames, ${SHUTTER_MIN}..${SHUTTER_MAX}: 0.5 is the usual half-open shutter, and past 1 is a stylized long exposure (2–3 smears a whip that settles in a few frames); setting it switches motion blur on`),
},
[]
),
diff --git a/site/src/cut/components/Inspector.tools.ts b/site/src/cut/components/Inspector.tools.ts
index 4ec7bad0..8825708f 100644
--- a/site/src/cut/components/Inspector.tools.ts
+++ b/site/src/cut/components/Inspector.tools.ts
@@ -46,6 +46,8 @@ import {
PATTERN_KINDS,
SHADOW_BLUR_MAX,
SHADOW_OFFSET_MAX,
+ SHUTTER_MAX,
+ SHUTTER_MIN,
STRIPE_GAP_MAX,
STRIPE_LINE_MAX,
STRIPE_LINE_MIN,
@@ -171,7 +173,7 @@ export const INSPECTOR_TOOLS = [
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"),
+ shutter: num(`Motion blur shutter in 30fps frames, ${SHUTTER_MIN}..${SHUTTER_MAX}: 0.5 is the usual half-open shutter, and past 1 is a stylized long exposure (2–3 smears a whip that settles in a few frames); 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."),
}, []),
@@ -260,7 +262,7 @@ export const INSPECTOR_TOOLS = [
),
},
motion_blur: bool("Streak the clip along its keyed movement while it moves (true starts at the default shutter); false switches it off; omitted keeps it"),
- 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"),
+ shutter: num(`Motion blur shutter in 30fps frames, ${SHUTTER_MIN}..${SHUTTER_MAX}: 0.5 is the usual half-open shutter, and past 1 is a stylized long exposure (2–3 smears a whip that settles in a few frames); setting it switches motion blur on`),
},
["clipId"]
),
diff --git a/site/src/cut/components/MotionControls.tsx b/site/src/cut/components/MotionControls.tsx
index c2b781e4..55824acd 100644
--- a/site/src/cut/components/MotionControls.tsx
+++ b/site/src/cut/components/MotionControls.tsx
@@ -13,6 +13,8 @@ import {
keyIndexAt,
poseAt,
removeKeyAt,
+ SHUTTER_MAX,
+ SHUTTER_MIN,
upsertKey,
type CameraKey,
type EaseId,
@@ -90,8 +92,8 @@ function MotionBlurRows({
{...SLIDER}
value={shutter.value}
mixed={shutter.mixed}
- min={0.05}
- max={1}
+ min={SHUTTER_MIN}
+ max={SHUTTER_MAX}
step={0.01}
snap={[0.5]}
format={(v) => `${Math.round(v * 100)}%`}
diff --git a/site/src/cut/lib/aiTools.ts b/site/src/cut/lib/aiTools.ts
index c07f5ec3..cda7fd6a 100644
--- a/site/src/cut/lib/aiTools.ts
+++ b/site/src/cut/lib/aiTools.ts
@@ -127,7 +127,7 @@ 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, CAMERA_WORLD_MAX, CAMERA_WORLD_MIN, ELEMENT_BLUR_MAX, TILT_MAX, isEaseId, upsertKey as upsertCameraKey, type CameraKey } from "@donkeycut/effects-kit";
+import { CAMERA_SCALE_MAX, CAMERA_SCALE_MIN, CAMERA_WORLD_MAX, CAMERA_WORLD_MIN, ELEMENT_BLUR_MAX, SHUTTER_MAX, SHUTTER_MIN, TILT_MAX, isEaseId, upsertKey as upsertCameraKey, type CameraKey } from "@donkeycut/effects-kit";
import { cleanInks, LETTER_SPACING_MAX, LETTER_SPACING_MIN, PATTERN_KINDS, SHADOW_BLUR_MAX, SHADOW_OFFSET_MAX, STRIPE_GAP_MAX, STRIPE_LINE_MAX, STRIPE_LINE_MIN, STRIPES_DEFAULT, type PatternSpec, type ShadowSpec } from "@donkeycut/effects-kit";
import { groupCameraOf, groupCameraPoseAt } from "@/cut/lib/groupCamera";
import { cutMotion } from "@/cut/lib/motionSettings";
@@ -6756,7 +6756,7 @@ async function launchVideoJob(
* `motion_blur` true for the current one or the default, false for off;
* neither keeps `current`. */
function shutterInput(input: Record<string, unknown>, current: number | undefined): number | undefined {
- if (isNum(input.shutter)) return input.shutter > 0 ? clamp(input.shutter, 0.05, 1) : undefined;
+ if (isNum(input.shutter)) return input.shutter > 0 ? clamp(input.shutter, SHUTTER_MIN, SHUTTER_MAX) : undefined;
if (input.motion_blur === true) return current ?? cutMotion().motionBlur;
if (input.motion_blur === false) return undefined;
return current;