Open source CapCut alternative.
TypeScript
import { sanitizeGuideLines, sanitizeGuides } from "@/cut/lib/guides";
import { execFile } from "node:child_process";
import { compatCoverIn, compatProxyNameFor } from "@/cut/lib/proxyNames";
import { OUTPUT_SPACES } from "@donkeycut/effects-kit";
import { isTimelineId, normalizeAspect, sanitizeTimelines, type ProjectDoc } from "@/cut/lib/types";
import { detectSilence, extractAudio, makeFreezeFrame, probeDims, probeDuration } from "../frames";
import {
createProject,
createProjectFolder,
deleteExport,
deleteMedia,
deleteProject,
deleteProjectFolder,
duplicateProject,
exportPath,
listExports,
listProjectFolders,
listProjects,
mediaPath,
moveProjectToFolder,
previewPath,
readProject,
projectFileRevision,
updateProjectFolder,
saveMedia,
sweepOrphanMedia,
writeProject,
} from "../projects";
import { convertToMp4, mp4NameFor } from "../convert";
import { convertModeIn } from "@/cut/lib/convertMode";
import { requestedLocale } from "@/cut/lib/defaultNames";
import { makeCompatProxy, makeProxy, proxyNameFor } from "../proxy";
import { serveFileRange, wantsDownload } from "../serveFile";
import { importUrlToProject } from "../urlImport";
import { createTranscribeJob, getTranscribeJob, type TranscribeSpec } from "../transcribe";
import { UserError } from "../../lib/userError";
import { exists, uniqueName, errorReply } from "../util";
const err = (failure: string | UserError, status: number) => Response.json(errorReply(failure, ""), { status });
const caught = (e: unknown, fallback: string | UserError, status = 500) =>
Response.json(errorReply(e, fallback), { status });
// The reply for an id with no project behind it, coded so the page words it.
const PROJECT_NOT_FOUND = new UserError("project_not_found", "Project not found.");
const clamp = (v: number, lo: number, hi: number) => Math.max(lo, Math.min(hi, v));
/** Project CRUD, media, exports, transcription, freeze-frames. */
export const projectsApi = {
async list() {
return Response.json(await listProjects());
},
async folders() {
return Response.json(await listProjectFolders());
},
async createFolder(req: Request) {
try {
const { name, parentId } = (await req.json()) as { name?: string; parentId?: string | null };
return Response.json(await createProjectFolder(name ?? "", parentId ?? null));
} catch (e) {
return caught(e, new UserError("folder_create_failed", "Could not create folder."));
}
},
/** Rename a folder, move it under another, or both. */
async updateFolder(req: Request, { id }: { id: string }) {
try {
const { name, parentId } = (await req.json()) as { name?: string; parentId?: string | null };
return Response.json(await updateProjectFolder(id, { name, parentId }));
} catch (e) {
return caught(e, new UserError("folder_update_failed", "Could not update folder."));
}
},
async deleteFolder(_req: Request, { id }: { id: string }) {
try {
await deleteProjectFolder(id);
return Response.json({ ok: true });
} catch (e) {
return caught(e, new UserError("folder_delete_failed", "Could not delete folder."));
}
},
/** File a project under a folder (or `null` to ungroup). */
async move(req: Request, { id }: { id: string }) {
try {
const { folderId } = (await req.json()) as { folderId: string | null };
await moveProjectToFolder(id, folderId ?? null);
return Response.json({ ok: true });
} catch (e) {
return caught(e, new UserError("project_move_failed", "Could not move project."));
}
},
async create(req: Request) {
try {
const { name, folderId, aspect, locale } = (await req.json()) as {
name?: string;
folderId?: string | null;
aspect?: string;
locale?: string;
};
return Response.json(
await createProject(name ?? "", folderId ?? null, normalizeAspect(aspect), requestedLocale(locale))
);
} catch (e) {
return caught(e, new UserError("project_create_failed", "Could not create project."));
}
},
async get(req: Request, { id }: { id: string }) {
const revision = await projectFileRevision(id);
if (!revision) return err(PROJECT_NOT_FOUND, 404);
const headers = { "x-cut-doc-version": revision };
if (req.method === "HEAD") return new Response(null, { headers });
const doc = await readProject(id).catch(() => null);
if (!doc) return err(PROJECT_NOT_FOUND, 404);
void sweepOrphanMedia(id, doc).catch(() => {});
return Response.json(doc, { headers });
},
async put(req: Request, { id }: { id: string }) {
try {
const existing = await readProject(id);
if (!existing) return err(PROJECT_NOT_FOUND, 404);
const body = (await req.json()) as Partial<ProjectDoc>;
const doc: ProjectDoc = {
...existing,
name: typeof body.name === "string" && body.name.trim() ? body.name.trim() : existing.name,
assets: Array.isArray(body.assets) ? body.assets : existing.assets,
clips: Array.isArray(body.clips) ? body.clips : existing.clips,
transitions: Array.isArray(body.transitions) ? body.transitions : existing.transitions,
audioClips: Array.isArray(body.audioClips) ? body.audioClips : existing.audioClips,
// Layer clips now live in `clips` (each with its `track`). A merged
// client saves `clips` with no `overlayClips`, which clears the legacy
// array so the two shapes can't drift or duplicate. A pre-merge client
// still sends both — its `overlayClips` are real layer data, so they
// persist untouched rather than being silently deleted.
overlayClips: Array.isArray(body.overlayClips)
? body.overlayClips
: Array.isArray(body.clips)
? []
: existing.overlayClips,
overlays: Array.isArray(body.overlays) ? body.overlays : existing.overlays,
timeline: isTimelineId(body.timeline) ? body.timeline : existing.timeline,
timelines: sanitizeTimelines(body.timelines, existing) ?? existing.timelines,
templates: Array.isArray(body.templates) ? body.templates : existing.templates,
mediaFolders: Array.isArray(body.mediaFolders) ? body.mediaFolders : existing.mediaFolders,
aspect: normalizeAspect(body.aspect) ?? existing.aspect,
guides: Array.isArray(body.guides) ? sanitizeGuides(body.guides) : existing.guides,
guideLines: body.guideLines !== undefined ? sanitizeGuideLines(body.guideLines) : existing.guideLines,
background: typeof body.background === "string" ? body.background : existing.background,
colorSpace: OUTPUT_SPACES.some((o) => o.id === body.colorSpace) ? body.colorSpace : existing.colorSpace,
magnet: typeof body.magnet === "boolean" ? body.magnet : existing.magnet,
subtitles:
body.subtitles && typeof body.subtitles === "object"
? body.subtitles
: existing.subtitles,
// Per-project view metadata (timeline zoom, …) — not part of the cut.
ui:
body.ui && typeof body.ui === "object" ? { ...existing.ui, ...body.ui } : existing.ui,
publish:
body.publish && typeof body.publish === "object"
? { ...existing.publish, ...body.publish }
: existing.publish,
notes:
body.notes && typeof body.notes === "object"
? { ...existing.notes, ...body.notes }
: existing.notes,
// Brief-to-video run state. Persisted verbatim; a client that omits the
// key keeps the existing plan, and null clears it (a dismissed plan) —
// normalized to undefined so the doc at rest never stores null.
genvideo: body.genvideo !== undefined ? body.genvideo ?? undefined : existing.genvideo,
renders: Array.isArray(body.renders) ? body.renders : existing.renders,
};
const revision = await writeProject(id, doc);
return Response.json({ ok: true, updatedAt: doc.updatedAt, revision });
} catch (e) {
return caught(e, new UserError("project_save_failed", "Could not save project."));
}
},
async remove(_req: Request, { id }: { id: string }) {
try {
await deleteProject(id);
return Response.json({ ok: true });
} catch (e) {
return caught(e, new UserError("project_delete_failed", "Could not delete project."));
}
},
/** Duplicate a project (doc + media) into a fresh one. */
async duplicate(req: Request, { id }: { id: string }) {
try {
// The copy is named in its creator's language; an older page sends no body.
const { locale } = ((await req.json().catch(() => null)) ?? {}) as { locale?: string };
return Response.json(await duplicateProject(id, requestedLocale(locale)));
} catch (e) {
return caught(e, new UserError("project_duplicate_error", "Could not duplicate project."));
}
},
/** The low-res proxy of the edit, played on the project card's hover. */
async servePreview(req: Request, { id }: { id: string }) {
let p: string;
try {
p = previewPath(id);
} catch {
return new Response("Bad request.", { status: 400 });
}
return serveFileRange(p, req, { contentType: "video/mp4" });
},
/** Download a media URL straight into the project's media folder. */
async importUrl(req: Request, { id }: { id: string }) {
try {
const { url, audio } = (await req.json()) as { url?: string; audio?: boolean };
if (!url) return err("No URL provided.", 400);
return Response.json(await importUrlToProject(id, url, { audio: audio === true }));
} catch (e) {
return caught(e, new UserError("url_import_failed", "Could not import that URL."));
}
},
async uploadMedia(req: Request, { id }: { id: string }) {
try {
if (!(await readProject(id))) return err(PROJECT_NOT_FOUND, 404);
const form = await req.formData();
const file = form.get("file");
if (!(file instanceof File)) return err("No file in upload.", 400);
const fileName = await saveMedia(id, file);
return Response.json({ fileName });
} catch (e) {
return caught(e, new UserError("upload_failed", "Upload failed."));
}
},
/** Delete a media file — called when its last referencing asset is removed. */
async removeMedia(_req: Request, { id, file }: { id: string; file: string }) {
try {
await deleteMedia(id, decodeURIComponent(file));
return Response.json({ ok: true });
} catch (e) {
return caught(e, new UserError("media_delete_failed", "Could not delete the media file."));
}
},
/** Reveal a media file in Finder (Cut runs on the user's own Mac). */
async revealMedia(_req: Request, { id, file }: { id: string; file: string }) {
let p: string;
try {
p = mediaPath(id, decodeURIComponent(file));
} catch {
return err("Bad request.", 400);
}
if (!(await exists(p))) return err(new UserError("media_file_not_found", "Media file not found."), 404);
try {
await new Promise<void>((resolve, reject) =>
execFile("open", ["-R", p], (e) => (e ? reject(e) : resolve()))
);
return Response.json({ ok: true });
} catch (e) {
return caught(e, new UserError("file_reveal_failed", "Could not reveal the file."));
}
},
/** Raw media file with Range support so <video>/<audio> can seek. */
async serveMedia(req: Request, { id, file }: { id: string; file: string }) {
let p: string;
let name: string;
try {
name = decodeURIComponent(file);
p = mediaPath(id, name);
} catch {
return new Response("Bad request.", { status: 400 });
}
return serveFileRange(p, req, wantsDownload(req) ? { downloadName: name } : {});
},
/** Rendered exports for a project, newest first. */
async listExports(_req: Request, { id }: { id: string }) {
try {
return Response.json(await listExports(id));
} catch {
return err("Invalid project.", 400);
}
},
/** A rendered export with Range support so the preview player can seek. */
async serveExport(req: Request, { id, file }: { id: string; file: string }) {
let p: string;
let name: string;
try {
name = decodeURIComponent(file);
p = exportPath(id, name);
} catch {
return new Response("Bad request.", { status: 400 });
}
// The type follows the name: an MP4 or a MOV, whichever the export wrote.
return serveFileRange(p, req, wantsDownload(req) ? { downloadName: name } : {});
},
/** Reveal a rendered export in Finder (Cut runs on the user's own Mac). */
async revealExport(_req: Request, { id, file }: { id: string; file: string }) {
let p: string;
try {
p = exportPath(id, decodeURIComponent(file));
} catch {
return err("Bad request.", 400);
}
if (!(await exists(p))) return err(new UserError("export_not_found", "Export not found."), 404);
try {
await new Promise<void>((resolve, reject) =>
execFile("open", ["-R", p], (e) => (e ? reject(e) : resolve()))
);
return Response.json({ ok: true });
} catch (e) {
return caught(e, new UserError("file_reveal_failed", "Could not reveal the file."));
}
},
/** Delete a rendered export from the project folder. */
async removeExport(_req: Request, { id, file }: { id: string; file: string }) {
try {
await deleteExport(id, decodeURIComponent(file));
return Response.json({ ok: true });
} catch (e) {
return caught(e, new UserError("export_delete_failed", "Could not delete the export."));
}
},
/** Start a background transcription of the current cut. */
async transcribeStart(req: Request, { id }: { id: string }) {
try {
const body = (await req.json()) as Omit<TranscribeSpec, "projectId">;
if (
!Array.isArray(body.clips) ||
!Array.isArray(body.audio) ||
typeof body.duration !== "number"
) {
return err("Bad transcribe spec.", 400);
}
const job = await createTranscribeJob({ ...body, projectId: id });
return Response.json({ id: job.id });
} catch (e) {
return caught(e, String(e));
}
},
/** Poll a transcription job: ?job=<id> */
async transcribePoll(req: Request, { id }: { id: string }) {
const jobId = new URL(req.url).searchParams.get("job");
const job = jobId ? getTranscribeJob(jobId) : undefined;
if (!job || job.projectId !== id) return err(new UserError("transcribe_job_unknown", "Unknown transcription job."), 404);
return Response.json({
status: job.status,
stage: job.stage,
error: job.error,
errorCode: job.errorCode,
errorParams: job.errorParams,
cues: job.status === "done" ? job.cues : undefined,
});
},
/** Store an uploaded image as a first-class image asset at native
* resolution — no video baking. AI generations and stock tiles land here. */
async importImage(req: Request, { id }: { id: string }) {
try {
if (!(await readProject(id))) return err(PROJECT_NOT_FOUND, 404);
const form = await req.formData();
const file = form.get("file");
if (!(file instanceof File)) return err("No image in upload.", 400);
const nameField = form.get("name");
const name = typeof nameField === "string" && nameField.trim() ? nameField.trim() : file.name;
const raw = form.get("origin");
const origin = raw === "generated" || raw === "sticker" ? raw : undefined;
const fileName = await saveMedia(id, file);
const dims = await probeDims(mediaPath(id, fileName));
return Response.json({
id: crypto.randomUUID().slice(0, 8),
type: "image",
name,
fileName,
duration: 0,
width: dims.width,
height: dims.height,
...(origin ? { origin } : {}),
});
} catch (e) {
return caught(e, new UserError("image_import_failed", "Could not import the image."));
}
},
/** Render a freeze-frame still clip from a media file's frame. */
async freeze(req: Request, { id }: { id: string }) {
try {
if (!(await readProject(id))) return err(PROJECT_NOT_FOUND, 404);
const body = (await req.json()) as {
file?: string;
srcTime?: number;
duration?: number;
frame?: { w?: number; h?: number };
framing?: {
fit?: "fit" | "fill";
zoom?: number;
panX?: number;
panY?: number;
flipH?: boolean;
flipV?: boolean;
};
};
if (!body.file || typeof body.srcTime !== "number") {
return err("file and srcTime are required.", 400);
}
const frame =
typeof body.frame?.w === "number" && typeof body.frame?.h === "number"
? { w: Math.round(body.frame.w), h: Math.round(body.frame.h) }
: undefined;
const framing = frame
? {
fit: body.framing?.fit === "fill" ? ("fill" as const) : ("fit" as const),
zoom: typeof body.framing?.zoom === "number" ? body.framing.zoom : 1,
panX: typeof body.framing?.panX === "number" ? body.framing.panX : 0,
panY: typeof body.framing?.panY === "number" ? body.framing.panY : 0,
flipH: body.framing?.flipH === true,
flipV: body.framing?.flipV === true,
}
: undefined;
const made = await makeFreezeFrame(id, body.file, body.srcTime, body.duration ?? 1, frame, framing);
return Response.json({
id: crypto.randomUUID().slice(0, 8),
fileName: made.fileName,
name: made.fileName,
type: "video",
duration: made.duration,
width: made.width,
height: made.height,
});
} catch (e) {
return caught(e, String(e));
}
},
/** Convert a media file in this project to MP4 (H.264/AAC), remuxing when
* the streams already fit. The new file lands beside the original; swapping
* the asset over to it and dropping the old bytes is the client's call. */
async convert(req: Request, { id }: { id: string }) {
try {
if (!(await readProject(id))) return err(PROJECT_NOT_FOUND, 404);
const body = (await req.json()) as { file?: string; maxHeight?: number; mode?: unknown };
if (!body.file) return err("file is required.", 400);
const mode = convertModeIn(body.mode);
if (!mode) return err("mode is fit or reencode.", 400);
const src = mediaPath(id, body.file);
if (!(await exists(src))) return err(new UserError("media_file_missing", "Media file missing from project."), 404);
const fileName = await uniqueName(mp4NameFor(body.file), (n) => mediaPath(id, n));
const outPath = mediaPath(id, fileName);
const handle = { tmpDir: "", outPath, progress: 0, log: [] as string[] };
const outcome = await convertToMp4(handle, src, outPath, {
maxHeight: typeof body.maxHeight === "number" ? body.maxHeight : undefined,
mode,
});
// Nothing was written for a file that already fits; the project keeps
// the one it has.
const made = outcome.unchanged ? { file: body.file, path: src } : { file: fileName, path: outPath };
return Response.json({
fileName: made.file,
duration: await probeDuration(made.path),
...outcome,
});
} catch (e) {
return caught(e, new UserError("convert_failed", "Could not convert that file."));
}
},
/** Build the preview proxy of a ProRes master in this project (see
* server/proxy.ts). The proxy lands beside the master; writing it onto the
* asset is the client's call. The page sends the size and quality it was
* configured with, and `compat` for a browser that cannot decode one of
* the master's streams (lib/proxyNames.ts). */
async proxy(req: Request, { id }: { id: string }) {
try {
if (!(await readProject(id))) return err(PROJECT_NOT_FOUND, 404);
const body = (await req.json()) as { file?: string; maxHeight?: number; crf?: number; compat?: unknown };
if (!body.file) return err("file is required.", 400);
if (typeof body.maxHeight !== "number" || typeof body.crf !== "number") return err("maxHeight and crf are required.", 400);
const compat = compatCoverIn(body.compat);
if (body.compat !== undefined && !compat) return err("compat is audio or video.", 400);
const src = mediaPath(id, body.file);
if (!(await exists(src))) return err(new UserError("media_file_missing", "Media file missing from project."), 404);
const fileName = await uniqueName(compat ? compatProxyNameFor(body.file, compat, false) : proxyNameFor(body.file), (n) => mediaPath(id, n));
const outPath = mediaPath(id, fileName);
const handle = { tmpDir: "", outPath, progress: 0, log: [] as string[] };
const opts = { maxHeight: body.maxHeight, crf: body.crf };
const outcome = compat ? await makeCompatProxy(handle, src, outPath, { ...opts, cover: compat }) : await makeProxy(handle, src, outPath, opts);
return Response.json({ fileName, ...outcome });
} catch (e) {
return caught(e, new UserError("proxy_failed", "Could not make the preview proxy."));
}
},
/** Report silent stretches in a media file's audio. */
async silence(req: Request, { id }: { id: string }) {
try {
if (!(await readProject(id))) return err("Project not found.", 404);
const body = (await req.json()) as {
file?: string;
from?: number;
to?: number;
threshold_db?: number;
min_silence?: number;
};
if (!body.file) return err("file is required.", 400);
const from = Math.max(0, typeof body.from === "number" ? body.from : 0);
const to = typeof body.to === "number" ? body.to : await probeDuration(mediaPath(id, body.file));
if (typeof body.to !== "number" && to <= 0)
return err("Could not read the media duration — pass to (seconds).", 400);
if (!(to > from)) return err("from/to describe an empty range.", 400);
const thresholdDb = clamp(typeof body.threshold_db === "number" ? body.threshold_db : -30, -90, 0);
const minSilence = clamp(typeof body.min_silence === "number" ? body.min_silence : 0.35, 0.05, 10);
const silences = await detectSilence(id, body.file, { from, to, thresholdDb, minSilence });
return Response.json({ silences, from, to });
} catch (e) {
return caught(e, "Could not scan for silence.");
}
},
/** Extract a media file's audio track so the assistant can hear it (video and
* audio alike). Returns raw AAC bytes; the caller inlines them for the model. */
async audio(req: Request, { id }: { id: string }) {
try {
if (!(await readProject(id))) return err("Project not found.", 404);
const body = (await req.json()) as { file?: string; from?: number; to?: number };
if (!body.file) return err("file is required.", 400);
const from = Math.max(0, typeof body.from === "number" ? body.from : 0);
const to = typeof body.to === "number" ? body.to : undefined;
if (to !== undefined && !(to > from)) return err("from/to describe an empty range.", 400);
const audio = await extractAudio(id, body.file, { from, to });
return new Response(new Uint8Array(audio), {
headers: { "Content-Type": "audio/aac", "Content-Length": String(audio.length) },
});
} catch (e) {
return caught(e, "Could not read the audio.");
}
},
};