Skip to content

Open source CapCut alternative.

TypeScript

fix(site): a text sequence puts its words in front of the cards [rebuild]

David Le36ae0443c6cb
diff --git a/site/src/cut/components/EffectsPanel.tools.ts b/site/src/cut/components/EffectsPanel.tools.ts
index 605c8ae7..72e69b8d 100644
--- a/site/src/cut/components/EffectsPanel.tools.ts
+++ b/site/src/cut/components/EffectsPanel.tools.ts
@@ -27,7 +27,7 @@ export const EFFECTS_TOOLS = [
amount: num("Strength 0.05..1 (default 0.5). For zoom it is the depth: 0.25 shallow, 0.5 moderate, 1 deep"),
focus_x: num("Zoom only: the x of the point to zoom into, 0..1 (default 0.5)"),
focus_y: num("Zoom only: the y of the point to zoom into, 0..1 (default 0.5)"),
- lane: num("Element row (0 = the bottom row). Elements on one row never overlap — a title over a shape needs a higher row than the shape."),
+ lane: num("Element row (0 = the front row, drawn over every higher row). Elements on one row never overlap — a title over a shape needs a lower row than the shape."),
}, ["effect"]),
},
] as const satisfies readonly AiToolDef[];
diff --git a/site/src/cut/components/ElementsPanel.tools.ts b/site/src/cut/components/ElementsPanel.tools.ts
index 1b85a1a5..208c89da 100644
--- a/site/src/cut/components/ElementsPanel.tools.ts
+++ b/site/src/cut/components/ElementsPanel.tools.ts
@@ -33,7 +33,7 @@ export const ELEMENTS_TOOLS = [
stroke_width: num("Outline width px at 1080 short side (0 removes it)"),
rotation: num("Degrees clockwise, -180..180"),
opacity: num("Whole-element opacity 0..1"),
- lane: num("Element row (0 = the bottom row). Elements on one row never overlap — a title over a shape needs a higher row than the shape."),
+ lane: num("Element row (0 = the front row, drawn over every higher row). Elements on one row never overlap — a title over a shape needs a lower row than the shape."),
}, ["shape"]),
},
{
@@ -49,7 +49,7 @@ export const ELEMENTS_TOOLS = [
w: num("Width, fraction of frame width (default 0.25)"),
rotation: num("Degrees clockwise, -180..180"),
opacity: num("Whole-element opacity 0..1"),
- lane: num("Element row (0 = the bottom row). Elements on one row never overlap — a title over a shape needs a higher row than the shape."),
+ lane: num("Element row (0 = the front row, drawn over every higher row). Elements on one row never overlap — a title over a shape needs a lower row than the shape."),
}),
},
{
@@ -63,7 +63,7 @@ export const ELEMENTS_TOOLS = [
x: num("Center x 0..1 (default 0.5)"),
y: num("Center y 0..1 (default 0.5)"),
w: num("Width, fraction of frame width (default 0.25)"),
- lane: num("Element row (0 = the bottom row). Elements on one row never overlap — a title over a shape needs a higher row than the shape."),
+ lane: num("Element row (0 = the front row, drawn over every higher row). Elements on one row never overlap — a title over a shape needs a lower row than the shape."),
}, ["idea"]),
},
] as const satisfies readonly AiToolDef[];
diff --git a/site/src/cut/components/Inspector.tools.ts b/site/src/cut/components/Inspector.tools.ts
index f3dd3f66..797d4f9c 100644
--- a/site/src/cut/components/Inspector.tools.ts
+++ b/site/src/cut/components/Inspector.tools.ts
@@ -40,7 +40,7 @@ export const INSPECTOR_TOOLS = [
rotation: num("Degrees clockwise, -180..180 (0 clears)"),
opacity: num("Whole-element opacity 0..1 (1 clears)"),
hidden: bool("Hide the element without deleting it"),
- lane: num("Move the element to another row (0 = the bottom row). Elements on one row never overlap — a title over a shape needs a higher row than the shape."),
+ lane: num("Move the element to another row (0 = the front row, drawn over every higher row). Elements on one row never overlap — a title over a shape needs a lower row than the shape."),
}, ["id"]),
},
{
diff --git a/site/src/cut/components/Timeline.tools.ts b/site/src/cut/components/Timeline.tools.ts
index 4fab3985..a1326cf1 100644
--- a/site/src/cut/components/Timeline.tools.ts
+++ b/site/src/cut/components/Timeline.tools.ts
@@ -188,13 +188,13 @@ export const TIMELINE_TOOLS = [
plate: bool("Translucent plate behind text (default false)"),
rotation: num("Degrees clockwise, -180..180"),
opacity: num("Whole-element opacity 0..1"),
- lane: num("Element row (0 = the bottom row). Elements on one row never overlap — a title over a shape needs a higher row than the shape."),
+ lane: num("Element row (0 = the front row, drawn over every higher row). Elements on one row never overlap — a title over a shape needs a lower row than the shape."),
}, ["text"]),
},
{
name: "add_text_sequence",
description:
- "Place a run of text on the timeline in one call — a lyric video, a kinetic-typography passage, a quote sequence — styled by a named look. `look` carries the whole design: the frame color, the card colors it cycles line to line, the type, and how each line arrives (ids and what each is for are in the text-videos skill). Lines come from `lines` ({text, start, end} in timeline seconds, plus an optional color/size override per line), or from the caption track with from_captions when a sync already timed them. Cards land on `lane` and the words one row above, so they stack instead of sliding apart. It sets the project background to the look's frame color unless background is false — words over the user's own footage want a look with no cards, and the footage keeps playing underneath.",
+ "Place a run of text on the timeline in one call — a lyric video, a kinetic-typography passage, a quote sequence — styled by a named look. `look` carries the whole design: the frame color, the card colors it cycles line to line, the type, and how each line arrives (ids and what each is for are in the text-videos skill). Lines come from `lines` ({text, start, end} in timeline seconds, plus an optional color/size override per line), or from the caption track with from_captions when a sync already timed them. The words land on `lane` and each card on the row under them, so they stack instead of sliding apart. It sets the project background to the look's frame color unless background is false — words over the user's own footage want a look with no cards, and the footage keeps playing underneath.",
inputSchema: obj({
look: str("Look id from the text-videos skill (default lyric-card)"),
lines: {
@@ -212,7 +212,7 @@ export const TIMELINE_TOOLS = [
),
},
from_captions: num("Build the run from this caption track's cues (0-based) instead of `lines`"),
- lane: num("Row for the color cards; the words go one row above (default 0)"),
+ lane: num("Row for the words; their color cards go one row under them (default 0, the front row)"),
cards: bool("Paint the look's color cards behind each line (default: whatever the look does)"),
background: bool("Set the project background to the look's frame color (default true)"),
}),
diff --git a/site/src/cut/lib/aiTools.ts b/site/src/cut/lib/aiTools.ts
index 12dafc1b..8fbd669b 100644
--- a/site/src/cut/lib/aiTools.ts
+++ b/site/src/cut/lib/aiTools.ts
@@ -218,8 +218,8 @@ 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);
/** The row an element tool was aimed at, if it named one. Rows are how
- * elements stack: two on the same row slide clear of each other, so a title
- * that has to sit over a shape has to name a row above it. */
+ * elements stack, row 0 at the front: two on the same row slide clear of each
+ * other, so a title that has to sit over a shape names a lower row than it. */
const aimedLane = (input: Record<string, unknown>): { lane?: number } | undefined =>
isNum(input.lane) ? { lane: Math.max(0, Math.round(input.lane)) } : undefined;
@@ -1336,13 +1336,16 @@ const toolRuns: Record<BrowserToolName, ToolRun> = {
"Pass lines: [{text, start, end}], or from_captions: true to build the sequence from the caption track."
);
if (input.background !== false) s.setBackground(look.frame.background);
- const textLane = lane + (cards.length > 0 ? 1 : 0);
+ // Row 0 is the front of the element stack, so the words take the row the
+ // caller named and each card goes one row under them. Cards over words
+ // would paint the line out.
+ const cardLane = lane + 1;
const made: { id: string; start: number; end: number; text: string }[] = [];
lines.forEach((line, i) => {
const card = cards.length > 0 ? cards[i % cards.length] : null;
if (card) {
useEditor.getState().seek(line.start);
- useEditor.getState().addShape("rect", { lane });
+ useEditor.getState().addShape("rect", { lane: cardLane });
const sel = useEditor.getState().selection;
if (sel?.kind === "overlay")
applyOverlayPatchSettled(sel.id, {
@@ -1356,7 +1359,7 @@ const toolRuns: Record<BrowserToolName, ToolRun> = {
});
}
useEditor.getState().seek(line.start);
- useEditor.getState().addOverlay({ lane: textLane });
+ useEditor.getState().addOverlay({ lane });
const sel = useEditor.getState().selection;
if (sel?.kind !== "overlay") return;
const onCard =
@@ -1398,14 +1401,14 @@ const toolRuns: Record<BrowserToolName, ToolRun> = {
return {
look: look.id,
count: made.length,
- lanes: cards.length > 0 ? { cards: lane, text: textLane } : { text: textLane },
+ lanes: cards.length > 0 ? { cards: cardLane, text: lane } : { text: lane },
background: useEditor.getState().background,
items: made.slice(0, 40),
...(made.length > 40 ? { itemsTruncated: true } : {}),
note:
cards.length > 0
- ? `Cards on row ${lane}, words on row ${textLane}, colors cycling ${look.frame.cards.join(" → ")}.`
- : `Words on row ${textLane} over the ${look.frame.background} frame.`,
+ ? `Words on row ${lane} with their cards on row ${cardLane} behind them, colors cycling ${look.frame.cards.join(" → ")}.`
+ : `Words on row ${lane} over the ${look.frame.background} frame.`,
};
},
diff --git a/site/src/cut/lib/textVideo.test.ts b/site/src/cut/lib/textVideo.test.ts
index 01b24c4a..0b545624 100644
--- a/site/src/cut/lib/textVideo.test.ts
+++ b/site/src/cut/lib/textVideo.test.ts
@@ -39,8 +39,10 @@ describe("add_text_sequence", () => {
const words = overlays().filter(isTextOverlay);
expect(cards).toHaveLength(3);
expect(words).toHaveLength(3);
- expect(cards.map((c) => c.lane ?? 0)).toEqual([0, 0, 0]);
- expect(words.map((w) => w.lane ?? 0)).toEqual([1, 1, 1]);
+ // Row 0 is the front of the stack: the words own it and the cards sit a
+ // row behind, so a card never paints its own line out.
+ expect(words.map((w) => w.lane ?? 0)).toEqual([0, 0, 0]);
+ expect(cards.map((c) => c.lane ?? 0)).toEqual([1, 1, 1]);
expect(cards.map((c) => c.fill)).toEqual(look.frame.cards);
expect(words.map((w) => w.color)).toEqual(look.text.onCards!);
expect(words.map((w) => w.text)).toEqual(["first line", "second line", "third line"]);
diff --git a/site/src/cut/server/ai/catalog.ts b/site/src/cut/server/ai/catalog.ts
index 290d5f4b..67342c30 100644
--- a/site/src/cut/server/ai/catalog.ts
+++ b/site/src/cut/server/ai/catalog.ts
@@ -134,7 +134,7 @@ What the user sees on the transitions row: one badge per bar, and nothing else
"graphics": `# Graphics: titles, shapes & stickers
The title lanes hold three overlay element kinds, all sharing timing (start/end), center position (x/y fractions 0..1), rotation (degrees), opacity, and a lane; \`overlays\` in editor_state lists them with their \`kind\`. All burn into the export exactly as previewed.
-Rows are how elements stack (\`lane\`, 0 = bottom). Two elements on ONE row never overlap in time — placing a title where a shape already sits slides it clear instead of laying it on top — so anything meant to sit over something else names a higher row: background shape on lane 0, its title on lane 1. Every add tool and update_overlay take \`lane\`.
+Rows are how elements stack (\`lane\`, 0 = the front row; a higher row draws further back). Two elements on ONE row never overlap in time — placing a title where a shape already sits slides it clear instead of laying it on top — so anything meant to sit over something else names a LOWER row: title on lane 0, the background shape behind it on lane 1. Every add tool and update_overlay take \`lane\`.
The frame's own color is set_background, not a full-frame rectangle: it fills the frame behind every clip and element, holds for the whole cut, letterboxes fitted footage, and shows through gaps on track 0. "Make the background white", a colored card behind a title sequence, a text-and-graphics video with no footage at all — all of them start with set_background. A rectangle element is for a panel or a band inside the frame, not for the frame itself.
A whole run of text — a lyric video, a kinetic-typography passage, a quote sequence — is add_text_sequence, one call carrying a named look (frame color, card colors, type, motion): read the text-videos skill for the looks and the flow. A video needs no footage. Titles, shapes and stickers over a background color are a complete cut on their own: it plays, exports, and shares like any other. Build one by setting the background, then placing elements on the rows the stack needs — reach for footage only when the user asks for it.
Titles (add_title / update_overlay): text, size (frame px; the design short side is 1080), font (sf=SF Pro, serif=New York, rounded, mono, impact), weight (400/700), color, shadow, plate (translucent dark backdrop).
@@ -174,7 +174,7 @@ With no lyrics text, transcribe with subtitles_generate and work from the cues i
**Words over the user's footage.** Same flow, with the over-footage look (or any look with \`cards: false\`) and \`background: false\` — the clips keep playing and the words ride above them. Aim them off the caption band when captions are also on.
-**Words on plain color.** A cut with nothing on track 0 is a complete video: set the background, place the run, export. Cards are how the color changes line to line — the sequence paints one per line on its own row and puts the words on the row above, so they stack instead of sliding apart.
+**Words on plain color.** A cut with nothing on track 0 is a complete video: set the background, place the run, export. Cards are how the color changes line to line — the sequence paints one per line on its own row behind the words, so they stack instead of sliding apart.
**Timing.** One line per screen beats two. A line needs about 0.4s minimum to read; 1.5–2.5s is the normal beat for a spoken line, and a sung line takes whatever the vocal takes. Lines never overlap on a row — the sequence tool lays them end to end from the times you give it.