Open source CapCut alternative.
TypeScript
// The cloud backend: hosted Cut APIs on the deployment itself, session-authed
// (same-origin cookie; no `u=` param — the server derives the account from
// the session). Routes mirror the engine's JSON shapes under /api/cut-cloud.
// Media bytes ride presigned R2 URLs minted by those routes, not this
// transport.
import { throttleWait } from "../network";
import { observeOperationResponse, operationFailure } from "../operationFailure";
import { UserError } from "../userError";
import {
DOC_SEQ_HEADER,
DOC_WRITER_HEADER,
HTTP_CONFLICT,
type CutBackend,
type CutRequestInit,
type StorageFull,
} from "./types";
const cloudPath = (path: string) => path.replace(/^\/api\/cut\//, "/api/cut-cloud/");
// A headless session's transport: an absolute origin and auth headers folded
// into every cloud call. The page binds nothing — its calls are same-origin
// and the session cookie rides on its own.
let session: { base: string; headers: Record<string, string> } | null = null;
export function bindCloudSession(base: string, headers: Record<string, string>) {
session = { base: base.replace(/\/$/, ""), headers };
sessionWriter = newWriter();
}
/** A request on the hosted site as this process's user: same-origin in the
* page, the bound session's origin and headers in a headless process. */
type CloudSession = { base: string; headers: Record<string, string> } | null;
async function requestWithSession(
bound: CloudSession,
path: string,
init?: RequestInit,
storageFull: StorageFull = "wall"
): Promise<Response> {
const headers = new Headers(bound?.headers);
new Headers(init?.headers).forEach((value, key) => headers.set(key, value));
// The firewall refuses a burst from one address before any route runs
// (site/firewall/), so the same request goes again once the window passes.
// A route that throttles answers JSON with its reason, and that stands.
for (let attempt = 1; ; attempt++) {
await firewallGate();
const res = await fetch((bound?.base ?? "") + path, { ...init, headers });
const wait = throttleWait(res);
if (wait === null || !firewallRefusal(res)) {
return observeOperationResponse(res, storageFull);
}
holdFirewall(wait);
if (attempt > FIREWALL_RETRIES || !resendable(init?.body) || init?.signal?.aborted) {
return observeOperationResponse(res, storageFull);
}
await res.body?.cancel().catch(() => {});
}
}
// How many times a request the firewall refused goes again.
const FIREWALL_RETRIES = 2;
// The firewall counts one address, so one refusal holds every cloud request
// this process sends until its window passes. Each then goes at a random
// point in a spread after it, half the window wide, so the burst that tripped
// the window does not land in the next one all at once: a 10 s window
// reopens over 10–15 s.
const FIREWALL_SPREAD = 0.5;
let firewallOpensAt = 0;
let firewallWindowMs = 0;
function holdFirewall(waitMs: number) {
const opensAt = Date.now() + waitMs;
if (opensAt <= firewallOpensAt) {
return;
}
firewallOpensAt = opensAt;
firewallWindowMs = waitMs;
}
async function firewallGate() {
const wait = firewallOpensAt - Date.now();
if (wait <= 0) {
return;
}
await new Promise((r) => setTimeout(r, wait + Math.random() * firewallWindowMs * FIREWALL_SPREAD));
}
/** Whether a throttle came from the firewall: its refusal is plain text. */
const firewallRefusal = (res: Response) => !/json/i.test(res.headers.get("content-type") ?? "");
/** Whether a request body can be sent a second time: a stream is spent once
* read, e.g. a piped upload. */
const resendable = (body: RequestInit["body"]) => !(typeof ReadableStream !== "undefined" && body instanceof ReadableStream);
export type CloudUsage = {
bytes: number;
/** null = unlimited. */
quotaBytes: number | null;
/** Present when the account's Pro ended and it holds more than the free cap:
* the sweep reclaims storage after `deadline` unless `overBytes` is freed. */
grace?: { deadline: string; overBytes: number };
};
/** The account's cloud storage usage — cloud-only by construction, so it hits
* the hosted route directly on the session cookie. */
export async function fetchCloudUsage(): Promise<CloudUsage> {
const res = await fetch("/api/cut-cloud/usage");
if (!res.ok) throw new Error(`usage ${res.status}`);
return (await res.json()) as CloudUsage;
}
export function cloudRequest(path: string, init?: RequestInit, storageFull?: StorageFull): Promise<Response> {
return requestWithSession(session, path, init, storageFull);
}
/** Capture transport credentials for work that outlives the active project. */
export function captureCloudBackend(): CutBackend {
const bound = session ? { base: session.base, headers: { ...session.headers } } : null;
const writer = newWriter();
return {
...cloudBackend,
fetch: (path, init) =>
cloudFetch(path, init, (url, options, storageFull) => requestWithSession(bound, url, options, storageFull), writer),
url: (path) => (bound?.base ?? "") + cloudPath(path),
};
}
// Cloud project docs are versioned for lost-write detection: GET hands the
// current version out in a header, PUT sends it back as ?v= and gets the
// incremented one in its body. The map lives in the transport so call sites
// keep the engine's unversioned shapes.
const docVersions = new Map<string, string>();
// Versions only grow, so the map keeps the newest it has seen. A GET response
// that lands after a save carries the version from before it — writing that
// back would make the next PUT report a conflict against this same session.
function noteVersion(projectId: string, v: string | number | undefined | null) {
if (v === undefined || v === null) return;
const next = Number(v);
const known = Number(docVersions.get(projectId));
if (!Number.isFinite(next)) return;
if (!Number.isFinite(known) || next > known) docVersions.set(projectId, String(next));
}
/** The doc version the transport last saw acknowledged for a project — what a
* dirty snapshot records as the base its edits were made on top of. */
export function knownDocVersion(projectId: string): string | null {
return docVersions.get(projectId) ?? null;
}
// A dirty snapshot resumed from disk was edited on top of a specific version.
// Its push must carry that base — not whatever version the open's own GET
// just reported — so a server copy that moved on answers 409 instead of being
// silently overwritten. The pin holds until a PUT settles (ok or conflict);
// transient failures keep it, so the retry still carries the base.
const basePins = new Map<string, string>();
export function pinDocBase(projectId: string, version: string | null) {
if (version === null) basePins.delete(projectId);
else basePins.set(projectId, version);
}
// A writer is one transport's identity on the server: the page load, a bound
// headless session, or a captured backend. Each save it sends carries the next
// number in its sequence, so a save that follows its own unacknowledged one
// (the response was lost, the save retried on the old version) applies, and a
// delayed save that its own later one overtook answers 409.
type DocWriter = { id: string; seq: number };
const newWriter = (): DocWriter => ({ id: crypto.randomUUID(), seq: 0 });
let sessionWriter = newWriter();
// One doc PUT on the wire per project: each waits for the one before it and
// reads the version at dispatch. Two saves in flight would carry the same ?v=
// and the later one would 409 against its own session's write.
const putChains = new Map<string, Promise<unknown>>();
// Doc GETs in flight, so a PUT racing the open never goes out unversioned —
// an unversioned PUT is first-save semantics and would apply unconditionally.
const docGets = new Map<string, Promise<void>>();
// /projects/:id only — /projects/folders is the folder collection, not a doc.
const PROJECT_DOC = /^\/api\/cut\/projects\/(?!folders$)([^/?]+)$/;
async function cloudFetch(
path: string,
options?: CutRequestInit,
request = cloudRequest,
writer = sessionWriter
): Promise<Response> {
const { observe, storageFull, ...init } = options ?? {};
const doc = PROJECT_DOC.exec(path);
const method = (init?.method ?? "GET").toUpperCase();
if (observe || !doc || (method !== "GET" && method !== "PUT")) return request(cloudPath(path), init, storageFull);
const projectId = decodeURIComponent(doc[1]);
if (method === "GET") {
const req = request(cloudPath(path), init);
const tracked = req.then(
(res) => {
if (res.ok) noteVersion(projectId, res.headers.get("x-cut-doc-version"));
},
() => {}
);
docGets.set(projectId, tracked);
void tracked.then(() => {
if (docGets.get(projectId) === tracked) docGets.delete(projectId);
});
return req;
}
const prev = putChains.get(projectId) ?? Promise.resolve();
const run = prev.then(() => putDoc(projectId, path, writer, init, request));
// The chain survives a failed link; the failure is the caller's to handle.
putChains.set(projectId, run.catch(() => undefined));
return run;
}
async function putDoc(
projectId: string,
path: string,
writer: DocWriter,
init?: RequestInit,
request = cloudRequest
): Promise<Response> {
await docGets.get(projectId);
// A pinned base outranks the map; with neither, an unversioned PUT is the
// first save and succeeds unconditionally.
const v = basePins.get(projectId) ?? docVersions.get(projectId);
const headers = new Headers(init?.headers);
headers.set(DOC_WRITER_HEADER, writer.id);
headers.set(DOC_SEQ_HEADER, String(++writer.seq));
const res = await request(cloudPath(path) + (v ? `?v=${encodeURIComponent(v)}` : ""), { ...init, headers });
if (res.ok || res.status === HTTP_CONFLICT) basePins.delete(projectId);
if (res.status === HTTP_CONFLICT) {
const body = (await res
.clone()
.json()
.catch(() => null)) as { doc?: unknown; version?: number | string } | null;
noteVersion(projectId, body?.version);
if (typeof window !== "undefined")
window.dispatchEvent(
new CustomEvent("cut-cloud-doc-conflict", {
detail: { projectId, doc: body?.doc, version: body?.version },
})
);
} else if (res.ok) {
const body = (await res
.clone()
.json()
.catch(() => null)) as { version?: number | string } | null;
noteVersion(projectId, body?.version);
}
return res;
}
export interface SignedMediaBatch {
/** fileName -> signed URL. */
urls: Map<string, string>;
/** Wall-clock ms when the batch's URLs stop working; null when the mint
* came back empty or without an expiry. */
expiresAt: number | null;
}
/** Batch-mint signed R2 GET URLs for a cloud or shared project's media files.
* Anything the mint misses keeps the /media route, whose 302 serves the same
* bytes. Network errors and 5xx retry with a short backoff — this runs right
* after a laptop wakes, when the link may still be coming up. Dispatches
* through the active backend so the shared driver's token prefix applies;
* lazy import because ./index imports this module. */
export async function fetchSignedMediaUrls(
projectId: string,
fileNames: string[]
): Promise<SignedMediaBatch> {
const out: SignedMediaBatch = { urls: new Map(), expiresAt: null };
if (fileNames.length === 0) return out;
const { apiFetch } = await import("./index");
for (let attempt = 0; attempt < 3; attempt++) {
if (attempt > 0) await new Promise((r) => setTimeout(r, 500 * 2 ** (attempt - 1)));
try {
const res = await apiFetch("/api/cut/media/presign-get", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ items: fileNames.map((fileName) => ({ projectId, fileName })) }),
});
if (res.status >= 500) continue;
if (!res.ok) return out; // 4xx: the route fallback still streams
const body = (await res.json()) as {
urls?: { fileName: string; url: string }[];
expiresIn?: number;
};
for (const u of body.urls ?? []) out.urls.set(u.fileName, u.url);
if (out.urls.size > 0 && typeof body.expiresIn === "number") {
out.expiresAt = Date.now() + body.expiresIn * 1000;
}
return out;
} catch {
// Network down — retry; signed URLs stay an optimization either way.
}
}
return out;
}
type QuotaBody = { error?: string; bytes?: number; quotaBytes?: number } | null | undefined;
/** The storage wall a reply is, coded so the page words it; null for any
* other reply. The host decides how a quota failure is presented.
*
* throw quotaError(res.status, body) ?? errorFromBody(body, new UserError("upload_failed", "Upload failed."));
*/
export function quotaError(status: number, body: QuotaBody): UserError | null {
const failure = operationFailure(status, body);
return failure?.code === "storage_quota_exceeded" ? new UserError(failure.code, failure.message) : null;
}
export const cloudBackend: CutBackend = {
kind: "cloud",
caps: {
importUrl: true, // executed by the render worker
liveMic: true, // hosted LLM STT (lib/cloudTranscribe.ts)
transcribe: true, // hosted LLM STT (lib/cloudTranscribe.ts)
captionAi: true, // hosted Gemini twin (server/cloud/captions.ts)
revealInFinder: false,
watch: true, // browser seek + canvas contact sheets (lib/media.ts)
},
fetch: (path, init) => cloudFetch(path, init),
url: (path) => cloudPath(path),
};