Skip to content

Open source CapCut alternative.

TypeScript

feat(site): the project owns the frame color [rebuild]

David Le4112dddac494
diff --git a/site/src/cut/components/EffectsPanel.tools.ts b/site/src/cut/components/EffectsPanel.tools.ts
index 055a63e0..605c8ae7 100644
--- a/site/src/cut/components/EffectsPanel.tools.ts
+++ b/site/src/cut/components/EffectsPanel.tools.ts
@@ -27,6 +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."),
}, ["effect"]),
},
] as const satisfies readonly AiToolDef[];
diff --git a/site/src/cut/components/EffectsPanel.tsx b/site/src/cut/components/EffectsPanel.tsx
index 9d8bd042..671d4259 100644
--- a/site/src/cut/components/EffectsPanel.tsx
+++ b/site/src/cut/components/EffectsPanel.tsx
@@ -15,7 +15,7 @@ import { PICKED_RING, pickGridNav, useAssetPick } from "@/cut/lib/assetPick";
import { clearElementDrag, setElementDragData, setObjectDragImage } from "@/cut/lib/assetDrag";
import { SubTabs } from "@/cut/components/SubTabs";
import { getPreviewCanvas } from "@/cut/lib/previewCanvas";
-import { useEditor } from "@/cut/lib/store";
+import { projectDuration, useEditor } from "@/cut/lib/store";
import { usePreviewTimeEvery } from "@/cut/lib/playhead";
import { isEffectOverlay, type EffectOverlay } from "@/cut/lib/types";
import { useLocalPref } from "@/cut/lib/uiState";
@@ -137,9 +137,11 @@ function usePlayheadFrame(): string | null {
);
const tick = usePreviewTimeEvery(5);
const epoch = useEditor((s) => s.loadEpoch);
- const hasClips = useEditor((s) => s.clips.length > 0);
+ // The tile shows the live frame, which a cut of titles and shapes over the
+ // background has as much as one made of footage.
+ const hasPicture = useEditor((s) => projectDuration(s) > 0);
useEffect(() => {
- if (!hasClips || !projectId) return;
+ if (!hasPicture || !projectId) return;
const t = setTimeout(() => {
const shot = snapshotPreview();
if (shot) {
@@ -148,8 +150,8 @@ function usePlayheadFrame(): string | null {
}
}, 160);
return () => clearTimeout(t);
- }, [tick, epoch, hasClips, projectId]);
- return hasClips ? frame : null;
+ }, [tick, epoch, hasPicture, projectId]);
+ return hasPicture ? frame : null;
}
/** One effect: the preview fills the tile with its name under it, a click
diff --git a/site/src/cut/components/ElementsPanel.tools.ts b/site/src/cut/components/ElementsPanel.tools.ts
index 561e831b..1b85a1a5 100644
--- a/site/src/cut/components/ElementsPanel.tools.ts
+++ b/site/src/cut/components/ElementsPanel.tools.ts
@@ -33,6 +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."),
}, ["shape"]),
},
{
@@ -48,6 +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."),
}),
},
{
@@ -61,6 +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."),
}, ["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 53da4a1a..f3dd3f66 100644
--- a/site/src/cut/components/Inspector.tools.ts
+++ b/site/src/cut/components/Inspector.tools.ts
@@ -40,6 +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."),
}, ["id"]),
},
{
diff --git a/site/src/cut/components/SidePanel.tools.ts b/site/src/cut/components/SidePanel.tools.ts
index 386d85ad..ff8adaf8 100644
--- a/site/src/cut/components/SidePanel.tools.ts
+++ b/site/src/cut/components/SidePanel.tools.ts
@@ -68,6 +68,12 @@ export const SIDE_PANEL_TOOLS = [
"Set the whole video's fade in from black and/or fade out to black, in seconds (0 clears, max 2). Applied to the final picture and mix at the start/end of the cut, independent of which clip sits there.",
inputSchema: obj({ fadeIn: num("Fade-in seconds (omit to keep)"), fadeOut: num("Fade-out seconds (omit to keep)") }),
},
+ {
+ name: "set_background",
+ description:
+ "Set the color of the video frame itself — what sits behind every clip and element. It fills the frame wherever no footage covers it: a cut made only of titles and shapes plays over it end to end, a fitted clip letterboxes into it, and a gap on track 0 shows it. Use this for \"make the background white/orange\" rather than laying a full-frame rectangle over the timeline. Default is black.",
+ inputSchema: obj({ color: str("Hex color, e.g. #FFFFFF") }, ["color"]),
+ },
] as const satisfies readonly AiToolDef[];
export type SidePanelToolName = (typeof SIDE_PANEL_TOOLS)[number]["name"];
diff --git a/site/src/cut/components/SidePanel.tsx b/site/src/cut/components/SidePanel.tsx
index 25e404e7..90160623 100644
--- a/site/src/cut/components/SidePanel.tsx
+++ b/site/src/cut/components/SidePanel.tsx
@@ -76,6 +76,7 @@ import { retryUpload } from "@/cut/lib/importQueue";
import { downloadMedia, isMediaFile, revealMedia } from "@/cut/lib/media";
import { mediaUrl, TRANSITION_MAX } from "@/cut/lib/types";
import { parseSecondsInput } from "@/cut/components/ScrubValue";
+import { ColorField } from "@/cut/components/ColorField";
import { ValueSlider } from "@/cut/components/ValueSlider";
import { genPulseOverlay, isGenTab, useGenNotify, useGenPulse, useWatchGenTab } from "@/cut/lib/genNotify";
import { useGenerate, type GenerateJob } from "@/cut/lib/generate";
@@ -1531,6 +1532,7 @@ function PublishPanel() {
const setNotes = useEditor((s) => s.setNotes);
const fadeIn = useEditor((s) => s.fadeIn);
const fadeOut = useEditor((s) => s.fadeOut);
+ const background = useEditor((s) => s.background);
const tagsLine = normalizeTags(publish.tags);
const combined = [publish.caption.trim(), tagsLine].filter(Boolean).join("\n\n");
const count = combined.length;
@@ -1553,6 +1555,16 @@ function PublishPanel() {
value={fadeOut}
onChange={(v) => useEditor.getState().setProjectFade({ fadeOut: v })}
/>
+ <div className="flex items-center justify-between gap-3 text-[12px] text-muted-foreground">
+ Background
+ <ColorField
+ value={background}
+ label="Background color"
+ onBegin={() => {}}
+ onLive={(c) => useEditor.getState().setBackground(c)}
+ onCommit={(c) => useEditor.getState().setBackground(c)}
+ />
+ </div>
</div>
)}
diff --git a/site/src/cut/components/Timeline.tools.ts b/site/src/cut/components/Timeline.tools.ts
index 488c2d2b..f2171f39 100644
--- a/site/src/cut/components/Timeline.tools.ts
+++ b/site/src/cut/components/Timeline.tools.ts
@@ -178,6 +178,7 @@ 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."),
}, ["text"]),
},
{
diff --git a/site/src/cut/components/TopBar.tsx b/site/src/cut/components/TopBar.tsx
index ddb92376..43995df9 100644
--- a/site/src/cut/components/TopBar.tsx
+++ b/site/src/cut/components/TopBar.tsx
@@ -32,7 +32,7 @@ import { clearProjectThreads } from "@/cut/lib/chatThreads";
import { retryUpload } from "@/cut/lib/importQueue";
import { backTarget, projectHref, useCutBase } from "@/cut/lib/nav";
import { copyProjectAcross } from "@/cut/lib/projectCopy";
-import { useEditor } from "@/cut/lib/store";
+import { projectDuration, useEditor } from "@/cut/lib/store";
import { useLocalPref } from "@/cut/lib/uiState";
import { ASPECT_PRESETS, aspectLabel, aspectOrientation, normalizeAspect, parseRatio, type Aspect } from "@/cut/lib/types";
import { cn } from "@/lib/utils";
@@ -62,7 +62,9 @@ export function TopBar({
}) {
const base = useCutBase();
const back = backTarget(base, from, folder);
- const hasClips = useEditor((s) => s.clips.length > 0);
+ // Something to render, which footage is only one way to have: a cut of
+ // titles and shapes over the background frame exports like any other.
+ const hasPicture = useEditor((s) => projectDuration(s) > 0);
const aspect = useEditor((s) => s.aspect);
const projectName = useEditor((s) => s.projectName);
const saveState = useEditor((s) => s.saveState);
@@ -353,7 +355,7 @@ export function TopBar({
// A render reads the saved document, which an import still uploading
// (or one that failed) is deliberately absent from — exporting now
// would quietly leave it out of the video.
- disabled={!hasClips || cloudUploading || failedImports > 0}
+ disabled={!hasPicture || cloudUploading || failedImports > 0}
title={
failedImports > 0
? "Retry the failed imports first"
@@ -655,7 +657,7 @@ export function TopBar({
</DropdownMenuItem>
)}
<DropdownMenuItem
- disabled={!hasClips || cloudUploading}
+ disabled={!hasPicture || cloudUploading}
onClick={() => {
const s = useEditor.getState();
s.setPlaying(false);
diff --git a/site/src/cut/hooks/usePlayback.ts b/site/src/cut/hooks/usePlayback.ts
index d23ac807..aa8401e7 100644
--- a/site/src/cut/hooks/usePlayback.ts
+++ b/site/src/cut/hooks/usePlayback.ts
@@ -385,6 +385,10 @@ class Engine {
const s = useEditor.getState();
const spans = getClipSpans(s.clips, s.assets);
const total = projectDuration(s);
+ // The frame's color is the project's, read fresh each frame: every clear
+ // and every letterbox below paints it, so a cut with no footage at all
+ // still plays a picture.
+ this.comp.background = s.background;
this.pool.beginFrame();
this.used.clear();
diff --git a/site/src/cut/lib/aiTools.ts b/site/src/cut/lib/aiTools.ts
index 5324b33b..2ea63455 100644
--- a/site/src/cut/lib/aiTools.ts
+++ b/site/src/cut/lib/aiTools.ts
@@ -72,7 +72,7 @@ import { blobToInlineAudio, refToInlineAudio, visualRefs, type InlineImage } fro
import { characterPrompt, stockAspectDims, stockTitle } from "./stock";
import { STOCK_IMAGES } from "./stockManifest";
import { STOCK_VIDEOS } from "./stockVideoManifest";
-import { applyOverlayPatchSettled, track0Clips, laneGapAt, getClipSpans, nextFreeStart, overlayLayers, parkedTransitions, resolveTransitions, totalDuration, useEditor } from "./store";
+import { applyOverlayPatchSettled, track0Clips, laneGapAt, getClipSpans, nextFreeStart, overlayLayers, parkedTransitions, projectDuration, resolveTransitions, totalDuration, useEditor } from "./store";
import { playheadAt } from "./playhead";
import { renderProjectFrame } from "./exportRender";
import { rasterCanvasToDataUrl } from "./raster";
@@ -92,6 +92,7 @@ import {
allFonts,
ANIM_DEFAULT_SECONDS,
ANIM_STYLE_IDS,
+ DEFAULT_BACKGROUND,
frameOf,
IMAGE_CLIP_SECONDS,
isEffectOverlay,
@@ -102,6 +103,7 @@ import {
nearestAspect,
normalizeAspect,
overlayAnimStyle,
+ projectBackground,
rectOf,
regionLabel,
SHAPE_LABELS,
@@ -211,6 +213,12 @@ const CAPTURE_LONG_SIDE = 640;
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. */
+const aimedLane = (input: Record<string, unknown>): { lane?: number } | undefined =>
+ isNum(input.lane) ? { lane: Math.max(0, Math.round(input.lane)) } : undefined;
+
/** Every tool that runs in the browser: the full catalog minus the
* `server: true` skills tools the engine answers itself. */
type BrowserToolName = Exclude<
@@ -248,7 +256,7 @@ const toolRuns: Record<BrowserToolName, ToolRun> = {
if (!(shape in SHAPE_LABELS))
throw new ToolError(`shape must be one of ${SHAPE_KINDS.join(", ")}.`);
if (isNum(input.start)) s.seek(input.start);
- s.addShape(shape);
+ s.addShape(shape, aimedLane(input));
const sel = useEditor.getState().selection;
if (sel?.kind !== "overlay") throw new ToolError("Could not create the shape.");
applyOverlayPatchSettled(sel.id, overlayPatch({ ...input, id: sel.id }, "shape"));
@@ -262,7 +270,7 @@ const toolRuns: Record<BrowserToolName, ToolRun> = {
const stickerAsset = s.assets.find((a) => a.id === assetId);
if (stickerAsset?.type !== "image") throw new ToolError(`No image asset with id ${assetId}.`);
if (isNum(input.start)) s.seek(input.start);
- s.addSticker({ assetId, ...(isLottieAsset(stickerAsset) ? { lottie: true } : {}) });
+ s.addSticker({ assetId, ...(isLottieAsset(stickerAsset) ? { lottie: true } : {}), ...aimedLane(input) });
const sel = useEditor.getState().selection;
if (sel?.kind !== "overlay") throw new ToolError("Could not create the sticker.");
applyOverlayPatchSettled(sel.id, overlayPatch({ ...input, id: sel.id }, "sticker"));
@@ -277,7 +285,7 @@ const toolRuns: Record<BrowserToolName, ToolRun> = {
const { createCustomSticker } = await import("./stickerCreate");
const asset = await createCustomSticker(s.projectId, idea);
if (isNum(input.start)) s.seek(input.start);
- useEditor.getState().addSticker({ assetId: asset.id });
+ useEditor.getState().addSticker({ assetId: asset.id, ...aimedLane(input) });
const sel = useEditor.getState().selection;
if (sel?.kind !== "overlay") throw new ToolError("Could not place the sticker.");
applyOverlayPatchSettled(sel.id, overlayPatch({ ...input, id: sel.id }, "sticker"));
@@ -290,7 +298,7 @@ const toolRuns: Record<BrowserToolName, ToolRun> = {
if (!(EFFECT_IDS as string[]).includes(effect))
throw new ToolError(`effect must be one of ${EFFECT_IDS.join(", ")}.`);
if (isNum(input.start)) s.seek(input.start);
- s.addEffect(effect as EffectId);
+ s.addEffect(effect as EffectId, aimedLane(input));
const sel = useEditor.getState().selection;
if (sel?.kind !== "overlay") throw new ToolError("Could not create the effect.");
applyOverlayPatchSettled(sel.id, overlayPatch({ ...input, id: sel.id }, "effect"));
@@ -563,6 +571,7 @@ const toolRuns: Record<BrowserToolName, ToolRun> = {
subtitles: s.subtitles,
fadeIn: s.fadeIn,
fadeOut: s.fadeOut,
+ background: s.background,
},
at,
{ width: Math.round(frame.w * k), height: Math.round(frame.h * k) },
@@ -1204,7 +1213,7 @@ const toolRuns: Record<BrowserToolName, ToolRun> = {
if (typeof input.text !== "string" || !input.text.trim())
throw new ToolError("text is required.");
if (isNum(input.start)) s.seek(input.start);
- s.addOverlay();
+ s.addOverlay(aimedLane(input));
const sel = useEditor.getState().selection;
if (sel?.kind !== "overlay") throw new ToolError("Could not create the title.");
applyOverlayPatchSettled(sel.id, overlayPatch({ ...input, id: sel.id }, "text"));
@@ -2354,8 +2363,8 @@ const toolRuns: Record<BrowserToolName, ToolRun> = {
},
open_export: (s) => {
- if (getClipSpans(s.clips, s.assets).length === 0)
- throw new ToolError("Add a video to the timeline first.");
+ if (!(projectDuration(s) > 0))
+ throw new ToolError("Add something to the timeline first.");
s.setExportOpen(true);
return { open: true };
},
@@ -2416,6 +2425,17 @@ const toolRuns: Record<BrowserToolName, ToolRun> = {
return { fadeIn: after.fadeIn, fadeOut: after.fadeOut };
},
+ set_background: (s, input) => {
+ const raw = typeof input.color === "string" ? input.color : "";
+ const hex = projectBackground(raw);
+ // projectBackground falls back rather than throwing, so a color it could
+ // not read would silently paint the frame black. Say so instead.
+ if (raw.trim() && hex === DEFAULT_BACKGROUND && !/^#?(000|000000)$/i.test(raw.trim()))
+ throw new ToolError(`Could not read ${raw} as a color — pass a hex like #FFFFFF.`);
+ s.setBackground(hex);
+ return { background: useEditor.getState().background };
+ },
+
set_project_name: (s, input) => {
if (typeof input.name !== "string" || !input.name.trim())
throw new ToolError("name is required.");
@@ -2849,6 +2869,7 @@ function overlayPatch(input: Record<string, unknown>, kind: "text" | "shape" | "
const patch: Record<string, unknown> = {};
if (isNum(input.start)) patch.start = Math.max(0, input.start);
if (isNum(input.end)) patch.end = input.end;
+ if (isNum(input.lane)) patch.lane = Math.max(0, Math.round(input.lane));
if (isNum(input.x)) patch.x = clamp(input.x, 0.02, 0.98);
if (isNum(input.y)) patch.y = clamp(input.y, 0.02, 0.98);
if (isNum(input.rotation))
diff --git a/site/src/cut/lib/composite.ts b/site/src/cut/lib/composite.ts
index 0a22ee97..35d4be75 100644
--- a/site/src/cut/lib/composite.ts
+++ b/site/src/cut/lib/composite.ts
@@ -21,7 +21,7 @@
import { applyMaskToCanvas, gradeTint, gradeToCssFilter, grainTile, isNeutralGrade, lookCssFilter, lookPost, maskComposite } from "@donkeycut/effects-kit";
import { createRasterCanvas } from "./raster";
-import { clipKeyed, clipPoseAt, isFullRect, rectOf } from "./types";
+import { clipKeyed, clipPoseAt, DEFAULT_BACKGROUND, isFullRect, rectOf } from "./types";
import type { FrameRect, TransitionStyle, VideoClip } from "./types";
/** A clip's picture at some instant, or the reasons there isn't one.
@@ -90,6 +90,13 @@ export class FrameCompositor {
| ((at: number) => { alpha: CanvasImageSource | null } | null)
| null = null;
+ /**
+ * The frame's own color, behind everything drawn into it. The project owns
+ * it, so the caller writes it before each frame; black keeps a compositor
+ * nobody told rendering the way it always did.
+ */
+ background = DEFAULT_BACKGROUND;
+
constructor(private canvas: Surface) {}
/** Point the compositor at a different surface, keeping the scratch buffers. */
@@ -140,7 +147,7 @@ export class FrameCompositor {
clear() {
const ctx = this.ctx();
if (!ctx) return;
- ctx.fillStyle = "#000";
+ ctx.fillStyle = this.background;
ctx.fillRect(0, 0, this.canvas.width, this.canvas.height);
}
@@ -527,7 +534,7 @@ export class FrameCompositor {
const H = this.canvas.height;
const blank = () => {
if (clear) {
- ctx.fillStyle = "#000";
+ ctx.fillStyle = this.background;
ctx.fillRect(0, 0, W, H);
}
};
diff --git a/site/src/cut/lib/exportClient.ts b/site/src/cut/lib/exportClient.ts
index 77b88f5c..d27a2dad 100644
--- a/site/src/cut/lib/exportClient.ts
+++ b/site/src/cut/lib/exportClient.ts
@@ -17,7 +17,7 @@ import { clipSpeed, getClipSpans, overlayLayers, projectDuration, spanSequence,
import { captionStyle, cueOverlay, cueWordWindows, laneCues, laneHidden, subtitleLaneCount, trackPos } from "./subtitles";
import { isMaskAnimated, isOverlayAnimated, normalizeGrade, paintMaskLuma } from "@donkeycut/effects-kit";
import { renderElementFrames, renderElementPng } from "./textRender";
-import { clipPoseAt, frameOf, isStickerOverlay, isTextOverlay, laneOf, overlayAnimStyle, rectOf, regionPx, subjectMasked } from "./types";
+import { clipPoseAt, frameOf, isStickerOverlay, isTextOverlay, laneOf, overlayAnimStyle, projectBackground, rectOf, regionPx, subjectMasked } from "./types";
import type {
Aspect,
AudioClip,
@@ -182,6 +182,8 @@ export interface ExportDoc {
* composite. */
fadeIn?: number;
fadeOut?: number;
+ /** The frame's own color behind every clip and element (hex); absent = black. */
+ background?: string;
}
@@ -321,18 +323,14 @@ async function buildExportPayload(
const duration = projectDuration(doc);
const pngs: ExportPayload["pngs"] = [];
const assetById = new Map(doc.assets.map((a) => [a.id, a]));
- // Overlay-only cuts (empty track 0) still export: track 0 becomes a black bed
- // the length of the project and the overlays/soundtrack composite onto it —
- // the same path as a gap before the first track-0 clip. Refuse only a cut with
- // no renderable content at all.
- const hasOverlayVideo = overlayLayers(doc.clips).some(
- (c) => !c.hidden && assetById.has(c.assetId) && c.start < duration,
- );
- const hasAudio = doc.audioClips.some(
- (a) => !a.hidden && a.start < duration && assetById.has(a.assetId),
- );
- if (spans.length === 0 && !hasOverlayVideo && !hasAudio) {
- throw new Error("Add a video to the timeline first.");
+ // Cuts with an empty track 0 still export: track 0 becomes a bed of the
+ // project's background color the length of the cut and the elements, layers
+ // and soundtrack composite onto it — the same path as a gap before the first
+ // track-0 clip. A cut of nothing but titles and shapes is that case for its
+ // whole length. Anything on any row gives the project a duration, so having
+ // one is the same question as having something to render.
+ if (!(duration > 0)) {
+ throw new Error("Add something to the timeline first.");
}
// The person matte renders first, so the loops below attach subject fields
@@ -722,6 +720,7 @@ async function buildExportPayload(
duration,
fadeIn: doc.fadeIn ?? 0,
fadeOut: doc.fadeOut ?? 0,
+ background: projectBackground(doc.background),
clips,
audio,
overlayVideos,
@@ -1157,7 +1156,7 @@ async function renderShareCard(projectId: string, doc: ExportDoc): Promise<void>
* previous one (or the generated placeholder) in place. */
export function refreshShareCard(projectId: string): void {
const s = useEditor.getState();
- if (!s.loaded || s.projectId !== projectId || s.clips.length === 0) return;
+ if (!s.loaded || s.projectId !== projectId || projectDuration(s) <= 0) return;
void renderShareCard(projectId, {
aspect: s.aspect,
assets: s.assets,
@@ -1167,6 +1166,7 @@ export function refreshShareCard(projectId: string): void {
subtitles: s.subtitles,
fadeIn: s.fadeIn,
fadeOut: s.fadeOut,
+ background: s.background,
}).catch(() => {});
}
@@ -1185,7 +1185,7 @@ export function refreshShareCard(projectId: string): void {
*/
export async function refreshShareLadder(projectId: string): Promise<void> {
const s = useEditor.getState();
- if (!s.loaded || s.projectId !== projectId || s.clips.length === 0) return;
+ if (!s.loaded || s.projectId !== projectId || projectDuration(s) <= 0) return;
const backend = getBackend();
// The share decides what the render may contain, so it is read first. This
// also settles whether to render at all: an unshared project has no viewer to
@@ -1207,6 +1207,7 @@ export async function refreshShareLadder(projectId: string): Promise<void> {
subtitles: s.subtitles,
fadeIn: s.fadeIn,
fadeOut: s.fadeOut,
+ background: s.background,
},
body.share.features?.subtitles === true
);
diff --git a/site/src/cut/lib/exportRender.ts b/site/src/cut/lib/exportRender.ts
index 5277d5af..497e8922 100644
--- a/site/src/cut/lib/exportRender.ts
+++ b/site/src/cut/lib/exportRender.ts
@@ -36,7 +36,7 @@ import { applyEffectToCanvas, evalOverlayFrame, grainTile, isMaskAnimated, isOve
import { hasSubjectOverlays, SubjectMaskCompositor } from "./behindPass";
import { createRasterCanvas, type RasterSurface } from "./raster";
import { renderElementPng } from "./textRender";
-import { behindSubjectOverlay, frameOf, frontSubjectOverlay, isEffectOverlay, isFullRect, isTextOverlay, laneOf, overlayAnimStyle, projectFadeSeconds, rectOf } from "./types";
+import { behindSubjectOverlay, frameOf, frontSubjectOverlay, isEffectOverlay, isFullRect, isTextOverlay, laneOf, overlayAnimStyle, projectBackground, projectFadeSeconds, rectOf } from "./types";
import type { ClipSpan, EffectOverlay, MediaAsset, Overlay, StickerOverlay } from "./types";
import type { ExportDoc, ExportSettings } from "./exportClient";
@@ -798,6 +798,7 @@ export class FramePainter {
private resolve: (asset: MediaAsset) => string
) {
this.comp = new FrameCompositor(canvas);
+ this.comp.background = projectBackground(doc.background);
this.stamps = new StampCache(canvas.width, canvas.height, doc.assets);
this.duration = projectDuration(doc);
}
diff --git a/site/src/cut/lib/store.test.ts b/site/src/cut/lib/store.test.ts
index 2d031e3e..f0cc5b96 100644
--- a/site/src/cut/lib/store.test.ts
+++ b/site/src/cut/lib/store.test.ts
@@ -115,6 +115,14 @@ describe("the document projection", () => {
expect(docOverlays(s().overlays)).toBe(a.overlays!);
});
+ test("the frame color survives the round trip, and a bad one falls back", () => {
+ s().setBackground("#ff5500");
+ expect(s().background).toBe("#FF5500");
+ expect(serializeDoc(s() as Parameters<typeof serializeDoc>[0]).background).toBe("#FF5500");
+ s().setBackground("burnt orange");
+ expect(s().background).toBe("#000000");
+ });
+
test("an edit gives a new projection, and the stamp still comes off", () => {
useEditor.setState({ overlays: [title({ kind: "text" })] });
const before = serializeDoc(s() as Parameters<typeof serializeDoc>[0]);
diff --git a/site/src/cut/lib/store.ts b/site/src/cut/lib/store.ts
index 1ea3f1a4..d89db231 100644
--- a/site/src/cut/lib/store.ts
+++ b/site/src/cut/lib/store.ts
@@ -60,7 +60,7 @@ import { useGenNotify } from "./genNotify";
import { clampPlayhead, playheadAt, previewAt, setPlayhead, setSkim } from "./playhead";
import { engineTranscribeSamples, withEngineStt } from "./localStt";
import { trackLocale } from "./subtitles";
-import { ANIM_STYLE_IDS, animStyleOfTransition, clipPoseAt, emptySubtitles, frameOf, IMAGE_CLIP_SECONDS, isEffectOverlay, isStickerOverlay, MAX_SUBTITLE_LANES, mediaUrl, migrateBehindSubject, migrateLegacyTransitions, normalizeAspect, overlayAnimStyle, SPEED_FLOOR, SPEED_MIN, stampOverlayKinds, stripDefaultOverlayKinds, TRANSITION_MAX, TRANSITION_STYLE_IDS, transitionStyleOfAnim } from "./types";
+import { ANIM_STYLE_IDS, animStyleOfTransition, clipPoseAt, DEFAULT_BACKGROUND, emptySubtitles, frameOf, IMAGE_CLIP_SECONDS, isEffectOverlay, isStickerOverlay, MAX_SUBTITLE_LANES, mediaUrl, migrateBehindSubject, migrateLegacyTransitions, normalizeAspect, overlayAnimStyle, projectBackground, SPEED_FLOOR, SPEED_MIN, stampOverlayKinds, stripDefaultOverlayKinds, TRANSITION_MAX, TRANSITION_STYLE_IDS, transitionStyleOfAnim } from "./types";
import { readTextStyle } from "./textStyle";
import { loadUiState, saveUiState, type ProjectUiState } from "./uiState";
import { captureTimelineFrames } from "./visualFrames";
@@ -213,6 +213,10 @@ export interface EditorState {
* black at the end of the cut. Applied to the final picture and mix. */
fadeIn: number;
fadeOut: number;
+ /** The frame's own color, behind every clip and element. A cut made of
+ * nothing but titles and shapes plays over it, a fitted clip letterboxes
+ * into it, and a gap on track 0 shows it. */
+ background: string;
selection: Selection;
/** Everything selected, including `selection` (the primary that drives the
* inspector). Bulk actions — delete, copy — act on this whole set. */
@@ -284,6 +288,9 @@ export interface EditorState {
/** Set the whole-video fade in/out (seconds; 0 clears). Like the aspect,
* project-level settings sit outside the undo history. */
setProjectFade: (patch: { fadeIn?: number; fadeOut?: number }) => void;
+ /** Set the frame color. Project-level, so it sits outside undo like the
+ * aspect and the fades. */
+ setBackground: (hex: string) => void;
addAsset: (asset: MediaAsset) => void;
updateAsset: (id: string, patch: Partial<MediaAsset>) => void;
/** Swap asset URLs in place (fileName -> url), e.g. after re-minting an
@@ -332,7 +339,8 @@ export interface EditorState {
* owned them) and clear the gen sets, so post-run edits to generated clips
* undo like any other edit. */
releaseGenClips: () => void;
- addOverlay: () => void;
+ /** Place a title element; a drop (or the assistant) passes where it landed. */
+ addOverlay: (aim?: { at?: number; lane?: number }) => void;
/** Add a vector shape element on the title lanes at the playhead. */
/** Place a shape element; a drop passes where it landed. */
addShape: (shape: ShapeKind, aim?: { at?: number; lane?: number }) => void;
@@ -1041,6 +1049,7 @@ const DOC_KEYS = [
"aspect",
"fadeIn",
"fadeOut",
+ "background",
"publish",
"notes",
"subtitles",
@@ -1261,6 +1270,7 @@ export const useEditor = create<EditorState>((baseSet, get, api) => {
aspectTouched: false,
fadeIn: 0,
fadeOut: 0,
+ background: DEFAULT_BACKGROUND,
selection: null,
multiSelection: [],
playing: false,
@@ -1307,6 +1317,7 @@ export const useEditor = create<EditorState>((baseSet, get, api) => {
aspectTouched: false,
fadeIn: 0,
fadeOut: 0,
+ background: DEFAULT_BACKGROUND,
selection: null,
multiSelection: [],
selectedKey: null,
@@ -1616,6 +1627,7 @@ export const useEditor = create<EditorState>((baseSet, get, api) => {
aspectTouched: doc.aspect !== undefined,
fadeIn: doc.fadeIn ?? 0,
fadeOut: doc.fadeOut ?? 0,
+ background: projectBackground(doc.background),
// View state lives in IndexedDB; doc.ui covers projects saved
// before the move.
pxPerSec: Math.max(12, Math.min(800, ui.pxPerSec ?? doc.ui?.pxPerSec ?? 60)),
@@ -1834,6 +1846,8 @@ export const useEditor = create<EditorState>((baseSet, get, api) => {
}));
},
+ setBackground: (hex) => set({ background: projectBackground(hex) }),
+
addAsset: (asset) =>
set((s) => {
// The first video in an untouched project decides the starting frame
@@ -2049,7 +2063,7 @@ export const useEditor = create<EditorState>((baseSet, get, api) => {
get().addVideoFromAsset(assetId, { kind: "track", track }, t);
},
- addOverlay: () => {
+ addOverlay: (aim) => {
// Seed the visual style from the last-used title so repeated titles in a
// project share one look; fall back to the built-in defaults.
const remembered = readTextStyle();
@@ -2076,7 +2090,7 @@ export const useEditor = create<EditorState>((baseSet, get, api) => {
plateOpacity: remembered.plateOpacity,
plateRadius: remembered.plateRadius,
lane,
- }));
+ }), aim);
},
addShape: (shape, aim) => {
@@ -4363,6 +4377,7 @@ export function serializeDoc(s: {
aspect: Aspect;
fadeIn: number;
fadeOut: number;
+ background: string;
publish: { caption: string; tags: string; soundTitle: string; handle: string };
notes: { text: string; publishedAt: string; links: string[] };
subtitles: SubtitlesBlock;
@@ -4383,6 +4398,7 @@ export function serializeDoc(s: {
aspect: s.aspect,
fadeIn: s.fadeIn,
fadeOut: s.fadeOut,
+ background: s.background,
subtitles: s.subtitles,
publish: { ...s.publish },
notes: { ...s.notes, links: [...s.notes.links] },
diff --git a/site/src/cut/lib/types.ts b/site/src/cut/lib/types.ts
index 3852f35c..4ec83efa 100644
--- a/site/src/cut/lib/types.ts
+++ b/site/src/cut/lib/types.ts
@@ -444,6 +444,21 @@ export function projectFadeSeconds(fade: number | undefined, duration: number):
return Math.max(0, Math.min(fade ?? 0, duration / 2));
}
+/** The frame color a project takes when it has not chosen one. Black is what
+ * every cut rendered before the field existed, so an old document opens
+ * looking exactly as it did. */
+export const DEFAULT_BACKGROUND = "#000000";
+
+/** A project's frame color as a `#RRGGBB` string. Anything unparseable — a
+ * hand-edited document, a tool argument — falls back to the default rather
+ * than reaching a canvas or an ffmpeg argument as garbage. */
+export function projectBackground(raw: string | undefined | null): string {
+ const m = /^#?([0-9a-f]{3}|[0-9a-f]{6})$/i.exec((raw ?? "").trim());
+ if (!m) return DEFAULT_BACKGROUND;
+ const h = m[1];
+ return `#${(h.length === 3 ? [...h].map((c) => c + c).join("") : h).toUpperCase()}`;
+}
+
/** How a clip hands off to the next one. Every style is a render-time blend
* across the outgoing clip's last transition-length seconds: the incoming
* clip's first frame arrives over the live tail and playback hands over at
@@ -1077,6 +1092,10 @@ export interface ProjectDoc {
* soundtrack fade together), so they survive clip reordering. */
fadeIn?: number;
fadeOut?: number;
+ /** The color of the frame itself, behind everything: what a text-and-graphics
+ * cut plays over, what letterboxes a fitted clip, and what fills a gap in the
+ * timeline. Hex; absent = `DEFAULT_BACKGROUND`. */
+ background?: string;
/** Auto-generated (then hand-edited) subtitles. */
subtitles?: SubtitlesBlock;
/** Legacy per-project view metadata — view state now lives in IndexedDB;
diff --git a/site/src/cut/server/ai/catalog.ts b/site/src/cut/server/ai/catalog.ts
index 378cf5c2..9242b6fb 100644
--- a/site/src/cut/server/ai/catalog.ts
+++ b/site/src/cut/server/ai/catalog.ts
@@ -112,6 +112,7 @@ Route the ask to the right feature:
- set_transition: a styled join between one video clip and the next, blended across the cut. It never moves clips or shortens anything, and it plays only while the pair touches.
- set_animation: one clip's own entrance ("in") or exit ("out") — the clip fades/zooms/pops/slides on its own edge. Never moves neighbors. For "fade this clip in", "make it slide in", use this. A wipe is a transition, not an animation.
- set_project_fade: the whole video fades in from black at the start and/or out to black at the end — picture and full mix (titles, captions, soundtrack). Survives clip reordering. For "fade in the video", "fade to black at the end", use this.
+- set_background: the color of the frame itself, behind everything, for the whole cut. For "make the background white", or any cut whose picture is titles and shapes rather than footage. Covered in the graphics skill.
- update_audio fadeIn/fadeOut: audio-only ramps on one soundtrack clip ("fade the music out").
- An ask beyond every preset here — a reference template, a grid or mosaic reveal, a multi-panel build — is a construction job: the graphics skill's composite-builds section shows how overlay video tracks, masks, and keyframes compose into it.
@@ -125,6 +126,9 @@ 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\`.
+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).
Shapes (add_shape): rect, ellipse, line, arrow. w/h are frame fractions; rect/ellipse take fill + fill_opacity, corner radius (rect), and an outline (stroke_color/stroke_width); line/arrow draw in \`fill\` with h as their thickness, and rotation gives them their direction (0° points right, 90° points down).
Stickers (add_sticker): a project image asset (generated cutouts in the Elements panel carry origin "sticker"); w is a frame-width fraction and height follows the source's aspect. Lottie JSON uploads become animated stickers that loop for the element's duration.
diff --git a/site/src/cut/server/exportPipeline.test.ts b/site/src/cut/server/exportPipeline.test.ts
index aae1e2d1..de729ef8 100644
--- a/site/src/cut/server/exportPipeline.test.ts
+++ b/site/src/cut/server/exportPipeline.test.ts
@@ -460,3 +460,29 @@ describe("clip keyframes in the filtergraph", () => {
expect(xfadeMismatches(g)).toEqual([]);
});
});
+
+describe("the project background in the filtergraph", () => {
+ test("a cut of nothing but elements renders the background for its whole length", async () => {
+ const g = await graphFor({
+ clips: [clip("", { out: 6, hidden: true, muted: true })],
+ background: "#FF5500",
+ overlays: [{ file: "o0.png", start: 0, end: 6 }],
+ });
+ const joined = g.join(";");
+ expect(joined).toContain("color=c=0xFF5500");
+ expect(joined).not.toContain("color=c=black:");
+ });
+
+ test("a fitted clip letterboxes into the background rather than into black", async () => {
+ const g = await graphFor({
+ clips: [clip("a.mp4", { fit: "fit" })],
+ background: "#FFFFFF",
+ });
+ expect(g.join(";")).toContain("color=0xFFFFFF");
+ });
+
+ test("no background named keeps the black frame every cut had before", async () => {
+ const g = await graphFor({ clips: [clip("", { out: 4, hidden: true, muted: true })] });
+ expect(g.join(";")).toContain("color=c=black:");
+ });
+});
diff --git a/site/src/cut/server/exportPipeline.ts b/site/src/cut/server/exportPipeline.ts
index ec770c98..16939fb5 100644
--- a/site/src/cut/server/exportPipeline.ts
+++ b/site/src/cut/server/exportPipeline.ts
@@ -26,6 +26,10 @@ export interface ExportSpec {
* final composite and mix after all overlays and soundtrack. */
fadeIn?: number;
fadeOut?: number;
+ /** The frame's own color (hex): what letterboxes a fitted clip, what a gap
+ * on track 0 plays, and what a cut of nothing but elements composites over.
+ * Absent = black. */
+ background?: string;
clips: {
file: string;
in: number;
@@ -274,6 +278,14 @@ export function sdrConvert(c: Awaited<ReturnType<typeof videoColorInfo>>) {
}
/** A clip's effective playback rate (>0, default 1). */
+/** A spec color as an ffmpeg color argument: `0xRRGGBB`. Anything the spec
+ * did not carry, or carried malformed, is black — the frame every cut had
+ * before the project could choose one. */
+function ffColor(hex: string | undefined): string {
+ const m = /^#?([0-9a-f]{6})$/i.exec((hex ?? "").trim());
+ return m ? `0x${m[1].toUpperCase()}` : "black";
+}
+
function clipRate(c: ExportSpec["clips"][number]) {
return c.speed && c.speed > 0 ? c.speed : 1;
}
@@ -372,7 +384,10 @@ export async function runExport(
(a, b) => a.track - b.track || a.start - b.start
);
const clipFmt = "yuv420p";
- const padColor = "black";
+ // Every bare patch of frame in the graph — the letterbox around a fitted
+ // clip, a gap on track 0, the backdrop behind an edge animation — is the
+ // project's own background color. ffmpeg takes it as 0xRRGGBB.
+ const padColor = ffColor(spec.background);
// One ffmpeg input per distinct media file (from the project folder),
// plus one per uploaded overlay PNG.
// Still images are excluded here: a plain `-i file` decodes one frame, so
@@ -755,11 +770,11 @@ export async function runExport(
return;
}
// The backdrop behind the window: a neighbor's held frame when given
- // (an abutting cut), else black (timeline ends and gaps).
+ // (an abutting cut), else the bare frame (timeline ends and gaps).
let bg = fx.bg;
if (!bg) {
bg = `xb${tag}_${side}`;
- filters.push(`color=c=black:s=${w}x${h}:r=${fps}:d=${d},format=${fmt}[${bg}]`);
+ filters.push(`color=c=${padColor}:s=${w}x${h}:r=${fps}:d=${d},format=${fmt}[${bg}]`);
}
if (fx.kind === "xfade") {
// Entering: the backdrop hands off to the picture; exiting: the
@@ -1055,11 +1070,12 @@ export async function runExport(
);
}
} else {
- // No video stream, or a hidden clip: the slot plays black. trim+setpts
+ // No video stream, or a hidden clip: the slot plays the bare frame — an
+ // elements-only cut is one such slot for its whole length. trim+setpts
// clear the frame-rate stamp a transitioned join's xfade demands —
// re-stamp it.
filters.push(
- `color=c=black:s=${W}x${H}:r=${fps},trim=0:${num(dur)},setpts=PTS-STARTPTS,fps=${fps},format=${clipFmt}[v${j}]`
+ `color=c=${padColor}:s=${W}x${H}:r=${fps},trim=0:${num(dur)},setpts=PTS-STARTPTS,fps=${fps},format=${clipFmt}[v${j}]`
);
}
if (!c.muted && !c.hidden && audioPresence.get(c.file)) {