Skip to content

Open source CapCut alternative.

TypeScript

feat(site): copy the preview frame and paste it

David Leda74e4e513a1
diff --git a/site/src/cut/components/Editor.tsx b/site/src/cut/components/Editor.tsx
index 4036cb89..23769efb 100644
--- a/site/src/cut/components/Editor.tsx
+++ b/site/src/cut/components/Editor.tsx
@@ -23,6 +23,7 @@ import {
import { fileZoneAt, hasRefDrag, selectionRefTokens } from "@/cut/lib/assetRef";
import { startUpload } from "@/cut/lib/importQueue";
import { enrichAsset, importFileToProject, prepareImport } from "@/cut/lib/media";
+import { clearCopiedFrame, hasCopiedFrame, pasteCopiedFrame } from "@/cut/lib/stageFrame";
// Side-effect import: registers the brief-to-video resume subscription, so a
// persisted run resumes on project load even when the AI panel never mounts.
import "@/cut/lib/genScene";
@@ -49,7 +50,7 @@ import {
storedAssets,
useEditor,
} from "@/cut/lib/store";
-import { playheadAt, skimAt } from "@/cut/lib/playhead";
+import { playheadAt, previewAt, skimAt } from "@/cut/lib/playhead";
import type { MediaAsset } from "@/cut/lib/types";
import { AiPanel } from "./AiPanel";
import { ExportDialog } from "./ExportDialog";
@@ -782,6 +783,35 @@ export function Editor({
};
}, [importFiles, viewer]);
+ // An image on the system clipboard joins the cut: a frame copied from
+ // another tab's preview, a screenshot, a picture from anywhere else. The
+ // editor's own ⌘V claims the timeline clipboard and the copied frame before
+ // this — both stop the keystroke, so no paste event follows them — and a
+ // composer marks its own paste handled, so this only ever sees the pastes
+ // nobody else wanted. The picture lands at the preview time.
+ useEffect(() => {
+ if (viewer) return;
+ const onPaste = (e: ClipboardEvent) => {
+ if (e.defaultPrevented || useEditor.getState().readOnly) return;
+ const target = e.target as HTMLElement | null;
+ const textEntry =
+ !!target &&
+ (target.tagName === "TEXTAREA" ||
+ target.tagName === "INPUT" ||
+ target.isContentEditable);
+ if (textEntry) return;
+ const files = Array.from(e.clipboardData?.items ?? [])
+ .filter((i) => i.kind === "file" && i.type.startsWith("image/"))
+ .map((i) => i.getAsFile())
+ .filter((f): f is File => f !== null);
+ if (files.length === 0) return;
+ e.preventDefault();
+ void importFiles(files, { at: Math.max(0, previewAt()) });
+ };
+ window.addEventListener("paste", onPaste);
+ return () => window.removeEventListener("paste", onPaste);
+ }, [importFiles, viewer]);
+
// Keyboard shortcuts.
useEffect(() => {
const onKey = (e: KeyboardEvent) => {
@@ -833,10 +863,20 @@ export function Editor({
if (!window.getSelection()?.toString()) {
const token = selectionRefTokens(s);
if (token) void navigator.clipboard.writeText(token).catch(() => {});
- if (s.copySelection() || token) e.preventDefault();
+ // The newer copy owns the clipboard: a copied preview frame steps
+ // aside for this one.
+ const copied = s.copySelection();
+ if (copied) clearCopiedFrame();
+ if (copied || token) e.preventDefault();
}
} else if ((e.metaKey || e.ctrlKey) && e.key.toLowerCase() === "v") {
+ // The timeline clipboard first; a frame copied off the preview canvas
+ // lands as a still at the preview time.
if (s.paste()) e.preventDefault();
+ else if (hasCopiedFrame()) {
+ e.preventDefault();
+ void pasteCopiedFrame().catch((err) => console.error("Paste frame failed:", err));
+ }
} else if ((e.metaKey || e.ctrlKey) && e.key.toLowerCase() === "g") {
// ⌘G groups the multi-selected elements, ⇧⌘G dissolves the primary's
// group — the panel's Group button is out of reach while a
diff --git a/site/src/cut/components/Preview.tsx b/site/src/cut/components/Preview.tsx
index 11587d40..f0985f42 100644
--- a/site/src/cut/components/Preview.tsx
+++ b/site/src/cut/components/Preview.tsx
@@ -1,7 +1,7 @@
"use client";
import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState, type RefObject } from "react";
-import { ZoomIn, ZoomOut } from "lucide-react";
+import { Check, Copy, ZoomIn, ZoomOut } from "lucide-react";
import { usePlayback } from "@/cut/hooks/usePlayback";
import { clearAssetDrag, setAssetDragData } from "@/cut/lib/assetDrag";
import { startDrag } from "@/cut/lib/drag";
@@ -13,6 +13,7 @@ import {
useSkim,
} from "@/cut/lib/playhead";
import { getClipSpans, projectDuration, useEditor } from "@/cut/lib/store";
+import { copyStageFrame, stageHasFrame } from "@/cut/lib/stageFrame";
import {
capturePoster,
capturePosterWhenReady,
@@ -298,6 +299,33 @@ export function Preview() {
const slices = useMemo(() => stageSliceStructure(effectLanes), [effectLanes]);
usePannableCursor(stageRef);
+ // Right-click on the picture: a one-item menu that copies the frame the
+ // preview is showing. The copy goes onto the system clipboard as a PNG, so
+ // it pastes into a message, a post, or another app, and onto the editor's
+ // own clipboard, so ⌘V drops it on the timeline as a still.
+ const [frameMenu, setFrameMenu] = useState<{ x: number; y: number } | null>(null);
+ const [copyState, setCopyState] = useState<"idle" | "working" | "done" | "failed">("idle");
+ useEffect(() => {
+ if (!frameMenu) return;
+ const close = (e: KeyboardEvent) => {
+ if (e.key === "Escape") setFrameMenu(null);
+ };
+ window.addEventListener("keydown", close);
+ return () => window.removeEventListener("keydown", close);
+ }, [frameMenu]);
+ const openFrameMenu = (e: React.MouseEvent) => {
+ // An empty cut has no picture to take; the browser's own menu can have the
+ // click.
+ if (!stageHasFrame()) return;
+ e.preventDefault();
+ // The frame is grabbed when the item is clicked, so playback stops here —
+ // what you right-clicked is what you copy.
+ const s = useEditor.getState();
+ if (s.playing) s.setPlaying(false);
+ setCopyState("idle");
+ setFrameMenu({ x: e.clientX, y: e.clientY });
+ };
+
useEffect(() => {
setPreviewCanvas(canvasRef.current);
return () => setPreviewCanvas(null);
@@ -551,6 +579,7 @@ export function Preview() {
"stage absolute inset-0 overflow-hidden bg-black shadow-[0_0_0_1px_rgba(0,0,0,0.08),0_12px_36px_rgba(0,0,0,0.18)]"
)}
style={{ borderRadius: stageRadius(stage.w, stage.h) }}
+ onContextMenu={openFrameMenu}
onPointerDown={(e) => {
if (
e.target === e.currentTarget ||
@@ -650,6 +679,52 @@ export function Preview() {
if (!held) pokeHud();
}}
/>
+ {frameMenu && (
+ <div
+ className="fixed inset-0 z-50"
+ onPointerDown={() => setFrameMenu(null)}
+ onContextMenu={(e) => {
+ e.preventDefault();
+ setFrameMenu(null);
+ }}
+ >
+ <div
+ className="absolute min-w-44 rounded-md border bg-popover p-1 text-popover-foreground shadow-md"
+ style={{ left: frameMenu.x, top: frameMenu.y }}
+ onPointerDown={(e) => e.stopPropagation()}
+ >
+ <button
+ className="flex w-full items-center gap-2 rounded-sm px-2 py-1.5 text-sm hover:bg-accent hover:text-accent-foreground disabled:opacity-60"
+ disabled={copyState === "working"}
+ onClick={() => {
+ setCopyState("working");
+ copyStageFrame().then(
+ () => {
+ setCopyState("done");
+ // A beat on “Copied” before the menu goes, so the copy is
+ // something you saw happen.
+ window.setTimeout(() => setFrameMenu(null), 800);
+ },
+ () => setCopyState("failed")
+ );
+ }}
+ >
+ {copyState === "done" ? (
+ <Check className="size-3.5 text-muted-foreground" />
+ ) : (
+ <Copy className="size-3.5 text-muted-foreground" />
+ )}
+ {copyState === "working"
+ ? "Copying frame…"
+ : copyState === "done"
+ ? "Copied"
+ : copyState === "failed"
+ ? "Couldn't copy the frame"
+ : "Copy frame"}
+ </button>
+ </div>
+ </div>
+ )}
</section>
);
}
diff --git a/site/src/cut/components/Timeline.tools.ts b/site/src/cut/components/Timeline.tools.ts
index 8c7bf458..fd8cf9ac 100644
--- a/site/src/cut/components/Timeline.tools.ts
+++ b/site/src/cut/components/Timeline.tools.ts
@@ -268,6 +268,9 @@ export const TIMELINE_TOOLS = [
t: num("Timeline time of the frame to grab (default: playhead)"),
duration: num("Still clip length in seconds, 0.5–10 (default 1)"),
index: num("Insert position on the video track (default 0 = first)"),
+ with_elements: bool(
+ "Bake the whole picture as the preview shows it — titles, captions and effects burned into the still (default false: the video frame alone)"
+ ),
}),
},
{
diff --git a/site/src/cut/lib/aiTools.ts b/site/src/cut/lib/aiTools.ts
index 0bbaecde..befbf61f 100644
--- a/site/src/cut/lib/aiTools.ts
+++ b/site/src/cut/lib/aiTools.ts
@@ -87,6 +87,7 @@ import { STOCK_VIDEOS } from "./stockVideoManifest";
import { applyOverlayPatchSettled, track0Clips, laneGapAt, getClipSpans, nextFreeStart, overlayLaneOrder, overlayLayers, parkedTransitions, projectDuration, resolveTransitions, totalDuration, useEditor } from "./store";
import { playheadAt } from "./playhead";
import { renderProjectFrame } from "./exportRender";
+import { renderStageFrame, storeStageStill } from "./stageFrame";
import { createRasterCanvas, decodeRasterImageUrl, rasterCanvasToDataUrl } from "./raster";
import { buildAiContext } from "./aiContext";
import { sampleClipFrameData } from "./previewCanvas";
@@ -1897,12 +1898,23 @@ const toolRuns: Record<BrowserToolName, ToolRun> = {
(t - span.start) *
(span.clip.speed && span.clip.speed > 0 ? span.clip.speed : 1);
let body: MediaAsset;
- if (getBackend().kind !== "local") {
+ const freezeDur = Math.min(10, Math.max(0.5, isNum(input.duration) ? input.duration : 1));
+ if (input.with_elements === true) {
+ // The whole picture, as the preview shows it — titles, captions and
+ // effects burned in. Same render path the canvas's Copy frame uses,
+ // so a still the assistant makes and one the user copies match.
+ const png = await renderStageFrame(t).catch((e) => {
+ throw new ToolError(e instanceof Error ? e.message : "Could not draw the frame.");
+ });
+ body = {
+ ...(await storeStageStill(projectId, png, t, "Could not render the freeze frame.")),
+ duration: freezeDur,
+ };
+ } else if (getBackend().kind !== "local") {
// No engine to bake a still video — grab the frame in the browser and
// store it as a project image; image clips carry their own length,
// sized below to the requested duration, mirroring the engine's
// /freeze clamps (default 1s, 0.5..10s).
- const freezeDur = Math.min(10, Math.max(0.5, isNum(input.duration) ? input.duration : 1));
body = await captureFreezeFrame(projectId, span.asset.url, srcTime, freezeDur, {
frame: frameOf(s.aspect),
cover: clipCovers(span.clip),
diff --git a/site/src/cut/lib/stageFrame.ts b/site/src/cut/lib/stageFrame.ts
new file mode 100644
index 00000000..1aee2a78
--- /dev/null
+++ b/site/src/cut/lib/stageFrame.ts
@@ -0,0 +1,135 @@
+"use client";
+
+/**
+ * The picture the preview is showing, as a still that goes anywhere.
+ *
+ * Right-clicking the canvas copies the frame. It is drawn through the render
+ * path rather than read back off the preview canvas: elements, captions and
+ * effects sit in DOM above that canvas, and a still meant to open a post has
+ * to carry them. The PNG lands on the system clipboard for anything that takes
+ * an image — a chat composer, a message, another app — and is held here for ⌘V
+ * onto the timeline, where it becomes a project image at the preview time.
+ *
+ * The held frame and the timeline clipboard are one clipboard to the person
+ * using them, so a copy on either side clears the other and ⌘V has one answer.
+ */
+
+import { renderProjectFrame } from "./exportRender";
+import { enrichAsset, uploadProjectImage } from "./media";
+import { previewAt } from "./playhead";
+import { rasterCanvasToPng } from "./raster";
+import { projectDuration, useEditor } from "./store";
+import { frameOf, type MediaAsset } from "./types";
+
+/** A copied frame, waiting for a paste. */
+interface CopiedFrame {
+ png: Blob;
+ /** Timeline second it was taken at — it names the asset. */
+ at: number;
+}
+
+let held: CopiedFrame | null = null;
+
+/** m:ss, for the still's name. */
+function stampOf(at: number): string {
+ const total = Math.round(at);
+ return `${Math.floor(total / 60)}:${String(total % 60).padStart(2, "0")}`;
+}
+
+/** Draw the cut as it stands at `at`, at the project's full frame size:
+ * clips, transitions, effects, elements, captions, the project fade. */
+export async function renderStageFrame(at: number): Promise<Blob> {
+ const s = useEditor.getState();
+ const frame = frameOf(s.aspect);
+ const canvas = await renderProjectFrame(
+ {
+ aspect: s.aspect,
+ assets: s.assets,
+ clips: s.clips,
+ audioClips: s.audioClips,
+ overlays: s.overlays,
+ subtitles: s.subtitles,
+ fadeIn: s.fadeIn,
+ fadeOut: s.fadeOut,
+ background: s.background,
+ },
+ at,
+ { width: frame.w, height: frame.h },
+ (asset) => asset.url
+ );
+ return rasterCanvasToPng(canvas);
+}
+
+/** Whether the stage has a picture worth copying. */
+export const stageHasFrame = (): boolean => projectDuration(useEditor.getState()) > 0;
+
+/**
+ * Copy the frame the preview is showing.
+ *
+ * The blob goes onto the system clipboard as a promise rather than an awaited
+ * value: Safari ties a clipboard write to the gesture that asked for it, and
+ * compositing the frame first spends that gesture. Rejects when the frame
+ * cannot be drawn or the browser refuses the write, which is the caller's cue
+ * to say so — a frame that drew is held for the timeline either way.
+ */
+export async function copyStageFrame(): Promise<void> {
+ const at = Math.max(0, previewAt());
+ const png = renderStageFrame(at);
+ // The write's verdict is kept rather than awaited here: a frame that fails
+ // to draw fails the write with it, and the draw is the failure worth
+ // reporting.
+ const wroteOk = navigator.clipboard.write([new ClipboardItem({ "image/png": png })]).then(
+ () => true,
+ () => false
+ );
+ held = { png: await png, at };
+ // The frame is the clipboard's contents now; a timeline copy no longer
+ // outranks it at the next ⌘V.
+ useEditor.getState().clearClipboard();
+ if (!(await wroteOk)) throw new Error("The browser refused the clipboard write.");
+}
+
+/** Whether a copied frame is waiting for ⌘V. */
+export const hasCopiedFrame = (): boolean => held !== null;
+
+/** Forget the copied frame — a ⌘C on the timeline is the newer copy. */
+export const clearCopiedFrame = (): void => {
+ held = null;
+};
+
+/** Store a composited still as a project image, named for the moment it was
+ * taken. Created media, so it carries the freeze origin and stays out of the
+ * Media panel. */
+export async function storeStageStill(
+ projectId: string,
+ png: Blob,
+ at: number,
+ failMessage?: string
+): Promise<MediaAsset> {
+ const stamp = stampOf(at);
+ const fileName = `frame-${stamp.replace(":", "m")}s-${crypto.randomUUID().slice(0, 4)}.png`;
+ const body = await uploadProjectImage(projectId, png, fileName, {
+ name: `Frame ${stamp}`,
+ ...(failMessage ? { failMessage } : {}),
+ });
+ return { ...body, origin: "freeze" };
+}
+
+/**
+ * Land the copied frame on the timeline: a project image placed at the preview
+ * time on the first row with room for it.
+ */
+export async function pasteCopiedFrame(): Promise<void> {
+ const frame = held;
+ const s = useEditor.getState();
+ if (!frame || !s.projectId || s.readOnly) return;
+ const projectId = s.projectId;
+ const asset = await storeStageStill(projectId, frame.png, frame.at, "Could not paste the frame.");
+ const cur = useEditor.getState();
+ // The project can change while the upload runs; the still belongs to the one
+ // it was pasted into.
+ if (cur.projectId !== projectId) return;
+ cur.addAsset(asset);
+ cur.addAssetAtPlayhead(asset.id);
+ void enrichAsset(asset);
+}
diff --git a/site/src/cut/lib/store.ts b/site/src/cut/lib/store.ts
index b7d976e9..f613058d 100644
--- a/site/src/cut/lib/store.ts
+++ b/site/src/cut/lib/store.ts
@@ -676,6 +676,9 @@ export interface EditorState {
endHistoryBatch: () => void;
/** Copy the selected clip/audio/overlay/title(s) to the timeline clipboard. */
copySelection: () => boolean;
+ /** Empty the timeline clipboard, so the next paste is somebody else's — a
+ * frame copied off the preview canvas takes the clipboard over this way. */
+ clearClipboard: () => void;
/** Paste the clipboard at the preview time (the skimmer while one is live,
* the playhead otherwise) — sliding past anything already on the target
* lane — and select the pasted item(s). */
@@ -4342,6 +4345,10 @@ export const useEditor = create<EditorState>((baseSet, get, api) => {
return true;
},
+ clearClipboard: () => {
+ clipboard = [];
+ },
+
paste: () => {
if (clipboard.length === 0) return false;
const s = get();
diff --git a/site/src/cut/server/ai/catalog.ts b/site/src/cut/server/ai/catalog.ts
index 0c218e99..4b8ba93b 100644
--- a/site/src/cut/server/ai/catalog.ts
+++ b/site/src/cut/server/ai/catalog.ts
@@ -88,7 +88,7 @@ Times are in seconds on the shared timeline. The playhead is currentTime; a skim
- The user can multi-select (⌘/⇧-click, or sweep a rubber-band over empty track space) across every kind at once — clips, audio, titles, cues. Deleting or copying acts on the whole selection, and dragging any member moves the set as one: every item shifts by the same time, relative spacing kept, while unselected items slide out of the way and flow back. A selection of one kind on the multi-row tracks (audio, titles) also retracks together on a vertical drag, one row past the end opening a new track. A hover chip on each video clip toggles its own audio.
- Anything can be hidden instead of deleted: it stays on the timeline (grayed) but drops out of playback and export — a hidden video clip plays black and silent. Per item: set_clip_hidden, or the \`hidden\` field on update_overlay_video/update_overlay/update_audio. Whole rows: set_track_hidden (video/soundtrack/text/subtitles) and set_track_muted (video) — the eye/speaker toggles on the track headers.
- detach_audio lifts a video clip's sound to the soundtrack track (and mutes the clip) so audio can be cut independently of video.
-- freeze_frame grabs one frame (default: the playhead — what the user currently sees) as a still clip and inserts it, by default at index 0 as a cover/hook frame ("make this the first frame"). The still is baked at the project's current aspect with the clip's framing applied; if the user later switches aspect they should capture a fresh one.
+- freeze_frame grabs one frame (default: the playhead — what the user currently sees) as a still clip and inserts it, by default at index 0 as a cover/hook frame ("make this the first frame"). The still is baked at the project's current aspect with the clip's framing applied; if the user later switches aspect they should capture a fresh one. \`with_elements\` bakes the composited picture instead — titles, captions and effects burned in — which is what a cover frame carrying the video's own text needs. The user reaches the same still by right-clicking the preview canvas: Copy frame puts that picture on their clipboard, and ⌘V drops it on the timeline.
- set_framing: per-clip Fit (letterbox) vs Fill (crop to cover the box), plus zoom 1..4 to push further in. Whenever the picture overflows, panX/panY position the crop window; the user can also drag the video directly in the preview, where a grey outline shows the part being cropped away. The controls live in the Inspector under "Framing" when a video clip is selected. Landscape footage usually wants fill + a pan that keeps the subject.
- update_clip also carries a clip's resting transform: rotation and opacity, alongside its region (layout/region) and zoom. Use these for a tilted or faded layer; set_clip_keyframes is for a transform that moves over time.
- set_clip_style rounds a clip's corners, strokes a border ring, and casts a drop shadow from the clip's shape — mask included, so a circle-masked webcam gets a circular shadow. The floating-cam look is one recipe: put the clip on an upper track, region it small (update_clip region or the preview handles), mask it with kind circle, and give it a soft shadow.