Skip to content

Open source CapCut alternative.

TypeScript

feat(site): export names the file, keeps the source rate, delivers a range, upscales to 4K [rebuild]

David Le4393c07d7013
diff --git a/site/src/cut/components/ExportDialog.tsx b/site/src/cut/components/ExportDialog.tsx
index 9bb266d7..293e3894 100644
--- a/site/src/cut/components/ExportDialog.tsx
+++ b/site/src/cut/components/ExportDialog.tsx
@@ -15,7 +15,9 @@ import {
import { Input } from "@/components/ui/input";
import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from "@/components/ui/select";
import { Slider } from "@/components/ui/slider";
+import { Switch } from "@/components/ui/switch";
import {
+ DEFAULT_EXPORT_FPS,
EXPORT_AUDIO,
EXPORT_CODECS,
EXPORT_CONTAINERS,
@@ -28,14 +30,20 @@ import {
quickPresetOf,
resolutionOptions,
resolveResolution,
+ selectionRange,
type ExportChoice,
type ExportCodec,
type ExportContainer,
+ type ExportSettings,
} from "@/cut/lib/exportClient";
import { useCutMode } from "@/cut/lib/backend/hooks";
-import { canRenderInBrowser } from "@/cut/lib/exportRender";
+import { downloadText } from "@/cut/lib/download";
+import { deliverySpan, exportBaseName } from "@/cut/lib/exportDelivery";
+import { canRenderInBrowser, sourceFrameRate, sourceFrameRateKey } from "@/cut/lib/exportRender";
import { useExports } from "@/cut/lib/exportStore";
import { projectDuration, useEditor } from "@/cut/lib/store";
+import { subtitleFiles } from "@/cut/lib/subtitleFile";
+import { formatTime } from "@/cut/lib/time";
import { cn } from "@/lib/utils";
/** A file format the menu offers: a container carrying a codec. MP4 cannot
@@ -64,6 +72,9 @@ export function ExportDialog() {
const assets = useEditor((s) => s.assets);
const audioClips = useEditor((s) => s.audioClips);
const overlays = useEditor((s) => s.overlays);
+ const subtitles = useEditor((s) => s.subtitles);
+ const multiSelection = useEditor((s) => s.multiSelection);
+ const projectName = useEditor((s) => s.projectName);
const duration = useMemo(
() => projectDuration({ clips, audioClips, overlays }),
[clips, audioClips, overlays]
@@ -72,7 +83,7 @@ export function ExportDialog() {
() => resolutionOptions(aspect, clips, assets),
[aspect, clips, assets]
);
- // The size rungs in slider order, smallest on the left, source on the right.
+ // The size rungs in slider order, smallest on the left, largest on the right.
const rungs = useMemo(() => [...resolutions].reverse(), [resolutions]);
const [choice, setChoice] = useState<ExportChoice>(EXPORT_QUICK_PRESETS[1].choice);
// The field's own text, so a decimal in progress ("1.") survives the parse.
@@ -81,9 +92,59 @@ export function ExportDialog() {
// options add up to, until a preset tile is clicked.
const [customPicked, setCustomPicked] = useState(false);
const [moreOpen, setMoreOpen] = useState(false);
+ // The file's name, the project's until typed over.
+ const [name, setName] = useState(projectName);
+ // What stretch of the timeline the file carries.
+ const [rangeMode, setRangeMode] = useState<"all" | "selection">("all");
+ // A captions file beside the video.
+ const [withCaptions, setWithCaptions] = useState(false);
+ // The footage's frame rate, read from the sources once the dialog opens;
+ // a "source" frame-rate choice resolves to it. Undefined while the probe
+ // runs, null for a cut with no readable video. The probe re-runs only when
+ // the set of sources it reads changes — an upload ticking its progress
+ // through the assets list leaves it alone — and a superseded probe closes
+ // its readers.
+ const probeKey = sourceFrameRateKey({ clips, assets });
+ const [probe, setProbe] = useState<{ key: string; fps: number | null } | null>(null);
+ useEffect(() => {
+ const abort = new AbortController();
+ const s = useEditor.getState();
+ void sourceFrameRate({ clips: s.clips, assets: s.assets }, (a) => a.url, { signal: abort.signal }).then(
+ (fps) => {
+ if (!abort.signal.aborted) setProbe({ key: probeKey, fps });
+ }
+ );
+ return () => abort.abort();
+ }, [probeKey]);
+ const probing = probe?.key !== probeKey;
+ const sourceFps = probing ? undefined : probe.fps;
+ const selection = useMemo(
+ () => selectionRange({ multiSelection, clips, audioClips, overlays, subtitles }),
+ [multiSelection, clips, audioClips, overlays, subtitles]
+ );
+ const range = rangeMode === "selection" && selection ? selection : undefined;
+ const span = deliverySpan(range, duration);
const preset = customPicked ? null : quickPresetOf(choice, resolutions);
- const settings = useMemo(() => choiceSettings(choice, resolutions), [choice, resolutions]);
+ // The file's base name. It rides in the settings only when typed over: the
+ // engine names a file after the project itself, so an untouched name asks
+ // nothing extra of it.
+ const baseName = exportBaseName(name || projectName);
+ const typedName = baseName !== exportBaseName(projectName);
+ const settings = useMemo<ExportSettings>(
+ () => ({
+ ...choiceSettings(choice, resolutions, sourceFps ?? DEFAULT_EXPORT_FPS),
+ ...(typedName ? { name: baseName } : {}),
+ ...(range ? { range } : {}),
+ }),
+ [choice, resolutions, sourceFps, typedName, baseName, range]
+ );
const set = (patch: Partial<ExportChoice>) => setChoice((c) => ({ ...c, ...patch }));
+ const captionFiles = useMemo(
+ () => subtitleFiles(subtitles, baseName, range),
+ [subtitles, baseName, range]
+ );
+ // A "source" rate is not known until the probe answers; the button waits.
+ const waiting = probing && choice.fps === "source";
// A browser-resident project renders in this tab when it can, and on the
// cloud worker when it can't; ask up front which it is, so the dialog says
@@ -133,12 +194,17 @@ export function ExportDialog() {
background: s.background,
},
settings,
- s.projectName
+ baseName
);
+ // The captions file is made here and saved at once; the video follows
+ // through the dock when its render lands.
+ if (withCaptions) {
+ for (const f of captionFiles) downloadText(f.text, f.name, "application/x-subrip");
+ }
setExportOpen(false); // the dock takes it from here
};
- const sizeEstimate = formatSizeEstimate(estimateExportBytes(settings, duration));
+ const sizeEstimate = formatSizeEstimate(estimateExportBytes(settings, span));
const prores = settings.codec === "prores";
const resolution = resolveResolution(resolutions, choice.resolution);
const rungIndex = Math.max(0, rungs.findIndex((r) => r.id === resolution.id));
@@ -156,7 +222,7 @@ export function ExportDialog() {
</DialogHeader>
<DialogBody className="mx-0 my-0 flex flex-col gap-6 px-6 pt-1 pb-6">
- <div className="grid grid-cols-5 gap-1.5 max-sm:grid-cols-3" role="radiogroup" aria-label="Export preset">
+ <div className="grid grid-cols-6 gap-1.5 max-sm:grid-cols-3" role="radiogroup" aria-label="Export preset">
{EXPORT_QUICK_PRESETS.map((p) => (
<PresetTile
key={p.id}
@@ -180,9 +246,12 @@ export function ExportDialog() {
<Scale
label="Resolution"
- value={`${settings.width} × ${settings.height}`}
+ value={`${settings.width} × ${settings.height}${resolution.upscale ? " · upscaled" : ""}`}
index={rungIndex}
- stops={rungs.map((r) => ({ label: r.label, title: `${r.width} × ${r.height}` }))}
+ stops={rungs.map((r) => ({
+ label: r.label,
+ title: `${r.width} × ${r.height}${r.upscale ? " · upscaled from the source" : ""}`,
+ }))}
onIndex={(i) => set({ resolution: rungs[i]!.id })}
/>
@@ -200,12 +269,45 @@ export function ExportDialog() {
/>
<div className="flex flex-col gap-3">
+ <Field label="File name">
+ <Input
+ aria-label="File name"
+ className="h-8 w-48 text-sm"
+ value={name}
+ placeholder={projectName}
+ onChange={(e) => setName(e.target.value)}
+ />
+ </Field>
+ {selection && (
+ <Field label="Range">
+ <Select value={rangeMode} onValueChange={(v) => setRangeMode(v as "all" | "selection")}>
+ <SelectTrigger className="w-fit min-w-32" aria-label="Range">
+ <SelectValue />
+ </SelectTrigger>
+ <SelectContent align="end">
+ <SelectItem value="all">Whole video</SelectItem>
+ <SelectItem
+ value="selection"
+ title="From the first selected item's start to the last one's end, every row included"
+ >
+ Selection · {formatTime(selection.start)}–{formatTime(selection.end)}
+ </SelectItem>
+ </SelectContent>
+ </Select>
+ </Field>
+ )}
<Field label="Frame rate">
- <Select value={String(choice.fps)} onValueChange={(v) => set({ fps: Number(v) })}>
- <SelectTrigger className="w-32" aria-label="Frame rate">
+ <Select
+ value={String(choice.fps)}
+ onValueChange={(v) => set({ fps: v === "source" ? "source" : Number(v) })}
+ >
+ <SelectTrigger className="w-fit min-w-32" aria-label="Frame rate">
<SelectValue />
</SelectTrigger>
<SelectContent align="end">
+ <SelectItem value="source" title="The rate the footage plays at">
+ {probing ? "Source · reading…" : `Source · ${sourceFps ?? DEFAULT_EXPORT_FPS} fps`}
+ </SelectItem>
{EXPORT_FRAME_RATES.map((f) => (
<SelectItem key={f} value={String(f)}>
{f} fps
@@ -302,6 +404,18 @@ export function ExportDialog() {
<span className="text-xs text-muted-foreground">Mbps</span>
</label>
</Field>
+ {captionFiles.length > 0 && (
+ <Field
+ label="Captions file"
+ hint="Saves the captions as an SRT file to your Downloads folder, for platforms that take their own captions."
+ >
+ <Switch
+ aria-label="Save a captions file"
+ checked={withCaptions}
+ onCheckedChange={(v) => setWithCaptions(v === true)}
+ />
+ </Field>
+ )}
</CollapsibleContent>
</Collapsible>
@@ -318,11 +432,12 @@ export function ExportDialog() {
<span className="truncate">
{settings.width} × {settings.height} · {settings.fps} fps ·{" "}
{FORMATS.find((f) => f.id === formatId)?.label ?? formatId} · {settings.audioCodec.toUpperCase()}
+ {range ? ` · ${formatTime(span)}` : ""}
</span>
<span className="shrink-0 tabular-nums">{sizeEstimate}</span>
</div>
- <Button className="h-11 w-full text-base" onClick={run}>
- Export video
+ <Button className="h-11 w-full text-base" onClick={run} disabled={waiting}>
+ {waiting ? "Reading the footage…" : "Export video"}
</Button>
</DialogFooter>
</DialogContent>
@@ -354,7 +469,7 @@ function PresetTile({
aria-checked={checked}
title={title}
className={cn(
- "flex h-8 min-w-0 items-center justify-center rounded-lg border px-2 text-sm font-medium whitespace-nowrap transition-colors",
+ "flex h-8 min-w-0 items-center justify-center rounded-lg border px-1.5 text-xs font-medium whitespace-nowrap transition-colors",
checked
? "border-primary bg-primary/10 text-foreground"
: "border-transparent bg-muted/60 text-muted-foreground hover:bg-muted hover:text-foreground"
diff --git a/site/src/cut/components/TopBar.tools.ts b/site/src/cut/components/TopBar.tools.ts
index cf4e4184..aea2a138 100644
--- a/site/src/cut/components/TopBar.tools.ts
+++ b/site/src/cut/components/TopBar.tools.ts
@@ -47,7 +47,7 @@ export const TOP_BAR_TOOLS = [
{
name: "open_export",
description:
- "Open the export dialog so the user can render the cut: quick presets (Share, Best, Small, Master) or the advanced panel — format MP4/MOV, codec H.264/HEVC/ProRes, resolution Source down to 720p, frame rate 24/30/60, quality tier or bitrate, AAC or PCM audio. Exporting itself stays a user action.",
+ "Open the export dialog so the user can render the cut: quick presets (Share, Best, Social 4K, Small, Master) or the advanced panel — file name, range (whole video or the selected items' span), format MP4/MOV, codec H.264/HEVC/ProRes, resolution from a 4K upscale through Source down to 720p, frame rate Source/24/30/60, quality tier or bitrate, AAC or PCM audio, and a captions file (SRT) saved beside the video. Exporting itself stays a user action.",
inputSchema: obj({}),
},
] as const satisfies readonly AiToolDef[];
diff --git a/site/src/cut/lib/exportClient.ts b/site/src/cut/lib/exportClient.ts
index aac8c5d5..aea74699 100644
--- a/site/src/cut/lib/exportClient.ts
+++ b/site/src/cut/lib/exportClient.ts
@@ -1,6 +1,8 @@
"use client";
import { apiFetch, apiJson, getBackend, type CutBackend } from "./backend";
+import { engineFeatures } from "./api";
+import type { EngineFeature } from "./engineFeatures";
import {
removeBrowserExportJob,
reserveBrowserExportJob,
@@ -14,7 +16,7 @@ import { bitrateFor, renderProjectToMp4 } from "./exportRender";
import { putSigned } from "./media";
import { renderRemovalPieces } from "./removalVideo";
import { createRasterCanvas, rasterCanvasToPng } from "./raster";
-import { clipSpeed, getClipSpans, overlayLayers, projectDuration, spanSequence, useEditor } from "./store";
+import { clipLen, clipSpeed, getClipSpans, overlayLayers, projectDuration, spanSequence, useEditor } from "./store";
import { captionStyle, cueOverlay, cueWordFrames, laneCues, laneHidden, subtitleLaneCount, trackPos } from "./subtitles";
import { isMaskAnimated, isOverlayAnimated, matteLumaToAlpha, normalizeGrade, paintMaskLuma, paintStrokeInk, retimeOf, type SpeedNode } from "@donkeycut/effects-kit";
import { renderElementFrames, renderElementPng } from "./textRender";
@@ -26,6 +28,7 @@ import type {
ClipAnim,
MediaAsset,
Overlay,
+ Selection,
SubtitlesBlock,
VideoClip,
} from "./types";
@@ -33,13 +36,15 @@ import type {
import {
deliveryContainer,
EXPORT_CONTAINERS,
+ exportBaseName,
specMediaFiles,
type ExportAudioCodec,
type ExportCodec,
type ExportContainer,
+ type ExportRange,
} from "./exportDelivery";
export { EXPORT_CONTAINERS };
-export type { ExportAudioCodec, ExportCodec, ExportContainer };
+export type { ExportAudioCodec, ExportCodec, ExportContainer, ExportRange };
export interface ExportSettings {
width: number;
@@ -54,6 +59,11 @@ export interface ExportSettings {
audioCodec: ExportAudioCodec;
/** A bitrate the user typed, bits per second. Absent = the tier's model. */
bitrate?: number;
+ /** The file's name without its extension, as typed; absent = the project's
+ * name. Sanitized by `exportBaseName` wherever a file is named. */
+ name?: string;
+ /** The stretch of the timeline to render, seconds; absent = all of it. */
+ range?: ExportRange;
}
/** The delivery every render that is not the user's own export uses — hover
@@ -136,7 +146,8 @@ export type ExportQualityId = (typeof EXPORT_QUALITIES)[number]["id"];
export interface ExportChoice {
/** A `resolutionOptions` id; one the project lacks falls back to "source". */
resolution: string;
- fps: number;
+ /** A fixed rate, or "source" for the rate the footage plays at. */
+ fps: number | "source";
quality: ExportQualityId;
codec: ExportCodec;
container: ExportContainer;
@@ -155,28 +166,35 @@ export const EXPORT_QUICK_PRESETS = [
label: "Share",
detail: "1080p · plays everywhere",
short: "1080p",
- choice: { resolution: "1080", fps: 30, quality: "balanced", ...DELIVERY_DEFAULTS },
+ choice: { resolution: "1080", fps: "source", quality: "balanced", ...DELIVERY_DEFAULTS },
},
{
id: "best",
label: "Best",
detail: "source size · H.264",
short: "Source",
- choice: { resolution: "source", fps: 30, quality: "high", ...DELIVERY_DEFAULTS },
+ choice: { resolution: "source", fps: "source", quality: "high", ...DELIVERY_DEFAULTS },
+ },
+ {
+ id: "social4k",
+ label: "Social 4K",
+ detail: "4K upscale · platforms transcode it at a higher bitrate",
+ short: "4K",
+ choice: { resolution: "2160", fps: "source", quality: "high", ...DELIVERY_DEFAULTS },
},
{
id: "small",
label: "Small",
detail: "720p · fastest",
short: "720p",
- choice: { resolution: "720", fps: 30, quality: "small", ...DELIVERY_DEFAULTS },
+ choice: { resolution: "720", fps: "source", quality: "small", ...DELIVERY_DEFAULTS },
},
{
id: "master",
label: "Master",
detail: "ProRes 422 HQ · MOV · PCM",
short: "ProRes",
- choice: { resolution: "source", fps: 30, quality: "high", codec: "prores", container: "mov", audioCodec: "pcm" },
+ choice: { resolution: "source", fps: "source", quality: "high", codec: "prores", container: "mov", audioCodec: "pcm" },
},
] as const satisfies readonly { id: string; label: string; detail: string; short: string; choice: ExportChoice }[];
@@ -191,18 +209,27 @@ export function quickPresetOf(choice: ExportChoice, options: ResolutionOption[])
/** The option a resolution id names, or the source frame when the project
* has no such rung. */
export function resolveResolution(options: ResolutionOption[], id: string): ResolutionOption {
- return options.find((r) => r.id === id) ?? options[0];
+ return options.find((r) => r.id === id) ?? options.find((r) => r.id === "source") ?? options[0];
}
+/** The rate an export runs at when the footage's own is not known: a cut of
+ * stills and titles, or a source the probe could not read. */
+export const DEFAULT_EXPORT_FPS = 30;
+
/** The settings a choice adds up to, with the container fitted to the codec
- * and audio it has to carry. */
-export function choiceSettings(choice: ExportChoice, options: ResolutionOption[]): ExportSettings {
+ * and audio it has to carry. `sourceFps` is the footage's rate (see
+ * `sourceFrameRate`), what a "source" frame-rate choice resolves to. */
+export function choiceSettings(
+ choice: ExportChoice,
+ options: ResolutionOption[],
+ sourceFps: number = DEFAULT_EXPORT_FPS
+): ExportSettings {
const q = EXPORT_QUALITIES.find((x) => x.id === choice.quality) ?? EXPORT_QUALITIES[0];
const r = resolveResolution(options, choice.resolution);
return fitContainer({
width: r.width,
height: r.height,
- fps: choice.fps,
+ fps: choice.fps === "source" ? sourceFps : choice.fps,
crf: q.crf,
preset: q.preset,
codec: choice.codec,
@@ -215,21 +242,27 @@ export function choiceSettings(choice: ExportChoice, options: ResolutionOption[]
});
}
-/** A size the dialog offers: the source's own frame, or a named rung under it. */
+/** A size the dialog offers: the source's own frame, or a named rung above
+ * or below it. */
export interface ResolutionOption {
id: string;
label: string;
width: number;
height: number;
+ /** The rung is bigger than the footage: the render scales the picture up.
+ * Platforms transcode a 4K upload on a higher bitrate rung than a 1080p
+ * one, so an upscale can come back looking sharper than the source file
+ * would have. */
+ upscale?: boolean;
}
/**
* The sizes this project can be exported at, largest first.
*
- * "Source" leads and is the frame the footage justifies. The named rungs below
- * it are the ones genuinely smaller — a rung that matches or exceeds the source
- * would be the same render under a second name, or an upscale, and the dialog
- * offers neither.
+ * "Source" is the frame the footage justifies. The named rungs below it are
+ * the ones genuinely smaller; the ones above it are upscales, marked as such.
+ * A rung that matches the source would be the same render under a second
+ * name, so it is left out.
*/
export function resolutionOptions(
aspect: Aspect,
@@ -238,16 +271,56 @@ export function resolutionOptions(
): ResolutionOption[] {
const src = sourceFrame(aspect, clips, assets);
const srcShort = Math.min(src.width, src.height);
+ const rung = (r: (typeof EXPORT_RESOLUTIONS)[number]): ResolutionOption => ({
+ id: r.id,
+ label: r.label,
+ ...scaledFrame(aspect, r.shortSide),
+ ...(r.shortSide > srcShort ? { upscale: true } : {}),
+ });
return [
+ ...EXPORT_RESOLUTIONS.filter((r) => r.shortSide > srcShort).map(rung),
{ id: "source", label: "Source", ...src },
- ...EXPORT_RESOLUTIONS.filter((r) => r.shortSide < srcShort).map((r) => ({
- id: r.id,
- label: r.label,
- ...scaledFrame(aspect, r.shortSide),
- })),
+ ...EXPORT_RESOLUTIONS.filter((r) => r.shortSide < srcShort).map(rung),
];
}
+/**
+ * The stretch of the timeline the selection covers: from the first selected
+ * item's start to the last one's end, whatever rows they sit on. Null when
+ * nothing with a place in time is selected.
+ */
+export function selectionRange(s: {
+ multiSelection: Selection[];
+ clips: VideoClip[];
+ audioClips: AudioClip[];
+ overlays: Overlay[];
+ subtitles: SubtitlesBlock;
+}): ExportRange | null {
+ let start = Infinity;
+ let end = -Infinity;
+ const take = (a: number, b: number) => {
+ start = Math.min(start, a);
+ end = Math.max(end, b);
+ };
+ for (const sel of s.multiSelection) {
+ if (!sel) continue;
+ if (sel.kind === "clip") {
+ const c = s.clips.find((x) => x.id === sel.id);
+ if (c) take(c.start, c.start + clipLen(c));
+ } else if (sel.kind === "audio") {
+ const a = s.audioClips.find((x) => x.id === sel.id);
+ if (a) take(a.start, a.start + clipLen(a));
+ } else if (sel.kind === "overlay") {
+ const o = s.overlays.find((x) => x.id === sel.id);
+ if (o) take(o.start, o.end);
+ } else if (sel.kind === "cue") {
+ const c = s.subtitles.cues.find((x) => x.id === sel.id);
+ if (c) take(c.start, c.end);
+ }
+ }
+ return end > start ? { start, end } : null;
+}
+
/** Frame dims for an aspect scaled to a short-side target, even-rounded. */
function scaledFrame(aspect: Aspect, shortSide: number): { width: number; height: number } {
const f = frameOf(aspect);
@@ -638,7 +711,15 @@ async function renderClipShadowPictures(
shapeCtx.roundRect(box.x, box.y, box.w, box.h, radius);
shapeCtx.clip();
if (sil) {
+ // The silhouette mirrors with the picture it was cut from.
+ shapeCtx.save();
+ if (clip.flipH || clip.flipV) {
+ shapeCtx.translate(box.x + box.w / 2, box.y + box.h / 2);
+ shapeCtx.scale(clip.flipH ? -1 : 1, clip.flipV ? -1 : 1);
+ shapeCtx.translate(-(box.x + box.w / 2), -(box.y + box.h / 2));
+ }
shapeCtx.drawImage(sil, pic.x, pic.y, pic.w, pic.h);
+ shapeCtx.restore();
} else {
shapeCtx.fillStyle = "#ffffff";
shapeCtx.fillRect(pic.x, pic.y, pic.w, pic.h);
@@ -801,6 +882,8 @@ export async function buildExportPayload(
zoom: clipZoom(sp.clip),
panX: sp.clip.panX ?? 0,
panY: sp.clip.panY ?? 0,
+ flipH: sp.clip.flipH,
+ flipV: sp.clip.flipV,
frame: sp.clip.frame,
speed: clipSpeed(sp.clip),
speedCurve: sp.clip.speedCurve,
@@ -1005,6 +1088,8 @@ export async function buildExportPayload(
zoom: clipZoom(c),
panX: c.panX ?? 0,
panY: c.panY ?? 0,
+ flipH: c.flipH,
+ flipV: c.flipV,
muted: c.muted,
volume: c.volume,
sound: c.sound,
@@ -1352,12 +1437,10 @@ async function postExport(
});
}
-/** The cloud names the output client-side (the engine derives it from the
- * project name itself, deduping on disk); mirror the engine's sanitize rule. */
+/** The output's file name: what the user typed, or the project's name, under
+ * the one sanitize rule every residency shares (the engine dedupes on disk). */
function exportOutName(settings: ExportSettings): string {
- const base =
- useEditor.getState().projectName.replace(/[/\\:*?"<>|]/g, "").trim().slice(0, 60) || "export";
- return `${base}${exportExtension(settings)}`;
+ return `${exportBaseName(settings.name ?? useEditor.getState().projectName)}${exportExtension(settings)}`;
}
/** Poll an export job to completion, reporting progress. Returns the file name. */
@@ -1392,6 +1475,24 @@ export function downloadExport(jobId: string, outName: string, backend: CutBacke
a.remove();
}
+/** The engine on this Mac ships inside the app, so it can be older than the
+ * page. An older build parses the spec by shape and drops the fields it does
+ * not know — a range export would come back as the whole cut, a typed name
+ * as the project's — so what the settings ask of the engine is checked
+ * against what it says it carries, and the export refuses with the fix. */
+async function assertEngineCarries(settings: ExportSettings): Promise<void> {
+ const wants: [EngineFeature, boolean, string][] = [
+ ["export.range", !!settings.range, "export a range"],
+ ["export.name", !!settings.name, "name the file"],
+ ];
+ const has = await engineFeatures();
+ for (const [feature, wanted, what] of wants) {
+ if (wanted && !has.has(feature)) {
+ throw new ExportRefusedError(`Update the Donkey app to ${what}.`);
+ }
+ }
+}
+
/** Build the cut and hand it to the engine, returning the new job id. Progress,
* cancel, download, and the finished-file actions are all driven from the
* engine's job feed by the exports dock — this only kicks the render off, so it
@@ -1402,6 +1503,7 @@ export async function createExportJob(
settings: ExportSettings
): Promise<string> {
const backend = getBackend(); // pinned: the payload build takes a while
+ if (backend.kind === "local") await assertEngineCarries(settings);
const payload = await buildExportPayload(projectId, doc, settings, "export");
const res = await postExport(projectId, payload, exportOutName(settings), backend);
const body = await apiJson<{ id?: string }>(res);
@@ -1529,10 +1631,11 @@ async function runEngineExport(
opts: NonNullable<Parameters<typeof runBrowserExport>[3]>,
backend: CutBackend
): Promise<string> {
+ await assertEngineCarries(settings);
const claim = await backend.fetch("/api/cut/export/client", {
method: "POST",
headers: { "Content-Type": "application/json" },
- body: JSON.stringify({ projectId, container: settings.container }),
+ body: JSON.stringify({ projectId, container: settings.container, name: settings.name }),
});
const claimed = await apiJson<{ id?: string; outName?: string }>(claim);
if (!claim.ok || !claimed.id) throw new Error(claimed.error ?? "Export failed to start.");
diff --git a/site/src/cut/lib/exportDelivery.ts b/site/src/cut/lib/exportDelivery.ts
index 1fb2c5b9..f15ebf0b 100644
--- a/site/src/cut/lib/exportDelivery.ts
+++ b/site/src/cut/lib/exportDelivery.ts
@@ -20,6 +20,39 @@ export const EXPORT_CONTAINERS: readonly DeliveryContainer[] = [
{ id: "mov", label: "MOV", ext: ".mov", mime: "video/quicktime" },
];
+/** A window of the timeline to deliver, seconds; absent = the whole cut. */
+export interface ExportRange {
+ start: number;
+ end: number;
+}
+
+/** How long a delivery runs: the range's span, or the whole cut. */
+export function deliverySpan(range: ExportRange | undefined, duration: number): number {
+ if (!range) return duration;
+ const start = Math.max(0, range.start);
+ const end = Math.min(duration, range.end);
+ return Math.max(0, end - start);
+}
+
+/** Seconds between key frames in a delivered file. Two is what the platforms
+ * ask for: seeks land within two seconds, and the encoder keeps most of its
+ * bits for the frames between. */
+export const KEYFRAME_INTERVAL_S = 2;
+
+/** The base of a delivered file's name, from what the user typed or the
+ * project is called: a container suffix dropped, path and shell characters
+ * stripped, trimmed, cut to sixty characters, with "export" standing in for
+ * nothing at all. The one rule every residency names its file by. */
+export function exportBaseName(raw: string): string {
+ return (
+ raw
+ .replace(/\.(mp4|mov)$/i, "")
+ .replace(/[/\\:*?"<>|]/g, "")
+ .trim()
+ .slice(0, 60) || "export"
+ );
+}
+
export function deliveryContainer(id: ExportContainer | undefined): DeliveryContainer {
return EXPORT_CONTAINERS.find((c) => c.id === id) ?? EXPORT_CONTAINERS[0];
}
diff --git a/site/src/cut/lib/exportRender.ts b/site/src/cut/lib/exportRender.ts
index 6ff74f39..0f8fc939 100644
--- a/site/src/cut/lib/exportRender.ts
+++ b/site/src/cut/lib/exportRender.ts
@@ -47,7 +47,7 @@ import { renderElementPng } from "./textRender";
import { assetIsSilent, behindSubjectOverlay, clipCovers, frameOf, frontSubjectOverlay, isEffectOverlay, isTextOverlay, laneOf, overlayAnimStyle, projectBackground, projectFadeSeconds, rectOf, removalActive } from "./types";
import type { ClipAnim, ClipSpan, EffectOverlay, MediaAsset, Overlay, StickerOverlay } from "./types";
import type { ExportDoc, ExportSettings } from "./exportClient";
-import { videoBitrateFor } from "./exportDelivery";
+import { deliverySpan, KEYFRAME_INTERVAL_S, videoBitrateFor } from "./exportDelivery";
/** Audio is written at the rate and width a delivery file wants, rather than
* the 16 kHz mono a speech model reads. */
@@ -143,6 +143,103 @@ export function bitrateFor(settings: ExportSettings): number {
return videoBitrateFor(settings);
}
+/** The stretch `[from, to]` of a rendered mix as a buffer of its own. */
+function sliceAudio(mix: AudioBuffer, from: number, to: number): AudioBuffer {
+ const a = Math.max(0, Math.min(mix.length, Math.round(from * mix.sampleRate)));
+ const b = Math.max(a + 1, Math.min(mix.length, Math.round(to * mix.sampleRate)));
+ const out = new AudioBuffer({
+ length: b - a,
+ numberOfChannels: mix.numberOfChannels,
+ sampleRate: mix.sampleRate,
+ });
+ for (let ch = 0; ch < mix.numberOfChannels; ch++) {
+ out.copyToChannel(mix.getChannelData(ch).subarray(a, b), ch);
+ }
+ return out;
+}
+
+/** The frame rates a delivered file is written at. A source's measured rate
+ * snaps to the nearest: 23.976 reads as 24, 29.97 as 30, 59.94 as 60. */
+const DELIVERY_RATES = [24, 25, 30, 48, 50, 60];
+
+/** Sources the probe reads for a rate: the ones with the most time on the
+ * timeline, so a cut of many files still answers quickly. */
+const RATE_PROBE_SOURCES = 6;
+
+/** How long the probe waits on a source before giving up on it. */
+const RATE_PROBE_TIMEOUT_MS = 8_000;
+
+/** The sources a rate probe would read, by footprint: the key a caller
+ * re-probes on, so a change elsewhere in the project leaves the answer. */
+export function sourceFrameRateKey(doc: Pick<ExportDoc, "clips" | "assets">): string {
+ return rateSources(doc)
+ .map(([id]) => id)
+ .join("|");
+}
+
+function rateSources(doc: Pick<ExportDoc, "clips" | "assets">): [string, number][] {
+ const byId = new Map(doc.assets.map((a) => [a.id, a]));
+ const footprint = new Map<string, number>();
+ for (const c of doc.clips) {
+ const asset = byId.get(c.assetId);
+ if (!asset || asset.type !== "video" || c.hidden) continue;
+ footprint.set(asset.id, (footprint.get(asset.id) ?? 0) + retimeOf(c).len);
+ }
+ return [...footprint.entries()]
+ .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
+ .slice(0, RATE_PROBE_SOURCES);
+}
+
+/**
+ * The rate the footage plays at: the delivery rate the most timeline seconds
+ * of video run at, read from each source's packet cadence. Null for a cut
+ * with no readable video — stills, titles, sound — which takes the default.
+ * An aborted probe closes its readers and answers null.
+ */
+export async function sourceFrameRate(
+ doc: Pick<ExportDoc, "clips" | "assets">,
+ resolve: (asset: MediaAsset) => string,
+ opts: { signal?: AbortSignal } = {}
+): Promise<number | null> {
+ const byId = new Map(doc.assets.map((a) => [a.id, a]));
+ const seconds = new Map<number, number>();
+ await Promise.all(
+ rateSources(doc).map(async ([id, len]) => {
+ if (opts.signal?.aborted) return;
+ const asset = byId.get(id)!;
+ const input = openMedia(resolve(asset));
+ // A cancel or the deadline closes the reader, which fails whatever it
+ // is waiting on; either way this source casts no vote.
+ const close = () => input.dispose();
+ const deadline = setTimeout(close, RATE_PROBE_TIMEOUT_MS);
+ opts.signal?.addEventListener("abort", close, { once: true });
+ try {
+ const track = await videoTrackOf(input);
+ if (!track) return;
+ const stats = await track.computePacketStats(120);
+ const rate = stats.averagePacketRate;
+ if (!(rate > 0) || opts.signal?.aborted) return;
+ const snapped = DELIVERY_RATES.reduce((best, r) =>
+ Math.abs(r - rate) < Math.abs(best - rate) ? r : best
+ );
+ seconds.set(snapped, (seconds.get(snapped) ?? 0) + len);
+ } catch {
+ // A source the probe cannot read casts no vote.
+ } finally {
+ clearTimeout(deadline);
+ opts.signal?.removeEventListener("abort", close);
+ close();
+ }
+ })
+ );
+ if (opts.signal?.aborted) return null;
+ let pick: number | null = null;
+ for (const [rate, len] of seconds) {
+ if (pick === null || len > seconds.get(pick)! || (len === seconds.get(pick) && rate > pick)) pick = rate;
+ }
+ return pick;
+}
+
/** The frame reader for one open video source. */
type ClipSink = ReturnType<typeof frameSink>;
@@ -829,6 +926,12 @@ export async function renderProjectToMp4(
const { resolve, onProgress, signal } = opts;
const duration = projectDuration(doc);
if (!(duration > 0)) throw new Error("There is nothing to export yet.");
+ // The window of the timeline the file carries: a range when the settings
+ // name one, the whole cut otherwise. Frames are drawn at timeline time and
+ // written at file time, so the file starts at zero.
+ const from = Math.max(0, settings.range?.start ?? 0);
+ const span = deliverySpan(settings.range, duration);
+ if (!(span > 0)) throw new Error("The export range is empty.");
const wanted = deliveryVideoCodec(settings);
if (!wanted) throw new Error("This browser can't encode ProRes.");
@@ -847,18 +950,19 @@ export async function renderProjectToMp4(
};
onProgress?.({ ratio: 0, stage: "audio" });
- const mix = await renderMix(mixSpecFor(doc, resolve), {
+ const whole = await renderMix(mixSpecFor(doc, resolve), {
sampleRate: AUDIO_RATE,
channels: AUDIO_CHANNELS,
resolve: (file) => file, // mixSpecFor already resolved each asset to a URL
});
+ const mix = whole && settings.range ? sliceAudio(whole, from, from + span) : whole;
stop();
const canvas = createRasterCanvas(settings.width, settings.height);
const painter = new FramePainter(doc, canvas, resolve);
const frameDur = 1 / settings.fps;
- const frames = Math.max(1, Math.round(duration * settings.fps));
+ const frames = Math.max(1, Math.round(span * settings.fps));
const dir = await scratchDir();
void sweepScratch(dir);
@@ -884,6 +988,7 @@ export async function renderProjectToMp4(
const video = new CanvasSource(canvas, {
codec,
quality: new Quality({ bitrate: bitrateFor(settings) }),
+ keyFrameInterval: KEYFRAME_INTERVAL_S,
});
// Reserving the index space needs a packet ceiling per track. The video's
// is exact — one packet per frame; the audio's is the mix's sample count
@@ -919,7 +1024,7 @@ export async function renderProjectToMp4(
for (let i = 0; i < frames; i++) {
stop();
const t = i * frameDur;
- await painter.drawAt(t);
+ await painter.drawAt(from + t);
await video.add(t, frameDur);
if (i % 15 === 0) {
@@ -1413,7 +1518,7 @@ export async function canRenderInBrowser(
settings: ExportSettings
): Promise<boolean> {
const duration = projectDuration(doc);
- if (!(duration > 0)) return false;
+ if (!(deliverySpan(settings.range, duration) > 0)) return false;
if (
typeof navigator.storage?.getDirectory !== "function" ||
typeof FileSystemFileHandle === "undefined" ||
diff --git a/site/src/cut/server/ai/catalog.ts b/site/src/cut/server/ai/catalog.ts
index 0172d1ca..0e4ab6b2 100644
--- a/site/src/cut/server/ai/catalog.ts
+++ b/site/src/cut/server/ai/catalog.ts
@@ -110,9 +110,9 @@ Times are in seconds on the shared timeline. The playhead is currentTime; a skim
- 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. A transition bar hides the same way (set_transition_hidden): it keeps the cut it sits on so nothing else claims that boundary, and the cut renders hard. Whole rows: set_track_hidden (video/soundtrack/text/subtitles/transitions) 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. \`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; in the preview a grey outline shows the part being cropped away, and the user drags that outline to slide the crop (dragging the clip itself moves its box). 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.
+- 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; in the preview a grey outline shows the part being cropped away, and the user drags that outline to slide the crop (dragging the clip itself moves its box). flipH mirrors the picture left for right and flipV top for bottom — a front-camera take that reads backward (mirrored text, a watch on the wrong wrist) wants flipH. The controls live in the Inspector under "Framing" when a video clip is selected, the mirror beside Rotation. Landscape footage usually wants fill + a pan that keeps the subject.
+- update_overlay_video also carries an overlay clip's resting transform: rotation, opacity and the mirror, 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_overlay_video region or the preview handles), mask it with kind circle, and give it a soft shadow.
- The user can copy/paste any selected segment (video, overlay video, audio, title) with ⌘C/⌘V; pastes aim for the playhead and slide right to free space.
- Zoom: set_view pxPerSec (12..800) or fit. The timeline panel height: set_view timelineH (170..600).`,
@@ -402,7 +402,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 (source size, H.264 MP4, high quality), Small (720p, fastest), Master (source size, ProRes 422 HQ in a MOV with PCM audio, for handing to another editor) — and an Advanced panel with every axis: format (MP4 or MOV), codec (H.264, HEVC at about half the size for newer devices, ProRes 422 HQ), resolution (Source, which matches the sharpest clip on the timeline along the project aspect with a 1080p floor and a 4K cap, then every named rung below it: 4K, 1440p, 1080p, 720p), frame rate (24, 30 or 60), quality (High, Balanced, Small, or a typed bitrate in Mbps), audio (AAC or uncompressed PCM). ProRes and PCM take a MOV. The dialog shows the size the choice will land at. Every export renders at the project aspect ratio, 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 (source size, H.264 MP4, high quality), 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 422 HQ in a MOV with PCM audio, for handing to another editor) — 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), resolution (Source, which matches the sharpest clip on the timeline along the project aspect with a 1080p floor and a 4K cap; the named rungs below it; and the named rungs above it as marked upscales: 4K, 1440p, 1080p, 720p), 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), 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. Every preset runs at the source frame rate. The dialog shows the size the choice will land at. H.264 files carry the High profile and HEVC files the Main profile; both key every two seconds, what the platforms ask for. An engine from an older Donkey app cannot take a range or a typed name, and the export says to update the app. Every export renders at the project aspect ratio, 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. */
diff --git a/site/src/cut/server/cloud/jobs.ts b/site/src/cut/server/cloud/jobs.ts
index 1b74376f..9908b6de 100644
--- a/site/src/cut/server/cloud/jobs.ts
+++ b/site/src/cut/server/cloud/jobs.ts
@@ -9,7 +9,7 @@ import { getProject } from "./projects";
import { MEDIA_REDIRECT_HEADERS, mediaObjectUrl } from "./mediaCdn";
import { del, head, overlayKey, overlayPrefix, presignPut, projectExportKey } from "./r2";
import { contentTypeFor } from "../serveFile";
-import { containerOfName, deliveryContainer, specMediaFiles, type ExportContainer } from "../../lib/exportDelivery";
+import { containerOfName, deliveryContainer, exportBaseName, specMediaFiles, type ExportContainer } from "../../lib/exportDelivery";
import { addUsage, quotaCheck, reservedBytes, usageBytes } from "./usage";
import { caught, err, redirect } from "./util";
@@ -161,8 +161,7 @@ async function exportName(
// `containerExtension` does; a name alone (a tab's own claim) says it by its
// suffix.
const { ext } = container ? deliveryContainer(container) : containerOfName(baseName);
- const base =
- baseName.replace(/\.(mp4|mov)$/i, "").replace(/[/\\:*?"<>|]/g, "").trim().slice(0, 60) || "export";
+ const base = exportBaseName(baseName);
const [files, jobs] = await Promise.all([
tx.cutMediaObject.findMany({
where: { userId, projectId, kind: "export" },
diff --git a/site/src/cut/server/exportPipeline.test.ts b/site/src/cut/server/exportPipeline.test.ts
index 969d4488..6c7f043b 100644
--- a/site/src/cut/server/exportPipeline.test.ts
+++ b/site/src/cut/server/exportPipeline.test.ts
@@ -1,6 +1,7 @@
import { describe, expect, test } from "bun:test";
import { retimeOf } from "@donkeycut/effects-kit";
import {
+ narrowSpecToRange,
runExport,
type ExportPipelineIO,
type ExportSpec,
@@ -680,6 +681,13 @@ describe("the project background in the filtergraph", () => {
expect(g.join(";")).toContain("crop='min(iw,1080)':'min(ih,1920)'");
});
+ test("a mirrored clip flips after its framing, inside its box", async () => {
+ const g = await graphFor({ clips: [clip("a.mp4", { fit: "fill", flipH: true })] });
+ expect(g.join(";")).toContain(":(ih-oh)*0.500,hflip,setsar=1");
+ const v = await graphFor({ clips: [clip("a.mp4", { flipV: true })] });
+ expect(v.join(";")).toContain(",vflip,pad=");
+ });
+
test("no background named keeps the black frame every cut had before", async () => {
const g = await graphFor({ clips: [clip("", { out: 4, hidden: true, muted: true })] });
expect(g.join(";")).toContain("color=c=black:");
@@ -860,6 +868,78 @@ describe("delivery", () => {
expect(arg(args, "-b:v")).toBe("6000000");
expect(arg(args, "-maxrate")).toBe("9000000");
});
+
+ test("H.264 and HEVC write the High profile with a key frame every two seconds", async () => {
+ const h264 = await encodeRun({ fps: 30 });
+ expect(arg(h264, "-profile:v")).toBe("high");
+ expect(arg(h264, "-g")).toBe("60");
+ const hevc = await encodeRun({ codec: "hevc", fps: 24 });
+ expect(arg(hevc, "-g")).toBe("48");
+ const prores = await encodeRun({ codec: "prores", container: "mov" });
+ expect(prores).not.toContain("-g");
+ });
+
+ test("a range is cut from the finished composite and sets the file's length", async () => {
+ const args = await encodeRun({ duration: 20, range: { start: 5, end: 12 } });
+ const graph = arg(args, "-filter_complex");
+ expect(graph).toContain("trim=start=5.000:end=12.000,setpts=PTS-STARTPTS[vrange]");
+ expect(graph).toContain("atrim=start=5.000:end=12.000,asetpts=PTS-STARTPTS[arange]");
+ expect(arg(args, "-map")).toBe("[vrange]");
+ expect(arg(args, "-t")).toBe("7.000");
+ });
+
+ test("a range hides the track-0 slots it cannot reach and drops the entries outside it", async () => {
+ const spec = {
+ projectId: "p", width: 1080, height: 1920, fps: 30, crf: 24, preset: "veryfast",
+ duration: 30,
+ range: { start: 12, end: 18 },
+ clips: ["a", "b", "c", "d", "e", "f"].map((n) => clip(`${n}.mp4`, { out: 5 })),
+ audio: [
+ { file: "m1.mp3", in: 0, out: 4, start: 0, volume: 1 },
+ { file: "m2.mp3", in: 0, out: 4, start: 15, volume: 1 },
+ ],
+ overlays: [
+ { file: "t1.png", start: 0, end: 3 },
+ { file: "t2.png", start: 17, end: 25 },
+ ],
+ captions: [
+ { file: "c1.png", start: 1, end: 2 },
+ { file: "c2.png", start: 13, end: 14 },
+ ],
+ } as unknown as ExportSpec;
+ const narrowed = narrowSpecToRange(spec);
+ // Five-second slots: [0,5) [5,10) [10,15) [15,20) [20,25) [25,30). The
+ // half-second slack keeps the slot ending at 10 hidden and the one
+ // starting at 20 hidden.
+ expect(narrowed.clips.map((c) => !!c.hidden)).toEqual([true, true, false, false, true, true]);
+ expect(narrowed.audio.map((a) => a.file)).toEqual(["m2.mp3"]);
+ expect(narrowed.overlays.map((o) => o.file)).toEqual(["t2.png"]);
+ expect(narrowed.captions?.map((c) => c.file)).toEqual(["c2.png"]);
+ expect(narrowed.duration).toBe(30);
+ const whole = { ...spec, range: undefined };
+ expect(narrowSpecToRange(whole)).toBe(whole);
+ });
+
+ test("a join at the range edge keeps its neighbor", async () => {
+ const spec = {
+ projectId: "p", width: 1080, height: 1920, fps: 30, crf: 24, preset: "veryfast",
+ duration: 15,
+ range: { start: 6, end: 8 },
+ clips: [clip("a.mp4", { out: 5, transition: 1 }), clip("b.mp4", { out: 5 }), clip("c.mp4", { out: 5 })],
+ audio: [],
+ overlays: [],
+ } as unknown as ExportSpec;
+ // Slots [0,5) [5,10) [10,15): a one-second join reaches 1.5 s past each
+ // edge, so the first slot (ending at 5, within 1.5 of 6) stays and the
+ // last (starting at 10, beyond 1.5 of 8) is hidden.
+ expect(narrowSpecToRange(spec).clips.map((c) => !!c.hidden)).toEqual([false, false, true]);
+ });
+
+ test("no range delivers the whole cut", async () => {
+ const args = await encodeRun({ duration: 20 });
+ expect(arg(args, "-filter_complex")).not.toContain("[vrange]");
+ expect(arg(args, "-t")).toBe("20.000");
+ });
});
describe("channel layout", () => {
diff --git a/site/src/cut/server/exportPipeline.ts b/site/src/cut/server/exportPipeline.ts
index 5e869fd0..4d2c0a4d 100644
--- a/site/src/cut/server/exportPipeline.ts
+++ b/site/src/cut/server/exportPipeline.ts
@@ -1,5 +1,5 @@
import { spawn, type ChildProcess } from "node:child_process";
-import { deliveryContainer, videoBitrateFor } from "../lib/exportDelivery";
+import { deliveryContainer, deliverySpan, KEYFRAME_INTERVAL_S, videoBitrateFor, type ExportRange } from "../lib/exportDelivery";
import { readFile, stat, unlink, writeFile } from "node:fs/promises";
import path from "node:path";
import { atempoChain, audioChannels, hasStream, mediaDuration, num, videoColorInfo, videoDecodeCost } from "./util";
@@ -69,6 +69,13 @@ export interface ExportSpec {
audioCodec?: "aac" | "pcm";
/** A bitrate the user typed, bits per second; absent = the `crf` tier. */
bitrate?: number;
+ /** The file's name without its extension, as typed; absent = the project's
+ * name. */
+ name?: string;
+ /** The stretch of the timeline to deliver, seconds; absent = all of it. The
+ * graph composites the whole cut and the delivery is cut from it, so fades,
+ * captions and elements sit where the timeline has them. */
+ range?: ExportRange;
duration: number;
/** Whole-video fades, seconds: in from black / out to black, applied to the
* final composite and mix after all overlays and soundtrack. */
@@ -94,6 +101,9 @@ export interface ExportSpec {
zoom?: number;
panX?: number; // crop-window pan -1..1, across whatever overflows
panY?: number;
+ /** Mirror the framed picture left for right / top for bottom. */
+ flipH?: boolean;
+ flipV?: boolean;
/** Region of the frame this clip fills; absent = full frame. */
frame?: { x: number; y: number; w: number; h: number };
speed?: number; // playback rate, default 1
@@ -185,6 +195,9 @@ export interface ExportSpec {
zoom?: number;
panX?: number; // crop-window pan -1..1, across whatever overflows
panY?: number;
+ /** Mirror the framed picture left for right / top for bottom. */
+ flipH?: boolean;
+ flipV?: boolean;
muted: boolean;
/** Gain on the clip's own audio, 0..3; absent = 1 (unchanged). */
volume?: number;
@@ -403,16 +416,19 @@ export function videoCodecArgs(enc: string, spec: ExportSpec): string[] {
const codec = spec.codec ?? "h264";
const bitrate = videoBitrateFor({ ...spec, codec });
const rate = ["-b:v", String(bitrate), "-maxrate", String(Math.round(bitrate * 1.5)), "-bufsize", String(bitrate * 3)];
+ // A key frame every two seconds, the cadence the platforms ask for and the
+ // one the tab's encoder writes.
+ const gop = ["-g", String(Math.max(1, Math.round(spec.fps * KEYFRAME_INTERVAL_S)))];
switch (enc) {
case "libx264":
- return ["-c:v", "libx264", "-preset", spec.preset, ...(spec.bitrate ? rate : ["-crf", String(spec.crf)]), "-profile:v", "high", "-pix_fmt", "yuv420p"];
+ return ["-c:v", "libx264", "-preset", spec.preset, ...(spec.bitrate ? rate : ["-crf", String(spec.crf)]), ...gop, "-profile:v", "high", "-pix_fmt", "yuv420p"];
case "h264_videotoolbox":
- return ["-c:v", "h264_videotoolbox", ...rate, "-profile:v", "high", "-pix_fmt", "yuv420p", "-allow_sw", "1"];
+ return ["-c:v", "h264_videotoolbox", ...rate, ...gop, "-profile:v", "high", "-pix_fmt", "yuv420p", "-allow_sw", "1"];
case "libx265":
// x265's CRF scale sits about four points above x264's for the same picture.
- return ["-c:v", "libx265", "-preset", spec.preset, ...(spec.bitrate ? rate : ["-crf", String(spec.crf + 4)]), "-x265-params", "log-level=error", "-tag:v", "hvc1", "-pix_fmt", "yuv420p"];
+ return ["-c:v", "libx265", "-preset", spec.preset, ...(spec.bitrate ? rate : ["-crf", String(spec.crf + 4)]), ...gop, "-x265-params", "log-level=error", "-tag:v", "hvc1", "-pix_fmt", "yuv420p"];
case "hevc_videotoolbox":
- return ["-c:v", "hevc_videotoolbox", ...rate, "-profile:v", "main", "-tag:v", "hvc1", "-pix_fmt", "yuv420p", "-allow_sw", "1"];
+ return ["-c:v", "hevc_videotoolbox", ...rate, ...gop, "-profile:v", "main", "-tag:v", "hvc1", "-pix_fmt", "yuv420p", "-allow_sw", "1"];
case "prores_ks":
return ["-c:v", "prores_ks", "-profile:v", "3", "-vendor", "apl0", "-pix_fmt", "yuv422p10le"];
default:
@@ -544,6 +560,53 @@ function framedTimebase(
const spanLen = (c: { in: number; out: number; speed?: number; speedCurve?: SpeedNode[]; reverse?: boolean }) =>
Math.max(0.1, retimeOf(c).len);
+/** Seconds a range keeps on either side of itself beyond what a join or a
+ * sound handle reaches, so a boundary never lands on a frame the neighbor
+ * still shapes. */
+const RANGE_SLACK_S = 0.5;
+
+/**
+ * The spec with everything that cannot reach the range taken out of the
+ * graph's way: a track-0 clip whose slot ends before the range or starts
+ * after it is hidden — the slot keeps its length as a bare frame, so nothing
+ * shifts, and its file is never decoded, scaled, or graded — and the entries
+ * placed at absolute times (layers, sound, elements, captions, effects) are
+ * dropped when they lie wholly outside. A clip is kept while any join or
+ * sound handle it takes part in can still reach the range. A spec with no
+ * range is returned as it is.
+ */
+export function narrowSpecToRange(spec: ExportSpec): ExportSpec {
+ if (!spec.range) return spec;
+ const reach =
+ Math.max(
+ 0,
+ ...spec.clips.map((c) =>
+ Math.max(c.transition ?? 0, c.soundCross ?? 0, c.soundAhead ?? 0, c.soundBack ?? 0)
+ )
+ ) + RANGE_SLACK_S;
+ const from = Math.max(0, spec.range.start) - reach;
+ const to = Math.min(spec.duration, spec.range.end) + reach;
+ const inside = (start: number, end: number) => end >= from && start <= to;
+ let cursor = 0;
+ const clips = spec.clips.map((c) => {
+ const start = cursor;
+ const end = cursor + spanLen(c);
+ cursor = end;
+ return c.hidden || inside(start, end) ? c : { ...c, hidden: true };
+ });
+ return {
+ ...spec,
+ clips,
+ ...(spec.overlayVideos
+ ? { overlayVideos: spec.overlayVideos.filter((o) => inside(o.start, o.start + spanLen(o))) }
+ : {}),
+ audio: spec.audio.filter((a) => inside(a.start, a.start + spanLen(a))),
+ overlays: spec.overlays.filter((o) => inside(o.start, o.end)),
+ ...(spec.captions ? { captions: spec.captions.filter((c) => inside(c.start, c.end)) } : {}),
+ ...(spec.effects ? { effects: spec.effects.filter((e) => inside(e.start, e.end)) } : {}),
+ };
+}
+
/** A clip's frame region in even pixels, or null when it fills the whole frame
* (the common case, which keeps the plain full-frame filter path). */
@@ -640,11 +703,12 @@ const realIO: ExportPipelineIO = {
* `job.tmpDir` by base name in both. */
export async function runExport(
job: RenderHandle,
- spec: ExportSpec,
+ given: ExportSpec,
mediaPathFor: (file: string) => string,
io: ExportPipelineIO = realIO
) {
- if (spec.clips.length === 0) throw new Error("Nothing to export.");
+ if (given.clips.length === 0) throw new Error("Nothing to export.");
+ let spec = narrowSpecToRange(given);
const { width: W, height: H, fps } = spec;
// A clip that plays backward is rendered off a turned copy of its span,
@@ -664,6 +728,7 @@ export async function runExport(
soundBack?: number;
soundAhead?: number;
image?: boolean;
+ hidden?: boolean;
},
>(
c: T,
@@ -673,7 +738,7 @@ export async function runExport(
* frame by frame for nothing. */
soundOnly = false
): Promise<T> => {
- if (!c.reverse || !c.file || c.image) return c;
+ if (!c.reverse || !c.file || c.image || c.hidden) return c;
const src = await resolveMedia(io.stat, mediaPathFor, c.file);
const rt = retimeOf(c);
// The span plus the handles a crossing reaches into, so the copy holds
@@ -749,6 +814,10 @@ export async function runExport(
const ky = num(0.5 + Math.max(-1, Math.min(1, panY ?? 0)) / 2);
return `${scale},crop=${fexpr(`min(iw,${bw})`)}:${fexpr(`min(ih,${bh})`)}:(iw-ow)*${kx}:(ih-oh)*${ky}`;
};
+ /** The mirror after the framing: the picture flips inside its box, the
+ * way the canvas turns it about the box center. */
+ const mirror = (c: { flipH?: boolean; flipV?: boolean }): string =>
+ (c.flipH ? ",hflip" : "") + (c.flipV ? ",vflip" : "");
// One ffmpeg input per distinct media file (from the project folder),
// plus one per uploaded overlay PNG.
// Still images are excluded here: a plain `-i file` decodes one frame, so
@@ -1493,12 +1562,13 @@ export async function runExport(
// The framed picture lands centered in its rect: a covering one fills
// the rect exactly, a fitted one keeps its margins.
frame =
- `${boxFraming(rw, rh, c.fit === "fill", c.zoom, c.panX, c.panY)},` +
+ `${boxFraming(rw, rh, c.fit === "fill", c.zoom, c.panX, c.panY)}${mirror(c)},` +
`pad=${bw}:${bh}:${rx - bx}+(${rw}-iw)/2:${ry - by}+(${rh}-ih)/2:color=${segPad}${win}`;
} else {
const cover = c.fit === "fill";
frame =
boxFraming(W, H, cover, c.zoom, c.panX, c.panY) +
+ mirror(c) +
// A covering picture already spans the frame; a fitted one letterboxes.
(cover ? "" : `,pad=${W}:${H}:(ow-iw)/2:(oh-ih)/2:color=${segPad}`);
}
@@ -1864,7 +1934,7 @@ export async function runExport(
const boxH = region ? region.rh : H;
// The overlay's picture meets its box the same way a track-0 clip meets
// the frame; whatever the box does not swallow sits centered in it.
- const framing = boxFraming(boxW, boxH, cover, oc.zoom, oc.panX, oc.panY);
+ const framing = boxFraming(boxW, boxH, cover, oc.zoom, oc.panX, oc.panY) + mirror(oc);
let pos: string;
if (!region) {
pos = cover ? "0:0" : `x=(${W}-w)/2:y=(${H}-h)/2`;
@@ -2303,6 +2373,18 @@ export async function runExport(
aLabel = "afinal";
}
+ // A range is cut from the finished composite, so it carries what the
+ // timeline shows there — fades, captions, and elements in place.
+ const span = deliverySpan(spec.range, spec.duration);
+ if (spec.range) {
+ const from = num(Math.max(0, spec.range.start));
+ const to = num(Math.min(spec.duration, spec.range.end));
+ filters.push(`[${vLabel}]trim=start=${from}:end=${to},setpts=PTS-STARTPTS[vrange]`);
+ vLabel = "vrange";
+ filters.push(`[${aLabel}]atrim=start=${from}:end=${to},asetpts=PTS-STARTPTS[arange]`);
+ aLabel = "arange";
+ }
+
const enc = await io.videoEncoder(spec.codec ?? "h264");
// Encode into the tmp dir, then re-emit the container to strip a stray output
@@ -2323,10 +2405,10 @@ export async function runExport(
"-color_primaries", "bt709",
"-color_trc", "bt709",
...audioCodecArgs(spec),
- "-t", num(spec.duration),
+ "-t", num(span),
encodePath,
],
- (t) => (job.progress = Math.min(0.99, t / Math.max(0.1, spec.duration)))
+ (t) => (job.progress = Math.min(0.99, t / Math.max(0.1, span)))
);
// ffmpeg's autorotation already baked each source's display matrix into the
diff --git a/site/src/cut/server/http/export.ts b/site/src/cut/server/http/export.ts
index 7414fd17..00f7b938 100644
--- a/site/src/cut/server/http/export.ts
+++ b/site/src/cut/server/http/export.ts
@@ -39,9 +39,13 @@ export const exportApi = {
* file's name; the tab draws the frames and hands the file in below. */
async createClient(req: Request) {
try {
- const body = (await req.json()) as { projectId?: string; container?: ExportSpec["container"] };
+ const body = (await req.json()) as {
+ projectId?: string;
+ container?: ExportSpec["container"];
+ name?: string;
+ };
if (!body.projectId) return Response.json({ error: "Missing project." }, { status: 400 });
- const job = await createClientJob(body.projectId, body.container);
+ const job = await createClientJob(body.projectId, body.container, body.name?.trim() || undefined);
if (job.status === "error") return Response.json({ error: job.error }, { status: 400 });
return Response.json({ id: job.id, outName: job.outName });
} catch (e) {
diff --git a/site/src/cut/server/jobs.ts b/site/src/cut/server/jobs.ts
index 09ebde32..8e0198b9 100644
--- a/site/src/cut/server/jobs.ts
+++ b/site/src/cut/server/jobs.ts
@@ -5,6 +5,7 @@ import path from "node:path";
import { assertLocalRuntime } from "./local-only";
import { createJobRegistry } from "./jobRegistry";
import { containerExtension, runExport, type ExportSpec } from "./exportPipeline";
+import { exportBaseName } from "../lib/exportDelivery";
import { exportsDir, mediaPath, projectDir, readProject, setActiveJobGuard } from "./projects";
export type { ExportSpec } from "./exportPipeline";
@@ -185,8 +186,7 @@ export function cancelJob(id: string) {
/** Export file named after the project, with a " 2", " 3"… suffix when the
* name is already taken by a file on disk or an export still in flight. */
async function exportName(projectId: string, projectName: string, ext: string) {
- const base =
- projectName.replace(/[/\\:*?"<>|]/g, "").trim().slice(0, 60) || "export";
+ const base = exportBaseName(projectName);
const taken = new Set(
await readdir(exportsDir(projectId)).catch(() => [] as string[])
);
@@ -263,7 +263,7 @@ export async function createJob(form: FormData): Promise<Job> {
if (!doc) throw new Error("Project not found.");
job.projectName = doc.name;
if (preview) job.outName = "preview.mp4";
- else await claimExportName(job, doc.name, containerExtension(spec));
+ else await claimExportName(job, spec.name ?? doc.name, containerExtension(spec));
job.outPath = path.join(
preview ? projectDir(spec.projectId) : exportsDir(spec.projectId),
job.outName
@@ -306,7 +306,8 @@ export async function createJob(form: FormData): Promise<Job> {
*/
export async function createClientJob(
projectId: string,
- container: ExportSpec["container"]
+ container: ExportSpec["container"],
+ name?: string
): Promise<Job> {
assertLocalRuntime();
sweepClientJobs();
@@ -331,7 +332,7 @@ export async function createClientJob(
const doc = await readProject(projectId);
if (!doc) throw new Error("Project not found.");
job.projectName = doc.name;
- await claimExportName(job, doc.name, containerExtension({ container }));
+ await claimExportName(job, name ?? doc.name, containerExtension({ container }));
job.outPath = path.join(exportsDir(projectId), job.outName);
await mkdir(path.dirname(job.outPath), { recursive: true });
} catch (err) {