Open source CapCut alternative.
TypeScript
/**
* Keyframes: the power tier over the In / Out / Loop presets.
*
* A key is a whole pose — position, scale, rotation, opacity — captured at a
* moment inside the element. Between keys the pose moves linearly; before the
* first and after the last it holds. An element with no keys poses at its own
* resting fields, so keyframes are strictly additive: nothing changes until a
* key exists.
*
* Presets still compose on top. The preset transform is read as an offset —
* travel, scale multiplier, extra rotation, alpha multiplier — so a title can
* fade in, drift along a keyframed path, and pulse, all at once. `evalOverlayFrame`
* is the one function that folds the two together, and every renderer calls
* it: the DOM preview, the in-tab canvas export, the behind-speaker pass, and
* the frame sampler that feeds ffmpeg.
*/
import {
evalOverlayAnim,
hasOverlayAnim,
type GlyphLoopPhase,
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";
import { splitScale } from "./stretch";
import { dealsMarks, type ShapeKind } from "./types";
/** 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
* element's intrinsic size, where 1 is the size it was drawn at. */
export interface OverlayKey {
t: number;
x: number; // center, fraction of frame width
y: number; // center, fraction of frame height
scale: number;
/** Width and height over `scale`; absent = 1. A screen switching off
* squashes scaleY toward 0. */
scaleX?: number;
scaleY?: number;
rotation: number; // degrees clockwise
/** 3D tilt in degrees, seen in perspective (TILT_PERSPECTIVE): tiltX turns
* the element about its horizontal axis, top edge away from the viewer;
* tiltY about its vertical axis, right edge away. Absent = flat. */
tiltX?: number;
tiltY?: number;
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;
}
/** How far the viewer sits from a tilted element, px at the 1080 design
* short side: the CSS perspective() the DOM draws with and the depth the
* canvas painters project through. */
export const TILT_PERSPECTIVE = 1600;
/** The steepest tilt a key holds, degrees either way: at 90 the element is
* edge-on and gone. */
export const TILT_MAX = 85;
/** The most a tilt can grow an element's nearer edge, for the frame sampler's
* crop: an edge 540 design px off center tipped fully toward the viewer. */
export const TILT_GROW = TILT_PERSPECTIVE / (TILT_PERSPECTIVE - 540);
/** What an element looks like at one moment, before presets compose over it. */
export interface OverlayPose {
x: number;
y: number;
/** The larger axis; `sx`/`sy` stretch each axis over it (see stretch.ts). */
scale: number;
sx?: number;
sy?: number;
rotation: number;
/** Absent = flat (see OverlayKey). */
tiltX?: number;
tiltY?: number;
opacity: number;
/** Absent = sharp. */
blur?: number;
}
/** The fields `evalOverlayFrame` reads — every overlay kind has them. The
* mask is read structurally (keyed or not), keeping this module free of the
* mask model. */
interface Posable {
start: number;
end: number;
x: number;
y: number;
/** Absent means text — the union's own default. Only the per-glyph styles
* read it, to decide whether there are glyphs to move. */
kind?: string;
/** A shape's kind; a doodle paints anew on every beat. */
shape?: ShapeKind;
rotation?: number;
opacity?: number;
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 60fps, so a
* key can be dropped on any frame and still replace the one already there,
* while keys on neighbouring 60fps frames stay apart. */
export const KEY_EPSILON = 1 / 120;
/** The element's pose with no keys in play. */
export function restingPose(o: Posable): OverlayPose {
return {
x: o.x,
y: o.y,
scale: 1,
rotation: o.rotation ?? 0,
opacity: o.opacity ?? 1,
...(o.blur ? { blur: o.blur } : {}),
};
}
/** Whether the element carries keys worth evaluating. */
export function hasOverlayKeys(o: Posable): boolean {
return !!o.kf && o.kf.length > 0;
}
/** 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
* paints anew on every beat (a doodle). Any other element renders as one
* still picture, its own blur baked in. */
export function isOverlayAnimated(o: Posable): boolean {
return (
(o.kind === "shape" && !!o.shape && dealsMarks(o.shape)) ||
hasOverlayAnim(o.anim) ||
hasOverlayKeys(o) ||
hasCameraKeys(o.camera) ||
!!(o.mask?.kf && o.mask.kf.length > 0)
);
}
/** Keys in play order. Callers may hand them over unsorted (a key added at the
* playhead lands wherever the user was). */
export function sortedKeys<K extends { t: number }>(keys: K[]): K[] {
return [...keys].sort((a, b) => a.t - b.t);
}
/** Each stored track in play order, sorted once: a track is replaced on
* every edit and never changed in place, so a tracked mask's key per frame
* costs one sort when it lands and nothing on the frames that read it. */
const playOrder = new WeakMap<object, { t: number }[]>();
/**
* The interpolation core every key track shares: find the surrounding keys,
* 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; ease?: EaseId }>(
keys: K[],
tLocal: number,
mix: (a: K, b: K, p: number) => K
): K {
let ks = playOrder.get(keys) as K[] | undefined;
if (!ks) {
ks = sortedKeys(keys);
playOrder.set(keys, ks);
}
if (tLocal <= ks[0].t) return ks[0];
const last = ks[ks.length - 1];
if (tLocal >= last.t) return last;
let lo = 0;
let hi = ks.length - 1;
while (hi - lo > 1) {
const mid = (lo + hi) >> 1;
if (ks[mid].t <= tLocal) lo = mid;
else hi = mid;
}
const i = lo;
const a = ks[i];
const b = ks[i + 1];
const span = b.t - a.t;
const p = span > 1e-6 ? (tLocal - a.t) / span : 0;
// 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
* surrounding keys, held flat outside them, resting when there are no keys. */
export function poseAt(o: Posable, tLocal: number): OverlayPose {
if (!hasOverlayKeys(o)) return restingPose(o);
return poseOf(trackAt(o.kf!, tLocal, o.blur ?? 0), o.blur ?? 0);
}
/** The pose at `tLocal` in the keys' own terms (a uniform scale with its
* per-axis stretch apart), the way an editor shows and writes it. */
export function keyPoseAt(o: Posable, tLocal: number): Omit<OverlayKey, "t" | "ease"> {
if (!hasOverlayKeys(o)) return restingPose(o);
const k: Partial<OverlayKey> = { ...trackAt(o.kf!, tLocal, o.blur ?? 0) };
delete k.t;
delete k.ease;
return k as Omit<OverlayKey, "t" | "ease">;
}
/** The key track interpolated at `tLocal`. */
function trackAt(keys: OverlayKey[], tLocal: number, rest: number): OverlayKey {
// A key with no blur of its own takes the element's.
return 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);
// Axes and tilts a key leaves out sit at rest, so a squash or a tilt on
// one key eases in from the key before it.
const scaleX = mix(a.scaleX ?? 1, b.scaleX ?? 1);
const scaleY = mix(a.scaleY ?? 1, b.scaleY ?? 1);
const tiltX = mix(a.tiltX ?? 0, b.tiltX ?? 0);
const tiltY = mix(a.tiltY ?? 0, b.tiltY ?? 0);
return {
t: mix(a.t, b.t),
x: mix(a.x, b.x),
y: mix(a.y, b.y),
scale: mix(a.scale, b.scale),
...(scaleX !== 1 ? { scaleX } : {}),
...(scaleY !== 1 ? { scaleY } : {}),
// Rotation takes the short way around, so a key at 350° into one at 10°
// turns 20° forward instead of 340° back.
rotation: a.rotation + shortestTurn(a.rotation, b.rotation) * p,
...(tiltX !== 0 ? { tiltX } : {}),
...(tiltY !== 0 ? { tiltY } : {}),
opacity: mix(a.opacity, b.opacity),
...(blur > 0 ? { blur } : {}),
};
});
}
/** The signed short-way-around turn from one angle to another, degrees. */
export function shortestTurn(from: number, to: number): number {
let d = (to - from) % 360;
if (d > 180) d -= 360;
if (d < -180) d += 360;
return d;
}
function poseOf(k: OverlayKey, restBlur = 0): OverlayPose {
const blur = k.blur ?? restBlur;
return {
x: k.x,
y: k.y,
...splitScale(k.scale * (k.scaleX ?? 1), k.scale * (k.scaleY ?? 1)),
rotation: k.rotation,
...(k.tiltX ? { tiltX: k.tiltX } : {}),
...(k.tiltY ? { tiltY: k.tiltY } : {}),
opacity: k.opacity,
...(blur > 0 ? { blur } : {}),
};
}
/** A key holding the element's pose at `t`, ready to be added. Capturing the
* live pose is what makes the first two keys a no-op: the element sits where
* it already sat until one of them is moved. */
export function keyAt(o: Posable, t: number): OverlayKey {
return { t, ...keyPoseAt(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[] {
const rest = (keys ?? []).filter((k) => Math.abs(k.t - key.t) > KEY_EPSILON);
return sortedKeys([...rest, key]);
}
/** Drop the key at `t`, or return the list unchanged when none sits there. */
export function removeKeyAt<K extends { t: number }>(keys: K[] | undefined, t: number): K[] {
return (keys ?? []).filter((k) => Math.abs(k.t - t) > KEY_EPSILON);
}
/** The key sitting at `t`, if there is one. */
export function keyIndexAt(keys: { t: number }[] | undefined, t: number): number {
return (keys ?? []).findIndex((k) => Math.abs(k.t - t) <= KEY_EPSILON);
}
/** The element's full frame state: the keyframed pose with the preset
* animation composed over it. `dx`/`dy` are the preset's travel in design px
* (1080 short side); the pose's `x`/`y` stay fractions of the frame, because
* that is what keeps an element in the same place at any aspect.
*/
export interface OverlayFrameState extends OverlayPose {
dx: number;
dy: number;
/** 0..1 share of the text shown (typewriter); absent when not typing. */
textProgress?: number;
/** 0..1 share of its value each number shows (count); absent when not
* counting. */
countProgress?: number;
/** 0..1 share of the box uncovered from its left edge (wipe). */
reveal?: number;
/** 0..1 share of the ink eaten away (disintegrate). */
erode?: number;
/** 0..1 strength of the electric arcs over the element (zap hit). */
zap?: number;
/** Where a per-glyph ramp stands; the element's own transform stays neutral
* and each character carries the motion. */
glyphs?: GlyphPhase;
/** Where a per-glyph loop stands, on the same terms. */
glyphLoop?: GlyphLoopPhase;
/** How far the view has flown into the element's deepest ink (dive). */
dive?: number;
/** The diving edge, when it zooms about its own anchor. */
diveEdge?: "in" | "out";
/** 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.");
}
let 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;
// Letters on a per-letter ramp carry their own moves, so each one streaks
// along its own: the glyph evaluator reads the shutter as a share of the
// ramp.
const ramp = placed.glyphs;
if (whole && ramp?.seconds)
placed = { ...placed, glyphs: { ...ramp, exposure: exposure / ramp.seconds, shutter } };
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,
shutter
);
return streak ? { ...placed, streak } : placed;
}
/** 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");
// The pose's axes and the preset's multiply axis by axis, so a key squash
// and a preset flip compose.
const size = splitScale(
pose.scale * (pose.sx ?? 1) * ev.scale * (ev.sx ?? 1),
pose.scale * (pose.sy ?? 1) * ev.scale * (ev.sy ?? 1)
);
return {
x: pose.x,
y: pose.y,
dx: ev.dx,
dy: ev.dy,
...size,
rotation: pose.rotation + ev.rotate,
...(pose.tiltX ? { tiltX: pose.tiltX } : {}),
...(pose.tiltY ? { tiltY: pose.tiltY } : {}),
opacity: pose.opacity * ev.alpha,
...(ev.textProgress !== undefined ? { textProgress: ev.textProgress } : {}),
...(ev.countProgress !== undefined ? { countProgress: ev.countProgress } : {}),
...(ev.reveal !== undefined ? { reveal: ev.reveal } : {}),
...(ev.erode !== undefined ? { erode: ev.erode } : {}),
...(ev.zap ? { zap: ev.zap } : {}),
...(ev.glyphs ? { glyphs: ev.glyphs } : {}),
...(ev.glyphLoop ? { glyphLoop: ev.glyphLoop } : {}),
...(ev.dive !== undefined ? { dive: ev.dive } : {}),
...(ev.diveEdge ? { diveEdge: ev.diveEdge } : {}),
...(pose.blur || ev.blur ? { blur: (pose.blur ?? 0) + (ev.blur ?? 0) } : {}),
...(ev.caret !== undefined ? { caret: ev.caret } : {}),
...(ev.brightness !== undefined ? { brightness: ev.brightness } : {}),
};
}
/** The corners of the box the pose sweeps through, as fractions of the frame,
* plus the largest scale it reaches. The frame sampler crops to this, so a
* keyframed element's pictures stay small even when it crosses the screen. */
export function poseExtent(o: Posable): {
x0: number;
y0: number;
x1: number;
y1: number;
scale: number;
} {
const poses = hasOverlayKeys(o) ? sortedKeys(o.kf!).map((k) => poseOf(k)) : [restingPose(o)];
// A tilted edge swings toward the viewer and draws larger than its scale.
const tilted = poses.some((p) => p.tiltX || p.tiltY);
return {
x0: Math.min(...poses.map((p) => p.x)),
y0: Math.min(...poses.map((p) => p.y)),
x1: Math.max(...poses.map((p) => p.x)),
y1: Math.max(...poses.map((p) => p.y)),
scale: Math.max(...poses.map((p) => p.scale), 1) * (tilted ? TILT_GROW : 1),
};
}