Skip to content

Open source CapCut alternative.

TypeScript

feat(site): square mask shape [rebuild]

David Le1992e1d759e7
diff --git a/site/packages/effects-kit/src/mask.ts b/site/packages/effects-kit/src/mask.ts
index 59ee1417..3c0024e5 100644
--- a/site/packages/effects-kit/src/mask.ts
+++ b/site/packages/effects-kit/src/mask.ts
@@ -17,7 +17,7 @@
import { lerpKeys, shortestTurn } from "./keys";
-export type MaskKind = "rect" | "circle" | "linear" | "mirror" | "subject";
+export type MaskKind = "rect" | "square" | "circle" | "linear" | "mirror" | "subject";
/** One keyed state of a mask's geometry, `t` seconds from the layer's start.
* Same interpolation rules as the pose track: linear between keys, held flat
@@ -26,8 +26,8 @@ export interface MaskKey {
t: number;
x: number; // center offset from the layer anchor, fraction of frame width
y: number; // center offset, fraction of frame height
- w: number; // fraction of frame width (linear ignores; mirror ignores)
- h: number; // fraction of frame height (mirror: band height; linear ignores)
+ w: number; // fraction of frame width (square: the side; linear/mirror ignore)
+ h: number; // fraction of frame height (mirror: band height; square/linear ignore)
rotation: number; // degrees clockwise
feather: number; // edge softness, px at the 1080 design short side
}
@@ -155,12 +155,15 @@ export function paintMaskCoverage(
ctx.translate(cx, cy);
ctx.rotate((f.rotation * Math.PI) / 180);
ctx.fillStyle = "#ffffff";
- if (m.kind === "rect") {
+ if (m.kind === "rect" || m.kind === "square") {
// Soft edges come from a gaussian of the hard shape; σ = feather / 2 puts
- // the visible transition at about the feather width.
+ // the visible transition at about the feather width. A square's side is
+ // `w` of the frame width on both axes, so it stays square in pixels on
+ // any aspect.
+ const rh = m.kind === "square" ? w : h;
if (feather > 0 && "filter" in ctx) ctx.filter = `blur(${feather / 2}px)`;
ctx.beginPath();
- ctx.roundRect(-w / 2, -h / 2, w, h, (m.radius ?? 0) * frame.scale);
+ ctx.roundRect(-w / 2, -rh / 2, w, rh, (m.radius ?? 0) * frame.scale);
ctx.fill();
} else if (m.kind === "circle") {
if (feather > 0 && "filter" in ctx) ctx.filter = `blur(${feather / 2}px)`;
diff --git a/site/src/cut/components/Inspector.tools.ts b/site/src/cut/components/Inspector.tools.ts
index 8c0abfa6..53da4a1a 100644
--- a/site/src/cut/components/Inspector.tools.ts
+++ b/site/src/cut/components/Inspector.tools.ts
@@ -45,18 +45,18 @@ export const INSPECTOR_TOOLS = [
{
name: "set_mask",
description:
- "Mask an overlay element or a video clip — trim its picture to a shape or to the person in the shot. Kinds: rect (rounded box), circle (ellipse), linear (half-plane: at rotation 0 the top side stays), mirror (band across the item), subject (the person matte: plain keeps the picture only on the person; invert keeps it off the person — behind the speaker). Position is the mask center's offset from the item's own center (a clip's region center), in frame fractions; w/h size it in frame fractions; feather softens the edge; invert keeps what the shape leaves out. Subject masks use only feather and invert. Pass kind \"none\" to remove the mask. `keys` animates the geometry over time — each key is the full geometry at a moment, moving linearly between keys; pass an empty list to clear the keys and keep the mask still.",
+ "Mask an overlay element or a video clip — trim its picture to a shape or to the person in the shot. Kinds: rect (rounded box), square (rounded square, side = w of the frame width), circle (ellipse), linear (half-plane: at rotation 0 the top side stays), mirror (band across the item), subject (the person matte: plain keeps the picture only on the person; invert keeps it off the person — behind the speaker). Position is the mask center's offset from the item's own center (a clip's region center), in frame fractions; w/h size it in frame fractions; feather softens the edge; invert keeps what the shape leaves out. Subject masks use only feather and invert. Pass kind \"none\" to remove the mask. `keys` animates the geometry over time — each key is the full geometry at a moment, moving linearly between keys; pass an empty list to clear the keys and keep the mask still.",
inputSchema: obj({
id: str("Overlay element id or video clip id"),
kind: {
type: "string",
- enum: ["rect", "circle", "linear", "mirror", "subject", "none"],
+ enum: ["rect", "square", "circle", "linear", "mirror", "subject", "none"],
description: 'Mask shape, the person matte ("subject"), or "none" to remove the mask',
},
x: num("Center offset x from the element center, fraction of frame width (default 0)"),
y: num("Center offset y, fraction of frame height (default 0)"),
- w: num("Width, fraction of frame width (default 0.5; linear ignores)"),
- h: num("Height, fraction of frame height (mirror: band height; linear ignores)"),
+ w: num("Width, fraction of frame width (default 0.5; square: the side; linear ignores)"),
+ h: num("Height, fraction of frame height (mirror: band height; square/linear ignore)"),
rotation: num("Degrees clockwise, -180..180"),
feather: num("Edge softness, px at the 1080 design short side (0..200)"),
invert: bool("Keep the pixels outside the shape"),
diff --git a/site/src/cut/components/Inspector.tsx b/site/src/cut/components/Inspector.tsx
index e8421190..3e7d1536 100644
--- a/site/src/cut/components/Inspector.tsx
+++ b/site/src/cut/components/Inspector.tsx
@@ -2072,6 +2072,7 @@ function KeyRow({
const MASK_SHAPES: { id: MaskKind; label: string }[] = [
{ id: "rect", label: "Rectangle" },
+ { id: "square", label: "Square" },
{ id: "circle", label: "Circle" },
{ id: "linear", label: "Linear" },
{ id: "mirror", label: "Mirror" },
@@ -2271,8 +2272,16 @@ function MaskSection({ target }: { target: MaskTarget }) {
if (hasMaskKeys(m)) return target.setKey(tLocal, patch, { transient: true });
target.setTransient({ ...m, ...patch });
};
- const showW = m?.kind === "rect" || m?.kind === "circle";
- const showH = showW || m?.kind === "mirror";
+ // Which size axes the shape has: a square has one side, a mirror band one
+ // height, linear none.
+ const sizeAxes: ("w" | "h")[] =
+ m?.kind === "rect" || m?.kind === "circle"
+ ? ["w", "h"]
+ : m?.kind === "square"
+ ? ["w"]
+ : m?.kind === "mirror"
+ ? ["h"]
+ : [];
const subject = m?.kind === "subject";
return (
<Section
@@ -2340,9 +2349,9 @@ function MaskSection({ target }: { target: MaskTarget }) {
))}
</Row>
)}
- {showH && (
+ {sizeAxes.length > 0 && (
<Row label="Size">
- {(showW ? (["w", "h"] as const) : (["h"] as const)).map((axis) => (
+ {sizeAxes.map((axis) => (
<span key={axis} className="flex items-center gap-1">
<span className="text-[11px] text-muted-foreground/70 uppercase">{axis}</span>
<ScrubValue
@@ -2400,7 +2409,7 @@ function MaskSection({ target }: { target: MaskTarget }) {
/>
<Value className="w-9 text-muted-foreground">{Math.round(geom.feather)}</Value>
</Row>
- {m.kind === "rect" && (
+ {(m.kind === "rect" || m.kind === "square") && (
<Row label="Radius">
<Slider
className="data-horizontal:w-24"
diff --git a/site/src/cut/lib/aiTools.ts b/site/src/cut/lib/aiTools.ts
index 19b38831..024388b0 100644
--- a/site/src/cut/lib/aiTools.ts
+++ b/site/src/cut/lib/aiTools.ts
@@ -401,7 +401,7 @@ const toolRuns: Record<BrowserToolName, ToolRun> = {
setMask(undefined);
return { id: input.id, mask: null };
}
- const kinds = ["rect", "circle", "linear", "mirror", "subject"];
+ const kinds = ["rect", "square", "circle", "linear", "mirror", "subject"];
const kind =
typeof input.kind === "string"
? input.kind
diff --git a/site/src/cut/server/ai/catalog.ts b/site/src/cut/server/ai/catalog.ts
index 25a2e1e1..f84cc755 100644
--- a/site/src/cut/server/ai/catalog.ts
+++ b/site/src/cut/server/ai/catalog.ts
@@ -129,7 +129,7 @@ Effects (add_effect): time-ranged treatments over the finished picture — the f
Advanced text (update_overlay): italic, align (multi-line), letter_spacing (em), line_height, stroke_color/stroke_width (em outline behind the fill), and richer shadows. Bundled Google families join the system set — inter, montserrat, poppins, oswald, space-grotesk, playfair, caveat, bebas, anton, archivo-black, bangers, lobster, pacifico, permanent-marker, dm-serif — and the user can upload .ttf/.otf fonts (they appear as font ids like "asset:<id>").
Animation (set_overlay_animation): every element takes preset In/Out ramps (${OVERLAY_ANIM_STYLE_IDS.join(", ")} — typewriter for titles only) and a Loop (${OVERLAY_LOOP_STYLE_IDS.join(", ")}) that runs its whole duration. Entrances 0.3–0.6s read well; one loop per scene, sparingly.
Keyframes (set_overlay_keyframes): for motion no preset covers — a path across the frame, a slow push in, a drift that holds first. A key is a whole pose (position, scale, rotation, opacity) at a time in seconds from the element's start; the pose moves linearly between keys and holds outside them, and presets still compose on top. Two or three keys carry almost everything; reach for a preset first and keyframes when the user describes a specific path or timing. In the UI the diamond in the inspector adds a key at the playhead, and dragging the element then records into it. set_clip_keyframes is the same track on a video clip (any track): pans, push-ins, picture-in-picture flights, spins, and fades on the footage itself.
-Masks (set_mask): trim any element or video clip to a shape — rect, circle, linear, mirror — with feather, invert, and its own keyframe track for reveals and wipes. The subject kind trims by the person in the shot (on-device segmentation; preview and export match): inverted sits the item behind the speaker, plain keeps it only on the speaker. Behind-speaker reads well when the speaker is clearly separated from the background; with no detectable person it degrades to the plain picture. Groups: the user can group elements (select several, Group in the inspector) — selecting one selects all, and moves/resize/rotate/timing ride together.
+Masks (set_mask): trim any element or video clip to a shape — rect, square, circle, linear, mirror — with feather, invert, and its own keyframe track for reveals and wipes. The subject kind trims by the person in the shot (on-device segmentation; preview and export match): inverted sits the item behind the speaker, plain keeps it only on the speaker. Behind-speaker reads well when the speaker is clearly separated from the background; with no detectable person it degrades to the plain picture. Groups: the user can group elements (select several, Group in the inspector) — selecting one selects all, and moves/resize/rotate/timing ride together.
Good TikTok titles: short punchy lines, high contrast (white/yellow + shadow or plate), size 72–110, keep inside the middle 80% of the frame (x 0.1..0.9, y 0.1..0.9), avoid the caption band (y≈0.8) when subtitles are on.
Tasteful graphics: shapes read best as accents (a highlight box behind a stat, an arrow pointing at the subject, a color bar under a title) — semi-transparent fills (fill_opacity 0.2–0.5) sit better over footage than solid blocks. One or two stickers a scene; size 0.15–0.3 of the frame width.
In the UI: the timeline toolbar adds Text; the Elements side-panel tab browses stickers and shapes and creates sticker images, and the Effects tab holds the effects — a click in any panel picks a tile, and dragging one onto the timeline is what places it; dragging in the preview places an element, its corner handle resizes, the top handle rotates; the Inspector edits every field.`,