Open source CapCut alternative.
TypeScript
"use client";
import { captureRenderSnapshot, renderDoc, type ExportDoc, type RenderSnapshot } from "./renderSnapshot";
import { sourceExportPlan, sourceSequence } from "@/cut/lib/sourceExportPlan";
import { DELIVERY_DEFAULTS, EXPORT_PRESETS, EXPORT_RESOLUTIONS } from "./exportPresets";
import { operationFailure, type OperationFailure } from "./operationFailure";
import { UserError, errorFromBody, type UserErrorParams } from "./userError";
import { projectOperation } from "./projectOperation";
import { apiFetch, apiJson, getBackend, type CutBackend } from "./backend";
import { engineFeatures } from "./api";
import type { EngineFeature } from "./engineFeatures";
import { CUT_COLOR } from "./colorSettings";
import { CUT_EXPORT_PASSES } from "./exportPassSettings";
import { loadLibraryLutFile, lutIdOf } from "./linkedLibrary/luts";
import {
removeBrowserExportJob,
reserveBrowserExportJob,
updateBrowserExportJob,
} from "./backend/browser/exportJobs";
import { deleteExport as dropStoredExport, exportsDir, projectDir, writeFileAt, readFileAt, saveExport } from "./backend/browser/opfs";
import { holdRegistered, registerBlobFile, releaseRegistered, resolveRegisteredBlob } from "./backend/browser/registry";
import { captureCloudBackend } from "./backend/cloud";
import { downloadFile, downloadFromUrl } from "./download";
import { bitrateFor, canRenderInBrowser, renderProjectToMp4, renderStemsArchive, type RenderedExport, type SourceExportProfile } from "./exportRender";
import { planStems, type StemDef } from "./stems";
import { putSigned } from "./media";
import { withAssetColors } from "./mediaRead";
import { renderRemovalPieces } from "./removalVideo";
import { renderCardPieces } from "./cameraCardVideo";
import { drawBlock } from "./blockSource";
import { createRasterCanvas, rasterCanvasToPng } from "./raster";
import { clipLen, clipSpeed, getClipSpans, MICRO_GAP_S, openedTimeline, overlayLayers, projectDuration, spanSequence, useEditor } from "./store";
import { captionStyle, cueOverlay, cueWordFrames, laneCues, laneHidden, subtitleLaneCount, trackPos } from "./subtitles";
import { drawStreak, elementLook, isMaskAnimated, isOverlayAnimated, matteLumaToAlpha, normalizeGrade, paintMaskLuma, paintStrokeInk, retimeOf, type EaseId, type FlashFade, type FlashRhythm, type FlashTone, type GlitchKind, type LeakCourse, type Mask, type SpeedNode } from "@donkeycut/effects-kit";
import { renderElementFrames, renderElementPng, renderStillPng, requireStickers } from "./textRender";
import { holdOverlays } from "./frameGrid";
import { CLIP_MIN_SECONDS, clipCovers, clipFrameAt, clipKeyed, clipPosed, clipPoseAt, clipZoom, contentRect, frameOf, isStickerOverlay, isTextOverlay, laneOf, overlayAnimStyle, projectBackground, rectOf, regionPx, removalActive, shadowInk, subjectMasked, parkedTimeline } from "./types";
import { liveReader } from "./liveReader";
import { soundSourceOf, spanSoundSpec, spanUsesSoundFeature, specSound } from "./soundSource";
import type {
Aspect,
AudioClip,
ClipAnim,
MediaAsset,
Overlay,
Selection,
SubtitlesBlock,
TimelineId,
VideoClip,
} from "./types";
import {
deliveryCodec,
deliveryContainer,
deliverySpan,
EXPORT_CODECS,
EXPORT_CONTAINERS,
exportBaseName,
fixedRate,
STEMS_MIME,
stemsArchiveName,
type SpecClipColor,
specMediaFiles,
type ExportAudioCodec,
type ExportCodec,
type ExportContainer,
type ExportRange,
} from "./exportDelivery";
export { deliveryCodec, EXPORT_CODECS, EXPORT_CONTAINERS, fixedRate };
export type { ExportAudioCodec, ExportCodec, ExportContainer, ExportRange };
export interface ExportSettings {
/** Resolve the original media settings before starting an export. */
matchSource?: boolean;
/** Source delivery can preserve compatible encoded packets. */
copySource?: boolean;
width: number;
height: number;
fps: number;
/** The quality tier, on x264's scale; the encoders that take a bitrate get
* `bitrateFor` of it. */
crf: number;
preset: string;
codec: ExportCodec;
container: ExportContainer;
audioCodec: ExportAudioCodec;
/** Video bitrate in bits per second; omitted uses the quality tier. */
bitrate?: number;
/** AAC bitrate in bits per second; omitted uses the delivery default. */
audioBitrate?: number;
audioSampleRate?: number;
audioChannels?: 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 integrated loudness the mix is mastered to, LUFS; absent = the
* mix as it plays. */
loudness?: number;
/** The true peak a mastered mix is held under, dBTP. */
truePeakCeiling?: number;
/** Write the audio as stems too: one WAV per lane, zipped beside the
* video. */
stems?: boolean;
}
export { DELIVERY_DEFAULTS, EXPORT_PRESETS } from "./exportPresets";
export const EXPORT_AUDIO = [
{ id: "aac", label: "AAC", detail: "compressed audio" },
{ id: "pcm", label: "PCM", detail: "uncompressed · MOV" },
] as const satisfies readonly { id: ExportAudioCodec; label: string; detail: string }[];
/** What a container can carry: the codec's own demand, and PCM's MOV. */
export function fitContainer(settings: ExportSettings): ExportSettings {
const needed = deliveryCodec(settings.codec).container ?? (settings.audioCodec === "pcm" ? "mov" : null);
if (needed && settings.container !== needed) return { ...settings, container: needed };
return settings;
}
/** The file extension a setting's container takes. */
export function exportExtension(settings: Pick<ExportSettings, "container">): string {
return deliveryContainer(settings.container).ext;
}
export const EXPORT_FRAME_RATES = [24, 30, 60] as const;
export const EXPORT_QUALITIES = [
{ id: "high", label: "High", detail: "best quality", crf: 19, preset: "medium" },
{ id: "balanced", label: "Balanced", detail: "smaller file", crf: 23, preset: "fast" },
{ id: "small", label: "Small", detail: "fastest render", crf: 28, preset: "veryfast" },
] as const;
export type ExportQualityId = (typeof EXPORT_QUALITIES)[number]["id"];
/** The user's whole choice, as the dialog holds it. */
export interface ExportChoice {
sourceCodec?: boolean;
/** A `resolutionOptions` id; one the project lacks falls back to "source". */
resolution: string;
/** A fixed rate, or "source" for the rate the footage plays at. */
fps: number | "source";
quality: ExportQualityId;
codec: ExportCodec;
container: ExportContainer;
audioCodec: ExportAudioCodec;
/** Megabits per second the user typed; absent = the tier. */
bitrateMbps?: number;
}
/**
* One-click exports. Each is a whole choice, so picking one sets every
* advanced control at once, and the advanced panel shows what it stands for.
*/
export const EXPORT_QUICK_PRESETS = [
{
id: "share",
label: "Share",
detail: "1080p · plays everywhere",
short: "1080p",
choice: { resolution: "1080", fps: "source", quality: "balanced", ...DELIVERY_DEFAULTS },
},
{
id: "best",
label: "Best",
detail: "original file settings",
short: "Source",
choice: { resolution: "source", fps: "source", quality: "high", sourceCodec: true, ...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: "source", quality: "small", ...DELIVERY_DEFAULTS },
},
{
id: "master",
label: "Master",
detail: "ProRes 4444 · MOV · PCM · nothing given up",
short: "ProRes",
choice: { resolution: "source", fps: "source", quality: "high", codec: "prores4444", container: "mov", audioCodec: "pcm" },
},
] as const satisfies readonly { id: string; label: string; detail: string; short: string; choice: ExportChoice }[];
/** The quick preset a choice is, when it is one. */
export function quickPresetOf(choice: ExportChoice, options: ResolutionOption[]): string | null {
const key = (c: ExportChoice) =>
[resolveResolution(options, c.resolution).id, c.fps, c.quality, c.codec, c.container, c.audioCodec, c.bitrateMbps ?? "", c.sourceCodec ?? false].join("|");
const k = key(choice);
return EXPORT_QUICK_PRESETS.find((p) => key(p.choice) === k)?.id ?? null;
}
/** 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.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. `sourceFps` is the footage's rate (see
* `sourceExportProfile`), what a "source" frame-rate choice resolves to. */
export function choiceSettings(
choice: ExportChoice,
options: ResolutionOption[],
sourceFps: number = DEFAULT_EXPORT_FPS,
sourceRates?: Partial<SourceExportProfile>
): ExportSettings {
const q = EXPORT_QUALITIES.find((x) => x.id === choice.quality) ?? EXPORT_QUALITIES[0];
const r = resolveResolution(options, choice.resolution);
const settings = fitContainer({
copySource: choice.resolution === "source" && choice.fps === "source" && choice.quality === "high" && !choice.bitrateMbps,
width: r.width,
height: r.height,
fps: choice.fps === "source" ? sourceFps : choice.fps,
crf: q.crf,
preset: q.preset,
codec: choice.sourceCodec ? sourceRates?.codec ?? choice.codec : choice.codec,
container: choice.container,
audioCodec: choice.audioCodec,
// A fixed-rate codec has one rate per profile; a typed bitrate is for
// the others.
...(choice.bitrateMbps && !fixedRate(choice.codec)
? { bitrate: Math.round(choice.bitrateMbps * 1_000_000) }
: {}),
});
return choice.resolution === "source" && !choice.bitrateMbps
? matchSourceBitrates(settings, sourceRates)
: settings;
}
/** Source-size delivery keeps the source's compression budget. */
export function matchSourceBitrates(
settings: ExportSettings,
source?: Partial<SourceExportProfile>
): ExportSettings {
if (fixedRate(settings.codec)) return settings;
return {
...settings,
...(source?.audioSampleRate ? { audioSampleRate: source.audioSampleRate } : {}),
...(source?.audioChannels ? { audioChannels: source.audioChannels } : {}),
...(source?.videoBitrate && Number.isFinite(source.videoBitrate) && source.videoBitrate > 0
? { bitrate: Math.round(settings.copySource ? source.videoBitrate : Math.min(bitrateFor(settings), source.videoBitrate)) } : {}),
...(settings.audioCodec === "aac" && source?.audioBitrate && Number.isFinite(source.audioBitrate) && source.audioBitrate > 0
? { audioBitrate: Math.round(settings.copySource ? source.audioBitrate : Math.min(audioBitrate(settings), source.audioBitrate)) } : {}),
};
}
/** Apply a probed source profile to an original-settings export. */
export function matchSourceSettings(settings: ExportSettings, source: SourceExportProfile): ExportSettings {
return matchSourceBitrates({ ...settings, matchSource: false, fps: source.fps ?? settings.fps, codec: source.codec ?? settings.codec }, source);
}
/** 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" 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,
clips: VideoClip[],
assets: MediaAsset[],
composition?: Pick<ExportDoc, "audioClips" | "overlays" | "subtitles">
): ResolutionOption[] {
const src = sourceFrame(aspect, clips, assets, composition);
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(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);
const k = shortSide / Math.min(f.w, f.h);
const even = (n: number) => 2 * Math.round((n * k) / 2);
return { width: even(f.w), height: even(f.h) };
}
export function presetSettings(
preset: (typeof EXPORT_PRESETS)[number],
aspect: Aspect
): ExportSettings {
return { ...scaledFrame(aspect, preset.shortSide), ...preset.settings };
}
/**
* Plain source sequences keep their original frame. Compositions fit the
* project aspect, capped at 4K.
* Projects with no measured source dimensions use the base frame.
*/
export function originalSettings(
aspect: Aspect,
clips: VideoClip[],
assets: MediaAsset[],
composition?: Pick<ExportDoc, "audioClips" | "overlays" | "subtitles">
): ExportSettings {
return { ...sourceFrame(aspect, clips, assets, composition), copySource: true, matchSource: true, fps: 30, crf: 19, preset: "medium", ...DELIVERY_DEFAULTS };
}
/** The frame `originalSettings` renders at — see its note for the rules. */
export function sourceFrame(
aspect: Aspect,
clips: VideoClip[],
assets: MediaAsset[],
composition?: Pick<ExportDoc, "audioClips" | "overlays" | "subtitles">
): { width: number; height: number } {
const source = composition && sourceSequence({ aspect, clips, assets, ...composition })?.[0];
if (source) return { width: source.asset.width!, height: source.asset.height! };
const base = frameOf(aspect);
const longBase = Math.max(base.w, base.h);
const sourceScale = Math.max(
0,
...getClipSpans(clips, assets).map((sp) =>
Math.max((sp.asset.width ?? 0) / base.w, (sp.asset.height ?? 0) / base.h)
)
);
const k = Math.min(3840 / longBase, sourceScale || 1);
const even = (n: number) => Math.max(2, 2 * Math.round((n * k) / 2));
return { width: even(base.w), height: even(base.h) };
}
/**
* Rough output size for a setting, in bytes: the video bitrate the encoders
* are given (`bitrateFor`) plus the selected audio bitrate. A CRF encode
* spends what the footage needs, so busy footage runs larger and flat footage
* smaller; the dialog shows it as an approximation.
*/
export function estimateExportBytes(settings: ExportSettings, durationSec: number): number {
if (durationSec <= 0) return 0;
return ((bitrateFor(settings) + audioBitrate(settings)) * durationSec) / 8;
}
/** AAC follows its source budget or uses 192 kbps; PCM is 48 kHz stereo 16-bit. */
export function audioBitrate(settings: Pick<ExportSettings, "audioCodec" | "audioBitrate" | "audioSampleRate" | "audioChannels">): number {
return settings.audioCodec === "pcm" ? (settings.audioSampleRate ?? 48_000) * 16 * (settings.audioChannels ?? 2) : settings.audioBitrate ?? 192_000;
}
/** Human-readable size estimate matching the finished-export MB display,
* with the number and unit in the reader's locale ("~1.4 MB", "~1,4 Mo"). */
export function formatSizeEstimate(bytes: number, locale: string): string {
if (bytes <= 0) return "";
const mb = bytes / (1024 * 1024);
const size = (value: number, unit: "megabyte" | "gigabyte", digits: number) =>
`~${new Intl.NumberFormat(locale, { style: "unit", unit, minimumFractionDigits: digits, maximumFractionDigits: digits }).format(value)}`;
if (mb < 1) return size(1, "megabyte", 0);
if (mb < 1000) return mb < 10 ? size(mb, "megabyte", 1) : size(Math.round(mb), "megabyte", 0);
return size(mb / 1024, "gigabyte", 1);
}
/** Reveal a rendered export in Finder (local engine only). */
export async function revealExport(
projectId: string,
file: string,
backend: CutBackend = getBackend()
) {
await backend.fetch(
`/api/cut/projects/${projectId}/exports/${encodeURIComponent(file)}/reveal`,
{ method: "POST" }
);
}
/** A finished export's file, by name and modification time.
*
* The time is part of the URL. An export name comes free again when its file
* is deleted, and the next render under that name lands on the same path, so
* a URL of the path alone would answer with whatever the browser and the edge
* still hold from the earlier file. The time changes with every render, so
* each one has a URL of its own. */
export function exportFileUrl(projectId: string, item: { file: string; mtime: number }): string {
return getBackend().url(
`/api/cut/projects/${projectId}/exports/${encodeURIComponent(item.file)}?v=${item.mtime}`
);
}
/** Download a rendered export — what stands in for revealExport when the
* backend has no Finder (the cloud route 302s to a signed R2 URL). */
export function downloadProjectExport(projectId: string, item: { file: string; mtime: number }) {
downloadFromUrl(exportFileUrl(projectId, item), item.file);
}
/** Delete a rendered export from the project folder. Throws on failure so the
* UI can stay truthful instead of optimistically dropping a file that's still
* on disk (which is why deleted exports used to reappear on the next refresh). */
export async function deleteExport(projectId: string, file: string) {
const res = await apiFetch(
`/api/cut/projects/${projectId}/exports/${encodeURIComponent(file)}`,
{ method: "DELETE" }
);
if (!res.ok) {
const body = (await res.json().catch(() => ({}))) as { error?: string };
throw errorFromBody(body, new UserError("export_delete_failed", "Could not delete the export."));
}
}
/** The neutral built cut: the engine spec plus the browser-rendered overlay
* PNGs. The local path serializes it to the engine's multipart form; the
* cloud path presigns the PNGs to R2 and posts the spec as JSON. */
export interface ExportPayload {
spec: object;
pngs: { name: string; blob: Blob }[];
}
/** A masked video clip's coverage in the spec: one grayscale still, a
* sampled sequence when the mask is keyframed, or the shared person matte
* (`subject`) with its knobs. */
interface SpecMask {
file?: string;
frames?: { file: string; duration: number }[];
subject?: { invert?: boolean; feather?: number };
}
/** How often a keyframed clip mask samples — the person-matte cadence; the
* server re-stamps the output fps over it. */
const MASK_SAMPLE_FPS = 15;
/** The rate a moving mask samples at: the matte cadence, or the export's own
* frame rate for a mask keyed more densely than that. A tracked outline
* moves on every frame, and a coarser sample would step behind the hand. */
const maskSampleFps = (mask: Mask | undefined, dur: number, fps: number) =>
(mask?.kf?.length ?? 0) / Math.max(dur, 1e-3) > MASK_SAMPLE_FPS ? Math.max(fps, MASK_SAMPLE_FPS) : MASK_SAMPLE_FPS;
/** Paint a clip's mask coverage for its export segment: one luma PNG for a
* resting mask, a 15fps sampled sequence for a keyframed one. Keyframed
* opacity folds into the luma — a clip fading under its pose track exports
* an opacity-scaled coverage (flat white when it has no shape mask), so the
* graph never needs an animatable alpha filter. The pictures land in `pngs`
* and the returned entry references them by name. */
async function renderClipMaskPictures(
clip: VideoClip,
box: { x: number; y: number; w: number; h: number },
W: number,
H: number,
dur: number,
fps: number,
tag: string,
pngs: ExportPayload["pngs"]
): Promise<SpecMask | undefined> {
const m = clip.mask && clip.mask.kind !== "subject" ? clip.mask : undefined;
const opacityVaries = (clip.kf ?? []).some((k) => Math.abs(k.opacity - 1) > 1e-3);
const radius = clip.boxStyle?.radius ?? 0;
if (!m && !opacityVaries && radius <= 0) return undefined;
const rect = rectOf(clip);
const anchor = { x: rect.x + rect.w / 2, y: rect.y + rect.h / 2 };
const frame = { width: W, height: H, scale: Math.min(W, H) / 1080 };
// Rounded corners trim coverage at the clip's box: outside the rounded box
// everything drops, and inside it the mask keeps deciding.
const rp = regionPx(clip.frame, W, H);
const rb = rp
? { x: rp.rx - box.x, y: rp.ry - box.y, w: rp.rw, h: rp.rh }
: { x: -box.x, y: -box.y, w: W, h: H };
const canvas = createRasterCanvas(box.w, box.h);
const blobAt = (tLocal: number) => {
const ctx = canvas.getContext("2d") as CanvasRenderingContext2D;
if (radius > 0) {
ctx.globalCompositeOperation = "source-over";
ctx.fillStyle = "#000000";
ctx.fillRect(0, 0, canvas.width, canvas.height);
ctx.save();
ctx.beginPath();
ctx.roundRect(rb.x, rb.y, rb.w, rb.h, radius * frame.scale);
ctx.clip();
}
if (m) {
paintMaskLuma(canvas, m, tLocal, frame, anchor, box.x, box.y);
} else {
ctx.globalCompositeOperation = "source-over";
ctx.fillStyle = "#ffffff";
ctx.fillRect(0, 0, canvas.width, canvas.height);
}
if (radius > 0) ctx.restore();
if (opacityVaries) {
const v = Math.round(
255 * Math.max(0, Math.min(1, clipPoseAt(clip, tLocal).opacity))
);
ctx.globalCompositeOperation = "multiply";
ctx.fillStyle = `rgb(${v},${v},${v})`;
ctx.fillRect(0, 0, canvas.width, canvas.height);
ctx.globalCompositeOperation = "source-over";
}
return rasterCanvasToPng(canvas);
};
if (!(m && isMaskAnimated(m)) && !opacityVaries) {
const name = `${tag}.png`;
pngs.push({ name, blob: await blobAt(0) });
return { file: name };
}
const rate = maskSampleFps(m, dur, fps);
const step = 1 / rate;
const n = Math.max(1, Math.round(dur * rate));
const frames: { file: string; duration: number }[] = [];
for (let i = 0; i < n; i++) {
const name = `${tag}_f${i}.png`;
pngs.push({ name, blob: await blobAt(i * step) });
frames.push({ file: name, duration: i === n - 1 ? Math.max(step, dur - (n - 1) * step) : step });
}
return { frames };
}
/** The keyed silhouette a removal clip's shadow falls from: white coverage
* over transparency in the clip's source frame, sampled at a shadow frame's
* local second. Null means the shadow keeps the picture's rectangle — no
* active removal, a backdrop fill restoring the full picture, or an AI
* removal whose matte hasn't baked (the export shows the plain picture then,
* and a rectangular shadow matches it). */
function removalShadowSilhouette(
clip: VideoClip,
assets: MediaAsset[]
): { at: (tLocal: number) => Promise<CanvasImageSource | null>; dispose: () => void } | null {
const r = clip.removal;
if (!removalActive(r)) return null;
if (r!.backdrop && r!.backdrop.kind !== "none") return null;
const asset = assets.find((a) => a.id === clip.assetId);
if (!asset) return null;
const rt = retimeOf(clip);
const still = asset.type === "image";
const canvas = createRasterCanvas(2, 2);
const ctx = canvas.getContext("2d", {
willReadFrequently: true,
}) as CanvasRenderingContext2D | null;
if (!ctx) return null;
const stage = (w: number, h: number) => {
if (canvas.width !== w || canvas.height !== h) {
canvas.width = w;
canvas.height = h;
}
ctx.clearRect(0, 0, w, h);
};
// The preview's shadow falls from the whole layer — keyed picture plus the
// stroke ink laid behind it — so the ink joins the silhouette here too;
// a thick or offset stroke moves the shadow's edge with it.
const ink = createRasterCanvas(2, 2);
const inkCtx = ink.getContext("2d") as CanvasRenderingContext2D | null;
// The ink paints from the selection (inset when the selection is the hole),
// before any complement, so it rims what the stroke really shows.
const paintInk = (w: number, h: number, tLocal: number): boolean => {
const stroke = r!.stroke;
if (!stroke || !inkCtx) return false;
if (ink.width !== w || ink.height !== h) {
ink.width = w;
ink.height = h;
}
inkCtx.setTransform(1, 0, 0, 1, 0, 0);
inkCtx.globalCompositeOperation = "source-over";
inkCtx.clearRect(0, 0, w, h);
paintStrokeInk(
inkCtx,
canvas as CanvasImageSource,
w,
h,
stroke,
tLocal,
Math.min(w, h) / 1080,
!!r!.invert
);
return true;
};
const matte = r!.matte ? assets.find((a) => a.id === r!.matte!.assetId) : undefined;
if (!matte) return null;
const reader = liveReader(matte);
const mdur = Math.max(0.1, matte.duration || 0.1);
return {
at: async (tLocal) => {
const srcT = still ? 0 : rt.srcAt(tLocal);
const frame = await reader.frameAt(
Math.min(Math.max(0, srcT - r!.matte!.in), mdur - 0.001)
);
if (frame.kind !== "ready") return null;
stage(frame.width, frame.height);
ctx.drawImage(frame.image, 0, 0);
const px = ctx.getImageData(0, 0, frame.width, frame.height);
matteLumaToAlpha(px.data);
ctx.putImageData(px, 0, 0);
const inked = paintInk(frame.width, frame.height, tLocal);
// Inverted, the clip shows everything around the matte, so the shadow's
// silhouette is the complement.
if (r!.invert) {
for (let i = 3; i < px.data.length; i += 4) px.data[i] = 255 - px.data[i];
ctx.putImageData(px, 0, 0);
}
if (inked) {
ctx.globalCompositeOperation = "destination-over";
ctx.drawImage(ink, 0, 0);
ctx.globalCompositeOperation = "source-over";
}
return canvas as CanvasImageSource;
},
dispose: () => reader.dispose(),
};
}
/**
* Paint the shadow a clip casts, frame-sized and transparent everywhere else.
* The silhouette is the picture the clip really shows — its box, its rounded
* corners, its mask, its pose, its keyed cutout — thrown behind itself and
* then punched back out, so the graph can lay the result over the frame and
* get what sitting behind the clip would have looked like. A moving clip
* samples the shadow per frame, the way a keyframed mask samples its
* coverage. Null without a shadow.
*/
async function renderClipShadowPictures(
clip: VideoClip,
asset: { width?: number; height?: number },
W: number,
H: number,
dur: number,
fps: number,
tag: string,
pngs: ExportPayload["pngs"],
assets: MediaAsset[]
): Promise<SpecMask | undefined> {
const sh = clip.boxStyle?.shadow;
if (!sh) return undefined;
// A cutout's shadow falls from the keyed subject, sampled per frame from
// the matte, the way the preview casts it.
const silhouette = removalShadowSilhouette(clip, assets);
const scale = Math.min(W, H) / 1080;
const frame = { width: W, height: H, scale };
const rect = rectOf(clip);
const box = { x: rect.x * W, y: rect.y * H, w: rect.w * W, h: rect.h * H };
const radius = Math.max(0, (clip.boxStyle?.radius ?? 0) * scale);
const mask = clip.mask && clip.mask.kind !== "subject" ? clip.mask : undefined;
// The picture's own footprint inside the box — a fitted clip's shadow follows
// the picture, not the empty margins beside it.
const pic =
asset.width && asset.height
? contentRect(box, asset.width, asset.height, clipCovers(clip), clipZoom(clip), clip.panX ?? 0, clip.panY ?? 0)
: box;
const shape = createRasterCanvas(W, H);
const cover = createRasterCanvas(W, H);
const canvas = createRasterCanvas(W, H);
// The smear and the blur the preview lays on the shadow, made on first use.
let smear: ReturnType<typeof createRasterCanvas> | null = null;
let soft: ReturnType<typeof createRasterCanvas> | null = null;
const anchor = { x: rect.x + rect.w / 2, y: rect.y + rect.h / 2 };
const blobAt = async (tLocal: number) => {
const sil = silhouette ? await silhouette.at(tLocal) : null;
const shapeCtx = shape.getContext("2d") as CanvasRenderingContext2D;
shapeCtx.setTransform(1, 0, 0, 1, 0, 0);
shapeCtx.clearRect(0, 0, W, H);
const pose = clipPosed(clip) ? clipFrameAt(clip, tLocal, W / H) : null;
const look = pose ? elementLook(pose, scale) : null;
if (pose) {
shapeCtx.translate(pose.x * W, pose.y * H);
shapeCtx.rotate((pose.rotation * Math.PI) / 180);
shapeCtx.scale(pose.scale, pose.scale);
shapeCtx.translate(-anchor.x * W, -anchor.y * H);
}
// The lit shape: the picture — a cutout's keyed silhouette in its place —
// trimmed at the box's rounded corners.
shapeCtx.save();
shapeCtx.beginPath();
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);
}
shapeCtx.restore();
if (mask) {
// The mask decides the rest of the shape; its luma becomes coverage.
paintMaskLuma(cover, mask, tLocal, frame, anchor, 0, 0);
shapeCtx.setTransform(1, 0, 0, 1, 0, 0);
shapeCtx.globalCompositeOperation = "destination-in";
shapeCtx.drawImage(cover as CanvasImageSource, 0, 0);
shapeCtx.globalCompositeOperation = "source-over";
}
// A moving clip with motion blur casts from its streaked shape.
let lit = shape;
if (look && look.taps >= 2) {
smear ??= createRasterCanvas(W, H);
const smearCtx = smear.getContext("2d") as CanvasRenderingContext2D;
smearCtx.setTransform(1, 0, 0, 1, 0, 0);
smearCtx.clearRect(0, 0, W, H);
drawStreak(smearCtx, shape as CanvasImageSource, 0, 0, look);
lit = smear;
}
const ctx = canvas.getContext("2d") as CanvasRenderingContext2D;
ctx.setTransform(1, 0, 0, 1, 0, 0);
ctx.globalCompositeOperation = "source-over";
ctx.clearRect(0, 0, W, H);
ctx.save();
ctx.shadowColor = shadowInk(sh);
ctx.shadowBlur = Math.max(0, sh.blur) * scale;
ctx.shadowOffsetX = (sh.x ?? 0) * scale;
ctx.shadowOffsetY = (sh.y ?? 0) * scale;
ctx.drawImage(lit as CanvasImageSource, 0, 0);
ctx.restore();
ctx.globalCompositeOperation = "destination-out";
ctx.drawImage(lit as CanvasImageSource, 0, 0);
ctx.globalCompositeOperation = "source-over";
// The keyed blur softens the shadow as it softens the picture.
if (!look || !(look.blur > 0) || !("filter" in ctx)) return rasterCanvasToPng(canvas);
soft ??= createRasterCanvas(W, H);
const softCtx = soft.getContext("2d") as CanvasRenderingContext2D;
softCtx.setTransform(1, 0, 0, 1, 0, 0);
softCtx.clearRect(0, 0, W, H);
softCtx.filter = `blur(${look.blur.toFixed(2)}px)`;
softCtx.drawImage(canvas as CanvasImageSource, 0, 0);
softCtx.filter = "none";
return rasterCanvasToPng(soft);
};
try {
// A keyed subject moves every frame, so its shadow samples like an
// animated mask does.
const moves = (mask && isMaskAnimated(mask)) || clipKeyed(clip) || !!silhouette;
if (!moves) {
const name = `${tag}.png`;
pngs.push({ name, blob: await blobAt(0) });
return { file: name };
}
const rate = maskSampleFps(mask, dur, fps);
const step = 1 / rate;
const n = Math.max(1, Math.round(dur * rate));
const frames: { file: string; duration: number }[] = [];
for (let i = 0; i < n; i++) {
const name = `${tag}_f${i}.png`;
pngs.push({ name, blob: await blobAt(i * step) });
frames.push({ file: name, duration: i === n - 1 ? Math.max(step, dur - (n - 1) * step) : step });
}
return { frames };
} finally {
silhouette?.dispose();
}
}
/** Paint the clip's border ring — a stroked rounded rect along its box edge,
* transparent everywhere else — sized to the segment the graph frames (the
* full frame for track 0, the region box for overlays). The engine overlays
* it onto the segment before fades, masks and pose, so the ring rides the
* clip like the preview's stroke does. Null without a border. */
function renderClipBorderPng(
clip: VideoClip,
seg: { w: number; h: number },
ring: { x: number; y: number; w: number; h: number },
W: number,
H: number
): Promise<Blob> | null {
const bs = clip.boxStyle;
if (!bs?.borderWidth) return null;
const scale = Math.min(W, H) / 1080;
const bw = bs.borderWidth * scale;
const rad = Math.max(0, (bs.radius ?? 0) * scale);
const canvas = createRasterCanvas(seg.w, seg.h);
const ctx = canvas.getContext("2d") as CanvasRenderingContext2D;
ctx.strokeStyle = bs.borderColor ?? "#ffffff";
ctx.lineWidth = bw;
ctx.beginPath();
ctx.roundRect(ring.x + bw / 2, ring.y + bw / 2, ring.w - bw, ring.h - bw, Math.max(0, rad - bw / 2));
ctx.stroke();
return rasterCanvasToPng(canvas);
}
/** The spec names a file by its name in the project's media folder. */
const specFile = (a: MediaAsset) => a.fileName;
/** What a source's code values mean, for the spec: the profile the header
* settled (with the person's override), and the matrix and range the file
* decodes with. A still is sRGB, decoded to full-range RGB, and a block is
* painted in Rec.709. The spec builder reads every video's header first
* (`withAssetColors`), so a video without a record is a caller's bug. */
export function specColor(
asset: Pick<MediaAsset, "type" | "color" | "colorProfile" | "block" | "fileName"> | undefined
): SpecClipColor {
if (!asset || asset.type === "image") return { profile: "srgb", matrix: "bt709", fullRange: true };
if (asset.block) return { profile: "rec709", matrix: "bt709", fullRange: false };
const c = asset.color;
if (!c) {
throw new UserError("asset_color_unread", `The color of ${asset.fileName} was never read.`, { file: asset.fileName });
}
return { profile: asset.colorProfile ?? c.detected, matrix: c.matrix, fullRange: c.fullRange };
}
/** A camera card draws its own corners and shadow, so its clip's box style
* stands aside in every painted picture (mask corners, border, shadow). */
const cardBoxless = (c: VideoClip): VideoClip => (c.card && c.boxStyle ? { ...c, boxStyle: undefined } : c);
/** The spec fields of a camera-card clip whose layer ships as `<tag>`
* pieces: the pair stands in for the source, already framed to the box,
* graded, looked and mirrored, so the engine frames it 1:1 and applies none
* of those again. */
const cardEntry = (tag: string) => ({
removal: { rgb: `${tag}_rgb.mp4`, alpha: `${tag}_a.mp4` },
grade: undefined,
look: undefined,
effects: undefined,
fit: "fill" as const,
zoom: 1,
panX: 0,
panY: 0,
flipH: undefined,
flipV: undefined,
});
/** Build the export spec + overlay PNGs from the cut. Media already lives in
* the project folder — the spec references it by file name; only overlay PNGs
* travel with the request. Shared by full exports and the low-res hover proxy. */
export async function buildExportPayload(
projectId: string,
doc: ExportDoc,
settings: ExportSettings,
target: "export" | "preview" | "card" | "hls"
): Promise<ExportPayload> {
// H.264 is an 8-bit delivery; an HDR picture takes HEVC Main 10 or ProRes.
if ((doc.colorSpace ?? "sdr") !== "sdr" && settings.codec === "h264" && target === "export") {
throw new UserError("export_h264_hdr", "H.264 is 8-bit. Export HDR as HEVC or ProRes.");
}
// Every video's color is read before the spec is: footage the lazy fill
// has not reached would otherwise go out as Rec.709.
doc = { ...doc, assets: await withAssetColors(doc.assets, doc) };
// Elements shorter than an output frame widen onto the one they hold.
doc = { ...doc, overlays: holdOverlays(doc.overlays, settings.fps) };
const spans = getClipSpans(doc.clips, doc.assets);
const duration = projectDuration(doc);
const pngs: ExportPayload["pngs"] = [];
const assetById = new Map(doc.assets.map((a) => [a.id, a]));
// Cuts with an empty track 0 still export: track 0 becomes a bed of the
// project's background color the length of the cut and the elements, layers
// and soundtrack composite onto it — the same path as a gap before the first
// track-0 clip. A cut of nothing but titles and shapes is that case for its
// whole length. Anything on any row gives the project a duration, so having
// one is the same question as having something to render.
if (!(duration > 0)) {
throw new UserError("export_timeline_empty", "Add something to the timeline first.");
}
// The person matte renders first, so the loops below attach subject fields
// only when the effect will actually composite (no person segmenter, or no
// person → everything renders plain, matching the preview's degrade). The
// spec field keeps its `behindMask` name so older engines keep rendering
// behind-tagged text.
let behindMask: { file: string; from: number } | undefined;
const wantsSubject =
doc.overlays.some((o) => subjectMasked(o) && !o.hidden) ||
doc.clips.some((c) => c.mask?.kind === "subject" && !c.hidden);
if (wantsSubject) {
const mask = await import("./maskVideo")
.then((m) => m.renderSubjectMask(doc, duration))
.catch(() => null);
if (mask) {
pngs.push({ name: "behind_mask.mp4", blob: mask.blob });
behindMask = { file: "behind_mask.mp4", from: mask.from };
}
}
/** A clip whose resting turn or fade rides as a one-key pose track: the
* graph and the mask painter both read the picture's pose off `kf`, and a
* single key holds flat, so the export renders the resting transform
* through the path the animated one already takes. */
const posed = (c: VideoClip): VideoClip => {
if (!clipPosed(c) || clipKeyed(c)) return c;
const rect = rectOf(c);
return {
...c,
kf: [
{
t: 0,
x: rect.x + rect.w / 2,
y: rect.y + rect.h / 2,
scale: 1,
rotation: c.rotation ?? 0,
opacity: c.opacity ?? 1,
},
],
};
};
/** The subject entry a masked item ships, or undefined without a matte. */
const subjectOf = (m: { invert?: boolean; feather?: number } | undefined) =>
behindMask && m
? {
...(m.invert ? { invert: true } : {}),
...(m.feather ? { feather: m.feather } : {}),
}
: undefined;
const clipEntries = spans.map((sp) => ({
...spanSoundSpec(sp, specFile),
file: sp.asset.fileName,
in: sp.clip.in,
out: sp.clip.out,
muted: sp.clip.muted,
volume: sp.clip.volume ?? 1,
sound: sp.clip.sound,
fit: sp.clip.fit ?? "fit",
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,
reverse: sp.clip.reverse,
smoothSlow: sp.clip.smoothSlow,
transition: sp.transitionOut,
// A cross dissolve carries its own window: the picture cuts, so the
// server's blend must not see one. The handles are what the crossing
// reaches into so both clips are audible over that cut.
soundCross: sp.soundOut,
soundAhead: sp.soundAhead,
soundBack: sp.soundBack,
// The style rides along with the overlap; the server resolves it to an
// xfade name (and the cross-zoom ramps) itself, so the spec carries only
// the id.
transitionStyle: sp.clip.transitionStyle,
transitionFeather: sp.clip.transitionFeather,
transitionBand: sp.clip.transitionBand,
animIn: sp.clip.animIn,
animOut: sp.clip.animOut,
look: sp.clip.look,
lookAmount: sp.clip.lookAmount,
effects: sp.clip.effects,
effectsFrom: sp.clip.effectsFrom,
hidden: sp.clip.hidden,
// A still: the server loops the image for the clip's length instead of
// trimming a source span.
image: sp.asset.type === "image",
grade: normalizeGrade(sp.clip.grade),
color: specColor(sp.asset),
mask: undefined as SpecMask | undefined,
shadow: undefined as SpecMask | undefined,
kf: posed(sp.clip).kf,
motionBlur: sp.clip.motionBlur,
border: undefined as string | undefined,
removal: undefined as { rgb: string; alpha: string } | undefined,
staged: undefined as boolean | undefined,
}));
// A block owns no file: its card is painted here at the output size and
// travels with the job, so this render draws what the preview draws.
for (let i = 0; i < spans.length; i++) {
if (!spans[i].asset.block) continue;
const name = `block_${i}.png`;
pngs.push({
name,
blob: await rasterCanvasToPng(drawBlock(spans[i].asset, settings.width, settings.height)),
});
clipEntries[i].file = name;
clipEntries[i].staged = true;
}
// Track-0 segments render at the full output frame (regioned clips pad out
// to it), so their masks paint full-frame. A subject mask rides the shared
// matte; painted pictures still travel beside it when the pose track keys
// opacity, since opacity ships as coverage luma.
for (let i = 0; i < spans.length; i++) {
const c = posed(cardBoxless(spans[i].clip));
const dur = Math.max(CLIP_MIN_SECONDS, retimeOf(c).len);
const pictures = await renderClipMaskPictures(
c,
{ x: 0, y: 0, w: settings.width, h: settings.height },
settings.width,
settings.height,
dur,
settings.fps,
`mask_c${i}`,
pngs
);
const subject = c.mask?.kind === "subject" ? subjectOf(c.mask) : undefined;
if (pictures || subject) {
clipEntries[i].mask = { ...(pictures ?? {}), ...(subject ? { subject } : {}) };
}
const rp = regionPx(c.frame, settings.width, settings.height);
const ring = rp
? { x: rp.rx, y: rp.ry, w: rp.rw, h: rp.rh }
: { x: 0, y: 0, w: settings.width, h: settings.height };
const borderBlob = renderClipBorderPng(
c,
{ w: settings.width, h: settings.height },
ring,
settings.width,
settings.height
);
if (borderBlob) {
const name = `border_c${i}.png`;
pngs.push({ name, blob: await borderBlob });
clipEntries[i].border = name;
}
clipEntries[i].shadow = await renderClipShadowPictures(
c,
spans[i].asset,
settings.width,
settings.height,
dur,
settings.fps,
`shadow_c${i}`,
pngs,
doc.assets
);
// A removal clip's picture travels as its keyed layer, client-rendered:
// a color/alpha pair the engine merges and frames in place of the source
// decode. Grade and key are baked in (the entry's grade clears so the
// engine never grades twice); the look stays on the entry — the engine
// runs it over the flattened segment. A null is the declared degrade (no
// matte yet — the export shows the plain picture, like the preview); a
// broken render throws and fails the export instead of silently dropping
// the cutout.
if (c.card && !c.hidden) {
const rp = regionPx(c.frame, settings.width, settings.height);
const pieces = await renderCardPieces(spans[i].asset, spans[i].clip, doc.assets, {
fps: settings.fps,
frameW: settings.width,
frameH: settings.height,
box: rp ? { w: rp.rw, h: rp.rh } : { w: settings.width, h: settings.height },
});
if (pieces) {
pngs.push({ name: `card_c${i}_rgb.mp4`, blob: pieces.rgb });
pngs.push({ name: `card_c${i}_a.mp4`, blob: pieces.alpha });
Object.assign(clipEntries[i], cardEntry(`card_c${i}`));
}
} else if (removalActive(c.removal) && !c.hidden) {
const pieces = await renderRemovalPieces(spans[i].asset, spans[i].clip, doc.assets, {
fps: settings.fps,
maxShort: Math.min(
2160,
Math.round(Math.min(settings.width, settings.height) * clipZoom(c))
),
// Effects bake into the keyed layer after the look, as the preview
// wears them, so the look bakes in with them.
bakeLook: !!c.effects?.length,
});
if (pieces) {
pngs.push({ name: `removal_c${i}_rgb.mp4`, blob: pieces.rgb });
pngs.push({ name: `removal_c${i}_a.mp4`, blob: pieces.alpha });
clipEntries[i].removal = { rgb: `removal_c${i}_rgb.mp4`, alpha: `removal_c${i}_a.mp4` };
clipEntries[i].grade = undefined;
if (c.effects?.length) clipEntries[i].look = undefined;
clipEntries[i].effects = undefined;
}
}
}
// The server's video graph is a sequential fold, so gaps between the
// free-placed clips ship as explicit spacer segments: no file, hidden and
// muted, which the server renders as black + silence for the gap's length.
const spacer = (len: number) => ({
file: "",
in: 0,
out: len,
muted: true,
volume: 0,
fit: "fit" as const,
zoom: 1,
panX: 0,
panY: 0,
frame: undefined,
speed: 1,
transition: 0,
hidden: true,
image: false,
});
// An overlay-only cut has no track-0 spans: the whole base is one black bed.
// Titles or sound that outlast the last shot run over black to the end.
const last = spans[spans.length - 1];
const tail = last ? duration - (last.start + last.len) : 0;
const clips =
spans.length === 0
? [spacer(duration)]
: [
...spanSequence(spans).flatMap(({ gapBefore }, i) => [
...(gapBefore > 0 ? [spacer(gapBefore)] : []),
clipEntries[i],
]),
...(tail > MICRO_GAP_S ? [spacer(tail)] : []),
];
// Video tracks composited over track 0; hidden ones are dropped. Each
// track's transitions and animations translate into per-clip head/tail
// ramps: on an upper track a fade is an alpha fade (transparent, so the
// tracks beneath show through), and a transition blends the incoming clip
// in over the outgoing one — the incoming alpha-fades in for the overlap
// while the outgoing stays opaque underneath it (cross zoom adds its zoom
// ramps). Animations map fade/zoom natively; the styles that need frame
// motion degrade to a fade up here.
const overlayTracks = [...new Set(overlayLayers(doc.clips).map((c) => c.track))];
// Entry → its source clip, so the mask loop below can paint per clip after
// the entries assemble.
const overlayClipOf = new Map<object, VideoClip>();
const overlayVideos = overlayTracks.flatMap((track) => {
const trackSpans = getClipSpans(doc.clips, doc.assets, track);
const ramps = trackSpans.map(() => ({
headFade: 0,
tailFade: 0,
headZoom: 0,
tailZoom: 0,
// Sound-only ramps: a dissolve on the sound leaves the picture alone,
// so its windows ride apart from the alpha fades.
headSound: 0,
tailSound: 0,
soundAhead: 0,
soundBack: 0,
}));
trackSpans.forEach((sp, i) => {
const r = ramps[i];
const applyAnim = (a: ClipAnim | undefined, side: "head" | "tail") => {
if (!a) return;
const secs = Math.min(a.seconds, sp.len);
if (overlayAnimStyle(a.style) === "zoom") {
r[side === "head" ? "headZoom" : "tailZoom"] = secs;
} else {
r[side === "head" ? "headFade" : "tailFade"] = secs;
}
};
// A transitioned joint owns its edges: that side's animation is held so
// it never fights the transition's blend (mirrors preview and track 0).
if (!((trackSpans[i - 1]?.transitionOut ?? 0) > 0)) applyAnim(sp.clip.animIn, "head");
if (!(sp.transitionOut > 0)) applyAnim(sp.clip.animOut, "tail");
if (sp.transitionOut > 0 && trackSpans[i + 1]) {
const nr = ramps[i + 1];
nr.headFade = Math.max(nr.headFade, sp.transitionOut);
if ((sp.clip.transitionStyle ?? "crossfade") === "crosszoom") {
r.tailZoom = Math.max(r.tailZoom, sp.transitionOut);
nr.headZoom = Math.max(nr.headZoom, sp.transitionOut);
}
}
if (sp.soundOut > 0 && trackSpans[i + 1]) {
r.tailSound = Math.max(r.tailSound, sp.soundOut);
ramps[i + 1].headSound = Math.max(ramps[i + 1].headSound, sp.soundOut);
}
r.soundAhead = sp.soundAhead;
r.soundBack = sp.soundBack;
});
return trackSpans
.map((sp, i) => ({ c: sp.clip, sp, ramp: ramps[i] }))
.filter(({ c }) => !c.hidden && c.start < duration)
.map(({ c, sp, ramp }) => {
const entry = {
...spanSoundSpec(sp, specFile),
file: assetById.get(c.assetId)!.fileName,
in: c.in,
out: c.out,
start: c.start,
track: c.track,
frame: c.frame,
// Pass `fit` through unset so the server's "default full-frame overlay
// covers what's below" branch fires — normalizing to "fit" defeated it.
fit: c.fit,
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,
speed: c.speed,
speedCurve: c.speedCurve,
reverse: c.reverse,
smoothSlow: c.smoothSlow,
image: assetById.get(c.assetId)!.type === "image",
grade: normalizeGrade(c.grade),
color: specColor(assetById.get(c.assetId)),
look: c.look,
lookAmount: c.lookAmount,
effects: c.effects,
effectsFrom: c.effectsFrom,
mask: undefined as SpecMask | undefined,
shadow: undefined as SpecMask | undefined,
kf: posed(c).kf,
motionBlur: c.motionBlur,
border: undefined as string | undefined,
removal: undefined as { rgb: string; alpha: string } | undefined,
...ramp,
};
overlayClipOf.set(entry, posed(cardBoxless(c)));
return entry;
});
});
// Upper-track segments render at their region box (letterboxed ones pad out
// to it when masked), so their masks paint box-sized. Subject masks ride
// the shared matte, with opacity-key luma pictures beside them.
for (let i = 0; i < overlayVideos.length; i++) {
const entry = overlayVideos[i];
const c = overlayClipOf.get(entry);
if (!c) continue;
const region = regionPx(c.frame, settings.width, settings.height);
const box = region
? { x: region.rx, y: region.ry, w: region.rw, h: region.rh }
: { x: 0, y: 0, w: settings.width, h: settings.height };
const olen = Math.max(CLIP_MIN_SECONDS, retimeOf(c).len);
const pictures = await renderClipMaskPictures(
c,
box,
settings.width,
settings.height,
olen,
settings.fps,
`mask_ov${i}`,
pngs
);
const subject = c.mask?.kind === "subject" ? subjectOf(c.mask) : undefined;
if (pictures || subject) {
entry.mask = { ...(pictures ?? {}), ...(subject ? { subject } : {}) };
}
const borderBlob = renderClipBorderPng(
c,
{ w: box.w, h: box.h },
{ x: 0, y: 0, w: box.w, h: box.h },
settings.width,
settings.height
);
if (borderBlob) {
const name = `border_ov${i}.png`;
pngs.push({ name, blob: await borderBlob });
entry.border = name;
}
entry.shadow = await renderClipShadowPictures(
c,
assetById.get(c.assetId) ?? {},
settings.width,
settings.height,
olen,
settings.fps,
`shadow_ov${i}`,
pngs,
doc.assets
);
// The keyed layer keeps its alpha over the tracks beneath, so the engine
// applies no grade or look to it — both bake into the pieces here, the
// way image overlays already carry their pixels ready-made.
const oAsset = assetById.get(c.assetId);
if (c.card && oAsset) {
const pieces = await renderCardPieces(oAsset, c, doc.assets, {
fps: settings.fps,
frameW: settings.width,
frameH: settings.height,
box: { w: box.w, h: box.h },
});
if (pieces) {
pngs.push({ name: `card_ov${i}_rgb.mp4`, blob: pieces.rgb });
pngs.push({ name: `card_ov${i}_a.mp4`, blob: pieces.alpha });
Object.assign(entry, cardEntry(`card_ov${i}`));
}
} else if (removalActive(c.removal) && oAsset) {
const pieces = await renderRemovalPieces(oAsset, c, doc.assets, {
fps: settings.fps,
maxShort: Math.min(
2160,
Math.round(Math.min(settings.width, settings.height) * clipZoom(c))
),
bakeLook: true,
});
if (pieces) {
pngs.push({ name: `removal_ov${i}_rgb.mp4`, blob: pieces.rgb });
pngs.push({ name: `removal_ov${i}_a.mp4`, blob: pieces.alpha });
entry.removal = { rgb: `removal_ov${i}_rgb.mp4`, alpha: `removal_ov${i}_a.mp4` };
entry.grade = undefined;
entry.look = undefined;
entry.effects = undefined;
}
}
}
// The library LUTs the grades name travel with the job, once per file, so
// the engine parses the same bytes the tab drew through. One that cannot
// be read fails the export here, naming it.
const lutFiles = new Map<string, string>();
for (const entry of [...clipEntries, ...overlayVideos]) {
const id = lutIdOf(entry.grade);
if (!id) continue;
let file = lutFiles.get(id);
if (!file) {
const { fileName, bytes } = await loadLibraryLutFile(id);
const ext = /\.([a-z0-9]+)$/i.exec(fileName)?.[1]?.toLowerCase() ?? "cube";
file = `lut_${id.replace(/^lut:/, "").replace(/[^a-z0-9]/gi, "")}.${ext}`;
pngs.push({ name: file, blob: new Blob([bytes as BlobPart]) });
lutFiles.set(id, file);
}
entry.color = { ...entry.color, lutFile: file };
}
const audio = doc.audioClips
.filter((a) => !a.hidden && a.start < duration && assetById.has(a.assetId))
.map((a) => ({
soundFrom: specSound(assetById.get(a.assetId)!, assetById, (x) => x.fileName),
file: assetById.get(a.assetId)!.fileName,
in: a.in,
out: a.out,
start: a.start,
volume: a.volume,
fadeIn: a.fadeIn ?? 0,
fadeOut: a.fadeOut ?? 0,
speed: a.speed,
speedCurve: a.speedCurve,
reverse: a.reverse,
sound: a.sound,
duck: a.duck,
...(a.lane ? { lane: a.lane } : {}),
}));
const overlays: {
file?: string;
start: number;
end: number;
x?: number;
y?: number;
blank?: string;
frames?: { file: string; duration: number }[];
/** The element trims by the shared person matte (invert = behind the
* speaker). */
subject?: { invert?: boolean; feather?: number };
/** Its row: lane 0 is the top of the stack, and the effects interleave
* with these by lane. */
lane?: number;
}[] = [];
// Effect elements never rasterize: they ship as time-gated filter recipes
// the server builds into the graph (the ids ride, never filter text). The
// audio ones ride the same list and treat the mix rather than the picture.
const effects = doc.overlays
.filter((o) => o.kind === "effect" && !o.hidden && o.start < duration)
.map((o) => ({
effect: (o as { effect: string }).effect,
amount: (o as { amount?: number }).amount,
focus: (o as { focus?: { x: number; y: number } }).focus,
ramp: (o as { ramp?: number }).ramp,
leak: (o as { leak?: LeakCourse }).leak,
glitch: (o as { glitch?: GlitchKind }).glitch,
tone: (o as { tone?: FlashTone }).tone,
rate: (o as { rate?: number }).rate,
rhythm: (o as { rhythm?: FlashRhythm }).rhythm,
fade: (o as { fade?: FlashFade }).fade,
fadeEase: (o as { fadeEase?: EaseId }).fadeEase,
lane: laneOf(o),
start: o.start,
end: Math.min(o.end, duration),
}));
// Every sticker the cut shows is read before any is drawn: one that cannot
// be read stops the export by name.
await requireStickers(doc.overlays.filter((o) => o.start < duration), doc.assets);
for (let i = 0; i < doc.overlays.length; i++) {
const o = doc.overlays[i];
if (o.hidden || o.start >= duration) continue;
if (o.kind === "effect") continue;
// A blank title has no pixels to burn; shapes and stickers always render.
if (isTextOverlay(o) && !o.text.trim()) continue;
// A subject-masked element's stream must run its whole window so the
// server can multiply the matte in per frame — the frames mechanism
// covers that (a static element costs one frame plus the blank).
const subject = subjectMasked(o) && o.mask ? subjectOf(o.mask) : undefined;
const subjectFields = subject ? { subject } : {};
// A Lottie sticker's pixels move on their own, so it exports as frames
// even with no transform animation set.
if (isOverlayAnimated(o) || (isStickerOverlay(o) && o.lottie) || subject) {
// Animated: a region-cropped 30fps frame sequence that the server plays
// as a concat-demuxer slideshow overlaid at the region. Presets sample
// their heads and tails and reuse the middle; a keyframed pose changes
// on its own schedule, so its whole span is sampled frame by frame.
const set = await renderElementFrames(o, settings.width, settings.height, 30, doc.assets);
const names = set.images.map((blob, j) => {
const name = `overlay_${i}_f${j}.png`;
pngs.push({ name, blob });
return name;
});
const blank = `overlay_${i}_blank.png`;
pngs.push({ name: blank, blob: set.blank });
overlays.push({
start: o.start,
end: Math.min(o.end, duration),
x: set.x,
y: set.y,
blank,
frames: set.entries.map((e) => ({ file: names[e.image], duration: e.duration })),
lane: laneOf(o),
...subjectFields,
});
continue;
}
const png = await renderStillPng(o, settings.width, settings.height, doc.assets);
const key = `overlay_${i}.png`;
pngs.push({ name: key, blob: png });
overlays.push({
file: key,
start: o.start,
end: Math.min(o.end, duration),
lane: laneOf(o),
...subjectFields,
});
}
// Subtitle stills travel in their own spec lane: the server plays each
// subtitle track as one concat-demuxer slideshow (with a transparent filler
// frame for gaps), so karaoke word windows don't each become an ffmpeg
// input. Tracks overlap each other in time, so every track (language) gets
// its own slideshow, marked by `lane`.
const captions: { file: string; start: number; end: number; lane?: number }[] = [];
if (doc.subtitles.showOnVideo) {
const capStyle = captionStyle(doc.subtitles.style);
for (let lane = 0; lane < subtitleLaneCount(doc.subtitles); lane++) {
if (laneHidden(doc.subtitles, lane)) continue;
const cues = laneCues(doc.subtitles, lane);
const pos = trackPos(doc.subtitles, capStyle, lane);
for (let i = 0; i < cues.length; i++) {
const cue = cues[i];
if (cue.start >= duration || !cue.text.trim()) continue;
// A word effect burns one frame per span its picture holds still for;
// otherwise the whole cue is a single still.
const windows = doc.subtitles.wordHighlight
? cueWordFrames(cue, capStyle, doc.subtitles)
: [{ start: cue.start, end: cue.end }];
for (let wi = 0; wi < windows.length; wi++) {
const win = windows[wi];
if (win.start >= duration) break;
const png = await renderElementPng(
cueOverlay(
cue,
capStyle,
i === 0,
pos,
doc.subtitles.wordHighlight ? (win.start + win.end) / 2 : undefined,
// Wrap in design space (1080 short side) from the project ratio —
// the same width the preview passes, whatever the render size.
frameOf(doc.aspect).w
),
settings.width,
settings.height
);
const key = windows.length > 1 ? `sub_${lane}_${i}_${wi}.png` : `sub_${lane}_${i}.png`;
pngs.push({ name: key, blob: png });
captions.push({
file: key,
start: win.start,
end: Math.min(win.end, duration),
...(lane > 0 ? { lane } : {}),
});
}
}
}
if (captions.length > 0) {
const blank = createRasterCanvas(settings.width, settings.height);
pngs.push({ name: "sub_blank.png", blob: await rasterCanvasToPng(blank) });
}
}
return {
spec: {
projectId,
target,
...settings,
...(target === "export" ? { sourceSegments: sourceExportPlan(doc, settings) ?? undefined } : {}),
...(target === "export" && settings.stems ? { stemPlan: stemsFor(doc) } : {}),
// The hover proxy, the share card and the streaming ladder are SDR web
// pictures whatever the project delivers.
colorSpace: target === "export" ? doc.colorSpace ?? "sdr" : "sdr",
lutSize: CUT_COLOR.lutSize,
lutSizeWide: CUT_COLOR.lutSizeWide,
passes: CUT_EXPORT_PASSES,
duration,
background: projectBackground(doc.background),
clips,
audio,
overlayVideos,
overlays,
captions,
...(effects.length ? { effects } : {}),
...(behindMask ? { behindMask } : {}),
},
pngs,
};
}
/**
* A cloud gate said no — the account is signed out, over its storage, or at
* its render cap. The worker would say the same, so the export ends here with
* the gate's own words.
*/
export class ExportRefusedError extends UserError {
constructor(code: string, message: string, params: UserErrorParams = {}, readonly failure?: OperationFailure) {
super(code, message, params);
}
}
const startFailed = () => new UserError("export_start_failed", "Export failed to start.");
const saveFailed = () => new UserError("export_save_failed", "Could not save the export.");
/** Concurrent PUTs a cloud export's inputs go up on. */
const UPLOAD_LANES = 4;
function cloudRefusal(res: Response, body: { error?: string; bytes?: number; quotaBytes?: number } | null | undefined): ExportRefusedError | null {
if (res.ok) return null;
const failure = operationFailure(res.status, body);
if (failure) {
return new ExportRefusedError(failure.code, failure.message, {}, failure);
}
if (res.status !== 429 && res.status !== 413) {
return null;
}
// The gate's own words keep their code; uncoded words read as they came.
const reason = errorFromBody(body, startFailed());
return reason instanceof UserError
? new ExportRefusedError(reason.code, reason.message, reason.params)
: new ExportRefusedError("export_refused", reason.message, { reason: reason.message });
}
/** Serialize a payload to the engine's multipart form: PNGs in render order,
* then the spec — the exact request shape from before the payload split. */
function exportFormFromPayload({ spec, pngs }: ExportPayload): FormData {
const form = new FormData();
for (const p of pngs) form.append(p.name, p.blob, p.name);
form.append("spec", JSON.stringify(spec));
return form;
}
/** Kick off an export on the given backend, returning the create response.
* The backend is captured when the export starts, so a job keeps rendering
* against its own backend even after the app rebinds to the other residency.
* Local: the engine's multipart form. Cloud: presign the overlay PNGs, PUT
* them straight to R2, then POST the JSON export body. */
async function postExport(
projectId: string,
payload: ExportPayload,
outName: string,
backend: CutBackend,
extra?: Record<string, unknown>,
signal?: AbortSignal
): Promise<Response> {
signal?.throwIfAborted();
if (backend.kind !== "cloud") {
return backend.fetch("/api/cut/export", { method: "POST", body: exportFormFromPayload(payload) });
}
const overlays: { name: string; key: string }[] = [];
if (payload.pngs.length > 0) {
const pre = await backend.fetch("/api/cut/export/presign", {
signal,
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
files: payload.pngs.map((p) => ({ name: p.name, bytes: p.blob.size })),
target: (payload.spec as { target?: string }).target ?? "export",
}),
});
const preBody =
await apiJson<{ files?: { name: string; key: string; type?: string; url: string }[] }>(pre);
if (!pre.ok || !preBody.files) {
throw cloudRefusal(pre, preBody) ?? errorFromBody(preBody, startFailed());
}
const byName = new Map(preBody.files.map((f) => [f.name, f]));
// The list carries a borrowed render's whole media set, so the PUTs go a
// few at a time, and a cancel stops the ones still in flight.
const queue = [...payload.pngs];
await Promise.all(
Array.from({ length: Math.min(UPLOAD_LANES, queue.length) }, async () => {
for (let p = queue.shift(); p; p = queue.shift()) {
const target = byName.get(p.name);
if (!target) {
throw startFailed();
}
// The content type the URL was signed with: it is the one the
// signature covers, and for a video it differs from the blob's.
await putSigned(target.url, p.blob, target.type || "image/png", { signal });
}
})
);
for (const p of payload.pngs) overlays.push({ name: p.name, key: byName.get(p.name)!.key });
}
signal?.throwIfAborted();
return backend.fetch("/api/cut/export", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ spec: payload.spec, overlays, projectId, outName, ...extra }),
});
}
/** The stems a cut exports as. A cut with nothing audible has none, and
* asking for them is refused before anything renders. */
function stemsFor(doc: ExportDoc): StemDef[] {
const stems = planStems(doc);
if (stems.length === 0) {
throw new ExportRefusedError("export_stems_silent", "Nothing in this cut makes a sound to split into stems.");
}
return stems;
}
/** The stems archive for an export that asks for one, rendered in this tab
* from the same mix fold as the file's sound; null when it asks for none. */
async function stemsArchive(
projectId: string,
doc: ExportDoc,
settings: ExportSettings,
signal?: AbortSignal
): Promise<RenderedExport | null> {
if (!settings.stems) return null;
return renderStemsArchive(doc, settings, stemsFor(doc), {
resolve: (asset) => renderAssetUrl(projectId, asset),
signal,
});
}
function renderAssetUrl(projectId: string, asset: MediaAsset): string {
const state = useEditor.getState();
return state.projectId === projectId
? state.assets.find((candidate) => candidate.id === asset.id)?.url ?? asset.url
: asset.url;
}
/** 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 {
return `${exportBaseName(settings.name ?? useEditor.getState().projectName)}${exportExtension(settings)}`;
}
/** Poll an export job to completion, reporting progress. Returns the file name. */
export async function pollExport(
jobId: string,
onProgress: (stage: string, ratio: number) => void,
isCanceled: () => boolean = () => false,
backend: CutBackend = getBackend()
): Promise<string> {
for (;;) {
if (isCanceled()) {
throw new UserError("export_canceled", "Export canceled.");
}
await new Promise((r) => setTimeout(r, 400));
const st = await backend.fetch(`/api/cut/export/${jobId}`);
const status = await apiJson<{
status?: string;
progress?: number;
outName?: string;
}>(st);
if (!st.ok || status.status === "error" || status.status === "canceled") {
throw errorFromBody(status, new UserError("export_failed", "Export failed."));
}
onProgress("Rendering", status.progress ?? 0);
if (status.status === "done") return status.outName ?? "export.mp4";
}
}
/** Trigger a browser download of a finished export by job id. */
export function downloadExport(jobId: string, outName: string, backend: CutBackend = getBackend()) {
downloadFile(backend.url(`/api/cut/export/${jobId}/file`), outName);
}
/** 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. */
/** Whether the cut plays a bound recording or a split edit anywhere: on a
* clip of any track that sounds, or on the soundtrack. */
function cutUsesSoundFeatures(doc: ExportDoc): boolean {
const byId = new Map(doc.assets.map((a) => [a.id, a]));
const soundtrack = doc.audioClips.some((a) => {
const asset = byId.get(a.assetId);
return !!asset && !a.hidden && soundSourceOf(asset, byId).bound;
});
if (soundtrack) return true;
const tracks = new Set(doc.clips.map((c) => c.track));
return [...tracks].some((t) => getClipSpans(doc.clips, doc.assets, t).some(spanUsesSoundFeature));
}
async function assertEngineCarries(
settings: ExportSettings,
doc: ExportDoc,
/** Who encodes the file: the engine in ffmpeg, or this tab, which only
* hands the engine the finished files. */
renderer: "engine" | "tab"
): Promise<void> {
const engineRenders = renderer === "engine";
const wants: [EngineFeature, boolean, string][] = [
// An older engine would deliver the mix unmastered and drop the stems.
["export.loudness", engineRenders && settings.loudness !== undefined, "master the loudness"],
["export.stems", !!settings.stems, "export stems"],
// An older engine plays the camera's own sound and no split edits, so a
// cut that binds a separate recording or leads/trails its sound would
// come back with the scratch track.
["export.sound", engineRenders && cutUsesSoundFeatures(doc), "play a separate sound recording or split edits"],
// The color pipeline: an engine from before it grades nothing and folds
// a log or HDR file the old way, so every export needs it.
["color.v2", true, "export this cut"],
["export.range", !!settings.range, "export a range"],
["export.name", !!settings.name, "name the file"],
// An engine that does not know the codec falls through to H.264, which
// would hand back a .mov of exactly the picture the master was chosen to
// avoid.
["export.prores4444", settings.codec === "prores4444", "export a ProRes 4444 master"],
// An engine from before HDR composites at 8 bits in BT.709 and tags the
// file so; the HLG or PQ picture would land as a wrong SDR file.
["export.hdr", (doc.colorSpace ?? "sdr") !== "sdr", "export HDR"],
];
const has = await engineFeatures();
for (const [feature, wanted, what] of wants) {
if (wanted && !has.has(feature)) {
throw new ExportRefusedError("app_update_required", `Update the Donkey app to ${what}.`, {
feature: feature.replace(".", "_"),
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
* returns the moment the job is queued and never blocks on the encode. */
export async function createExportJob(
projectId: string,
doc: ExportDoc,
settings: ExportSettings
): Promise<string> {
const backend = projectOperation(projectId).backend;
const outName = exportOutName(settings);
if (backend.kind === "local") await assertEngineCarries(settings, doc, "engine");
const payload = await buildExportPayload(projectId, doc, settings, "export");
const res = await postExport(projectId, payload, outName, backend);
const body = await apiJson<{ id?: string }>(res);
if (!res.ok || !body.id) {
throw cloudRefusal(res, body) ?? errorFromBody(body, startFailed());
}
return body.id;
}
/**
* Render the cut in this tab and store the result, returning the finished job's
* id.
*
* The worker path exists because a hosted page had no way to encode video; it
* does now. Rendering here removes the round trip a queued export costs — the
* media does not have to be pulled back out of storage into a container, and
* nothing waits behind another account's render — and the file matches the
* preview, because the same compositor drew both.
*
* Every residency: a cloud project's file goes up to storage, a browser
* project's into the tab's own store, and a Mac project's to the engine on
* this machine, which holds the job row and lands the file in the project's
* folder.
*/
export async function runBrowserExport(
projectId: string,
doc: ExportDoc,
settings: ExportSettings,
opts: {
onProgress?: (ratio: number) => void;
signal?: AbortSignal;
/** Dock-row label for a browser-resident render's tab-local job. */
projectName?: string;
/** The reserved job's id, as soon as it exists — the dock hides that row
* while this tab is the thing rendering it. */
onClaimed?: (jobId: string) => void;
} = {}
): Promise<string> {
const backend = projectOperation(projectId).backend;
if (backend.kind === "browser") return runStoreExport(projectId, doc, settings, opts);
if (backend.kind === "local") return runEngineExport(projectId, doc, settings, opts, backend);
// The name and the destination are claimed before a frame is drawn, so a
// render that is going to be refused for space or for the render cap is
// refused now rather than after minutes of work. The claim is a job row, so
// a second export started while this one renders sees it and takes the next
// name instead of overwriting this one's file.
const claim = await backend.fetch("/api/cut/export/client/presign", {
method: "POST",
headers: { "Content-Type": "application/json" },
// The size this render is heading for — the number the dialog showed —
// travels with the claim, so an account with no room for the file is told
// now rather than after the encode.
body: JSON.stringify({
projectId,
outName: exportOutName(settings),
bytes: Math.round(
estimateExportBytes(settings, deliverySpan(settings.range, projectDuration(doc)))
),
// The stems ride the same claim: their name is held with the video's,
// and the completion registers both.
...(settings.stems ? { stems: true } : {}),
}),
});
const claimed = await apiJson<{ jobId?: string; url?: string; outName?: string; type?: string; stemsUrl?: string }>(claim);
if (!claim.ok || !claimed.jobId || !claimed.url) {
throw cloudRefusal(claim, claimed) ?? errorFromBody(claimed, startFailed());
}
if (settings.stems && !claimed.stemsUrl) {
throw new UserError("cloud_stems_slot_missing", "The cloud did not hold a place for the stems.");
}
const jobId = claimed.jobId;
opts.onClaimed?.(jobId);
// The render keeps reading the project's store-served blob URLs after the
// user opens another project; the hold keeps them alive until it finishes.
holdRegistered(`/api/cut/projects/${projectId}/`);
// The claim's row hears from the tab on a timer, so the worker's stale sweep
// tells a render still drawing from a tab that closed mid-render.
let reported = 0;
const heartbeat = setInterval(
() =>
void backend
.fetch(`/api/cut/export/client/${jobId}/progress`, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ ratio: reported }),
})
.catch(() => {}),
CLIENT_HEARTBEAT_MS
);
try {
const rendered = await renderProjectToMp4(doc, settings, {
// Read the asset's URL at the moment it is needed rather than off the
// snapshot: a long render can outlive the links it started with, and the
// store re-mints them behind it.
resolve: (asset) =>
renderAssetUrl(projectId, asset),
signal: opts.signal,
// The render is nearly all of the work; the upload is the tail of the bar.
onProgress: ({ ratio }) => {
reported = ratio * 0.9;
opts.onProgress?.(reported);
},
});
try {
await putSigned(claimed.url, rendered.file, claimed.type ?? "video/mp4", {
signal: opts.signal,
onProgress: (fraction) => opts.onProgress?.(0.9 + fraction * 0.1),
});
} finally {
// The file streamed from scratch disk into the upload; its space comes
// back as soon as the upload is done with it.
void rendered.discard();
}
const stems = await stemsArchive(projectId, doc, settings, opts.signal);
if (stems) {
try {
await putSigned(claimed.stemsUrl!, stems.file, STEMS_MIME, { signal: opts.signal });
} finally {
void stems.discard();
}
}
const done = await backend.fetch("/api/cut/export/client/complete", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ jobId }),
});
const body = await apiJson<{ id?: string }>(done);
if (!done.ok || !body.id) {
throw cloudRefusal(done, body) ?? errorFromBody(body, saveFailed());
}
return body.id;
} catch (err) {
// A render that stopped — cancelled, failed, or refused — gives back the
// name it was holding. Leaving the row behind would keep the name taken and
// a render slot spent for a file that will never exist.
void backend
.fetch(`/api/cut/export/client/${jobId}/release`, { method: "POST" })
.catch(() => {});
throw err;
} finally {
clearInterval(heartbeat);
releaseRegistered(`/api/cut/projects/${projectId}/`);
}
}
/**
* A Mac-resident project's export: the same in-tab render, with the finished
* file streamed into the project's exports folder on this Mac. The engine
* holds the job row — the file's name, the dock's slot, the progress every
* other tab's dock shows — and encodes nothing: what the user watched on the
* stage is what goes into the file, drawn by the same compositor and mixed
* by the same graph.
*/
/** How often a tab render tells the engine it is still drawing. Well inside
* the engine's silence window even for a hidden tab's throttled timers. */
const CLIENT_HEARTBEAT_MS = 5000;
async function runEngineExport(
projectId: string,
doc: ExportDoc,
settings: ExportSettings,
opts: NonNullable<Parameters<typeof runBrowserExport>[3]>,
backend: CutBackend
): Promise<string> {
await assertEngineCarries(settings, doc, "tab");
const claim = await backend.fetch("/api/cut/export/client", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
projectId,
container: settings.container,
name: settings.name,
...(settings.stems ? { stems: true } : {}),
}),
});
const claimed = await apiJson<{ id?: string; outName?: string }>(claim);
if (!claim.ok || !claimed.id) {
throw errorFromBody(claimed, startFailed());
}
const jobId = claimed.id;
opts.onClaimed?.(jobId);
// The engine's feed carries the progress to every other tab's dock; a
// report every couple of percent is plenty for a bar.
let reported = 0;
const post = (ratio: number) =>
void backend
.fetch(`/api/cut/export/client/${jobId}/progress`, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ ratio }),
})
.catch(() => {});
const report = (ratio: number) => {
if (ratio - reported < 0.02 && ratio < 1) return;
reported = ratio;
post(ratio);
};
// Each report is also the engine's sign that this tab is still drawing; a
// long stretch with no new percent still says so on a timer, so a tab that
// closed mid-render is told apart from one encoding a slow stretch.
const heartbeat = setInterval(() => post(reported), CLIENT_HEARTBEAT_MS);
try {
const rendered = await renderProjectToMp4(doc, settings, {
resolve: (asset) =>
renderAssetUrl(projectId, asset),
signal: opts.signal,
// The render is nearly all of the work; the hand-in to the engine on
// this machine is the tail of the bar.
onProgress: ({ ratio }) => {
opts.onProgress?.(ratio * 0.95);
report(ratio * 0.95);
},
});
// The stems land first: the video's hand-in settles the job.
const stems = await stemsArchive(projectId, doc, settings, opts.signal);
if (stems) {
let landed: Response;
try {
landed = await backend.fetch(`/api/cut/export/client/${jobId}/stems`, {
method: "PUT",
headers: { "Content-Type": STEMS_MIME },
body: stems.file,
signal: opts.signal,
});
} finally {
void stems.discard();
}
if (landed.status === 409) throw new DOMException("Export canceled.", "AbortError");
if (!landed.ok) {
throw errorFromBody(
await apiJson<object>(landed),
new UserError("export_stems_save_failed", "Could not save the stems."),
);
}
}
let done: Response;
try {
done = await backend.fetch(`/api/cut/export/client/${jobId}/file`, {
method: "PUT",
headers: { "Content-Type": deliveryContainer(settings.container).mime },
body: rendered.file,
signal: opts.signal,
});
} finally {
// The file streamed from scratch disk into the engine's folder; its
// space comes back as soon as the hand-in is done with it.
void rendered.discard();
}
// The engine refuses a file for a job it no longer holds: the user
// canceled this render from another dock. That is their stop, and it
// ends here the way a cancel in this tab does.
if (done.status === 409) throw new DOMException("Export canceled.", "AbortError");
const body = await apiJson<{ id?: string }>(done);
if (!done.ok || !body.id) {
throw errorFromBody(body, saveFailed());
}
opts.onProgress?.(1);
return body.id;
} catch (err) {
// A render that stopped — cancelled, failed — gives back the name it was
// holding, so no row stays in the feed for a file that will never exist.
// The release lands before the store hears of the stop, so the feed the
// dock reads next is already clear of the row.
await backend
.fetch(`/api/cut/export/client/${jobId}/release`, { method: "POST" })
.catch(() => {});
throw err;
} finally {
clearInterval(heartbeat);
}
}
/** A browser-resident project's stems, rendered in this tab and shelved
* beside the video they go with. The two land together: stems that fail or
* are canceled take the saved video with them. A failure is final, since the
* cloud fallback mixes its stems in this same tab. */
async function saveStems(
projectId: string,
doc: ExportDoc,
settings: ExportSettings,
videoName: string,
signal?: AbortSignal
): Promise<void> {
if (!settings.stems) return;
holdRegistered(`/api/cut/projects/${projectId}/`);
try {
const stems = (await stemsArchive(projectId, doc, settings, signal))!;
try {
const saved = await saveExport(projectId, stems.file, stemsArchiveName(videoName));
const stored = await readFileAt(await exportsDir(projectId), saved);
if (stored) registerBlobFile(`/api/cut/projects/${projectId}/exports/${encodeURIComponent(saved)}`, stored);
} finally {
void stems.discard();
}
} catch (err) {
await dropStoredExport(projectId, videoName);
if (err instanceof DOMException && err.name === "AbortError") throw err;
if (err instanceof ExportRefusedError) throw err;
const reason = err instanceof Error ? err.message : String(err);
throw new ExportRefusedError("stems_save_failed", `The stems could not be saved: ${reason}`, { reason });
} finally {
releaseRegistered(`/api/cut/projects/${projectId}/`);
}
}
/** A browser-resident project's export: the same in-tab render, with the
* finished file written into the project's exports shelf in the browser store.
* The job is a row in the tab-local feed, so the dock tracks, cancels, and
* downloads it the way it does every other residency's. */
async function runStoreExport(
projectId: string,
doc: ExportDoc,
settings: ExportSettings,
opts: Parameters<typeof runBrowserExport>[3] = {}
): Promise<string> {
const requestedName = exportOutName(settings);
const job = reserveBrowserExportJob(projectId, opts.projectName);
opts.onClaimed?.(job.id);
holdRegistered(`/api/cut/projects/${projectId}/`);
try {
const rendered = await renderProjectToMp4(doc, settings, {
resolve: (asset) =>
renderAssetUrl(projectId, asset),
signal: opts.signal,
onProgress: ({ ratio }) => {
opts.onProgress?.(ratio);
updateBrowserExportJob(job.id, { progress: ratio });
},
});
let outName: string;
try {
outName = await saveExport(projectId, rendered.file, requestedName);
} finally {
void rendered.discard();
}
await saveStems(projectId, doc, settings, outName, opts.signal);
// Serve the finished file from the store copy: the scratch file behind the
// render is already gone, and these two paths are what the dock's download
// button and the exports shelf resolve through backend.url().
const saved = await readFileAt(await exportsDir(projectId), outName);
if (saved) {
registerBlobFile(`/api/cut/export/${job.id}/file`, saved);
registerBlobFile(
`/api/cut/projects/${projectId}/exports/${encodeURIComponent(outName)}`,
saved
);
}
updateBrowserExportJob(job.id, { status: "done", progress: 1, outName });
return job.id;
} catch (err) {
removeBrowserExportJob(job.id);
throw err;
} finally {
releaseRegistered(`/api/cut/projects/${projectId}/`);
}
}
/**
* Render a browser-resident project on the cloud worker.
*
* The tab is that project's whole machine, and when it cannot carry a render
* — no encoder for the codec, ProRes, scratch storage that gives out — the
* worker is the machine it borrows. The cut's media lives only in this
* browser, so it rides up with the job beside the overlay stills, the worker
* renders from those uploads, and the finished file comes back down into the
* project's own exports folder. The cloud keeps nothing: the uploads and the
* output are the job's scratch, gone when the job is dismissed or swept.
*/
async function renderBorrowedFile(
projectId: string,
doc: ExportDoc,
settings: ExportSettings,
target: "export" | "preview",
opts: Parameters<typeof runBrowserExport>[3] = {}
): Promise<File> {
const backend = captureCloudBackend();
const requestedName = exportOutName(settings);
let cloudJobId: string | null = null;
const stop = () => opts.signal?.throwIfAborted();
holdRegistered(`/api/cut/projects/${projectId}/`);
try {
const payload = await buildExportPayload(projectId, doc, settings, target);
stop();
for (const name of specMediaFiles(payload.spec as Parameters<typeof specMediaFiles>[0])) {
const asset = doc.assets.find((a) => a.fileName === name);
const url = asset ? renderAssetUrl(projectId, asset) : null;
const blob = url ? resolveRegisteredBlob(url) : null;
if (!blob) {
throw new UserError("export_media_not_stored", `${name} is not in this browser's storage.`, { name });
}
payload.pngs.push({ name, blob });
}
const res = await postExport(projectId, payload, requestedName, backend, { mediaFrom: "overlays" }, opts.signal);
const body = await apiJson<{ id?: string }>(res);
if (!res.ok || !body.id) {
throw cloudRefusal(res, body) ?? errorFromBody(body, new UserError("render_start_failed", "Render failed to start."));
}
cloudJobId = body.id;
opts.onClaimed?.(cloudJobId);
const outName = await pollExport(cloudJobId, (_stage, ratio) => opts.onProgress?.(ratio * 0.95), () => !!opts.signal?.aborted, backend);
stop();
const fileRes = await backend.fetch(`/api/cut/export/${cloudJobId}/file`, { signal: opts.signal });
if (!fileRes.ok) {
throw new UserError("render_fetch_failed", "Could not fetch the rendered file.");
}
const file = new File([await fileRes.blob()], outName, { type: deliveryContainer(settings.container).mime });
stop();
return file;
} finally {
if (cloudJobId) cancelExportJob(cloudJobId, backend);
releaseRegistered(`/api/cut/projects/${projectId}/`);
}
}
async function runBorrowedExport(
projectId: string,
doc: ExportDoc,
settings: ExportSettings,
opts: Parameters<typeof runBrowserExport>[3] = {}
): Promise<string> {
const job = reserveBrowserExportJob(projectId, opts.projectName);
opts.onClaimed?.(job.id);
try {
// The worker borrows only the encode the tab cannot do; the stems are
// sound, which this tab mixes itself, so they stay here.
const file = await renderBorrowedFile(projectId, doc, { ...settings, stems: undefined }, "export", {
...opts,
onProgress: (progress) => { opts.onProgress?.(progress); updateBrowserExportJob(job.id, { progress }); },
});
const saved = await saveExport(projectId, file, file.name);
await saveStems(projectId, doc, settings, saved, opts.signal);
const stored = await readFileAt(await exportsDir(projectId), saved);
if (stored) {
registerBlobFile(`/api/cut/export/${job.id}/file`, stored);
registerBlobFile(`/api/cut/projects/${projectId}/exports/${encodeURIComponent(saved)}`, stored);
}
updateBrowserExportJob(job.id, { status: "done", progress: 1, outName: saved });
return job.id;
} catch (error) {
removeBrowserExportJob(job.id);
throw error;
}
}
/** The cloud renders a browser-resident project's export when its tab
* cannot; see `runBorrowedExport`. */
export function runBrowserExportInCloud(
projectId: string,
doc: ExportDoc,
settings: ExportSettings,
opts: Parameters<typeof runBrowserExport>[3] = {}
): Promise<string> {
return runBorrowedExport(projectId, doc, settings, opts);
}
/** Cancel a running or queued export job, or retire a settled one from the
* export-jobs feed. */
export function cancelExportJob(jobId: string, backend: CutBackend = getBackend()) {
void backend.fetch(`/api/cut/export/${jobId}`, { method: "DELETE" }).catch(() => {});
}
/**
* Build the share's streaming ladder for the cut as it stands.
*
* A share plays HLS rather than a single file, so this is what makes a shared
* project watchable — see server/hlsLadder.ts for why. The render is queued and
* not waited on: it re-encodes the whole cut once per rung, so the caller
* returns immediately and the viewer's page polls for the ladder to appear.
*
* The top rung is capped at the source, so the frame size sent here is the
* ceiling on what any viewer can ever see; it renders at the doc's own size.
*
* `shareSubtitles` is what the share grants, and it decides whether captions
* are burned in at all. The doc is what the OWNER sees, so passing it through
* unfiltered would put cue text in the pixels of a stream sent to viewers whose
* share hides Subtitles — and pixels are past the point where the server's doc
* filter can take it back out.
*/
export async function renderShareLadder(
projectId: string,
doc: ExportDoc,
shareSubtitles: boolean,
backend: CutBackend = getBackend()
): Promise<boolean> {
// The master renders at "Original" — the ladder caps its top rung at this
// frame, so anything given up here is given up for every viewer. The encode
// preset is loosened because this master is an intermediate: every rung is
// re-encoded from it, so its own compression never reaches a viewer.
const settings: ExportSettings = {
...originalSettings(doc.aspect, doc.clips, doc.assets),
preset: "veryfast",
};
// Both the flag and the cues go: the flag is what the burn-in reads, and
// dropping the cues as well means no path through the pipeline can put this
// text on screen for a viewer whose share does not grant it.
const source: ExportDoc = shareSubtitles
? doc
: { ...doc, subtitles: { ...doc.subtitles, cues: [], showOnVideo: false } };
const burnedSubtitles = shareSubtitles && doc.subtitles?.showOnVideo === true;
try {
const payload = await buildExportPayload(projectId, source, settings, "hls");
return (await postExport(projectId, payload, "master.m3u8", backend, { burnedSubtitles })).ok;
} catch {
// No clips yet, or a slot was busy. The share keeps playing whatever it
// already had until a later attempt lands.
return false;
}
}
export function previewSettings(aspect: Aspect): ExportSettings {
return { ...scaledFrame(aspect, 360), fps: 24, crf: 30, preset: "veryfast", ...DELIVERY_DEFAULTS };
}
export type PreviewArtifact = { id: string; projectId: string; revision: string; url: string; expiresAt?: number };
export type PreviewJob = PreviewArtifact & { status: "queued" | "done"; statusUrl?: string };
export async function submitPreviewSnapshot(
snapshot: RenderSnapshot,
onProgress: (stage: string, ratio: number) => void = () => {},
signal?: AbortSignal
): Promise<PreviewJob> {
const { operation: { projectId, backend }, doc, revision } = snapshot;
signal?.throwIfAborted();
const settings = previewSettings(doc.aspect);
if (backend.kind === "browser") {
const directory = await projectDir(projectId);
if (!directory) {
throw new UserError("project_not_in_browser", "Project not found in browser storage.");
}
holdRegistered(`/api/cut/projects/${projectId}/`);
try {
// The hover preview is an SDR web picture whatever the project delivers.
const rendered = await canRenderInBrowser(doc, settings, "sdr")
? await renderProjectToMp4(doc, settings, {
resolve: (asset) => asset.url, signal,
onProgress: ({ ratio }) => onProgress("Rendering", ratio),
})
: {
file: await renderBorrowedFile(projectId, doc, { ...settings, name: "preview" }, "preview", {
signal, onProgress: (ratio) => onProgress("Rendering", ratio),
}),
discard: async () => {},
};
try {
signal?.throwIfAborted();
await writeFileAt(directory, "preview.mp4", rendered.file);
const file = await readFileAt(directory, "preview.mp4");
if (!file) {
throw new UserError("preview_read_failed", "Could not read the rendered preview.");
}
const url = registerBlobFile(`/api/cut/projects/${projectId}/preview`, file);
return { id: revision, projectId, revision, url, status: "done" };
} finally {
await rendered.discard();
}
} finally {
releaseRegistered(`/api/cut/projects/${projectId}/`);
}
}
const payload = await buildExportPayload(projectId, doc, settings, "preview");
signal?.throwIfAborted();
const res = await postExport(projectId, payload, "preview.mp4", backend, { revision }, signal);
const body = await apiJson<{ id?: string }>(res);
if (!res.ok || !body.id) {
throw cloudRefusal(res, body) ?? errorFromBody(body, new UserError("preview_start_failed", "Preview failed to start."));
}
if (signal?.aborted) {
cancelExportJob(body.id, backend);
signal.throwIfAborted();
}
return {
id: body.id, projectId, revision, status: "queued",
url: backend.url(`/api/cut/export/${body.id}/file`),
statusUrl: backend.url(`/api/cut/export/${body.id}`),
};
}
export async function renderPreviewSnapshot(
snapshot: RenderSnapshot,
onProgress: (stage: string, ratio: number) => void = () => {},
signal?: AbortSignal
): Promise<PreviewArtifact> {
const job = await submitPreviewSnapshot(snapshot, onProgress, signal);
if (job.status === "done") return job;
const backend = snapshot.operation.backend;
const cancel = () => cancelExportJob(job.id, backend);
signal?.addEventListener("abort", cancel, { once: true });
try {
if (signal?.aborted) cancel();
await pollExport(job.id, onProgress, () => signal?.aborted === true, backend);
if (backend.kind === "cloud") {
const response = await backend.fetch(`/api/cut/export/${job.id}`);
const body = await apiJson<{ artifact?: { url: string; expiresIn: number } }>(response);
if (!response.ok || !body.artifact) {
throw errorFromBody(body, new UserError("preview_unavailable", "Preview is unavailable."));
}
return { id: job.id, projectId: job.projectId, revision: job.revision, url: body.artifact.url,
expiresAt: Date.now() + body.artifact.expiresIn * 1000 };
}
return { id: job.id, projectId: job.projectId, revision: job.revision, url: job.url };
} finally {
signal?.removeEventListener("abort", cancel);
}
}
/** Seconds of the cut a share card shows. */
const CARD_SECONDS = 5;
/** The cut's first `seconds`, as a doc. Clips keep their trim-in and lose
* whatever hangs past the cut-off; everything starting after it drops. Used
* for the share card, which is a five-second window onto the opening rather
* than a render of the whole project. */
export function docFirstSeconds(doc: ExportDoc, seconds: number): ExportDoc {
// The trim that ends a clip at `seconds` goes back through the clip's own
// map, so a curved clip cuts at the source second really playing there.
const clampOut = <
T extends { start: number; in: number; out: number; speed?: number; speedCurve?: SpeedNode[]; reverse?: boolean },
>(
clip: T
): T => {
const rt = retimeOf(clip);
const room = seconds - clip.start;
if (rt.len <= room) return clip;
// The cut-off lands on the source second playing there: the tail of a
// reversed clip is its `in`.
return clip.reverse ? { ...clip, in: rt.srcAt(room) } : { ...clip, out: rt.srcAt(room) };
};
const starts = <T extends { start: number }>(item: T) => item.start < seconds;
return {
...doc,
clips: doc.clips.filter(starts).map(clampOut),
audioClips: doc.audioClips.filter(starts).map(clampOut),
overlays: doc.overlays
.filter(starts)
.map((o) => (o.end <= seconds ? o : { ...o, end: seconds })),
subtitles: {
...doc.subtitles,
cues: doc.subtitles.cues
.filter(starts)
.map((c) => (c.end <= seconds ? c : { ...c, end: seconds })),
},
};
}
/** Card frame size for an aspect: 16:9 sits close to the 1.91:1 social cards
* want, and portrait cuts get a tall card rather than a letterboxed wide one. */
function cardSettings(aspect: Aspect): ExportSettings {
return { ...scaledFrame(aspect, 720), fps: 15, crf: 26, preset: "veryfast", ...DELIVERY_DEFAULTS };
}
/** Render the project's link-preview card: the opening five seconds, which
* the worker turns into the still frame and the animated thumbnail a shared
* link unfurls with. Only shared projects have one, so this asks first and
* costs a single small request when the project isn't shared.
*
* Best-effort throughout — a project with no footage, an unconfigured
* backend, or a busy render slot simply keeps the card it already had. */
async function renderShareCard(projectId: string, doc: ExportDoc, backend: CutBackend, force = false): Promise<void> {
if (backend.kind !== "cloud") return;
const share = await shareSettings(projectId, backend);
if (!share) return;
const { cut, key } = sharedCut(doc, share.features?.timeline);
if (!force && key !== null && lastShareRender.get(`${projectId}:card`) === key) return;
let res: Response;
try {
const payload = await buildExportPayload(
projectId,
docFirstSeconds(cut, CARD_SECONDS),
cardSettings(cut.aspect),
"card"
);
res = await postExport(projectId, payload, "card.mp4", backend);
} catch {
return; // no clips yet
}
const body = (await res.json().catch(() => ({}))) as { id?: string };
if (!res.ok || !body.id) return;
await pollExport(body.id, () => {}, undefined, backend)
.then(() => key !== null && lastShareRender.set(`${projectId}:card`, key))
.catch(() => {});
}
type ShareRenderSettings = { features?: { subtitles?: boolean; timeline?: TimelineId } };
/** The project's share settings, or null when it is not shared. */
async function shareSettings(projectId: string, backend: CutBackend): Promise<ShareRenderSettings | null> {
const res = await backend.fetch(`/api/cut/projects/${projectId}/share`).catch(() => null);
if (!res?.ok) return null;
const body = (await res.json().catch(() => null)) as { share?: ShareRenderSettings | null } | null;
return body?.share ?? null;
}
/** The cut a share link plays: the timeline its settings name, Main by
* default, whichever one the editor has open. A parked one carries a key of
* what it draws, so editing the open timeline does not re-render a link that
* plays another; the open one renders on every change, as it always has. */
function sharedCut(doc: ExportDoc, timeline: TimelineId | undefined): { cut: ExportDoc; key: string | null } {
const { timeline: open = "main", timelines, ...cut } = doc;
const want = timeline ?? "main";
if (want === open) return { cut, key: null };
const { aspect, ...body } = parkedTimeline({ aspect: cut.aspect, timeline: open, timelines: timelines ?? {} }, want);
const parked = { ...cut, ...openedTimeline(body, doc.assets), aspect };
return { cut: parked, key: shareRenderKey(parked) };
}
/** What each share render of a parked timeline last drew, this session. */
const lastShareRender = new Map<string, string>();
const shareRenderKey = (doc: ExportDoc) =>
JSON.stringify([
doc.clips, doc.audioClips, doc.overlays, doc.subtitles, doc.aspect, doc.background, doc.colorSpace,
doc.assets.map((a) => [a.fileName, a.colorProfile, a.color, a.proxy?.fileName]),
]);
/** Rebuild the open project's share card from the cut as it stands. Fire and
* forget: the card is an accessory to the link, and a failed render leaves the
* previous one (or the generated placeholder) in place. */
export function refreshShareCard(projectId: string): void {
const s = useEditor.getState();
if (!s.loaded || s.projectId !== projectId) return;
const snapshot = captureRenderSnapshot(projectOperation(projectId), renderDoc(s));
void renderShareCard(projectId, snapshot.doc, snapshot.operation.backend, true).catch(() => {});
}
/**
* Rebuild the open project's streaming ladder from the cut as it stands.
*
* Fire and forget, like the card: a failed render leaves the previous ladder
* serving. Unlike the card, this is not cheap — it re-encodes the whole cut
* once per rung — so it belongs on the same lull the hover proxy waits for
* (the editor closing, or the tab going to the background), never on an
* interaction like opening a dialog. The server drops it for a project that
* has no share, so callers do not have to know.
*
* `shareSubtitles` decides whether captions are burned in; pass what the share
* actually grants, not what the owner is looking at.
*/
export async function refreshShareLadder(projectId: string): Promise<void> {
const s = useEditor.getState();
if (!s.loaded || s.projectId !== projectId) return;
const snapshot = captureRenderSnapshot(projectOperation(projectId), renderDoc(s));
await refreshSnapshotLadder(snapshot, true);
}
async function refreshSnapshotLadder({ operation, doc }: RenderSnapshot, force = false): Promise<void> {
const { projectId, backend } = operation;
if (backend.kind !== "cloud") return;
const share = await shareSettings(projectId, backend);
if (!share) return;
const { cut, key: drawn } = sharedCut(doc, share.features?.timeline);
const subtitles = share.features?.subtitles === true;
const key = drawn === null ? null : `${subtitles}:${drawn}`;
if (!force && key !== null && lastShareRender.get(`${projectId}:ladder`) === key) return;
// Like the open timeline's ladder, a job the worker accepted counts as drawn;
// the next change to that cut renders it again.
if ((await renderShareLadder(projectId, cut, subtitles, backend)) && key !== null)
lastShareRender.set(`${projectId}:ladder`, key);
}
/** All derived representations consume the same captured document and transport. */
export async function refreshProjectPreviews(snapshot: RenderSnapshot, signal?: AbortSignal): Promise<void> {
const { projectId, backend } = snapshot.operation;
await renderPreviewSnapshot(snapshot, undefined, signal);
await renderShareCard(projectId, snapshot.doc, backend);
await refreshSnapshotLadder(snapshot);
}