Open source CapCut alternative.
TypeScript
/**
* The one word evaluator.
*
* Everything a line does word by word — the karaoke accent captions have
* always had, a title swelling on the beat, a sentence assembling itself as
* it is spoken — comes through here. The windows are the model: one per
* display word, covering the element's span end to end with no gaps, so a
* treatment never blinks off between two words. `times` is the element's own
* clock, filled in when something measured the speech; its absence means
* nobody did, and the words share the span by length.
*
* A word's look at a moment is read off its effect's three poses and the
* seconds between them (see `types.ts`), resolved to a `WordDraw` the
* painters read straight. Neither painter knows what an effect is.
*/
import { bezierEase } from "../motion/evaluate";
import type { Overlay, TextOverlay } from "../types";
import { wordEffect, wordEffectRamps } from "./catalog";
import type { OverlayWords, WordDraw, WordEffect, WordFace, WordPose } from "./types";
/** How far a word's alphabetic baseline sits below the middle of its em box,
* in em. The canvas painter measures this off the face it is drawing and only
* falls back here; a stylesheet cannot measure, so the DOM twin works from
* this figure, which is where the two can differ by a hair while a word is
* mid-resize. */
export const WORD_BASELINE_DROP = 0.3;
/** Accent for an effect that names no color of its own. */
export const WORD_ACCENT_DEFAULT = "#FFE94A";
/** How much a popped word swells while it is said, and the bounds a caller
* may set instead. */
export const WORD_POP_SCALE = 1.24;
export const WORD_SWELL_MIN = 1;
export const WORD_SWELL_MAX = 2;
const clamp01 = (v: number) => (v < 0 ? 0 : v > 1 ? 1 : v);
const lerp = (a: number, b: number, p: number) => a + (b - a) * p;
/** Black or white, whichever reads on the given hex fill. */
export function contrastText(hex: string): string {
const n = hexValue(hex);
if (n === null) return "#111114";
const lum = 0.299 * ((n >> 16) & 255) + 0.587 * ((n >> 8) & 255) + 0.114 * (n & 255);
return lum > 150 ? "#111114" : "#FFFFFF";
}
function hexValue(hex: string): number | null {
const m = /^#?([0-9a-fA-F]{6})$/.exec(hex.trim());
return m ? parseInt(m[1], 16) : null;
}
/** Two hex colors blended in sRGB. Anything that will not parse hands back
* the endpoint it is nearest, so an unusual color string still draws. */
export function mixHex(from: string, to: string, p: number): string {
if (p <= 0.001) return from;
if (p >= 0.999) return to;
const a = hexValue(from);
const b = hexValue(to);
if (a === null || b === null) return p < 0.5 ? from : to;
let out = "#";
for (let s = 16; s >= 0; s -= 8) {
const v = Math.round(lerp((a >> s) & 255, (b >> s) & 255, p));
out += v.toString(16).padStart(2, "0");
}
return out;
}
/**
* The color a word runs to: what the element set, else the effect's own
* default. An effect that says everything with size keeps the color the rest
* of the line is written in; the ones that speak in color take the accent.
*/
export function wordAccent(
w: { style?: string; color?: string } | undefined,
textColor: string
): string {
if (w?.color) return w.color;
return wordEffect(w?.style).accentDefault === "text" ? textColor : WORD_ACCENT_DEFAULT;
}
/** How far a word swells at its moment: the element's own setting, else the
* peak its effect reaches. Never below 1 — this is also the room a frame
* sampler leaves around the line for a word that grows past it. */
export function wordSwell(w: { style?: string; scale?: number } | undefined): number {
if (!w) return 1;
const set = w.scale;
if (set !== undefined && Number.isFinite(set))
return Math.min(WORD_SWELL_MAX, Math.max(WORD_SWELL_MIN, set));
const e = wordEffect(w.style);
return Math.max(1, e.before.scale ?? 1, e.active.scale ?? 1, e.after.scale ?? 1);
}
/** The opacity a word wears off its moment: the element's own setting, else
* the faintest its effect calls for. */
export function wordDim(w: { style?: string; dim?: number } | undefined): number {
if (w?.dim !== undefined && Number.isFinite(w.dim)) return clamp01(w.dim);
const e = wordEffect(w?.style);
return Math.min(1, e.before.opacity ?? 1, e.active.opacity ?? 1, e.after.opacity ?? 1);
}
/** The display words of a text block: whitespace-split across every line.
* Both renderers walk them in this order, which is what a word index means. */
export function displayWords(text: string): string[] {
return text.trim().split(/\s+/).filter(Boolean);
}
/**
* One window per display word, seconds from the element's start, partitioning
* [0, dur] with no gaps. Measured onsets are used while they still match the
* text one for one; otherwise (an edited line, a rewrite) the span is split
* proportionally by word length.
*/
export function wordWindows(
text: string,
dur: number,
times?: number[]
): { start: number; end: number }[] {
const words = displayWords(text);
const n = words.length;
if (n === 0 || dur <= 0) return [];
const starts: number[] = [];
if (times && times.length === n) {
for (let i = 0; i < n; i++) {
const t = i === 0 ? 0 : Math.min(Math.max(times[i], 0), dur);
starts.push(i > 0 && t < starts[i - 1] ? starts[i - 1] : t);
}
} else {
const weights = words.map((w) => w.length + 1);
const total = weights.reduce((a, b) => a + b, 0);
let acc = 0;
for (const w of weights) {
starts.push((dur * acc) / total);
acc += w;
}
}
return starts.map((start, i) => ({ start, end: i === n - 1 ? dur : starts[i + 1] }));
}
/** A pose with every channel filled in, and the element's two overrides
* folded in: the size knob replaces every scale above 1, the dim knob every
* opacity below 1. Both are single settings across the effect, so an effect
* that wanted two different faint levels would flatten them — none does. */
function settled(
p: WordPose,
swell: number,
dim: number,
/** The pose a word wears at its moment, which is where a swell the caller
* asked for lands even on an effect that resizes nothing of its own. */
atItsMoment = false
): Required<WordPose> {
const scale = p.scale ?? 1;
const opacity = p.opacity ?? 1;
return {
accent: p.accent ?? 0,
opacity: opacity < 1 ? dim : 1,
scale: scale > 1 || (atItsMoment && swell > 1) ? swell : scale,
dx: p.dx ?? 0,
dy: p.dy ?? 0,
rotate: p.rotate ?? 0,
mark: p.mark ?? 0,
};
}
function blend(a: Required<WordPose>, b: Required<WordPose>, p: number): Required<WordPose> {
return {
accent: lerp(a.accent, b.accent, p),
opacity: lerp(a.opacity, b.opacity, p),
scale: lerp(a.scale, b.scale, p),
dx: lerp(a.dx, b.dx, p),
dy: lerp(a.dy, b.dy, p),
rotate: lerp(a.rotate, b.rotate, p),
mark: lerp(a.mark, b.mark, p),
};
}
/**
* One word's pose at `t` seconds on the element's clock: held at `before`
* until its window opens, ramped to `active` over the attack, held there to
* the end of the window, then ramped to `after` over the release. An attack
* longer than the window itself is cut to fit, so a fast word still finishes
* arriving before the next one starts.
*/
export function wordPoseAt(
e: WordEffect,
win: { start: number; end: number },
t: number,
opts: { swell: number; dim: number }
): Required<WordPose> {
const before = settled(e.before, opts.swell, opts.dim);
const active = settled(e.active, opts.swell, opts.dim, true);
const after = settled(e.after, opts.swell, opts.dim);
const ease = (u: number) => (e.ease ? bezierEase(e.ease, clamp01(u)) : clamp01(u));
const span = Math.max(0, win.end - win.start);
const attack = Math.min(e.attack, span);
if (t < win.start) return before;
if (attack > 0 && t < win.start + attack)
return blend(before, active, ease((t - win.start) / attack));
if (t < win.end) return active;
if (e.release > 0 && t < win.end + e.release)
return blend(active, after, ease((t - win.end) / e.release));
return after;
}
/** The word effect an element carries, or nothing — the slot is text only. */
export function overlayWords(o: Overlay): OverlayWords | undefined {
if ((o.kind ?? "text") !== "text") return undefined;
return o.anim?.words;
}
/**
* Every display word resolved for drawing at `t` seconds on the element's
* clock. The accent is already blended into each word's fill, so a painter
* reads colors and numbers and nothing else.
*/
export function wordDrawsAt(
text: string,
words: OverlayWords,
textColor: string,
dur: number,
t: number,
/** Per display word: the face a word is set apart in, or nothing. The
* effect's accent blends from the face's own fill. */
faces?: readonly (WordFace | undefined)[]
): WordDraw[] {
const e = wordEffect(words.style);
const accent = wordAccent(words, textColor);
const markText = contrastText(accent);
// A box puts the word inside the accent, so its fill runs to the color that
// reads against that fill rather than to the accent itself.
const target = e.mark === "box" ? markText : accent;
const opts = { swell: wordSwell(words), dim: wordDim(words) };
const restScale = (e.after.scale ?? 1) > 1 ? opts.swell : (e.after.scale ?? 1);
return wordWindows(text, dur, words.times).map((win, i) => {
const p = wordPoseAt(e, win, t, opts);
const face = faces?.[i];
return withFace(
{
color: mixHex(face?.color ?? textColor, target, p.accent),
opacity: p.opacity,
scale: p.scale,
layoutScale: Math.max(p.scale, restScale),
dx: p.dx,
dy: p.dy,
rotate: p.rotate,
...(e.mark && p.mark > 0.001
? { mark: e.mark, markAlpha: p.mark, markColor: accent, markText }
: {}),
},
face
);
});
}
/** A resolved word set in its face: the face's size multiplies the pose's,
* and its family, slant and weight ride along for the painters. */
function withFace(d: WordDraw, face: WordFace | undefined): WordDraw {
if (!face) return d;
const k = face.scale !== undefined && Number.isFinite(face.scale) && face.scale > 0 ? face.scale : 1;
if (k !== 1) {
d.scale *= k;
d.layoutScale *= k;
}
if (face.font) d.font = face.font;
if (face.italic !== undefined) d.italic = face.italic;
if (face.weight !== undefined) d.weight = face.weight;
return d;
}
/**
* Every display word at rest, with the faces some of them are set apart in —
* a line that runs no word effect but still sets chosen words apart. Nothing
* here moves, so a caller may compute it once and hold it for the line's
* whole span.
*/
export function wordFaceDraws(
text: string,
textColor: string,
faces: readonly (WordFace | undefined)[]
): WordDraw[] {
return displayWords(text).map((_, i) => {
const face = faces[i];
return withFace({ ...REST_WORD, color: face?.color ?? textColor }, face);
});
}
/**
* The element as it paints at `t`, its words resolved — the one field both
* painters read, so neither needs to know an effect exists. An element with
* no word effect rides through untouched.
*/
export function applyWordDraw<T extends Overlay>(o: T, t: number, dur: number): T {
const w = overlayWords(o);
if (!w) return o;
const text = o as TextOverlay;
return {
...o,
wordDraw: wordDrawsAt(text.text, w, text.color ?? WORD_ACCENT_DEFAULT, dur, t),
} as T;
}
/** Frames per second a ramping effect is cut at when a sampler has to bake it
* into stills. Matches the slice rate the typed-out ramps use. */
const WORD_SLICE_FPS = 24;
/**
* The spans a sampler has to draw separately to carry this effect: one per
* stretch where the picture holds still, cut finer wherever a word is
* ramping. An effect that lands on the beat comes back as its word windows
* exactly — one still per word, which is what the caption burn-in has always
* written. Spans partition [0, dur] with no gaps.
*/
export function wordSampleWindows(
text: string,
words: OverlayWords,
dur: number,
fps = WORD_SLICE_FPS,
/** Most slices one ramp may be cut into. A sampler whose pictures are
* expensive — a caption burn-in draws whole frames — bounds it, so a long
* attack costs the same few pictures a short one does. */
maxSlices = Infinity
): { start: number; end: number }[] {
const wins = wordWindows(text, dur, words.times);
if (wins.length === 0) return [];
const e = wordEffect(words.style);
const cuts = new Set<number>([0, dur]);
const at = (v: number) => {
if (v > 1e-3 && v < dur - 1e-3) cuts.add(Math.round(v * 1e4) / 1e4);
};
for (const w of wins) {
at(w.start);
at(w.end);
}
if (wordEffectRamps(e)) {
const ramp = (from: number, secs: number) => {
if (secs <= 0) return;
const n = Math.min(Math.ceil(secs * fps), maxSlices + 1);
for (let i = 1; i < n; i++) at(from + (secs * i) / n);
};
for (const w of wins) {
ramp(w.start, Math.min(e.attack, Math.max(0, w.end - w.start)));
ramp(w.end, e.release);
}
}
const sorted = [...cuts].sort((a, b) => a - b);
const out: { start: number; end: number }[] = [];
for (let i = 0; i + 1 < sorted.length; i++) {
if (sorted[i + 1] - sorted[i] > 1e-3) out.push({ start: sorted[i], end: sorted[i + 1] });
}
return out;
}
/** A hex color at a given alpha, as the 8-digit hex both CSS and a canvas
* fill accept. */
export function hexAlpha(hex: string, a: number): string {
const n = hexValue(hex);
const byte = Math.round(clamp01(a) * 255)
.toString(16)
.padStart(2, "0");
if (n === null) return hex;
return `#${n.toString(16).padStart(6, "0")}${byte}`;
}
/** How far a word strays from its place, in em of its own type size — the
* room a frame sampler has to leave around the line. A turn counts as reach
* too: a word pivoting about its own center swings its ends out of the box.
*/
export function wordReach(w: { style?: string } | undefined): number {
if (!w) return 0;
const e = wordEffect(w.style);
const of = (p: WordPose) =>
Math.max(Math.abs(p.dx ?? 0), Math.abs(p.dy ?? 0)) + Math.abs(p.rotate ?? 0) / 30;
return Math.max(of(e.before), of(e.active), of(e.after));
}
/** A word at rest — the pose a painter falls back to when the track it was
* handed is shorter than the text it is drawing. */
export const REST_WORD: WordDraw = {
color: "#FFFFFF",
opacity: 1,
scale: 1,
layoutScale: 1,
dx: 0,
dy: 0,
rotate: 0,
};