Open source CapCut alternative.
TypeScript
/**
* Canvas painters: rasterize any overlay element to a transparent full-frame
* PNG at the export resolution, with the same metrics the host's DOM preview
* uses. The host supplies a RenderEnv for everything it owns — font stacks and
* sticker image bytes — so painters stay host-agnostic.
*/
import {
bakesPixels,
CARET_GAP_EM,
CARET_HEIGHT_EM,
CARET_WIDTH_EM,
caretOn,
caretToggles,
edgeMotion,
evalOverlayAnim,
glyphStateAt,
hasGlyphMotion,
hitScale,
hitWindow,
hitZaps,
loopExtent,
loopPeriod,
moveExtent,
typeCaret,
type GlyphLoopPhase,
type GlyphPhase,
type OverlayAnim,
} from "./anim";
import { diveView, reelBand, slotReel, slotSeed, type DiveFocus, type DiveView } from "./dive";
import { cutAtFaces, cycleFaceTag, fontCycleCuts, fontCycleVariants, withFontCycle } from "./fontCycle";
import { evalWhole, presetExtent } from "./motion/evaluate";
import { countStep, countText } from "./count";
import { evalOverlayFrame, hasOverlayKeys, poseAt, poseExtent, sortedKeys, type OverlayFrameState } from "./keys";
import { ELEMENT_BLUR_MAX, hasCameraKeys, MOTION_BLUR_FRAME, streakCap, streakTaps } from "./camera";
import { drawStreak, ElementFx, elementLook } from "./elementFx";
import { applyMaskToCanvas, isMaskAnimated } from "./mask";
import { tracePolyShape } from "./shapePath";
import { paintPattern } from "./pattern";
import type { LottieHandle } from "./lottie";
import { elementPlugin } from "./registry";
import { kitCanvas } from "./surface";
import { cutTexture, erodeTile } from "./texture";
import { isInkless, SPLIT_CYAN, SPLIT_RED } from "./glyphLook";
import { paintZap, zapSeed, type ZapPhase } from "./zap";
import { DOODLE_FPS, doodleBeat, doodleSeed, paintDoodle } from "./doodle";
import {
dealsMarks,
lineLikeShape,
type Overlay,
type ShapeOverlay,
type StickerOverlay,
type TextOverlay,
type ShadowSpec,
} from "./types";
import {
applyWordDraw,
overlayWords,
REST_WORD,
WORD_ACCENT_DEFAULT,
WORD_BASELINE_DROP,
wordReach,
wordSampleWindows,
wordSwell,
type WordDraw,
} from "./words";
// Text metrics shared by DOM preview and canvas burn-in.
export const LINE_HEIGHT = 1.25;
export const PLATE_PAD_X = 0.55; // em
export const PLATE_PAD_Y = 0.3; // em
export const PLATE_RADIUS = 0.32; // em
export const PLATE_COLOR = "#000000";
export const PLATE_OPACITY = 0.55;
export const PLATE_FILL = "rgba(0, 0, 0, 0.55)";
export const SHADOW = { color: "rgba(0, 0, 0, 0.65)", blur: 14, offsetY: 2 };
/** A hex color with an opacity folded in, as rgba(); non-hex input falls back
* to black at that opacity. */
function rgba(hex: string, opacity: number): string {
const m = /^#?([0-9a-fA-F]{6})$/.exec(hex.trim());
if (!m) return `rgba(0, 0, 0, ${opacity})`;
const n = parseInt(m[1], 16);
return `rgba(${(n >> 16) & 255}, ${(n >> 8) & 255}, ${n & 255}, ${opacity})`;
}
/** A text element's plate fill as an rgba() string, defaulting to translucent
* black when color/opacity are unset. Shared by preview and export. */
export function plateFill(o: { plateColor?: string; plateOpacity?: number }): string {
return rgba(o.plateColor ?? PLATE_COLOR, o.plateOpacity ?? PLATE_OPACITY);
}
/** Resolve a text element's shadow to concrete design-px values, or null when
* it is off. `true` and `{}` both mean the legacy default look. */
export function resolveShadow(
shadow: boolean | ShadowSpec
): { color: string; blur: number; offsetY: number } | null {
if (shadow === false) return null;
const spec: ShadowSpec = shadow === true ? {} : shadow;
return {
color: rgba(spec.color ?? "#000000", spec.opacity ?? 0.65),
blur: spec.blur ?? SHADOW.blur,
offsetY: spec.offsetY ?? SHADOW.offsetY,
};
}
/** Await the faces a text element needs before measuring or painting, so a
* rasterize never silently measures a fallback font. No-op outside the DOM. */
export async function ensureFontLoaded(cssFont: string, text?: string): Promise<void> {
if (typeof document === "undefined" || !document.fonts?.load) return;
try {
await document.fonts.load(cssFont, text);
} catch {
// An unknown family or a blocked face falls back; painting proceeds.
}
}
/** A decoded sticker image with its natural size (for aspect). */
export interface StickerImage {
source: CanvasImageSource;
width: number;
height: number;
}
/** What the host supplies so painters can resolve host-owned resources. */
export interface RenderEnv {
/** CSS font-family stack for a host font id. */
fontStack(font: string): string;
/** Canvas surface for rasterization. The host injects a server canvas here
* to render headless; unset, the DOM canvas is used. */
createCanvas?(w: number, h: number): HTMLCanvasElement;
/** PNG encode for a canvas made by `createCanvas`. Required alongside it —
* a server canvas encodes through its own API. */
canvasToPngBlob?(canvas: HTMLCanvasElement): Promise<Blob>;
/** Decoded image for a sticker asset id; null when the asset is gone. */
resolveAsset?(assetId: string): Promise<StickerImage | null>;
/** Seekable player for a Lottie sticker asset id; null when the asset is
* gone or isn't a Lottie document. */
resolveLottie?(assetId: string): Promise<LottieHandle | null>;
/** The share of a face's em box above its baseline, read off the face's own
* tables, for a css font; undefined for a face the host cannot read. Lines
* are set from the em box's middle (`baselineDrop`), so a host that knows
* its faces sets them alike on every canvas. */
emAscent?(cssFont: string): number | undefined;
}
/**
* How far under a line's middle the line's baseline sits, px, for the font
* set on `ctx` at `px`.
*
* A line is set from the middle of its face's em box, as Chrome draws
* textBaseline "middle": its OS/2 typo ascent and descent, scaled to fill the
* em. Other canvases read "middle" off other boxes — skia off the line box a
* CSS line centres, which on Jost at 110 px is 12 px lower — so the painter
* draws from the alphabetic baseline and drops each line by this much itself.
* Given the face's `emAscent` the drop is the em box's own; a face nobody can
* read falls back on this canvas's "middle", read as the gap between the two
* alignments' ascents.
*/
export function baselineDrop(ctx: CanvasRenderingContext2D, px: number, emAscent?: number): number {
if (emAscent !== undefined && Number.isFinite(emAscent)) return px * (emAscent - 0.5);
const was = ctx.textBaseline;
ctx.textBaseline = "alphabetic";
const alphabetic = ctx.measureText("Hg").actualBoundingBoxAscent;
ctx.textBaseline = "middle";
const middle = ctx.measureText("Hg").actualBoundingBoxAscent;
ctx.textBaseline = was;
return Number.isFinite(alphabetic) && Number.isFinite(middle) && alphabetic > middle
? alphabetic - middle
: px * WORD_BASELINE_DROP;
}
/** The frame geometry handed to painters. `scale` converts design px (1080
* short side) to output px. `t` is seconds since the element's start, for
* painters whose pixels are time-dependent (Lottie stickers). */
export interface PaintFrame {
width: number;
height: number;
scale: number;
t?: number;
/** Pixel-level animation baked into this picture; absent = the element at
* rest. */
phase?: PaintPhase;
}
/** What a pixel-changing animation contributes to one picture: its reveal,
* glyph motion, and the pose and view a dive paints inside the frame. */
export interface PaintPhase {
reveal?: number;
/** Share of the ink eaten away (see `erodeTile`). */
erode?: number;
/** Electric arcs over the element (see `paintZap`). */
zap?: ZapPhase;
/** The beat a doodle deals its mark on (see `doodleBeat`). */
doodle?: number;
glyphs?: GlyphPhase;
glyphLoop?: GlyphLoopPhase;
/** The view a dive draws the whole picture under (see `diveView`). */
dive?: DiveView;
/** The typing bar is lit in this picture (see `caretOn`). */
caret?: boolean;
/** How many characters a typewriter has typed. They stand where the whole
* text puts them and the rest hold their room, so letters never slide as
* the line grows. A line break takes a turn, as the glyph index counts. */
typed?: number;
/** A dive's pose is painted before frame clipping, so a half-size title
* still fills the output frame when its flight lands. */
pose?: Pick<OverlayFrameState, "x" | "y" | "dx" | "dy" | "scale" | "sx" | "sy" | "rotation">;
}
/**
* A shape's pixel geometry in the output frame — the one place the fractions
* become pixels, shared by the canvas painter and testable on its own.
* Line/arrow thickness rides the shape's `h`; the arrow head scales with the
* thickness but never eats more than half the length.
*/
export function shapeMetrics(o: ShapeOverlay, frame: PaintFrame) {
const cx = o.x * frame.width;
const cy = o.y * frame.height;
const w = Math.max(1, o.w * frame.width);
const h = Math.max(1, o.h * frame.height);
const thickness = Math.max(2 * frame.scale, h);
const headLen = Math.min(thickness * 3, w / 2);
return {
cx,
cy,
w,
h,
radius: (o.radius ?? 0) * frame.scale,
strokeWidth: (o.stroke?.width ?? 0) * frame.scale,
thickness,
headLen,
headHalf: thickness * 1.6,
};
}
type ShapeMetrics = ReturnType<typeof shapeMetrics>;
/** How a shape body draws: as painted, or as the solid silhouette that casts
* its shadow (a pattern fill's gaps still cast). */
type ShapeCoat = "painted" | "silhouette";
function paintShape(ctx: CanvasRenderingContext2D, o: ShapeOverlay, frame: PaintFrame) {
const m = shapeMetrics(o, frame);
const shadow = resolveShadow(o.shadow ?? false);
const beat = frame.phase?.doodle ?? 0;
if (shadow) {
castShapeShadow(ctx, o, m, shadow, frame.scale, beat);
}
drawShapeBody(ctx, o, m, frame.scale, "painted", beat);
}
/**
* Cast a shape's shadow with no body: the silhouette draws far off to the
* left of the surface and its shadow is thrown back by the same distance, so
* only the shadow lands. Nothing is clipped while it draws, so a pattern fill
* keeps its lines inside the outline and its glow spreads past it.
*/
function castShapeShadow(
ctx: CanvasRenderingContext2D,
o: ShapeOverlay,
m: ShapeMetrics,
shadow: NonNullable<ReturnType<typeof resolveShadow>>,
scale: number,
beat: number
): void {
const t = ctx.getTransform();
const det = t.a * t.d - t.b * t.c;
if (!det) {
return;
}
// Far enough on screen that the moved body clears the surface: past the
// body's own screen x by its whole reach.
const reach = Math.hypot(m.w, Math.max(m.h, m.headHalf * 2)) + 2 * (m.strokeWidth + m.thickness);
const zoom = Math.max(Math.hypot(t.a, t.b), Math.hypot(t.c, t.d));
const away = Math.ceil(Math.abs(t.a * m.cx + t.c * m.cy + t.e) + reach * zoom + 1);
ctx.save();
ctx.shadowColor = shadow.color;
ctx.shadowBlur = shadow.blur * scale;
ctx.shadowOffsetX = away;
ctx.shadowOffsetY = shadow.offsetY * scale;
// Shadow offsets are screen px; the move is the same screen vector
// (-away, 0) carried back through the current transform.
ctx.translate((-away * t.d) / det, (away * t.b) / det);
drawShapeBody(ctx, o, m, scale, "silhouette", beat);
ctx.restore();
}
/** Trace a filled shape's outline as the current path. */
function traceShapeOutline(ctx: CanvasRenderingContext2D, o: ShapeOverlay, m: ShapeMetrics): void {
ctx.beginPath();
if (o.shape === "rect") {
ctx.roundRect(m.cx - m.w / 2, m.cy - m.h / 2, m.w, m.h, m.radius);
} else if (o.shape === "ellipse") {
ctx.ellipse(m.cx, m.cy, m.w / 2, m.h / 2, 0, 0, Math.PI * 2);
} else {
tracePolyShape(ctx, o.shape, m.w, m.h, m.cx - m.w / 2, m.cy - m.h / 2);
}
}
function drawShapeBody(
ctx: CanvasRenderingContext2D,
o: ShapeOverlay,
m: ShapeMetrics,
scale: number,
coat: ShapeCoat,
beat: number
): void {
const alpha = ctx.globalAlpha;
// A doodle paints the mark dealt on this beat inside its box, in the fill
// or one of its inks.
if (dealsMarks(o.shape)) {
ctx.globalAlpha = alpha * (o.fillOpacity ?? 1);
paintDoodle(ctx, { cx: m.cx, cy: m.cy, w: m.w, h: m.h, scale }, [o.fill, ...(o.inks ?? [])], beat, doodleSeed(o.id));
ctx.globalAlpha = alpha;
return;
}
ctx.fillStyle = o.fill;
if (!lineLikeShape(o.shape)) {
traceShapeOutline(ctx, o, m);
ctx.globalAlpha = alpha * (o.fillOpacity ?? 1);
// A pattern paints over the box clipped to the outline, anchored at the
// box's top-left; the outline is traced again for the stroke.
if (o.pattern && coat === "painted") {
ctx.save();
ctx.clip();
ctx.translate(m.cx - m.w / 2, m.cy - m.h / 2);
paintPattern(ctx, o.pattern, m.w, m.h, o.fill, scale);
ctx.restore();
traceShapeOutline(ctx, o, m);
} else {
ctx.fill();
}
ctx.globalAlpha = alpha;
if (o.stroke && m.strokeWidth > 0) {
ctx.strokeStyle = o.stroke.color;
ctx.lineWidth = m.strokeWidth;
ctx.lineJoin = "round";
ctx.stroke();
}
return;
}
// Line / arrow: a horizontal stroke across the element box; rotation (the
// generic element transform) gives it any direction.
const x0 = m.cx - m.w / 2;
const x1 = m.cx + m.w / 2;
ctx.strokeStyle = o.fill;
ctx.lineWidth = m.thickness;
ctx.lineCap = "round";
ctx.beginPath();
ctx.moveTo(x0, m.cy);
ctx.lineTo(o.shape === "arrow" ? x1 - m.headLen : x1, m.cy);
ctx.stroke();
if (o.shape === "arrow") {
ctx.fillStyle = o.fill;
ctx.beginPath();
ctx.moveTo(x1, m.cy);
ctx.lineTo(x1 - m.headLen, m.cy - m.headHalf);
ctx.lineTo(x1 - m.headLen, m.cy + m.headHalf);
ctx.closePath();
ctx.fill();
}
}
async function paintSticker(
ctx: CanvasRenderingContext2D,
o: StickerOverlay,
frame: PaintFrame,
env: RenderEnv
) {
const cx = o.x * frame.width;
const cy = o.y * frame.height;
const w = Math.max(1, o.w * frame.width);
if (!o.assetId) return;
if (o.lottie) {
const handle = await env.resolveLottie?.(o.assetId);
if (!handle) return;
const aspect = handle.width > 0 && handle.height > 0 ? handle.width / handle.height : 1;
const h = stickerHeight(o, frame, w, aspect);
ctx.drawImage(handle.seek(frame.t ?? 0), cx - w / 2, cy - h / 2, w, h);
return;
}
if (!env.resolveAsset) return;
const img = await env.resolveAsset(o.assetId);
if (!img) return;
const aspect = img.width > 0 && img.height > 0 ? img.width / img.height : 1;
const h = stickerHeight(o, frame, w, aspect);
ctx.drawImage(img.source, cx - w / 2, cy - h / 2, w, h);
}
/** A sticker's painted height in px: its stored height when a side grip set
* one, otherwise the width under the source's own aspect. */
function stickerHeight(o: StickerOverlay, frame: PaintFrame, w: number, aspect: number): number {
return o.h ? Math.max(1, o.h * frame.height) : w / aspect;
}
/** The CSS font shorthand a text element paints (and loads faces) with. */
export function textCssFont(overlay: TextOverlay, fpx: number, env: RenderEnv): string {
return `${overlay.italic ? "italic " : ""}${overlay.weight} ${fpx}px ${env.fontStack(overlay.font)}`;
}
/** Share of the frame width a line of type may take. The rest is the margin
* that keeps words off the edge of the picture. */
export const TEXT_SAFE_WIDTH = 0.88;
/** The room an element anchored at `x` has for a centered box: the safe width,
* narrowed when the anchor sits off-center so the box cannot reach past the
* near edge. An anchor pinned to an edge has no room at all, and text there is
* left whole — nothing a break could do would bring it back into the picture. */
export function textRoom(x: number, frameWidth: number): number {
const anchored = 2 * Math.min(Math.max(0, x), Math.max(0, 1 - x));
return Math.min(TEXT_SAFE_WIDTH, anchored) * frameWidth;
}
/** Explicit boxes wrap at their width; auto-width text stays within the frame.
* A line turned by its rotation runs across the frame at that angle, so its
* room is the run along it from the anchor: a column word at -90 has the
* frame's height, measured from its y. Without the frame's height, or upright,
* the room is across. */
export function textWrapRoom(
o: Pick<TextOverlay, "x" | "wrapWidth"> & { y?: number; rotation?: number },
frameWidth: number,
frameHeight?: number
): number {
if (o.wrapWidth && Number.isFinite(o.wrapWidth)) return Math.max(0.01, o.wrapWidth) * frameWidth;
const across = textRoom(o.x, frameWidth);
const a = ((o.rotation ?? 0) * Math.PI) / 180;
if (!frameHeight || !a || !Number.isFinite(a)) return across;
const cos = Math.abs(Math.cos(a));
const sin = Math.abs(Math.sin(a));
const down = textRoom(o.y ?? 0.5, frameHeight);
return Math.min(cos > 1e-6 ? across / cos : Infinity, sin > 1e-6 ? down / sin : Infinity);
}
/**
* Break text into lines that each fit `room`, keeping the author's own breaks.
*
* Every surface draws text from explicit lines and none of them reflows, so a
* line longer than the frame simply runs off it. This is where that is
* prevented, and the measurer is the caller's: the painter
* measures with the canvas it is about to draw on, the preview with the face
* the browser has loaded, and both break in the same places.
*
* A word too wide for the room keeps its own line whole.
*
* A line already inside the room is handed back exactly as written, so the
* spacing an author typed survives everywhere it fits.
*/
/**
* Break one token across lines, at the last character that still fits.
*
* Walks code points rather than code units, so a break never lands inside an
* emoji or a surrogate pair. A single character wider than the room is emitted
* on its own — there is nothing narrower to fall back to, and the alternative
* is a loop with no end.
*/
function breakToken(word: string, room: number, measure: (line: string) => number): string[] {
const parts: string[] = [];
let line = "";
for (const ch of Array.from(word)) {
const cand = line + ch;
if (line && measure(cand) > room) {
parts.push(line);
line = ch;
} else {
line = cand;
}
}
if (line) parts.push(line);
return parts;
}
export function wrapTextToRoom(
text: string,
room: number,
measure: (line: string) => number
): string {
if (!(room > 0)) return text;
const out = text.split("\n").map((source) => {
if (measure(source) <= room) return source;
const words = source.split(/\s+/).filter(Boolean);
if (words.length === 0) return "";
const lines: string[] = [];
let line = "";
for (const w of words) {
// A token with nowhere to break that is still too wide — a URL, a long
// compound, a hashtag. Every surface draws these lines as they are
// given, so a line left over the room is a line that runs off the frame
// in the preview and in the rendered file alike.
if (measure(w) > room) {
if (line) lines.push(line);
const parts = breakToken(w, room, measure);
lines.push(...parts.slice(0, -1));
line = parts[parts.length - 1] ?? "";
continue;
}
const cand = line ? `${line} ${w}` : w;
if (line && measure(cand) > room) {
lines.push(line);
line = w;
} else {
line = cand;
}
}
if (line) lines.push(line);
return lines.join("\n");
});
return out.join("\n");
}
/** The type a line is measured in: a title's own, or a face of its cycle. */
export type TextType = Pick<TextOverlay, "font" | "weight" | "italic" | "size" | "letterSpacing">;
/**
* A face of a title's font cycle, set on the title's own lines.
*
* A face is wider or narrower than the title's own type, and broken to the
* room in its own measure it would reflow: a one-line title in a wide face at
* 1.6× drops its last word onto a second line, over whatever sits above or
* below it. So the lines are the ones the title breaks into in its own type
* (`cycleOwn`), and where one of them is wider than the room in the face, the
* face is set smaller until the widest fits. Every painter calls this with
* its own measure — the canvas it draws on, the face the browser has loaded —
* so the preview, the canvas export and the ffmpeg frames set the same lines
* at the same size. Anything that is not a cycle's face comes back as it is.
*/
export function settleCycleFace<T extends Overlay>(
o: T,
room: number,
measure: (type: TextType, line: string) => number
): T {
if ((o.kind ?? "text") !== "text") return o;
const { cycleOwn: own, ...face } = o as TextOverlay;
if (!own) return o;
const text = wrapTextToRoom(face.text, room, (line) => measure(own, line));
const lines = text.split("\n");
let size = face.size;
// Type widens in step with its size, so one scale brings the widest line
// onto the room; the margin and a second pass take up what hinting rounds.
for (let pass = 0; pass < 3 && room > 0; pass++) {
const widest = Math.max(0, ...lines.map((line) => measure({ ...face, size }, line)));
if (widest <= room) break;
size *= (room / widest) * 0.999;
}
return { ...face, text, size } as unknown as T;
}
/** The canvas every face settles on, made once through the host's seam: a
* measure draws nothing, so one serves every frame and every title. */
let settleCtx: CanvasRenderingContext2D | null = null;
/** Settled lines and size by everything that decides them, oldest first. A
* handful of titles cycle at once, each through a few faces. */
const settledFaces = new Map<string, { text: string; size: number }>();
const SETTLED_FACES_MAX = 256;
/** Drop every settled face, for a host whose fonts just changed: a face
* measured in a fallback settles again in the real one. */
export function forgetSettledFaces(): void {
settledFaces.clear();
}
/** `settleCycleFace` measured the way the painter measures: on a canvas in
* the frame's pixels, with both faces resident first. Each face settles once
* per room and scale; a painted frame after that reuses it. */
async function settledFace(o: TextOverlay, frame: PaintFrame, env: RenderEnv): Promise<TextOverlay> {
const own = o.cycleOwn;
if (!own) return o;
const cssOf = (type: TextType) => textCssFont({ ...o, ...type }, type.size * frame.scale, env);
const room = textWrapRoom(o, frame.width, frame.height);
const key = `${room}|${frame.scale}|${cssOf(own)}|${own.letterSpacing ?? 0}|${cssOf(o)}|${o.letterSpacing ?? 0}|${o.text}`;
let hit = settledFaces.get(key);
if (!hit) {
await Promise.all([ensureFontLoaded(cssOf(own), o.text), ensureFontLoaded(cssOf(o), o.text)]);
const ctx = (settleCtx ??= newCanvas(env, 1, 1).getContext("2d")!);
const set = settleCycleFace(o, room, (type, line) => {
ctx.font = cssOf(type);
if ("letterSpacing" in ctx) ctx.letterSpacing = `${(type.letterSpacing ?? 0) * type.size * frame.scale}px`;
return ctx.measureText(line).width;
});
hit = { text: set.text, size: set.size };
// Bounded: the oldest settle goes first.
if (settledFaces.size >= SETTLED_FACES_MAX) settledFaces.delete(settledFaces.keys().next().value!);
settledFaces.set(key, hit);
}
const face: TextOverlay = { ...o, text: hit.text, size: hit.size };
delete face.cycleOwn;
return face;
}
async function paintText(
ctx: CanvasRenderingContext2D,
cycled: TextOverlay,
frame: PaintFrame,
env: RenderEnv,
) {
const overlay = await settledFace(cycled, frame, env);
const { width, scale } = frame;
const fpx = overlay.size * scale;
const cssFont = textCssFont(overlay, fpx, env);
// Faces must be resident before measureText, or the plate and alignment are
// measured against a fallback font and the burn-in drifts off the preview.
await ensureFontLoaded(cssFont, overlay.text);
ctx.font = cssFont;
if ("letterSpacing" in ctx) {
ctx.letterSpacing = `${(overlay.letterSpacing ?? 0) * fpx}px`;
}
ctx.textAlign = "center";
ctx.textBaseline = "alphabetic";
// Each line is drawn on its baseline, this far under the line's middle.
const drop = baselineDrop(ctx, fpx, env.emAscent?.(cssFont));
// Words stay in the picture: a line wider than the room its anchor leaves
// is broken here, measured on the very context that is about to draw it.
const lines = wrapTextToRoom(overlay.text, textWrapRoom(overlay, width, frame.height), (line) =>
ctx.measureText(line).width
).split("\n");
const lineH = fpx * (overlay.lineHeight ?? LINE_HEIGHT);
const totalH = lines.length * lineH;
const cx = overlay.x * width;
const cy = overlay.y * frame.height;
// 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<string, string>();
const sizeKey = (mult: number) => Math.round(mult * 1000) / 1000;
// A word set in its own face (an emphasized caption word) measures and
// draws in that face; every other word in the line's.
const faceKey = (d?: WordDraw) =>
d && (d.font !== undefined || d.italic !== undefined || d.weight !== undefined)
? `${d.font ?? ""}|${d.italic === undefined ? "" : d.italic ? 1 : 0}|${d.weight ?? ""}`
: "";
const fontFor = (mult: number, d?: WordDraw) => {
const key = sizeKey(mult);
const face = faceKey(d);
const id = `${key}#${face}`;
let f = fonts.get(id);
if (!f) {
f =
key === 1 && !face
? cssFont
: textCssFont(
face && d
? {
...overlay,
font: d.font ?? overlay.font,
italic: d.italic ?? overlay.italic,
weight: d.weight ?? overlay.weight,
}
: overlay,
fpx * key,
env
);
fonts.set(id, f);
}
return f;
};
// Every size and face 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 wanted = new Set<string>();
for (const d of draws) {
wanted.add(fontFor(d.scale, d));
wanted.add(fontFor(d.layoutScale, d));
}
for (const f of wanted) {
if (f !== cssFont) await ensureFontLoaded(f, 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, d?: WordDraw) => {
ctx.font = fontFor(mult, d);
drawSize = fpx * sizeKey(mult);
if ("letterSpacing" in ctx) ctx.letterSpacing = `${(overlay.letterSpacing ?? 0) * drawSize}px`;
};
const runs = !draws
? null
: (() => {
const spaceW = ctx.measureText(" ").width;
let k = 0;
const at = (w: string, mult: number, d?: WordDraw) => {
if (mult === 1 && !faceKey(d)) return ctx.measureText(w).width;
setSize(mult, d);
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), draws[from + j])
);
const drawn = words.map((w, j) =>
at(w, sizeKey(draws[from + j]?.scale ?? 1), draws[from + j])
);
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 = overlay.wrapWidth ? textWrapRoom(overlay, width) : Math.max(...widthsOf, 1);
// A textured title cuts its grain out of the type, so its plate goes in
// behind the finished letters instead of under them.
const texture = overlay.texture;
const surface = { owner: env, make: (w: number, h: number) => newCanvas(env, w, h) };
const paintPlate = () => {
if (!overlay.plate) {
return;
}
const padX = PLATE_PAD_X * fpx;
const padY = PLATE_PAD_Y * fpx;
const r = (overlay.plateRadius ?? PLATE_RADIUS) * fpx;
const w = maxW + padX * 2;
const h = totalH + padY * 2;
ctx.save();
if (texture) {
ctx.globalCompositeOperation = "destination-over";
ctx.shadowColor = "transparent";
}
ctx.fillStyle = plateFill(overlay);
ctx.beginPath();
ctx.roundRect(cx - w / 2, cy - h / 2, w, h, r);
ctx.fill();
ctx.restore();
};
if (!texture) {
paintPlate();
}
const shadow = resolveShadow(overlay.shadow);
if (shadow) {
ctx.shadowColor = shadow.color;
ctx.shadowBlur = shadow.blur * scale;
ctx.shadowOffsetY = shadow.offsetY * scale;
}
// Outline behind the fill: stroke first, then fill over it — the same order
// the DOM pair (-webkit-text-stroke + paint-order: stroke fill) paints.
const strokeW = (overlay.stroke?.width ?? 0) * fpx;
// `on` is where the type lands: the frame, or a streaking letter's own
// picture.
const drawText = (text: string, x: number, y: number, fill: string = overlay.color, on = ctx) => {
if (overlay.stroke && strokeW > 0) {
on.lineJoin = "round";
// In em of whatever size is set, so a resized word wears the same
// outline weight as the words beside it.
on.lineWidth = (strokeW / fpx) * drawSize * 2; // half of a centered stroke shows behind the fill
on.strokeStyle = overlay.stroke.color;
on.strokeText(text, x, y);
}
on.fillStyle = fill;
on.fillText(text, x, y);
};
// A glitching letter's channel copies: the same outline and fill in one
// tint, so a hollow title tears into hollow copies.
const drawTinted = (text: string, x: number, y: number, tint: string, on = ctx) => {
if (overlay.stroke && strokeW > 0) {
on.lineJoin = "round";
on.lineWidth = (strokeW / fpx) * drawSize * 2;
on.strokeStyle = tint;
on.strokeText(text, x, y);
}
if (!isInkless(overlay.color)) {
on.fillStyle = tint;
on.fillText(text, x, y);
}
};
// Line alignment inside the block; the block stays centered on (x, y).
const align = overlay.align ?? "center";
const lineX = (i: number) =>
align === "center"
? cx
: align === "left"
? cx - maxW / 2 + widthsOf[i] / 2
: cx + maxW / 2 - widthsOf[i] / 2;
const phase = frame.phase;
// Typing draws the typed characters where the whole text lays them out.
// Each line's first character index counts a break as a turn, so a typed
// count reads the same here as in the glyph loop. "AB\nCD" typed 4 shows
// "AB" and "C".
const typed = phase?.typed;
const lineStart: number[] = [];
lines.reduce((at, l) => {
lineStart.push(at);
return at + [...l].length + 1;
}, 0);
const shownIn = (i: number) => (typed === undefined ? Infinity : Math.max(0, typed - lineStart[i]));
// The line the typing stands on: the last one it has reached.
const typingLine =
typed === undefined ? lines.length - 1 : Math.max(0, lineStart.filter((s) => s <= typed).length - 1);
// The typing bar: just past the last character drawn, on its line, as
// tall as the type, centered where the DOM's vertical-align: middle puts
// it — half an x-height over the baseline. No shadow, so it reads the same
// as the preview's bar.
const caretColor = phase?.caret ? (typeCaret(overlay.anim)?.color ?? overlay.color) : null;
const alphaOf = ctx.globalAlpha;
// A bar after a typed letter hugs its ink: the tracking a browser counts
// after a run's last letter (skia leaves it out) comes back off `right`.
const drawCaret = (right: number, line = lines.length - 1, hug = false) => {
if (!caretColor) return;
const y = cy - totalH / 2 + lineH * (line + 0.5);
ctx.save();
ctx.font = cssFont;
if (hug && "letterSpacing" in ctx) {
const track = (overlay.letterSpacing ?? 0) * fpx;
right -= track - (ctx.measureText("II").width - 2 * ctx.measureText("I").width);
}
const xh = ctx.measureText("x").actualBoundingBoxAscent;
const off = Number.isFinite(xh) ? drop - xh / 2 : 0;
ctx.shadowColor = "transparent";
ctx.globalAlpha = alphaOf;
ctx.fillStyle = caretColor;
const h = CARET_HEIGHT_EM * fpx;
ctx.fillRect(right + CARET_GAP_EM * fpx, y + off - h / 2, Math.max(2 * scale, CARET_WIDTH_EM * fpx), h);
ctx.restore();
};
// A streaking letter's two scratches: its picture, and the smear the taps
// add up in. Made on the first streak and reused for every letter after.
let glyphPic: HTMLCanvasElement | null = null;
let glyphSmear: HTMLCanvasElement | null = null;
const smearGlyph = (
streak: { x: number; y: number },
placed: DOMMatrix,
w: number,
paint: (on: CanvasRenderingContext2D) => void
) => {
// The streak in the target's own pixels.
const sx = (placed.a * streak.x + placed.c * streak.y) * scale;
const sy = (placed.b * streak.x + placed.d * streak.y) * scale;
// Room for the letter at any turn or stretch it is drawn at, its outline
// and its shadow.
const shadowPad = shadow ? (shadow.blur + Math.abs(shadow.offsetY)) * scale : 0;
const zoom = Math.max(Math.hypot(placed.a, placed.b), Math.hypot(placed.c, placed.d));
const half = Math.ceil((Math.max(w, lineH) * 1.5 + strokeW + shadowPad + 4) * zoom);
const pw = 2 * half;
const mw = pw + Math.ceil(Math.abs(sx));
const mh = pw + Math.ceil(Math.abs(sy));
glyphPic ??= newCanvas(env, pw, pw);
glyphSmear ??= newCanvas(env, mw, mh);
if (glyphPic.width !== pw || glyphPic.height !== pw) {
glyphPic.width = pw;
glyphPic.height = pw;
}
if (glyphSmear.width < mw || glyphSmear.height < mh) {
glyphSmear.width = Math.max(glyphSmear.width, mw);
glyphSmear.height = Math.max(glyphSmear.height, mh);
}
// The letter, posed as the frame would pose it, at the picture's middle.
const pic = glyphPic.getContext("2d")!;
pic.setTransform(1, 0, 0, 1, 0, 0);
pic.clearRect(0, 0, pw, pw);
pic.font = ctx.font;
if ("letterSpacing" in pic) pic.letterSpacing = (ctx as CanvasRenderingContext2D & { letterSpacing: string }).letterSpacing;
pic.textAlign = ctx.textAlign;
pic.textBaseline = ctx.textBaseline;
pic.filter = ctx.filter;
pic.shadowColor = ctx.shadowColor;
pic.shadowBlur = ctx.shadowBlur;
pic.shadowOffsetY = ctx.shadowOffsetY;
const m = ctx.getTransform();
// Turn and stretch carry over; the frame's own placement does not.
pic.setTransform(m.a, m.b, m.c, m.d, half, half);
paint(pic);
// The taps add up into the smear, so the streak averages the letter's
// positions the way the element's own streak does.
const smear = glyphSmear.getContext("2d")!;
smear.setTransform(1, 0, 0, 1, 0, 0);
smear.clearRect(0, 0, glyphSmear.width, glyphSmear.height);
drawStreak(smear, glyphPic, (mw - pw) / 2, (mh - pw) / 2, {
streakX: sx,
streakY: sy,
taps: streakTaps(Math.hypot(streak.x, streak.y)),
});
// Back at the letter's place, untransformed: the picture already wears
// its turn and stretch.
ctx.save();
ctx.setTransform(1, 0, 0, 1, 0, 0);
ctx.filter = "none";
ctx.shadowColor = "transparent";
ctx.drawImage(glyphSmear, 0, 0, mw, mh, placed.e - mw / 2, placed.f - mh / 2, mw, mh);
ctx.restore();
};
if ((phase && hasGlyphMotion(phase)) || (texture && !draws)) {
// A per-glyph ramp or loop draws character by character, each at its own
// place in the motion. The index counts through the whole element, line
// breaks included, which is exactly what the DOM preview counts. A
// texture draws the same way, so each letter wears its own grain.
const total = Math.max(1, [...overlay.text].length);
const alpha0 = ctx.globalAlpha;
let gi = 0;
let caretRight = cx;
let hug = false;
lines.forEach((line, i) => {
const y = cy - totalH / 2 + lineH * (i + 0.5);
// Characters drawn one by one lose the kerning between them, so the run
// is centered on what it actually measures — the DOM's inline boxes
// land in the same place.
const chars = [...line];
const widths = chars.map((ch) => ctx.measureText(ch).width);
let x = lineX(i) - widths.reduce((a, b) => a + b, 0) / 2;
// The bar waits at the head of the line the typing has reached.
if (i === typingLine) {
caretRight = x;
}
chars.forEach((ch, ci) => {
const w = widths[ci];
const shown = typed === undefined || gi < typed;
const g = glyphStateAt(phase ?? {}, gi, total);
gi++;
if (shown && i === typingLine) {
caretRight = x + w;
hug = true;
}
if (shown && ch !== " " && g.alpha > 0.001) {
ctx.save();
ctx.globalAlpha = alpha0 * Math.min(1, Math.max(0, g.alpha));
ctx.translate(x + w / 2 + g.dx * scale, y + g.dy * scale);
// Where the letter sits before its own turn and stretch: its streak
// runs in this space, since the move is an offset, not a turn.
const placed = g.streak ? ctx.getTransform() : null;
if (g.rotate) ctx.rotate((g.rotate * Math.PI) / 180);
ctx.scale(g.sx, g.sy);
if (g.blur && "filter" in ctx) {
// A letter's own defocus stacks on whatever the element wears.
const own = ctx.filter && ctx.filter !== "none" ? `${ctx.filter} ` : "";
ctx.filter = `${own}blur(${(g.blur * scale).toFixed(2)}px)`;
}
if (placed && g.streak && !g.roll) {
// A letter in flight under motion blur: painted once into its own
// picture, smeared along its streak, then laid down whole.
smearGlyph(g.streak, placed, w, (on) => {
if (g.split) {
const off = g.split * scale;
drawTinted(ch, -off, drop, SPLIT_RED, on);
drawTinted(ch, off, drop, SPLIT_CYAN, on);
}
drawText(ch, 0, drop, overlay.color, on);
});
ctx.restore();
x += w;
return;
}
if (g.split) {
const off = g.split * scale;
drawTinted(ch, -off, drop, SPLIT_RED);
drawTinted(ch, off, drop, SPLIT_CYAN);
}
if (g.roll) {
// A rolling reel shows through its own band only — the line, or
// the band its edge sets; sideways it stays open, so a wide
// filler is not cut to the slot.
const em = fpx / lineH;
const band = reelBand(g.reel, em) * lineH;
ctx.beginPath();
ctx.rect(-w * 3, -band, w * 6, band * 2);
ctx.clip();
const a = ctx.globalAlpha;
for (const r of slotReel(ch, gi - 1, g.roll, slotSeed(overlay.text), g.reel, em)) {
ctx.globalAlpha = a * r.alpha;
drawText(r.ch, 0, r.y * lineH + drop);
}
} else {
drawText(ch, 0, drop);
}
if (texture) {
cutTexture(ctx, texture, surface, -w / 2, -lineH / 2, w, lineH);
}
ctx.restore();
}
x += w;
});
gi++; // the line break takes a turn too
});
paintPlate();
drawCaret(caretRight, typingLine, hug);
return;
}
// 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) {
let caretRight = lineX(typingLine) + widthsOf[typingLine] / 2;
lines.forEach((line, i) => {
const y = cy - totalH / 2 + lineH * (i + 0.5);
const chars = [...line];
const n = shownIn(i);
if (n >= chars.length) {
drawText(line, lineX(i), y + drop);
return;
}
// A line typing in draws its typed head from where the whole line
// starts, so each letter lands where it will stay.
const left = lineX(i) - widthsOf[i] / 2;
const head = chars.slice(0, n).join("");
if (i === typingLine) {
caretRight = left + ctx.measureText(head).width;
}
if (!head) {
return;
}
ctx.textAlign = "left";
drawText(head, left, y + drop);
ctx.textAlign = "center";
});
drawCaret(caretRight, typingLine, shownIn(typingLine) > 0);
return;
}
// A word drawn at another size or in its own face stands on the line's
// baseline, so its middle — where its marks and its turn are centred — sits
// its own face's drop above that baseline: read once per face, at the
// line's size, and scaled with the word.
const drops = new Map<string, number>();
const dropOf = (d: WordDraw) => {
const face = faceKey(d);
if (!face) return drop;
let v = drops.get(face);
if (v === undefined) {
setSize(1, d);
v = baselineDrop(ctx, fpx, env.emAscent?.(fontFor(1, d)));
drops.set(face, v);
setSize(1);
}
return v;
};
const alpha0 = ctx.globalAlpha;
let k = 0;
let caretRight = cx - (runs[typingLine]?.lineW ?? 0) / 2;
let hug = false;
ctx.textAlign = "left";
runs.forEach((run, i) => {
const y = cy - totalH / 2 + lineH * (i + 0.5);
let x = cx - run.lineW / 2;
// Where each word starts in its line, in characters, for the typing count.
let from = 0;
const wordAt = run.words.map((w) => {
const s = lines[i].indexOf(w, from);
from = s + w.length;
return [...lines[i].slice(0, s)].length;
});
run.words.forEach((w, wi) => {
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));
// Typing shows a word's typed head from the word's own left edge.
const letters = [...w];
const typedIn = Math.min(letters.length, shownIn(i) - wordAt[wi]);
const shown = typedIn >= letters.length ? w : letters.slice(0, Math.max(0, typedIn)).join("");
// Centered in the room the layout left it.
const drawX = x + (width - run.drawn[wi]) / 2;
if (i === typingLine && shown) {
setSize(mult, d);
caretRight = drawX + (shown === w ? run.drawn[wi] : ctx.measureText(shown).width);
hug = true;
setSize(1);
}
// 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 && shown) {
// Every word draws on the line's baseline; a resized one has its
// middle lifted or dropped by exactly as much as sharing it asks for.
const size = fpx * mult;
const drawY = y + drop;
const mid = drawY - dropOf(d) * mult;
// 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);
}
setSize(mult, d);
const inkW = shown === w ? run.drawn[wi] : ctx.measureText(shown).width;
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,
inkW + pad * 2,
size + pad * 2,
0.18 * size
);
ctx.fill();
ctx.globalAlpha = alpha;
}
drawText(shown, drawX, drawY, d.color);
// A textured line in a word effect wears its grain word by word.
if (texture) {
cutTexture(ctx, texture, surface, drawX, mid - lineH / 2, inkW, lineH);
}
if (d.mark === "underline" && d.markAlpha) {
ctx.globalAlpha = alpha * d.markAlpha;
ctx.fillStyle = d.color;
ctx.fillRect(drawX, mid + size * 0.42, inkW, 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 += width + run.spaceW;
k++;
});
});
ctx.globalAlpha = alpha0;
ctx.textAlign = "center";
paintPlate();
drawCaret(caretRight, typingLine, hug);
}
/** Paint one element in frame coordinates with no element-level transform —
* the raw painter dispatch. Callers own rotation/opacity (renderElementPng)
* or the full animation transform (renderOverlayFrames). */
export async function paintElement(
ctx: CanvasRenderingContext2D,
overlay: Overlay,
frame: PaintFrame,
env: RenderEnv
): Promise<void> {
const kind = overlay.kind ?? "text";
if (kind === "effect") return; // effects filter the video; nothing to paint
const reveal = frame.phase?.reveal;
if (reveal !== undefined && reveal < 1) {
// A wipe uncovers the element from its left edge: clip to the uncovered
// share of its box and paint the whole thing behind it.
if (reveal <= 0) return;
const b = await measureElementBounds(overlay, frame, env, { pad: false });
ctx.save();
ctx.beginPath();
ctx.rect(b.cx - b.w / 2, b.cy - b.h / 2, b.w * reveal, b.h);
ctx.clip();
await paintElement(ctx, overlay, { ...frame, phase: { ...frame.phase, reveal: undefined } }, env);
ctx.restore();
return;
}
const erode = frame.phase?.erode;
if (erode !== undefined && erode > 0) {
// A disintegration paints the element inside its box, then cuts the
// eaten grain out of it — the box the DOM masks with the same tile.
if (erode >= 1) {
return;
}
const b = await measureElementBounds(overlay, frame, env, { pad: false });
const x = b.cx - b.w / 2;
const y = b.cy - b.h / 2;
ctx.save();
ctx.beginPath();
ctx.rect(x, y, b.w, b.h);
ctx.clip();
await paintElement(ctx, overlay, { ...frame, phase: { ...frame.phase, erode: undefined } }, env);
ctx.globalCompositeOperation = "destination-out";
ctx.globalAlpha = 1;
ctx.shadowColor = "transparent";
ctx.drawImage(erodeTile(erode, "holes", { owner: env, make: (w, h) => newCanvas(env, w, h) }), x, y, b.w, b.h);
ctx.restore();
return;
}
const plugin = elementPlugin(kind);
if (plugin) {
await plugin.paint(ctx, overlay, frame, env);
} else if (kind === "shape") {
paintShape(ctx, overlay as ShapeOverlay, frame);
} else if (kind === "sticker") {
await paintSticker(ctx, overlay as StickerOverlay, frame, env);
} else {
await paintText(ctx, overlay as TextOverlay, frame, env);
}
// A zap crackles over the finished element, inside its own box.
const zap = frame.phase?.zap;
if (zap && zap.amount > 0) {
paintZap(ctx, await measureElementBounds(overlay, frame, env, { pad: false }), zap, frame.scale);
}
}
/**
* Paint only an element's arcs over the whole of a canvas the caller owns,
* cleared first, under the element's pose — the preview's arc layer, laid
* over the element its DOM box draws.
*/
export async function paintZapInto(
canvas: HTMLCanvasElement,
overlay: Overlay,
env: RenderEnv,
phase: PaintPhase & { zap: ZapPhase }
): Promise<void> {
const { width, height } = canvas;
const scale = Math.min(width, height) / 1080;
const ctx = canvas.getContext("2d")!;
const frame: PaintFrame = { width, height, scale, phase };
ctx.setTransform(1, 0, 0, 1, 0, 0);
ctx.globalAlpha = 1;
ctx.clearRect(0, 0, width, height);
if (phase.pose) {
applyPaintPose(ctx, phase.pose, overlay, frame);
}
paintZap(ctx, await measureElementBounds(overlay, frame, env, { pad: false }), phase.zap, scale);
}
/** Draw everything after this under a dive's view. */
export function applyDiveView(
ctx: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D,
v: DiveView
): void {
ctx.translate(v.tx, v.ty);
ctx.scale(v.s, v.s);
ctx.translate(-v.fx, -v.fy);
}
// Place the element inside the output surface before the dive fills it.
function applyPaintPose(
ctx: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D,
pose: NonNullable<PaintPhase["pose"]>,
rest: { x: number; y: number },
frame: PaintFrame
): void {
ctx.translate(pose.x * frame.width + pose.dx * frame.scale, pose.y * frame.height + pose.dy * frame.scale);
ctx.rotate((pose.rotation * Math.PI) / 180);
ctx.scale(pose.scale * (pose.sx ?? 1), pose.scale * (pose.sy ?? 1));
ctx.translate(-rest.x * frame.width, -rest.y * frame.height);
}
/** Whether either edge of an element dives, so a renderer knows to measure
* the focus and give the flight the whole frame. */
export function divesAt(anim: OverlayAnim | undefined): boolean {
return !!edgeMotion(anim?.in)?.animate.dive || !!edgeMotion(anim?.out)?.animate.dive;
}
/** Measured foci, by look, newest last. A focus is three numbers, so the
* bound is a count. */
const diveFoci = new Map<string, Promise<DiveFocus>>();
const settledFoci = new Map<string, DiveFocus>();
const DIVE_FOCI_MAX = 64;
/** The longest side the focus raster is drawn at: enough to place the point
* within a couple of design px, small enough to measure in a frame. */
const DIVE_RASTER = 480;
/** What decides where a dive lands: the look, the layout and the edges'
* anchors, never the timing or the rest of the motion. */
function diveKey(o: Overlay, aspect: number): string {
const look: Record<string, unknown> = { ...o };
for (const k of ["id", "start", "end", "anim", "kf", "lane", "opacity", "rotation", "mask"]) delete look[k];
return JSON.stringify([look, Math.round(aspect * 1000), o.anim?.in?.anchor ?? null, o.anim?.out?.anchor ?? null]);
}
/**
* Where a dive flies into: the point of the element's ink that sits deepest
* inside it — on a title, inside its last letter — and how deep. Measured on
* the same painter that draws the element, at a 1080 short side, and kept per
* look, so every renderer and every frame reads one answer.
*/
export function measureDiveFocus(o: Overlay, aspect: number, env: RenderEnv): Promise<DiveFocus> {
const key = diveKey(o, aspect);
let hit = diveFoci.get(key);
if (hit) {
diveFoci.delete(key);
} else {
hit = findDiveFocus(o, aspect, env).then((f) => {
settledFoci.set(key, f);
return f;
});
}
diveFoci.set(key, hit);
while (diveFoci.size > DIVE_FOCI_MAX) {
const old = diveFoci.keys().next().value!;
diveFoci.delete(old);
settledFoci.delete(old);
}
return hit;
}
/** The measured focus if it has landed; otherwise starts measuring and says
* so with undefined. For renderers that draw synchronously. */
export function peekDiveFocus(o: Overlay, aspect: number, env: RenderEnv): DiveFocus | undefined {
const hit = settledFoci.get(diveKey(o, aspect));
if (!hit) void measureDiveFocus(o, aspect, env).catch(() => {});
return hit;
}
async function findDiveFocus(o: Overlay, aspect: number, env: RenderEnv): Promise<DiveFocus> {
const width = aspect >= 1 ? 1080 * aspect : 1080;
const height = aspect >= 1 ? 1080 : 1080 / aspect;
const frame: PaintFrame = { width, height, scale: 1 };
const isText = (o.kind ?? "text") === "text";
// The ink alone: a plate would pull the flight into the plate, a shadow
// blurs the edge the depth is measured from.
const el = {
...o,
rotation: undefined,
opacity: undefined,
mask: undefined,
anim: undefined,
kf: undefined,
...(isText ? { plate: false, shadow: false } : {}),
} as Overlay;
const b = await measureElementBounds(el, frame, env);
const q = Math.min(1, DIVE_RASTER / Math.max(b.w, b.h, 1));
const pad = 2;
const rw = Math.ceil(b.w * q) + pad * 2;
const rh = Math.ceil(b.h * q) + pad * 2;
const left = b.cx - b.w / 2;
const top = b.cy - b.h / 2;
const canvas = newCanvas(env, rw, rh);
const ctx = canvas.getContext("2d")!;
ctx.translate(pad, pad);
ctx.scale(q, q);
ctx.translate(-left, -top);
await paintElement(ctx, el, frame, env);
const pixels = ctx.getImageData(0, 0, rw, rh).data;
const depth = inkDepth(pixels, rw, rh);
// A title flies into its last letter; anything else into its deepest ink.
const box = isText ? await lastGlyphBox(el as TextOverlay, frame, env) : null;
const toRaster = (v: number, from: number) => (v - from) * q + pad;
const x0 = box ? Math.max(0, Math.floor(toRaster(box.x0, left))) : 0;
const x1 = box ? Math.min(rw, Math.ceil(toRaster(box.x1, left))) : rw;
const y0 = box ? Math.max(0, Math.floor(toRaster(box.y0, top))) : 0;
const y1 = box ? Math.min(rh, Math.ceil(toRaster(box.y1, top))) : rh;
let best = -1;
let bx = rw / 2;
let by = rh / 2;
const scan = (ax: number, bx1: number, ay: number, by1: number) => {
for (let y = ay; y < by1; y++)
for (let x = ax; x < bx1; x++) {
const d = depth[y * rw + x];
if (d > best) {
best = d;
bx = x;
by = y;
}
}
};
scan(x0, x1, y0, y1);
// A last letter with no ink of its own (a mark too thin to measure) falls
// back to the deepest ink anywhere.
if (best <= 0) scan(0, rw, 0, rh);
// Distances run center to center; the antialiased edge sits up to a pixel
// short of the last ink center, so that pixel is not counted.
const radius = (d: number) => Math.max(0.5, d - 1) / q;
// An anchor keeps its own point; the ink around it sets how far in it goes.
const pointAt = (a: { x: number; y: number }) => {
const x = Math.min(rw - 1, Math.max(0, Math.floor((a.x + b.cx - left) * q + pad)));
const y = Math.min(rh - 1, Math.max(0, Math.floor((a.y + b.cy - top) * q + pad)));
return { x: a.x, y: a.y, r: radius(depth[y * rw + x]) };
};
const anchorIn = o.anim?.in?.anchor;
const anchorOut = o.anim?.out?.anchor;
return {
x: (bx + 0.5 - pad) / q + left - b.cx,
y: (by + 0.5 - pad) / q + top - b.cy,
r: radius(best),
...(anchorIn || anchorOut
? { at: { ...(anchorIn ? { in: pointAt(anchorIn) } : {}), ...(anchorOut ? { out: pointAt(anchorOut) } : {}) } }
: {}),
};
}
/** Each pixel's distance to the nearest pixel outside the ink, in raster px:
* the exact Euclidean transform (Felzenszwalb–Huttenlocher), one pass down
* the columns and one along the rows. A dive's landing scale is read off this
* depth, so an estimate that runs long leaves a corner of the frame uncovered. */
function inkDepth(rgba: Uint8ClampedArray, w: number, h: number): Float32Array {
const INF = 1e20;
const n = Math.max(w, h);
const f = new Float64Array(n);
const d = new Float64Array(n);
const v = new Int32Array(n);
const z = new Float64Array(n + 1);
// The squared distance along one line, in place.
const line = (len: number) => {
let k = 0;
v[0] = 0;
z[0] = -INF;
z[1] = INF;
for (let q = 1; q < len; q++) {
let s = (f[q] + q * q - (f[v[k]] + v[k] * v[k])) / (2 * q - 2 * v[k]);
while (s <= z[k]) {
k--;
s = (f[q] + q * q - (f[v[k]] + v[k] * v[k])) / (2 * q - 2 * v[k]);
}
k++;
v[k] = q;
z[k] = s;
z[k + 1] = INF;
}
k = 0;
for (let q = 0; q < len; q++) {
while (z[k + 1] < q) k++;
d[q] = (q - v[k]) * (q - v[k]) + f[v[k]];
}
};
const sq = new Float64Array(w * h);
for (let i = 0; i < w * h; i++) sq[i] = rgba[i * 4 + 3] >= 128 ? INF : 0;
for (let x = 0; x < w; x++) {
for (let y = 0; y < h; y++) f[y] = sq[y * w + x];
line(h);
for (let y = 0; y < h; y++) sq[y * w + x] = d[y];
}
const out = new Float32Array(w * h);
for (let y = 0; y < h; y++) {
for (let x = 0; x < w; x++) f[x] = sq[y * w + x];
line(w);
for (let x = 0; x < w; x++) out[y * w + x] = Math.sqrt(d[x]);
}
return out;
}
/** The box the last drawn character of a title takes, in frame px — laid out
* the way `paintText` lays it out. */
async function lastGlyphBox(
cycled: TextOverlay,
frame: PaintFrame,
env: RenderEnv
): Promise<{ x0: number; x1: number; y0: number; y1: number } | null> {
const o = await settledFace(cycled, frame, env);
const fpx = o.size * frame.scale;
const cssFont = textCssFont(o, fpx, env);
await ensureFontLoaded(cssFont, o.text);
const ctx = newCanvas(env, 1, 1).getContext("2d")!;
ctx.font = cssFont;
if ("letterSpacing" in ctx) ctx.letterSpacing = `${(o.letterSpacing ?? 0) * fpx}px`;
const measure = (line: string) => ctx.measureText(line).width;
const lines = wrapTextToRoom(o.text, textWrapRoom(o, frame.width, frame.height), measure).split("\n");
const widths = lines.map(measure);
const maxW = o.wrapWidth ? textWrapRoom(o, frame.width) : Math.max(...widths, 1);
const lineH = fpx * (o.lineHeight ?? LINE_HEIGHT);
const cx = o.x * frame.width;
const cy = o.y * frame.height;
const align = o.align ?? "center";
let i = lines.length - 1;
while (i >= 0 && !lines[i].trim()) i--;
if (i < 0) return null;
const chars = [...lines[i].trimEnd()];
const center =
align === "center" ? cx : align === "left" ? cx - maxW / 2 + widths[i] / 2 : cx + maxW / 2 - widths[i] / 2;
const left = center - widths[i] / 2;
const y0 = cy - (lines.length * lineH) / 2 + lineH * i;
return {
x0: left + measure(chars.slice(0, -1).join("")),
x1: left + measure(chars.join("")),
y0,
y1: y0 + lineH,
};
}
function pngBlob(canvas: HTMLCanvasElement, env: RenderEnv): Promise<Blob> {
if (env.canvasToPngBlob) return env.canvasToPngBlob(canvas);
return new Promise((resolve, reject) =>
canvas.toBlob(
(b) => (b ? resolve(b) : reject(new Error("Could not render the overlay."))),
"image/png"
)
);
}
function newCanvas(env: RenderEnv, w: number, h: number): HTMLCanvasElement {
if (env.createCanvas) return env.createCanvas(Math.max(1, w), Math.max(1, h));
return kitCanvas(w, h);
}
/**
* Rasterize one element to a transparent full-frame PNG at the given output
* size. Rotation and opacity apply here, around the element center, so every
* painter draws unrotated in frame coordinates.
*/
export async function renderElementPng(
overlay: Overlay,
width: number,
height: number,
env: RenderEnv,
phase?: PaintPhase
): Promise<Blob> {
return pngBlob(await renderElementCanvas(overlay, width, height, env, phase), env);
}
/** The same picture left on its canvas, for a caller that draws it straight
* away — a picture redrawn every frame never pays a PNG round trip. */
export async function renderElementCanvas(
overlay: Overlay,
width: number,
height: number,
env: RenderEnv,
phase?: PaintPhase
): Promise<HTMLCanvasElement> {
const canvas = newCanvas(env, width, height);
await paintElementInto(canvas, overlay, env, phase);
return canvas;
}
/** The picture of an element that holds still: the full-frame picture with
* the element's own blur baked in, so a blurred element that never moves
* costs one picture for its whole span. */
export async function renderStillCanvas(
overlay: Overlay,
width: number,
height: number,
env: RenderEnv
): Promise<HTMLCanvasElement> {
const canvas = await renderElementCanvas(overlay, width, height, env);
const look = elementLook({ blur: overlay.blur }, Math.min(width, height) / 1080);
if (!look) return canvas;
const soft = newCanvas(env, width, height);
const ctx = soft.getContext("2d")!;
if ("filter" in ctx) ctx.filter = `blur(${look.blur.toFixed(2)}px)`;
ctx.drawImage(canvas, 0, 0);
canvas.width = canvas.height = 1;
return soft;
}
/** `renderStillCanvas` as a PNG. */
export async function renderStillPng(overlay: Overlay, width: number, height: number, env: RenderEnv): Promise<Blob> {
return pngBlob(await renderStillCanvas(overlay, width, height, env), env);
}
/** Paint one element over the whole of a canvas the caller owns, cleared
* first — the full-frame picture `renderElementPng` encodes, drawn into a
* surface that is reused frame after frame. */
export async function paintElementInto(
canvas: HTMLCanvasElement,
overlay: Overlay,
env: RenderEnv,
phase?: PaintPhase
): Promise<void> {
const { width, height } = canvas;
// Element sizes are design pixels with a 1080 short side, so scaling by the
// short side keeps them the same visual size in any aspect and resolution.
const scale = Math.min(width, height) / 1080;
const ctx = canvas.getContext("2d")!;
const frame: PaintFrame = { width, height, scale, phase };
ctx.setTransform(1, 0, 0, 1, 0, 0);
ctx.globalAlpha = 1;
ctx.clearRect(0, 0, width, height);
ctx.globalAlpha = overlay.opacity ?? 1;
if (phase?.pose) {
applyPaintPose(ctx, phase.pose, overlay, frame);
} else if (overlay.rotation) {
const cx = overlay.x * width;
const cy = overlay.y * height;
ctx.translate(cx, cy);
ctx.rotate((overlay.rotation * Math.PI) / 180);
ctx.translate(-cx, -cy);
}
if (phase?.dive) applyDiveView(ctx, phase.dive);
await paintElement(ctx, overlay, frame, env);
if (overlay.mask) {
// The mask is painted under the element's own transform, so it rotates
// and travels with the element. A keyframed mask routes through the
// animated frame sampler; here its resting (first) geometry applies.
applyMaskToCanvas(
ctx,
newCanvas(env, 1, 1),
overlay.mask,
0,
frame,
{ x: overlay.x, y: overlay.y },
ctx.getTransform()
);
}
}
/** An element's resting box in output pixels (center + size), rotation left
* to the caller. Conservative on purpose: it feeds the animated-region crop,
* where a few spare pixels beat a clipped shadow. `pad: false` drops that
* slack and returns the box the DOM lays out, which is what a wipe clips to.
*/
export async function measureElementBounds(
overlay: Overlay,
frame: PaintFrame,
env: RenderEnv,
opts?: { pad?: boolean }
): Promise<{ cx: number; cy: number; w: number; h: number }> {
const cx = overlay.x * frame.width;
const cy = overlay.y * frame.height;
const kind = overlay.kind ?? "text";
if (kind === "effect") return { cx, cy, w: 2, h: 2 };
if (kind === "shape") {
const s = overlay as ShapeOverlay;
const m = shapeMetrics(s, frame);
const lineLike = lineLikeShape(s.shape);
const w = m.w + m.strokeWidth * 2 + (lineLike ? m.thickness : 0);
const h = (lineLike ? Math.max(m.thickness, m.headHalf * 2) : m.h) + m.strokeWidth * 2;
if (opts?.pad === false) {
return { cx, cy, w, h };
}
// A shadow or glow spills past the box by the same reach text pads for.
const shadow = resolveShadow(s.shadow ?? false);
const shadowPad = shadow ? (shadow.blur + Math.abs(shadow.offsetY)) * frame.scale : 0;
return { cx, cy, w: w + shadowPad * 2, h: h + shadowPad * 2 };
}
if (kind === "sticker") {
const s = overlay as StickerOverlay;
const w = Math.max(1, s.w * frame.width);
if (s.lottie) {
const handle = s.assetId ? await env.resolveLottie?.(s.assetId) : null;
const aspect = handle && handle.width > 0 ? handle.width / handle.height : 1;
return { cx, cy, w, h: stickerHeight(s, frame, w, aspect) };
}
const img = s.assetId && env.resolveAsset ? await env.resolveAsset(s.assetId) : null;
const aspect = img && img.width > 0 && img.height > 0 ? img.width / img.height : 1;
return { cx, cy, w, h: stickerHeight(s, frame, w, aspect) };
}
const o = await settledFace(overlay as TextOverlay, frame, env);
const fpx = o.size * frame.scale;
const cssFont = textCssFont(o, fpx, env);
await ensureFontLoaded(cssFont, o.text);
const scratch = newCanvas(env, 1, 1);
const ctx = scratch.getContext("2d")!;
ctx.font = cssFont;
if ("letterSpacing" in ctx) ctx.letterSpacing = `${(o.letterSpacing ?? 0) * fpx}px`;
const lines = wrapTextToRoom(o.text, textWrapRoom(o, frame.width, frame.height), (line) =>
ctx.measureText(line).width
).split("\n");
const maxW = o.wrapWidth ? textWrapRoom(o, frame.width) : Math.max(...lines.map((l) => ctx.measureText(l).width), 1);
const lineH = fpx * (o.lineHeight ?? LINE_HEIGHT);
let w = maxW;
let h = lines.length * lineH;
if (o.plate) {
w += PLATE_PAD_X * fpx * 2;
h += PLATE_PAD_Y * fpx * 2;
}
if (opts?.pad === false) return { cx, cy, w, h };
// The typing bar stands past the last character, so the crop leaves it room.
if (typeCaret(o.anim)) w += ((CARET_GAP_EM + CARET_WIDTH_EM) * fpx + 2 * frame.scale) * 2;
const strokePad = (o.stroke?.width ?? 0) * fpx * 2;
const shadow = resolveShadow(o.shadow);
const shadowPad = shadow ? (shadow.blur + Math.abs(shadow.offsetY)) * frame.scale : 0;
// Ascenders/descenders overhang the em-box line grid a little.
return {
cx,
cy,
w: (w + strokePad * 2 + shadowPad * 2),
h: (h + fpx * 0.3 + strokePad * 2 + shadowPad * 2),
};
}
/** One window of an animated element, ready to be drawn under a per-frame
* transform. `overlay` is neutral — rotation and opacity belong to the pose,
* so a picture that baked them in would apply each twice — and a typewriter
* window carries the characters revealed so far. */
export interface AnimatedLayer {
overlay: Overlay;
start: number; // timeline seconds
end: number;
/** The pixel-level animation this window's picture is drawn at (a wipe's
* uncovered share, a per-glyph ramp's position); absent = at rest. */
phase?: PaintPhase;
/** The slots still in play for this window (a typed-out one has spent its
* ramp, so that slot is gone). */
anim: OverlayAnim;
}
/** Baked slices per second: one per output frame, matching the rate the frame
* sequences sample at. */
const TYPE_SLICE_FPS = 30;
/** `a`, every output frame time strictly between `a` and `b` (timeline
* seconds) at `fps`, and `b`: the cuts that give each frame of a stretch its
* own piece. */
function frameCuts(a: number, b: number, fps = TYPE_SLICE_FPS): number[] {
const slack = 1e-6;
const cuts = [a];
for (let k = Math.floor(a * fps) + 1; k / fps < b - slack; k++) {
if (k / fps > a + slack) {
cuts.push(k / fps);
}
}
cuts.push(b);
return cuts;
}
/**
* Split an animated element into the windows a canvas renderer draws.
*
* Continuous transforms — slides, fades, loops, a keyframed pose — stay one
* window whose picture is drawn under a per-frame transform. A style that
* changes the pixels themselves (typing, a wipe, per-glyph motion) can't ride
* one cached picture, so its ramp becomes one window per slice. This is the
* canvas-side twin of `renderOverlayFrames`: same split, one baked into
* pictures, the other handed to a compositor.
*/
export function planAnimatedLayers(o: Overlay, end: number): AnimatedLayer[] {
const anim: OverlayAnim = o.anim ?? {};
const dur = Math.max(0.1, o.end - o.start);
const isText = (o.kind ?? "text") === "text";
const baked = (slot: "in" | "out") => bakesPixels(anim[slot], isText);
const inS = anim.in ? Math.min(anim.in.seconds, dur) : 0;
const outS = anim.out ? Math.min(anim.out.seconds, Math.max(0, dur - inS)) : 0;
const out: AnimatedLayer[] = [];
// Word emphasis walks the line on the element's own clock, so every window
// below is cut at the word boundaries inside it and each piece stamped with
// the word it emphasizes — the same one-picture-per-word the caption
// burn-in has always used.
const words = overlayWords(o);
const push = (
overlay: Overlay,
from: number,
to: number,
animPart: OverlayAnim,
phase?: PaintPhase
) => {
const start = Math.max(o.start, from);
const stop = Math.min(end, to);
if (stop - start < 1e-3) return;
const add = (el: Overlay, a: number, b: number) =>
out.push({
overlay: { ...el, rotation: undefined, opacity: undefined } as Overlay,
start: a,
end: b,
anim: animPart,
phase,
});
// A font cycle changes the type at every step, so the windows are cut
// again at each face change and each piece drawn in its face.
const faces = fontCycleCuts(o, dur);
if (words || faces.length > 0) {
const spans = words ? wordSampleWindows((o as TextOverlay).text, words, dur) : [{ start: 0, end: dur }];
cutAtFaces(spans, faces).forEach((w) => {
const a = Math.max(start, o.start + w.start);
const b = Math.min(stop, o.start + w.end);
// Drawn at the middle of the span it stands for, which is where the
// picture it caches actually sits.
const mid = (w.start + w.end) / 2;
if (b - a >= 1e-3) add(withFontCycle(words ? applyWordDraw(overlay, mid, dur) : overlay, mid), a, b);
});
return;
}
add(overlay, start, stop);
};
// The typing bar blinks on the element's own clock, so a window it lights
// and darkens inside is cut where it turns, and each piece is drawn with the
// bar as it stands there.
const barred = isText && !!typeCaret(anim);
const toggles = barred ? caretToggles(anim, dur).map((t) => o.start + t) : [];
const lit = (phase: PaintPhase | undefined, from: number, to: number) =>
barred && caretOn(anim, (from + to) / 2 - o.start, dur) ? { ...phase, caret: true } : phase;
const pushLit = (from: number, to: number, animPart: OverlayAnim) => {
const cuts = [from, ...toggles.filter((t) => t > from && t < to), to];
for (let i = 0; i + 1 < cuts.length; i++)
push(o, cuts[i], cuts[i + 1], animPart, lit(undefined, cuts[i], cuts[i + 1]));
};
/** One window per slice. A typing slice is a run of frames that show one
* count, a counting slice is one step drawn at its middle; every other
* slice is one frame, drawn at its start, the moment the preview shows on
* that frame. The slot leaves the window's anim: its motion is in the
* picture already. */
const slices = (from: number, secs: number, slot: "in" | "out") => {
const edge = anim[slot]!;
// Which of the three bakes this is comes from the preset's own channels,
// so a composed animation is sliced by what it does.
const preset = edgeMotion(edge);
const types = !!preset?.animate.typed;
const counts = !!preset?.animate.counted;
const perGlyph = !!preset?.selector;
const text = isText ? (o as TextOverlay).text : "";
// A count never needs more slices than it has steps ("100 %" has 100).
const cap = counts ? Math.max(1, countStep(text, 1)) : Infinity;
const n = Math.max(1, Math.min(cap, Math.ceil(secs * TYPE_SLICE_FPS)));
const rest: OverlayAnim = { ...anim, [slot]: undefined };
// Typing reads the preset's own typed curve per output frame, drawn at
// the frame's middle, and frames that show the same count share one
// window: a composed typewriter's holds and jumps (the bar alone for a
// beat, three letters at once) land on the frames the preview shows them.
if (types) {
const frames = frameCuts(from, from + secs);
let runFrom = from;
let runCount = -1;
for (let i = 0; i + 1 < frames.length; i++) {
const q = ((frames[i] + frames[i + 1]) / 2 - from) / secs;
const p = slot === "out" ? 1 - q : q;
const count = typedChars(text, evalWhole(preset!, p, slot === "out").typed ?? p);
if (i > 0 && count !== runCount) {
push(o, runFrom, frames[i], rest, { ...lit(undefined, runFrom, frames[i]), typed: runCount });
runFrom = frames[i];
}
runCount = count;
}
push(o, runFrom, from + secs, rest, { ...lit(undefined, runFrom, from + secs), typed: runCount });
return;
}
// A counting ramp is cut into its steps, each drawn at its middle; any
// other ramp is cut where the output frames fall, each piece drawn at its
// own start, so a frame shows what the preview shows then.
const stepped = counts;
const cuts = stepped ? [...Array(n + 1).keys()].map((i) => from + (i / n) * secs) : frameCuts(from, from + secs);
for (let i = 0; i + 1 < cuts.length; i++) {
const at = cuts[i];
const to = cuts[i + 1];
const q = stepped ? (i + 0.5) / n : (at - from) / secs;
const p = slot === "out" ? 1 - q : q;
if (counts) {
// The count follows the preset's own curve, the way the evaluator
// reads it for the live preview.
const shown = evalWhole(preset!, p, slot === "out").counted ?? p;
push({ ...o, text: countText(text, shown) } as Overlay, at, to, rest, lit(undefined, at, to));
} else if (perGlyph) {
push(o, at, to, rest, lit({
glyphs: {
style: edge.style,
// The slot's own order and reach, as the preview plays them.
preset,
p,
exiting: slot === "out",
seconds: secs,
...(edge.stagger !== undefined ? { stagger: edge.stagger } : {}),
// Under motion blur each letter streaks along its own move.
...(o.motionBlur ? { exposure: (o.motionBlur * MOTION_BLUR_FRAME) / secs, shutter: o.motionBlur } : {}),
},
}, at, to));
} else if (preset?.animate.erode) {
// A disintegration eats the ink along the preset's own curve.
push(o, at, to, rest, lit({ erode: evalWhole(preset, p, slot === "out").erode ?? 0 }, at, to));
} else {
push(o, at, to, rest, lit({ reveal: p }, at, to));
}
}
};
if (inS > 1e-3) {
if (baked("in")) slices(o.start, inS, "in");
else pushLit(o.start, o.start + inS, anim);
}
pushLit(o.start + inS, o.start + dur - outS, anim);
if (outS > 1e-3) {
if (baked("out")) slices(o.start + dur - outS, outS, "out");
else pushLit(o.start + dur - outS, o.start + dur, anim);
}
return doodleWindows(o, zapWindows(o, out, anim, dur, isText));
}
/** A doodle deals a new mark on every beat, so every window is cut at the
* beats inside it and each piece drawn with its beat's mark. */
function doodleWindows(o: Overlay, layers: AnimatedLayer[]): AnimatedLayer[] {
if (o.kind !== "shape" || !dealsMarks(o.shape)) {
return layers;
}
return layers.flatMap((l) => {
const pieces: AnimatedLayer[] = [];
let at = l.start;
while (l.end - at > 1e-4) {
const beat = doodleBeat(at - o.start);
const next = Math.min(l.end, o.start + (beat + 1) / DOODLE_FPS);
pieces.push({ ...l, start: at, end: next, phase: { ...l.phase, doodle: beat } });
at = next;
}
return pieces;
});
}
/** A zap paints arcs inside the hit's window over whatever plays there — a
* ramp's slice, a fade, the hold — so every window crossing it is cut per
* frame inside it, each piece keeping its picture and adding its own deal of
* the arcs. */
function zapWindows(o: Overlay, layers: AnimatedLayer[], anim: OverlayAnim, dur: number, isText: boolean): AnimatedLayer[] {
const hit = hitZaps(anim) ? hitWindow(anim, dur) : null;
if (!hit) {
return layers;
}
const from = o.start + hit.start;
const to = o.start + hit.end;
return layers.flatMap((l) => {
const a = Math.max(l.start, from);
const b = Math.min(l.end, to);
if (b - a < 1e-3) {
return [l];
}
const pieces: AnimatedLayer[] = a > l.start ? [{ ...l, end: a }] : [];
const n = Math.max(1, Math.round((b - a) * TYPE_SLICE_FPS));
for (let i = 0; i < n; i++) {
const at = a + (i / n) * (b - a);
const next = a + ((i + 1) / n) * (b - a);
const tLocal = (at + next) / 2 - o.start;
const amount = evalOverlayAnim(anim, tLocal, dur, isText).zap ?? 0;
pieces.push({ ...l, start: at, end: next, ...(amount > 0 ? { phase: { ...l.phase, zap: { amount, seed: zapSeed(tLocal) } } } : {}) });
}
if (b < l.end) {
pieces.push({ ...l, start: b });
}
return pieces;
});
}
/** How many characters a typewriter at `progress` (0..1) has typed. */
export function typedChars(text: string, progress: number): number {
const n = [...text].length;
return Math.max(0, Math.min(n, Math.ceil(progress * n)));
}
/** The element as it paints at one moment, neutral — rotation and opacity
* belong to the pose: its words drawn as they stand, the typed share of its
* text, and the pixel-level phase of a wipe or a per-glyph move. `typed` says
* the typewriter is running. */
export function elementAtMoment(
overlay: Overlay,
tLocal: number,
ev: OverlayFrameState
): { el: Overlay; phase?: PaintPhase; typed: boolean } {
const dur = Math.max(0.1, overlay.end - overlay.start);
let el: Overlay = withFontCycle(
applyWordDraw({ ...overlay, rotation: undefined, opacity: undefined }, tLocal, dur),
tLocal
);
const typed = ev.textProgress !== undefined && (overlay.kind ?? "text") === "text";
const typedCount = typed ? typedChars((overlay as TextOverlay).text, ev.textProgress!) : undefined;
// A count draws every number in the text where its count stands.
if (ev.countProgress !== undefined && (overlay.kind ?? "text") === "text") {
el = { ...el, text: countText((el as TextOverlay).text, ev.countProgress) } as Overlay;
}
const marks = overlay.kind === "shape" && dealsMarks(overlay.shape);
const phase: PaintPhase | undefined =
ev.glyphs || ev.glyphLoop || ev.reveal !== undefined || ev.erode !== undefined || ev.zap || ev.caret || typed || marks
? {
...(marks ? { doodle: doodleBeat(tLocal) } : {}),
...(ev.glyphs ? { glyphs: ev.glyphs } : {}),
...(ev.glyphLoop ? { glyphLoop: ev.glyphLoop } : {}),
...(ev.reveal !== undefined ? { reveal: ev.reveal } : {}),
...(ev.erode !== undefined ? { erode: ev.erode } : {}),
...(ev.zap ? { zap: { amount: ev.zap, seed: zapSeed(tLocal) } } : {}),
...(ev.caret ? { caret: true } : {}),
...(typedCount !== undefined ? { typed: typedCount } : {}),
}
: undefined;
return { el, phase, typed };
}
/**
* Paint an element, neutral and at rest, into a canvas cropped to its inked
* box in a `width` × `height` frame, its shape mask applied. Returns where the
* crop's top-left sits in the frame. The preview's motion blur smears this
* picture: a few element-sized draws a frame where a frame-sized picture
* would cost the whole stage. `maskScratch` is the caller's own canvas for
* the mask pass, held across paints.
*/
export async function paintElementCrop(
canvas: HTMLCanvasElement,
el: Overlay,
width: number,
height: number,
env: RenderEnv,
opts: { t: number; phase?: PaintPhase; maskScratch: HTMLCanvasElement }
): Promise<{ x: number; y: number }> {
const scale = Math.min(width, height) / 1080;
const frame: PaintFrame = { width, height, scale, t: opts.t, phase: opts.phase };
const b = await measureElementBounds(el, frame, env);
// Letters on a per-glyph move and lifted words travel a little past the
// resting box.
const pad = Math.ceil(4 + 0.1 * Math.max(b.w, b.h) + ((el.kind ?? "text") === "text" ? 1.5 * (el as TextOverlay).size * scale : 0));
const x = Math.floor(b.cx - b.w / 2 - pad);
const y = Math.floor(b.cy - b.h / 2 - pad);
const w = Math.max(1, Math.ceil(b.w + 2 * pad));
const h = Math.max(1, Math.ceil(b.h + 2 * pad));
if (canvas.width !== w) canvas.width = w;
if (canvas.height !== h) canvas.height = h;
const ctx = canvas.getContext("2d")!;
ctx.setTransform(1, 0, 0, 1, 0, 0);
ctx.globalAlpha = 1;
ctx.clearRect(0, 0, w, h);
ctx.translate(-x, -y);
await paintElement(ctx, el, frame, env);
if (el.mask && el.mask.kind !== "subject") {
applyMaskToCanvas(ctx, opts.maskScratch, el.mask, opts.t, frame, { x: el.x, y: el.y }, ctx.getTransform());
}
return { x, y };
}
/** One animated element as a region-cropped frame sequence: unique pictures
* plus play entries (repeats reference the same picture, so a loop costs one
* cycle of pixels however long the element runs). Entries cover the
* element's [0, dur] exactly; the caller pads the timeline around it. */
export interface OverlayFrameSet {
/** Region top-left in output px, and its size. */
x: number;
y: number;
w: number;
h: number;
/** Unique region-sized pictures. */
images: Blob[];
/** Region-sized transparent filler for the ffconcat gaps. */
blank: Blob;
/** Play order: index into `images` + seconds on screen. */
entries: { image: number; duration: number }[];
}
/** How a sampled picture shows the typing bar. */
type BarLook = "lit" | "dark";
/**
* Sample an animated element into frames at `fps`: the In and Out windows
* frame by frame, the middle as one still (or one loop cycle, repeated by
* reference). Samples the same evalOverlayAnim the live preview applies.
*/
export async function renderOverlayFrames(
overlay: Overlay,
width: number,
height: number,
fps: number,
env: RenderEnv
): Promise<OverlayFrameSet> {
const scale = Math.min(width, height) / 1080;
const frame: PaintFrame = { width, height, scale };
const anim = overlay.anim;
const dur = Math.max(0.1, overlay.end - overlay.start);
const inS = anim?.in ? Math.min(anim.in.seconds, dur) : 0;
const outS = anim?.out ? Math.min(anim.out.seconds, Math.max(0, dur - inS)) : 0;
// A Lottie sticker's pixels change every frame on their own; its play-through
// acts as the middle segment's cycle even with no transform loop set.
const sticker = (overlay.kind ?? "text") === "sticker" ? (overlay as StickerOverlay) : null;
const lottieDur =
sticker?.lottie && sticker.assetId
? ((await env.resolveLottie?.(sticker.assetId))?.duration ?? null)
: null;
// The crop region: the resting box, grown for travel, scale overshoot,
// shadow spill, and — when anything rotates — the circumscribed square.
// A font cycle sets the title in other faces for a while, so the region
// holds the widest and tallest of them too.
let base = await measureElementBounds(overlay, frame, env);
for (const face of fontCycleVariants(overlay)) {
const b = await measureElementBounds(face, frame, env);
base = { ...base, w: Math.max(base.w, b.w), h: Math.max(base.h, b.h) };
}
// Read from the presets themselves, so a composed animation pads its crop
// by what it actually travels rather than by what its name suggests.
const edges = [anim?.in, anim?.out]
.map(edgeMotion)
.filter((p): p is NonNullable<typeof p> => !!p);
const edgeTravel = edges.reduce((max, p) => Math.max(max, presetExtent(p).travel), 0);
// A per-glyph ramp hands each character its share of the same tracks, so
// the preset's own reach already covers where the glyphs get to.
const loop = loopExtent(anim?.loop);
const move = moveExtent(anim?.move);
// 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;
// A slot reel set to show through a band wider than its line reaches past
// the line by up to that band, em of the type's own size.
const reelTravel =
(overlay.kind ?? "text") === "text"
? Math.max(0, ...edges.map((p) => p.reel?.band ?? 0)) * (overlay as TextOverlay).size * scale
: 0;
const travel = (edgeTravel + loop.travel + move.travel) * scale + wordTravel + reelTravel;
// 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 maxScale = 1.15 * extent.scale * move.scale * wordSwell(accent) * hitScale(anim);
// A key tilted about both axes swings the box's ends like a turn, never
// past its half diagonal.
const rotates =
!!overlay.rotation ||
loop.rotates ||
move.rotates ||
(keyed && sortedKeys(overlay.kf!).some((k) => !!k.rotation || (!!k.tiltX && !!k.tiltY)));
let halfW = (base.w * maxScale) / 2 + travel + 4;
let halfH = (base.h * maxScale) / 2 + travel + 4;
if (rotates) {
const r = (Math.hypot(base.w, base.h) * maxScale) / 2 + travel + 4;
halfW = r;
halfH = r;
}
// A dive flies into the element until it fills the frame, so its flight
// takes the whole frame.
const focus = divesAt(anim) ? await measureDiveFocus(overlay, width / height, env) : null;
// A camera can carry the element anywhere in the frame at any size, so its
// pictures take the whole frame too.
const filmed = hasCameraKeys(overlay.camera);
const whole = !!focus || filmed;
// Blur spills about three radii past the ink; a streak reaches half its
// longest length either side.
const blurs = [overlay.blur ?? 0, ...(overlay.kf ?? []).map((k) => k.blur ?? 0)];
const spill =
Math.min(ELEMENT_BLUR_MAX, Math.max(...blurs)) * 3 * scale +
(overlay.motionBlur ? (streakCap(overlay.motionBlur) / 2) * scale : 0);
halfW += spill;
halfH += spill;
const x0 = whole ? 0 : Math.max(0, Math.floor(extent.x0 * width - halfW));
const y0 = whole ? 0 : Math.max(0, Math.floor(extent.y0 * height - halfH));
const x1 = whole ? width : Math.min(width, Math.ceil(extent.x1 * width + halfW));
const y1 = whole ? height : Math.min(height, Math.ceil(extent.y1 * height + halfH));
const rw = Math.max(2, x1 - x0);
const rh = Math.max(2, y1 - y0);
const canvas = newCanvas(env, rw, rh);
const target = canvas.getContext("2d")!;
const maskScratch = overlay.mask ? newCanvas(env, 1, 1) : null;
// Blur and motion blur paint the posed element into a scratch first.
const fx = new ElementFx((w, h) => newCanvas(env, w, h));
// `bar` paints the typing bar lit or dark whatever `tLocal` says, so a
// cycle drawn once serves every blink it repeats under.
const drawAt = async (tLocal: number, bar?: BarLook): Promise<Blob> => {
target.setTransform(1, 0, 0, 1, 0, 0);
target.clearRect(0, 0, rw, rh);
const ev = evalOverlayFrame(overlay, tLocal, width / height);
if (bar) ev.caret = bar === "lit";
if (ev.opacity <= 0.001) return pngBlob(canvas, env); // fully transparent frame
// A tilt turns about the posed center, here in the crop's own px.
const center = { x: ev.x * width + ev.dx * scale - x0, y: ev.y * height + ev.dy * scale - y0 };
const ctx = fx.begin(target, rw, rh, elementLook(ev, scale, center)) as CanvasRenderingContext2D;
ctx.globalAlpha = ev.opacity;
ctx.translate(-x0, -y0);
// The pose places the element; the preset's travel rides on top of it.
applyPaintPose(ctx, ev, overlay, frame);
// A dive's view goes inside the pose, so the type is drawn as vectors at
// the size it is seen and stays sharp however far in the flight gets.
if (focus && ev.dive) applyDiveView(ctx, diveView(ev.dive, focus, ev, overlay, frame));
const { el, phase, typed } = elementAtMoment(overlay, tLocal, ev);
// Typing reveals characters; it must not also fade them.
if (typed) ctx.globalAlpha = poseAt(overlay, tLocal).opacity;
const maskTransform = ctx.getTransform();
await paintElement(ctx, el, { ...frame, t: tLocal, phase }, env);
if (overlay.mask && maskScratch) {
// Painted under the frame's element transform, so the mask rides the
// pose; its own keys evaluate at this frame's time.
applyMaskToCanvas(
ctx,
maskScratch,
overlay.mask,
tLocal,
frame,
{ x: overlay.x, y: overlay.y },
maskTransform
);
}
fx.end(target);
return pngBlob(canvas, env);
};
const images: Blob[] = [];
const entries: OverlayFrameSet["entries"] = [];
const push = async (t: number, duration: number) => {
images.push(await drawAt(t));
entries.push({ image: images.length - 1, duration });
};
// A stretch of the element [a, b), element seconds, cut where the output
// frames fall on the timeline, each piece drawn at its own start: the
// moment the preview shows on that frame.
const perFrame = async (a: number, b: number) => {
const cuts = frameCuts(overlay.start + a, overlay.start + b, fps);
for (let i = 0; i + 1 < cuts.length; i++) {
await push(cuts[i] - overlay.start, cuts[i + 1] - cuts[i]);
}
};
const period = loopPeriod(anim) ?? lottieDur;
const hit = hitWindow(anim, dur);
const toggles = (overlay.kind ?? "text") === "text" ? caretToggles(anim, dur) : [];
// A keyframed pose, a camera, a move, or a keyframed mask changes on its
// own schedule across the whole element, so there is no still middle and no cycle to
// repeat: sample the element frame by frame.
// A doodle deals a new mark every beat, the same.
const marks = overlay.kind === "shape" && dealsMarks(overlay.shape);
if (keyed || filmed || marks || anim?.move || isMaskAnimated(overlay.mask) || (accent && anim?.loop)) {
await perFrame(0, dur);
target.setTransform(1, 0, 0, 1, 0, 0);
target.clearRect(0, 0, rw, rh);
fx.dispose();
return { x: x0, y: y0, w: rw, h: rh, images, blank: await pngBlob(canvas, env), entries };
}
// Head ramp, frame by frame.
if (inS > 1e-3) {
await perFrame(0, inS);
}
const a0 = inS;
const b0 = dur - outS;
// Pictures the middle reuses, by what they show: a word span or a cycle
// frame with the bar lit or dark.
const kept = new Map<string, number>();
const keep = async (key: string, t: number, bar?: BarLook): Promise<number> => {
let image = kept.get(key);
if (image === undefined) {
images.push(await drawAt(t, bar));
image = images.length - 1;
kept.set(key, image);
}
return image;
};
// The moment a cycle frame is drawn at, moved by whole periods off the
// hit, so the cycle repeated around the press never carries it.
const calm = (t: number): number => {
if (!hit || !period) return t;
for (let u = t; u < b0; u += period) if (u < hit.start || u >= hit.end) return u;
return t;
};
// One stretch of the middle between the hit and the bar's turns, drawn as
// the middle draws when nothing interrupts it: one frame per word span,
// one cycle repeated by reference, or one still.
const fill = async (a: number, b: number, bar?: BarLook) => {
if (accent) {
const spans = wordSampleWindows((overlay as TextOverlay).text, accent, dur, fps)
.map((w, i) => ({ i, a: Math.max(a, w.start), b: Math.min(b, w.end) }))
.filter((w) => w.b - w.a > 1e-3);
if (spans.length === 0) {
entries.push({ image: await keep(`still:${bar}${cycleFaceTag(overlay, (a + b) / 2)}`, (a + b) / 2, bar), duration: b - a });
return;
}
// The last one absorbs the rounding, so the pieces sum to the stretch.
spans[0].a = a;
spans[spans.length - 1].b = b;
for (const w of spans) {
const mid = (w.a + w.b) / 2;
entries.push({ image: await keep(`word${w.i}:${bar}${cycleFaceTag(overlay, mid)}`, mid, bar), duration: w.b - w.a });
}
return;
}
if (period) {
// One cycle of pictures, repeated by reference, on the cycle's own
// clock from the middle's start.
const n = Math.max(2, Math.min(Math.round(period * fps), 180));
const cycleStep = period / n;
let t = a;
while (b - t > 1e-4) {
const j = Math.floor((t - a0) / cycleStep + 1e-6);
const next = Math.min(b, a0 + (j + 1) * cycleStep);
const image = await keep(`cycle${j % n}:${bar}${cycleFaceTag(overlay, t)}`, calm(a0 + (j % n) * cycleStep), bar);
entries.push({ image, duration: next - t });
t = next;
}
return;
}
entries.push({ image: await keep(`still:${bar}${cycleFaceTag(overlay, (a + b) / 2)}`, (a + b) / 2, bar), duration: b - a });
};
// A hit and a blinking bar change the middle at their own moments: it is
// cut there, the hit plays frame by frame, and every stretch between fills
// as an uninterrupted middle would.
if (b0 - a0 > 1e-3) {
const cuts = [a0, b0, ...toggles, ...fontCycleCuts(overlay, dur)];
if (hit) cuts.push(hit.start, hit.end);
const marks = [...new Set(cuts.filter((t) => t >= a0 && t <= b0))].sort((x, y) => x - y);
for (let i = 0; i + 1 < marks.length; i++) {
const a = marks[i];
const b = marks[i + 1];
if (b - a < 1e-4) continue;
if (hit && a >= hit.start - 1e-6 && b <= hit.end + 1e-6) {
await perFrame(a, b);
continue;
}
const on = caretOn(anim, (a + b) / 2, dur);
await fill(a, b, on === undefined ? undefined : on ? "lit" : "dark");
}
}
if (outS > 1e-3) {
await perFrame(dur - outS, dur);
}
target.setTransform(1, 0, 0, 1, 0, 0);
target.clearRect(0, 0, rw, rh);
fx.dispose();
const blank = await pngBlob(canvas, env);
return { x: x0, y: y0, w: rw, h: rh, images, blank, entries };
}