Skip to content

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

feat: preview quality picker replaces the footer fps readout

Jareerd5db5246a736
diff --git a/desktop/src/App.tsx b/desktop/src/App.tsx
index 0f8c8d0b..5bc74fe1 100644
--- a/desktop/src/App.tsx
+++ b/desktop/src/App.tsx
@@ -953,7 +953,9 @@ function Editor({
);
// The engine's true frames: paused dwell + playback stream. See
- // useEngineTruth and desktop decision 0009.
+ // useEngineTruth and desktop decision 0009. Quality is the footer's
+ // dropdown: what fraction of the output frame the engine composites.
+ const [previewQuality, setPreviewQuality] = useState(0.5);
const engineStill = useEngineTruth({
playing,
loaded,
@@ -962,6 +964,7 @@ function Editor({
renderableClipCount,
frame,
fps: session ? session.rateNum / session.rateDen : 30,
+ quality: previewQuality,
latest,
});
@@ -1210,6 +1213,8 @@ function Editor({
duration={duration}
frameRate={frameRate}
frame={frame}
+ quality={previewQuality}
+ onQualityChange={setPreviewQuality}
transform={
previewClip
? {
diff --git a/desktop/src/components/Preview.tsx b/desktop/src/components/Preview.tsx
index b7950c97..e3701723 100644
--- a/desktop/src/components/Preview.tsx
+++ b/desktop/src/components/Preview.tsx
@@ -250,6 +250,8 @@ export function Preview({
duration,
frameRate,
frame,
+ quality,
+ onQualityChange,
transform,
opacity,
effects,
@@ -277,6 +279,9 @@ export function Preview({
frameRate: number;
/** The project's output size, shown and changed in the footer. */
frame: { width: number; height: number };
+ /** Engine-preview resolution as a fraction of the output frame. */
+ quality: number;
+ onQualityChange: (quality: number) => void;
/** The displayed clip's picture transform. Null when nothing is showing. */
transform: PreviewTransform | null;
/** The displayed clip's blend strength, 1 being solid. */
@@ -774,15 +779,72 @@ export function Preview({
</span>
)}
/>
- <span className="truncate font-technical text-[10px] text-tertiary">
- {frameRate.toFixed(2)} fps
- </span>
+ <QualityMenu quality={quality} onQualityChange={onQualityChange} />
</span>
</div>
</div>
);
}
+/**
+ * Engine-preview resolutions, as fractions of the output frame. The labels
+ * follow the convention every editor uses; the pixels follow the project.
+ */
+const PREVIEW_QUALITIES = [
+ { label: "Full", ratio: "1:1", value: 1 },
+ { label: "Half", ratio: "1:2", value: 0.5 },
+ { label: "Quarter", ratio: "1:4", value: 0.25 },
+] as const;
+
+/**
+ * The preview-quality picker, next to the output-size menu it modifies:
+ * what fraction of the frame the engine composites for the monitor. The
+ * frame rate is not shown here - it lives in the Details panel, and the
+ * tray reads better carrying only what can be changed from it.
+ */
+function QualityMenu({
+ quality,
+ onQualityChange,
+}: {
+ quality: number;
+ onQualityChange: (quality: number) => void;
+}) {
+ const active =
+ PREVIEW_QUALITIES.find((option) => option.value === quality) ?? PREVIEW_QUALITIES[1];
+ return (
+ <Menu
+ align="right"
+ direction="up"
+ groups={[
+ PREVIEW_QUALITIES.map((option) => ({
+ label: `${option.label} — ${option.ratio}`,
+ leading: (
+ <span
+ className={`h-1 w-1 rounded-full ${
+ option.value === active.value ? "bg-current" : "bg-transparent"
+ }`}
+ />
+ ),
+ onSelect: () => onQualityChange(option.value),
+ })),
+ ]}
+ trigger={(open) => (
+ <span
+ title={`Preview quality: ${active.label} (${active.ratio})`}
+ className={`flex items-center gap-1 rounded-md px-1.5 py-1 transition-colors ${
+ open
+ ? "bg-active text-primary"
+ : "text-tertiary hover:bg-hover hover:text-secondary"
+ }`}
+ >
+ <span className="font-technical text-[10px] tabular-nums">{active.ratio}</span>
+ <Icon name="chevronDown" size={10} />
+ </span>
+ )}
+ />
+ );
+}
+
/**
* The engine's paused-frame composite, blitted into the frame box.
*
diff --git a/desktop/src/hooks/useEngineTruth.ts b/desktop/src/hooks/useEngineTruth.ts
index 60ac08d3..880371b3 100644
--- a/desktop/src/hooks/useEngineTruth.ts
+++ b/desktop/src/hooks/useEngineTruth.ts
@@ -2,15 +2,16 @@
* The engine's true frames for the monitor: the paused dwell and the
* playback stream, one owner.
*
- * Paused: when the playhead settles, fetch the exporter's own composite at
- * up to 960px and hold it over the approximation until the playhead moves.
- * Playing: while two or more visual layers sit under the playhead, stream
- * frames at up to 640px against the transport clock - requests are
+ * Paused: when the playhead settles, fetch the exporter's own composite and
+ * hold it over the approximation until the playhead moves. Playing: while
+ * two or more visual layers sit under the playhead, stream frames against
+ * the transport clock - requests are
* quantised to the project's frame grid and issued one measured round-trip
* ahead of the interpolated playhead, so a frame lands about when it is
* due; each presented frame also warms the engine's cache for the instants
* after it (desktop decision 0009). Single layers keep the smooth element
- * preview.
+ * preview. Both paths fetch at the user's preview quality - a fraction of
+ * the output frame, chosen in the monitor's footer.
*
* The request carries an instant and a resolution, nothing else: the engine
* flattens its own session (engine decision 0009). The UI used to serialise
@@ -28,12 +29,12 @@ export interface EngineStill {
height: number;
}
-/** Even dimensions at an aspect-preserving cap - decoders round odd sizes. */
-function capped(frame: { width: number; height: number }, cap: number) {
- const scale = Math.min(1, cap / Math.max(frame.width, frame.height));
+/** Even dimensions at a fraction of the frame - decoders round odd sizes. */
+function scaled(frame: { width: number; height: number }, quality: number) {
+ const fraction = Number.isFinite(quality) && quality > 0 ? Math.min(quality, 1) : 0.5;
return {
- width: Math.max(2, Math.round((frame.width * scale) / 2) * 2),
- height: Math.max(2, Math.round((frame.height * scale) / 2) * 2),
+ width: Math.max(2, Math.round((frame.width * fraction) / 2) * 2),
+ height: Math.max(2, Math.round((frame.height * fraction) / 2) * 2),
};
}
@@ -45,6 +46,7 @@ export function useEngineTruth({
renderableClipCount,
frame,
fps,
+ quality,
latest,
}: {
playing: boolean;
@@ -57,6 +59,8 @@ export function useEngineTruth({
frame: { width: number; height: number };
/** The project's frame rate; the grid streamed requests snap to. */
fps: number;
+ /** Preview resolution as a fraction of the output frame: 1, 0.5, 0.25. */
+ quality: number;
/** Live values, read mid-flight without restarting the loops. */
latest: { current: { playhead: number; frame: { width: number; height: number }; project: EditorProject } };
}): EngineStill | null {
@@ -73,7 +77,7 @@ export function useEngineTruth({
if (!loaded || renderableClipCount === 0) return;
const timer = window.setTimeout(() => {
- const { width, height } = capped(frame, 960);
+ const { width, height } = scaled(frame, quality);
previewFrame({ time: latest.current.playhead, width, height })
.then((bytes) => {
if (stillToken.current === token) setEngineStill({ bytes, width, height });
@@ -85,7 +89,7 @@ export function useEngineTruth({
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, project, renderableClipCount, frame]);
+ }, [playing, loaded, playhead, project, renderableClipCount, frame, quality]);
// The playback stream, paced by the transport clock. Still pull - one
// request in flight, never a queue of stale frames - but the requests are
@@ -95,7 +99,8 @@ export function useEngineTruth({
// the same instant is never composited twice. After each presented frame
// a fire-and-forget prefetch warms the engine's cache for the instants
// after it, which keeps the pool's readers rolling forward and turns the
- // next pulls into cache hits. Rate beats resolution while moving.
+ // next pulls into cache hits. Frames come back at the chosen preview
+ // quality; dropping it is the lever when playback cannot keep up.
useEffect(() => {
if (!playing || !loaded) return;
let live = true;
@@ -129,7 +134,7 @@ export function useEngineTruth({
await wait(250 / rate);
continue;
}
- const { width, height } = capped(latest.current.frame, 640);
+ const { width, height } = scaled(latest.current.frame, quality);
const started = performance.now();
try {
const bytes = await previewFrame({ time: target / rate, width, height });
@@ -155,7 +160,7 @@ export function useEngineTruth({
return () => {
live = false;
};
- }, [playing, loaded, latest, fps]);
+ }, [playing, loaded, latest, fps, quality]);
return engineStill;
}