Skip to content

Open source CapCut alternative.

TypeScript

feat(cut): suggest the bundled face a reference uses [rebuild]

David Le9edb47bdb5ce
diff --git a/site/scripts/lib/cut-eval/fixtures.ts b/site/scripts/lib/cut-eval/fixtures.ts
index 0e03db3a..57dabe17 100644
--- a/site/scripts/lib/cut-eval/fixtures.ts
+++ b/site/scripts/lib/cut-eval/fixtures.ts
@@ -21,6 +21,7 @@ export const SAFE_TOOLS = new Set([
"list_skills",
"read_skill",
"capture_frame",
+ "suggest_font",
"watch_video",
"detect_silence",
"find_filler",
diff --git a/site/src/clients/chatgpt/server/catalog.ts b/site/src/clients/chatgpt/server/catalog.ts
index f4d08107..ad4539b8 100644
--- a/site/src/clients/chatgpt/server/catalog.ts
+++ b/site/src/clients/chatgpt/server/catalog.ts
@@ -58,6 +58,7 @@ export const READ_COMMANDS = new Set([
"watch_video",
"capture_frame",
"compare_to_source",
+ "suggest_font",
"listen_audio",
"detect_silence",
"detect_beats",
diff --git a/site/src/cut/components/AiPanel.tools.ts b/site/src/cut/components/AiPanel.tools.ts
index e6488525..6bea6f45 100644
--- a/site/src/cut/components/AiPanel.tools.ts
+++ b/site/src/cut/components/AiPanel.tools.ts
@@ -159,6 +159,29 @@ export const AI_PANEL_TOOLS = [
["asset_id", "times"]
),
},
+ {
+ name: "suggest_font",
+ description:
+ "Name the face a reference's type is set in: reads the source's frame at t, lifts the ink inside region off its ground, and ranks every face Donkey can set a title in — each bundled family at each bundled weight, the system set and the account's own fonts — by how closely its glyphs for the same words match, tracking solved so each runs as wide as the reference. Call it for each distinct face while rebuilding a reference's titles, so the font, weight, size and tracking come from the frame. Pass the words exactly as they read, case and line breaks included, and a region close around them read off watch_video at detail original. Returns the best faces with score (0..1), size (px at the 1080 short side, for the same ink height) and tracking (em), plus the ink's box in frame fractions. verdict no_match means nothing bundled is close: the reference uses a face Donkey does not bundle, so say so and name the stand-in you use.",
+ inputSchema: obj(
+ {
+ asset_id: str("Project asset id of the reference (video or image)"),
+ t: num("Source second the type shows at (default 0)"),
+ region: obj(
+ {
+ x: num("Left edge, frame fraction"),
+ y: num("Top edge, frame fraction"),
+ w: num("Width, frame fraction"),
+ h: num("Height, frame fraction"),
+ },
+ ["x", "y", "w", "h"]
+ ),
+ text: str("The words the region shows, as they read, with a line break where the type breaks"),
+ count: num("How many faces to return, 1..10 (default 5)"),
+ },
+ ["asset_id", "region", "text"]
+ ),
+ },
{
name: "find_highlights",
description:
diff --git a/site/src/cut/components/RequireSession.tsx b/site/src/cut/components/RequireSession.tsx
index 0834c04f..24c5766c 100644
--- a/site/src/cut/components/RequireSession.tsx
+++ b/site/src/cut/components/RequireSession.tsx
@@ -4,6 +4,7 @@ import { bindCutColor } from "@/cut/lib/colorSettings";
import { bindCutExportPasses } from "@/cut/lib/exportPassSettings";
import { bindCutSound } from "@/cut/lib/soundSettings";
import { bindCutMotion } from "@/cut/lib/motionSettings";
+import { bindCutFontMatch } from "@/cut/lib/fontMatchSettings";
import { bindCutLoudness } from "@/cut/lib/loudnessSettings";
import { bindCutMediaCache } from "@/cut/lib/chunkCache";
@@ -56,6 +57,7 @@ export function RequireSession({ children }: { children: ReactNode }) {
bindCutColor(config.data.settings.cutColor);
bindCutSound(config.data.settings.cutSound);
bindCutMotion(config.data.settings.cutMotion);
+ bindCutFontMatch(config.data.settings.cutFontMatch);
bindCutLoudness(config.data.settings.cutLoudness);
bindCutExportPasses(config.data.settings.cutExportPasses);
bindCutMediaCache(config.data.settings.cutMediaCache);
diff --git a/site/src/cut/lib/aiTools.ts b/site/src/cut/lib/aiTools.ts
index 6c611ad0..3b336cf5 100644
--- a/site/src/cut/lib/aiTools.ts
+++ b/site/src/cut/lib/aiTools.ts
@@ -236,7 +236,9 @@ import { playheadAt } from "./playhead";
import { mixSpecFor, renderProjectFrame, renderProjectFrames } from "./exportRender";
import { renderMix } from "./audioMix";
import { measureLoudnessSliced, roundedLoudness, type LoudnessMeasure } from "./loudness";
-import { framesAt, readMediaFileSize } from "./mediaRead";
+import { frameAt, framesAt, readMediaFileSize } from "./mediaRead";
+import { bundledFaces, inkMaskOf, rankFaces } from "./fontMatch";
+import { cutFontMatch } from "./fontMatchSettings";
import { renderStageFrame, storeStageStill } from "./stageFrame";
import { createRasterCanvas, decodeRasterImageUrl, rasterCanvasToDataUrl } from "./raster";
import { buildAiContext, describeCameraCard, describeDoc, hiddenFromChat, OTHER_CHATS_MEDIA_NOTE, roundT } from "./aiContext";
@@ -307,6 +309,7 @@ import {
clampOverlayPos,
previewUrl,
clipZoom,
+ fontStack,
frameOf,
IMAGE_CLIP_SECONDS,
isEffectOverlay,
@@ -576,6 +579,14 @@ const MAX_BLOCKS = 40;
// Each moment is two frames drawn and one picture composed; a handful at a
// time keeps the call inside the bridge's deadline and the reply readable.
const MAX_COMPARE = 4;
+/** Faces suggest_font hands back by default, and at most. */
+const FONT_SUGGESTIONS = 5;
+const FONT_SUGGESTIONS_MAX = 10;
+/** The longest side a suggest_font crop is read at, px: type this tall is
+ * already far finer than the grid it is scored on. */
+const FONT_CROP_MAX = 1600;
+/** Design px on a frame's short side, the unit a title's size is in. */
+const DESIGN_SHORT_SIDE = 1080;
const clamp = (v: number, lo: number, hi: number) => Math.max(lo, Math.min(hi, v));
const isNum = (v: unknown): v is number => typeof v === "number" && Number.isFinite(v);
@@ -1771,6 +1782,89 @@ const toolRuns: Record<BrowserToolName, ToolRun> = {
};
},
+ suggest_font: async (s, input) => {
+ // Which bundled face a reference's type is set in: its ink in the
+ // region against every face this process can draw, set in the same
+ // words. Reads one frame of the source.
+ const asset = requireItem(s.assets, input.asset_id, "project asset");
+ if (asset.type === "audio")
+ throw new ToolError(`"${asset.name}" is audio — it has no type to read. Pass the video or image the words show on.`);
+ const text = typeof input.text === "string" ? input.text.trim() : "";
+ if (!text) throw new ToolError("Pass text: the words the region shows, as they read, with a line break where the type breaks.");
+ const r = (input.region ?? {}) as Record<string, unknown>;
+ if (![r.x, r.y, r.w, r.h].every(isNum) || !((r.w as number) > 0 && (r.h as number) > 0))
+ throw new ToolError("Pass region: {x, y, w, h} in frame fractions, x/y its top-left corner, around the type and little else.");
+ const t = clamp(isNum(input.t) ? input.t : 0, 0, Math.max(0, asset.duration - 0.001));
+
+ // The frame, then the region of it at a size the scoring can use.
+ let source: CanvasImageSource;
+ let fw: number;
+ let fh: number;
+ if (asset.type === "image") {
+ const img = await decodeRasterImageUrl(asset.url);
+ if (!img) throw new ToolError(`Could not read "${asset.name}".`);
+ ({ source, width: fw, height: fh } = img);
+ } else {
+ const frame = await frameAt(asset.url, t).catch((e) => {
+ throw new ToolError(e instanceof Error ? e.message : `Could not read "${asset.name}".`, { cause: e });
+ });
+ if (!frame) throw new ToolError(`Could not read "${asset.name}" at ${round2(t)}s.`);
+ source = frame.canvas as CanvasImageSource;
+ fw = frame.canvas.width;
+ fh = frame.canvas.height;
+ }
+ const x0 = clamp(r.x as number, 0, 1) * fw;
+ const y0 = clamp(r.y as number, 0, 1) * fh;
+ const sw = Math.max(1, Math.min(fw - x0, (r.w as number) * fw));
+ const sh = Math.max(1, Math.min(fh - y0, (r.h as number) * fh));
+ const k = Math.min(1, FONT_CROP_MAX / Math.max(sw, sh));
+ const cw = Math.max(1, Math.round(sw * k));
+ const ch = Math.max(1, Math.round(sh * k));
+ const crop = createRasterCanvas(cw, ch);
+ const ctx = crop.getContext("2d") as CanvasRenderingContext2D | null;
+ if (!ctx) throw new ToolError("No 2D context to read the frame on.");
+ ctx.drawImage(source, x0, y0, sw, sh, 0, 0, cw, ch);
+ const ref = inkMaskOf(ctx.getImageData(0, 0, cw, ch).data, cw, ch);
+ crop.width = 0;
+ if (!ref.box)
+ throw new ToolError("No type stands out from its ground in that region. Check where the words sit with watch_video at detail original, then pass a region around them.");
+
+ // Every face ranked; the size each would need to fill the ink's height.
+ const ranked = await rankFaces(ref, text, bundledFaces(), fontStack).catch((e) => {
+ throw new ToolError(e instanceof Error ? e.message : "Could not set the faces.", { cause: e });
+ });
+ const count = Math.round(clamp(isNum(input.count) ? input.count : FONT_SUGGESTIONS, 1, FONT_SUGGESTIONS_MAX));
+ const labels = new Map(allFonts().map((f) => [f.id, f.label]));
+ const matches = ranked.slice(0, count).map((m) => ({
+ font: m.font,
+ label: labels.get(m.font) ?? m.font,
+ weight: m.weight,
+ ...(m.italic ? { italic: true } : {}),
+ score: m.score,
+ size: m.typePx > 0 ? Math.round((m.typePx / k / Math.min(fw, fh)) * DESIGN_SHORT_SIDE) : null,
+ tracking: m.tracking,
+ }));
+ const good = cutFontMatch().goodScore;
+ const best = matches[0];
+ const round3 = (v: number) => Math.round(v * 1000) / 1000;
+ return {
+ t: round2(t),
+ text,
+ ink: {
+ x: round3((x0 + ref.box.x / k) / fw),
+ y: round3((y0 + ref.box.y / k) / fh),
+ w: round3(ref.box.w / k / fw),
+ h: round3(ref.box.h / k / fh),
+ },
+ verdict: best && best.score >= good ? "match" : "no_match",
+ matches,
+ note:
+ best && best.score >= good
+ ? `${best.label} ${best.weight}${best.italic ? " italic" : ""} matches (a match scores ${good}+). Set it with its weight, size (px at the 1080 short side, for the same ink height) and tracking (em); faces scoring near it are close cuts worth a look with compare_to_source.`
+ : `Nothing bundled matches closely (best ${best?.score ?? 0}; a match scores ${good}+), so the reference is likely set in a face Donkey does not bundle. Tell the user so, name the closest face here as the stand-in you use, and say the Library takes their own font files.`,
+ };
+ },
+
detect_beats: async (s, input) => {
const { asset, clip, speed, from, to } = resolveWatchRange(s, input);
if (assetIsSilent(asset)) throw new ToolError(`"${asset.name}" carries no audio.`);
@@ -5777,6 +5871,7 @@ export const MEDIA_RUNTIME_TOOLS: ReadonlySet<string> = new Set([
"sync_audio",
"capture_frame",
"compare_to_source",
+ "suggest_font",
"render_preview",
"freeze_frame",
"create_sticker",
diff --git a/site/src/cut/lib/fontCatalog.test.ts b/site/src/cut/lib/fontCatalog.test.ts
new file mode 100644
index 00000000..8a97e408
--- /dev/null
+++ b/site/src/cut/lib/fontCatalog.test.ts
@@ -0,0 +1,22 @@
+import { expect, test } from "bun:test";
+import { readFileSync } from "node:fs";
+import { GOOGLE_FONTS } from "./fontCatalog";
+
+// The catalog's weights are the faces googleFonts.ts declares for the page, so
+// a font suggestion never offers a weight the page would draw synthesized.
+
+const declared = readFileSync(new URL("./googleFonts.ts", import.meta.url), "utf8");
+const faces = (style: "normal" | "italic") =>
+ new Set(
+ [...declared.matchAll(/@fontsource\/([a-z0-9-]+)\/(\d+)(-italic)?\.css/g)]
+ .filter((m) => (style === "italic") === Boolean(m[3]))
+ .map((m) => `${m[1]}/${m[2]}`)
+ );
+const pkg = (label: string) => label.toLowerCase().replace(/[^a-z0-9]+/g, "-");
+
+test("every bundled family lists the weights the page declares", () => {
+ const listed = new Set(GOOGLE_FONTS.flatMap((f) => f.weights.map((w) => `${pkg(f.label)}/${w}`)));
+ expect(listed).toEqual(faces("normal"));
+ const italics = new Set(GOOGLE_FONTS.flatMap((f) => (f.italics ?? []).map((w) => `${pkg(f.label)}/${w}`)));
+ expect(italics).toEqual(faces("italic"));
+});
diff --git a/site/src/cut/lib/fontCatalog.ts b/site/src/cut/lib/fontCatalog.ts
index f40d7ff7..1a74f4fe 100644
--- a/site/src/cut/lib/fontCatalog.ts
+++ b/site/src/cut/lib/fontCatalog.ts
@@ -4,46 +4,51 @@
* `googleFonts.ts` registers this list for the page, and the assistant's
* catalog builds its font sentence from it, so the menu the user sees and the
* ids the model is taught can't drift apart. A label is the family's own name,
- * the one its stylesheet and the headless renderer declare it under.
+ * the one its stylesheet and the headless renderer declare it under. The
+ * weights are the faces bundled, so a font suggestion only offers those.
* Framework-free on purpose: the server imports it too.
*/
export interface BundledFont {
id: string;
label: string;
+ /** The upright weights bundled, as googleFonts.ts declares them. */
+ weights: number[];
+ /** The weights bundled in italic too. */
+ italics?: number[];
}
export const GOOGLE_FONTS: BundledFont[] = [
- { id: "inter", label: "Inter" },
- { id: "montserrat", label: "Montserrat" },
- { id: "poppins", label: "Poppins" },
- { id: "oswald", label: "Oswald" },
- { id: "space-grotesk", label: "Space Grotesk" },
- { id: "playfair", label: "Playfair Display" },
- { id: "caveat", label: "Caveat" },
- { id: "bebas", label: "Bebas Neue" },
- { id: "anton", label: "Anton" },
- { id: "archivo-black", label: "Archivo Black" },
- { id: "bangers", label: "Bangers" },
- { id: "lobster", label: "Lobster" },
- { id: "pacifico", label: "Pacifico" },
- { id: "permanent-marker", label: "Permanent Marker" },
- { id: "dm-serif", label: "DM Serif Display" },
- { id: "amatic", label: "Amatic SC" },
- { id: "dseg14", label: "DSEG14 Classic" },
- { id: "outfit", label: "Outfit" },
- { id: "cinzel", label: "Cinzel" },
- { id: "freckle-face", label: "Freckle Face" },
- { id: "orbitron", label: "Orbitron" },
- { id: "chewy", label: "Chewy" },
- { id: "great-vibes", label: "Great Vibes" },
- { id: "rubik-dirt", label: "Rubik Dirt" },
- { id: "fredoka", label: "Fredoka" },
- { id: "oranienbaum", label: "Oranienbaum" },
- { id: "kaushan", label: "Kaushan Script" },
- { id: "rubik", label: "Rubik" },
- { id: "jost", label: "Jost" },
- { id: "gloria-hallelujah", label: "Gloria Hallelujah" },
+ { id: "inter", label: "Inter", weights: [400, 500, 600, 700] },
+ { id: "montserrat", label: "Montserrat", weights: [400, 500, 600, 700, 800, 900] },
+ { id: "poppins", label: "Poppins", weights: [400, 500, 600, 700, 800, 900] },
+ { id: "oswald", label: "Oswald", weights: [400, 500, 600, 700] },
+ { id: "space-grotesk", label: "Space Grotesk", weights: [400, 500, 600, 700] },
+ { id: "playfair", label: "Playfair Display", weights: [400, 500, 600, 700, 900], italics: [400, 700, 900] },
+ { id: "caveat", label: "Caveat", weights: [400, 500, 600, 700] },
+ { id: "bebas", label: "Bebas Neue", weights: [400] },
+ { id: "anton", label: "Anton", weights: [400] },
+ { id: "archivo-black", label: "Archivo Black", weights: [400] },
+ { id: "bangers", label: "Bangers", weights: [400] },
+ { id: "lobster", label: "Lobster", weights: [400] },
+ { id: "pacifico", label: "Pacifico", weights: [400] },
+ { id: "permanent-marker", label: "Permanent Marker", weights: [400] },
+ { id: "dm-serif", label: "DM Serif Display", weights: [400] },
+ { id: "amatic", label: "Amatic SC", weights: [400, 700] },
+ { id: "dseg14", label: "DSEG14 Classic", weights: [300, 700], italics: [300, 700] },
+ { id: "outfit", label: "Outfit", weights: [400, 500, 600, 700] },
+ { id: "cinzel", label: "Cinzel", weights: [400, 700] },
+ { id: "freckle-face", label: "Freckle Face", weights: [400] },
+ { id: "orbitron", label: "Orbitron", weights: [400, 900] },
+ { id: "chewy", label: "Chewy", weights: [400] },
+ { id: "great-vibes", label: "Great Vibes", weights: [400] },
+ { id: "rubik-dirt", label: "Rubik Dirt", weights: [400] },
+ { id: "fredoka", label: "Fredoka", weights: [500, 600, 700] },
+ { id: "oranienbaum", label: "Oranienbaum", weights: [400] },
+ { id: "kaushan", label: "Kaushan Script", weights: [400] },
+ { id: "rubik", label: "Rubik", weights: [400, 500, 700, 900] },
+ { id: "jost", label: "Jost", weights: [400, 500, 600, 700] },
+ { id: "gloria-hallelujah", label: "Gloria Hallelujah", weights: [400] },
];
export const GOOGLE_FONT_IDS = GOOGLE_FONTS.map((f) => f.id);
diff --git a/site/src/cut/lib/fontMatch.test.ts b/site/src/cut/lib/fontMatch.test.ts
new file mode 100644
index 00000000..0dee5214
--- /dev/null
+++ b/site/src/cut/lib/fontMatch.test.ts
@@ -0,0 +1,139 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { Canvas, FontLibrary } from "skia-canvas";
+
+/** skia's font registry, under a name the hook lint leaves alone. */
+const fontLibrary = FontLibrary;
+import { SETTINGS } from "@/lib/config/registry";
+import { setRasterFactory, type RasterFactory, type RasterSurface } from "./raster";
+import { inkMaskOf, rankFaces, type TitleFace } from "./fontMatch";
+import { fontStack, registerFonts } from "./types";
+
+// Which bundled face a piece of type on a reference frame is set in: the
+// reference's ink against each candidate's glyphs for the same words.
+
+const FILES = new URL("../../../node_modules/@fontsource/", import.meta.url).pathname;
+const FAMILIES: [id: string, pkg: string, label: string, weights: number[]][] = [
+ ["oswald", "oswald", "Oswald", [400, 700]],
+ ["montserrat", "montserrat", "Montserrat", [400, 900]],
+ ["anton", "anton", "Anton", [400]],
+ ["bebas", "bebas-neue", "Bebas Neue", [400]],
+ ["playfair", "playfair-display", "Playfair Display", [400, 700]],
+ ["lobster", "lobster", "Lobster", [400]],
+ ["cinzel", "cinzel", "Cinzel", [400, 700]],
+ ["great-vibes", "great-vibes", "Great Vibes", [400]],
+];
+
+const CANDIDATES: TitleFace[] = [
+ { font: "oswald", weight: 400 },
+ { font: "oswald", weight: 700 },
+ { font: "montserrat", weight: 400 },
+ { font: "montserrat", weight: 900 },
+ { font: "anton", weight: 400 },
+ { font: "bebas", weight: 400 },
+ { font: "playfair", weight: 400 },
+ { font: "playfair", weight: 700 },
+ { font: "lobster", weight: 400 },
+ { font: "cinzel", weight: 400 },
+];
+
+let restore: RasterFactory | undefined;
+beforeAll(() => {
+ for (const [id, pkg, label, weights] of FAMILIES) {
+ fontLibrary.use(label, weights.map((w) => `${FILES}${pkg}/files/${pkg}-latin-${w}-normal.woff2`));
+ registerFonts([{ id, label, stack: `"${label}"` }]);
+ }
+ restore = setRasterFactory({
+ createCanvas: (w, h) => new Canvas(Math.max(1, w), Math.max(1, h)) as unknown as RasterSurface,
+ decodeImage: async () => null,
+ canvasToBlob: async () => new Blob([]),
+ snapshot: async (c) => c as unknown as ImageBitmap,
+ });
+});
+afterAll(() => {
+ if (restore) setRasterFactory(restore);
+});
+
+/** A frame region holding `text` set in a face, ink on a plain ground. */
+function reference(text: string, css: string, opts: { tracking?: number; ink?: string; ground?: string } = {}) {
+ const c = new Canvas(1200, 260);
+ const ctx = c.getContext("2d");
+ ctx.fillStyle = opts.ground ?? "#1b2a3a";
+ ctx.fillRect(0, 0, c.width, c.height);
+ ctx.font = css;
+ const px = Number(/(\d+)px/.exec(css)![1]);
+ ctx.letterSpacing = `${(opts.tracking ?? 0) * px}px`;
+ ctx.fillStyle = opts.ink ?? "#f4efe6";
+ ctx.textBaseline = "middle";
+ text.split("\n").forEach((line, i, all) => ctx.fillText(line, 40, 130 + (i - (all.length - 1) / 2) * px * 1.3));
+ const data = ctx.getImageData(0, 0, c.width, c.height);
+ return inkMaskOf(data.data, data.width, data.height);
+}
+
+const good = SETTINGS.cutFontMatch.default.goodScore;
+
+describe("font suggestions", () => {
+ test("the face the words are set in ranks first, with its tracking", async () => {
+ const ref = reference("TRAVEL DESTINATION", '700 64px "Oswald"', { tracking: 0.12 });
+ const ranked = await rankFaces(ref, "TRAVEL DESTINATION", CANDIDATES, fontStack);
+ expect(ranked[0]).toMatchObject({ font: "oswald", weight: 700 });
+ expect(ranked[0].score).toBeGreaterThan(good);
+ expect(Math.abs(ranked[0].tracking - 0.12)).toBeLessThan(0.03);
+ });
+
+ test("small, soft, noisy type still finds its face", async () => {
+ // Set small, blown up 3× through a blur, with grain on top: a title read
+ // off a compressed 720p frame.
+ const small = new Canvas(400, 80);
+ const s = small.getContext("2d");
+ s.fillStyle = "#3a5068";
+ s.fillRect(0, 0, 400, 80);
+ s.font = '700 26px "Oswald"';
+ s.letterSpacing = "2.6px";
+ s.fillStyle = "#ffffff";
+ s.textBaseline = "middle";
+ s.fillText("TRAVEL DESTINATION", 10, 40);
+ const big = new Canvas(1200, 240);
+ const b = big.getContext("2d");
+ b.filter = "blur(2px)";
+ b.drawImage(small, 0, 0, 1200, 240);
+ const d = b.getImageData(0, 0, 1200, 240);
+ let seed = 7;
+ for (let i = 0; i < d.data.length; i += 4) {
+ seed = (seed * 1103515245 + 12345) % 2147483648;
+ const n = (seed / 2147483648 - 0.5) * 50;
+ for (let c = 0; c < 3; c++) d.data[i + c] = Math.max(0, Math.min(255, d.data[i + c] + n));
+ }
+ const ranked = await rankFaces(inkMaskOf(d.data, 1200, 240), "TRAVEL DESTINATION", CANDIDATES, fontStack);
+ expect(ranked[0]).toMatchObject({ font: "oswald", weight: 700 });
+ expect(ranked[0].score).toBeGreaterThan(good);
+ });
+
+ test("weight tells two cuts of one family apart", async () => {
+ const ref = reference("Travel Destination", '900 60px "Montserrat"');
+ const ranked = await rankFaces(ref, "Travel Destination", CANDIDATES, fontStack);
+ expect(ranked[0]).toMatchObject({ font: "montserrat", weight: 900 });
+ const light = ranked.find((m) => m.font === "montserrat" && m.weight === 400)!;
+ expect(light.score).toBeLessThan(ranked[0].score);
+ });
+
+ test("a face none of the candidates is scores under the good mark", async () => {
+ const ref = reference("Travel Destination", '400 90px "Great Vibes"');
+ const ranked = await rankFaces(ref, "Travel Destination", CANDIDATES, fontStack);
+ expect(ranked[0].score).toBeLessThan(good);
+ });
+
+ test("dark type on a light ground reads the same as light on dark", async () => {
+ const light = reference("DESTINATION", '400 80px "Anton"', { ink: "#111111", ground: "#f0f0f0" });
+ const dark = reference("DESTINATION", '400 80px "Anton"');
+ // The same box, give or take the pixel anti-aliasing lands on.
+ for (const k of ["x", "y", "w", "h"] as const) expect(Math.abs(light.box![k] - dark.box![k])).toBeLessThanOrEqual(1);
+ expect((await rankFaces(light, "DESTINATION", CANDIDATES, fontStack))[0].font).toBe("anton");
+ });
+
+ test("two lines are scored line by line, and a line count that differs is refused", async () => {
+ const ref = reference("TRAVEL\nDESTINATION", '400 60px "Cinzel"');
+ const ranked = await rankFaces(ref, "TRAVEL\nDESTINATION", CANDIDATES, fontStack);
+ expect(ranked[0]).toMatchObject({ font: "cinzel", weight: 400 });
+ await expect(rankFaces(ref, "TRAVEL DESTINATION", CANDIDATES, fontStack)).rejects.toThrow(/2 lines/);
+ });
+});
diff --git a/site/src/cut/lib/fontMatch.ts b/site/src/cut/lib/fontMatch.ts
new file mode 100644
index 00000000..44ab2e9c
--- /dev/null
+++ b/site/src/cut/lib/fontMatch.ts
@@ -0,0 +1,396 @@
+/**
+ * Which face a piece of type on a reference frame is set in.
+ *
+ * The reference's ink is lifted off its ground, cut to its bounding box and
+ * laid on a small grid; each candidate face sets the same words, its tracking
+ * solved so its ink runs as wide for its height as the reference's does, and
+ * goes on a grid the same size. The score is how much of the two grids' ink
+ * overlaps (soft IoU) times how close their widths come once the tracking is
+ * spent, so a condensed face that cannot stretch to a wide line scores low.
+ * Every face draws through the raster seam, so the page and a headless job
+ * rank alike.
+ */
+
+import { ensureFontLoaded, LETTER_SPACING_MAX, LETTER_SPACING_MIN, TEXT_WEIGHTS, type TextWeight } from "@donkeycut/effects-kit";
+import { GOOGLE_FONTS } from "./fontCatalog";
+import { createRasterCanvas, type RasterSurface } from "./raster";
+import { allFonts, FONTS, hasFont } from "./types";
+
+/** A face a title can be set in. */
+export interface TitleFace {
+ font: string;
+ weight: TextWeight;
+ italic?: boolean;
+}
+
+/** A face as it ranks against the reference. */
+export interface FaceMatch extends TitleFace {
+ /** 0..1: ink overlap times width agreement. */
+ score: number;
+ /** The letter spacing, em, that runs the face as wide as the reference. */
+ tracking: number;
+ /** The type size, in the reference's px, that sets its first line's ink
+ * as tall as the reference's. */
+ typePx: number;
+}
+
+/** Pixels in a box. */
+export interface InkBox {
+ x: number;
+ y: number;
+ w: number;
+ h: number;
+}
+
+/** A crop's ink: 1 where type is, 0 where its ground is, and the box the ink
+ * fills. */
+export interface InkMask {
+ w: number;
+ h: number;
+ ink: Uint8Array;
+ box: InkBox | null;
+}
+
+/** Type size every candidate is set at, px. */
+const PROBE_PX = 64;
+/** Grid rows both inks are laid on. */
+const GRID_ROWS = 40;
+/** A row or column whose ink is under this share of the fullest one is a
+ * speck, outside the box. */
+const SPECK = 0.02;
+/** The upright weights of the system set, which every host draws. */
+const BASE_WEIGHTS: Record<string, TextWeight[]> = { impact: [400] };
+const BASE_DEFAULT_WEIGHTS: TextWeight[] = [400, 700];
+
+/** Every face this process can draw a title in: the bundled families at their
+ * bundled weights (a lighter cut answers to 400, as a title asks for it), the
+ * system set, and the account's own fonts. */
+export function bundledFaces(): TitleFace[] {
+ const asTitle = (w: number) => TEXT_WEIGHTS.find((t) => t >= w) ?? 900;
+ const faces: TitleFace[] = [];
+ for (const f of FONTS) {
+ for (const weight of BASE_WEIGHTS[f.id] ?? BASE_DEFAULT_WEIGHTS) faces.push({ font: f.id, weight });
+ }
+ for (const f of GOOGLE_FONTS) {
+ if (!hasFont(f.id)) {
+ continue;
+ }
+ for (const w of new Set(f.weights.map(asTitle))) faces.push({ font: f.id, weight: w });
+ for (const w of new Set((f.italics ?? []).map(asTitle))) faces.push({ font: f.id, weight: w, italic: true });
+ }
+
+ // Fonts the account brought: one face each, drawn as the file sets it.
+ const known = new Set([...FONTS.map((f) => f.id), ...GOOGLE_FONTS.map((f) => f.id)]);
+ for (const f of allFonts()) {
+ if (!known.has(f.id)) faces.push({ font: f.id, weight: 400 });
+ }
+ return faces;
+}
+
+/** The ink in an RGBA crop. The ground is the colour its border mostly
+ * holds; ink is whatever sits far from it, split at the Otsu threshold of
+ * that distance, so light type on dark, dark on light and coloured type all
+ * read the same. */
+export function inkMaskOf(data: Uint8ClampedArray, w: number, h: number): InkMask {
+ const n = w * h;
+ const ground = borderMedian(data, w, h);
+
+ // Distance from the ground, 0..255, and its histogram.
+ const dist = new Uint8Array(n);
+ const hist = new Float64Array(256);
+ for (let i = 0; i < n; i++) {
+ const d = Math.max(
+ Math.abs(data[i * 4] - ground[0]),
+ Math.abs(data[i * 4 + 1] - ground[1]),
+ Math.abs(data[i * 4 + 2] - ground[2])
+ );
+ dist[i] = d;
+ hist[d]++;
+ }
+ const cut = Math.max(24, otsu(hist, n));
+ const ink = new Uint8Array(n);
+ for (let i = 0; i < n; i++) ink[i] = dist[i] > cut ? 1 : 0;
+ return { w, h, ink, box: inkBoxOf(ink, w, h, { x: 0, y: 0, w, h }) };
+}
+
+/** Rank `faces` by how closely each sets `text` the way the reference's ink
+ * shows it, best first. A text with line breaks is scored line by line
+ * against the reference's rows of ink, which have to number the same. */
+export async function rankFaces(
+ ref: InkMask,
+ text: string,
+ faces: TitleFace[],
+ fontStack: (font: string) => string
+): Promise<FaceMatch[]> {
+ if (!ref.box) throw new Error("No type stands out from its ground in that region.");
+ const lines = text.split("\n").map((l) => l.trim()).filter(Boolean);
+ if (lines.length === 0) throw new Error("Pass the words the region shows.");
+ const bands = bandsOf(ref, ref.box);
+ if (bands.length !== lines.length)
+ throw new Error(
+ `The region holds ${lines_(bands.length)} of ink and the text has ${lines_(lines.length)}. Pass the text with a line break where the type breaks, or a region around one line.`
+ );
+
+ // The reference lines on their grids, once.
+ const refs = bands.map((b) => {
+ const cols = gridCols(b);
+ return { box: b, cols, grid: soften(gridOf(ref.ink, ref.w, b, cols), cols) };
+ });
+ const widest = Math.max(...bands.map((b) => b.w));
+
+ const inkWidth = bands.reduce((sum, b) => sum + b.w, 0);
+
+ // Each face sets every line; a line counts by how wide its ink runs.
+ const probe = new Probe();
+ const ranked: FaceMatch[] = [];
+ try {
+ for (const face of faces) {
+ const css = `${face.italic ? "italic " : ""}${face.weight} ${PROBE_PX}px ${fontStack(face.font)}`;
+ await ensureFontLoaded(css, lines.join(" "));
+ let score = 0;
+ let tracking = 0;
+ let typePx = 0;
+ for (let i = 0; i < lines.length; i++) {
+ const m = fitLine(probe, css, lines[i], refs[i]);
+ score += (m.score * refs[i].box.w) / inkWidth;
+ if (refs[i].box.w === widest) tracking = m.tracking;
+ if (i === 0 && m.inkPerPx > 0) typePx = refs[0].box.h / m.inkPerPx;
+ }
+ ranked.push({ ...face, score: Math.round(score * 1000) / 1000, tracking: Math.round(tracking * 1000) / 1000, typePx });
+ }
+ } finally {
+ probe.close();
+ }
+ return ranked.sort((a, b) => b.score - a.score);
+}
+
+/** One line set in one face against one reference line: tracking solved
+ * from the width its ink runs at tracking 0. */
+function fitLine(
+ probe: Probe,
+ css: string,
+ line: string,
+ ref: { box: InkBox; cols: number; grid: Float32Array }
+): { score: number; tracking: number; inkPerPx: number } {
+ const flat = probe.set(css, line, 0);
+ if (!flat) return { score: 0, tracking: 0, inkPerPx: 0 };
+
+ // Letter spacing adds a step between each pair of characters.
+ // Example: ink 600 wide and 60 tall against a reference 12:1 wants
+ // 720, so 11 gaps at 64px take 120/704 ≈ 0.17em.
+ const gaps = [...line].length - 1;
+ const aspect = ref.box.w / ref.box.h;
+ const wanted = gaps > 0 && probe.tracks ? (aspect * flat.box.h - flat.box.w) / (gaps * PROBE_PX) : 0;
+ const tracking = Math.max(LETTER_SPACING_MIN, Math.min(LETTER_SPACING_MAX, wanted));
+ const set = Math.abs(tracking) > 0.005 ? (probe.set(css, line, tracking) ?? flat) : flat;
+
+ const grid = gridOf(set.ink, set.w, set.box, ref.cols);
+ const own = set.box.w / set.box.h;
+ const widthAgree = Math.min(own, aspect) / Math.max(own, aspect);
+ return { score: softIou(ref.grid, soften(grid, ref.cols)) * widthAgree, tracking: set === flat ? 0 : tracking, inkPerPx: flat.box.h / PROBE_PX };
+}
+
+/** "1 line", "2 lines". */
+const lines_ = (n: number) => `${n} line${n === 1 ? "" : "s"}`;
+
+/** The canvas candidates are set on, grown to the widest line asked for and
+ * released when the ranking ends. */
+class Probe {
+ private canvas: RasterSurface | null = null;
+ private ctx: CanvasRenderingContext2D | null = null;
+ /** Whether this surface spaces letters; without it every face sets at 0. */
+ tracks = false;
+
+ set(css: string, line: string, tracking: number): (InkMask & { box: InkBox }) | null {
+ const w = Math.ceil(PROBE_PX * ([...line].length * (1.4 + Math.max(0, tracking)) + 2));
+ const h = PROBE_PX * 2;
+ if (!this.canvas || this.canvas.width < w) {
+ this.canvas = createRasterCanvas(w, h);
+ this.ctx = this.canvas.getContext("2d") as CanvasRenderingContext2D | null;
+ this.tracks = Boolean(this.ctx && "letterSpacing" in this.ctx);
+ }
+ const ctx = this.ctx;
+ if (!ctx) throw new Error("No 2D context to set type on.");
+ const cw = this.canvas.width;
+ ctx.clearRect(0, 0, cw, h);
+ ctx.font = css;
+ if (this.tracks) ctx.letterSpacing = `${tracking * PROBE_PX}px`;
+ ctx.fillStyle = "#ffffff";
+ ctx.textBaseline = "middle";
+ ctx.textAlign = "left";
+ ctx.fillText(line, PROBE_PX / 2, h / 2);
+
+ const data = ctx.getImageData(0, 0, cw, h).data;
+ const ink = new Uint8Array(cw * h);
+ for (let i = 0; i < ink.length; i++) ink[i] = data[i * 4 + 3] > 127 ? 1 : 0;
+ const box = inkBoxOf(ink, cw, h, { x: 0, y: 0, w: cw, h });
+ return box ? { w: cw, h, ink, box } : null;
+ }
+
+ close(): void {
+ if (this.canvas) {
+ this.canvas.width = 0;
+ this.canvas.height = 0;
+ }
+ this.canvas = null;
+ this.ctx = null;
+ }
+}
+
+/** The median colour of a crop's outermost pixels. */
+function borderMedian(data: Uint8ClampedArray, w: number, h: number): [number, number, number] {
+ const r: number[] = [];
+ const g: number[] = [];
+ const b: number[] = [];
+ const take = (x: number, y: number) => {
+ const i = (y * w + x) * 4;
+ r.push(data[i]);
+ g.push(data[i + 1]);
+ b.push(data[i + 2]);
+ };
+ for (let x = 0; x < w; x++) {
+ take(x, 0);
+ take(x, h - 1);
+ }
+ for (let y = 1; y < h - 1; y++) {
+ take(0, y);
+ take(w - 1, y);
+ }
+ const mid = (v: number[]) => v.sort((p, q) => p - q)[v.length >> 1];
+ return [mid(r), mid(g), mid(b)];
+}
+
+/** The threshold that best splits a 256-bin histogram in two (Otsu). */
+function otsu(hist: Float64Array, total: number): number {
+ let sum = 0;
+ for (let i = 0; i < 256; i++) sum += i * hist[i];
+ let sumB = 0;
+ let wB = 0;
+ let best = 0;
+ let cut = 0;
+ for (let t = 0; t < 256; t++) {
+ wB += hist[t];
+ if (wB === 0) continue;
+ const wF = total - wB;
+ if (wF === 0) break;
+ sumB += t * hist[t];
+ const between = wB * wF * (sumB / wB - (sum - sumB) / wF) ** 2;
+ if (between > best) {
+ best = between;
+ cut = t;
+ }
+ }
+ return cut;
+}
+
+/** The box the ink inside `within` fills, specks left out. */
+function inkBoxOf(ink: Uint8Array, w: number, h: number, within: InkBox): InkBox | null {
+ const rows = new Float64Array(within.h);
+ const cols = new Float64Array(within.w);
+ for (let y = 0; y < within.h; y++) {
+ const off = (within.y + y) * w + within.x;
+ for (let x = 0; x < within.w; x++) {
+ if (ink[off + x]) {
+ rows[y]++;
+ cols[x]++;
+ }
+ }
+ }
+ const span = (v: Float64Array) => {
+ const floor = Math.max(1, Math.max(...v) * SPECK);
+ let a = 0;
+ while (a < v.length && v[a] < floor) a++;
+ let b = v.length - 1;
+ while (b > a && v[b] < floor) b--;
+ return a < v.length ? [a, b] : null;
+ };
+ const ys = span(rows);
+ const xs = span(cols);
+ if (!ys || !xs) return null;
+ return { x: within.x + xs[0], y: within.y + ys[0], w: xs[1] - xs[0] + 1, h: ys[1] - ys[0] + 1 };
+}
+
+/** The rows of ink inside a box, split where a run of empty rows parts them. */
+function bandsOf(ref: InkMask, box: InkBox): InkBox[] {
+ const rows: number[] = [];
+ for (let y = 0; y < box.h; y++) {
+ let n = 0;
+ const off = (box.y + y) * ref.w + box.x;
+ for (let x = 0; x < box.w; x++) n += ref.ink[off + x];
+ rows.push(n);
+ }
+ const floor = Math.max(1, Math.max(...rows) * SPECK);
+ const bands: InkBox[] = [];
+ let start = -1;
+ for (let y = 0; y <= rows.length; y++) {
+ const on = y < rows.length && rows[y] >= floor;
+ if (on && start < 0) start = y;
+ if (!on && start >= 0) {
+ const band = inkBoxOf(ref.ink, ref.w, ref.h, { x: box.x, y: box.y + start, w: box.w, h: y - start });
+ if (band) bands.push(band);
+ start = -1;
+ }
+ }
+ // A sliver of a band is a descender or an accent that broke loose.
+ const tallest = Math.max(...bands.map((b) => b.h));
+ return bands.filter((b) => b.h >= tallest * 0.25);
+}
+
+/** Grid columns for a box: its shape at GRID_ROWS rows. */
+const gridCols = (b: InkBox) => Math.max(4, Math.min(640, Math.round((GRID_ROWS * b.w) / b.h)));
+
+/** A box of ink averaged onto a GRID_ROWS × cols grid, each cell the share
+ * of ink in the stretch of the box it covers. */
+function gridOf(ink: Uint8Array, w: number, box: InkBox, cols: number): Float32Array {
+ const grid = new Float32Array(GRID_ROWS * cols);
+ const edge = (i: number, n: number, of: number) => Math.floor((i * of) / n);
+ for (let gy = 0; gy < GRID_ROWS; gy++) {
+ const y0 = edge(gy, GRID_ROWS, box.h);
+ const y1 = Math.max(y0 + 1, edge(gy + 1, GRID_ROWS, box.h));
+ for (let gx = 0; gx < cols; gx++) {
+ const x0 = edge(gx, cols, box.w);
+ const x1 = Math.max(x0 + 1, edge(gx + 1, cols, box.w));
+ let sum = 0;
+ for (let y = y0; y < y1; y++) {
+ const off = (box.y + y) * w + box.x;
+ for (let x = x0; x < x1; x++) sum += ink[off + x];
+ }
+ grid[gy * cols + gx] = sum / ((y1 - y0) * (x1 - x0));
+ }
+ }
+ return grid;
+}
+
+/** A grid with each cell averaged with its neighbours, so ink a cell off
+ * still overlaps. */
+function soften(grid: Float32Array, cols: number): Float32Array {
+ const out = new Float32Array(grid.length);
+ for (let y = 0; y < GRID_ROWS; y++) {
+ for (let x = 0; x < cols; x++) {
+ let sum = 0;
+ let n = 0;
+ for (let dy = -1; dy <= 1; dy++) {
+ for (let dx = -1; dx <= 1; dx++) {
+ const yy = y + dy;
+ const xx = x + dx;
+ if (yy < 0 || yy >= GRID_ROWS || xx < 0 || xx >= cols) continue;
+ sum += grid[yy * cols + xx];
+ n++;
+ }
+ }
+ out[y * cols + x] = sum / n;
+ }
+ }
+ return out;
+}
+
+/** Overlap of two soft masks: Σmin / Σmax. */
+function softIou(a: Float32Array, b: Float32Array): number {
+ let lo = 0;
+ let hi = 0;
+ for (let i = 0; i < a.length; i++) {
+ lo += Math.min(a[i], b[i]);
+ hi += Math.max(a[i], b[i]);
+ }
+ return hi > 0 ? lo / hi : 0;
+}
diff --git a/site/src/cut/lib/fontMatchSettings.ts b/site/src/cut/lib/fontMatchSettings.ts
new file mode 100644
index 00000000..5d698832
--- /dev/null
+++ b/site/src/cut/lib/fontMatchSettings.ts
@@ -0,0 +1,16 @@
+import { SETTINGS, type Settings } from "@/lib/config/registry";
+
+// Font-suggestion tunables — the score a bundled face has to reach to count as
+// the reference's face — bound once at session start from account config (the
+// tab) or the global setting (a worker job).
+
+let fontMatch: Settings["cutFontMatch"] = SETTINGS.cutFontMatch.default;
+
+export function bindCutFontMatch(value: unknown): void {
+ const parsed = SETTINGS.cutFontMatch.schema.safeParse(value);
+ if (parsed.success) fontMatch = parsed.data;
+}
+
+export function cutFontMatch(): Settings["cutFontMatch"] {
+ return fontMatch;
+}
diff --git a/site/src/cut/lib/googleFonts.ts b/site/src/cut/lib/googleFonts.ts
index 264ce376..8aaabc0d 100644
--- a/site/src/cut/lib/googleFonts.ts
+++ b/site/src/cut/lib/googleFonts.ts
@@ -91,4 +91,4 @@ import "@fontsource/gloria-hallelujah/400.css";
import { GOOGLE_FONTS } from "./fontCatalog";
import { registerFonts } from "./types";
-registerFonts(GOOGLE_FONTS.map((f) => ({ ...f, stack: `"${f.label}"` })));
+registerFonts(GOOGLE_FONTS.map((f) => ({ id: f.id, label: f.label, stack: `"${f.label}"` })));
diff --git a/site/src/cut/lib/pi/mutationLedger.ts b/site/src/cut/lib/pi/mutationLedger.ts
index 3d7ce412..d88f979e 100644
--- a/site/src/cut/lib/pi/mutationLedger.ts
+++ b/site/src/cut/lib/pi/mutationLedger.ts
@@ -13,6 +13,7 @@ const READ_ONLY = new Set([
"request_tools",
"capture_frame",
"compare_to_source",
+ "suggest_font",
"watch_video",
"note_source",
"detect_silence",
diff --git a/site/src/cut/lib/suggestFontTool.test.ts b/site/src/cut/lib/suggestFontTool.test.ts
new file mode 100644
index 00000000..a3671935
--- /dev/null
+++ b/site/src/cut/lib/suggestFontTool.test.ts
@@ -0,0 +1,109 @@
+import { afterAll, beforeAll, beforeEach, expect, test } from "bun:test";
+import { Canvas, FontLibrary } from "skia-canvas";
+
+/** skia's font registry, under a name the hook lint leaves alone. */
+const fontLibrary = FontLibrary;
+import { SETTINGS } from "@/lib/config/registry";
+import { stubModule } from "@/lib/testing/stubModule";
+import { setRasterFactory, type RasterFactory, type RasterSurface } from "./raster";
+import { registerFonts } from "./types";
+
+// suggest_font reads a reference's frame where its type sits and ranks the
+// faces Donkey can set a title in against it.
+
+const FILES = new URL("../../../node_modules/@fontsource/", import.meta.url).pathname;
+fontLibrary.use("Oswald", [400, 500, 600, 700].map((w) => `${FILES}oswald/files/oswald-latin-${w}-normal.woff2`));
+fontLibrary.use("Anton", [`${FILES}anton/files/anton-latin-400-normal.woff2`]);
+fontLibrary.use("Great Vibes", [`${FILES}great-vibes/files/great-vibes-latin-400-normal.woff2`]);
+
+/** What the reference shows: a 1920×1080 frame with one line of type. */
+let shows = { text: "TRAVEL DESTINATION", css: '700 72px "Oswald"' };
+const reads: number[] = [];
+async function frameAt(_src: string | Blob, time: number) {
+ reads.push(time);
+ const c = new Canvas(1920, 1080);
+ const ctx = c.getContext("2d");
+ ctx.fillStyle = "#20304a";
+ ctx.fillRect(0, 0, 1920, 1080);
+ ctx.font = shows.css;
+ ctx.fillStyle = "#ffffff";
+ ctx.textAlign = "center";
+ ctx.textBaseline = "middle";
+ ctx.fillText(shows.text, 960, 540);
+ return { canvas: c, timestamp: time, duration: 1 / 30 } as never;
+}
+await stubModule<typeof import("./mediaRead")>("./mediaRead", import.meta.url, { frameAt });
+
+const { runAiTool } = await import("./aiTools");
+const { useEditor } = await import("./store");
+
+let restore: RasterFactory | undefined;
+beforeAll(() => {
+ registerFonts([
+ { id: "oswald", label: "Oswald", stack: '"Oswald"' },
+ { id: "anton", label: "Anton", stack: '"Anton"' },
+ ]);
+ restore = setRasterFactory({
+ createCanvas: (w, h) => new Canvas(Math.max(1, w), Math.max(1, h)) as unknown as RasterSurface,
+ decodeImage: async () => null,
+ canvasToBlob: async () => new Blob([]),
+ snapshot: async (c) => c as unknown as ImageBitmap,
+ });
+});
+afterAll(() => {
+ if (restore) setRasterFactory(restore);
+});
+
+beforeEach(() => {
+ reads.length = 0;
+ shows = { text: "TRAVEL DESTINATION", css: '700 72px "Oswald"' };
+ useEditor.setState({
+ projectId: "p",
+ aspect: "16:9",
+ clips: [],
+ overlays: [],
+ audioClips: [],
+ assets: [
+ { id: "ref", fileName: "ref.mp4", name: "Reference", type: "video", duration: 20, url: "" },
+ { id: "song", fileName: "song.mp3", name: "Song", type: "audio", duration: 20, url: "" },
+ ],
+ } as never);
+});
+
+const REGION = { x: 0.2, y: 0.4, w: 0.6, h: 0.2 };
+type Out = {
+ verdict: string;
+ ink: { x: number; y: number; w: number; h: number };
+ matches: { font: string; weight: number; score: number; size: number; tracking: number }[];
+ note: string;
+};
+const message = async (p: Promise<unknown>) =>
+ p.then(() => "", (e: unknown) => (e instanceof Error ? e.message : String(e)));
+
+test("the face the reference is set in comes first, with the size that matches its ink", async () => {
+ const out = (await runAiTool("suggest_font", { asset_id: "ref", t: 3, region: REGION, text: "TRAVEL DESTINATION" })) as Out;
+ expect(reads).toEqual([3]);
+ expect(out.verdict).toBe("match");
+ expect(out.matches[0]).toMatchObject({ font: "oswald", weight: 700 });
+ // 72px type on a 1080-tall frame is 72px at the 1080 short side.
+ expect(Math.abs(out.matches[0].size - 72)).toBeLessThanOrEqual(3);
+ expect(Math.abs(out.matches[0].tracking)).toBeLessThan(0.03);
+ // The ink, in frame fractions, sits centred where it was drawn.
+ expect(Math.abs(out.ink.x + out.ink.w / 2 - 0.5)).toBeLessThan(0.01);
+ expect(out.matches.length).toBeLessThanOrEqual(5);
+});
+
+test("type in a face Donkey does not bundle is reported as that", async () => {
+ shows = { text: "Travel Destination", css: '400 110px "Great Vibes"' };
+ const out = (await runAiTool("suggest_font", { asset_id: "ref", t: 3, region: REGION, text: "Travel Destination" })) as Out;
+ expect(out.verdict).toBe("no_match");
+ expect(out.matches[0].score).toBeLessThan(SETTINGS.cutFontMatch.default.goodScore);
+ expect(out.note).toContain("does not bundle");
+});
+
+test("a region with no type, a sound, and missing words are refused", async () => {
+ expect(await message(runAiTool("suggest_font", { asset_id: "ref", t: 3, region: { x: 0, y: 0, w: 0.1, h: 0.1 }, text: "TRAVEL" }))).toContain("No type");
+ expect(await message(runAiTool("suggest_font", { asset_id: "song", t: 3, region: REGION, text: "TRAVEL" }))).toContain("audio");
+ expect(await message(runAiTool("suggest_font", { asset_id: "ref", t: 3, region: REGION, text: " " }))).toContain("text");
+ expect(await message(runAiTool("suggest_font", { asset_id: "ref", t: 3, region: { x: 0.5, y: 0.5, w: 0, h: 0.1 }, text: "TRAVEL" }))).toContain("region");
+});
diff --git a/site/src/cut/server/ai/catalog.ts b/site/src/cut/server/ai/catalog.ts
index c2d8e4c4..c3fabf5e 100644
--- a/site/src/cut/server/ai/catalog.ts
+++ b/site/src/cut/server/ai/catalog.ts
@@ -354,7 +354,7 @@ Someone points at a video — a file they imported, a link you brought in, a cli
**Block out the cuts.** \`sceneChanges\` are the cut times: shot 1 runs from 0 to the first, shot n from one to the next, the last to the end. add_clip with \`blocks\` lays the whole skeleton down in one call — one block per shot on track 0, each the length that shot runs, \`color\` set to what the reference has behind that shot and \`label\` naming what the person drops there. The label rides the timeline chip and the editor state; the frame itself shows the colour alone, so a shot never plays a sentence describing itself. A block is filled by dropping footage on it — it takes the block's place and its length — or with replace_item, so everything you build on top keeps its timing. Cuts timed to a reference are timed to what it sounds like, so that sound belongs on the soundtrack under them: detach_audio with the reference's \`assetId\` puts its whole track there and places none of its picture. When the ask is the reference's own picture playing, add_clip \`spans\` lays its shots down instead, one span per shot at those same times.
-**Rebuild the text as elements.** One add_title per card — the words exactly as they read, the face from the graphics skill's font ids, size in px at 1080 wide, and x/y as the fraction of the frame it sits at (a lower-third card is around y 0.75, a centered statement 0.5). A run of lines timed one after another is add_text_sequence in one call. Match the case the reference uses; match its weight and its color against the frame behind it.
+**Rebuild the text as elements.** One add_title per card — the words exactly as they read, size in px at 1080 wide, and x/y as the fraction of the frame it sits at (a lower-third card is around y 0.75, a centered statement 0.5). A run of lines timed one after another is add_text_sequence in one call. Match the case the reference uses, and its color against the frame behind it. 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 and tracking to set. Call it once per distinct face — 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. 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 you read 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 — which is how the timing lands on the reference's own frames. 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. add_shape is the rest of the graphics: bars, cards, rules, a block of color behind a line.
diff --git a/site/src/cut/server/ai/headlessTools.ts b/site/src/cut/server/ai/headlessTools.ts
index 09bd4b96..a38c41dd 100644
--- a/site/src/cut/server/ai/headlessTools.ts
+++ b/site/src/cut/server/ai/headlessTools.ts
@@ -39,6 +39,7 @@ const PAGE_MEDIA_TOOLS: ReadonlySet<string> = new Set([
"freeze_frame",
"capture_frame",
"compare_to_source",
+ "suggest_font",
"render_preview",
"create_sticker",
"subtitles_generate",
diff --git a/site/src/cut/worker/turnJob.ts b/site/src/cut/worker/turnJob.ts
index 70249a5b..b32399dd 100644
--- a/site/src/cut/worker/turnJob.ts
+++ b/site/src/cut/worker/turnJob.ts
@@ -4,6 +4,7 @@ import { bindCutClip, bindCutJudge } from "@/cut/lib/chatRuntime";
import { bindCutColor } from "@/cut/lib/colorSettings";
import { bindCutSound } from "@/cut/lib/soundSettings";
import { bindCutMotion } from "@/cut/lib/motionSettings";
+import { bindCutFontMatch } from "@/cut/lib/fontMatchSettings";
import { geminiModelRoleNames } from "@/lib/inference/gemini-models";
import { openCloudProject, pushCloudProject } from "../lib/headless/docSession";
import { dropPiSession, streamCutChat } from "../lib/pi/cutAgent";
@@ -115,6 +116,7 @@ export async function runTurnJob(
bindCutColor(await getGlobalSetting("cutColor"));
bindCutSound(await getGlobalSetting("cutSound"));
bindCutMotion(await getGlobalSetting("cutMotion"));
+ bindCutFontMatch(await getGlobalSetting("cutFontMatch"));
deps.judgeSettings = judgeSettings;
const toolCalls: string[] = [];
const exec = deps.execTool;
diff --git a/site/src/lib/config/registry.ts b/site/src/lib/config/registry.ts
index d7ddc392..01be573c 100644
--- a/site/src/lib/config/registry.ts
+++ b/site/src/lib/config/registry.ts
@@ -473,6 +473,14 @@ export const SETTINGS = defineSettings({
description:
"The shutter a newly switched-on motion blur starts at, as a share of a 30fps frame. 0.5 is the half-open shutter of most filmed footage; higher streaks harder.",
},
+ cutFontMatch: {
+ schema: z.object({ goodScore: z.number().min(0).max(1) }).strict(),
+ default: { goodScore: 0.72 },
+ public: true,
+ title: "Font suggestions",
+ description:
+ "The score (0..1, glyph overlap times width agreement) a bundled face has to reach before suggest_font calls it a match; under it the reference is reported as set in a face Donkey does not bundle.",
+ },
cutLoudness: {
schema: z
.object({