Skip to content

Open source CapCut alternative.

TypeScript

feat(site): read a title's letters coming in off a reference, soft, fading and out of step [rebuild]

David Le2bc29ae4302c
diff --git a/evals/cut-perf.latest-report.json b/evals/cut-perf.latest-report.json
index cdbdb186..d78ebf39 100644
--- a/evals/cut-perf.latest-report.json
+++ b/evals/cut-perf.latest-report.json
@@ -51,10 +51,10 @@
},
"frameMs": 16.7,
"scrub": {
- "p50": 15.8,
- "p95": 31.6,
- "mean": 18.41,
- "max": 31.8,
+ "p50": 15.7,
+ "p95": 32.7,
+ "mean": 18,
+ "max": 32.9,
"n": 41
},
"longTasks": {
@@ -64,7 +64,7 @@
"max": 0,
"n": 0
},
- "liveSamples": 56,
+ "liveSamples": 55,
"machine": "desktop"
},
{
@@ -74,17 +74,17 @@
"notes": [],
"late": {
"p50": 0,
- "p95": 1,
- "mean": 0.12,
+ "p95": 0,
+ "mean": 0.05,
"max": 1,
"n": 41
},
"frameMs": 16.7,
"scrub": {
- "p50": 15.4,
- "p95": 31.9,
- "mean": 17.07,
- "max": 47.3,
+ "p50": 15.5,
+ "p95": 16.8,
+ "mean": 16.14,
+ "max": 33.2,
"n": 41
},
"longTasks": {
@@ -94,7 +94,7 @@
"max": 0,
"n": 0
},
- "liveSamples": 74,
+ "liveSamples": 58,
"machine": "desktop"
},
{
@@ -111,10 +111,10 @@
},
"frameMs": 16.7,
"scrub": {
- "p50": 15.4,
- "p95": 16.3,
- "mean": 15.33,
- "max": 32.2,
+ "p50": 15.7,
+ "p95": 16.6,
+ "mean": 15.83,
+ "max": 32.4,
"n": 41
},
"longTasks": {
@@ -124,7 +124,7 @@
"max": 0,
"n": 0
},
- "liveSamples": 91,
+ "liveSamples": 75,
"machine": "desktop"
},
{
@@ -141,10 +141,10 @@
},
"frameMs": 16.7,
"scrub": {
- "p50": 15.1,
- "p95": 16.4,
- "mean": 14.9,
- "max": 31.9,
+ "p50": 15.3,
+ "p95": 16.7,
+ "mean": 15.5,
+ "max": 36.9,
"n": 81
},
"longTasks": {
@@ -171,10 +171,10 @@
},
"frameMs": 16.7,
"scrub": {
- "p50": 15.5,
- "p95": 32.2,
- "mean": 17.71,
- "max": 48.9,
+ "p50": 15.7,
+ "p95": 32.3,
+ "mean": 18.24,
+ "max": 49.2,
"n": 41
},
"longTasks": {
@@ -184,7 +184,7 @@
"max": 0,
"n": 0
},
- "liveSamples": 65,
+ "liveSamples": 56,
"machine": "desktop"
},
{
@@ -195,16 +195,16 @@
"late": {
"p50": 0,
"p95": 1,
- "mean": 0.17,
+ "mean": 0.2,
"max": 2,
"n": 41
},
"frameMs": 16.7,
"scrub": {
- "p50": 15.6,
- "p95": 32.3,
- "mean": 18.17,
- "max": 49.3,
+ "p50": 15.7,
+ "p95": 32.5,
+ "mean": 18.7,
+ "max": 48.6,
"n": 41
},
"longTasks": {
@@ -214,7 +214,7 @@
"max": 0,
"n": 0
},
- "liveSamples": 66,
+ "liveSamples": 47,
"machine": "desktop"
},
{
@@ -225,16 +225,16 @@
"late": {
"p50": 1,
"p95": 1,
- "mean": 0.93,
- "max": 1,
+ "mean": 0.98,
+ "max": 2,
"n": 41
},
"frameMs": 16.7,
"scrub": {
"p50": 31.9,
"p95": 32.7,
- "mean": 30.66,
- "max": 33.1,
+ "mean": 28.87,
+ "max": 48.8,
"n": 41
},
"longTasks": {
@@ -326,13 +326,13 @@
"pass": true,
"notes": [],
"drops": 0,
- "presented": 3243,
+ "presented": 3237,
"lag": {
"p50": 0.02,
"p95": 0.03,
"mean": 0.02,
"max": 0.03,
- "n": 3243
+ "n": 3237
},
"stallShare": 0,
"decay": {
@@ -363,13 +363,13 @@
"pass": true,
"notes": [],
"drops": 0,
- "presented": 223,
+ "presented": 221,
"lag": {
"p50": 0.02,
"p95": 0.03,
"mean": 0.02,
"max": 0.03,
- "n": 223
+ "n": 221
},
"stallShare": 0,
"decay": {
@@ -476,7 +476,7 @@
"drops": 0,
"presented": 3444,
"lag": {
- "p50": 0.02,
+ "p50": 0.01,
"p95": 0.03,
"mean": 0.02,
"max": 0.03,
@@ -492,11 +492,11 @@
"reported": 0.04
},
"longTasks": {
- "p50": 0,
- "p95": 0,
- "mean": 0,
- "max": 0,
- "n": 0
+ "p50": 73,
+ "p95": 73,
+ "mean": 73,
+ "max": 73,
+ "n": 1
},
"liveSamples": 10,
"liveSources": 1,
@@ -511,13 +511,13 @@
"pass": true,
"notes": [],
"drops": 0,
- "presented": 3437,
+ "presented": 3444,
"lag": {
"p50": 0.02,
"p95": 0.03,
- "mean": 0.01,
+ "mean": 0.02,
"max": 0.03,
- "n": 3437
+ "n": 3444
},
"stallShare": 0,
"decay": {
@@ -529,11 +529,11 @@
"reported": 0.04
},
"longTasks": {
- "p50": 73,
- "p95": 73,
- "mean": 73,
- "max": 73,
- "n": 1
+ "p50": 78,
+ "p95": 78,
+ "mean": 65.5,
+ "max": 78,
+ "n": 2
},
"liveSamples": 10,
"liveSources": 1,
@@ -551,7 +551,7 @@
"presented": 3444,
"lag": {
"p50": 0.01,
- "p95": 0.01,
+ "p95": 0.02,
"mean": 0.01,
"max": 0.02,
"n": 3444
@@ -585,13 +585,13 @@
"pass": true,
"notes": [],
"drops": 0,
- "presented": 3439,
+ "presented": 3444,
"lag": {
"p50": 0.02,
"p95": 0.03,
"mean": 0.02,
"max": 0.03,
- "n": 3439
+ "n": 3444
},
"stallShare": 0,
"decay": {
@@ -603,11 +603,11 @@
"reported": 0.04
},
"longTasks": {
- "p50": 100,
- "p95": 100,
- "mean": 100,
- "max": 100,
- "n": 1
+ "p50": 0,
+ "p95": 0,
+ "mean": 0,
+ "max": 0,
+ "n": 0
},
"liveSamples": 10,
"liveSources": 1,
@@ -622,13 +622,13 @@
"pass": true,
"notes": [],
"drops": 0,
- "presented": 1620,
+ "presented": 1621,
"lag": {
"p50": 0.02,
"p95": 0.03,
"mean": 0.02,
"max": 0.03,
- "n": 1620
+ "n": 1621
},
"stallShare": 0,
"decay": {
@@ -692,13 +692,13 @@
"pass": true,
"notes": [],
"drops": 3,
- "presented": 1095,
+ "presented": 1094,
"lag": {
"p50": 0.02,
- "p95": 0.02,
- "mean": 0.01,
+ "p95": 0.03,
+ "mean": 0.02,
"max": 0.03,
- "n": 1092
+ "n": 1091
},
"stallShare": 0,
"decay": {
@@ -710,10 +710,10 @@
"reported": 0.04
},
"longTasks": {
- "p50": 196,
- "p95": 196,
- "mean": 134,
- "max": 196,
+ "p50": 202,
+ "p95": 202,
+ "mean": 136.5,
+ "max": 202,
"n": 2
},
"liveSamples": 10,
diff --git a/site/packages/effects-kit/src/anim.ts b/site/packages/effects-kit/src/anim.ts
index 638e4fca..8789ce2d 100644
--- a/site/packages/effects-kit/src/anim.ts
+++ b/site/packages/effects-kit/src/anim.ts
@@ -29,7 +29,7 @@ import type { OverlayFontCycle } from "./fontCycle";
import type { MotionPose, MotionPreset } from "./motion/types";
import type { OverlayWords } from "./words";
import { splitScale } from "./stretch";
-import { capStreak } from "./camera";
+import { capStreak, ELEMENT_BLUR_MAX } from "./camera";
import { EASE_BEZIER, type EaseId } from "./ease";
export type OverlayAnimStyle =
@@ -128,6 +128,10 @@ export interface OverlayEdge {
* breaks included) in the order they go, an order read off a reference.
* Absent = the style's own, reading order for most. */
order?: EdgeOrder | number[];
+ /** With an order named as a list: when each of its characters starts, as a
+ * share of the hand-off (0 the first, 1 the last), for letters read off a
+ * reference that do not go evenly spaced. Absent = evenly spaced. */
+ orderAt?: number[];
/** How far the style travels from rest at its far end, design px (1080
* short side): a drop from high above the frame, a long slide. Absent =
* the style's own reach. */
@@ -136,15 +140,23 @@ export interface OverlayEdge {
* at a steady pace is linear, one that brakes into place an ease out. */
ease?: EaseId;
/** false: no fade — the element (each letter) stays solid the whole way
- * in or out, as a letter falling in from beyond the frame does. Absent =
- * the style's own. */
- fade?: boolean;
+ * in or out, as a letter falling in from beyond the frame does. A share of
+ * the move, 0..1: it fades up over that much of its move and holds solid
+ * after. Absent or true = the style's own. */
+ fade?: boolean | number;
+ /** Defocus at the far end, design px: each letter (the element) comes in
+ * that soft and sharpens as it lands, on the move's own curve — a letter
+ * falling out of focus. 0 takes a soft style's own blur away. Absent = the
+ * style's own. */
+ blur?: number;
}
export type EdgeOrder = "reading" | "shuffle";
export const EDGE_ORDERS: readonly EdgeOrder[] = ["reading", "shuffle"];
/** The farthest an edge's distance may send it, design px: past any frame. */
export const EDGE_DISTANCE_MAX = 4000;
+/** The softest an edge's far end may be, design px: an element's own blur cap. */
+export const EDGE_BLUR_MAX = ELEMENT_BLUR_MAX;
/** Seeds the shuffled order, so the same title always scatters the same way. */
const EDGE_SHUFFLE_SEED = 5;
@@ -227,7 +239,13 @@ export interface OverlayAnim {
export const edgeMotion = (slot: OverlayEdge | undefined): MotionPreset | undefined => {
if (!slot) return undefined;
const base = slot.preset ?? edgePreset(slot.style);
- if (!base || (slot.order === undefined && !(slot.distance! > 0) && !slot.ease && slot.fade !== false)) return base;
+ const plain =
+ slot.order === undefined &&
+ !(slot.distance! > 0) &&
+ !slot.ease &&
+ (slot.fade === undefined || slot.fade === true) &&
+ slot.blur === undefined;
+ if (!base || plain) return base;
let made = shaped.get(slot);
if (!made) {
made = shapeEdge(base, slot);
@@ -278,7 +296,8 @@ const shaped = new WeakMap<OverlayEdge, MotionPreset>();
function shapeEdge(base: MotionPreset, slot: OverlayEdge): MotionPreset {
let preset = base;
if (Array.isArray(slot.order) && base.selector) {
- preset = { ...preset, selector: { ...base.selector, randomize: false, sequence: slot.order } };
+ const timed = slot.orderAt?.length === slot.order.length ? { sequenceAt: slot.orderAt } : {};
+ preset = { ...preset, selector: { ...base.selector, randomize: false, sequence: slot.order, ...timed } };
} else if (slot.order && base.selector) {
const randomize = slot.order === "shuffle";
preset = {
@@ -299,13 +318,25 @@ function shapeEdge(base: MotionPreset, slot: OverlayEdge): MotionPreset {
...(preset.animateOut ? { animateOut: scaled(preset.animateOut) } : {}),
};
}
- if (slot.ease || slot.fade === false) {
+ if (slot.ease || slot.fade === false || typeof slot.fade === "number" || slot.blur !== undefined) {
const curve = slot.ease ? EASE_BEZIER[slot.ease] : undefined;
+ const soft = slot.blur === undefined ? undefined : Math.min(EDGE_BLUR_MAX, Math.max(0, slot.blur));
const reshaped = (props: MotionPreset["animate"]): MotionPreset["animate"] => {
const next = { ...props };
if (curve && next.position)
next.position = next.position.map((key, k, all) => (k < all.length - 1 ? { ...key, ease: curve } : key));
if (slot.fade === false) delete next.opacity;
+ // A fade over the first share of the move, solid after.
+ else if (typeof slot.fade === "number" && next.opacity)
+ next.opacity = [
+ { t: 0, v: 0, ease: EASE_BEZIER.linear },
+ { t: Math.min(1, Math.max(0.01, slot.fade)), v: 1 },
+ { t: 1, v: 1 },
+ ];
+ // The defocus clears on the move's own curve, so it is sharp as it lands.
+ if (soft === 0) delete next.blur;
+ else if (soft !== undefined)
+ next.blur = [{ t: 0, v: soft, ease: curve ?? next.position?.[0]?.ease ?? EASE_BEZIER.linear }, { t: 1, v: 0 }];
return next;
};
preset = {
diff --git a/site/packages/effects-kit/src/edgeShape.test.ts b/site/packages/effects-kit/src/edgeShape.test.ts
index f14f6f63..13222955 100644
--- a/site/packages/effects-kit/src/edgeShape.test.ts
+++ b/site/packages/effects-kit/src/edgeShape.test.ts
@@ -197,3 +197,59 @@ describe("an edge's ease and fade", () => {
expect(at({ ...edge, fade: undefined }, 0.05).alpha).toBeLessThan(0.2);
});
});
+
+describe("an edge's defocus", () => {
+ const at = (edge: OverlayEdge, t: number) => glyphStateAt(evalOverlayAnim({ in: edge }, t, 6, true), 0, 1);
+
+ test("a letter comes in that soft and sharpens as it lands", () => {
+ const edge: OverlayEdge = { style: "drop", seconds: 1, stagger: 0, distance: 600, blur: 18 };
+ expect(at(edge, 0).blur).toBeCloseTo(18, 0);
+ expect(at(edge, 0.5).blur!).toBeGreaterThan(0);
+ expect(at(edge, 0.5).blur!).toBeLessThan(18);
+ expect(at(edge, 1.2).blur ?? 0).toBe(0);
+ // Absent, a drop stays sharp.
+ expect(at({ ...edge, blur: undefined }, 0).blur ?? 0).toBe(0);
+ });
+
+ test("0 takes a soft style's own blur away", () => {
+ expect(at({ style: "blur", seconds: 1, stagger: 0 }, 0).blur!).toBeGreaterThan(0);
+ expect(at({ style: "blur", seconds: 1, stagger: 0, blur: 0 }, 0).blur ?? 0).toBe(0);
+ });
+
+ test("the crop pads for it and the export slices carry it", async () => {
+ const edge: OverlayEdge = { style: "drop", seconds: 2, stagger: 0.5, distance: 500, blur: 30 };
+ expect(presetExtent(edgeMotion(edge)!).travel).toBeGreaterThanOrEqual(500 + 60);
+ const { planAnimatedLayers } = await import("./render");
+ const o = { id: "t", kind: "text", text: TEXT, start: 0, end: 6, x: 0.5, y: 0.5, size: 200, color: "#ff0000", font: "bebas", anim: { in: edge } };
+ const mid = planAnimatedLayers(o as never, 6).find((l) => l.phase?.glyphs && l.start >= 0.5)!;
+ const live = evalOverlayFrame(o as never, mid.start, 16 / 9);
+ for (let i = 0; i < N; i++) expect(glyphStateAt(mid.phase!, i, N).blur ?? 0).toBeCloseTo(glyphStateAt(live, i, N).blur ?? 0, 3);
+ });
+});
+
+describe("an edge's fade length", () => {
+ const at = (edge: OverlayEdge, t: number) => glyphStateAt(evalOverlayAnim({ in: edge }, t, 6, true), 0, 1);
+
+ test("a share of the move fades the letter up that early, then holds it solid", () => {
+ const edge: OverlayEdge = { style: "drop", seconds: 1, stagger: 0, distance: 600, fade: 0.25 };
+ expect(at(edge, 0.125).alpha).toBeCloseTo(0.5, 1);
+ expect(at(edge, 0.3).alpha).toBe(1);
+ // The style's own fade runs the whole move.
+ expect(at({ ...edge, fade: undefined }, 0.3).alpha).toBeLessThan(0.5);
+ });
+});
+
+describe("an order's own timing", () => {
+ test("each named letter starts at its share of the hand-off, not evenly spaced", () => {
+ const { letterSequence } = require("./anim") as typeof import("./anim");
+ const order = letterSequence(TEXT, [5, 4, 0]);
+ // O starts at once, L a tenth of the way through the hand-off, Y at its end.
+ const edge: OverlayEdge = { style: "drop", seconds: 2, stagger: 0.5, order, orderAt: [0, 0.1, 1] };
+ const starts = order.map((i) => firstShow(edge, i));
+ expect(starts[0]).toBeCloseTo(0, 1);
+ expect(starts[1]).toBeCloseTo(0.1, 1);
+ expect(starts[2]).toBeCloseTo(1, 1);
+ // Evenly spaced, L would wait for half the hand-off.
+ expect(firstShow({ ...edge, orderAt: undefined }, order[1])).toBeCloseTo(0.5, 1);
+ });
+});
diff --git a/site/packages/effects-kit/src/motion/evaluate.ts b/site/packages/effects-kit/src/motion/evaluate.ts
index 3607ba84..90bcae31 100644
--- a/site/packages/effects-kit/src/motion/evaluate.ts
+++ b/site/packages/effects-kit/src/motion/evaluate.ts
@@ -192,6 +192,7 @@ function orderOf(sel: RangeSelector, i: number, n: number): number {
function startShare(sel: RangeSelector, i: number, n: number, share = sel.spread, reverse = false): number {
if (n <= 1) return 0;
let o = orderOf(sel, i, n);
+ const spread = clamp01(share);
if (sel.sequence?.length) {
// A sequence hands the motion along the units it names, so the last of
// them lands as the ramp ends; any it leaves out (a space) go with the
@@ -199,9 +200,11 @@ function startShare(sel: RangeSelector, i: number, n: number, share = sel.spread
// reading-order exit does.
n = Math.max(2, sel.sequence.length);
o = Math.min(o, n - 1);
+ // Each unit's own turn, when the order carries them.
+ const at = sel.sequenceAt;
+ if (at && at.length === sel.sequence.length) return clamp01(reverse ? 1 - at[o] : at[o]) * spread;
if (reverse) o = n - 1 - o;
}
- const spread = clamp01(share);
if (sel.shape === "square") return o / n;
const u = o / (n - 1);
switch (sel.shape) {
diff --git a/site/packages/effects-kit/src/motion/types.ts b/site/packages/effects-kit/src/motion/types.ts
index b33a9c89..9c494dc8 100644
--- a/site/packages/effects-kit/src/motion/types.ts
+++ b/site/packages/effects-kit/src/motion/types.ts
@@ -113,6 +113,10 @@ export interface RangeSelector {
/** The units in the order they take their turns, by index: an order read
* off a reference. Units it leaves out go after it, in reading order. */
sequence?: number[];
+ /** When each unit of `sequence` takes its turn, as a share of the
+ * hand-off (0 the first, 1 the last), for a reference whose letters do not
+ * go evenly spaced. Absent, or not one per unit, = evenly spaced. */
+ sequenceAt?: number[];
}
/**
diff --git a/site/src/cut/components/AiPanel.tools.ts b/site/src/cut/components/AiPanel.tools.ts
index e006185c..662e60c3 100644
--- a/site/src/cut/components/AiPanel.tools.ts
+++ b/site/src/cut/components/AiPanel.tools.ts
@@ -282,7 +282,7 @@ export const AI_PANEL_TOOLS = [
{
name: "track_element",
description:
- `Measure where an element of a source's picture sits, frame by frame, and how it moves, so a grow, a slide or a pop is keyed with set_overlay_keyframes to the reference's own numbers. Give a stretch of a video (SOURCE seconds) and a \`seed\` box on the element at \`from\`; boxes in and out are x/y centre and w/h size as frame fractions — what add_shape, add_title and the keys take. The element is found by colour: \`color\` (sample_color reads it), or else the seed's median colour on the first frame, so draw the seed inside the element's edges at a moment it is on screen. \`match\` shape follows the one connected piece of that colour the seed sits on — a card, a bar, a sticker — as it moves and changes size; ink takes every pixel of that colour inside the seed (or \`within\`), the ink of a line of type whose letters are separate pieces: its centre is where the title sits and its height is about 0.7 of the font size when the line is capitals. Leave out \`to\` to measure one frame. \`moves\` lists each move of x, y, w and h with from/to (the source seconds it starts and lands), start/end values, the ease that fits it (${EASE_IDS.join(", ")}) and \`error\`, the RMS miss as a share of the move: under 0.03 is that curve, over 0.1 none fits and the move keys from \`path\` point by point. A size move keys as scale: w over the element's resting w. \`path\` lists the box wherever it changes (a hold is one entry); a null box is a frame where the element was not found. Up to ${TRACK_FRAMES_MAX} frames a call; when \`truncated\`, continue from \`coveredTo\`. Works on a still image too (one frame).`,
+ `Measure where an element of a source's picture sits, frame by frame, and how it moves, so a grow, a slide or a pop is keyed with set_overlay_keyframes to the reference's own numbers. Give a stretch of a video (SOURCE seconds) and a \`seed\` box on the element at \`from\`; boxes in and out are x/y centre and w/h size as frame fractions — what add_shape, add_title and the keys take. The element is found by colour: \`color\` (sample_color reads it), or else the seed's median colour on the first frame, so draw the seed inside the element's edges at a moment it is on screen. \`match\` shape follows the one connected piece of that colour the seed sits on — a card, a bar, a sticker — as it moves and changes size; ink takes every pixel of that colour inside the seed (or \`within\`), the ink of a line of type whose letters are separate pieces: its centre is where the title sits and its height is about 0.7 of the font size when the line is capitals. letters reads a line of type coming in letter by letter — a drop, a rise, a fall out of focus: give \`text\` (the words as they read), \`to\` a moment just after the last letter lands, \`from\` before the first one shows, and a seed close around the landed line; it returns each letter's timing (shows, starts, lands, alpha, soft — the defocus it shows in at) and \`entrance\`, the whole entrance as set_overlay_animation takes it, plus \`crosses\`, other ink the letters pass in front of or behind, which says which lane goes in front. Leave out \`to\` to measure one frame. \`moves\` lists each move of x, y, w and h with from/to (the source seconds it starts and lands), start/end values, the ease that fits it (${EASE_IDS.join(", ")}) and \`error\`, the RMS miss as a share of the move: under 0.03 is that curve, over 0.1 none fits and the move keys from \`path\` point by point. A size move keys as scale: w over the element's resting w. \`path\` lists the box wherever it changes (a hold is one entry); a null box is a frame where the element was not found. Up to ${TRACK_FRAMES_MAX} frames a call; when \`truncated\`, continue from \`coveredTo\`. Works on a still image too (one frame).`,
inputSchema: obj(
{
asset_id: str("Project asset id (video or image)"),
@@ -290,12 +290,14 @@ export const AI_PANEL_TOOLS = [
to: num("Source end s; omit to measure the one frame at from"),
seed: frameBox("A box on the element at from — inside its edges for shape, around the line for ink"),
within: frameBox("Only look inside this box (default: the whole frame for shape, the seed for ink)"),
- color: str("The element's colour as #RRGGBB (default: the seed's median colour)"),
+ color: str("The element's colour as #RRGGBB (default: the seed's median colour; for letters, the seed's main colour other than its ground)"),
+ text: str("letters: the line's words exactly as they read once every letter has landed"),
tolerance: num(`Per-channel distance from color that still counts as it, 0..255 (default ${TRACK_TOLERANCE_DEFAULT}); raise it for a gradient or a soft edge`),
match: {
type: "string",
enum: [...TRACK_MATCHES],
- description: "shape: the one connected piece the seed sits on (default). ink: every pixel of the colour inside the seed or within — type",
+ description:
+ "shape: the one connected piece the seed sits on (default). ink: every pixel of the colour inside the seed or within — type. letters: a line of type coming in letter by letter, read as one per-letter entrance (needs text and to)",
},
picture: pictureArg,
},
diff --git a/site/src/cut/components/AnimationTiles.tools.ts b/site/src/cut/components/AnimationTiles.tools.ts
index a11cba71..1152d9ba 100644
--- a/site/src/cut/components/AnimationTiles.tools.ts
+++ b/site/src/cut/components/AnimationTiles.tools.ts
@@ -28,6 +28,7 @@ import {
OVERLAY_ANIM_DEFAULT_SECONDS,
OVERLAY_ANIM_MAX_SECONDS,
OVERLAY_GLYPH_ANIM_MAX_SECONDS,
+ EDGE_BLUR_MAX,
EDGE_DISTANCE_MAX,
EDGE_ORDERS,
edgeMaxSeconds,
@@ -76,7 +77,7 @@ export const OVERLAY_ANIMATION_TOOLS = [
{
name: "set_overlay_animation",
description:
- `Animate an overlay element (title, shape, or sticker): preset In/Out ramps, a Loop that runs its whole duration, and a Move that says what the element does WHILE it holds. Omitted slots keep their setting; pass "none" to clear one. In/Out styles: ${OVERLAY_ANIM_STYLE_IDS.join(", ")} — slide names are the motion direction; ${TEXT_ONLY_ANIM_STYLE_IDS.join(", ")} animate titles only; ${GLYPH_ANIM_STYLE_IDS.join(", ")} move a title's letters one at a time, and move any other kind as one piece; in_stagger/out_stagger set how much of their ramp the hand-off from the first letter to the last takes, so a 1.6s drop at stagger 0.8 lands a letter every ~0.27s, each moving for ~0.3s. in_order/out_order "shuffle" deals the letters their turns in a scattered order instead of left to right — letters landing at random; in_sequence names the exact order when it is read off a reference. in_ease sets the curve the move travels on and in_fade false keeps letters solid while they fall, both read off how a letter in flight looks. A ramp's timing comes from two reads: how long ONE letter takes from first showing to settling (its own move: track_element match ink within a tall strip over that letter's column), and the span from the first letter's start to the last one's — in_seconds is that span plus one letter's move, and in_stagger is the span over in_seconds. in_distance/out_distance set how far the motion travels from rest, design px: a letter falling from above the frame drops the distance from where track_element first sees it to where it lands. A per-letter ramp on an element with update_overlay motion_blur streaks each letter along its own move, the smear a fast fall wears. ${edgeNotes()} ${DIVE_ANIM_STYLE_IDS.join(", ")} as the exit is the zoom-through-a-letter transition: the shot after the element shows once the ink has filled the frame, so it needs no freeze frames, image stills or per-letter keyframes. Loop styles: ${OVERLAY_LOOP_STYLE_IDS.join(", ")} — ${GLYPH_LOOP_STYLE_IDS.join(", ")} carry a title's letters on their own delays, and carry any other kind as one piece. A move is a slot like the others and never touches the element's keyframe track; set_overlay_keyframes is the precise way to move an element and the default reach, so name a move when it is exactly what you mean — the two compose together. Word effects — words_style, titles only — play the line word by word, timed against the cut's transcript when there is one and spread across the element's own span when there is not: an emphasis travels along a line that is fully up, and a build assembles the line as it is spoken. It is the slot for "make each word pop as I say it" and for "have the words appear one by one". A typewriter entrance on a title can carry a caret: a thin bar at the end of the typed text, solid while it types, then blinking every ${CARET_BLINK_SECONDS}s — the typed comment or search box of a call-to-action card. A hit plays one motion once at a moment inside the element (hit_at seconds from its start), between its entrance and exit: ${hitNotes()}. Use press for a button being pressed, a tap on a UI element, a like or post button; pair it with a click from stock_search kind "sound" placed at the same moment when the tap should be heard. A font cycle flickers a title through typefaces — a new face font_cycle_rate times a second, from font_cycle_at for font_cycle_seconds — and then the title settles back into its own face: the typeface-shuffle beat of a teaser title. Give each face a scale (and tracking) so it fills about the room the title's own face does; a wide tracked title cycling through condensed or hand-drawn faces wants tracking 0 and a scale above 1 on them. A face keeps the title's own line breaks: where its scale makes a line wider than the room the title wraps in, that face is set smaller to fit rather than broken onto another line. Time the faces to the music with font_cycle_beats — a new face on each beat of that clip's detect_beats grid, font_cycle_beat_step 2 for every other beat or 0.5 for half beats — or to a reference's own face changes with font_cycle_switches, the timeline seconds you read them at; either sets every hold and repeats the faces in order to fill the run. A face's own hold times one face by hand; faces repeat in the list to revisit a typeface.`,
+ `Animate an overlay element (title, shape, or sticker): preset In/Out ramps, a Loop that runs its whole duration, and a Move that says what the element does WHILE it holds. Omitted slots keep their setting; pass "none" to clear one. In/Out styles: ${OVERLAY_ANIM_STYLE_IDS.join(", ")} — slide names are the motion direction; ${TEXT_ONLY_ANIM_STYLE_IDS.join(", ")} animate titles only; ${GLYPH_ANIM_STYLE_IDS.join(", ")} move a title's letters one at a time, and move any other kind as one piece; in_stagger/out_stagger set how much of their ramp the hand-off from the first letter to the last takes, so a 1.6s drop at stagger 0.8 lands a letter every ~0.27s, each moving for ~0.3s. in_order/out_order "shuffle" deals the letters their turns in a scattered order instead of left to right — letters landing at random; in_sequence names the exact order when it is read off a reference. in_ease sets the curve the move travels on, in_fade false keeps letters solid while they fall, and in_blur starts each letter out of focus (design px) to sharpen as it lands. in_distance/out_distance set how far the motion travels from rest, design px. A reference's letters coming in are read in one call, never by eye: track_element match letters with the line's words over the stretch they come in returns \`entrance\`, every one of these settings as it goes in (in_style, in_seconds, in_stagger, in_sequence, in_sequence_at — each letter's own turn — in_distance, in_ease, in_fade — false, a share of the move, or true — and in_blur) and the source second the ramp starts — one letter's move is in_seconds × (1 − in_stagger). A per-letter ramp on an element with update_overlay motion_blur streaks each letter along its own move, the smear a fast fall wears — a different look from a soft start. ${edgeNotes()} ${DIVE_ANIM_STYLE_IDS.join(", ")} as the exit is the zoom-through-a-letter transition: the shot after the element shows once the ink has filled the frame, so it needs no freeze frames, image stills or per-letter keyframes. Loop styles: ${OVERLAY_LOOP_STYLE_IDS.join(", ")} — ${GLYPH_LOOP_STYLE_IDS.join(", ")} carry a title's letters on their own delays, and carry any other kind as one piece. A move is a slot like the others and never touches the element's keyframe track; set_overlay_keyframes is the precise way to move an element and the default reach, so name a move when it is exactly what you mean — the two compose together. Word effects — words_style, titles only — play the line word by word, timed against the cut's transcript when there is one and spread across the element's own span when there is not: an emphasis travels along a line that is fully up, and a build assembles the line as it is spoken. It is the slot for "make each word pop as I say it" and for "have the words appear one by one". A typewriter entrance on a title can carry a caret: a thin bar at the end of the typed text, solid while it types, then blinking every ${CARET_BLINK_SECONDS}s — the typed comment or search box of a call-to-action card. A hit plays one motion once at a moment inside the element (hit_at seconds from its start), between its entrance and exit: ${hitNotes()}. Use press for a button being pressed, a tap on a UI element, a like or post button; pair it with a click from stock_search kind "sound" placed at the same moment when the tap should be heard. A font cycle flickers a title through typefaces — a new face font_cycle_rate times a second, from font_cycle_at for font_cycle_seconds — and then the title settles back into its own face: the typeface-shuffle beat of a teaser title. Give each face a scale (and tracking) so it fills about the room the title's own face does; a wide tracked title cycling through condensed or hand-drawn faces wants tracking 0 and a scale above 1 on them. A face keeps the title's own line breaks: where its scale makes a line wider than the room the title wraps in, that face is set smaller to fit rather than broken onto another line. Time the faces to the music with font_cycle_beats — a new face on each beat of that clip's detect_beats grid, font_cycle_beat_step 2 for every other beat or 0.5 for half beats — or to a reference's own face changes with font_cycle_switches, the timeline seconds you read them at; either sets every hold and repeats the faces in order to fill the run. A face's own hold times one face by hand; faces repeat in the list to revisit a typeface.`,
inputSchema: obj({
id: str("Overlay element id"),
move: {
@@ -114,14 +115,30 @@ export const OVERLAY_ANIMATION_TOOLS = [
"Per-letter entrance in an order read off a reference: the letters' numbers in the order they arrive, counting the title's letters from 0 and skipping spaces (YOUR LOCATION: Y=0 … R=3, L=4 … N=11). Overrides in_order; [] clears it",
},
out_sequence: { type: "array", items: { type: "integer" }, description: "Per-letter exit: the letters' numbers in the order they leave; [] clears it" },
+ in_sequence_at: {
+ type: "array",
+ items: { type: "number" },
+ description:
+ "With in_sequence: when each of its letters starts, in its order, as a share of the hand-off — 0 the first, 1 the last — for a reference whose letters do not go evenly spaced (track_element match letters reads it). [] spaces them evenly",
+ },
+ out_sequence_at: { type: "array", items: { type: "number" }, description: "With out_sequence: each letter's turn as a share of the hand-off; [] spaces them evenly" },
in_ease: {
type: "string",
enum: [...EASE_IDS, "style"],
description: `Entrance: the curve the move travels on — the ease track_element reads for the reference's move (linear for a steady fall, an .out ease for one that brakes into place); "style" restores the style's own`,
},
out_ease: { type: "string", enum: [...EASE_IDS, "style"], description: 'Exit: the same curve for the exit ramp; "style" restores the style\'s own' },
- in_fade: bool("Entrance: false keeps the element (each letter) solid the whole way in instead of fading up as it moves — a letter falling in from beyond the frame is solid; true restores the style's fade"),
- out_fade: bool("Exit: false keeps it solid the whole way out; true restores the style's fade"),
+ in_fade: {
+ anyOf: [{ type: "boolean" }, { type: "number" }],
+ description:
+ "Entrance: false keeps the element (each letter) solid the whole way in instead of fading up as it moves — a letter falling in from beyond the frame is solid; a share of the move, 0..1, fades it up over that much and holds it solid after; true restores the style's fade",
+ },
+ out_fade: {
+ anyOf: [{ type: "boolean" }, { type: "number" }],
+ description: "Exit: false keeps it solid the whole way out; a share of the move fades it over that much; true restores the style's fade",
+ },
+ in_blur: num(`Entrance: how soft each letter (the element) starts, design px of defocus, 0..${EDGE_BLUR_MAX}, sharpening on the move's curve as it lands; 0 keeps a soft style sharp, -1 restores the style's own`),
+ out_blur: num(`Exit: how soft it ends, design px; 0 keeps it sharp, -1 restores the style's own`),
in_distance: num(`Entrance: how far the motion travels from rest at its far end, design px at 1080, 1..${EDGE_DISTANCE_MAX}; 0 restores the style's own reach`),
out_distance: num(`Exit: the same reach for the exit ramp, design px; 0 restores the style's own`),
loop_style: {
diff --git a/site/src/cut/components/Inspector.tsx b/site/src/cut/components/Inspector.tsx
index 59923de5..79621fa7 100644
--- a/site/src/cut/components/Inspector.tsx
+++ b/site/src/cut/components/Inspector.tsx
@@ -54,6 +54,7 @@ import {
edgeMotion,
edgeStagger,
EDGE_STAGGER_MAX,
+ EDGE_BLUR_MAX,
EDGE_DISTANCE_MAX,
EASE_IDS,
EASE_LABELS,
@@ -3634,6 +3635,10 @@ function AnimationToolbar({ overlay: o, slot, peers }: { overlay: Overlay; slot:
// A style that fades as it moves can be told to stay solid.
const edgeFades = !!(edge && (edge.preset ?? edgePreset(edge.style))?.animate.opacity);
const edgeFade = edge?.fade !== false;
+ // How much of the move the fade takes: a share, or all of it.
+ const edgeFadeShare = typeof edge?.fade === "number" ? edge.fade : 1;
+ // How soft it starts: the slot's own, else the style's far-end defocus.
+ const edgeBlur = edge?.blur ?? (edge ? ((edge.preset ?? edgePreset(edge.style))?.animate.blur?.[0]?.v ?? 0) : 0);
const writeEdge = (patch: Partial<OverlayEdge>) => {
if (!edge) return;
ck.begin();
@@ -3734,6 +3739,26 @@ function AnimationToolbar({ overlay: o, slot, peers }: { overlay: Overlay; slot:
/>
</Row>
)}
+ {edgeFades && edgeFade && (
+ <Row label="Fade length">
+ <ValueSlider
+ label="Fade length"
+ sliderClassName="data-horizontal:w-24"
+ valueClassName="w-9 text-muted-foreground"
+ value={edgeFadeShare}
+ min={0.05}
+ max={1}
+ step={0.05}
+ format={(v) => `${Math.round(v * 100)}%`}
+ parse={(t) => Number(t.replace("%", "")) / 100}
+ onDraft={(v) => writeEdge({ fade: v >= 1 ? undefined : v })}
+ onCommit={(v) => {
+ writeEdge({ fade: v >= 1 ? undefined : v });
+ ck.end();
+ }}
+ />
+ </Row>
+ )}
{edgeSequence && isTextOverlay(o) && (
// An order read off a reference: the letters as they arrive.
<Row label="Order">
@@ -3763,6 +3788,26 @@ function AnimationToolbar({ overlay: o, slot, peers }: { overlay: Overlay; slot:
/>
</Row>
)}
+ {edge && (
+ <Row label="Blur">
+ <ValueSlider
+ label="Blur"
+ sliderClassName="data-horizontal:w-24"
+ valueClassName="w-9 text-muted-foreground"
+ value={edgeBlur}
+ min={0}
+ max={EDGE_BLUR_MAX}
+ step={1}
+ format={(v) => String(Math.round(v))}
+ parse={(t) => Number(t)}
+ onDraft={(v) => writeEdge({ blur: v })}
+ onCommit={(v) => {
+ writeEdge({ blur: v });
+ ck.end();
+ }}
+ />
+ </Row>
+ )}
{types && <CaretSettings overlay={o} peers={peers} />}
</>
);
diff --git a/site/src/cut/components/inspectorToolFields.test.ts b/site/src/cut/components/inspectorToolFields.test.ts
index 38945688..b943567e 100644
--- a/site/src/cut/components/inspectorToolFields.test.ts
+++ b/site/src/cut/components/inspectorToolFields.test.ts
@@ -116,6 +116,10 @@ const PANEL_NAME: Record<string, string> = {
out_fade: "edgeFade",
in_distance: "edgeDistance",
out_distance: "edgeDistance",
+ in_blur: "edgeBlur",
+ in_sequence_at: "edgeSequence",
+ out_sequence_at: "edgeSequence",
+ out_blur: "edgeBlur",
loop_speed: "speed",
words_style: "words",
words_color: "words",
diff --git a/site/src/cut/lib/aiTools.ts b/site/src/cut/lib/aiTools.ts
index c1a7b1ed..c4980950 100644
--- a/site/src/cut/lib/aiTools.ts
+++ b/site/src/cut/lib/aiTools.ts
@@ -64,6 +64,7 @@ import {
OVERLAY_ANIM_DEFAULT_SECONDS,
EDGE_STAGGER_MAX,
edgeMaxSeconds,
+ EDGE_BLUR_MAX,
EDGE_DISTANCE_MAX,
EDGE_ORDERS,
EASE_IDS,
@@ -250,7 +251,7 @@ import { fontKind, fontLook } from "./fontCatalog";
import { CUT_FONT_MATCH } from "./fontMatchSettings";
import { COMPARE_MODES, MAX_COMPARE, SWEEP_TARGET } from "./frameDiff";
import { compareMoments, sweepSource } from "./sourceCompare";
-import { findPicture, sampleColors, scanCuts, sourcePictureAt, trackCamera, trackElement, type FrameBox } from "./measure/sourceMeasure";
+import { findPicture, sampleColors, scanCuts, sourcePictureAt, trackCamera, trackElement, trackLetters, type FrameBox } from "./measure/sourceMeasure";
import { FULL_FRAME, isFullFrame } from "./measure/picture";
import { DETECT_CHANGES_MAX, DETECT_CUTS_MAX, DETECT_CUTS_SPAN_MAX, SAMPLE_COLOR_MAX, SAMPLE_COLORS_K_MAX, TRACK_FRAMES_MAX, CAMERA_FRAMES_MAX, TRACK_MATCHES, TRACK_PATH_MAX, TRACK_TOLERANCE_DEFAULT } from "./measure/limits";
import { renderStageFrame, storeStageStill } from "./stageFrame";
@@ -641,6 +642,88 @@ function statsReport(stats: ColorStats) {
};
}
+/** track_element with match letters: how a line of type comes in letter by
+ * letter, as the per-letter entrance set_overlay_animation plays back. */
+async function trackLettersResult(
+ asset: MediaAsset,
+ input: Record<string, unknown>,
+ opts: { from: number; to: number | undefined; seed: FrameBox; color: string | undefined; area: FrameBox }
+) {
+ if (asset.type !== "video") throw new ToolError(`"${asset.name}" is a still image — letters coming in need a video.`);
+ const text = typeof input.text === "string" ? input.text.trim() : "";
+ if (!text) throw new ToolError("Pass text: the line's words exactly as they read once every letter has landed.");
+ if (opts.to === undefined)
+ throw new ToolError("Pass to: a source second just after the last letter lands, with the whole line at rest — from is where the first letter is still out of sight.");
+ const run = await withSweepPaused(() =>
+ trackLetters(asset.url, {
+ from: opts.from,
+ to: opts.to!,
+ seed: opts.seed,
+ text,
+ ...(opts.color ? { color: opts.color } : {}),
+ maxFrames: TRACK_FRAMES_MAX,
+ area: opts.area,
+ })
+ ).catch((e) => {
+ throw new ToolError(e instanceof Error ? e.message : `Could not read "${asset.name}".`, { cause: e });
+ });
+ const r2 = (v: number) => Math.round(v * 100) / 100;
+ const e = run.edge;
+ // A first letter already moving as the stretch opens starts at its opening.
+ const start = e ? Math.max(opts.from, e.start) : undefined;
+ return {
+ color: run.color,
+ match: "letters",
+ ...(run.fps > 0 ? { fps: Math.round(run.fps * 100) / 100 } : {}),
+ framesRead: run.framesRead,
+ letters: run.letters.map((l) => ({
+ letter: l.char,
+ index: l.index,
+ shows: l.shows === null ? null : roundT(l.shows),
+ starts: l.starts === null ? null : roundT(l.starts),
+ lands: l.lands === null ? null : roundT(l.lands),
+ ...(l.alpha !== null ? { alpha: r2(l.alpha) } : {}),
+ ...(l.soft !== null ? { soft: Math.round(l.soft) } : {}),
+ ...(l.error !== null ? { error: Math.round(l.error * 1000) / 1000 } : {}),
+ })),
+ ...(e && start !== undefined
+ ? {
+ entrance: {
+ starts: roundT(start),
+ in_style: e.direction === "up" ? "rise" : "drop",
+ in_seconds: r2(e.seconds),
+ in_stagger: r2(Math.min(0.95, e.stagger)),
+ in_sequence: e.sequence,
+ in_sequence_at: e.sequenceAt.map((v) => Math.round(v * 1000) / 1000),
+ in_distance: Math.round(e.distance),
+ ...(e.ease ? { in_ease: e.ease } : {}),
+ in_fade: typeof e.fade === "number" ? Math.round(e.fade * 100) / 100 : e.fade,
+ in_blur: Math.round(Math.min(EDGE_BLUR_MAX, e.blur)),
+ },
+ entranceNote:
+ "The entrance as set_overlay_animation takes it, read off every frame: each letter's move fitted on one ease and one distance, the order their moves start in, the hand-off spread across them, whether they fade in and how soft they start. Set the title to begin on the timeline second `starts` maps to, and pass these as they are; one letter's move is in_seconds × (1 − in_stagger). Leave motion_blur off unless the letters streak along their fall — a soft start is in_blur.",
+ }
+ : {
+ entranceNote:
+ "Not every letter was seen coming in: widen from/to so the stretch opens before the first letter shows and closes once the last has landed.",
+ }),
+ ...(run.passes.length
+ ? {
+ crosses: run.passes.map((p) => ({
+ color: p.color,
+ box: { x: rF(p.box.x), y: rF(p.box.y), w: rF(p.box.w), h: rF(p.box.h) },
+ letters: p.letters,
+ })),
+ crossesNote:
+ "Other ink the letters pass over on their way in. front: the letters cover it, so the title sits on a lower lane (nearer 0) than that element; behind: it covers them, so it sits nearer 0.",
+ }
+ : {}),
+ ...(run.truncated ? { truncated: true } : {}),
+ ...pictureReport(opts.area),
+ source: sourceRef(asset),
+ };
+}
+
/** The measuring tools (detect_cuts, sample_color, track_element) read the
* source's own pixels: a video, or for "picture" also a still image. */
function measuredSource(s: Editor, input: Record<string, unknown>, wants: "video" | "picture"): MediaAsset {
@@ -1052,8 +1135,20 @@ const toolRuns: Record<BrowserToolName, ToolRun> = {
const order = letterSequence(text, sequence as number[]);
if (sequence.length > 0 && order.length === 0)
throw new ToolError(`${slot}_sequence names no letter of "${text}": count its letters from 0, skipping spaces.`);
+ delete rest.orderAt;
anim[slot] = order.length > 0 ? { ...rest, order } : rest;
}
+ // Each named letter's own turn, as a share of the hand-off.
+ const sequenceAt = input[`${slot}_sequence_at`];
+ if (Array.isArray(sequenceAt) && anim[slot]) {
+ const rest = { ...anim[slot]! };
+ delete rest.orderAt;
+ const named = Array.isArray(rest.order) ? rest.order.length : 0;
+ if (sequenceAt.length > 0 && sequenceAt.length !== named)
+ throw new ToolError(`${slot}_sequence_at needs one share per letter of ${slot}_sequence (${named}), in its order.`);
+ const at = (sequenceAt as unknown[]).map((v) => (isNum(v) ? clamp(v, 0, 1) : 0));
+ anim[slot] = at.length > 0 ? { ...rest, orderAt: at } : rest;
+ }
const ease = input[`${slot}_ease`];
if (typeof ease === "string" && anim[slot]) {
if (ease !== "style" && !isEaseId(ease))
@@ -1062,11 +1157,14 @@ const toolRuns: Record<BrowserToolName, ToolRun> = {
delete rest.ease;
anim[slot] = ease === "style" ? rest : { ...rest, ease: ease as EaseId };
}
+ // false keeps it solid, a share of the move fades it up over that much,
+ // true hands back the style's own.
const fade = input[`${slot}_fade`];
- if (typeof fade === "boolean" && anim[slot]) {
+ if ((typeof fade === "boolean" || isNum(fade)) && anim[slot]) {
const rest = { ...anim[slot]! };
delete rest.fade;
- anim[slot] = fade ? rest : { ...rest, fade: false };
+ anim[slot] =
+ fade === true || (isNum(fade) && fade >= 1) ? rest : fade === false || fade <= 0 ? { ...rest, fade: false } : { ...rest, fade: clamp(fade, 0.01, 1) };
}
const distance = input[`${slot}_distance`];
if (isNum(distance) && anim[slot]) {
@@ -1074,6 +1172,13 @@ const toolRuns: Record<BrowserToolName, ToolRun> = {
delete rest.distance;
anim[slot] = distance <= 0 ? rest : { ...rest, distance: clamp(distance, 1, EDGE_DISTANCE_MAX) };
}
+ // A soft start: 0 keeps a soft style sharp, a negative hands it back.
+ const blur = input[`${slot}_blur`];
+ if (isNum(blur) && anim[slot]) {
+ const rest = { ...anim[slot]! };
+ delete rest.blur;
+ anim[slot] = blur < 0 ? rest : { ...rest, blur: clamp(blur, 0, EDGE_BLUR_MAX) };
+ }
};
edge("in", "in_style", "in_seconds");
edge("out", "out_style", "out_seconds");
@@ -1859,6 +1964,7 @@ const toolRuns: Record<BrowserToolName, ToolRun> = {
const from = asset.type === "video" ? clamp(isNum(input.from) ? input.from : 0, 0, end) : 0;
const to = asset.type === "video" && isNum(input.to) && input.to > from ? clamp(input.to, 0, asset.duration) : undefined;
const area = pictureArea(asset, input);
+ if (match === "letters") return trackLettersResult(asset, input, { from, to, seed, color, area });
const run = await withSweepPaused(() =>
trackElement(asset.url, asset.type === "image" ? "image" : "video", {
area,
diff --git a/site/src/cut/lib/edgeShapeTool.test.ts b/site/src/cut/lib/edgeShapeTool.test.ts
index 8fda2822..fbff4557 100644
--- a/site/src/cut/lib/edgeShapeTool.test.ts
+++ b/site/src/cut/lib/edgeShapeTool.test.ts
@@ -69,3 +69,42 @@ describe("set_overlay_animation ease and fade", () => {
expect(edgeOf(t.id)?.fade).toBeUndefined();
});
});
+
+describe("set_overlay_animation blur", () => {
+ beforeEach(reset);
+
+ test("a soft start rides the slot, capped; a negative hands it back, 0 keeps it sharp", async () => {
+ const t = await title();
+ await runAiTool("set_overlay_animation", { id: t.id, in_style: "drop", in_blur: 40 });
+ expect(edgeOf(t.id)?.blur).toBe(40);
+ await runAiTool("set_overlay_animation", { id: t.id, in_blur: 500 });
+ expect(edgeOf(t.id)?.blur).toBe(60);
+ await runAiTool("set_overlay_animation", { id: t.id, in_blur: 0 });
+ expect(edgeOf(t.id)?.blur).toBe(0);
+ await runAiTool("set_overlay_animation", { id: t.id, in_blur: -1 });
+ expect(edgeOf(t.id)?.blur).toBeUndefined();
+ });
+});
+
+describe("set_overlay_animation fade length and letter turns", () => {
+ beforeEach(reset);
+
+ test("a fade share rides the slot; 1 or true hands back the style's own, 0 is solid", async () => {
+ const t = await title();
+ await runAiTool("set_overlay_animation", { id: t.id, in_style: "drop", in_fade: 0.45 });
+ expect(edgeOf(t.id)?.fade).toBe(0.45);
+ await runAiTool("set_overlay_animation", { id: t.id, in_fade: 1 });
+ expect(edgeOf(t.id)?.fade).toBeUndefined();
+ await runAiTool("set_overlay_animation", { id: t.id, in_fade: 0 });
+ expect(edgeOf(t.id)?.fade).toBe(false);
+ });
+
+ test("each named letter's turn rides the order; a new order drops the old turns", async () => {
+ const t = await title();
+ await runAiTool("set_overlay_animation", { id: t.id, in_style: "drop", in_sequence: [5, 4, 0], in_sequence_at: [0, 0.2, 1] });
+ expect(edgeOf(t.id)?.orderAt).toEqual([0, 0.2, 1]);
+ await expect(runAiTool("set_overlay_animation", { id: t.id, in_sequence_at: [0, 1] })).rejects.toThrow("one share per letter");
+ await runAiTool("set_overlay_animation", { id: t.id, in_sequence: [0, 4, 5] });
+ expect(edgeOf(t.id)?.orderAt).toBeUndefined();
+ });
+});
diff --git a/site/src/cut/lib/measure/letters.test.ts b/site/src/cut/lib/measure/letters.test.ts
new file mode 100644
index 00000000..d3570009
--- /dev/null
+++ b/site/src/cut/lib/measure/letters.test.ts
@@ -0,0 +1,203 @@
+import { describe, expect, test } from "bun:test";
+import { evalOverlayAnim, glyphStateAt, type OverlayEdge } from "@donkeycut/effects-kit";
+import { readLetters, type LetterFrame } from "./letters";
+
+type Rgb = [number, number, number];
+
+// A 240×135 picture of a 1080-short-side design: a pixel is 8 design px.
+const W = 240;
+const H = 135;
+const UNIT = 1080 / H;
+const RED: Rgb = [255, 0, 0];
+const WHITE: Rgb = [255, 255, 255];
+// The ground cuts between two dark colours every few frames, as the shots do.
+const GROUNDS: Rgb[] = [
+ [0, 42, 51],
+ [103, 1, 45],
+];
+const TEXT = "ABCD EF";
+const N = 6;
+// Each letter's rest: 14 px wide columns with gaps, 30 px tall, centred at y 80.
+const REST = Array.from({ length: N }, (_, i) => ({
+ x: 50 + i * 24,
+ y: 65,
+ w: 14,
+ h: 30,
+}));
+// A line of white type the letters fall through, above where they land.
+const LINE = { x: 40, y: 48, w: 160, h: 8 };
+
+/** Abramowitz and Stegun 7.1.26: the error function to 1.5e-7. */
+function erf(x: number): number {
+ const s = Math.sign(x);
+ const a = Math.abs(x);
+ const t = 1 / (1 + 0.3275911 * a);
+ const y = 1 - ((((1.061405429 * t - 1.453152027) * t + 1.421413741) * t - 0.284496736) * t + 0.254829592) * t * Math.exp(-a * a);
+ return s * y;
+}
+
+const mix = (a: Rgb, b: Rgb, k: number): Rgb => [0, 1, 2].map((c) => Math.round(a[c] + (b[c] - a[c]) * k)) as Rgb;
+
+/** The picture at `t` with the letters on `edge`, the white line behind them
+ * or in front of them. */
+function frameAt(t: number, edge: OverlayEdge, lineInFront: boolean, frame: number, gradient = false): LetterFrame {
+ const ground = GROUNDS[Math.floor(frame / 5) % 2];
+ const data = new Uint8ClampedArray(W * H * 4);
+ // A gradient ground has no one colour most of it is.
+ for (let i = 0; i < W * H; i++) data.set([...(gradient ? mix(ground, [0, 0, 0], (i % W) / W) : ground), 255], i * 4);
+ // A rectangle's coverage of each pixel, defocused by `sigma` px.
+ const paint = (r: { x: number; y: number; w: number; h: number }, c: Rgb, alpha = 1, sigma = 0) => {
+ const reach = Math.ceil(sigma * 3) + 1;
+ const cover = (a: number, b: number, p: number) =>
+ sigma > 0
+ ? (erf((b - p - 0.5) / (sigma * Math.SQRT2)) - erf((a - p - 0.5) / (sigma * Math.SQRT2))) / 2
+ : p >= Math.round(a) && p < Math.round(b)
+ ? 1
+ : 0;
+ for (let y = Math.max(0, Math.floor(r.y) - reach); y < Math.min(H, Math.ceil(r.y + r.h) + reach); y++)
+ for (let x = Math.max(0, r.x - reach); x < Math.min(W, r.x + r.w + reach); x++) {
+ const k = alpha * cover(r.x, r.x + r.w, x) * cover(r.y, r.y + r.h, y);
+ if (k <= 0) continue;
+ const i = (y * W + x) * 4;
+ data.set([...mix([data[i], data[i + 1], data[i + 2]], c, k), 255], i);
+ }
+ };
+ const line = () => paint(LINE, WHITE);
+ if (!lineInFront) line();
+ const st = evalOverlayAnim({ in: edge }, t, 10, true);
+ // Glyph indices count the space, as the title's characters do.
+ const chars = [...TEXT];
+ let letter = 0;
+ chars.forEach((c, gi) => {
+ if (!c.trim()) return;
+ const g = glyphStateAt(st, gi, chars.length);
+ paint({ ...REST[letter], y: REST[letter].y + g.dy / UNIT }, RED, g.alpha, (g.blur ?? 0) / UNIT);
+ letter++;
+ });
+ if (lineInFront) line();
+ return { data, width: W, height: H, t };
+}
+
+function framesOf(edge: OverlayEdge, lineInFront = false, gradient = false): LetterFrame[] {
+ const out: LetterFrame[] = [];
+ for (let f = 0; f / 30 <= edge.seconds + 0.3; f++) out.push(frameAt(f / 30, edge, lineInFront, f, gradient));
+ return out;
+}
+
+const region = { x: 40, y: 58, w: 160, h: 44 };
+const read = (frames: LetterFrame[]) => readLetters(frames, { text: TEXT, region, ink: RED, unit: UNIT });
+
+// Letters 3, 1, 5, 0, 4, 2 (spaces skipped) as glyph indices of "ABCD EF".
+const ORDER = [3, 1, 6, 0, 5, 2];
+const SEQUENCE = [3, 1, 5, 0, 4, 2];
+
+describe("reading a line's letters as they come in", () => {
+ // Solid letters falling from well above the picture at a steady speed.
+ const edge: OverlayEdge = {
+ style: "drop",
+ seconds: 2.2,
+ stagger: 0.75,
+ order: ORDER,
+ distance: 1200,
+ ease: "linear",
+ fade: false,
+ };
+
+ test("names the order, the hand-off and one letter's move", () => {
+ const r = read(framesOf(edge));
+ expect(r.edge?.sequence).toEqual(SEQUENCE);
+ // Each letter's own move: 2.2 × 0.25 = 0.55s, of which the part inside the picture shows.
+ expect(r.edge!.ease).toBe("linear");
+ expect(r.edge!.fade).toBe(false);
+ expect(r.edge!.direction).toBe("down");
+ // The span of starts is the stagger's share, 1.65s, wherever the moves begin.
+ const span = r.edge!.seconds * r.edge!.stagger;
+ expect(span).toBeCloseTo(1.65, 1);
+ });
+
+ test("its edge, played back, puts every letter where the reference has it", () => {
+ const frames = framesOf(edge);
+ const e = read(frames).edge!;
+ const chars = [...TEXT];
+ const glyphOf = (letter: number) =>
+ chars.findIndex((c, gi) => c.trim() && chars.slice(0, gi).filter((x) => x.trim()).length === letter);
+ const ours: OverlayEdge = {
+ style: "drop",
+ seconds: e.seconds,
+ stagger: e.stagger,
+ order: e.sequence.map(glyphOf),
+ orderAt: e.sequenceAt,
+ distance: e.distance,
+ ease: e.ease ?? undefined,
+ fade: e.fade,
+ };
+ for (const f of frames) {
+ const theirs = evalOverlayAnim({ in: edge }, f.t, 10, true);
+ const mine = evalOverlayAnim({ in: ours }, f.t - e.start, 10, true);
+ for (let letter = 0; letter < N; letter++) {
+ const gi = glyphOf(letter);
+ const a = glyphStateAt(theirs, gi, chars.length);
+ const b = glyphStateAt(mine, gi, chars.length);
+ // Inside the picture the two agree to within a couple of pixels.
+ const bottom = REST[letter].y + REST[letter].h;
+ if (bottom + a.dy / UNIT > 0) expect(Math.abs(a.dy - b.dy) / UNIT).toBeLessThan(2.5);
+ }
+ }
+ });
+
+ test("solid, sharp letters read as solid and sharp", () => {
+ const r = read(framesOf(edge));
+ expect(r.edge!.fade).toBe(false);
+ expect(r.edge!.blur).toBe(0);
+ });
+
+ test("a short fade and uneven turns read as they are, and play back the same", () => {
+ // Starting inside the picture, so the fade shows: fully up a third of the
+ // way into each move, turns bunched at the start.
+ const ragged: OverlayEdge = { ...edge, distance: 500, fade: 0.3, orderAt: [0, 0.1, 0.2, 0.5, 0.9, 1] };
+ const e = read(framesOf(ragged)).edge!;
+ expect(typeof e.fade).toBe("number");
+ expect(e.fade as number).toBeGreaterThan(0.15);
+ expect(e.fade as number).toBeLessThan(0.45);
+ expect(e.sequenceAt[1]).toBeCloseTo(0.1, 1);
+ expect(e.sequenceAt[3]).toBeCloseTo(0.5, 1);
+ });
+
+ test("letters that fade in and sharpen on the way read as fading and soft", () => {
+ // Out of focus by 40 design px (5 of these pixels) at the far end.
+ const r = read(framesOf({ ...edge, ease: "power3.out", fade: undefined, blur: 40 }));
+ expect(r.edge!.fade).toBe(true);
+ expect(r.edge!.ease).toBe("power3.out");
+ expect(r.edge!.blur).toBeGreaterThan(28);
+ expect(r.edge!.blur).toBeLessThan(52);
+ });
+
+ test("tells which side of a line they cross the letters pass", () => {
+ expect(read(framesOf(edge, false)).passes[0]?.letters).toBe("front");
+ expect(read(framesOf(edge, true)).passes[0]?.letters).toBe("behind");
+ });
+
+ test("letters filling most of a seed close around them, over a gradient, still read", () => {
+ const frames = framesOf(edge, false, true);
+ const tight = { x: 49, y: 64, w: 136, h: 32 };
+ expect(readLetters(frames, { text: TEXT, region: tight, ink: RED, unit: UNIT }).edge?.sequence).toEqual(SEQUENCE);
+ });
+
+ test("a seed at fractions of a pixel, as a frame box maps to one, still reads", () => {
+ const frames = framesOf(edge);
+ const loose = { x: 40.37, y: 58.6, w: 160.25, h: 44.4 };
+ expect(readLetters(frames, { text: TEXT, region: loose, ink: RED, unit: UNIT }).edge?.sequence).toEqual(SEQUENCE);
+ });
+
+ test("a seed with none of the colour is refused, not misread", () => {
+ const frames = framesOf(edge);
+ expect(() => readLetters(frames, { text: TEXT, region: { x: 0, y: 0, w: 30, h: 20 }, ink: RED, unit: UNIT })).toThrow(
+ /Found 0 letters/,
+ );
+ });
+
+ test("a last frame missing a letter is refused, not misread", () => {
+ const frames = framesOf(edge).slice(0, 20);
+ expect(() => read(frames)).toThrow(/letters? of that colour/);
+ });
+});
diff --git a/site/src/cut/lib/measure/letters.ts b/site/src/cut/lib/measure/letters.ts
new file mode 100644
index 00000000..0579b807
--- /dev/null
+++ b/site/src/cut/lib/measure/letters.ts
@@ -0,0 +1,701 @@
+/** How a line of type comes in letter by letter: each letter's column read
+ * frame by frame — when it shows, where it starts, when it lands, how solid
+ * it is on the way — and what the whole entrance comes to as one per-letter
+ * edge (order, length, hand-off, distance, ease, fade). Also which side of
+ * other ink the letters pass: in front of a line they cross, or behind it.
+ * Pure pixel math over a picture's frames; sourceMeasure.ts reads them. */
+
+import { easeAt, EASE_IDS, type EaseId } from "@donkeycut/effects-kit";
+import type { PixelRect, Pixels, Rgb } from "./color";
+
+export interface LetterFrame extends Pixels {
+ t: number;
+}
+
+/** A pixel counts as the letter's ink when it sits at least this far from the
+ * ground toward the letter's colour: a soft fade's early frames and a motion
+ * blur's tail both still read. */
+const INK_MIX = 0.2;
+/** …and strays no further than this off the line between the two colours. */
+const INK_OFF = 60;
+/** A pixel this far toward the letter's colour counts toward its mass. */
+const MASS_MIX = 0.06;
+/** The reaches tried, as multiples of the distance past the picture's edge. */
+const REACHES = [1, 1.25, 1.5, 2, 3];
+/** The softest defocus tried, px of the picture as read. */
+const SOFT_MAX = 20;
+/** A frame names the far end's defocus while this much of it is left. */
+const SOFT_LEFT = 0.15;
+/** A defocus under this, design px, reads as sharp. */
+const SOFT_MIN = 2;
+/** Rows either side of its measured place a frame's letter is matched at. */
+const SOFT_SHIFT = 6;
+/** Frames per letter matched for its softness and opacity. */
+const SOFT_FRAMES = 6;
+/** The shortest and longest one-letter move the fit tries, seconds. */
+const FIT_MIN = 0.1;
+const FIT_MAX = 3;
+/** The ground is never a colour this close to the letters'. */
+const GROUND_CLEAR = 80;
+/** A row of a letter's column holds ink when this many of its pixels do. */
+const ROW_INK = 2;
+/** A letter is at rest within this many pixels of where it settles. */
+const REST_PX = 1.5;
+/** A moving letter's ink runs up to this many times its height: its streak. */
+const TALL = 1.6;
+/** Other ink a letter's box must cross, summed over frames, to call a side. */
+const PASS_MIN = 30;
+/** How far, px, a stroke of other ink stands off its surroundings. */
+const MARK = 6;
+/** Share of the crossed ink a letter's colour must take to be in front. */
+const FRONT_SHARE = 0.15;
+
+export interface LetterTiming {
+ char: string;
+ /** Its place among the line's letters, counted from 0, spaces skipped. */
+ index: number;
+ /** When it first shows, when its move starts (a letter coming in from past
+ * the picture's edge started before it showed), and when it lands. */
+ shows: number | null;
+ starts: number | null;
+ lands: number | null;
+ /** Where it first shows, design px from rest (+ is below or right). */
+ from: number | null;
+ /** Its opacity on the first frame it fully shows, 0..1. */
+ alpha: number | null;
+ /** How soft it is on that frame, design px of defocus. */
+ soft: number | null;
+ ease: EaseId | null;
+ error: number | null;
+}
+
+export interface LetterPass {
+ /** The other ink's colour and box (pixels of the picture). */
+ color: Rgb;
+ box: PixelRect;
+ /** The letters' side of it: they cover it, or it covers them. */
+ letters: "front" | "behind";
+ pixels: number;
+}
+
+export interface LetterRead {
+ letters: LetterTiming[];
+ /** The whole entrance as one per-letter edge, when every letter came in. */
+ edge: {
+ /** Letter indices in the order their moves start. */
+ sequence: number[];
+ /** When each of them starts, as a share of the hand-off: 0 the first, 1
+ * the last — a reference's letters seldom go evenly spaced. */
+ sequenceAt: number[];
+ seconds: number;
+ stagger: number;
+ /** The first letter's move starts here: where the title's ramp begins. */
+ start: number;
+ /** One letter's move, the median. */
+ move: number;
+ distance: number;
+ direction: "down" | "up" | "none";
+ ease: EaseId | null;
+ /** false: solid all the way; a share of the move: it fades up over that
+ * much of it; true: over the whole move. */
+ fade: boolean | number;
+ /** Defocus at the far end, design px, clearing on the move's curve. */
+ blur: number;
+ } | null;
+ passes: LetterPass[];
+}
+
+const dist = (a: Rgb, b: Rgb) => Math.hypot(a[0] - b[0], a[1] - b[1], a[2] - b[2]);
+const at = (px: Pixels, x: number, y: number): Rgb => {
+ const i = (y * px.width + x) * 4;
+ return [px.data[i], px.data[i + 1], px.data[i + 2]];
+};
+const median = (v: number[]) => {
+ const s = [...v].sort((a, b) => a - b);
+ return s.length ? s[Math.floor(s.length / 2)] : 0;
+};
+
+/** The colour most of `rect` is, the letters' own colour aside: the ground.
+ * Quantized so a flat fill wins; a seed close around solid letters over a
+ * gradient holds more of the letters' colour than of any one shade of it. */
+function groundOf(px: Pixels, rect: PixelRect, ink: Rgb): Rgb {
+ const counts = new Map<number, { n: number; sum: [number, number, number] }>();
+ const step = Math.max(1, Math.floor((rect.w * rect.h) / 4000));
+ let k = 0;
+ for (let y = rect.y; y < rect.y + rect.h; y++)
+ for (let x = rect.x; x < rect.x + rect.w; x++) {
+ if (k++ % step) continue;
+ const c = at(px, x, y);
+ if (dist(c, ink) < GROUND_CLEAR) continue;
+ const key = ((c[0] >> 3) << 10) | ((c[1] >> 3) << 5) | (c[2] >> 3);
+ const e = counts.get(key) ?? { n: 0, sum: [0, 0, 0] };
+ e.n++;
+ e.sum[0] += c[0];
+ e.sum[1] += c[1];
+ e.sum[2] += c[2];
+ counts.set(key, e);
+ }
+ let best = { n: 0, sum: [0, 0, 0] as [number, number, number] };
+ for (const e of counts.values()) if (e.n > best.n) best = e;
+ return best.sum.map((v) => v / Math.max(1, best.n)) as Rgb;
+}
+
+/** How far `c` sits from `ground` toward `ink`, 0..1, or -1 when it is off
+ * the line between them — some other colour. */
+function mixOf(c: Rgb, ground: Rgb, ink: Rgb): number {
+ const d = [ink[0] - ground[0], ink[1] - ground[1], ink[2] - ground[2]];
+ const len2 = d[0] * d[0] + d[1] * d[1] + d[2] * d[2];
+ if (len2 < 1) return -1;
+ const v = [c[0] - ground[0], c[1] - ground[1], c[2] - ground[2]];
+ const m = (v[0] * d[0] + v[1] * d[1] + v[2] * d[2]) / len2;
+ const off = Math.hypot(v[0] - m * d[0], v[1] - m * d[1], v[2] - m * d[2]);
+ return off > INK_OFF ? -1 : Math.max(0, Math.min(1, m));
+}
+
+/** The letter's ink in one column: its rows' box (the run holding the most
+ * ink, with the pieces of it within `tall` rows) and its mass, the sum of
+ * every pixel's share of the letter's colour — a blur spreads it over more
+ * rows and keeps it, a fade thins it. Null when it is not there. */
+function columnInk(px: Pixels, x0: number, x1: number, ink: Rgb, tall = 0): { y0: number; y1: number; mass: number } | null {
+ const ground = groundOf(px, { x: x0, y: 0, w: x1 - x0, h: px.height }, ink);
+ if (dist(ground, ink) < 30) return null;
+ const rows: number[] = [];
+ const mass: number[] = [];
+ for (let y = 0; y < px.height; y++) {
+ let n = 0;
+ let m = 0;
+ for (let x = x0; x < x1; x++) {
+ const v = mixOf(at(px, x, y), ground, ink);
+ if (v >= INK_MIX) n++;
+ if (v >= MASS_MIX) m += v;
+ }
+ rows.push(n);
+ mass.push(m);
+ }
+ // Runs of inked rows, a one-row gap bridged (a letter's crossbar gap).
+ const runs: { y0: number; y1: number; total: number }[] = [];
+ let y = 0;
+ while (y < rows.length) {
+ if (rows[y] < ROW_INK) {
+ y++;
+ continue;
+ }
+ let e = y;
+ let total = 0;
+ while (e < rows.length && (rows[e] >= ROW_INK || (e + 1 < rows.length && rows[e + 1] >= ROW_INK))) total += rows[e++];
+ runs.push({ y0: y, y1: e, total });
+ y = e;
+ }
+ let best = runs.reduce<(typeof runs)[number] | null>((b, r) => (!b || r.total > b.total ? r : b), null);
+ if (!best || best.total < 6) return null;
+ // Something drawn over the letter cuts it in two: the runs either side
+ // that still fit inside one letter's height are the same letter.
+ if (tall)
+ for (const r of [...runs].sort((a, b) => Math.abs(a.y0 - best!.y0) - Math.abs(b.y0 - best!.y0))) {
+ const y0 = Math.min(best.y0, r.y0);
+ const y1 = Math.max(best.y1, r.y1);
+ if (r !== best && y1 - y0 <= tall) best = { y0, y1, total: best.total + r.total };
+ }
+ // The blur's faint tails, however long, carry mass too: the column's own.
+ const sum = mass.reduce((a, m) => a + m, 0);
+ return { y0: best.y0, y1: best.y1, mass: sum };
+}
+
+/** The letters' columns on the settled frame: runs of columns holding ink,
+ * left to right — a letter's pieces (an i's dot) share one. */
+function columnsOf(px: Pixels, region: PixelRect, ink: Rgb, count: number): { x0: number; x1: number; y0: number; y1: number }[] {
+ const ground = groundOf(px, region, ink);
+ const inked = (x: number, y: number) => mixOf(at(px, x, y), ground, ink) >= 0.5;
+ // Each column of the region: how many of its pixels are ink, and where.
+ const xs = Array.from({ length: Math.max(0, region.w) }, (_, k) => {
+ const x = region.x + k;
+ let n = 0;
+ let y0 = Infinity;
+ let y1 = -Infinity;
+ for (let y = region.y; y < region.y + region.h; y++)
+ if (inked(x, y)) {
+ n++;
+ y0 = Math.min(y0, y);
+ y1 = Math.max(y1, y + 1);
+ }
+ return { n, y0, y1 };
+ });
+ const span = (k0: number, k1: number) => ({
+ x0: region.x + k0,
+ x1: region.x + k1,
+ y0: Math.min(
+ ...xs
+ .slice(k0, k1)
+ .filter((c) => c.n)
+ .map((c) => c.y0),
+ ),
+ y1: Math.max(
+ ...xs
+ .slice(k0, k1)
+ .filter((c) => c.n)
+ .map((c) => c.y1),
+ ),
+ });
+ let runs: [number, number][] = [];
+ for (let k = 0; k < xs.length; k++) {
+ if (!xs[k].n) continue;
+ let e = k;
+ while (e < xs.length && xs[e].n) e++;
+ runs.push([k, e]);
+ k = e;
+ }
+ // A sliver is noise, not a letter.
+ const wide = median(runs.map(([k0, k1]) => k1 - k0));
+ runs = runs.filter(([k0, k1]) => k1 - k0 >= Math.max(2, wide * 0.15));
+ // Letters set tight touch: split the widest run at its thinnest column, away
+ // from its edges, until there are as many as the line has letters.
+ while (runs.length > 0 && runs.length < count) {
+ const at = runs.reduce((w, r, i) => (r[1] - r[0] > runs[w][1] - runs[w][0] ? i : w), 0);
+ const [k0, k1] = runs[at];
+ if (k1 - k0 < 4) break;
+ let cut = -1;
+ for (let k = k0 + Math.ceil((k1 - k0) * 0.2); k < k1 - Math.ceil((k1 - k0) * 0.2); k++) if (cut < 0 || xs[k].n < xs[cut].n) cut = k;
+ if (cut < 0) break;
+ runs.splice(at, 1, [k0, cut], [cut + 1, k1]);
+ }
+ return runs.map(([k0, k1]) => span(k0, k1));
+}
+
+/** Each ease sampled once, read back between samples: the fit asks for
+ * millions of points, and solving a bezier for each is the slow part. */
+const CURVE_STEPS = 1024;
+const curves = new Map<EaseId, Float64Array>();
+function curveOf(ease: EaseId): Float64Array {
+ let c = curves.get(ease);
+ if (!c) {
+ c = new Float64Array(CURVE_STEPS + 1);
+ for (let k = 0; k <= CURVE_STEPS; k++) c[k] = easeAt(ease, k / CURVE_STEPS);
+ curves.set(ease, c);
+ }
+ return c;
+}
+
+/** One letter's frames as the fit reads them: where it was (px from rest)
+ * on each frame it showed, and the frames before that it did not. */
+interface Track {
+ seen: { t: number; v: number }[];
+ hidden: number[];
+ /** How far from rest it is wholly past the picture's edge, px. */
+ edge: number;
+ /** Rest height, px: a miss is capped at half of it, so a frame where
+ * something else crossed the column cannot drag the fit. */
+ h: number;
+}
+
+/** The squared miss of a letter moving `d` px (signed: − comes from above)
+ * on `ease` from t0 over `secs`, against its frames. */
+function missOf(tr: Track, d: number, ease: EaseId, t0: number, secs: number): number {
+ const cap = (tr.h / 2) ** 2;
+ const curve = curveOf(ease);
+ const pos = (t: number) => {
+ const p = (t - t0) / secs;
+ if (p <= 0) return d;
+ if (p >= 1) return 0;
+ const f = p * CURVE_STEPS;
+ const k = Math.floor(f);
+ return d * (1 - (curve[k] + (curve[k + 1] - curve[k]) * (f - k)));
+ };
+ let sq = 0;
+ for (const p of tr.seen) sq += Math.min(cap, (pos(p.t) - p.v) ** 2);
+ // Before it showed it was out of the picture, past its edge.
+ for (const t of tr.hidden) {
+ const short = tr.edge - 1 - Math.abs(pos(t));
+ if (short > 0) sq += Math.min(cap, short * short);
+ }
+ return sq;
+}
+
+/** The best start and length for one letter on one distance and ease:
+ * a coarse grid, then a fine one around its best. No move starts before
+ * `earliest`, the source's first frame: a title cannot start before it, and
+ * a letter come in from past the edge fits a longer, earlier move from
+ * further off just as well. */
+function fitTrack(tr: Track, d: number, ease: EaseId, step: number, earliest: number): { t0: number; secs: number; sq: number } {
+ const shows = tr.seen[0].t;
+ let best = { t0: shows, secs: 0.5, sq: Infinity };
+ const search = (secsLo: number, secsHi: number, dSecs: number, t0Of: (secs: number) => [number, number], dT: number) => {
+ for (let secs = secsLo; secs <= secsHi + 1e-9; secs += dSecs) {
+ if (secs < FIT_MIN) continue;
+ const [lo, hi] = t0Of(secs);
+ for (let t0 = Math.max(earliest, lo); t0 <= hi + 1e-9; t0 += dT) {
+ const sq = missOf(tr, d, ease, t0, secs);
+ if (sq < best.sq) best = { t0, secs, sq };
+ }
+ }
+ };
+ search(FIT_MIN, FIT_MAX, 0.05, (secs) => [shows - secs, shows], step);
+ const c = best;
+ search(c.secs - 0.05, c.secs + 0.05, 0.005, () => [c.t0 - step, c.t0 + step], step / 8);
+ return best;
+}
+
+/** A letter at rest: its share of its colour, pixel by pixel, on the last
+ * frame, and where it sits. */
+interface Sprite {
+ data: Float32Array;
+ w: number;
+ h: number;
+ x0: number;
+ y0: number;
+ /** The sprite blurred at each defocus tried, padded by the blur's reach. */
+ blurred: Map<number, Float32Array>;
+}
+
+/** A sprite defocused by `sigma` px, worked out once per sprite. */
+function blurredSprite(sprite: Sprite, sigma: number): Float32Array {
+ const hit = sprite.blurred.get(sigma);
+ if (hit) return hit;
+ const r = Math.ceil(sigma * 3);
+ const kernel = Array.from({ length: 2 * r + 1 }, (_, k) => (sigma > 0 ? Math.exp(-((k - r) ** 2) / (2 * sigma * sigma)) : 1));
+ const ksum = kernel.reduce((a, b) => a + b, 0);
+ // The sprite padded by the blur's reach, blurred one way then the other.
+ const w = sprite.w + 2 * r;
+ const h = sprite.h + 2 * r;
+ const rowPass = new Float32Array(w * h);
+ for (let y = 0; y < sprite.h; y++)
+ for (let x = 0; x < w; x++) {
+ let v = 0;
+ for (let k = -r; k <= r; k++) {
+ const sx = x - r + k;
+ if (sx >= 0 && sx < sprite.w) v += sprite.data[y * sprite.w + sx] * kernel[k + r];
+ }
+ rowPass[(y + r) * w + x] = v / ksum;
+ }
+ const blurred = new Float32Array(w * h);
+ for (let y = 0; y < h; y++)
+ for (let x = 0; x < w; x++) {
+ let v = 0;
+ for (let k = -r; k <= r; k++) {
+ const sy = y + k;
+ if (sy >= 0 && sy < h) v += rowPass[sy * w + x] * kernel[k + r];
+ }
+ blurred[y * w + x] = v / ksum;
+ }
+ sprite.blurred.set(sigma, blurred);
+ return blurred;
+}
+
+/** One frame of a letter matched against its own rest pose: the defocus
+ * (px) and opacity that, laid at `offset` px from rest, best make that
+ * frame's column. Each try blurs the rest pose, places it and scales it. */
+function softnessOf(px: Pixels, sprite: Sprite, offset: number, ink: Rgb): { sigma: number; alpha: number } {
+ const ground = groundOf(
+ px,
+ {
+ x: sprite.x0,
+ y: 0,
+ w: sprite.w,
+ h: px.height,
+ },
+ ink,
+ );
+ // The frame's column as shares of the letter's colour, read once; -1 where
+ // some other colour is (a line the letter crosses), which says nothing.
+ const obsAll = new Float32Array(sprite.w * px.height);
+ for (let y = 0; y < px.height; y++)
+ for (let x = 0; x < sprite.w; x++) obsAll[y * sprite.w + x] = mixOf(at(px, sprite.x0 + x, y), ground, ink);
+ const obs = (x: number, y: number) => (y < 0 || y >= px.height ? 0 : obsAll[y * sprite.w + x]);
+ // Every try is scored over the same rows — the letter plus the softest
+ // blur's reach — so a wider blur is not charged for more of the frame.
+ const reach = Math.ceil(SOFT_MAX * 3);
+ let best = { sigma: 0, alpha: 1, err: Infinity };
+ for (let shift = -SOFT_SHIFT; shift <= SOFT_SHIFT; shift++) {
+ const base = Math.round(sprite.y0 + offset) + shift;
+ let oo = 0;
+ for (let y = base - reach; y < base + sprite.h + reach; y++) for (let x = 0; x < sprite.w; x++) oo += Math.max(0, obs(x, y)) ** 2;
+ for (let sigma = 0; sigma <= SOFT_MAX; sigma += 0.5) {
+ const r = Math.ceil(sigma * 3);
+ const w = sprite.w + 2 * r;
+ const h = sprite.h + 2 * r;
+ const blurred = blurredSprite(sprite, sigma);
+ // The column only: the blur spilling past it is a neighbour's to read.
+ let sb = 0;
+ let bb = 0;
+ for (let y = 0; y < h; y++)
+ for (let x = r; x < r + sprite.w; x++) {
+ const o = obs(x - r, base - r + y);
+ if (o < 0) continue;
+ const b = blurred[y * w + x];
+ sb += o * b;
+ bb += b * b;
+ }
+ if (bb <= 0) continue;
+ const alpha = Math.max(0, Math.min(1, sb / bb));
+ const err = oo - 2 * alpha * sb + alpha * alpha * bb;
+ if (err < best.err) best = { sigma, alpha, err };
+ }
+ }
+ return { sigma: best.sigma, alpha: best.alpha };
+}
+
+/** Read how `text`'s letters come in over `frames` (the picture's frames in
+ * order, the last with every letter at rest), the line sitting inside
+ * `region` on that last frame in `ink`. `unit` is design px per pixel. Each
+ * letter's frames are fitted with a move from past the picture's edge (or
+ * further) on one of the editor's eases, one distance and ease for the line,
+ * so the edge it hands back plays the same frames. */
+export function readLetters(
+ frames: LetterFrame[],
+ opts: { text: string; region: PixelRect; ink: Rgb; unit: number; earliest?: number },
+): LetterRead {
+ const chars = [...opts.text].filter((c) => c.trim());
+ const last = frames[frames.length - 1];
+ // Whole pixels inside the frame: a frame box lands on fractions of one.
+ const x0 = Math.max(0, Math.floor(opts.region.x));
+ const y0 = Math.max(0, Math.floor(opts.region.y));
+ const region = {
+ x: x0,
+ y: y0,
+ w: Math.max(0, Math.min(last.width, Math.ceil(opts.region.x + opts.region.w)) - x0),
+ h: Math.max(0, Math.min(last.height, Math.ceil(opts.region.y + opts.region.h)) - y0),
+ };
+ const cols = columnsOf(last, region, opts.ink, chars.length);
+ if (cols.length !== chars.length)
+ throw new Error(
+ `Found ${cols.length} letter${cols.length === 1 ? "" : "s"} of that colour in the region on the last frame, and "${opts.text}" has ${chars.length}. ` +
+ "Pass `to` at a moment every letter has landed and none has left, and a seed close around the line.",
+ );
+ const step = frames.length > 1 ? median(frames.slice(1).map((f, i) => f.t - frames[i].t)) : 1 / 30;
+
+ // Each letter's frames: where it shows, and how solid.
+ const reads = cols.map((c) => {
+ const rest = columnInk(last, c.x0, c.x1, opts.ink);
+ const restMid = rest ? (rest.y0 + rest.y1) / 2 : (c.y0 + c.y1) / 2;
+ const restH = rest ? rest.y1 - rest.y0 : c.y1 - c.y0;
+ const series = frames.map((f) => {
+ const k = columnInk(f, c.x0, c.x1, opts.ink, restH * TALL);
+ if (!k) return null;
+ // A letter cut by the picture's edge is placed by its far side.
+ const cut = k.y0 <= 0 || k.y1 >= f.height;
+ const offset =
+ k.y0 <= 0 ? k.y1 - (restMid + restH / 2) : k.y1 >= f.height ? k.y0 - (restMid - restH / 2) : (k.y0 + k.y1) / 2 - restMid;
+ return { offset, mass: k.mass, cut };
+ });
+ const first = series.findIndex((s) => s !== null);
+ // The letter at rest, its share of its colour pixel by pixel: what each
+ // frame is matched against for how soft and how solid it is.
+ const ground = groundOf(
+ last,
+ {
+ x: c.x0,
+ y: 0,
+ w: c.x1 - c.x0,
+ h: last.height,
+ },
+ opts.ink,
+ );
+ const y0 = Math.max(0, Math.floor(restMid - restH / 2) - 1);
+ const sh = Math.min(last.height - y0, Math.ceil(restH) + 2);
+ const sprite: Sprite = {
+ data: new Float32Array((c.x1 - c.x0) * sh),
+ w: c.x1 - c.x0,
+ h: sh,
+ x0: c.x0,
+ y0,
+ blurred: new Map(),
+ };
+ for (let y = 0; y < sh; y++)
+ for (let x = 0; x < sprite.w; x++) sprite.data[y * sprite.w + x] = Math.max(0, mixOf(at(last, c.x0 + x, y0 + y), ground, opts.ink));
+ return {
+ first,
+ series,
+ sprite,
+ above: restMid + restH / 2,
+ below: last.height - (restMid - restH / 2),
+ h: restH,
+ };
+ });
+ const shown = reads.filter((r) => r.first >= 0);
+ const firstOffsets = shown.map((r) => r.series[r.first]!.offset);
+ const down = median(firstOffsets) < 0;
+ const travels = median(firstOffsets.map(Math.abs)) > REST_PX * 2;
+ const tracks: (Track | null)[] = reads.map((r) =>
+ r.first < 0
+ ? null
+ : {
+ seen: r.series.flatMap((s, i) => (i >= r.first && s ? [{ t: frames[i].t, v: s.offset }] : [])),
+ hidden: frames.slice(0, r.first).map((f) => f.t),
+ edge: down ? r.above : r.below,
+ h: r.h,
+ },
+ );
+
+ // One distance and one ease for the whole line: the pair whose best fits
+ // miss least, letter for letter.
+ const sign = down ? -1 : 1;
+ const edgePx = median(tracks.filter((t): t is Track => t !== null).map((t) => t.edge));
+ let pick: {
+ d: number;
+ ease: EaseId;
+ fits: ({ t0: number; secs: number; sq: number } | null)[];
+ sq: number;
+ } | null = null;
+ if (travels && tracks.every((t) => t !== null))
+ for (const k of REACHES)
+ for (const ease of EASE_IDS) {
+ const d = sign * edgePx * k;
+ const fits = tracks.map((t) => fitTrack(t!, d, ease, step, opts.earliest ?? 0));
+ const sq = fits.reduce((a, f) => a + f.sq, 0);
+ // A longer reach has to fit clearly better to win over the edge.
+ if (!pick || sq < pick.sq * 0.97) pick = { d, ease, fits, sq };
+ }
+
+ // How soft and how solid each letter is on its way in, at a few frames of
+ // its move: its defocus fitted on the move's curve, its opacity against
+ // the share of the move it has made (a fade rises with it).
+ const looks = reads.map((r, index) => {
+ const fit = pick?.fits[index];
+ const along = (t: number) => (fit ? (t - fit.t0) / fit.secs : 0);
+ const moving = r.series.flatMap((s, i) => {
+ const p = along(frames[i].t);
+ return s && !s.cut && p > 0.02 && p < 0.9 ? [i] : [];
+ });
+ const picked =
+ moving.length <= SOFT_FRAMES
+ ? moving
+ : Array.from({ length: SOFT_FRAMES }, (_, k) => moving[Math.round((k * (moving.length - 1)) / (SOFT_FRAMES - 1))]);
+ const out = picked.map((i) => ({
+ p: along(frames[i].t),
+ ...softnessOf(frames[i], r.sprite, r.series[i]!.offset, opts.ink),
+ }));
+ return out;
+ });
+
+ const letters: LetterTiming[] = reads.map((r, index) => {
+ const fit = pick?.fits[index];
+ const tr = tracks[index];
+ const shows = r.first >= 0 ? frames[r.first].t : null;
+ const look = looks[index][0];
+ return {
+ char: chars[index],
+ index,
+ shows,
+ starts: fit ? fit.t0 : shows,
+ lands: fit ? fit.t0 + fit.secs : shows,
+ from: pick ? pick.d * opts.unit : r.first >= 0 ? r.series[r.first]!.offset * opts.unit : null,
+ alpha: look ? look.alpha : null,
+ soft: look ? look.sigma * opts.unit : null,
+ ease: pick ? pick.ease : null,
+ error: fit && tr ? Math.sqrt(fit.sq / Math.max(1, tr.seen.length + tr.hidden.length)) / Math.max(1, Math.abs(pick!.d)) : null,
+ };
+ });
+
+ let edge: LetterRead["edge"] = null;
+ if (pick) {
+ const order = [...letters].sort((a, b) => a.starts! - b.starts! || a.index - b.index);
+ const start = order[0].starts!;
+ const span = order[order.length - 1].starts! - start;
+ const move = median(pick.fits.map((f) => f!.secs));
+ const seconds = span + move;
+ // Defocus B at the far end clears as B × (1 − ease(p)), so each frame
+ // still well short of sharp names a B — their median, as a frame where a
+ // neighbour's fall crossed the column misreads and is outvoted.
+ const all = looks.flat();
+ const named = all.flatMap((l) => {
+ const left = 1 - easeAt(pick!.ease, l.p);
+ return left > SOFT_LEFT ? [l.sigma / left] : [];
+ });
+ const blur = named.length > 0 ? median(named) * opts.unit : 0;
+ // How long the fade runs: opacity min(1, p / k) over the share k of the
+ // move that misses the frames least — 0 is solid, 1 the whole move.
+ let fade: boolean | number = true;
+ let fadeMiss = Infinity;
+ for (let k = 0; k <= 1 + 1e-9; k += 0.05) {
+ const miss = all.reduce((a, l) => a + (l.alpha - (k > 0 ? Math.min(1, l.p / k) : 1)) ** 2, 0);
+ if (miss < fadeMiss - 1e-9) {
+ fadeMiss = miss;
+ fade = k < 0.05 ? false : k > 0.95 ? true : Math.round(k * 100) / 100;
+ }
+ }
+ edge = {
+ sequence: order.map((l) => l.index),
+ sequenceAt: order.map((l) => (span > 0 ? (l.starts! - start) / span : 0)),
+ seconds,
+ stagger: seconds > 0 ? span / seconds : 0,
+ start,
+ move,
+ distance: Math.abs(pick.d) * opts.unit,
+ direction: down ? "down" : "up",
+ ease: pick.ease,
+ fade,
+ blur: blur < SOFT_MIN ? 0 : blur,
+ };
+ }
+
+ return { letters, edge, passes: passesOf(frames, cols, opts.ink) };
+}
+/** Which side of other ink the moving letters pass. The other ink is read off
+ * the last frame inside the letters' columns, above and below the line; on
+ * each frame a moving letter's box covers some of it, and each covered pixel
+ * reads as the letter's colour (the letter in front) or not (behind). */
+function passesOf(frames: LetterFrame[], cols: { x0: number; x1: number; y0: number; y1: number }[], ink: Rgb): LetterPass[] {
+ const last = frames[frames.length - 1];
+ const ground = groundOf(last, { x: 0, y: 0, w: last.width, h: last.height }, ink);
+ // Other ink: neither ground nor the letters' colour, in the letters' columns.
+ const other = new Uint8Array(last.width * last.height);
+ let box: PixelRect | null = null;
+ const colour = [0, 0, 0];
+ let n = 0;
+ for (const c of cols)
+ for (let y = 0; y < last.height; y++)
+ for (let x = c.x0; x < c.x1; x++) {
+ const p = at(last, x, y);
+ if (dist(p, ground) < 60 || dist(p, ink) < 60 || mixOf(p, ground, ink) >= 0) continue;
+ // Ink is a stroke: it stands off what lies a little way to either
+ // side or above and below, where a gradient's far shades do not.
+ const off = [
+ [x - MARK, y],
+ [x + MARK, y],
+ [x, y - MARK],
+ [x, y + MARK],
+ ].filter(([nx, ny]) => nx >= 0 && ny >= 0 && nx < last.width && ny < last.height && dist(p, at(last, nx, ny)) > 60).length;
+ if (off < 2) continue;
+ other[y * last.width + x] = 1;
+ colour[0] += p[0];
+ colour[1] += p[1];
+ colour[2] += p[2];
+ n++;
+ box = box
+ ? {
+ x: Math.min(box.x, x),
+ y: Math.min(box.y, y),
+ w: Math.max(box.x + box.w, x + 1) - Math.min(box.x, x),
+ h: Math.max(box.y + box.h, y + 1) - Math.min(box.y, y),
+ }
+ : { x, y, w: 1, h: 1 };
+ }
+ if (!box || n < PASS_MIN) return [];
+ const otherColour = colour.map((v) => v / n) as Rgb;
+ let front = 0;
+ let behind = 0;
+ for (const f of frames.slice(0, -1))
+ for (const c of cols) {
+ const k = columnInk(f, c.x0, c.x1, ink, (c.y1 - c.y0) * TALL);
+ if (!k) continue;
+ // A letter at rest covers the same ink on every frame: only moving ones tell.
+ if (Math.abs(k.y0 - c.y0) <= REST_PX) continue;
+ for (let y = k.y0; y < k.y1; y++)
+ for (let x = c.x0; x < c.x1; x++) {
+ if (!other[y * f.width + x]) continue;
+ const p = at(f, x, y);
+ if (dist(p, ink) < dist(p, otherColour) && dist(p, ink) < 90) front++;
+ else if (dist(p, otherColour) < 90) behind++;
+ }
+ }
+ if (front + behind < PASS_MIN) return [];
+ return [
+ {
+ color: otherColour.map(Math.round) as Rgb,
+ box,
+ // In front, the letters' strokes take a good share of what their boxes
+ // cross; behind, the other ink shows through all of it.
+ letters: front / (front + behind) > FRONT_SHARE ? "front" : "behind",
+ pixels: front + behind,
+ },
+ ];
+}
diff --git a/site/src/cut/lib/measure/limits.ts b/site/src/cut/lib/measure/limits.ts
index c027e2b1..94bc4a9b 100644
--- a/site/src/cut/lib/measure/limits.ts
+++ b/site/src/cut/lib/measure/limits.ts
@@ -17,8 +17,9 @@ export const SAMPLE_COLORS_K_MAX = 6;
export const TRACK_FRAMES_MAX = 360;
/** track_element: per-channel distance from the colour that still counts as it. */
export const TRACK_TOLERANCE_DEFAULT = 40;
-/** track_element: the element as one connected piece, or every pixel of it. */
-export const TRACK_MATCHES = ["shape", "ink"] as const;
+/** track_element: the element as one connected piece, every pixel of it, or
+ * a line of type read letter by letter as it comes in. */
+export const TRACK_MATCHES = ["shape", "ink", "letters"] as const;
/** track_element: path entries listed per call; a longer path is thinned. */
export const TRACK_PATH_MAX = 60;
/** track_camera: frames read per call — four seconds at 30 fps, every one
diff --git a/site/src/cut/lib/measure/sourceMeasure.ts b/site/src/cut/lib/measure/sourceMeasure.ts
index 106884d9..c6f31138 100644
--- a/site/src/cut/lib/measure/sourceMeasure.ts
+++ b/site/src/cut/lib/measure/sourceMeasure.ts
@@ -14,6 +14,7 @@ import { frameStep, gridsOf, pickShotEdges, type FrameGrids, type FrameStep, typ
import { fitMoves, type Move } from "./easeFit";
import { FULL_FRAME, areaOf, findPictureBox, intoArea, type PictureFind } from "./picture";
import { inkBox, shapeBox } from "./track";
+import { readLetters, type LetterFrame, type LetterRead } from "./letters";
/** A box as the editor places one: centre and size, frame fractions. */
export interface FrameBox {
@@ -389,6 +390,67 @@ export async function trackElement(
};
}
+export interface LetterRun extends Omit<LetterRead, "passes"> {
+ color: string;
+ fps: number;
+ framesRead: number;
+ /** Other ink the letters cross on their way in, its box in the area's fractions. */
+ passes: (Omit<LetterRead["passes"][number], "box" | "color"> & { color: string; box: FrameBox })[];
+ truncated: boolean;
+}
+
+/** How the letters of `text` come in over [from, to]: the line sits inside
+ * `seed` at `to`, every letter landed. The letters are the seed's dominant
+ * colour other than its ground, or `color`. */
+export async function trackLetters(
+ url: string,
+ opts: { from: number; to: number; seed: FrameBox; text: string; color?: string; maxFrames: number; area?: FrameBox }
+): Promise<LetterRun> {
+ const area = opts.area ?? FULL_FRAME;
+ return withSourceVideo(url, async (v) => {
+ const at = sizeAt(v.width, v.height, TRACK_LONG_SIDE, area);
+ const frames: LetterFrame[] = [];
+ const durations: number[] = [];
+ let truncated = false;
+ const crop = (f: SourceFrame) => cropPixels(f, toPixels(f, area));
+ for await (const f of v.frames(opts.from, opts.to, at)) {
+ if (frames.length >= opts.maxFrames - 1) {
+ truncated = true;
+ break;
+ }
+ frames.push({ ...crop(f), t: f.t });
+ durations.push(f.duration);
+ }
+ // The landed line is read on the frame at `to` itself.
+ for await (const f of v.framesAt([opts.to], at)) if (f && (!frames.length || f.t > frames[frames.length - 1].t)) frames.push({ ...crop(f), t: f.t });
+ if (frames.length < 3) throw new Error(`Only ${frames.length} frames between ${opts.from}s and ${opts.to}s — give the whole entrance.`);
+ const last = frames[frames.length - 1];
+ const region = toPixels(last, opts.seed);
+ let ink = opts.color ? parseHex(opts.color) : null;
+ if (!ink) {
+ // The line's colour: the seed's biggest colour other than the picture's ground.
+ const ground = regionColor(last, { x: 0, y: 0, w: last.width, h: last.height }).hex;
+ const g = parseHex(ground)!;
+ const parts = (regionColor(last, region, 3).dominant ?? []).map((d) => ({ ...d, rgb: parseHex(d.hex)! }));
+ const far = parts.filter((d) => Math.hypot(d.rgb[0] - g[0], d.rgb[1] - g[1], d.rgb[2] - g[2]) > 60);
+ ink = (far.sort((a, b) => b.share - a.share)[0] ?? parts[0])?.rgb ?? null;
+ }
+ if (!ink) throw new Error("Could not tell the letters' colour — pass color.");
+ const read = readLetters(frames, { text: opts.text, region, ink, unit: 1080 / Math.min(last.width, last.height), earliest: 0 });
+ return {
+ ...read,
+ color: hexOf(...ink),
+ fps: rateOf(
+ frames.map((f) => f.t),
+ durations
+ ),
+ framesRead: frames.length,
+ passes: read.passes.map((p) => ({ ...p, color: hexOf(...p.color), box: toFrame(last, p.box) })),
+ truncated,
+ };
+ });
+}
+
export interface CameraRun {
fps: number;
/** Per frame read: its time and how the picture sits against the first. */
diff --git a/site/src/cut/server/ai/catalog.ts b/site/src/cut/server/ai/catalog.ts
index 2927d185..d54b8e39 100644
--- a/site/src/cut/server/ai/catalog.ts
+++ b/site/src/cut/server/ai/catalog.ts
@@ -362,7 +362,7 @@ Someone points at a video — a file they imported, a link you brought in, a cli
**Rebuild the text as elements.** One title per card, a stretch of cards per add_title call — the words exactly as they read, size in px at 1080 wide, and x/y where suggest_font sets it on that card — a title is set from the middle of its line, so the centre of its ink box (track_element, match ink, the text's colour) sits off it by the face's own offset. A run of lines timed one after another is add_text_sequence in one call. Match the case the reference uses, and its colour from sample_color. The face comes off the frame: suggest_font with the card's moment, a region close around its words and the words themselves ranks every face Donkey has and hands back the font, weight, size, tracking and x/y to set. Call it on each card: cards in one face share its weight, size and tracking, but each sits its own way in its space, so its x/y comes from its own read, never from a neighbour's place. A title that cycles through typefaces is one call per face it shows. A no_match verdict means the reference uses a face Donkey does not bundle: say so, and set the closest one it named. Without a suggestion, size comes off the ink: capitals stand about 0.7 of the size tall, so size is the ink height in px at 1080 wide ÷ 0.7 (h × 1920 ÷ 0.7 on 9:16). A cycle whose faces change on the music's beats times itself with set_overlay_animation font_cycle_beats on the soundtrack clip after detect_beats; one whose changes follow the reference's own rhythm takes font_cycle_switches, the timeline seconds detect_cuts reads each change at.
-**Then the motion.** set_overlay_keyframes gives each card its own pose track — where it sits, at what scale, at what second. track_element over a move hands you the keys: each move's from/to, start/end and ease, with scale as w over the resting w. set_overlay_animation composes on top for the entrance, the exit, a loop, and what a line does while it holds; 0.3-0.6s reads as an entrance, and a per-letter style is what makes a card read as typed. A line whose letters land one at a time is a per-letter entrance read off detect_cuts' \`changes\`: its timing from two reads — one letter's own move, from first showing to settling (track_element with match ink, \`within\` a tall strip over that one letter's column from the top of the frame to its line, from before it shows until it stops), and the span from the first letter's start to the last one's: in_seconds is the span plus one move, in_stagger the span over in_seconds — in_sequence the order they arrive in (in_order shuffle only when no order can be read), in_distance from where track_element first sees a letter to where it settles — a drop from above the frame travels hundreds of px — in_ease the curve that same track reads for its fall (linear when it drops at a steady pace), in_fade false when a letter is already solid as it comes in over the frame's edge, and motion_blur on the element (update_overlay) when a letter in flight smears along its fall. add_shape, a stretch per call, is the rest of the graphics: bars, cards, rules, a block of color behind a line.
+**Then the motion.** set_overlay_keyframes gives each card its own pose track — where it sits, at what scale, at what second. track_element over a move hands you the keys: each move's from/to, start/end and ease, with scale as w over the resting w. set_overlay_animation composes on top for the entrance, the exit, a loop, and what a line does while it holds; 0.3-0.6s reads as an entrance, and a per-letter style is what makes a card read as typed. A line whose letters land one at a time is a per-letter entrance read off detect_cuts' \`changes\`, and it is read in one call, never by eye from sheets: track_element with match letters, the line's \`text\`, a seed close around the landed line, \`from\` before the first letter shows and \`to\` just after the last one lands. Its \`entrance\` is the set_overlay_animation call — in_style, in_seconds, in_stagger, in_sequence, in_sequence_at, in_distance, in_ease, in_fade, in_blur — and \`starts\`, the source second the title's ramp begins; pass them as they come. Its \`crosses\` says whether the letters pass in front of or behind other ink on their way in — a smaller line above them — and so which of the two takes the lower row. motion_blur on the element (update_overlay) is for letters that streak along their fall; one that comes in soft is in_blur. add_shape, a stretch per call, is the rest of the graphics: bars, cards, rules, a block of color behind a line.
**Look at what you made.** A build that reads right from your own notes is still a guess until you measure it. compare_to_source does: mode sweep scores every frame of the cut against the source — 0 is the same picture, under ${SWEEP_TARGET} reads as one — and names the worst stretches with a grid of where each differs; mode moments shows those peaks beside the source's frames. Sweep as you build, since an error in the first card is in every card after it: look at the worst stretches, fix what differs, sweep again, and stop when the median is under ${SWEEP_TARGET} and no stretch stands out. A \`shift\` means the right thing lands early or late by that much. Read each picture for colour, the words and their face, where a thing sits, its size, and how far along a move is; a title the same colour as the block behind it reads as correct in the document and shows up here. A block keeps its footage's difference, so judge a shot by the cells over what you built.