Skip to content

The truly free, open-source, local-first, cross-platform CapCut replacement. Scriptable through a JSON-RPC API & MCP.

perf(ui): stop the 60fps full-tree re-render during playback

Jareer34b3ce63c9ff
diff --git a/desktop/src/App.tsx b/desktop/src/App.tsx
index 80b4316d..1f5109ff 100644
--- a/desktop/src/App.tsx
+++ b/desktop/src/App.tsx
@@ -214,8 +214,10 @@ function Editor({
const timeline = activeTimeline(project);
const duration = projectDuration(project);
- const transport = useTransport({ duration });
- const { playhead, playing } = transport;
+ // `transport` is the stable controls object - safe in deps and memoised
+ // props without per-frame churn. Only `playhead`/`playing` move at
+ // animation rate, and only Preview and TimelinePanel take them as props.
+ const { playhead, playing, controls: transport } = useTransport({ duration });
// Read by event listeners that outlive the render that installed them.
const latest = useRef({ project, secondsPerPixel, scrollLeft, trackScroll, snap, playhead, frame });
@@ -749,6 +751,61 @@ function Editor({
[duration],
);
+ // ── stable prop identities ───────────────────────────────────────────────
+ // MediaBin, RightPanel and the TitleBar are React.memo'd so they sit out
+ // the per-frame renders playback causes here. That only holds if every
+ // callback they receive keeps its identity - an inline arrow minted per
+ // render would make the memo a no-op - so their handlers live here as
+ // useCallbacks over stable dependencies.
+
+ const selectMedia = useCallback((ids: string[]) => {
+ setSelectedMediaIds(ids);
+ // Bin and timeline selections are exclusive: picking media drops clips.
+ if (ids.length > 0) setSelectedClipIds([]);
+ }, []);
+
+ const importFiles = useCallback(
+ (paths: string[]) => void importPaths(paths),
+ [importPaths],
+ );
+
+ const removeMedia = useCallback(
+ (id: string) => void dispatch({ op: "removeMedia", mediaId: id }),
+ [dispatch],
+ );
+
+ const dismissError = useCallback(() => setError(null), []);
+
+ const toggleSlot = useCallback(
+ (mediaId: string, placeholder: boolean) =>
+ void dispatch({ op: "setMediaPlaceholder", mediaId, placeholder }),
+ [dispatch],
+ );
+
+ const openTemplateDialog = useCallback(() => setTemplateDialog({ busy: false }), []);
+
+ const leaveForTemplate = useCallback(
+ (template: TemplateInfo) => {
+ // Save what is open first: leaving for the fill flow closes this
+ // project, and the debounced autosave may not have fired.
+ void editorSave(latest.current.frame)
+ .catch(() => undefined)
+ .then(() => onUseTemplate(template));
+ },
+ [onUseTemplate],
+ );
+
+ const addFont = useCallback(() => void pickFont(), [pickFont]);
+
+ const removeFont = useCallback(
+ (family: string) => void dispatch({ op: "removeFont", family }),
+ [dispatch],
+ );
+
+ const openModifyProject = useCallback(() => setModifyingProject({ busy: false }), []);
+ const openSettings = useCallback(() => setSettingsOpen(true), []);
+ const openExport = useCallback(() => setExporting(true), []);
+
// ── keyboard ─────────────────────────────────────────────────────────────
useEffect(() => {
const onKey = (event: KeyboardEvent) => {
@@ -916,6 +973,177 @@ function Editor({
? findMedia(project, selectedMediaIds[0])
: null;
+ // Walks every selected clip's neighbours, so not something to redo per
+ // frame of playback - only an edit or a selection change moves the answer.
+ const mergeBlockedBecause = useMemo(
+ () => whyNotMerge(project, selectedClipIds),
+ [project, selectedClipIds],
+ );
+
+ // The Export button, built once so the memoised TitleBar sees the same
+ // `actions` element across playback renders.
+ const exportAction = useMemo(
+ () => (
+ <button
+ type="button"
+ onClick={openExport}
+ className="flex cursor-pointer items-center gap-1.5 rounded-md bg-accent px-2.5 py-1
+ text-xs font-medium text-on-accent transition-colors hover:bg-accent-hover"
+ >
+ <Icon name="export" size={13} />
+ Export
+ </button>
+ ),
+ [openExport],
+ );
+
+ // The whole menu structure, rebuilt only when something a menu shows or
+ // does actually changes. Building it inline in the JSX minted a new tree
+ // per render - 60 times a second during playback - and dragged the
+ // memoised TitleBar along with it. Nothing here reads the playhead (the
+ // File menu's "add at playhead" goes through `latest`), so playback never
+ // invalidates it.
+ const menus = useMemo<{ label: string; groups: MenuOption[][] }[]>(
+ () => [
+ {
+ label: "File",
+ groups: [
+ [
+ {
+ label: "Add selected to timeline",
+ icon: "plus",
+ disabled: selectedMediaIds.length === 0,
+ onSelect: () => placeMediaSet(selectedMediaIds, latest.current.playhead, null),
+ },
+ {
+ label: "Save",
+ icon: "folder",
+ hint: "Ctrl+S",
+ onSelect: () => saveAndNotify(),
+ },
+ {
+ label: "Export...",
+ icon: "export",
+ disabled: exportClips.length === 0,
+ onSelect: openExport,
+ },
+ {
+ label: "Save as template...",
+ icon: "slot",
+ onSelect: openTemplateDialog,
+ },
+ ],
+ [
+ {
+ label: "Settings...",
+ icon: "settings",
+ onSelect: openSettings,
+ },
+ ],
+ [
+ {
+ label: "Close project",
+ icon: "folder",
+ onSelect: onCloseProject,
+ },
+ {
+ label: "Close window",
+ icon: "close",
+ onSelect: () => void getCurrentWindow().close(),
+ danger: true,
+ },
+ ],
+ ],
+ },
+ {
+ label: "Edit",
+ groups: [
+ [
+ {
+ label: "Undo",
+ icon: "chevronUp",
+ hint: "Ctrl+Z",
+ disabled: !view?.canUndo,
+ onSelect: undoAction,
+ },
+ {
+ label: "Redo",
+ icon: "chevronDown",
+ hint: "Ctrl+Shift+Z",
+ disabled: !view?.canRedo,
+ onSelect: redoAction,
+ },
+ ],
+ [
+ { label: "Split at playhead", icon: "razor", hint: "Ctrl+B", onSelect: splitAtPlayhead },
+ {
+ label:
+ selectedClipIds.length > 1
+ ? `Delete ${selectedClipIds.length} clips`
+ : "Delete clip",
+ icon: "trash",
+ hint: "Del",
+ disabled: selectedClipIds.length === 0,
+ onSelect: deleteSelected,
+ danger: true,
+ },
+ ],
+ [
+ {
+ label: snap ? "Disable snapping" : "Enable snapping",
+ icon: "magnet",
+ hint: "N",
+ onSelect: () => setSnap((current) => !current),
+ },
+ ],
+ ],
+ },
+ {
+ label: "View",
+ groups: [
+ [
+ { label: "Zoom in", icon: "plus", onSelect: () => zoom(1 / 1.4) },
+ { label: "Zoom out", icon: "minus", onSelect: () => zoom(1.4) },
+ ],
+ [
+ {
+ label: "Go to start",
+ icon: "skipStart",
+ hint: "Home",
+ onSelect: () => transport.seek(0),
+ },
+ {
+ label: "Go to end",
+ icon: "skipEnd",
+ hint: "End",
+ onSelect: () => transport.seek(duration),
+ },
+ ],
+ ],
+ },
+ ],
+ [
+ deleteSelected,
+ duration,
+ exportClips,
+ onCloseProject,
+ openExport,
+ openSettings,
+ openTemplateDialog,
+ placeMediaSet,
+ redoAction,
+ saveAndNotify,
+ selectedClipIds,
+ selectedMediaIds,
+ snap,
+ splitAtPlayhead,
+ transport,
+ undoAction,
+ view,
+ zoom,
+ ],
+ );
+
return (
<div className="flex h-full flex-col overflow-hidden">
<TitleBar
@@ -933,136 +1161,9 @@ function Editor({
}
theme={theme}
onToggleTheme={onToggleTheme}
- onOpenSettings={() => setSettingsOpen(true)}
- actions={
- <button
- type="button"
- onClick={() => setExporting(true)}
- className="flex cursor-pointer items-center gap-1.5 rounded-md bg-accent px-2.5 py-1
- text-xs font-medium text-on-accent transition-colors hover:bg-accent-hover"
- >
- <Icon name="export" size={13} />
- Export
- </button>
- }
- menus={[
- {
- label: "File",
- groups: [
- [
- {
- label: "Add selected to timeline",
- icon: "plus",
- disabled: selectedMediaIds.length === 0,
- onSelect: () => placeMediaSet(selectedMediaIds, latest.current.playhead, null),
- },
- {
- label: "Save",
- icon: "folder",
- hint: "Ctrl+S",
- onSelect: () => saveAndNotify(),
- },
- {
- label: "Export...",
- icon: "export",
- disabled: exportClips.length === 0,
- onSelect: () => setExporting(true),
- },
- {
- label: "Save as template...",
- icon: "slot",
- onSelect: () => setTemplateDialog({ busy: false }),
- },
- ],
- [
- {
- label: "Settings...",
- icon: "settings",
- onSelect: () => setSettingsOpen(true),
- },
- ],
- [
- {
- label: "Close project",
- icon: "folder",
- onSelect: onCloseProject,
- },
- {
- label: "Close window",
- icon: "close",
- onSelect: () => void getCurrentWindow().close(),
- danger: true,
- },
- ],
- ],
- },
- {
- label: "Edit",
- groups: [
- [
- {
- label: "Undo",
- icon: "chevronUp",
- hint: "Ctrl+Z",
- disabled: !view?.canUndo,
- onSelect: undoAction,
- },
- {
- label: "Redo",
- icon: "chevronDown",
- hint: "Ctrl+Shift+Z",
- disabled: !view?.canRedo,
- onSelect: redoAction,
- },
- ],
- [
- { label: "Split at playhead", icon: "razor", hint: "Ctrl+B", onSelect: splitAtPlayhead },
- {
- label:
- selectedClipIds.length > 1
- ? `Delete ${selectedClipIds.length} clips`
- : "Delete clip",
- icon: "trash",
- hint: "Del",
- disabled: selectedClipIds.length === 0,
- onSelect: deleteSelected,
- danger: true,
- },
- ],
- [
- {
- label: snap ? "Disable snapping" : "Enable snapping",
- icon: "magnet",
- hint: "N",
- onSelect: () => setSnap((current) => !current),
- },
- ],
- ],
- },
- {
- label: "View",
- groups: [
- [
- { label: "Zoom in", icon: "plus", onSelect: () => zoom(1 / 1.4) },
- { label: "Zoom out", icon: "minus", onSelect: () => zoom(1.4) },
- ],
- [
- {
- label: "Go to start",
- icon: "skipStart",
- hint: "Home",
- onSelect: () => transport.seek(0),
- },
- {
- label: "Go to end",
- icon: "skipEnd",
- hint: "End",
- onSelect: () => transport.seek(duration),
- },
- ],
- ],
- },
- ]}
+ onOpenSettings={openSettings}
+ actions={exportAction}
+ menus={menus}
/>
<div className="flex min-h-0 flex-1 flex-col p-2">
@@ -1078,29 +1179,18 @@ function Editor({
error={error}
onFilter={setBinFilter}
onAddText={addText}
- onSelect={(ids) => {
- setSelectedMediaIds(ids);
- if (ids.length > 0) setSelectedClipIds([]);
- }}
- onImport={(paths) => void importPaths(paths)}
- onRemove={(id) => void dispatch({ op: "removeMedia", mediaId: id })}
+ onSelect={selectMedia}
+ onImport={importFiles}
+ onRemove={removeMedia}
onRemoveSelected={deleteSelectedMedia}
- onDismissError={() => setError(null)}
+ onDismissError={dismissError}
onBeginDrag={beginMediaDrag}
onAddToTimeline={addToTimeline}
onApplyEffect={applyEffect}
onApplyTransition={applyTransition}
- onToggleSlot={(mediaId, placeholder) =>
- void dispatch({ op: "setMediaPlaceholder", mediaId, placeholder })
- }
- onSaveTemplate={() => setTemplateDialog({ busy: false })}
- onUseTemplate={(template) => {
- // Save what is open first: leaving for the fill flow closes
- // this project, and the debounced autosave may not have fired.
- void editorSave(latest.current.frame)
- .catch(() => undefined)
- .then(() => onUseTemplate(template));
- }}
+ onToggleSlot={toggleSlot}
+ onSaveTemplate={openTemplateDialog}
+ onUseTemplate={leaveForTemplate}
/>
</div>
@@ -1185,12 +1275,12 @@ function Editor({
frame={frame}
duration={duration}
frameRate={frameRate}
- onAddFont={() => void pickFont()}
- onRemoveFont={(family) => void dispatch({ op: "removeFont", family })}
+ onAddFont={addFont}
+ onRemoveFont={removeFont}
onChangeClip={changeClip}
onCommitClip={commitEcho}
onSpeedChange={changeSpeed}
- onModifyProject={() => setModifyingProject({ busy: false })}
+ onModifyProject={openModifyProject}
/>
</div>
</div>
@@ -1232,7 +1322,7 @@ function Editor({
onGestureEnd={commitEcho}
onSplitAtPlayhead={splitAtPlayhead}
onMergeSelected={mergeSelected}
- mergeBlockedBecause={whyNotMerge(project, selectedClipIds)}
+ mergeBlockedBecause={mergeBlockedBecause}
onDeleteSelected={deleteSelected}
mediaDrag={mediaDrag ? { x: mediaDrag.x, y: mediaDrag.y } : null}
onZoom={zoom}
diff --git a/desktop/src/components/MediaBin.tsx b/desktop/src/components/MediaBin.tsx
index 00e47bd1..f7771102 100644
--- a/desktop/src/components/MediaBin.tsx
+++ b/desktop/src/components/MediaBin.tsx
@@ -1,4 +1,4 @@
-import { useEffect, useRef, useState } from "react";
+import { memo, useEffect, useRef, useState } from "react";
import { open } from "@tauri-apps/plugin-dialog";
import type { PointerEvent as ReactPointerEvent, ReactNode } from "react";
@@ -59,8 +59,13 @@ const TABS: { id: LibraryTab; label: string }[] = [
* at the drop position. That is the primary way material gets into an edit, so
* it needs to be the obvious one - hence the whole card being the drag handle
* rather than some grip affordance.
+ *
+ * Memoised: the editor re-renders per animation frame during playback and
+ * nothing in the library depends on the playhead. App.tsx keeps every
+ * callback here referentially stable (useCallback) so the memo actually
+ * skips those renders.
*/
-export function MediaBin({
+export const MediaBin = memo(function MediaBin({
items,
filter,
selectedIds,
@@ -226,7 +231,7 @@ export function MediaBin({
</div>
</Panel>
);
-}
+});
// ── the category sidebar ─────────────────────────────────────────────────────
diff --git a/desktop/src/components/RightPanel.tsx b/desktop/src/components/RightPanel.tsx
index d71b01fd..d34a2972 100644
--- a/desktop/src/components/RightPanel.tsx
+++ b/desktop/src/components/RightPanel.tsx
@@ -1,3 +1,5 @@
+import { memo } from "react";
+
import type { AppliedEffect, ClipTransition } from "../lib/effects";
import type { ClipFilter } from "../lib/filters";
import {
@@ -49,8 +51,13 @@ const TEXT_TABS: { id: RightTab; label: string }[] = [{ id: "text", label: "Text
* Filters is what you can add to it. Keeping those apart matters because the
* first is read-only and the other two are not, and mixing them makes it
* unclear which numbers you are allowed to touch.
+ *
+ * Memoised: playback re-renders the editor per animation frame, and nothing
+ * here reads the playhead - the panel shows the selection, not the clock.
+ * App.tsx keeps every callback and derived prop referentially stable
+ * (useCallback / useMemo / objects straight off the memoised project).
*/
-export function RightPanel({
+export const RightPanel = memo(function RightPanel({
tab,
onTab,
clip,
@@ -181,4 +188,4 @@ export function RightPanel({
)}
</Panel>
);
-}
+});
diff --git a/desktop/src/components/TitleBar.tsx b/desktop/src/components/TitleBar.tsx
index 81d0e99a..f7517020 100644
--- a/desktop/src/components/TitleBar.tsx
+++ b/desktop/src/components/TitleBar.tsx
@@ -1,4 +1,4 @@
-import { useEffect, useState } from "react";
+import { memo, useEffect, useState } from "react";
import type { ReactNode } from "react";
import { isTauri } from "@tauri-apps/api/core";
import { getCurrentWindow } from "@tauri-apps/api/window";
@@ -28,8 +28,12 @@ import { Menu, type MenuOption } from "./Menu";
*
* In a plain browser (`npm run dev` without the host) the window APIs are
* absent, so the controls hide themselves rather than throwing.
+ *
+ * Memoised: the editor re-renders at animation rate during playback and
+ * nothing up here depends on the playhead. App.tsx keeps `menus`, `actions`
+ * and the callbacks referentially stable so this actually holds.
*/
-export function TitleBar({
+export const TitleBar = memo(function TitleBar({
projectName,
menus,
status,
@@ -164,7 +168,7 @@ export function TitleBar({
)}
</header>
);
-}
+});
/**
* Window controls are wider than they are tall and reach the very top edge, so
diff --git a/desktop/src/lib/transport.ts b/desktop/src/lib/transport.ts
index ff246613..f69a392e 100644
--- a/desktop/src/lib/transport.ts
+++ b/desktop/src/lib/transport.ts
@@ -1,4 +1,4 @@
-import { useCallback, useEffect, useRef, useState } from "react";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
import { isTauri } from "@tauri-apps/api/core";
import { transportPause, transportPlay, transportSeek } from "./engine";
@@ -17,9 +17,16 @@ import { listen } from "@tauri-apps/api/event";
* the anchor simply never gets corrected - the wall clock alone is the same
* prototype behaviour this file always had there.
*/
-export interface Transport {
- playhead: number;
- playing: boolean;
+/**
+ * The methods, kept apart from the values on purpose. `playhead` changes
+ * every animation frame while playing; the methods never change at all. One
+ * object holding both would get a fresh identity per frame, and everything
+ * keyed on it - effect deps, memoised children - would churn at 60fps. So
+ * consumers that only *drive* the transport take `controls` (one stable
+ * identity for the life of the hook) and never re-render on playback, while
+ * the few that *display* the playhead subscribe to it explicitly.
+ */
+export interface TransportControls {
play: () => void;
pause: () => void;
toggle: () => void;
@@ -29,6 +36,12 @@ export interface Transport {
step: (frames: number, frameRate: number) => void;
}
+export interface Transport {
+ playhead: number;
+ playing: boolean;
+ controls: TransportControls;
+}
+
export function useTransport({ duration }: { duration: number }): Transport {
const native = isTauri();
const [playhead, setPlayhead] = useState(0);
@@ -122,5 +135,12 @@ export function useTransport({ duration }: { duration: number }): Transport {
return () => cancelAnimationFrame(frame);
}, [playing, native]);
- return { playhead, playing, play, pause, toggle, seek, step };
+ // Every method is a useCallback keyed only on `native`, so this memo holds
+ // one identity for the hook's whole life - see the note on TransportControls.
+ const controls = useMemo<TransportControls>(
+ () => ({ play, pause, toggle, seek, step }),
+ [play, pause, toggle, seek, step],
+ );
+
+ return { playhead, playing, controls };
}