Skip to content

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

feat: export and preview render the engine's session, not UI JSON

Jareer63ec3a199952
diff --git a/desktop/src-tauri/src/editor_api.rs b/desktop/src-tauri/src/editor_api.rs
index afac43a9..7179fed3 100644
--- a/desktop/src-tauri/src/editor_api.rs
+++ b/desktop/src-tauri/src/editor_api.rs
@@ -70,6 +70,25 @@ fn view(session: &Session, created_id: Option<String>) -> EditorView {
}
}
+/// The active timeline flattened for rendering, plus the session settings.
+///
+/// This is what export and preview consume. It used to be a clip list the
+/// UI flattened and sent over the wire, which made the frontend's copy of
+/// the model - not the model - the thing that rendered; see engine decision
+/// 0009. Now the engine flattens its own session and the wire carries only
+/// what the UI genuinely owns (the destination, the quality, its rasterised
+/// titles).
+pub fn flattened_clips(
+ state: &EditorState,
+) -> Result<(Vec<wolfcut_export::ExportClip>, DocumentSettings), String> {
+ with_session(state, |session| {
+ Ok((
+ wolfcut_export::flatten::flatten_timeline(session.editor.project(), None),
+ session.settings.clone(),
+ ))
+ })
+}
+
/// The open session's document, project folder and settings, for features
/// that package the current edit (saving it as a template) rather than
/// editing it.
diff --git a/desktop/src-tauri/src/lib.rs b/desktop/src-tauri/src/lib.rs
index fced45f0..719e7527 100644
--- a/desktop/src-tauri/src/lib.rs
+++ b/desktop/src-tauri/src/lib.rs
@@ -557,6 +557,20 @@ struct ExportState(std::sync::Arc<jobs::SingleFlight>);
/// app's lifetime: its whole value is what stays warm between scrubs.
struct PoolState(std::sync::Arc<std::sync::Mutex<wolfcut_media::ReaderPool>>);
+/// What the UI sends for one true frame: an instant and a resolution. The
+/// clips come from the engine's own session - the UI no longer serialises
+/// its whole clip list per scrub frame (see engine decision 0009).
+#[derive(serde::Deserialize)]
+#[serde(rename_all = "camelCase")]
+struct PreviewSpec {
+ /// The timeline instant to composite, in seconds.
+ time: f64,
+ /// Preview frame width in pixels.
+ width: u32,
+ /// Preview frame height in pixels.
+ height: u32,
+}
+
/// The engine-composited frame at one instant, as raw RGBA bytes.
///
/// Serialised through the pool's mutex on a blocking thread: one scrub at a
@@ -565,8 +579,18 @@ struct PoolState(std::sync::Arc<std::sync::Mutex<wolfcut_media::ReaderPool>>);
#[tauri::command]
async fn preview_frame(
state: tauri::State<'_, PoolState>,
- request: export::PreviewFrameRequest,
+ editor: tauri::State<'_, editor_api::EditorState>,
+ request: PreviewSpec,
) -> Result<tauri::ipc::Response, String> {
+ let (clips, settings) = editor_api::flattened_clips(&editor)?;
+ let request = export::PreviewFrameRequest {
+ time: request.time,
+ width: request.width,
+ height: request.height,
+ rate_num: settings.rate_num,
+ rate_den: settings.rate_den,
+ clips,
+ };
let pool = std::sync::Arc::clone(&state.0);
tauri::async_runtime::spawn_blocking(move || {
let mut pool = pool.lock().map_err(|_| "reader pool poisoned".to_owned())?;
@@ -585,12 +609,44 @@ async fn preview_frame(
/// Runs on a blocking thread and reports progress through the
/// `export://progress` event, because a two-minute export must not freeze the
/// window and gives the UI nothing to show if it says nothing until it is done.
+/// What the UI sends to start an export: the destination, the quality, and
+/// its rasterised titles rejoining as image clips. The timeline itself is
+/// deliberately absent - the engine flattens its own session, so the pixels
+/// rendered are the model's, never a frontend's copy of it.
+#[derive(serde::Deserialize)]
+#[serde(rename_all = "camelCase")]
+struct ExportSpec {
+ /// The file to write.
+ output: String,
+ /// Constant rate factor; lower is better quality and a bigger file.
+ crf: u8,
+ /// The x264 speed/size preset name, e.g. "medium".
+ preset: String,
+ /// Rasterised text clips - fonts and layout live in the webview, so
+ /// titles arrive as images the flattener cannot produce itself.
+ #[serde(default)]
+ titles: Vec<export::ExportClip>,
+}
+
#[tauri::command]
async fn export_project(
app: tauri::AppHandle,
state: tauri::State<'_, ExportState>,
- request: export::ExportRequest,
+ editor: tauri::State<'_, editor_api::EditorState>,
+ request: ExportSpec,
) -> Result<String, String> {
+ let (mut clips, settings) = editor_api::flattened_clips(&editor)?;
+ clips.extend(request.titles);
+ let request = export::ExportRequest {
+ output: request.output,
+ width: settings.width,
+ height: settings.height,
+ rate_num: settings.rate_num,
+ rate_den: settings.rate_den,
+ crf: request.crf,
+ preset: request.preset,
+ clips,
+ };
let job = state.0.begin("export")?;
tauri::async_runtime::spawn_blocking(move || export::run(&app, request, job.cancel_flag()))
.await
diff --git a/desktop/src/App.tsx b/desktop/src/App.tsx
index 1f5109ff..c22d7e90 100644
--- a/desktop/src/App.tsx
+++ b/desktop/src/App.tsx
@@ -13,7 +13,6 @@ import type { MenuOption } from "./components/Menu";
import { ModifyProjectDialog } from "./components/ModifyProjectDialog";
import { Preview } from "./components/Preview";
import {
- exportClipsOf,
exportTitlesOf,
previewGhostAt,
previewSourceAt,
@@ -54,7 +53,6 @@ import {
probeMedia,
readMediaBytes,
templateSave,
- type ExportClip,
type TemplateInfo,
} from "./lib/engine";
import { findTransition } from "./lib/effects";
@@ -941,10 +939,12 @@ function Editor({
[project, timeline, playhead],
);
- // The exporter works from a flat list of the active timeline's clips.
- const exportClips = useMemo<ExportClip[]>(
- () => exportClipsOf(project, timeline),
- [project, timeline],
+ // The exporter flattens the engine's own session (decision 0009); the UI
+ // only counts renderable clips to know whether there is anything to show,
+ // and rasterises its titles.
+ const renderableClipCount = useMemo(
+ () => timeline.clips.filter((clip) => clip.kind !== "text").length,
+ [timeline],
);
const exportTitles = useMemo<ExportTitle[]>(
@@ -958,10 +958,9 @@ function Editor({
playing,
loaded,
playhead,
- exportClips,
+ project,
+ renderableClipCount,
frame,
- rateNum: session.rateNum,
- rateDen: session.rateDen,
latest,
});
@@ -1024,7 +1023,7 @@ function Editor({
{
label: "Export...",
icon: "export",
- disabled: exportClips.length === 0,
+ disabled: renderableClipCount === 0,
onSelect: openExport,
},
{
@@ -1125,7 +1124,7 @@ function Editor({
[
deleteSelected,
duration,
- exportClips,
+ renderableClipCount,
onCloseProject,
openExport,
openSettings,
@@ -1551,7 +1550,7 @@ function Editor({
rateNum={session.rateNum}
rateDen={session.rateDen}
duration={duration}
- clips={exportClips}
+ clipCount={renderableClipCount}
titles={exportTitles}
onClose={() => setExporting(false)}
/>
diff --git a/desktop/src/components/ExportDialog.tsx b/desktop/src/components/ExportDialog.tsx
index 22cb66f7..ad52722e 100644
--- a/desktop/src/components/ExportDialog.tsx
+++ b/desktop/src/components/ExportDialog.tsx
@@ -84,7 +84,7 @@ export function ExportDialog({
rateNum,
rateDen,
duration,
- clips,
+ clipCount,
titles,
onClose,
}: {
@@ -95,7 +95,10 @@ export function ExportDialog({
rateNum: number;
rateDen: number;
duration: number;
- clips: ExportClip[];
+ /** Non-text clips on the active timeline. The engine flattens the clips
+ * itself (engine decision 0009); the dialog only needs to know whether
+ * there is anything to export and how to describe it. */
+ clipCount: number;
titles: ExportTitle[];
onClose: () => void;
}) {
@@ -111,7 +114,7 @@ export function ExportDialog({
}, []);
const running = phase.kind === "running";
- const empty = clips.length === 0 && titles.length === 0;
+ const empty = clipCount === 0 && titles.length === 0;
const browse = async () => {
const chosen = await save({
@@ -153,13 +156,9 @@ export function ExportDialog({
const path = await exportProject({
output,
- width,
- height,
- rateNum,
- rateDen,
crf: quality.crf,
preset: quality.preset,
- clips: [...clips, ...overlays],
+ titles: overlays,
});
setPhase({ kind: "done", path });
} catch (cause) {
@@ -225,7 +224,7 @@ export function ExportDialog({
<Row
label="Contents"
value={
- `${clips.length} clip${clips.length === 1 ? "" : "s"}` +
+ `${clipCount} clip${clipCount === 1 ? "" : "s"}` +
(titles.length > 0 ? ` · ${titles.length} title${titles.length === 1 ? "" : "s"}` : "")
}
/>
diff --git a/desktop/src/hooks/useEngineTruth.ts b/desktop/src/hooks/useEngineTruth.ts
index 09ada67a..86621c1a 100644
--- a/desktop/src/hooks/useEngineTruth.ts
+++ b/desktop/src/hooks/useEngineTruth.ts
@@ -8,11 +8,16 @@
* frames continuously at up to 640px - request at the transport's position,
* present, request the next when it lands (desktop decision 0009). Single
* layers keep the smooth element preview.
+ *
+ * The request carries an instant and a resolution, nothing else: the engine
+ * flattens its own session (engine decision 0009). The UI used to serialise
+ * its whole flattened clip list into every one of these requests - per
+ * scrub, per streamed frame.
*/
import { useEffect, useRef, useState } from "react";
import { clipsAt, type EditorProject } from "../lib/editor";
-import { previewFrame, type ExportClip } from "../lib/engine";
+import { previewFrame } from "../lib/engine";
export interface EngineStill {
bytes: ArrayBuffer;
@@ -33,26 +38,24 @@ export function useEngineTruth({
playing,
loaded,
playhead,
- exportClips,
+ project,
+ renderableClipCount,
frame,
- rateNum,
- rateDen,
latest,
}: {
playing: boolean;
loaded: boolean;
playhead: number;
- exportClips: ExportClip[];
+ /** The engine's state; a new identity per edit refreshes the paused still. */
+ project: EditorProject;
+ /** Non-text clips on the active timeline - zero means nothing to composite. */
+ renderableClipCount: number;
frame: { width: number; height: number };
- rateNum: number;
- rateDen: number;
/** Live values, read mid-flight without restarting the loops. */
latest: { current: { playhead: number; frame: { width: number; height: number }; project: EditorProject } };
}): EngineStill | null {
const [engineStill, setEngineStill] = useState<EngineStill | null>(null);
const stillToken = useRef(0);
- const exportClipsRef = useRef(exportClips);
- exportClipsRef.current = exportClips;
// The paused dwell.
useEffect(() => {
@@ -61,18 +64,11 @@ export function useEngineTruth({
if (playing) return;
const token = ++stillToken.current;
setEngineStill(null);
- if (!loaded || exportClips.length === 0) return;
+ if (!loaded || renderableClipCount === 0) return;
const timer = window.setTimeout(() => {
const { width, height } = capped(frame, 960);
- previewFrame({
- time: latest.current.playhead,
- width,
- height,
- rateNum,
- rateDen,
- clips: exportClips,
- })
+ previewFrame({ time: latest.current.playhead, width, height })
.then((bytes) => {
if (stillToken.current === token) setEngineStill({ bytes, width, height });
})
@@ -81,8 +77,9 @@ export function useEngineTruth({
});
}, 160);
return () => window.clearTimeout(timer);
+ // `project` is the refresh signal: an edit while paused must re-fetch.
// eslint-disable-next-line react-hooks/exhaustive-deps
- }, [playing, loaded, playhead, exportClips, frame, rateNum, rateDen]);
+ }, [playing, loaded, playhead, project, renderableClipCount, frame]);
// The playback stream. Pull, not push: one request in flight, never a
// queue of stale frames; the pool's warm readers make consecutive
@@ -108,14 +105,7 @@ export function useEngineTruth({
}
const { width, height } = capped(latest.current.frame, 640);
try {
- const bytes = await previewFrame({
- time,
- width,
- height,
- rateNum,
- rateDen,
- clips: exportClipsRef.current,
- });
+ const bytes = await previewFrame({ time, width, height });
if (live) setEngineStill({ bytes, width, height });
} catch {
// A failed frame keeps the approximation on screen; back off so a
@@ -129,8 +119,7 @@ export function useEngineTruth({
return () => {
live = false;
};
- // eslint-disable-next-line react-hooks/exhaustive-deps
- }, [playing, loaded, rateNum, rateDen]);
+ }, [playing, loaded, latest]);
return engineStill;
}
diff --git a/desktop/src/lib/engine.ts b/desktop/src/lib/engine.ts
index d24c2f6d..fa820cf2 100644
--- a/desktop/src/lib/engine.ts
+++ b/desktop/src/lib/engine.ts
@@ -370,14 +370,15 @@ export interface ExportClip {
export interface ExportRequest {
output: string;
- width: number;
- height: number;
- /** Exact frame rate. Never send a rounded decimal here. */
- rateNum: number;
- rateDen: number;
crf: number;
preset: string;
- clips: ExportClip[];
+ /**
+ * Rasterised titles, rejoining as image clips. The timeline itself is
+ * deliberately absent: the engine flattens its own session (engine
+ * decision 0009), so size, rate and clips all come from the model. The
+ * webview contributes only what it genuinely owns - fonts and layout.
+ */
+ titles: ExportClip[];
}
export interface ExportProgress {
@@ -401,17 +402,15 @@ export async function cancelExport(): Promise<void> {
/**
* The engine-composited frame at one instant: the exporter's own plan,
- * compositor and effects, fed from the host's reader pool. Raw RGBA bytes,
- * exactly `width * height * 4` of them. This is what the paused monitor
- * shows - the true frame, not the approximation.
+ * compositor and effects, fed from the host's reader pool and flattened
+ * from the engine's own session. Raw RGBA bytes, exactly
+ * `width * height * 4` of them. This is what the paused monitor shows -
+ * the true frame, not the approximation.
*/
export async function previewFrame(request: {
time: number;
width: number;
height: number;
- rateNum: number;
- rateDen: number;
- clips: ExportClip[];
}): Promise<ArrayBuffer> {
return invoke<ArrayBuffer>("preview_frame", { request });
}
diff --git a/desktop/src/lib/monitor.test.ts b/desktop/src/lib/monitor.test.ts
index 7c8b6ad6..38693374 100644
--- a/desktop/src/lib/monitor.test.ts
+++ b/desktop/src/lib/monitor.test.ts
@@ -11,7 +11,6 @@ import { describe, expect, test } from "vitest";
import type { Clip, EditorProject } from "./editor";
import {
- exportClipsOf,
previewGhostAt,
previewSourceAt,
previewVeilAt,
@@ -169,23 +168,6 @@ describe("previewVeilAt", () => {
});
});
-describe("exportClipsOf", () => {
- test("flattens with track state, chains and audio knowledge", () => {
- const p = project([
- clip({ id: "a" }),
- clip({ id: "text", kind: "text", text: undefined }),
- ]);
- p.timelines[0].tracks[0].muted = true;
-
- const flat = exportClipsOf(p, timeline(p));
- expect(flat).toHaveLength(1);
- expect(flat[0].muted).toBe(true);
- expect(flat[0].hasAudio).toBe(true);
- expect(flat[0].track).toBe(0);
- expect(flat[0].transition).toBeNull();
- });
-});
-
describe("textOverlaysAt", () => {
test("only visible text at the playhead, bottom-most first", () => {
const style = { content: "hi" } as never;
diff --git a/desktop/src/lib/monitor.ts b/desktop/src/lib/monitor.ts
index 6abcf56b..697bf010 100644
--- a/desktop/src/lib/monitor.ts
+++ b/desktop/src/lib/monitor.ts
@@ -8,8 +8,6 @@
* these; nothing else derives them a second way.
*/
-import { buildEffectChain } from "./effects";
-import { buildChain } from "./filters";
import {
clipsAt,
findMedia,
@@ -18,7 +16,6 @@ import {
type EditorProject,
type TimelineData,
} from "./editor";
-import type { ExportClip } from "./engine";
import type { TextStyle } from "./text";
/** The clip the element preview shows: top-most visual clip at the playhead. */
@@ -176,49 +173,6 @@ export function previewVeilAt(
return null;
}
-/** The active timeline flattened for the exporter. Text clips are excluded;
- * they rasterise separately and rejoin as image clips. */
-export function exportClipsOf(project: EditorProject, timeline: TimelineData): ExportClip[] {
- return timeline.clips.flatMap((clip) => {
- if (clip.kind === "text") return [];
- const media = findMedia(project, clip.mediaId);
- const track = findTrack(project, clip.trackId);
- const index = timeline.tracks.findIndex((candidate) => candidate.id === clip.trackId);
- if (!media || !track || index < 0) return [];
- return [
- {
- path: media.path,
- kind: clip.kind as "video" | "audio" | "image",
- start: clip.start,
- duration: clip.duration,
- sourceStart: clip.sourceStart,
- track: index,
- hidden: !track.visible,
- muted: track.muted || clip.muted === true,
- volume: clip.volume,
- fadeIn: clip.fadeIn,
- fadeOut: clip.fadeOut,
- filterChain: buildChain(clip.filters) ?? "",
- speed: clip.speed,
- preservePitch: clip.preservePitch,
- scale: clip.scale,
- offsetX: clip.offsetX,
- offsetY: clip.offsetY,
- rotation: clip.rotation,
- opacity: clip.opacity,
- videoFilterChain: buildEffectChain(clip.videoEffects) ?? "",
- transition:
- clip.transitionIn && precedingClip(project, clip.id)
- ? { kind: clip.transitionIn.id, duration: clip.transitionIn.duration }
- : null,
- mediaWidth: media.width,
- mediaHeight: media.height,
- hasAudio: media.hasAudio,
- },
- ];
- });
-}
-
/** The active timeline's titles, flattened for rasterisation at export. */
export function exportTitlesOf(project: EditorProject, timeline: TimelineData): ExportTitle[] {
return timeline.clips.flatMap((clip) => {