Open source CapCut alternative.
TypeScript
/**
* Preview guides: lines and keep-out regions drawn over the stage so titles,
* stickers and captions land where a phone will show them. Geometry is in
* frame fractions (0..1 of width and height), so one preset serves every
* frame size. Guides draw in the editor only; exports and captured frames
* never carry them. The short-form preset is measured on a phone and dated,
* so a change in an app's UI is one edit here.
*/
import { aspectOrientation, type Aspect } from "./types";
export type GuideId = "thirds" | "center" | "margins" | "shortform" | "custom";
/** The user's own lines, frame fractions per axis: v is x positions, h is y. */
export interface GuideLines {
v: number[];
h: number[];
}
/** Which part of a platform's UI a keep-out box covers; the preview names
* it in the page's language. */
export type GuideRegion = "topBar" | "cropped" | "actions" | "caption";
/** A region the platform's own UI covers, as frame fractions. */
export interface GuideBox {
x: number;
y: number;
w: number;
h: number;
label: string;
region: GuideRegion;
}
/** Lines (frame fractions along one axis) and keep-out boxes to draw. The
* custom lines come separately: they draw in their own color and drag. */
export interface GuideGeometry {
v: number[];
h: number[];
boxes: GuideBox[];
custom: GuideLines;
}
/** The rectangle left for graphics once every keep-out box is removed. */
export interface SafeArea {
x: number;
y: number;
w: number;
h: number;
}
export interface GuidePreset {
id: GuideId;
name: string;
sublabel?: string;
/** Phone UI is measured on a phone, so the preset fits portrait frames. */
portraitOnly?: boolean;
geometry: Omit<GuideGeometry, "custom">;
}
/** Safe-margin inset, fraction of the frame. */
export const MARGIN_INSET = 0.05;
const phone = (px: number, of: 1080 | 1920) => px / of;
export const GUIDE_PRESETS: readonly GuidePreset[] = [
{
id: "thirds",
name: "Thirds",
geometry: { v: [1 / 3, 2 / 3], h: [1 / 3, 2 / 3], boxes: [] },
},
{
id: "center",
name: "Center",
geometry: { v: [0.5], h: [0.5], boxes: [] },
},
{
id: "margins",
name: "Safe margins",
sublabel: "5% inset",
geometry: {
v: [MARGIN_INSET, 1 - MARGIN_INSET],
h: [MARGIN_INSET, 1 - MARGIN_INSET],
boxes: [],
},
},
// The phone UI of TikTok, Instagram Reels and YouTube Shorts, merged into
// one keep-out: each region is the widest of the three. Measured September
// 2026 on a 1170×2532 phone, mapped onto the 1080×1920 frame. Reels and
// Shorts scale a 9:16 frame to fill the player and crop 4.4% off each
// side; TikTok crops 1.4%. The top band covers the status bar and the
// search row under it, the rail the actions from the avatar down, the
// bottom band the username, caption and music line.
{
id: "shortform",
name: "Short form",
sublabel: "TikTok, Instagram, YouTube",
portraitOnly: true,
geometry: {
v: [],
h: [],
boxes: [
{ x: 0, y: 0, w: 1, h: phone(215, 1920), label: "Top bar", region: "topBar" },
{ x: 0, y: 0, w: phone(50, 1080), h: 1, label: "Cropped", region: "cropped" },
{ x: 1 - phone(50, 1080), y: 0, w: phone(50, 1080), h: 1, label: "Cropped", region: "cropped" },
{ x: phone(895, 1080), y: phone(730, 1920), w: phone(185, 1080), h: phone(730, 1920), label: "Actions", region: "actions" },
{ x: 0, y: phone(1460, 1920), w: 1, h: phone(460, 1920), label: "Caption · music · nav", region: "caption" },
],
},
},
// The user's own lines, held in the project's guideLines and dragged on
// the preview.
{
id: "custom",
name: "Custom",
sublabel: "Drag lines on the preview",
geometry: { v: [], h: [], boxes: [] },
},
];
export const EMPTY_GUIDE_LINES: GuideLines = { v: [], h: [] };
const clamp01 = (n: number) => Math.min(1, Math.max(0, n));
/** A stored line list with every position a number in 0..1. */
export function sanitizeGuideLines(v: unknown): GuideLines {
const axis = (a: unknown) =>
Array.isArray(a) ? a.filter((n): n is number => typeof n === "number" && Number.isFinite(n)).map(clamp01) : [];
const o = v && typeof v === "object" ? (v as Record<string, unknown>) : {};
return { v: axis(o.v), h: axis(o.h) };
}
export const GUIDE_IDS = GUIDE_PRESETS.map((p) => p.id) as GuideId[];
export function isGuideId(v: unknown): v is GuideId {
return typeof v === "string" && (GUIDE_IDS as string[]).includes(v);
}
/** The known guide ids in a stored list, in registry order, each once. */
export function sanitizeGuides(v: unknown): GuideId[] {
if (!Array.isArray(v)) return [];
return GUIDE_IDS.filter((id) => v.includes(id));
}
export function guidePreset(id: GuideId): GuidePreset {
return GUIDE_PRESETS.find((p) => p.id === id)!;
}
/** Whether a preset applies to the frame: platform chrome fits portrait frames. */
export function guideFits(id: GuideId, aspect: Aspect): boolean {
return !guidePreset(id).portraitOnly || aspectOrientation(aspect) === "portrait";
}
/** Every line and box of the guides that are on and fit the frame, merged;
* the custom lines ride along when the custom set is on. */
export function guideGeometry(
ids: readonly GuideId[],
aspect: Aspect,
lines: GuideLines = EMPTY_GUIDE_LINES
): GuideGeometry {
const out: GuideGeometry = { v: [], h: [], boxes: [], custom: EMPTY_GUIDE_LINES };
for (const id of ids) {
if (!guideFits(id, aspect)) continue;
if (id === "custom") {
out.custom = lines;
continue;
}
const g = guidePreset(id).geometry;
out.v.push(...g.v);
out.h.push(...g.h);
out.boxes.push(...g.boxes);
}
return out;
}
/** The snap lines the guides offer a dragged element: every drawn line plus
* the inner edge of every keep-out box. */
export function guideSnapLines(
ids: readonly GuideId[],
aspect: Aspect,
lines: GuideLines = EMPTY_GUIDE_LINES
): GuideLines {
const g = guideGeometry(ids, aspect, lines);
const v = [...g.v, ...g.custom.v];
const h = [...g.h, ...g.custom.h];
for (const b of g.boxes) {
if (b.w >= 0.99) h.push(b.y <= 0.01 ? b.y + b.h : b.y);
else if (b.x + b.w >= 0.99) v.push(b.x);
else if (b.x <= 0.01) v.push(b.x + b.w);
}
return { v, h };
}
/** The frame minus every keep-out box and inside the safe margins, as one
* rectangle; null when no active guide bounds anything. */
export function safeAreaOf(ids: readonly GuideId[], aspect: Aspect): SafeArea | null {
let left = 0;
let top = 0;
let right = 1;
let bottom = 1;
let bounded = false;
if (ids.includes("margins")) {
left = top = MARGIN_INSET;
right = bottom = 1 - MARGIN_INSET;
bounded = true;
}
for (const b of guideGeometry(ids, aspect).boxes) {
bounded = true;
if (b.w >= 0.99) {
if (b.y <= 0.01) top = Math.max(top, b.y + b.h);
else bottom = Math.min(bottom, b.y);
} else if (b.x + b.w >= 0.99) right = Math.min(right, b.x);
else if (b.x <= 0.01) left = Math.max(left, b.x + b.w);
}
if (!bounded) return null;
const round = (n: number) => Math.round(n * 1000) / 1000;
return { x: round(left), y: round(top), w: round(right - left), h: round(bottom - top) };
}