Skip to content

Open source CapCut alternative.

TypeScript

fix(cut): export a reshaped clip in the project's shape [rebuild]

David Le050ea0fc1a1c
diff --git a/docs/guides/cut/README.md b/docs/guides/cut/README.md
index 77f695bf..a0a5bfc5 100644
--- a/docs/guides/cut/README.md
+++ b/docs/guides/cut/README.md
@@ -54,7 +54,7 @@ Guides draw over the preview from the button beside the timeline zoom: thirds, c
## The export
-Best uses original resolution, cadence, supported H.264/HEVC codec and audio settings. Whole files and trims copy compressed streams; compatible sequences copy video and encode joined audio. Interior joins need matching codec configurations and keyframes. Browser, Mac and cloud share packet copying; audio joins use FFmpeg on the project’s machine. The [local-compute guide](local-compute.md) covers browser handoff, the [color guide](color.md) HDR delivery.
+Best uses original resolution, cadence, supported H.264/HEVC codec and audio settings. Whole files and trims in the project’s shape copy compressed streams; compatible sequences copy video and encode joined audio. Interior joins need matching codec configurations and keyframes. Audio joins use FFmpeg on the project’s machine. The [local-compute guide](local-compute.md) covers browser handoff, the [color guide](color.md) HDR delivery.
## Sharing
diff --git a/site/src/cut/lib/sourceExportPlan.test.ts b/site/src/cut/lib/sourceExportPlan.test.ts
index 9b0b31d2..8cbf6d34 100644
--- a/site/src/cut/lib/sourceExportPlan.test.ts
+++ b/site/src/cut/lib/sourceExportPlan.test.ts
@@ -5,7 +5,7 @@ import type { ExportDoc } from "@/cut/lib/renderSnapshot";
import type { VideoClip } from "@/cut/lib/types";
const doc: ExportDoc = {
- aspect: "16:9", assets: [{ id: "source", fileName: "source.mp4", name: "Source", type: "video", duration: 904, width: 320, height: 240, url: "",
+ aspect: "4:3", assets: [{ id: "source", fileName: "source.mp4", name: "Source", type: "video", duration: 904, width: 320, height: 240, url: "",
color: { matrix: "bt709", fullRange: false, bitDepth: 8, detected: "rec709" } }],
clips: [{ id: "clip", assetId: "source", track: 0, start: 0, in: 15.137, out: 870.437, muted: false }],
audioClips: [], overlays: [], subtitles: { cues: [], showOnVideo: false, showOnTimeline: false },
@@ -20,6 +20,15 @@ test("a plain trim preserves the source frame and exact source window", async ()
expect("sourceSegments" in (await buildExportPayload("project", doc, settings, "preview")).spec).toBe(false);
});
+test("a source in another shape than the project renders to the project's frame", () => {
+ // The preview fits a 4:3 clip into a 9:16 frame; the file has to match it.
+ const vertical = { ...doc, aspect: "9:16" as const };
+ expect(sourceSequence(vertical)).toBeNull();
+ const frame = originalSettings(vertical.aspect, vertical.clips, vertical.assets, vertical);
+ expect(frame.height).toBeGreaterThan(frame.width);
+ expect(sourceExportPlan(vertical, frame)).toBeNull();
+});
+
test("selection ranges resolve inside the original trim", () => {
expect(sourceExportPlan(doc, { ...settings, range: { start: 3, end: 8 } }))
.toEqual([{ file: "source.mp4", from: 18.137, to: 23.137 }]);
diff --git a/site/src/cut/lib/sourceExportPlan.ts b/site/src/cut/lib/sourceExportPlan.ts
index c994b9cf..43bbcec5 100644
--- a/site/src/cut/lib/sourceExportPlan.ts
+++ b/site/src/cut/lib/sourceExportPlan.ts
@@ -1,14 +1,22 @@
import { recipeIsIdentity } from "@donkeycut/effects-kit";
import type { ExportDoc } from "@/cut/lib/renderSnapshot";
import type { ExportSettings } from "@/cut/lib/exportClient";
-import type { VideoClip } from "@/cut/lib/types";
+import { parseRatio, type VideoClip } from "@/cut/lib/types";
export type SourceSegment = { file: string; from: number; to: number };
-/** Plain sequential clips can reuse their source tracks. */
+/** How far a source's shape may sit from the project's and still copy: a
+ * 1918×1080 file in a 16:9 project is the same picture. */
+const SHAPE_TOLERANCE = 0.01;
+
+/** Plain sequential clips can reuse their source tracks, when their picture
+ * has the project's shape: the preview fits any other shape into the
+ * project's frame, so that file has to render. */
export function sourceSequence(doc: ExportDoc) {
if (!doc.clips.length || doc.audioClips.length || doc.overlays.length ||
(doc.subtitles.showOnVideo && doc.subtitles.cues.length)) return null;
+ const shape = parseRatio(doc.aspect);
+ if (!shape) return null;
const clips = [...doc.clips].sort((a, b) => a.start - b.start);
const segments: { asset: ExportDoc["assets"][number]; from: number; to: number }[] = [];
let end = 0;
@@ -32,6 +40,7 @@ export function sourceSequence(doc: ExportDoc) {
// delivery's own encoding copies as is.
const profile = asset.colorProfile ?? asset.color?.detected ?? "rec709";
if (!recipeIsIdentity(profile, doc.colorSpace ?? "sdr")) return null;
+ if (Math.abs(asset.width / asset.height / (shape.w / shape.h) - 1) > SHAPE_TOLERANCE) return null;
if (segments.length && (asset.width !== segments[0].asset.width || asset.height !== segments[0].asset.height)) return null;
const previous = segments.at(-1);
if (previous?.asset.id === asset.id && Math.abs(previous.to - clip.in) < 0.000001) previous.to = clip.out;
diff --git a/site/src/cut/server/ai/catalog.ts b/site/src/cut/server/ai/catalog.ts
index 9599383e..43d5bdc7 100644
--- a/site/src/cut/server/ai/catalog.ts
+++ b/site/src/cut/server/ai/catalog.ts
@@ -637,7 +637,7 @@ Templates (save_template / template_add) ride the same rail and now keep grades,
"publish-and-export": `# Publish & export
Publish tab fields (set_publish): caption (TikTok limit 4,000 chars INCLUDING tags/emoji; hook in the first line), tags (3–5 focused tags recommended; stored space-separated, rendered as #tags), soundTitle (TikTok lets you rename the sound once after posting), handle (shown as @handle in platform previews).
-Export (open_export): one-click presets — Share (1080p H.264 MP4, plays everywhere), Best (original file settings, H.264/HEVC MP4), Social 4K (the cut upscaled to 4K in H.264, because TikTok, Reels and YouTube transcode a 4K upload on a higher bitrate rung than a 1080p one, so it comes back sharper), Small (720p, fastest), Master (source size, ProRes 4444 in a MOV with PCM audio, for handing to another editor or archiving the cut) — and an Advanced panel with every axis: file name (the project's until typed over), range (the whole video, or the span from the first selected item's start to the last one's end when something is selected), format (MP4 or MOV), codec (H.264, HEVC at about half the size for newer devices, ProRes 422 HQ, ProRes 4444), resolution (Source, which matches the sharpest clip on the timeline along the project aspect with a 4K cap, preserving smaller sources; the named rungs below it; and the named rungs above it as marked upscales: ${EXPORT_RESOLUTIONS.map((r) => r.label).join(", ")}), frame rate (Source, the rate the footage plays at, read from the files; or 24, 30, 60), quality (High, Balanced, Small, or a typed bitrate in Mbps), audio (AAC or uncompressed PCM), color (the project's SDR / HDR HLG / HDR PQ space — set_project_color writes the same setting; HDR takes HEVC Main 10 or ProRes and greys H.264 out, tagged Rec.2020 with the HLG or PQ transfer, PQ from the Mac app carrying no static metadata), and a captions file — the subtitle track saved as an SRT to the browser's Downloads folder (the video lands in the project's exports), one per visible language, for platforms that take their own captions. ProRes and PCM take a MOV, and ProRes sets its own rate, so the quality scale and a typed bitrate grey out. A ProRes 4444 master keeps every pixel's own color: the whole composite is built at 4:4:4 for it, so titles, captions and stickers land in the file without the color smearing a 4:2:0 delivery gives them. The other formats subsample, which is what H.264 and HEVC do at the encoder anyway. Every preset runs at the source frame rate. Best preserves source resolution, fractional frame rate, supported H.264/HEVC codec, audio sample rate, channels and bitrates. Whole files and trims copy compressed streams; compatible sequences copy video and encode joined audio. Interior video joins need matching codec configurations and keyframe boundaries. Effects, captions, additional tracks and incompatible joins render with the selected source settings. Source resolution also matches source video/audio bitrates unless a custom bitrate or ProRes is chosen; extra soundtrack audio keeps the delivery audio budget. The dialog shows the size the choice will land at. Rendered H.264 files use High profile and HEVC uses Main, with two-second keyframes; packet copies keep source encoding. An engine from an older Donkey app cannot take a range or a typed name, and the export says to update the app. Source copies preserve the media frame. Composited exports use the project aspect, with titles and subtitles burned in. Files land in the project's exports/ folder and appear in the Media tab's Exports section, where each can be previewed plain or in TikTok/Instagram/YouTube chrome with the publish metadata rendered in place, revealed in Finder, or deleted.`,
+Export (open_export): one-click presets — Share (1080p H.264 MP4, plays everywhere), Best (original file settings, H.264/HEVC MP4), Social 4K (the cut upscaled to 4K in H.264, because TikTok, Reels and YouTube transcode a 4K upload on a higher bitrate rung than a 1080p one, so it comes back sharper), Small (720p, fastest), Master (source size, ProRes 4444 in a MOV with PCM audio, for handing to another editor or archiving the cut) — and an Advanced panel with every axis: file name (the project's until typed over), range (the whole video, or the span from the first selected item's start to the last one's end when something is selected), format (MP4 or MOV), codec (H.264, HEVC at about half the size for newer devices, ProRes 422 HQ, ProRes 4444), resolution (Source, which matches the sharpest clip on the timeline along the project aspect with a 4K cap, preserving smaller sources; the named rungs below it; and the named rungs above it as marked upscales: ${EXPORT_RESOLUTIONS.map((r) => r.label).join(", ")}), frame rate (Source, the rate the footage plays at, read from the files; or 24, 30, 60), quality (High, Balanced, Small, or a typed bitrate in Mbps), audio (AAC or uncompressed PCM), color (the project's SDR / HDR HLG / HDR PQ space — set_project_color writes the same setting; HDR takes HEVC Main 10 or ProRes and greys H.264 out, tagged Rec.2020 with the HLG or PQ transfer, PQ from the Mac app carrying no static metadata), and a captions file — the subtitle track saved as an SRT to the browser's Downloads folder (the video lands in the project's exports), one per visible language, for platforms that take their own captions. ProRes and PCM take a MOV, and ProRes sets its own rate, so the quality scale and a typed bitrate grey out. A ProRes 4444 master keeps every pixel's own color: the whole composite is built at 4:4:4 for it, so titles, captions and stickers land in the file without the color smearing a 4:2:0 delivery gives them. The other formats subsample, which is what H.264 and HEVC do at the encoder anyway. Every preset runs at the source frame rate. Best preserves source resolution, fractional frame rate, supported H.264/HEVC codec, audio sample rate, channels and bitrates. Whole files and trims whose picture has the project's shape copy compressed streams; compatible sequences copy video and encode joined audio. Interior video joins need matching codec configurations and keyframe boundaries. Effects, captions, additional tracks and incompatible joins render with the selected source settings. Source resolution also matches source video/audio bitrates unless a custom bitrate or ProRes is chosen; extra soundtrack audio keeps the delivery audio budget. The dialog shows the size the choice will land at. Rendered H.264 files use High profile and HEVC uses Main, with two-second keyframes; packet copies keep source encoding. An engine from an older Donkey app cannot take a range or a typed name, and the export says to update the app. Source copies preserve the media frame. Composited exports use the project aspect, with titles and subtitles burned in. Files land in the project's exports/ folder and appear in the Media tab's Exports section, where each can be previewed plain or in TikTok/Instagram/YouTube chrome with the publish metadata rendered in place, revealed in Finder, or deleted.`,
};
/** System prompt shared by all providers. */