Open source CapCut alternative.
TypeScript
/**
* The one motion evaluator.
*
* Everything that moves in the app — entrances, exits, loops, hold moves and
* the per-character sweeps — comes through here: sample a property's
* keyframes at a normalized time, after a range selector has decided what
* that time is for the unit being drawn. Nothing else computes motion.
*/
import {
REST_POSE,
type Easing,
type MotionPose,
type MotionPreset,
type MotionProperties,
type PropertyKey,
type RangeSelector,
type WigglySelector,
} from "./types";
const clamp01 = (v: number) => (v < 0 ? 0 : v > 1 ? 1 : v);
const lerp = (a: number, b: number, p: number) => a + (b - a) * p;
/** A cubic bezier timing function, solved by bisection on x. Curves run
* [0,0] to [1,1], the same handles Lottie writes and CSS reads. */
export function bezierEase(e: Easing, x: number): number {
const [x1, y1, x2, y2] = e;
const at = (a: number, b: number, t: number) =>
3 * (1 - t) * (1 - t) * t * a + 3 * (1 - t) * t * t * b + t * t * t;
let lo = 0;
let hi = 1;
for (let i = 0; i < 30; i++) {
const mid = (lo + hi) / 2;
if (at(x1, x2, mid) < x) lo = mid;
else hi = mid;
}
return at(y1, y2, (lo + hi) / 2);
}
/** One property's value at normalized time `q`: held before its first key and
* after its last, eased between. */
export function sampleTrack<V extends number | [number, number]>(
keys: PropertyKey<V>[] | undefined,
q: number,
rest: V
): V {
if (!keys || keys.length === 0) return rest;
const t = clamp01(q);
if (t <= keys[0].t) return keys[0].v;
const last = keys[keys.length - 1];
if (t >= last.t) return last.v;
let i = 0;
while (i + 1 < keys.length && keys[i + 1].t <= t) i++;
const a = keys[i];
const b = keys[i + 1];
if (a.hold) return a.v;
const span = b.t - a.t;
const raw = span > 0 ? (t - a.t) / span : 1;
const p = a.ease ? bezierEase(a.ease, clamp01(raw)) : clamp01(raw);
if (typeof a.v === "number") return lerp(a.v as number, b.v as number, p) as V;
const av = a.v as [number, number];
const bv = b.v as [number, number];
return [lerp(av[0], bv[0], p), lerp(av[1], bv[1], p)] as V;
}
/** A track with its `tMax` caps resolved against a known duration. Keys stay
* in order: a capped key drags the ones after it no earlier than itself. */
function capped<V extends number | [number, number]>(
keys: PropertyKey<V>[] | undefined,
dur: number
): PropertyKey<V>[] | undefined {
if (!keys || dur <= 0 || !keys.some((k) => k.tMax !== undefined)) return keys;
let floor = 0;
return keys.map((k) => {
const t = Math.max(floor, k.tMax === undefined ? k.t : Math.min(k.t, k.tMax / dur));
floor = t;
return { ...k, t };
});
}
/** Every property of a preset sampled at one moment. `dur` resolves any
* `tMax` caps; omit it and normalized time is used as written. */
export function sampleProperties(props: MotionProperties, q: number, dur = 0): MotionPose {
if (dur > 0)
props = {
position: capped(props.position, dur),
scale: capped(props.scale, dur),
rotation: capped(props.rotation, dur),
opacity: capped(props.opacity, dur),
tracking: capped(props.tracking, dur),
reveal: capped(props.reveal, dur),
erode: capped(props.erode, dur),
zap: capped(props.zap, dur),
typed: capped(props.typed, dur),
counted: capped(props.counted, dur),
roll: capped(props.roll, dur),
dive: capped(props.dive, dur),
brightness: capped(props.brightness, dur),
blur: capped(props.blur, dur),
split: capped(props.split, dur),
flicker: capped(props.flicker, dur),
};
return samplePropertiesRaw(props, q);
}
function samplePropertiesRaw(props: MotionProperties, q: number): MotionPose {
const pos = sampleTrack(props.position, q, [0, 0] as [number, number]);
const scale = sampleTrack(props.scale, q, [1, 1] as [number, number]);
return {
dx: pos[0],
dy: pos[1],
sx: scale[0],
sy: scale[1],
rotate: sampleTrack(props.rotation, q, 0),
alpha: sampleTrack(props.opacity, q, 1),
tracking: sampleTrack(props.tracking, q, 0),
...(props.reveal ? { reveal: sampleTrack(props.reveal, q, 1) } : {}),
...(props.erode ? { erode: sampleTrack(props.erode, q, 0) } : {}),
...(props.zap ? { zap: sampleTrack(props.zap, q, 0) } : {}),
...(props.typed ? { typed: sampleTrack(props.typed, q, 1) } : {}),
...(props.counted ? { counted: sampleTrack(props.counted, q, 1) } : {}),
...(props.roll ? { roll: sampleTrack(props.roll, q, 0) } : {}),
...(props.dive ? { dive: sampleTrack(props.dive, q, 0) } : {}),
...(props.brightness ? { brightness: sampleTrack(props.brightness, q, 1) } : {}),
...(props.blur ? { blur: sampleTrack(props.blur, q, 0) } : {}),
...(props.split ? { split: sampleTrack(props.split, q, 0) } : {}),
...(props.flicker ? { flicker: sampleTrack(props.flicker, q, 0) } : {}),
};
}
/** A deterministic 0..1 draw for unit `i` of a seeded selector. */
function draw(seed: number, i: number, salt = 0): number {
let h = (Math.imul(seed, 374761393) + Math.imul(i, 668265263) + Math.imul(salt, 2246822519)) >>> 0;
h = (h ^ (h >>> 13)) >>> 0;
h = Math.imul(h, 1274126177) >>> 0;
return ((h ^ (h >>> 16)) >>> 0) / 4294967296;
}
/** How many times a flickering unit may change state across its window. A
* 0.75s exit changes about every frame and a half, the pace of a failing
* tube. */
const FLICKER_STEPS = 16;
/** How bright a flickering unit shows when it dips without going out. */
const FLICKER_DIM = 0.35;
/** Seeds every flicker pattern, so the same line always blinks the same way. */
const FLICKER_SEED = 29;
/** The pose with its flicker spent on its opacity. Each unit draws its own
* pattern from its index, so the letters of a line blink independently: at
* flicker 0.5 a letter is dark for about half the steps, and at 1 for all of
* them. A dark step is out half the time and dim the rest. */
function flickered(pose: MotionPose, q: number, index: number): MotionPose {
const chance = pose.flicker ?? 0;
if (chance <= 0) return pose;
const step = Math.min(FLICKER_STEPS - 1, Math.floor(clamp01(q) * FLICKER_STEPS));
if (chance < 1 && draw(FLICKER_SEED, index, 100 + step) >= chance) return pose;
const level = draw(FLICKER_SEED, index, 500 + step) < 0.5 ? 0 : FLICKER_DIM;
return { ...pose, alpha: pose.alpha * level };
}
/** Where unit `i` sits in the hand-off order, 0 at the front. */
function orderOf(sel: RangeSelector, i: number, n: number): number {
if (n <= 1) return 0;
if (sel.sequence?.length) {
const at = sel.sequence.indexOf(i);
if (at >= 0) return at;
// The rest follow in reading order.
return sel.sequence.length + [...Array(i).keys()].filter((j) => !sel.sequence!.includes(j)).length;
}
if (sel.randomize) {
// Rank by the unit's own draw: a stable shuffle that needs no array.
const mine = draw(sel.seed ?? 1, i);
let rank = 0;
for (let j = 0; j < n; j++) if (j !== i && draw(sel.seed ?? 1, j) < mine) rank++;
return rank;
}
switch (sel.shape) {
case "rampDown":
return n - 1 - i;
case "triangle": {
// Both ends move first, meeting in the middle.
const mid = (n - 1) / 2;
return Math.round(mid - Math.abs(i - mid));
}
default:
return i;
}
}
/** The share of the window unit `i` starts at. `square` gives every unit its
* own slot with no overlap; the ramps and curves overlap by `spread`. */
function startShare(sel: RangeSelector, i: number, n: number, share = sel.spread, reverse = false): number {
if (n <= 1) return 0;
let o = orderOf(sel, i, n);
const spread = clamp01(share);
if (sel.sequence?.length) {
// A sequence hands the motion along the units it names, so the last of
// them lands as the ramp ends; any it leaves out (a space) go with the
// last. An exit sweeps them out in the order they came in, the way a
// reading-order exit does.
n = Math.max(2, sel.sequence.length);
o = Math.min(o, n - 1);
// Each unit's own turn, when the order carries them.
const at = sel.sequenceAt;
if (at && at.length === sel.sequence.length) return clamp01(reverse ? 1 - at[o] : at[o]) * spread;
if (reverse) o = n - 1 - o;
}
if (sel.shape === "square") return o / n;
const u = o / (n - 1);
switch (sel.shape) {
case "round":
// Slow at the ends, quick through the middle.
return (0.5 - Math.cos(u * Math.PI) / 2) * spread;
case "smooth":
return u * u * (3 - 2 * u) * spread;
default:
return u * spread;
}
}
/**
* Unit `i` of `n`'s own progress when its element's window stands at `p`.
* This is the whole of what a range selector does: turn one clock into a
* clock per character.
*/
export function selectorProgress(
sel: RangeSelector,
p: number,
index: number,
count: number,
exiting = false,
/** The hand-off share over the selector's own `spread`. */
spread = sel.spread
): number {
const n = Math.max(1, count);
// An exit sweeps out the way it came in, so the order reverses.
const listed = !!sel.sequence?.length;
const i = exiting && !listed ? n - 1 - index : index;
const from = startShare(sel, i, n, spread, exiting && listed);
const slots = listed ? Math.max(2, sel.sequence!.length) : n;
const window = sel.shape === "square" ? 1 / slots : Math.max(1e-6, 1 - clamp01(spread));
let q = clamp01((clamp01(p) - from) / window);
if (sel.easeHigh) q = lerp(q, bezierEase([0.42, 0, 1, 1], q), clamp01(sel.easeHigh));
if (sel.easeLow) q = lerp(q, bezierEase([0, 0, 0.58, 1], q), clamp01(sel.easeLow));
return q;
}
/**
* A looping selector hands each unit the same cycle at its own phase, so one
* turn sweeps the whole line exactly once and the motion stays exactly
* periodic — which is what lets a frame sequence render one cycle and repeat
* it for as long as the element runs.
*/
export function loopProgress(
sel: RangeSelector,
p: number,
index: number,
count: number
): number {
const n = Math.max(1, count);
// The order — shuffled when the selector randomizes — is the phase offset,
// so a run of one always sits at phase 0 and a whole element with no
// characters plays the cycle exactly as written.
const q = (p - (orderOf(sel, index, n) / n) * clamp01(sel.spread)) % 1;
return q < 0 ? q + 1 : q;
}
/** The wiggly selector's fixed draw for one unit, applied on top of the pose.
* `away` is how far from rest the unit still is, so the stray collapses to
* nothing as the motion settles. */
function applyWiggly(pose: MotionPose, w: WigglySelector, index: number, away: number): MotionPose {
const seed = w.seed ?? 7;
const signed = (salt: number) => draw(seed, index, salt) * 2 - 1;
const out = { ...pose };
if (w.position) {
out.dx += signed(1) * w.position[0] * away;
out.dy += signed(2) * w.position[1] * away;
}
if (w.rotation) out.rotate += signed(3) * w.rotation * away;
if (w.scale) {
out.sx *= 1 + signed(4) * (w.scale[0] - 1) * away;
out.sy *= 1 + signed(5) * (w.scale[1] - 1) * away;
}
return out;
}
/**
* A preset's pose for one unit at window position `p`.
*
* `index`/`count` place the unit in its run; an element moving as one piece is
* unit 0 of 1. `exiting` picks the exit track and reverses the sweep.
*/
export function evalPreset(
preset: MotionPreset,
p: number,
index = 0,
count = 1,
exiting = false,
dur = 0,
/** An edge's own hand-off over its selector's (`OverlayEdge.stagger`). */
spread?: number
): MotionPose {
const props = exiting && preset.animateOut ? preset.animateOut : preset.animate;
const q = !preset.selector
? clamp01(p)
: preset.period !== undefined
? loopProgress(preset.selector, p, index, count)
: selectorProgress(preset.selector, p, index, count, exiting, spread);
const pose = flickered(sampleProperties(props, q, dur), q, index);
return preset.wiggly ? applyWiggly(pose, preset.wiggly, index, 1 - q) : pose;
}
/**
* A preset's pose for the element as ONE piece, ignoring any selector: the
* whole box plays the motion once over the window. This is what a renderer
* with a single cached picture draws, and what every non-text kind gets from
* a per-character style.
*/
export function evalWhole(
preset: MotionPreset,
p: number,
exiting = false,
dur = 0
): MotionPose {
const props = exiting && preset.animateOut ? preset.animateOut : preset.animate;
const q = clamp01(p);
const pose = flickered(sampleProperties(props, q, dur), q, 0);
// A wiggly preset keeps its stray here too — it is the whole motion of a
// scatter, and dropping it would leave the element with only its fade.
return preset.wiggly ? applyWiggly(pose, preset.wiggly, 0, 1 - q) : pose;
}
/** How far a preset ever strays from rest, in design px, and whether it turns.
* Read from the data, so a new preset never has to be registered anywhere for
* the frame sampler to pad its crop correctly. */
export function presetExtent(preset: MotionPreset): { travel: number; rotates: boolean } {
let travel = 0;
let rotates = false;
for (const props of [preset.animate, preset.animateOut]) {
if (!props) continue;
// A unit carries both: the whole line's offset, plus its own share of the
// spread, so the one that gets farthest gets the sum of the two.
let offset = 0;
let spread = 0;
for (const k of props.position ?? [])
offset = Math.max(offset, Math.abs(k.v[0]), Math.abs(k.v[1]));
for (const k of props.tracking ?? []) spread = Math.max(spread, Math.abs(k.v));
// A split letter's copies and a blurred letter's halo reach past it too:
// a defocus spreads about twice its radius.
let halo = 0;
for (const k of props.split ?? []) halo = Math.max(halo, Math.abs(k.v));
for (const k of props.blur ?? []) halo = Math.max(halo, Math.abs(k.v) * 2);
travel = Math.max(travel, offset + spread + halo);
if ((props.rotation ?? []).some((k) => k.v !== 0)) rotates = true;
}
if (preset.wiggly?.position)
travel += Math.max(preset.wiggly.position[0], preset.wiggly.position[1]);
if (preset.wiggly?.rotation) rotates = true;
return { travel, rotates };
}
export { REST_POSE };