Skip to content

Open source CapCut alternative.

TypeScript
13.7 KB
Raw Blame
import { textRoom, wrapTextToRoom } from "@donkeycut/effects-kit";
import type { OverlayAnim, OverlayAnimStyle, TextWeight } from "@donkeycut/effects-kit";
import { measureLine, textFontOf } from "./textFit";
import type { TextLook } from "./textLooks";
import type { TextMoveId } from "./textMotion";
import type { FontId } from "./types";

/**
 * How a run of text is composed across the frame and across its own length.
 *
 * A look says what one line looks like. This says what a hundred of them look
 * like together: where each lands, which face carries it, how it arrives, and
 * which lines are the loud ones. Without it every line of a lyric video comes
 * out identical and dead center, and the only way to vary anything is to edit
 * each element afterwards one call at a time.
 *
 * Everything here is deterministic — index in, pose out — so the same run
 * composes the same way twice, and index 0 always reproduces the look's own
 * settings exactly.
 */

/** How loud a line is. The model decides this per line from the meaning of
 * the words; nothing here reads the text to guess. */
export type TextEmphasis = "whisper" | "normal" | "hero";

/** How far the run departs from a single repeated design.
 * - `none`: every line identical — the look, nothing else.
 * - `subtle`: lines move around the frame and change entrance; one typeface.
 * - `bold`: the look's whole ensemble — faces, tilts, palette, hero accents. */
export type TextVariation = "none" | "subtle" | "bold";

/** Where successive lines land relative to the look's own anchor. */
export type TextLayout =
  | "center"
  | "stack"
  | "alternate"
  | "corners"
  | "drift"
  | "scatter"
  | "ladder";

export const TEXT_LAYOUT_IDS: TextLayout[] = [
  "center",
  "stack",
  "alternate",
  "corners",
  "drift",
  "scatter",
  "ladder",
];

export const TEXT_VARIATION_IDS: TextVariation[] = ["none", "subtle", "bold"];
export const TEXT_EMPHASIS_IDS: TextEmphasis[] = ["whisper", "normal", "hero"];

/** One-line descriptions, so the tool schema and the skill teach the same
 * thing the composer does. */
export const TEXT_LAYOUT_NOTES: Record<TextLayout, string> = {
  center: "Every line on the look's anchor. Still, formal, karaoke.",
  stack: "Lines step up and down the middle column, so a phrase builds vertically.",
  alternate: "Lines swing left and right of center — call and response.",
  corners: "Lines walk the four corners of the safe area. Busy, poster-like.",
  drift: "A slow diagonal walk across the frame and back. Ballads, long holds.",
  scatter: "A fixed scatter around the frame that never lands twice in a row. Chaotic energy.",
  ladder: "Each line one rung lower than the last, then back to the top. Lists, countdowns, verses.",
};

/** The offsets a layout walks, in frame fractions from the look's anchor.
 * Entry 0 is always zero: a single line, and the first line of any run, sits
 * exactly where the look put it. */
const LAYOUT_STEPS: Record<TextLayout, { dx: number; dy: number }[]> = {
  center: [{ dx: 0, dy: 0 }],
  stack: [
    { dx: 0, dy: 0 },
    { dx: 0, dy: -0.19 },
    { dx: 0, dy: 0.19 },
    { dx: 0, dy: -0.1 },
    { dx: 0, dy: 0.1 },
  ],
  alternate: [
    { dx: 0, dy: 0 },
    { dx: -0.17, dy: -0.12 },
    { dx: 0.17, dy: 0.12 },
    { dx: -0.15, dy: 0.1 },
    { dx: 0.15, dy: -0.1 },
  ],
  corners: [
    { dx: 0, dy: 0 },
    { dx: -0.21, dy: -0.17 },
    { dx: 0.21, dy: -0.17 },
    { dx: 0.21, dy: 0.17 },
    { dx: -0.21, dy: 0.17 },
  ],
  drift: [
    { dx: 0, dy: 0 },
    { dx: 0.07, dy: 0.07 },
    { dx: 0.14, dy: 0.14 },
    { dx: 0.07, dy: 0.2 },
    { dx: -0.07, dy: 0.14 },
    { dx: -0.14, dy: 0.05 },
    { dx: -0.08, dy: -0.06 },
  ],
  scatter: [
    { dx: 0, dy: 0 },
    { dx: 0.2, dy: -0.15 },
    { dx: -0.18, dy: 0.14 },
    { dx: 0.13, dy: 0.19 },
    { dx: -0.21, dy: -0.12 },
    { dx: 0.05, dy: -0.2 },
    { dx: -0.09, dy: 0.21 },
    { dx: 0.22, dy: 0.04 },
  ],
  ladder: [
    { dx: 0, dy: 0 },
    { dx: 0.05, dy: 0.11 },
    { dx: 0.1, dy: 0.22 },
    { dx: -0.05, dy: -0.11 },
    { dx: -0.1, dy: -0.22 },
  ],
};

/** Tilts a bold run walks. Entry 0 is upright, so the first line never leans. */
const TILTS = [0, -6, 5, -4, 7, -3, 6, -7, 4, -5];

/** How much bigger or smaller than the look's size each emphasis runs. */
const EMPHASIS_SCALE: Record<TextEmphasis, number> = {
  whisper: 0.68,
  normal: 1,
  hero: 1.34,
};

/** One face in a look's ensemble. */
export interface TextFace {
  font: FontId;
  weight: TextWeight;
  /** Size multiplier against the look's own size — a condensed face carries a
   * bigger number than a wide one at the same optical weight. */
  scale?: number;
  italic?: boolean;
}

/** The rotas a look walks when a run asks for variation. Entry 0 of every
 * rota is the look's own setting, so a one-line run and the first line of a
 * long one are exactly what the look describes. */
export interface TextEnsemble {
  faces: TextFace[];
  /** Entrances, walked one per line. */
  motion: OverlayAnimStyle[];
  layout: TextLayout;
  /** Moves the run walks while each line HOLDS — see textMotion.ts.
   * Entrances say how a line arrives; these say what it does after. */
  moves: TextMoveId[];
  /** The move a hero line takes regardless of where the rota is. */
  heroMove?: TextMoveId;
  /** Line colors for a run with no cards behind it. */
  palette?: string[];
}

export interface ComposeLine {
  text: string;
  start: number;
  end: number;
  color?: string;
  size?: number;
  emphasis?: TextEmphasis;
  /** Verse, chorus, bridge — any label. Lines sharing a label compose as one
   * passage, and each new label starts the type and palette rotas somewhere
   * else, so a chorus does not look like the verse before it. */
  section?: string;
  font?: FontId;
  x?: number;
  y?: number;
  rotation?: number;
  inStyle?: OverlayAnimStyle;
  /** A named move for this line, overriding the look's rota. */
  move?: TextMoveId;
}

export interface ComposedLine {
  text: string;
  start: number;
  end: number;
  x: number;
  y: number;
  rotation: number;
  font: FontId;
  weight: TextWeight;
  italic: boolean;
  size: number;
  color: string;
  anim: OverlayAnim;
  move: TextMoveId | string;
  /** Which of the look's cards sits behind this line. */
  cardIndex: number;
}

const clampPos = (v: number) => Math.min(0.9, Math.max(0.1, v));
const round2 = (n: number) => Math.round(n * 100) / 100;
/** A line held for less than this cuts in and out: an entrance or exit ramp
 * starts at nothing, so on a label that runs a frame or a few (one per shot
 * of a fast cut) the ramp would be all there is and the words never show. */
export const TEXT_RAMP_MIN_SECONDS = 0.2;
const step = <T,>(arr: readonly T[], n: number): T => arr[((n % arr.length) + arr.length) % arr.length];

/** Comparison form of a line: letters and digits only. Two lines that read
 * the same are the same hook however they are punctuated. */
const normText = (t: string): string =>
  t
    .toLowerCase()
    .normalize("NFKD")
    .replace(/[^\p{L}\p{N}]/gu, "");

/**
 * A line broken and sized to the room it actually has.
 *
 * The look's size is a ceiling written for a wide frame at center; a vertical
 * cut, a long line, a wider face, or a line placed off to one side all get
 * breaks at word boundaries first and a smaller size only when breaking is not
 * enough. Every width here is measured on the face the line will be drawn in,
 * through the same seam the painter and the preview measure with, so a run
 * lands where the frame says it lands.
 */
export function fitLineToFrame(
  text: string,
  frame: { w: number; h: number },
  size: number,
  opts: {
    font: FontId;
    weight: TextWeight;
    italic?: boolean;
    lineHeight?: number;
    x?: number;
    maxLines?: number;
  }
): { text: string; size: number } {
  if (text.includes("\n")) return { text, size }; // the caller broke it themselves
  const room = textRoom(opts.x ?? 0.5, frame.w);
  const words = text.split(/\s+/).filter((w) => w.length > 0);
  if (words.length === 0 || !(room > 0)) return { text, size };
  const maxLines = opts.maxLines ?? 3;
  const lineH = opts.lineHeight ?? 1.25;
  const widthAt = (line: string, px: number) =>
    measureLine(line, textFontOf({ font: opts.font, weight: opts.weight, italic: opts.italic }, px), px);

  const layout = (px: number) => wrapTextToRoom(text, room, (line) => widthAt(line, px)).split("\n");
  let lines = layout(size);
  let fitted = size;
  // A single word wider than the room is the one break that cannot help, so
  // the size comes down until it fits.
  const widest = Math.max(...lines.map((l) => widthAt(l, size)), 1);
  if (widest > room) fitted = Math.floor((size * room) / widest);
  // Too many lines is a design failure the same way overflow is: the run
  // shrinks until the stack is the height the look asked for.
  if (lines.length > maxLines) fitted = Math.min(fitted, Math.floor(size * (maxLines / lines.length)));
  if (fitted < size) lines = layout(Math.max(16, fitted));
  const tall = lines.length * fitted * lineH;
  if (tall > frame.h * 0.8) fitted = Math.floor((frame.h * 0.8) / (lines.length * lineH));
  const px = Math.max(16, Math.min(size, fitted));
  return { text: layout(px).join("\n"), size: px };
}

/**
 * Compose a run: every line's place in the frame, its face, its size, its
 * tilt and how it arrives.
 *
 * The rotas are walked by index, so the design moves whether or not the
 * caller said anything about a given line, and any field the caller did name
 * wins outright.
 */
export function composeTextRun(
  lines: ComposeLine[],
  look: TextLook,
  opts: {
    variation: TextVariation;
    layout?: TextLayout;
    frame: { w: number; h: number };
    /** The color cards the run is cycling; empty = the words sit on the
     * frame and the palette is free to carry them. */
    cards: string[];
  }
): ComposedLine[] {
  const { variation, frame } = opts;
  const cardCount = opts.cards.length;
  const onCards = look.text.onCards ?? [];
  const ens = look.ensemble;
  const layout = opts.layout ?? (variation === "none" ? "center" : ens?.layout ?? "center");
  const steps = LAYOUT_STEPS[layout] ?? LAYOUT_STEPS.center;
  const faces: TextFace[] =
    variation === "bold" && ens?.faces.length
      ? ens.faces
      : [{ font: look.text.font, weight: look.text.weight, italic: look.text.italic }];
  const motions: OverlayAnimStyle[] =
    variation === "none" || !ens?.motion.length
      ? [look.motion.in?.style ?? "fade"]
      : ens.motion;
  const moves: TextMoveId[] =
    variation === "none" || !ens?.moves.length ? ["none"] : ens.moves;
  const palette =
    variation === "bold" && cardCount === 0 && ens?.palette?.length
      ? [look.text.color, ...ens.palette]
      : [look.text.color];

  // Sections in the order they first appear, so the rotas can start a new
  // passage somewhere the last one did not sit.
  const sectionOrder: string[] = [];
  for (const l of lines) {
    const s = l.section;
    if (s && !sectionOrder.includes(s)) sectionOrder.push(s);
  }

  const seen = new Map<string, number>();

  return lines.map((line, i) => {
    const sec = line.section ? sectionOrder.indexOf(line.section) : 0;
    const emphasis = line.emphasis ?? "normal";

    // A hook that comes round again steps up rather than repeating flat.
    const key = normText(line.text);
    const repeats = key ? seen.get(key) ?? 0 : 0;
    if (key) seen.set(key, repeats + 1);
    const repeatBoost = variation === "none" ? 1 : 1 + Math.min(repeats, 3) * 0.09;

    const place = variation === "none" ? { dx: 0, dy: 0 } : step(steps, i);
    const x = line.x ?? clampPos(look.text.x + place.dx);
    const y = line.y ?? clampPos(look.text.y + place.dy);

    // Faces change per phrase pair; a new face every single line reads as
    // noise even in a ransom-note look.
    const face = step(faces, Math.floor(i / 2) + sec);
    const font = line.font ?? face.font;
    const tilt = line.rotation ?? (variation === "bold" ? step(TILTS, i + sec) : 0);

    const base = (line.size ?? look.text.size) * (line.size ? 1 : face.scale ?? 1);
    const wanted = Math.round(base * EMPHASIS_SCALE[emphasis] * repeatBoost);
    // Measured on the face this line is actually carried by, so a line that
    // takes the ensemble's wider typeface breaks where that face runs out of
    // room.
    const fit = fitLineToFrame(line.text, frame, wanted, {
      font,
      weight: face.weight,
      italic: face.italic ?? false,
      lineHeight: look.text.lineHeight,
      x,
    });

    const inStyle = line.inStyle ?? step(motions, i + sec);
    const inSeconds = Math.min(look.motion.in?.seconds ?? 0.35, Math.max(0.12, (line.end - line.start) * 0.4));

    const cardIndex = cardCount > 0 ? i % cardCount : -1;
    const onCard = cardIndex >= 0 && onCards.length > 0 ? step(onCards, cardIndex) : undefined;

    // What the line does while it holds. A hero line takes the look's hero
    // move; everything else walks the rota, so no two neighbours move alike.
    const moveId =
      line.move ??
      (emphasis === "hero" ? ens?.heroMove ?? step(moves, i + sec) : step(moves, i + sec));
    const ramps = line.end - line.start >= TEXT_RAMP_MIN_SECONDS;
    const anim: OverlayAnim = {
      ...(ramps ? { in: { style: inStyle, seconds: round2(inSeconds) } } : {}),
      ...(ramps && look.motion.out ? { out: look.motion.out } : {}),
      ...(look.motion.loop
        ? { loop: { style: look.motion.loop.style, speed: look.motion.loop.speed ?? 1 } }
        : {}),
      ...(moveId && moveId !== "none" ? { move: { style: moveId, strength: 1 } } : {}),
    };

    return {
      text: fit.text,
      start: line.start,
      end: line.end,
      x,
      y,
      rotation: tilt,
      font,
      weight: face.weight,
      italic: face.italic ?? false,
      size: fit.size,
      color: line.color ?? onCard ?? step(palette, i + sec),
      anim,
      move: moveId,
      cardIndex,
    };
  });
}