Skip to content

Production-ready animations, transitions, backgrounds, and scenes for Remotion

feat: added stop-motion lib

kapishdima0d73963c8510
diff --git a/registry-artifacts/registry.json b/registry-artifacts/registry.json
index 2b6e745c..5742d111 100644
--- a/registry-artifacts/registry.json
+++ b/registry-artifacts/registry.json
@@ -1283,6 +1283,20 @@
],
"type": "registry:component"
},
+ {
+ "name": "stop-motion",
+ "title": "Stop Motion Clock",
+ "description": "Quantized stop-motion clock for Remotion. Stepped frames, stepped springs, deterministic hashing, and per-pose paper jitter.",
+ "dependencies": ["remotion"],
+ "files": [
+ {
+ "path": "registry/remocn/stop-motion/index.ts",
+ "type": "registry:lib",
+ "target": "lib/remocn/stop-motion.ts"
+ }
+ ],
+ "type": "registry:lib"
+ },
{
"name": "remocn-ui",
"title": "remocn UI Core",
diff --git a/registry-artifacts/stop-motion.json b/registry-artifacts/stop-motion.json
new file mode 100644
index 00000000..d0cff4c2
--- /dev/null
+++ b/registry-artifacts/stop-motion.json
@@ -0,0 +1,16 @@
+{
+ "$schema": "https://ui.shadcn.com/schema/registry-item.json",
+ "name": "stop-motion",
+ "title": "Stop Motion Clock",
+ "description": "Quantized stop-motion clock for Remotion. Stepped frames, stepped springs, deterministic hashing, and per-pose paper jitter.",
+ "dependencies": ["remotion"],
+ "files": [
+ {
+ "path": "registry/remocn/stop-motion/index.ts",
+ "content": "import { spring } from \"remotion\";\n\nexport const DEFAULT_STEP = 3;\n\nexport const qf = (frame: number, step = DEFAULT_STEP): number =>\n Math.floor(frame / step) * step;\n\nexport const qstep = (frame: number, step = DEFAULT_STEP): number =>\n Math.floor(frame / step);\n\nexport const hash01 = (seed: string): number => {\n let h = 2166136261;\n for (let i = 0; i < seed.length; i++) {\n h ^= seed.charCodeAt(i);\n h = Math.imul(h, 16777619);\n }\n h = Math.imul(h ^ (h >>> 13), 2246822519);\n return ((h ^ (h >>> 16)) >>> 0) / 4294967296;\n};\n\nexport const hashRange = (seed: string, lo: number, hi: number): number =>\n lo + hash01(seed) * (hi - lo);\n\nexport type Jitter = { x: number; y: number; rot: number };\n\nexport const paperJitter = (\n frame: number,\n seed: string,\n options?: { amp?: number; rotAmp?: number; step?: number },\n): Jitter => {\n const amp = options?.amp ?? 1.4;\n const rotAmp = options?.rotAmp ?? 0.35;\n const s = qstep(frame, options?.step ?? DEFAULT_STEP);\n return {\n x: hashRange(`${seed}:x:${s}`, -amp, amp),\n y: hashRange(`${seed}:y:${s}`, -amp, amp),\n rot: hashRange(`${seed}:r:${s}`, -rotAmp, rotAmp),\n };\n};\n\nexport const steppedSpring = (args: {\n frame: number;\n fps: number;\n delay?: number;\n step?: number;\n config?: { damping?: number; stiffness?: number; mass?: number };\n}): number =>\n spring({\n frame: qf(\n Math.max(0, args.frame - (args.delay ?? 0)),\n args.step ?? DEFAULT_STEP,\n ),\n fps: args.fps,\n config: args.config,\n });\n\nexport const steppedRamp = (\n frame: number,\n from: number,\n to: number,\n options?: { ease?: (t: number) => number; step?: number },\n): number => {\n const f = qf(frame, options?.step ?? DEFAULT_STEP);\n if (f <= from) return 0;\n if (f >= to) return 1;\n const ease = options?.ease ?? ((t: number) => t);\n return ease((f - from) / (to - from));\n};\n",
+ "type": "registry:lib",
+ "target": "lib/remocn/stop-motion.ts"
+ }
+ ],
+ "type": "registry:lib"
+}
diff --git a/registry/remocn/registry.json b/registry/remocn/registry.json
index e6fabb60..817dec6a 100644
--- a/registry/remocn/registry.json
+++ b/registry/remocn/registry.json
@@ -1282,6 +1282,20 @@
"target": "components/remocn/logo-enter.tsx"
}
]
+ },
+ {
+ "name": "stop-motion",
+ "type": "registry:lib",
+ "title": "Stop Motion Clock",
+ "description": "Quantized stop-motion clock for Remotion. Stepped frames, stepped springs, deterministic hashing, and per-pose paper jitter.",
+ "dependencies": ["remotion"],
+ "files": [
+ {
+ "path": "stop-motion/index.ts",
+ "type": "registry:lib",
+ "target": "lib/remocn/stop-motion.ts"
+ }
+ ]
}
]
}
diff --git a/registry/remocn/stop-motion/__tests__/stop-motion.test.ts b/registry/remocn/stop-motion/__tests__/stop-motion.test.ts
new file mode 100644
index 00000000..ded6cfd7
--- /dev/null
+++ b/registry/remocn/stop-motion/__tests__/stop-motion.test.ts
@@ -0,0 +1,187 @@
+import { describe, expect, it } from "bun:test";
+import { spring } from "remotion";
+
+import {
+ DEFAULT_STEP,
+ hash01,
+ hashRange,
+ paperJitter,
+ qf,
+ qstep,
+ steppedRamp,
+ steppedSpring,
+} from "../index";
+
+const FPS = 30;
+
+describe("qf / qstep", () => {
+ it("holds the first step at frame 0", () => {
+ expect(qf(0)).toBe(0);
+ expect(qf(1)).toBe(0);
+ expect(qf(2)).toBe(0);
+ expect(qstep(0)).toBe(0);
+ expect(qstep(1)).toBe(0);
+ expect(qstep(2)).toBe(0);
+ });
+
+ it("ticks at the step boundary", () => {
+ expect(qf(3)).toBe(3);
+ expect(qstep(3)).toBe(1);
+ expect(qf(5)).toBe(3);
+ expect(qf(6)).toBe(6);
+ expect(qstep(6)).toBe(2);
+ });
+
+ it("defaults to a 3-frame step", () => {
+ expect(DEFAULT_STEP).toBe(3);
+ expect(qf(7)).toBe(qf(7, 3));
+ expect(qstep(7)).toBe(qstep(7, 3));
+ });
+
+ it("honors a custom step", () => {
+ expect(qf(7, 5)).toBe(5);
+ expect(qf(4, 5)).toBe(0);
+ expect(qstep(11, 5)).toBe(2);
+ expect(qf(9, 1)).toBe(9);
+ });
+});
+
+describe("hash01", () => {
+ it("is deterministic per seed", () => {
+ expect(hash01("paper")).toBe(hash01("paper"));
+ });
+
+ it("stays inside [0, 1)", () => {
+ for (let i = 0; i < 500; i++) {
+ const v = hash01(`seed:${i}`);
+ expect(v).toBeGreaterThanOrEqual(0);
+ expect(v).toBeLessThan(1);
+ }
+ });
+
+ it("differs across seeds", () => {
+ expect(hash01("a")).not.toBe(hash01("b"));
+ expect(hash01("card:x:0")).not.toBe(hash01("card:x:1"));
+ });
+});
+
+describe("hashRange", () => {
+ it("stays inside [lo, hi]", () => {
+ for (let i = 0; i < 500; i++) {
+ const v = hashRange(`range:${i}`, -1.4, 1.4);
+ expect(v).toBeGreaterThanOrEqual(-1.4);
+ expect(v).toBeLessThanOrEqual(1.4);
+ }
+ });
+
+ it("is deterministic", () => {
+ expect(hashRange("photo", 0, 10)).toBe(hashRange("photo", 0, 10));
+ });
+});
+
+describe("paperJitter", () => {
+ it("returns the same pose for every frame inside one step", () => {
+ const a = paperJitter(3, "photo");
+ const b = paperJitter(4, "photo");
+ const c = paperJitter(5, "photo");
+ expect(a).toEqual(b);
+ expect(a).toEqual(c);
+ });
+
+ it("changes when the step ticks", () => {
+ expect(paperJitter(2, "photo")).not.toEqual(paperJitter(3, "photo"));
+ });
+
+ it("respects amp and rotAmp bounds", () => {
+ for (let f = 0; f <= 120; f++) {
+ const j = paperJitter(f, "photo", { amp: 2, rotAmp: 0.5 });
+ expect(Math.abs(j.x)).toBeLessThanOrEqual(2);
+ expect(Math.abs(j.y)).toBeLessThanOrEqual(2);
+ expect(Math.abs(j.rot)).toBeLessThanOrEqual(0.5);
+ }
+ });
+
+ it("is deterministic per seed and differs across seeds", () => {
+ expect(paperJitter(9, "photo")).toEqual(paperJitter(9, "photo"));
+ expect(paperJitter(9, "photo")).not.toEqual(paperJitter(9, "note"));
+ });
+
+ it("honors a custom step", () => {
+ expect(paperJitter(3, "photo", { step: 6 })).toEqual(
+ paperJitter(5, "photo", { step: 6 }),
+ );
+ expect(paperJitter(5, "photo", { step: 6 })).not.toEqual(
+ paperJitter(6, "photo", { step: 6 }),
+ );
+ });
+});
+
+describe("steppedRamp", () => {
+ it("returns 0 at or before from", () => {
+ expect(steppedRamp(0, 6, 18)).toBe(0);
+ expect(steppedRamp(6, 6, 18)).toBe(0);
+ expect(steppedRamp(8, 6, 18)).toBe(0);
+ });
+
+ it("returns 1 at or after to", () => {
+ expect(steppedRamp(18, 6, 18)).toBe(1);
+ expect(steppedRamp(40, 6, 18)).toBe(1);
+ });
+
+ it("is constant within a step", () => {
+ expect(steppedRamp(9, 6, 18)).toBe(steppedRamp(11, 6, 18));
+ });
+
+ it("progresses linearly by default", () => {
+ expect(steppedRamp(12, 6, 18)).toBeCloseTo(0.5, 10);
+ });
+
+ it("applies the ease", () => {
+ const eased = steppedRamp(12, 6, 18, { ease: (t) => t * t });
+ expect(eased).toBeCloseTo(0.25, 10);
+ });
+
+ it("honors a custom step", () => {
+ expect(steppedRamp(11, 0, 12, { step: 6 })).toBe(
+ steppedRamp(7, 0, 12, { step: 6 }),
+ );
+ });
+});
+
+describe("steppedSpring", () => {
+ it("is constant within a step", () => {
+ expect(steppedSpring({ frame: 6, fps: FPS })).toBe(
+ steppedSpring({ frame: 8, fps: FPS }),
+ );
+ });
+
+ it("equals spring() sampled at the quantized frame", () => {
+ for (const frame of [0, 4, 7, 13, 25]) {
+ expect(steppedSpring({ frame, fps: FPS })).toBe(
+ spring({ frame: qf(frame), fps: FPS }),
+ );
+ }
+ });
+
+ it("shifts by delay and clamps below zero", () => {
+ expect(steppedSpring({ frame: 15, fps: FPS, delay: 9 })).toBe(
+ spring({ frame: qf(6), fps: FPS }),
+ );
+ expect(steppedSpring({ frame: 2, fps: FPS, delay: 9 })).toBe(
+ spring({ frame: 0, fps: FPS }),
+ );
+ });
+
+ it("honors a custom step", () => {
+ expect(steppedSpring({ frame: 11, fps: FPS, step: 6 })).toBe(
+ spring({ frame: 6, fps: FPS }),
+ );
+ });
+
+ it("threads the spring config", () => {
+ const config = { damping: 200, stiffness: 100, mass: 1 };
+ expect(steppedSpring({ frame: 9, fps: FPS, config })).toBe(
+ spring({ frame: 9, fps: FPS, config }),
+ );
+ });
+});
diff --git a/registry/remocn/stop-motion/index.ts b/registry/remocn/stop-motion/index.ts
new file mode 100644
index 00000000..84b727ed
--- /dev/null
+++ b/registry/remocn/stop-motion/index.ts
@@ -0,0 +1,68 @@
+import { spring } from "remotion";
+
+export const DEFAULT_STEP = 3;
+
+export const qf = (frame: number, step = DEFAULT_STEP): number =>
+ Math.floor(frame / step) * step;
+
+export const qstep = (frame: number, step = DEFAULT_STEP): number =>
+ Math.floor(frame / step);
+
+export const hash01 = (seed: string): number => {
+ let h = 2166136261;
+ for (let i = 0; i < seed.length; i++) {
+ h ^= seed.charCodeAt(i);
+ h = Math.imul(h, 16777619);
+ }
+ h = Math.imul(h ^ (h >>> 13), 2246822519);
+ return ((h ^ (h >>> 16)) >>> 0) / 4294967296;
+};
+
+export const hashRange = (seed: string, lo: number, hi: number): number =>
+ lo + hash01(seed) * (hi - lo);
+
+export type Jitter = { x: number; y: number; rot: number };
+
+export const paperJitter = (
+ frame: number,
+ seed: string,
+ options?: { amp?: number; rotAmp?: number; step?: number },
+): Jitter => {
+ const amp = options?.amp ?? 1.4;
+ const rotAmp = options?.rotAmp ?? 0.35;
+ const s = qstep(frame, options?.step ?? DEFAULT_STEP);
+ return {
+ x: hashRange(`${seed}:x:${s}`, -amp, amp),
+ y: hashRange(`${seed}:y:${s}`, -amp, amp),
+ rot: hashRange(`${seed}:r:${s}`, -rotAmp, rotAmp),
+ };
+};
+
+export const steppedSpring = (args: {
+ frame: number;
+ fps: number;
+ delay?: number;
+ step?: number;
+ config?: { damping?: number; stiffness?: number; mass?: number };
+}): number =>
+ spring({
+ frame: qf(
+ Math.max(0, args.frame - (args.delay ?? 0)),
+ args.step ?? DEFAULT_STEP,
+ ),
+ fps: args.fps,
+ config: args.config,
+ });
+
+export const steppedRamp = (
+ frame: number,
+ from: number,
+ to: number,
+ options?: { ease?: (t: number) => number; step?: number },
+): number => {
+ const f = qf(frame, options?.step ?? DEFAULT_STEP);
+ if (f <= from) return 0;
+ if (f >= to) return 1;
+ const ease = options?.ease ?? ((t: number) => t);
+ return ease((f - from) / (to - from));
+};
diff --git a/tsconfig.json b/tsconfig.json
index 06289dbe..00af7434 100644
--- a/tsconfig.json
+++ b/tsconfig.json
@@ -23,6 +23,7 @@
"@/lib/remocn-icons": ["./registry/remocn-icons/icons-core/index.ts"],
"@/lib/remocn-ui": ["./registry/remocn-ui/core/index.ts"],
"@/lib/remocn-ui/*": ["./registry/remocn-ui/core/*"],
+ "@/lib/remocn/stop-motion": ["./registry/remocn/stop-motion/index.ts"],
"@/components/remocn/use-cursor-path": [
"./registry/remocn-ui/cursor/use-cursor-path.ts"
],