Skip to content

Open source CapCut alternative.

TypeScript

feat(site): a word effect engine with configs [rebuild]

David Le314dcd9a0054
diff --git a/site/packages/effects-kit/src/render.ts b/site/packages/effects-kit/src/render.ts
index 17b746de..83d64c19 100644
--- a/site/packages/effects-kit/src/render.ts
+++ b/site/packages/effects-kit/src/render.ts
@@ -34,13 +34,14 @@ import {
type TextShadowSpec,
} from "./types";
import {
- applyWordAccent,
- highlightSwell,
+ applyWordDraw,
overlayWords,
+ REST_WORD,
WORD_ACCENT_DEFAULT,
- wordAccentIndex,
+ WORD_BASELINE_DROP,
+ wordReach,
+ wordSampleWindows,
wordSwell,
- wordWindows,
} from "./words";
// Text metrics shared by DOM preview and canvas burn-in.
@@ -382,43 +383,71 @@ async function paintText(
const cx = overlay.x * width;
const cy = overlay.y * frame.height;
- // Karaoke lays its words out first. The emphasized word may be swollen, and
- // it takes that width in the line — its neighbours move out of its way — so
- // the plate, the alignment and the draw all have to read one layout.
- const swell = overlay.highlightWord === undefined ? 1 : highlightSwell(overlay);
- const bigFont = swell !== 1 ? textCssFont(overlay, fpx * swell, env) : cssFont;
- if (swell !== 1) await ensureFontLoaded(bigFont, overlay.text);
- /** Draw and measure at the swollen word's size, or back at the line's.
- * Tracking is em of the size in play, so a swollen word is spaced like the
- * words beside it. */
- const setSize = (big: boolean) => {
- ctx.font = big ? bigFont : cssFont;
- if ("letterSpacing" in ctx)
- ctx.letterSpacing = `${(overlay.letterSpacing ?? 0) * (big ? fpx * swell : fpx)}px`;
+ // A word effect lays its words out first. A word may draw at its own size,
+ // and it takes that width in the line — its neighbours move out of its way —
+ // so the plate, the alignment and the draw all have to read one layout.
+ const draws = overlay.wordDraw?.length ? overlay.wordDraw : null;
+ const fonts = new Map<number, string>();
+ const sizeKey = (mult: number) => Math.round(mult * 1000) / 1000;
+ const fontFor = (mult: number) => {
+ const key = sizeKey(mult);
+ let f = fonts.get(key);
+ if (!f) {
+ f = key === 1 ? cssFont : textCssFont(overlay, fpx * key, env);
+ fonts.set(key, f);
+ }
+ return f;
+ };
+ // Every size in play has to be resident before measureText, or the layout is
+ // measured against a fallback face and the burn-in drifts off the preview.
+ if (draws) {
+ const sizes = new Set(draws.flatMap((d) => [sizeKey(d.scale), sizeKey(d.layoutScale)]));
+ for (const key of sizes) {
+ if (key !== 1) await ensureFontLoaded(fontFor(key), overlay.text);
+ }
+ }
+ /** Draw and measure at a word's own size, or back at the line's. Tracking is
+ * em of the size in play, so a resized word is spaced like the words beside
+ * it. */
+ // The size the next draw happens at. A font string carries the weight in
+ // front of it, so reading the size back out of `ctx.font` returns the weight
+ // on any bold face; this is the size, tracked where it is set.
+ let drawSize = fpx;
+ const setSize = (mult: number) => {
+ ctx.font = fontFor(mult);
+ drawSize = fpx * sizeKey(mult);
+ if ("letterSpacing" in ctx) ctx.letterSpacing = `${(overlay.letterSpacing ?? 0) * drawSize}px`;
};
- const runs =
- overlay.highlightWord === undefined
- ? null
- : (() => {
- const spaceW = ctx.measureText(" ").width;
- let k = 0;
- return lines.map((line) => {
- const words = line.split(" ").filter(Boolean);
- const widths = words.map((w) => {
- const big = k++ === overlay.highlightWord && swell !== 1;
- if (big) setSize(true);
- const ww = ctx.measureText(w).width;
- if (big) setSize(false);
- return ww;
- });
- return {
- words,
- widths,
- spaceW,
- lineW: widths.reduce((a, b) => a + b, 0) + spaceW * Math.max(0, words.length - 1),
- };
- });
- })();
+ const runs = !draws
+ ? null
+ : (() => {
+ const spaceW = ctx.measureText(" ").width;
+ let k = 0;
+ const at = (w: string, mult: number) => {
+ if (mult === 1) return ctx.measureText(w).width;
+ setSize(mult);
+ const ww = ctx.measureText(w).width;
+ setSize(1);
+ return ww;
+ };
+ return lines.map((line) => {
+ const words = line.split(" ").filter(Boolean);
+ // Two widths per word: the room it takes in the line, and the width
+ // it actually draws at. They differ only while a word is growing
+ // into its place, and it draws centered in the room it will fill.
+ const from = k;
+ k += words.length;
+ const widths = words.map((w, j) => at(w, sizeKey(draws[from + j]?.layoutScale ?? 1)));
+ const drawn = words.map((w, j) => at(w, sizeKey(draws[from + j]?.scale ?? 1)));
+ return {
+ words,
+ widths,
+ drawn,
+ spaceW,
+ lineW: widths.reduce((a, b) => a + b, 0) + spaceW * Math.max(0, words.length - 1),
+ };
+ });
+ })();
const widthsOf = runs ? runs.map((r) => r.lineW) : lines.map((l) => ctx.measureText(l).width);
const maxW = Math.max(...widthsOf, 1);
@@ -447,10 +476,9 @@ async function paintText(
const drawText = (text: string, x: number, y: number, fill: string = overlay.color) => {
if (overlay.stroke && strokeW > 0) {
ctx.lineJoin = "round";
- // In em of whatever size is set, so a swollen word wears the same
+ // In em of whatever size is set, so a resized word wears the same
// outline weight as the words beside it.
- const em = parseFloat(ctx.font) || fpx;
- ctx.lineWidth = (strokeW / fpx) * em * 2; // half of a centered stroke shows behind the fill
+ ctx.lineWidth = (strokeW / fpx) * drawSize * 2; // half of a centered stroke shows behind the fill
ctx.strokeStyle = overlay.stroke.color;
ctx.strokeText(text, x, y);
}
@@ -503,68 +531,100 @@ async function paintText(
return;
}
- // Karaoke: draw word by word so the spoken word takes its accent treatment —
- // color, underline, a box, or a swell; the word index counts across all
- // lines. The words sit in the layout measured above, so a swollen one has
- // already pushed its neighbours aside and they close back up as the
- // emphasis moves on.
- if (!runs) {
+ // A word effect draws word by word, each word at the color, opacity and pose
+ // the engine resolved for it; the word index counts across all lines. The
+ // words sit in the layout measured above, so one drawn bigger has already
+ // pushed its neighbours aside and they close back up as it shrinks.
+ if (!runs || !draws) {
lines.forEach((line, i) => drawText(line, lineX(i), cy - totalH / 2 + lineH * (i + 0.5)));
return;
}
- // A word drawn at another size shares the baseline with the words beside
- // it, so where that baseline sits has to be read off the face: the middle
- // this painter draws from is half the type's own height above it.
- const fm = ctx.measureText("Hg");
- const asc = fm.fontBoundingBoxAscent ?? fpx * 0.8;
- const desc = fm.fontBoundingBoxDescent ?? fpx * 0.2;
- const midOf = (size: number) => ((asc - desc) / 2) * (size / fpx);
+ // A word drawn at another size shares the baseline with the words beside it,
+ // so where that baseline sits under the middle this painter draws from has to
+ // be read off the face. Measuring the same string against both alignments
+ // gives the gap exactly, in whatever engine is drawing: the ascent is
+ // reported from the alignment point, so the difference between the two is the
+ // distance between them.
+ const ascentAt = (baseline: CanvasTextBaseline) => {
+ ctx.textBaseline = baseline;
+ return ctx.measureText("Hg").actualBoundingBoxAscent;
+ };
+ const alphabetic = ascentAt("alphabetic");
+ const middle = ascentAt("middle");
+ const drop =
+ Number.isFinite(alphabetic) && Number.isFinite(middle) && alphabetic > middle
+ ? alphabetic - middle
+ : fpx * WORD_BASELINE_DROP;
+ ctx.textBaseline = "middle";
+ const alpha0 = ctx.globalAlpha;
let k = 0;
ctx.textAlign = "left";
runs.forEach((run, i) => {
const y = cy - totalH / 2 + lineH * (i + 0.5);
let x = cx - run.lineW / 2;
run.words.forEach((w, wi) => {
- const active = k === overlay.highlightWord;
- const big = active && swell !== 1;
- // A word at the line's own size draws from the middle, exactly as it
- // always has; a swollen one hangs off the shared baseline instead, and
- // its own middle follows from there.
- const size = big ? fpx * swell : fpx;
- const drawY = big ? y + midOf(fpx) : y;
- const mid = big ? y + midOf(fpx) - midOf(size) : y;
- if (big) {
- setSize(true);
- ctx.textBaseline = "alphabetic";
- }
- if (active && overlay.highlightMode === "box") {
- // Accent box behind the word, contrast text on top — drawn with the
- // shadow off so the box and its word stay crisp.
- const pad = 0.12 * size;
- const prevShadow = ctx.shadowColor;
- ctx.shadowColor = "transparent";
- ctx.fillStyle = overlay.highlightColor ?? WORD_ACCENT_DEFAULT;
- ctx.beginPath();
- ctx.roundRect(x - pad, mid - size * 0.5 - pad, run.widths[wi] + pad * 2, size + pad * 2, 0.18 * size);
- ctx.fill();
- drawText(w, x, drawY, overlay.highlightText ?? "#111114");
- ctx.shadowColor = prevShadow;
- } else if (active) {
- drawText(w, x, drawY, overlay.highlightColor ?? WORD_ACCENT_DEFAULT);
- if (overlay.highlightMode === "underline") {
- ctx.fillRect(x, mid + size * 0.42, run.widths[wi], Math.max(2 * scale, size * 0.07));
+ const d = draws[k] ?? { ...REST_WORD, color: overlay.color };
+ const mult = sizeKey(d.scale);
+ const width = run.widths[wi];
+ const alpha = alpha0 * Math.min(1, Math.max(0, d.opacity));
+ // A word its effect has not brought in yet has no pixels; it still holds
+ // its place, so the words beside it stay where they will be.
+ if (alpha > 0.001) {
+ // Every word draws from its own middle; a resized one has that middle
+ // lifted or dropped by exactly as much as sharing the line's baseline
+ // asks for.
+ const size = fpx * mult;
+ const mid = y + drop * (1 - mult);
+ const drawY = mid;
+ // Centered in the room the layout left it.
+ const drawX = x + (width - run.drawn[wi]) / 2;
+ // Everything below rides one saved state, so nothing set for this word
+ // reaches the next.
+ ctx.save();
+ ctx.globalAlpha = alpha;
+ // Offsets are em of the word's own size, and it turns about its center.
+ if (d.dx || d.dy || d.rotate) {
+ const wx = drawX + run.drawn[wi] / 2;
+ ctx.translate(wx + d.dx * size, mid + d.dy * size);
+ if (d.rotate) ctx.rotate((d.rotate * Math.PI) / 180);
+ ctx.translate(-wx, -mid);
}
- } else {
- drawText(w, x, drawY);
- }
- if (big) {
- setSize(false);
- ctx.textBaseline = "middle";
+ setSize(mult);
+ const boxed = d.mark === "box" && !!d.markAlpha;
+ if (boxed) {
+ // Accent box behind the word, and the word on top of it — both drawn
+ // with the shadow off so the box and its word stay crisp.
+ const pad = 0.12 * size;
+ ctx.shadowColor = "transparent";
+ ctx.globalAlpha = alpha * d.markAlpha!;
+ ctx.fillStyle = d.markColor ?? WORD_ACCENT_DEFAULT;
+ ctx.beginPath();
+ ctx.roundRect(
+ drawX - pad,
+ mid - size * 0.5 - pad,
+ run.drawn[wi] + pad * 2,
+ size + pad * 2,
+ 0.18 * size
+ );
+ ctx.fill();
+ ctx.globalAlpha = alpha;
+ }
+ drawText(w, drawX, drawY, d.color);
+ if (d.mark === "underline" && d.markAlpha) {
+ ctx.globalAlpha = alpha * d.markAlpha;
+ ctx.fillStyle = d.color;
+ ctx.fillRect(drawX, mid + size * 0.42, run.drawn[wi], Math.max(2 * scale, size * 0.07));
+ }
+ ctx.restore();
+ // `restore` puts the canvas back at the line's own size; the size this
+ // painter tracks goes back with it.
+ drawSize = fpx;
}
- x += run.widths[wi] + run.spaceW;
+ x += width + run.spaceW;
k++;
});
});
+ ctx.globalAlpha = alpha0;
ctx.textAlign = "center";
}
@@ -797,10 +857,12 @@ export function planAnimatedLayers(o: Overlay, end: number): AnimatedLayer[] {
phase,
});
if (words) {
- wordWindows((o as TextOverlay).text, dur, words.times).forEach((w, i) => {
+ wordSampleWindows((o as TextOverlay).text, words, dur).forEach((w) => {
const a = Math.max(start, o.start + w.start);
const b = Math.min(stop, o.start + w.end);
- if (b - a >= 1e-3) add(applyWordAccent(overlay, i), a, b);
+ // Drawn at the middle of the span it stands for, which is where the
+ // picture it caches actually sits.
+ if (b - a >= 1e-3) add(applyWordDraw(overlay, (w.start + w.end) / 2, dur), a, b);
});
return;
}
@@ -906,14 +968,20 @@ export async function renderOverlayFrames(
// the preset's own reach already covers where the glyphs get to.
const loop = loopExtent(anim?.loop);
const move = moveExtent(anim?.move);
- const travel = (edgeTravel + loop.travel + move.travel) * scale;
+ // A word effect can lift, shift or turn a word out of the resting line, in
+ // em of the type's own size, so the region carries that reach as well.
+ const accent = overlayWords(overlay);
+ const wordTravel =
+ accent && (overlay.kind ?? "text") === "text"
+ ? wordReach(accent) * (overlay as TextOverlay).size * scale
+ : 0;
+ const travel = (edgeTravel + loop.travel + move.travel) * scale + wordTravel;
// A keyframed element carries its own travel and its own zoom: the region
// spans every pose the track visits, at the largest scale it reaches.
const keyed = hasOverlayKeys(overlay);
const extent = poseExtent(overlay);
// A swollen word grows the line past the resting box, so the region carries
// it — width from the swell, and the type's own extra height with it.
- const accent = overlayWords(overlay);
const maxScale = 1.15 * extent.scale * move.scale * wordSwell(accent);
const rotates =
!!overlay.rotation ||
@@ -952,9 +1020,10 @@ export async function renderOverlayFrames(
// Back to the origin the painters draw around, so they stay unaware of
// any of this.
ctx.translate(-overlay.x * width, -overlay.y * height);
- let el: Overlay = applyWordAccent(
+ let el: Overlay = applyWordDraw(
{ ...overlay, rotation: undefined, opacity: undefined },
- wordAccentIndex(overlay, tLocal, dur)
+ tLocal,
+ dur
);
if (ev.textProgress !== undefined && (overlay.kind ?? "text") === "text") {
const text = (overlay as TextOverlay).text;
@@ -1021,10 +1090,11 @@ export async function renderOverlayFrames(
if (middle > 1e-3) {
const period = loopPeriod(anim) ?? lottieDur;
if (accent) {
- // The picture changes as the emphasis moves on, and nowhere else: one
- // frame per word covers the middle however long it runs. The last one
- // absorbs the rounding, so the pieces sum to the middle exactly.
- const spans = wordWindows((overlay as TextOverlay).text, dur, accent.times)
+ // The picture changes as the effect walks the line, and nowhere else:
+ // one frame per span the engine says holds still covers the middle
+ // however long it runs. The last one absorbs the rounding, so the
+ // pieces sum to the middle exactly.
+ const spans = wordSampleWindows((overlay as TextOverlay).text, accent, dur, fps)
.map((w) => ({ a: Math.max(inS, w.start), b: Math.min(dur - outS, w.end) }))
.filter((w) => w.b - w.a > 1e-3);
if (spans.length > 0) spans[spans.length - 1].b = dur - outS;
diff --git a/site/packages/effects-kit/src/types.ts b/site/packages/effects-kit/src/types.ts
index 1a1d08aa..1e409d8f 100644
--- a/site/packages/effects-kit/src/types.ts
+++ b/site/packages/effects-kit/src/types.ts
@@ -9,6 +9,7 @@ import type { OverlayAnim } from "./anim";
import type { EffectOverlay } from "./effects";
import type { OverlayKey } from "./keys";
import type { Mask } from "./mask";
+import type { WordDraw } from "./words/types";
/** Fields every overlay element carries, whatever its kind. */
export interface OverlayBase {
@@ -39,13 +40,6 @@ export interface OverlayBase {
mask?: Mask;
}
-/** How a highlighted word lights up in karaoke text: accent color only,
- * accent color plus underline, an accent box behind the word, or the word
- * swelling at the accent color. A swollen word takes its new width in the
- * line, so its neighbours move out of its way and settle back as the
- * emphasis travels on. */
-export type WordAccentMode = "color" | "underline" | "box" | "pop";
-
/** A custom drop shadow. Every field is optional — absent ones take the
* legacy defaults, so `shadow: true` and `shadow: {}` render identically. */
export interface TextShadowSpec {
@@ -90,14 +84,10 @@ export interface TextOverlay extends OverlayBase {
plateRadius?: number; // plate corner radius in em
plateColor?: string; // plate fill color
plateOpacity?: number; // plate fill opacity 0..1
- /** Karaoke burn-in: index of the display word (whitespace-split across all
- * lines) drawn per the accent treatment. */
- highlightWord?: number;
- highlightColor?: string;
- highlightMode?: WordAccentMode;
- highlightText?: string;
- /** How far the highlighted word swells; absent = the mode's own default. */
- highlightScale?: number;
+ /** Word burn-in: one entry per display word (whitespace-split across all
+ * lines), each resolved to the color, opacity and pose it draws at. Stamped
+ * by the word engine at paint time; absent = the line draws as one piece. */
+ wordDraw?: WordDraw[];
}
export type ShapeKind =
diff --git a/site/packages/effects-kit/src/words.test.ts b/site/packages/effects-kit/src/words.test.ts
deleted file mode 100644
index 04d459cf..00000000
--- a/site/packages/effects-kit/src/words.test.ts
+++ /dev/null
@@ -1,123 +0,0 @@
-import { describe, expect, test } from "bun:test";
-import { hasOverlayAnim } from "./anim";
-import type { TextOverlay } from "./types";
-import {
- applyWordAccent,
- displayWords,
- wordAccent,
- WORD_ACCENT_DEFAULT,
- wordAccentIndex,
- wordSwell,
- WORD_POP_SCALE,
- WORD_SWELL_MAX,
- wordWindows,
-} from "./words";
-
-const title = (over: Partial<TextOverlay> = {}): TextOverlay => ({
- id: "t1",
- kind: "text",
- text: "one two three",
- start: 2,
- end: 5,
- x: 0.5,
- y: 0.5,
- size: 64,
- font: "sf",
- weight: 700,
- color: "#FFFFFF",
- shadow: true,
- plate: false,
- ...over,
-});
-
-describe("word windows", () => {
- test("cover the span end to end with no gaps", () => {
- const wins = wordWindows("one two three", 3);
- expect(wins.length).toBe(3);
- expect(wins[0].start).toBe(0);
- expect(wins[2].end).toBe(3);
- for (let i = 1; i < wins.length; i++) expect(wins[i].start).toBe(wins[i - 1].end);
- });
-
- test("follow measured onsets when they match the words", () => {
- const wins = wordWindows("one two three", 3, [0, 1.2, 2.4]);
- expect(wins.map((w) => w.start)).toEqual([0, 1.2, 2.4]);
- expect(wins[2].end).toBe(3);
- });
-
- test("fall back to an even share when the text has outgrown the times", () => {
- const wins = wordWindows("one two three four", 4, [0, 1.2, 2.4]);
- expect(wins.length).toBe(4);
- expect(wins[0].start).toBe(0);
- });
-
- test("never run backwards", () => {
- const wins = wordWindows("one two three", 3, [0, 2.5, 1]);
- expect(wins[2].start).toBeGreaterThanOrEqual(wins[1].start);
- });
-
- test("count words across lines", () => {
- expect(displayWords("one two\nthree")).toEqual(["one", "two", "three"]);
- });
-});
-
-describe("word emphasis", () => {
- const words = { style: "pop" as const, color: "#FF3D00" };
-
- test("counts as animation, so both renderers take the moving path", () => {
- expect(hasOverlayAnim({ words })).toBe(true);
- expect(hasOverlayAnim({})).toBe(false);
- });
-
- test("marks the word being said", () => {
- const o = title({ anim: { words } });
- expect(wordAccentIndex(o, 0, 3)).toBe(0);
- expect(wordAccentIndex(o, 2.9, 3)).toBe(2);
- });
-
- test("is a title's slot; other kinds ignore it", () => {
- const sticker = { ...title({ anim: { words } }), kind: "sticker" as const, w: 0.2 };
- expect(wordAccentIndex(sticker as never, 0, 3)).toBe(-1);
- });
-
- test("paints through the same highlight fields captions ride", () => {
- const marked = applyWordAccent(title({ anim: { words } }), 1) as TextOverlay;
- expect(marked.highlightWord).toBe(1);
- expect(marked.highlightMode).toBe("pop");
- expect(marked.highlightColor).toBe("#FF3D00");
- expect(marked.highlightText).toBe("#FFFFFF");
- expect(marked.highlightScale).toBe(WORD_POP_SCALE);
- });
-
- test("a swell keeps the line's own color; the color treatments take the accent", () => {
- const swelled = applyWordAccent(
- title({ color: "#FFFFFF", anim: { words: { style: "pop" } } }),
- 0
- ) as TextOverlay;
- expect(swelled.highlightColor).toBe("#FFFFFF");
- const boxed = applyWordAccent(
- title({ color: "#FFFFFF", anim: { words: { style: "box" } } }),
- 0
- ) as TextOverlay;
- expect(boxed.highlightColor).toBe(WORD_ACCENT_DEFAULT);
- expect(wordAccent({ style: "pop", color: "#0A84FF" }, "#FFFFFF")).toBe("#0A84FF");
- });
-
- test("swells by the treatment's default until something says otherwise", () => {
- expect(wordSwell({ style: "pop" })).toBe(WORD_POP_SCALE);
- expect(wordSwell({ style: "box" })).toBe(1);
- expect(wordSwell({ style: "box", scale: 1.5 })).toBe(1.5);
- expect(wordSwell(undefined)).toBe(1);
- });
-
- test("holds the swell inside its bounds", () => {
- expect(wordSwell({ style: "pop", scale: 9 })).toBe(WORD_SWELL_MAX);
- expect(wordSwell({ style: "pop", scale: 0.2 })).toBe(1);
- expect(wordSwell({ style: "pop", scale: Number.NaN })).toBe(WORD_POP_SCALE);
- });
-
- test("an element with no emphasis rides through untouched", () => {
- const o = title();
- expect(applyWordAccent(o, 1)).toBe(o);
- });
-});
diff --git a/site/packages/effects-kit/src/words.ts b/site/packages/effects-kit/src/words.ts
deleted file mode 100644
index c81ab6d3..00000000
--- a/site/packages/effects-kit/src/words.ts
+++ /dev/null
@@ -1,167 +0,0 @@
-/**
- * Word-by-word emphasis on text: the whole line stays on screen and the word
- * being said takes the accent. Captions have had this since they carried word
- * timings; here it is the same treatment offered as a slot on any text
- * element, so a title placed by hand emphasizes on its own clock.
- *
- * The windows are the model. One per display word, covering the element's
- * span end to end with no gaps, so the accent never blinks off between two
- * words. `times` is the element's own clock — seconds from its start — filled
- * in when something measured the speech; its absence means nobody did, and
- * the words share the span by length.
- */
-
-import type { Overlay, TextOverlay, WordAccentMode } from "./types";
-
-/** Accent for emphasis 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. The swollen word takes its new width in the line, so the
- * words beside it move out of its way and settle back as it shrinks. */
-export const WORD_POP_SCALE = 1.24;
-export const WORD_SWELL_MIN = 1;
-export const WORD_SWELL_MAX = 2;
-
-/** The treatments, in the order every picker offers them. */
-export const WORD_ACCENT_MODE_IDS: WordAccentMode[] = ["pop", "color", "underline", "box"];
-
-export const WORD_ACCENT_LABELS: Record<WordAccentMode, string> = {
- pop: "Pop",
- color: "Color",
- underline: "Underline",
- box: "Highlight",
-};
-
-export const WORD_ACCENT_NOTES: Record<WordAccentMode, string> = {
- pop: "the word swells and the line makes room for it, in the text's own color unless an accent is set",
- color: "the word takes the accent color",
- underline: "accent color with a rule under the word",
- box: "an accent box behind the word",
-};
-
-/** Word emphasis as an element carries it. */
-export interface OverlayWords {
- style: WordAccentMode;
- /** Accent color; absent = the treatment's own default (see `wordAccent`):
- * a swell keeps the text's color, the color treatments take the accent. */
- color?: string;
- /** How far the word swells while it is said, WORD_SWELL_MIN..MAX; absent =
- * the treatment's own default. */
- scale?: number;
- /** Word onsets in seconds from the element's start, one per display word.
- * Absent, or a count the text has outgrown, = an even share by length. */
- times?: number[];
-}
-
-/**
- * The color an emphasized word wears: what the element set, else the
- * treatment's own default. A swell says everything it has to say with size,
- * so it keeps the color the rest of the line is written in; the treatments
- * that speak in color take the accent.
- */
-export function wordAccent(
- w: { style?: WordAccentMode; color?: string } | undefined,
- textColor: string
-): string {
- if (w?.color) return w.color;
- return w?.style === "pop" ? textColor : WORD_ACCENT_DEFAULT;
-}
-
-/** How far the emphasized word swells: the element's own setting, else the
- * treatment's default — a pop swells, the rest hold their size. */
-export function wordSwell(w: { style?: WordAccentMode; 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));
- return w.style === "pop" ? WORD_POP_SCALE : 1;
-}
-
-/** The swell of the word a painted overlay has marked — the same reading as
- * `wordSwell`, off the highlight fields the painters actually carry. */
-export function highlightSwell(o: { highlightMode?: WordAccentMode; highlightScale?: number }): number {
- return wordSwell({ style: o.highlightMode, scale: o.highlightScale });
-}
-
-/** Black or white, whichever reads on the given hex fill. */
-export function contrastText(hex: string): string {
- const m = /^#?([0-9a-fA-F]{6})$/.exec(hex.trim());
- if (!m) return "#111114";
- const n = parseInt(m[1], 16);
- const lum = 0.299 * ((n >> 16) & 255) + 0.587 * ((n >> 8) & 255) + 0.114 * (n & 255);
- return lum > 150 ? "#111114" : "#FFFFFF";
-}
-
-/** 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] }));
-}
-
-/** The emphasis 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;
-}
-
-/** Which display word is emphasized at `tLocal`, or -1 before the first. */
-export function wordAccentIndex(o: Overlay, tLocal: number, dur: number): number {
- const w = overlayWords(o);
- if (!w) return -1;
- return wordWindows((o as TextOverlay).text, dur, w.times).findIndex(
- (win) => tLocal >= win.start && tLocal < win.end
- );
-}
-
-/**
- * The element as it paints with one word emphasized — the same
- * `highlightWord` fields captions ride, so the painters need to know nothing
- * about where the index came from. An element with no emphasis, or a time
- * before its first word, rides through untouched.
- */
-export function applyWordAccent<T extends Overlay>(o: T, index: number): T {
- const w = overlayWords(o);
- if (!w || index < 0) return o;
- const color = wordAccent(w, (o as TextOverlay).color ?? WORD_ACCENT_DEFAULT);
- return {
- ...o,
- highlightWord: index,
- highlightColor: color,
- highlightMode: w.style,
- highlightText: contrastText(color),
- highlightScale: wordSwell(w),
- } as T;
-}
diff --git a/site/packages/effects-kit/src/words/catalog.ts b/site/packages/effects-kit/src/words/catalog.ts
new file mode 100644
index 00000000..d5b8eb36
--- /dev/null
+++ b/site/packages/effects-kit/src/words/catalog.ts
@@ -0,0 +1,88 @@
+/**
+ * The word-effect catalog: every treatment a line's words can take, as data.
+ *
+ * The JSON beside this file holds them in the three-pose shape `types.ts`
+ * describes. Every picker, tool enum and prompt line is written from these
+ * entries, so an effect added to the file reaches the element panel, the
+ * caption panel and the assistant at once.
+ */
+
+import effects from "./effects.json";
+import type { WordEffect, WordEffectId, WordFamily, WordPose } from "./types";
+
+export const WORD_EFFECTS: Record<string, WordEffect> = effects as unknown as Record<
+ string,
+ WordEffect
+>;
+
+/** The effects, in the order every picker offers them. */
+export const WORD_EFFECT_IDS: WordEffectId[] = Object.keys(WORD_EFFECTS);
+
+/** The effect an id names, or the plainest one when the id is unknown — a
+ * document written against an effect since renamed still plays. */
+export function wordEffect(id: WordEffectId | undefined): WordEffect {
+ return WORD_EFFECTS[id ?? ""] ?? WORD_EFFECTS.color;
+}
+
+export const WORD_EFFECT_LABELS: Record<string, string> = Object.fromEntries(
+ WORD_EFFECT_IDS.map((id) => [id, WORD_EFFECTS[id].label])
+);
+
+export const WORD_EFFECT_NOTES: Record<string, string> = Object.fromEntries(
+ WORD_EFFECT_IDS.map((id) => [id, WORD_EFFECTS[id].note])
+);
+
+/** The catalog as a menu: id, label and line, in picker order — what the
+ * element panel, the caption panel and the tool enums all list from. */
+export const WORD_EFFECT_MENU: { id: WordEffectId; label: string; note: string; family: WordFamily }[] =
+ WORD_EFFECT_IDS.map((id) => ({
+ id,
+ label: WORD_EFFECTS[id].label,
+ note: WORD_EFFECTS[id].note,
+ family: WORD_EFFECTS[id].family,
+ }));
+
+/** The shelves the picker lays out, with the line each one is titled by. */
+export const WORD_FAMILIES: { id: WordFamily; label: string; note: string }[] = [
+ {
+ id: "emphasis",
+ label: "Emphasis",
+ note: "the treatment travels along the line, one word at a time",
+ },
+ { id: "build", label: "Build", note: "the line assembles itself as it is spoken" },
+];
+
+export const wordEffectIdsIn = (family: WordFamily): WordEffectId[] =>
+ WORD_EFFECT_IDS.filter((id) => WORD_EFFECTS[id].family === family);
+
+const poses = (e: WordEffect): WordPose[] => [e.before, e.active, e.after];
+
+/** Which settings an effect actually has, so a panel offers the knobs that do
+ * something and no others. `size` drives every pose scale above 1, `dim` every
+ * pose opacity below 1, `color` the accent the effect runs to. A value the
+ * element already carries opens its knob whatever the effect does, so a
+ * setting in play is always one the reader can see and change. */
+export function wordKnobs(
+ e: WordEffect,
+ set?: { scale?: number; dim?: number }
+): { size: boolean; color: boolean; dim: boolean } {
+ return {
+ size: poses(e).some((p) => (p.scale ?? 1) > 1) || set?.scale !== undefined,
+ color: poses(e).some((p) => (p.accent ?? 0) > 0),
+ dim: poses(e).some((p) => (p.opacity ?? 1) < 1) || set?.dim !== undefined,
+ };
+}
+
+/** An effect whose poses change over seconds rather than landing on the beat.
+ * A ramp means the picture moves inside a word's window, so the frame
+ * samplers cut it finer than one still per word. */
+export const wordEffectRamps = (e: WordEffect): boolean => e.attack > 0 || e.release > 0;
+
+/** The catalog as prompt text: one line per effect, grouped by shelf. */
+export const wordEffectCatalog = (): string =>
+ WORD_FAMILIES.map(
+ (f) =>
+ `${f.label} — ${f.note}: ${wordEffectIdsIn(f.id)
+ .map((id) => `${id} (${WORD_EFFECTS[id].note})`)
+ .join("; ")}`
+ ).join("\n");
diff --git a/site/packages/effects-kit/src/words/effects.json b/site/packages/effects-kit/src/words/effects.json
new file mode 100644
index 00000000..8973a48d
--- /dev/null
+++ b/site/packages/effects-kit/src/words/effects.json
@@ -0,0 +1,122 @@
+{
+ "color": {
+ "label": "Color",
+ "note": "the word being said takes the accent color and hands it on",
+ "family": "emphasis",
+ "before": {},
+ "active": { "accent": 1 },
+ "after": {},
+ "attack": 0,
+ "release": 0
+ },
+ "pop": {
+ "label": "Pop",
+ "note": "the word swells and the line makes room for it, in the text's own color unless an accent is set",
+ "family": "emphasis",
+ "before": {},
+ "active": { "accent": 1, "scale": 1.24 },
+ "after": {},
+ "attack": 0,
+ "release": 0,
+ "accentDefault": "text"
+ },
+ "underline": {
+ "label": "Underline",
+ "note": "accent color with a rule under the word",
+ "family": "emphasis",
+ "before": {},
+ "active": { "accent": 1, "mark": 1 },
+ "after": {},
+ "attack": 0,
+ "release": 0,
+ "mark": "underline"
+ },
+ "box": {
+ "label": "Highlight",
+ "note": "an accent box behind the word",
+ "family": "emphasis",
+ "before": {},
+ "active": { "accent": 1, "mark": 1 },
+ "after": {},
+ "attack": 0,
+ "release": 0,
+ "mark": "box"
+ },
+ "spotlight": {
+ "label": "Spotlight",
+ "note": "the line sits faded and only the word being said is at full strength",
+ "family": "emphasis",
+ "before": { "opacity": 0.35 },
+ "active": { "opacity": 1 },
+ "after": { "opacity": 0.35 },
+ "attack": 0.1,
+ "release": 0.18,
+ "ease": [0.33, 0, 0.67, 1]
+ },
+ "build": {
+ "label": "Build up",
+ "note": "the line starts empty and each word appears as it is said, completing the sentence",
+ "family": "build",
+ "before": { "opacity": 0 },
+ "active": { "opacity": 1 },
+ "after": { "opacity": 1 },
+ "attack": 0.14,
+ "release": 0,
+ "ease": [0.33, 0, 0.67, 1]
+ },
+ "fill": {
+ "label": "Fill in",
+ "note": "the whole line is up but faint, and each word goes solid as it is said until the sentence is fully opaque",
+ "family": "build",
+ "before": { "opacity": 0.3 },
+ "active": { "opacity": 1 },
+ "after": { "opacity": 1 },
+ "attack": 0.2,
+ "release": 0,
+ "ease": [0.33, 0, 0.67, 1]
+ },
+ "rise": {
+ "label": "Rise up",
+ "note": "each word lifts into its place as it is said and stays",
+ "family": "build",
+ "before": { "opacity": 0, "dy": 0.45 },
+ "active": { "opacity": 1, "dy": 0 },
+ "after": { "opacity": 1, "dy": 0 },
+ "attack": 0.26,
+ "release": 0,
+ "ease": [0.16, 1, 0.3, 1]
+ },
+ "bloom": {
+ "label": "Bloom",
+ "note": "each word grows out of nothing into its size as it is said and stays",
+ "family": "build",
+ "before": { "opacity": 0, "scale": 0.4 },
+ "active": { "opacity": 1, "scale": 1 },
+ "after": { "opacity": 1, "scale": 1 },
+ "attack": 0.24,
+ "release": 0,
+ "ease": [0.34, 1.56, 0.64, 1]
+ },
+ "swing": {
+ "label": "Swing in",
+ "note": "each word drops in leaning and rights itself as it is said",
+ "family": "build",
+ "before": { "opacity": 0, "rotate": -14, "dy": -0.3 },
+ "active": { "opacity": 1, "rotate": 0, "dy": 0 },
+ "after": { "opacity": 1, "rotate": 0, "dy": 0 },
+ "attack": 0.3,
+ "release": 0,
+ "ease": [0.34, 1.56, 0.64, 1]
+ },
+ "paint": {
+ "label": "Paint on",
+ "note": "the line is written in its own color and each word takes the accent as it is said, keeping it",
+ "family": "build",
+ "before": {},
+ "active": { "accent": 1 },
+ "after": { "accent": 1 },
+ "attack": 0.12,
+ "release": 0,
+ "ease": [0.33, 0, 0.67, 1]
+ }
+}
diff --git a/site/packages/effects-kit/src/words/engine.ts b/site/packages/effects-kit/src/words/engine.ts
new file mode 100644
index 00000000..5b2ba6fb
--- /dev/null
+++ b/site/packages/effects-kit/src/words/engine.ts
@@ -0,0 +1,348 @@
+/**
+ * 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, 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
+): 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) => {
+ const p = wordPoseAt(e, win, t, opts);
+ return {
+ color: mixHex(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 }
+ : {}),
+ };
+ });
+}
+
+/**
+ * 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,
+};
diff --git a/site/packages/effects-kit/src/words/index.ts b/site/packages/effects-kit/src/words/index.ts
new file mode 100644
index 00000000..260d6b7c
--- /dev/null
+++ b/site/packages/effects-kit/src/words/index.ts
@@ -0,0 +1,3 @@
+export * from "./types";
+export * from "./catalog";
+export * from "./engine";
diff --git a/site/packages/effects-kit/src/words/types.ts b/site/packages/effects-kit/src/words/types.ts
new file mode 100644
index 00000000..9bd111e8
--- /dev/null
+++ b/site/packages/effects-kit/src/words/types.ts
@@ -0,0 +1,108 @@
+/**
+ * The word-effect format: three poses and the seconds between them.
+ *
+ * A word effect is what a line does word by word while it plays. Each display
+ * word owns a window on the element's clock (see `wordWindows`), and the
+ * effect says how that word looks before its window, at it, and after it has
+ * passed. An emphasis travels — `after` is `before`, so the treatment moves
+ * along the line. A build accumulates — `after` is `active`, so the line
+ * assembles itself as it is spoken.
+ *
+ * Everything in the picker is one entry in this shape, stored as data beside
+ * this file. Adding an effect means adding an entry; no code lists them.
+ */
+
+import type { Easing } from "../motion/types";
+
+/** One word's look at one moment. Offsets are em of the word's own type size,
+ * rotation is degrees clockwise about its center; every channel is optional
+ * and an absent one rests. */
+export interface WordPose {
+ /** How far the word has taken the accent color, 0..1. */
+ accent?: number;
+ /** The word's own opacity, multiplying the element's. */
+ opacity?: number;
+ /** Type-size multiplier. A word drawn bigger takes its new width in the
+ * line, so its neighbours move out of its way and settle back after. */
+ scale?: number;
+ dx?: number;
+ dy?: number;
+ rotate?: number;
+ /** How far the effect's mark is drawn, 0..1. */
+ mark?: number;
+}
+
+/** The mark an effect draws behind or under the word it is on. */
+export type WordMark = "underline" | "box";
+
+/** Which shelf of the picker an effect sits on: an emphasis that travels
+ * along the line, or a build the line assembles itself through. */
+export type WordFamily = "emphasis" | "build";
+
+export interface WordEffect {
+ label: string;
+ /** What the effect does, in one line — the text the tool schemas and the
+ * assistant's skills are written from. */
+ note: string;
+ family: WordFamily;
+ /** Before the word's window. */
+ before: WordPose;
+ /** Once it has arrived. */
+ active: WordPose;
+ /** After its window has passed. */
+ after: WordPose;
+ /** Seconds from the word's onset to `active`; 0 = it lands on the beat. */
+ attack: number;
+ /** Seconds from the end of its window to `after`; 0 = it leaves on the
+ * beat. */
+ release: number;
+ ease?: Easing;
+ mark?: WordMark;
+ /** The color the accent channel runs to when the element names none: the
+ * accent (`accent`), or the text's own color (`text`), which is what an
+ * effect that says everything with size wants. */
+ accentDefault?: "accent" | "text";
+}
+
+/** The effect ids, as saved on an element and on the subtitles block. */
+export type WordEffectId = string;
+
+/** Word effects as an element carries them. */
+export interface OverlayWords {
+ style: WordEffectId;
+ /** Accent color; absent = the effect's own default (see `wordAccent`). */
+ color?: string;
+ /** How far a word swells at its moment; replaces every pose scale above 1.
+ * Absent = the effect's own. */
+ scale?: number;
+ /** The opacity a word wears off its moment; replaces every pose opacity
+ * below 1. Absent = the effect's own. */
+ dim?: number;
+ /** Word onsets in seconds from the element's start, one per display word.
+ * Absent, or a count the text has outgrown, = an even share by length. */
+ times?: number[];
+}
+
+/** One word, resolved for drawing: what both painters read and neither
+ * computes. */
+export interface WordDraw {
+ /** The fill, with the accent already blended in. */
+ color: string;
+ opacity: number;
+ scale: number;
+ /** The size the word takes room at, which is its own or its resting size,
+ * whichever is wider. A word swelling past its rest pushes its neighbours
+ * aside; one still growing into place holds the room it will end up
+ * needing, so the line does not slide about as it assembles. */
+ layoutScale: number;
+ /** Em of the word's own type size. */
+ dx: number;
+ dy: number;
+ rotate: number;
+ /** The mark to draw, and how far; absent = none. */
+ mark?: WordMark;
+ markAlpha?: number;
+ markColor?: string;
+ /** Word color over a box, which needs to read against the fill. */
+ markText?: string;
+}
diff --git a/site/packages/effects-kit/src/words/words.test.ts b/site/packages/effects-kit/src/words/words.test.ts
new file mode 100644
index 00000000..426b6a23
--- /dev/null
+++ b/site/packages/effects-kit/src/words/words.test.ts
@@ -0,0 +1,261 @@
+import { describe, expect, test } from "bun:test";
+import { hasOverlayAnim } from "../anim";
+import type { TextOverlay } from "../types";
+import {
+ applyWordDraw,
+ displayWords,
+ mixHex,
+ wordAccent,
+ WORD_ACCENT_DEFAULT,
+ wordDim,
+ wordDrawsAt,
+ wordEffect,
+ WORD_EFFECT_IDS,
+ wordKnobs,
+ WORD_POP_SCALE,
+ wordSampleWindows,
+ wordSwell,
+ WORD_SWELL_MAX,
+ wordWindows,
+} from ".";
+
+const title = (over: Partial<TextOverlay> = {}): TextOverlay => ({
+ id: "t1",
+ kind: "text",
+ text: "one two three",
+ start: 2,
+ end: 5,
+ x: 0.5,
+ y: 0.5,
+ size: 64,
+ font: "sf",
+ weight: 700,
+ color: "#FFFFFF",
+ shadow: true,
+ plate: false,
+ ...over,
+});
+
+describe("word windows", () => {
+ test("cover the span end to end with no gaps", () => {
+ const wins = wordWindows("one two three", 3);
+ expect(wins.length).toBe(3);
+ expect(wins[0].start).toBe(0);
+ expect(wins[2].end).toBe(3);
+ for (let i = 1; i < wins.length; i++) expect(wins[i].start).toBe(wins[i - 1].end);
+ });
+
+ test("follow measured onsets when they match the words", () => {
+ const wins = wordWindows("one two three", 3, [0, 1.2, 2.4]);
+ expect(wins.map((w) => w.start)).toEqual([0, 1.2, 2.4]);
+ expect(wins[2].end).toBe(3);
+ });
+
+ test("fall back to an even share when the text has outgrown the times", () => {
+ const wins = wordWindows("one two three four", 4, [0, 1.2, 2.4]);
+ expect(wins.length).toBe(4);
+ expect(wins[0].start).toBe(0);
+ });
+
+ test("never run backwards", () => {
+ const wins = wordWindows("one two three", 3, [0, 2.5, 1]);
+ expect(wins[2].start).toBeGreaterThanOrEqual(wins[1].start);
+ });
+
+ test("count words across lines", () => {
+ expect(displayWords("one two\nthree")).toEqual(["one", "two", "three"]);
+ });
+});
+
+describe("the catalog", () => {
+ test("every effect names its family and settles its three poses", () => {
+ for (const id of WORD_EFFECT_IDS) {
+ const e = wordEffect(id);
+ expect(["emphasis", "build"]).toContain(e.family);
+ expect(e.attack).toBeGreaterThanOrEqual(0);
+ expect(e.release).toBeGreaterThanOrEqual(0);
+ }
+ });
+
+ test("an emphasis returns to where it started; a build keeps what it did", () => {
+ expect(wordEffect("color").after).toEqual(wordEffect("color").before);
+ expect(wordEffect("build").after).toEqual(wordEffect("build").active);
+ });
+
+ test("an unknown id falls back rather than throwing", () => {
+ expect(wordEffect("nope").label).toBe(wordEffect("color").label);
+ });
+
+ test("offers the knobs an effect actually uses", () => {
+ expect(wordKnobs(wordEffect("pop"))).toEqual({ size: true, color: true, dim: false });
+ expect(wordKnobs(wordEffect("build"))).toEqual({ size: false, color: false, dim: true });
+ });
+});
+
+describe("word effects", () => {
+ const words = { style: "pop", color: "#FF3D00" };
+
+ test("count as animation, so both renderers take the moving path", () => {
+ expect(hasOverlayAnim({ words })).toBe(true);
+ expect(hasOverlayAnim({})).toBe(false);
+ });
+
+ test("mark the word being said and leave the rest alone", () => {
+ const draws = wordDrawsAt("one two three", words, "#FFFFFF", 3, 0);
+ expect(draws[0].color).toBe("#FF3D00");
+ expect(draws[0].scale).toBe(WORD_POP_SCALE);
+ expect(draws[1].color).toBe("#FFFFFF");
+ expect(draws[1].scale).toBe(1);
+ });
+
+ test("are a title's slot; other kinds ride through untouched", () => {
+ const sticker = { ...title({ anim: { words } }), kind: "sticker" as const, w: 0.2 };
+ expect(applyWordDraw(sticker as never, 0, 3)).toBe(sticker);
+ });
+
+ test("stamp one entry per display word", () => {
+ const marked = applyWordDraw(title({ anim: { words } }), 1.5, 3) as TextOverlay;
+ expect(marked.wordDraw?.length).toBe(3);
+ });
+
+ test("a swell keeps the line's own color; the color treatments take the accent", () => {
+ expect(wordAccent({ style: "pop" }, "#FFFFFF")).toBe("#FFFFFF");
+ expect(wordAccent({ style: "box" }, "#FFFFFF")).toBe(WORD_ACCENT_DEFAULT);
+ expect(wordAccent({ style: "pop", color: "#0A84FF" }, "#FFFFFF")).toBe("#0A84FF");
+ });
+
+ test("a box puts contrast text on the word so it reads against its own fill", () => {
+ const draws = wordDrawsAt("one two", { style: "box", color: "#FFE94A" }, "#FFFFFF", 2, 0);
+ expect(draws[0].mark).toBe("box");
+ expect(draws[0].markColor).toBe("#FFE94A");
+ expect(draws[0].color).toBe("#111114");
+ });
+
+ test("swell by the effect's default until something says otherwise", () => {
+ expect(wordSwell({ style: "pop" })).toBe(WORD_POP_SCALE);
+ expect(wordSwell({ style: "box" })).toBe(1);
+ expect(wordSwell({ style: "box", scale: 1.5 })).toBe(1.5);
+ expect(wordSwell(undefined)).toBe(1);
+ });
+
+ test("hold the swell inside its bounds", () => {
+ expect(wordSwell({ style: "pop", scale: 9 })).toBe(WORD_SWELL_MAX);
+ expect(wordSwell({ style: "pop", scale: 0.2 })).toBe(1);
+ expect(wordSwell({ style: "pop", scale: Number.NaN })).toBe(WORD_POP_SCALE);
+ });
+
+ test("an element with no effect rides through untouched", () => {
+ const o = title();
+ expect(applyWordDraw(o, 1, 3)).toBe(o);
+ });
+});
+
+describe("a build", () => {
+ const words = { style: "build", times: [0, 1, 2] };
+ const text = "one two three";
+
+ test("starts with nothing up and finishes with the whole line", () => {
+ const first = wordDrawsAt(text, words, "#FFFFFF", 3, 0);
+ expect(first[1].opacity).toBe(0);
+ expect(first[2].opacity).toBe(0);
+ const last = wordDrawsAt(text, words, "#FFFFFF", 3, 2.9);
+ expect(last.every((d) => d.opacity === 1)).toBe(true);
+ });
+
+ test("keeps every word it has landed", () => {
+ const mid = wordDrawsAt(text, words, "#FFFFFF", 3, 1.5);
+ expect(mid[0].opacity).toBe(1);
+ expect(mid[1].opacity).toBe(1);
+ expect(mid[2].opacity).toBe(0);
+ });
+
+ test("ramps rather than snapping", () => {
+ const e = wordEffect("build");
+ const mid = wordDrawsAt(text, words, "#FFFFFF", 3, 1 + e.attack / 2);
+ expect(mid[1].opacity).toBeGreaterThan(0);
+ expect(mid[1].opacity).toBeLessThan(1);
+ });
+});
+
+describe("a fill", () => {
+ const words = { style: "fill", times: [0, 1, 2] };
+ const text = "one two three";
+
+ test("leaves the whole line faintly up before its words land", () => {
+ const draws = wordDrawsAt(text, words, "#FFFFFF", 3, 0);
+ expect(draws[2].opacity).toBeCloseTo(wordEffect("fill").before.opacity!, 5);
+ expect(draws[2].opacity).toBeGreaterThan(0);
+ });
+
+ test("takes the caller's transparency over its own", () => {
+ const draws = wordDrawsAt(text, { ...words, dim: 0.6 }, "#FFFFFF", 3, 0);
+ expect(draws[2].opacity).toBeCloseTo(0.6, 5);
+ expect(wordDim({ style: "fill", dim: 0.6 })).toBe(0.6);
+ expect(wordDim({ style: "fill" })).toBe(wordEffect("fill").before.opacity);
+ });
+
+ test("ends fully opaque all the way along", () => {
+ const draws = wordDrawsAt(text, { ...words, dim: 0.6 }, "#FFFFFF", 3, 3);
+ expect(draws.every((d) => d.opacity === 1)).toBe(true);
+ });
+});
+
+describe("sample windows", () => {
+ test("an effect that lands on the beat is one still per word", () => {
+ const spans = wordSampleWindows("one two three", { style: "color" }, 3);
+ expect(spans.length).toBe(3);
+ expect(spans[0].start).toBe(0);
+ expect(spans[2].end).toBe(3);
+ });
+
+ test("a ramping effect is cut finer, still covering the span with no gaps", () => {
+ const spans = wordSampleWindows("one two three", { style: "build", times: [0, 1, 2] }, 3);
+ expect(spans.length).toBeGreaterThan(3);
+ expect(spans[0].start).toBe(0);
+ expect(spans[spans.length - 1].end).toBe(3);
+ for (let i = 1; i < spans.length; i++) expect(spans[i].start).toBe(spans[i - 1].end);
+ });
+});
+
+describe("color blending", () => {
+ test("runs between the two ends and stops at them", () => {
+ expect(mixHex("#000000", "#FFFFFF", 0)).toBe("#000000");
+ expect(mixHex("#000000", "#FFFFFF", 1)).toBe("#FFFFFF");
+ expect(mixHex("#000000", "#FFFFFF", 0.5)).toBe("#808080");
+ });
+});
+
+describe("a saved swell", () => {
+ test("lands on the word's moment even where the effect resizes nothing", () => {
+ // The picker used to offer a size on every treatment, so documents carry
+ // one on effects whose own poses hold their size.
+ const draws = wordDrawsAt("one two", { style: "box", scale: 1.5 }, "#FFFFFF", 2, 0);
+ expect(draws[0].scale).toBe(1.5);
+ expect(draws[1].scale).toBe(1);
+ });
+
+ test("opens its knob wherever a value is in play", () => {
+ expect(wordKnobs(wordEffect("box")).size).toBe(false);
+ expect(wordKnobs(wordEffect("box"), { scale: 1.5 }).size).toBe(true);
+ expect(wordKnobs(wordEffect("color"), { dim: 0.5 }).dim).toBe(true);
+ });
+
+ test("leaves a word still growing into place at the size its effect asks", () => {
+ const e = wordEffect("bloom");
+ const draws = wordDrawsAt("one two", { style: "bloom", times: [0, 1] }, "#FFFFFF", 2, 0.999);
+ expect(draws[1].scale).toBeCloseTo(e.before.scale!, 5);
+ expect(draws[1].layoutScale).toBe(1);
+ });
+});
+
+describe("sample slices", () => {
+ test("are bounded when the sampler asks for a cap", () => {
+ const words = { style: "rise", times: [0, 1, 2] };
+ const free = wordSampleWindows("one two three", words, 3);
+ const capped = wordSampleWindows("one two three", words, 3, 12, 2);
+ expect(capped.length).toBeLessThan(free.length);
+ expect(capped.length).toBeLessThanOrEqual(9);
+ expect(capped[capped.length - 1].end).toBe(3);
+ for (let i = 1; i < capped.length; i++) expect(capped[i].start).toBe(capped[i - 1].end);
+ });
+});