Open source CapCut alternative.
TypeScript
"use client";
import { uploadCloudLibraryMedia, withCloudPreparedMedia } from "@/cut/lib/cloudLibraryUpload";
import type { LibraryUploadStage, LibraryUploadState } from "@/cut/lib/libraryUpload";
import { assetTypeOf } from "@/cut/lib/media";
import { CUT_COLOR } from "@/cut/lib/colorSettings";
import { lutFacts, parseLutFile } from "@donkeycut/effects-kit";
import { apiJson, getBackend } from "./backend";
import { cloudBackend } from "./backend/cloud";
import { readSnapshot, writeSnapshot } from "./cache";
import { contentKey } from "./contentKey";
import { pollCloudJob } from "./cloudJob";
import { downloadFromUrl } from "./download";
import { subtreeOf } from "./folderTree";
import { normalizeLink } from "./link";
import { installFontFace } from "./fontAssets";
import { fontLabelFor } from "./fontName";
import { itemName } from "./itemName";
import { SPECIMEN_FILE_SUFFIX, specimenPng } from "./fontSpecimen";
import {
enrichAsset,
importRemote,
isFontFile,
isLutFile,
MAX_FONT_BYTES,
presignedUpload,
probeFileMeta,
registerLandedAsset,
uploadProjectMediaTo,
} from "./media";
import {
activeResidency,
availableResidencies,
backendFor,
libraryShelfKey,
listedResidencies,
type Residency,
} from "./residency";
import { probeMediaFile } from "./mediaRead";
import { storedMediaUrl } from "./mediaSync";
import { UserError, errorFromBody, replyError } from "./userError";
import { reportSwallowed } from "./report";
import { useEditor } from "./store";
import { playheadAt } from "./playhead";
import type {
AssetType,
LibraryTemplate,
MediaAsset,
TemplateMedia,
TemplateSaveInput,
} from "./types";
import { landedSoundFrom } from "./projectTemplate";
import { IMAGE_CLIP_SECONDS, isLinkedAssetType, mediaUrl } from "./types";
/** A LUT goes by its file's name. The TITLE line inside the file is whatever
* the tool that wrote it put there. */
export const lutFileName = (fileName: string) => fileName.replace(/\.[^.]+$/, "");
/** What a Library file is called wherever it is shown: a clip by the title
* read off it, anything else by its name. */
export const libraryAssetName = (a: Pick<LibraryAsset, "name" | "title">) => a.title || a.name;
export interface LibrarySource {
url: string;
title?: string;
uploader?: string;
uploadDate?: string;
}
/** What a LUT's row says about its table. */
export type LutFactsMeta = { kind: "1d" | "3d" | "shaper+3d"; size: number };
export interface LibraryAsset {
id: string;
fileName: string;
/** Uploaded source retained when playback needs conversion. */
originalFile?: string;
/** The playable copy of a master the browser cannot decode (a ProRes
* file): what the shelf's cards and viewer play. `fileName` stays the
* master, which a project copies. */
proxyFile?: string;
name: string;
type: AssetType;
duration: number;
width?: number;
height?: number;
addedAt: number;
folderId?: string | null;
source?: LibrarySource;
/** A linked item's identity — the content hash every project names it by.
* Written by the page that checked the file, so a sync of a lazy kind
* never reads the bytes back. */
contentKey?: string;
/** For a LUT, what kind of table the file holds. */
lut?: LutFactsMeta;
/** The source's own cover image, stored beside the media on the same shelf.
* An import from a site that publishes one carries it; it is what a card and
* the viewer show while the video itself loads. */
posterFile?: string;
/** How the asset entered the account from the iOS app: a phone camera
* recording (shown in Camera Roll, kept out of the Library grid) or an
* inspiration item. Cloud shelf only. */
origin?: "camera" | "inspiration";
/** A short name read off the clip itself — what is said in it and what is on
* screen — standing in for `name` wherever the asset is shown. A phone
* recording arrives named after the clock it was shot on, which tells nobody
* which clip it is; this is what the card, the viewer and the assistant read
* instead. Written once per clip by lib/clipTitle.ts. */
title?: string;
/** Which shelf this came off. Stamped on arrival — the servers each answer
* for themselves and don't know the other exists. */
residency: Residency;
}
export interface LibraryFolder {
id: string;
name: string;
/** The folder this one is filed in; null is the top level. Folders nest
* only within their own shelf. */
parentId?: string | null;
createdAt: number;
residency: Residency;
}
/** A template as the library lists it: the stored doc plus the shelf it sits
* on, so its media resolve against the right backend. */
export type LibraryTemplateItem = LibraryTemplate & { residency: Residency };
export interface LibraryData {
assets: LibraryAsset[];
folders: LibraryFolder[];
templates: LibraryTemplateItem[];
}
/** Signed edge URLs for the cloud shelf's files, minted with its listing.
*
* The route that serves a library file answers with a redirect to the same
* object, so it works — but a relative route path is not media-origin, and
* that costs every read: two connections instead of eight, no chunk cache
* (chunkCache.ts keys on the media origin), and a hop through the deployment
* ahead of each range. A 55MB phone clip dragged onto the timeline reads its
* container through that, which is the difference between a segment that
* paints frames and one that sits black. The URL a card, a ghost and an
* imported asset all read is this one, so a frame captured for any of them
* serves the others.
*
* Tokens outlive their mint by at least an hour; a URL is retired well inside
* that and the next listing mints it again. Anything unminted — a shelf listed
* before the mint answered, a file uploaded since — falls back to the route,
* which serves the same bytes. */
const MINT_TTL_MS = 30 * 60 * 1000;
const MINT_BATCH = 500;
/** A file's edge URL and the moment it was minted. Held per file rather than
* per listing: a live shelf re-reads on a timer, and re-minting everything
* each time would hand every card a new src and make the grid reload its
* thumbnails on that timer. A URL already in hand stays the same string until
* it nears expiry. */
const cloudMedia = new Map<string, { url: string; at: number }>();
/** The shelf route for a file: stable, self-healing, and the only form worth
* persisting — a ref saved in a chat thread outlives any signed URL. */
export const libraryRouteUrl = (fileName: string, residency: Residency) =>
backendFor(residency).url(
`/api/cut/library/media/${encodeURIComponent(fileName)}`,
);
/** How a live surface reads a library file: the minted edge URL while one is
* in hand, the route otherwise. */
export const libraryMediaUrl = (fileName: string, residency: Residency) => {
if (residency === "cloud") {
const hit = cloudMedia.get(fileName);
if (hit && Date.now() - hit.at < MINT_TTL_MS) return hit.url;
}
return libraryRouteUrl(fileName, residency);
};
/** The file a card or the viewer plays: the playable copy of a master the
* browser cannot decode, else the file itself. A project copies the master. */
export const libraryPlaybackUrl = (a: Pick<LibraryAsset, "fileName" | "proxyFile" | "residency">) =>
libraryMediaUrl(a.proxyFile ?? a.fileName, a.residency);
/** Mint edge URLs for everything a cloud listing names — media, covers, and
* the files templates draw from. Best-effort: a shelf reads through the route
* when this fails. */
async function mintCloudMediaUrls(shelf: LibraryData): Promise<void> {
const files = [
...new Set(
[
...shelf.assets.flatMap((a) => [a.fileName, a.posterFile, a.proxyFile]),
...shelf.templates.flatMap((t) => t.media.map((m) => m.fileName)),
].filter((f): f is string => !!f),
),
];
// Only what has no URL in hand: on a shelf that has already been listed
// that is a clip that just finished uploading, and usually nothing at all.
const now = Date.now();
const wanted = files.filter((f) => {
const hit = cloudMedia.get(f);
return !hit || now - hit.at >= MINT_TTL_MS;
});
if (!wanted.length) return;
const batches: string[][] = [];
for (let i = 0; i < wanted.length; i += MINT_BATCH) batches.push(wanted.slice(i, i + MINT_BATCH));
// The batches go out together rather than one after the next, and each
// keeps what it got: a batch that fails costs its own files the edge URL,
// and the rest of the shelf still reads from the edge.
await Promise.all(
batches.map(async (batch) => {
try {
const res = await cloudBackend.fetch("/api/cut/library/presign-get", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ files: batch }),
});
if (!res.ok) return;
const body = (await res.json()) as {
urls?: { fileName: string; url: string }[];
};
for (const u of body.urls ?? []) cloudMedia.set(u.fileName, { url: u.url, at: Date.now() });
} catch {
// The route is the fallback for these files, same as an unminted one.
}
})
);
}
/** The asset's cover image, when the import brought one back. */
export const libraryPosterUrl = (
a: Pick<LibraryAsset, "posterFile" | "residency">,
) => (a.posterFile ? libraryMediaUrl(a.posterFile, a.residency) : undefined);
/** Save a library file to the user's Downloads folder, off the shelf it sits
* on. The download goes through the route because it signs the attachment
* name; a minted edge URL is signed for inline reads only. */
export function downloadLibraryAsset(
a: Pick<LibraryAsset, "fileName" | "originalFile" | "residency">,
) {
const file = a.originalFile ?? a.fileName;
downloadFromUrl(libraryRouteUrl(file, a.residency), file);
}
async function fetchLibraryFrom(r: Residency): Promise<LibraryData> {
const res = await backendFor(r).fetch("/api/cut/library");
if (!res.ok) throw new UserError("library_load_failed", "Could not load the library.");
const data = (await res.json()) as LibraryData;
const shelf: LibraryData = {
assets: (data.assets ?? []).map((a) => ({ ...a, residency: r })),
folders: (data.folders ?? []).map((f) => ({ ...f, residency: r })),
templates: (data.templates ?? []).map((t) => ({ ...t, residency: r })),
};
// Each half is stored on its own, so one can be recalled while the other is
// re-read: that is what keeps the Mac's shelf listed with the app closed.
writeSnapshot(libraryShelfKey(r), shelf);
// Signed URLs expire, so they stay out of the snapshot and are minted with
// the live listing instead.
if (r === "cloud") await mintCloudMediaUrls(shelf).catch(() => {});
return shelf;
}
/** One shelf as this browser last saw it, for a residency it can't ask right
* now. Those files are still on that Mac; only the way to reach them is gone. */
async function rememberedLibraryFrom(
r: Residency,
): Promise<LibraryData | null> {
const hit = await readSnapshot<LibraryData>(libraryShelfKey(r));
return hit?.value ?? null;
}
/** One residency's part of a listing already on screen, standing in for a
* read of that shelf that failed. */
function heldShelf(r: Residency, held: LibraryData | undefined): LibraryData | null {
if (!held) {
return null;
}
return {
assets: held.assets.filter((a) => a.residency === r),
folders: held.folders.filter((f) => f.residency === r),
templates: held.templates.filter((t) => t.residency === r),
};
}
/**
* The whole shelf: every residency's library in one listing, newest first. A
* residency that fails keeps what `held` — the listing the caller already
* shows — lists for it, so a read that blinks never empties the page; with
* nothing held it is recalled when `remembered`, else left out. Only every
* shelf failing is an error.
*
* `remembered` widens that from what this browser can reach to what the user
* has: a shelf whose backend isn't answering is recalled from its last
* listing. The Library tab asks for it, because those items exist and the user
* is entitled to see them; the editor's library picker doesn't, because an
* item it can't copy into the project has no business in a picker.
*/
export async function fetchLibrary(opts?: {
remembered?: boolean;
held?: LibraryData;
}): Promise<LibraryData> {
const live = availableResidencies();
const rs = opts?.remembered ? listedResidencies() : live;
const parts = await Promise.all(
rs.map((r) =>
live.includes(r)
? fetchLibraryFrom(r).catch(() =>
heldShelf(r, opts?.held) ??
(opts?.remembered ? rememberedLibraryFrom(r) : null),
)
: rememberedLibraryFrom(r),
),
);
const got = parts.filter((p): p is LibraryData => p !== null);
if (got.length === 0) throw new UserError("library_load_failed", "Could not load the library.");
const byNewest = <T extends { addedAt: number }>(items: T[]) =>
[...items].sort((a, b) => b.addedAt - a.addedAt);
return {
assets: byNewest(got.flatMap((p) => p.assets)),
folders: got
.flatMap((p) => p.folders)
.sort((a, b) => a.createdAt - b.createdAt),
templates: byNewest(got.flatMap((p) => p.templates)),
};
}
/** Where an import is in its trip: waiting for a worker, pulling the media
* down, or writing it onto the shelf. The library shows it on the tile the
* import already took. */
export type ImportStage = "queued" | "downloading" | "saving";
/** The shape a link is likely to land in, before anything is known about it:
* the short-form feeds are vertical, everything else is filmed wide. The tile
* takes the real shape the moment the media lands. */
export function estimatedShape(url: string): { width: number; height: number } {
return SHORT_FORM_URL.test(url)
? { width: 9, height: 16 }
: { width: 16, height: 9 };
}
const SHORT_FORM_URL =
/^https?:\/\/[^/]*(?:youtube\.com\/shorts\/|tiktok\.com\/|instagram\.com\/(?:reels?|stories)\/)/i;
/** Import a link into a shelf. `key` is the caller's own id for this import —
* the pending card's — and rides to the cloud with the link, so a retry of
* the same card gets the job it already queued and the link lands once. */
export async function importUrlToLibrary(
url: string,
residency: Residency = activeResidency(),
onStage?: (stage: ImportStage) => void,
key?: string,
): Promise<LibraryAsset[]> {
url = normalizeLink(url);
if (residency === "browser")
return importUrlThroughCloud(url, "browser", onStage, key);
onStage?.("downloading");
const backend = backendFor(residency);
const res = await backend.fetch("/api/cut/library/import-url", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ url, ...(key ? { key } : {}) }),
});
// The engine downloads inside the request; the cloud answers {jobId} and a
// worker does the fetch, so that side waits on the job.
if (backend.kind === "cloud") {
const started = await apiJson<{ jobId?: string }>(res);
if (!res.ok || !started.jobId)
throw replyError(res.status, started, new UserError("url_import_failed", "Could not import that URL."));
const done = await pollCloudJob<{ assets?: LibraryAsset[] }>(
started.jobId,
backend,
new UserError("url_import_failed", "Could not import that URL."),
{
onState: (state) =>
onStage?.(state === "queued" ? "queued" : "downloading"),
},
);
// The library holds media, so a source that turned out to be only words
// fails here — the same line the engine's library import draws.
if (!done.assets?.length)
throw new UserError("link_no_media", "That link has no media to import.");
return done.assets.map((a) => ({ ...a, residency }));
}
const body = await apiJson<LibraryAsset[]>(res);
if (res.ok)
return (Array.isArray(body) ? body : []).map((a) => ({ ...a, residency }));
// The engine fetches with the tools it ships, and a site can refuse the
// build it happens to carry — TikTok reads the requests it impersonates with
// and answers with nothing usable. The cloud worker fetches with a different
// one, so the link gets a second chance there and the bytes come back down
// to this Mac. The engine's own reason stands if that side can't do it
// either: it is the shelf the user was importing to.
const reason = replyError(res.status, body, new UserError("url_import_failed", "Could not import that URL."));
try {
return await importUrlThroughCloud(url, residency, onStage, key);
} catch {
throw reason;
}
}
const STAGED_GONE = 404;
/**
* A link fetched by the cloud worker and landed on a shelf of this machine.
*
* Nothing in a page can pull a video off a YouTube or TikTok link, so the
* browser shelf always imports this way; the engine falls back to it when the
* fetch it runs itself comes back empty-handed. The worker stages the media in
* the account's cloud shelf, where this browser can read it, and the bytes come
* straight back down into the target shelf's own storage. The staged cloud copy
* is dropped once they land, however this ends, so an import leaves nothing
* behind on a shelf the user wasn't importing to.
*/
async function importUrlThroughCloud(
url: string,
target: Residency,
onStage?: (stage: ImportStage) => void,
key?: string,
): Promise<LibraryAsset[]> {
onStage?.("downloading");
const res = await cloudBackend.fetch("/api/cut/library/import-url", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ url, ...(key ? { key } : {}) }),
});
const started = await apiJson<{ jobId?: string }>(res);
if (!res.ok || !started.jobId)
throw replyError(res.status, started, new UserError("url_import_failed", "Could not import that URL."));
const done = await pollCloudJob<{ assets?: LibraryAsset[] }>(
started.jobId,
cloudBackend,
new UserError("url_import_failed", "Could not import that URL."),
{
onState: (state) =>
onStage?.(state === "queued" ? "queued" : "downloading"),
},
);
// The library holds media, so a source that turned out to be only words
// fails here — the same line the engine's library import draws.
if (!done.assets?.length)
throw new UserError("link_no_media", "That link has no media to import.");
const landed: LibraryAsset[] = [];
onStage?.("saving");
try {
for (const staged of done.assets) {
const bytes = await cloudBackend.fetch(
`/api/cut/library/media/${encodeURIComponent(staged.fileName)}`,
);
// A page resuming this key after its earlier run landed the media
// finds the staged copy already dropped: the shelf holds it.
if (bytes.status === STAGED_GONE && landed.length === 0) return [];
if (!bytes.ok) throw new UserError("url_import_failed", "Could not import that URL.");
const form = new FormData();
form.append("file", await bytes.blob(), staged.fileName);
form.append("name", staged.name);
if (staged.posterFile) {
const poster = await cloudBackend.fetch(
`/api/cut/library/media/${encodeURIComponent(staged.posterFile)}`,
);
if (poster.ok)
form.append("poster", await poster.blob(), staged.posterFile);
}
form.append(
"meta",
JSON.stringify({
type: staged.type,
duration: staged.duration,
width: staged.width,
height: staged.height,
}),
);
if (staged.source) form.append("source", JSON.stringify(staged.source));
const saved = await backendFor(target).fetch("/api/cut/library", {
method: "POST",
body: form,
});
const body = await apiJson<LibraryAsset>(saved);
if (!saved.ok)
throw replyError(saved.status, body, new UserError("url_import_failed", "Could not import that URL."));
landed.push({ ...body, residency: target });
}
} catch (e) {
// A part-written import is worse than none: the user reads an error and is
// left holding half a link.
for (const a of landed)
await deleteFromLibrary(target, a.id).catch(() => {});
throw e;
} finally {
for (const staged of done.assets) {
await cloudBackend
.fetch(`/api/cut/library/${staged.id}`, { method: "DELETE" })
.catch(() => {});
}
}
return landed;
}
/** Make a folder on a shelf, filed under `parentId` there (null for the
* top level). */
export async function createLibraryFolder(
name: string,
residency: Residency = activeResidency(),
parentId: string | null = null,
): Promise<LibraryFolder> {
const res = await backendFor(residency).fetch("/api/cut/library/folders", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ name, parentId }),
});
const body = await apiJson<LibraryFolder>(res);
if (!res.ok) throw errorFromBody(body, new UserError("folder_create_failed", "Could not create folder."));
return { ...body, residency };
}
/** Rename a folder, move it under another (null for the top level), or
* both. A key left out keeps what the folder has. The shelf answers with the
* folder as stored: a parent it could not honor reads back as the top level. */
export async function updateLibraryFolder(
residency: Residency,
id: string,
patch: { name?: string; parentId?: string | null },
): Promise<LibraryFolder> {
const res = await backendFor(residency).fetch(
`/api/cut/library/folders/${id}`,
{
method: "PUT",
headers: { "Content-Type": "application/json" },
body: JSON.stringify(patch),
},
);
if (!res.ok) throw new UserError("folder_update_failed", "Could not update folder.");
return { ...((await res.json()) as Omit<LibraryFolder, "residency">), residency };
}
/** What a delete of `folders` takes off the shelf: those folders and the ones
* filed under them, however deep, and the assets and templates filed in any
* of them. A camera clip lives in Camera Roll whatever folder it is filed
* under, so it stays; the shelf unfiles it. */
export function folderDeleteTakes(
data: LibraryData,
folders: readonly { id: string }[],
): { tree: Set<string>; assets: LibraryAsset[]; templates: LibraryTemplateItem[] } {
const tree = new Set(folders.flatMap((f) => subtreeOf(data.folders, f.id)));
const filed = (x: { folderId?: string | null }) => !!x.folderId && tree.has(x.folderId);
return {
tree,
assets: data.assets.filter((a) => filed(a) && a.origin !== "camera"),
templates: data.templates.filter(filed),
};
}
/** Delete a folder and everything in it: folders, items and the notes filed
* there. The cloud shelf takes its notes itself; on the others the notes go
* once the folder has, so a delete that fails leaves them in place. */
export async function deleteLibraryFolder(
residency: Residency,
id: string,
): Promise<void> {
let tree: string[] = [];
if (residency !== "cloud") {
const listing = await backendFor(residency).fetch("/api/cut/library");
if (!listing.ok) throw new UserError("folder_read_failed", "Could not read the folder.");
tree = subtreeOf((await listing.json() as LibraryData).folders, id);
}
const res = await backendFor(residency).fetch(
`/api/cut/library/folders/${id}`,
{
method: "DELETE",
},
);
if (!res.ok) throw new UserError("folder_delete_failed", "Could not delete folder.");
if (residency !== "cloud") {
const { deleteLibraryFolderNotes } = await import("@/cut/lib/notes");
await deleteLibraryFolderNotes(residency, tree);
}
}
/** File a library item — an asset or a template — into a folder on its own
* shelf (`null` ungroups). Folders don't span residencies: a cloud item can't
* move into a folder that lives on the Mac. */
export async function moveLibraryItem(
residency: Residency,
id: string,
folderId: string | null,
): Promise<void> {
const res = await backendFor(residency).fetch("/api/cut/library/move", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ id, folderId }),
});
if (!res.ok) throw new UserError("library_item_move_failed", "Could not move item.");
}
/**
* Carry a library file to another shelf, filed where it lands.
*
* A folder belongs to one shelf, so filing an item into one can mean crossing
* shelves. Neither server can see the other, so the bytes come down here and go
* back up, the item keeps its name and the link it was imported from, and the
* copy left behind comes off.
*/
export async function carryAssetTo(
asset: LibraryAsset,
to: Residency,
folderId: string | null,
): Promise<LibraryAsset> {
const res = await backendFor(asset.residency).fetch(
`/api/cut/library/media/${encodeURIComponent(asset.fileName)}`,
);
if (!res.ok) throw new UserError("library_shelf_read_failed", "Could not read that file off its shelf.");
// A font's cover is baked from its bytes on the way in, so the shelf it
// lands on draws its own — always the current sheet. A LUT has none.
const from = isLinkedAssetType(asset.type) ? undefined : libraryPosterUrl(asset);
const cover = from
? await backendFor(asset.residency)
.fetch(
`/api/cut/library/media/${encodeURIComponent(asset.posterFile!)}`,
)
.then((r) => (r.ok ? r.blob() : null))
.catch(() => null)
: null;
const landed = await uploadToLibrary(
new File([await res.blob()], asset.fileName),
to,
{
// A clip carried to another shelf keeps the name the user reads, which
// for a phone recording is the title read off the clip.
name: asset.title || asset.name,
...(asset.source ? { source: asset.source } : {}),
...(cover ? { poster: cover } : {}),
},
);
if (folderId) await moveLibraryItem(to, landed.id, folderId).catch(() => {});
await deleteFromLibrary(asset.residency, asset.id).catch(() => {});
return { ...landed, folderId };
}
/** A font is readable when the renderer can install it, so the check runs
* through the installer seam: the file that passes here is exactly the file a
* preview and a render job can draw with, and a renamed archive or a truncated
* download is refused before a byte leaves the browser. It comes back with the
* family name the font calls itself — the shelf's label and the font menu's —
* and a specimen drawn in the face it just installed, which becomes the file's
* cover, so a card never has to have the font installed to show it. */
async function checkFont(
file: File,
): Promise<{ label: string; poster: Blob | null }> {
if (file.size > MAX_FONT_BYTES) {
const limit = Math.round(MAX_FONT_BYTES / 1024 ** 2);
throw new UserError("font_too_large", `Fonts are limited to ${limit}MB.`, { limit });
}
const bytes = await file.arrayBuffer();
const family = `lf-check-${file.size}`;
try {
await installFontFace(family, bytes);
} catch {
throw new UserError("font_unreadable", "That file isn't a font Cut can read.");
}
return {
label: fontLabelFor(bytes, file.name),
poster: await specimenPng(family).catch(() => null),
};
}
/** A LUT is readable when the parser takes it, so the file is parsed once
* here — a truncated download or a renamed text file is refused before a byte
* leaves the browser. What comes back is the row's fields: the content key
* every project names it by and what kind of table it is, so a sync lists
* the shelf without reading the file again. */
async function checkLut(
file: File,
): Promise<{ label: string; meta: LinkedUploadMeta }> {
const maxBytes = CUT_COLOR.lutFileMaxBytes;
if (file.size > maxBytes) {
const limit = Math.round(maxBytes / 1024 ** 2);
throw new UserError("lut_too_large", `LUT files are limited to ${limit}MB.`, { limit });
}
const bytes = await file.arrayBuffer();
let parsed: ReturnType<typeof parseLutFile>;
try {
parsed = parseLutFile(file.name, new TextDecoder().decode(bytes));
} catch (e) {
// The parser's reason rides as a value; with none the sentence stands alone.
const reason = e instanceof Error ? e.message.trim() : "";
if (!reason) {
throw new UserError("lut_unreadable", "That file isn't a LUT Cut can read.");
}
throw new UserError("lut_unreadable_reason", `That file isn't a LUT Cut can read. ${reason}`, { reason });
}
return {
label: lutFileName(file.name),
meta: {
type: "lut",
duration: 0,
contentKey: await contentKey(bytes),
lut: lutFacts(parsed),
},
};
}
/** The row a linked upload writes in place of a probe. */
type LinkedUploadMeta = {
type: "font" | "lut";
duration: 0;
contentKey?: string;
lut?: LutFactsMeta;
};
export async function uploadToLibrary(
file: File,
residency: Residency = activeResidency(),
/** What the shelf should call it and where it came from, when the file is
* arriving from somewhere that already knows — a carry from another shelf,
* say. Left out, the file names itself and keeps whatever cover it makes. */
keep: { name?: string; source?: LibrarySource; poster?: Blob; folderId?: string | null; state?: LibraryUploadState; onStage?: (stage: LibraryUploadStage) => void } = {},
): Promise<LibraryAsset> {
const backend = backendFor(residency);
// A linked item has no streams to measure. A font is checked by installing
// it, and the check hands back the specimen the shelf keeps as its cover;
// a LUT is checked by parsing it, and the check hands back its row.
const font = isFontFile(file) ? await checkFont(file) : null;
const lut = !font && isLutFile(file) ? await checkLut(file) : null;
const linkedLabel = font?.label ?? lut?.label ?? null;
const poster = keep.poster ?? font?.poster ?? null;
const posterName = `${file.name}${SPECIMEN_FILE_SUFFIX}`;
const linkedMeta: LinkedUploadMeta | null = font
? { type: "font", duration: 0 }
: (lut?.meta ?? null);
if (residency === "cloud") {
const type = assetTypeOf(file);
const meta = linkedMeta ?? (await probeFileMeta(file).catch(() => null));
if ((!meta || !(meta.duration > 0)) && (type === "video" || type === "audio")) {
return uploadCloudLibraryMedia(file, keep);
}
if (
!meta ||
(meta.type !== "image" && !isLinkedAssetType(meta.type) && !(meta.duration > 0))
) {
throw new UserError("image_unreadable", "This image could not be read.");
}
const key = await presignedUpload(
"/api/cut/library/presign",
file,
file.name,
backend,
);
// The cover rides up as an object of its own; `complete` marks it and
// records it against the asset.
const posterKey = poster
? await presignedUpload(
"/api/cut/library/presign",
poster,
posterName,
backend,
).catch(() => null)
: null;
const res = await backend.fetch("/api/cut/library/complete", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
key,
...(posterKey ? { posterKey } : {}),
meta: {
name: keep.name ?? linkedLabel ?? file.name,
...(keep.source ? { source: keep.source } : {}),
...meta,
},
}),
});
const body = await apiJson<LibraryAsset>(res);
if (!res.ok) throw replyError(res.status, body, new UserError("upload_failed", "Upload failed."));
return { ...body, residency };
}
const form = new FormData();
form.append("file", file, file.name);
const name = keep.name ?? linkedLabel;
if (name) form.append("name", name);
if (keep.source) form.append("source", JSON.stringify(keep.source));
if (poster) form.append("poster", poster, posterName);
if (residency === "browser") {
// Hosted preparation supplies missing decoders before the page stores media.
const meta = linkedMeta ?? (await probeFileMeta(file).catch(() => null));
if (
!meta ||
(meta.type !== "image" && !isLinkedAssetType(meta.type) && !(meta.duration > 0))
) {
const type = assetTypeOf(file);
if (type === "video" || type === "audio") {
return withCloudPreparedMedia(file, async (prepared) => {
await probeFileMeta(prepared);
return uploadToLibrary(prepared, residency, { ...keep, name: keep.name ?? file.name });
}, { ...keep, folderId: undefined });
}
throw new UserError("image_unreadable", "This image could not be read.");
}
form.append("meta", JSON.stringify(meta));
} else if (linkedMeta) {
form.append("meta", JSON.stringify(linkedMeta));
} else {
const type = assetTypeOf(file);
if ((type === "video" || type === "audio") && !(await probeFileMeta(file).catch(() => null))) {
keep.onStage?.("preparing");
form.append("prepare", "true");
}
}
const res = await backend.fetch("/api/cut/library", {
method: "POST",
body: form,
});
const body = await apiJson<LibraryAsset>(res);
if (!res.ok && form.get("prepare") === "true") {
return withCloudPreparedMedia(file, async (prepared) => {
await probeFileMeta(prepared);
return uploadToLibrary(prepared, residency, { ...keep, name: keep.name ?? file.name });
}, { ...keep, folderId: undefined });
}
if (!res.ok) throw replyError(res.status, body, new UserError("upload_failed", "Upload failed."));
return { ...body, residency };
}
export async function deleteFromLibrary(residency: Residency, id: string) {
const res = await backendFor(residency).fetch(`/api/cut/library/${id}`, {
method: "DELETE",
});
if (!res.ok) throw new UserError("library_delete_failed", "Could not delete.");
}
/** Whether a library file on this shelf lands in the open project by a
* server-side copy: the project's own backend holds both ends. */
const sameShelf = (residency: Residency) => residency === getBackend().kind;
/** Land one library file in the open project and return its stored name.
*
* On the project's own shelf the server does the copy without the bytes ever
* reaching the browser. Off it — a cloud project reaching for a clip on this
* Mac, or the reverse — neither server can see the other, so the bytes come
* down here and go back up into the project. */
async function copyLibraryFileToProject(
projectId: string,
residency: Residency,
fileName: string,
assetId?: string,
opts?: { onProgress?: (fraction: number) => void; signal?: AbortSignal },
): Promise<string> {
const target = getBackend();
if (assetId && sameShelf(residency)) {
const res = await target.fetch("/api/cut/library/use", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ assetId, projectId }),
signal: opts?.signal,
});
const body = await apiJson<{ fileName?: string }>(res);
if (!res.ok || !body.fileName)
throw replyError(res.status, body, new UserError("library_add_failed", "Could not add from library."));
return body.fileName;
}
const bytes = await backendFor(residency).fetch(
`/api/cut/library/media/${encodeURIComponent(fileName)}`,
{ signal: opts?.signal },
);
if (!bytes.ok) throw new UserError("library_file_read_failed", "Could not read that library file.");
return uploadProjectMediaTo(
target,
projectId,
await bytes.blob(),
fileName,
opts,
);
}
/** Register a library asset in the open project's media, without placing it on
* the timeline. Callers choose where it lands. Usable immediately: it plays
* from the library's own route while the copy into the project runs behind
* the editor (server-side on the asset's own shelf, download-and-upload
* across residencies). */
export async function importLibraryAsset(
projectId: string,
lib: LibraryAsset,
): Promise<MediaAsset> {
if (lib.type === "font")
throw new UserError("font_not_for_timeline", "Fonts are used from the font menu, not the timeline.");
if (isLinkedAssetType(lib.type))
throw new UserError("lut_not_for_timeline", "A LUT is applied to a clip's color, from the Color panel.");
// The project's media takes the name the shelf shows, so a phone
// recording lands on the timeline under its title.
const name = lib.title || lib.name;
// A row uploaded unmeasured — a phone's camera-roll import carries no
// length or size — is read here, before the clip is cut from it, so the
// clip takes the footage's true length and the row learns it.
let { duration, width, height } = lib;
if (lib.type === "video" && !(duration > 0)) {
const probe = await probeMediaFile(libraryMediaUrl(lib.fileName, lib.residency));
duration = probe.duration;
if (probe.width && probe.height) {
width = probe.width;
height = probe.height;
}
repairLibraryAssetMeta(lib, { duration, width, height }).catch((err: unknown) =>
reportSwallowed("[cut] library meta repair failed", err, lib.fileName),
);
}
// On this Mac the engine lands the file with a clone, and it is landed
// before this returns: the asset registers at the project's own address
// and plays from there. Registered on the shelf's address first, the
// preview would open the file there, then open it again at the project's
// once the copy reported — two readers and a walk restarted on a file
// whose every keyframe is a 4K decode — while the strip and the waveform
// went on reading the shelf's copy.
if (lib.residency === "local" && sameShelf(lib.residency)) {
const fileName = await copyLibraryFileToProject(
projectId,
lib.residency,
lib.fileName,
lib.id,
);
return registerLandedAsset(projectId, {
fileName,
name,
type: lib.type,
duration,
width,
height,
});
}
return importRemote(
projectId,
{
url: libraryMediaUrl(lib.fileName, lib.residency),
name,
fileName: lib.fileName,
type: lib.type,
duration,
width,
height,
server: sameShelf(lib.residency),
},
(opts) =>
copyLibraryFileToProject(
projectId,
lib.residency,
lib.fileName,
lib.id,
opts,
),
);
}
/** Write the length and size a probe read off a file back onto the shelf row
* that was uploaded without them, so the card's time pill and the drop
* preview show the footage's real length from the next listing on. The
* browser shelf and the engine measure at ingest; only the cloud shelf takes
* unmeasured rows, from the phone. */
async function repairLibraryAssetMeta(
lib: LibraryAsset,
meta: { duration: number; width?: number; height?: number },
): Promise<void> {
if (lib.residency !== "cloud" || !(meta.duration > 0)) return;
const res = await cloudBackend.fetch(`/api/cut/library/${encodeURIComponent(lib.id)}`, {
method: "PUT",
headers: { "Content-Type": "application/json" },
body: JSON.stringify(meta),
});
if (!res.ok) throw errorFromBody(await apiJson<unknown>(res), new UserError("library_asset_update_failed", "Could not update the library asset."));
}
/** Copy a library asset into the open project and add it to the timeline at
* the playhead. */
export async function addLibraryAssetToProject(
projectId: string,
lib: LibraryAsset,
): Promise<MediaAsset> {
const asset = await importLibraryAsset(projectId, lib);
useEditor.getState().addAssetAtPlayhead(asset.id);
return asset;
}
/** Save the current timeline selection as a by-reference template. It lands on
* the project's own shelf: the server copies the media straight across. */
export async function saveTemplate(
projectId: string,
input: TemplateSaveInput,
): Promise<LibraryTemplateItem> {
const residency = activeResidency();
const res = await backendFor(residency).fetch("/api/cut/library/templates", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ projectId, ...input }),
});
const body = await apiJson<LibraryTemplate>(res);
if (!res.ok) throw replyError(res.status, body, new UserError("template_save_failed", "Could not save the template."));
return { ...body, residency };
}
/**
* Carry a template to another shelf, filed where it lands.
*
* A template's media live privately in the library, so the carry takes them
* with it: the files come down here and go up on the target shelf — presigned
* objects in the cloud, a multipart post anywhere else — and the doc arrives in
* the same order, since `layers` and `audio` point at `media` by index. The
* template left behind comes off.
*/
export async function carryTemplateTo(
t: LibraryTemplateItem,
to: Residency,
folderId: string | null,
): Promise<void> {
const source = backendFor(t.residency);
const files: File[] = [];
for (const m of t.media) {
const res = await source.fetch(
`/api/cut/library/media/${encodeURIComponent(m.fileName)}`,
);
if (!res.ok)
throw new UserError("template_media_read_failed", "Could not read that template's media off its shelf.");
files.push(new File([await res.blob()], m.fileName));
}
const input = {
name: t.name,
folderId,
duration: t.duration,
media: t.media,
layers: t.layers,
audio: t.audio,
texts: t.texts,
cues: t.cues,
...(t.transitions ? { transitions: t.transitions } : {}),
...(t.stickers ? { stickers: t.stickers } : {}),
...(t.captions ? { captions: t.captions } : {}),
...(t.project ? { project: t.project } : {}),
...(t.sound ? { sound: t.sound } : {}),
...(t.grade ? { grade: t.grade } : {}),
};
const backend = backendFor(to);
let res: Response;
if (to === "cloud") {
const keys: string[] = [];
for (const f of files) {
keys.push(
await presignedUpload("/api/cut/library/presign", f, f.name, backend),
);
}
res = await backend.fetch("/api/cut/library/templates/import", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ ...input, keys }),
});
} else {
const form = new FormData();
form.append("doc", JSON.stringify(input));
for (const f of files) form.append("file", f, f.name);
res = await backend.fetch("/api/cut/library/templates/import", {
method: "POST",
body: form,
});
}
const body = await apiJson<LibraryTemplate>(res);
if (!res.ok) throw replyError(res.status, body, new UserError("template_add_failed", "Could not add the template."));
await deleteTemplate(t.residency, t.id);
}
/** Append a project asset to a library template as one more part at its end:
* the server copies the file into the library and returns the updated
* template. Same-shelf only — the copy happens server-side, where neither
* backend can see the other's project media. */
export async function addAssetToLibraryTemplate(
projectId: string,
template: LibraryTemplateItem,
asset: MediaAsset,
): Promise<LibraryTemplateItem> {
if (template.residency !== getBackend().kind) {
throw template.residency === "cloud"
? new UserError("template_in_cloud", "That template is in the cloud; this project isn't.")
: new UserError("template_on_mac", "That template is on this Mac; this project isn't.");
}
const len = asset.type === "image" ? IMAGE_CLIP_SECONDS : asset.duration;
const part =
asset.type === "audio"
? { audio: { in: 0, out: len, volume: 1 } }
: { layer: { in: 0, out: len, muted: false, track: 1, asClip: true } };
const res = await getBackend().fetch(
`/api/cut/library/templates/${template.id}/add`,
{
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
projectId,
media: {
fileName: asset.fileName,
name: asset.name,
type: asset.type,
duration: asset.duration,
width: asset.width,
height: asset.height,
},
extend: len,
...part,
}),
},
);
const body = await apiJson<LibraryTemplate>(res);
if (!res.ok) throw replyError(res.status, body, new UserError("template_append_failed", "Could not add to the template."));
return { ...body, residency: template.residency };
}
export async function renameTemplate(
residency: Residency,
id: string,
name: string,
): Promise<void> {
const res = await backendFor(residency).fetch(
`/api/cut/library/templates/${id}`,
{
method: "PUT",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ name }),
},
);
if (!res.ok) throw new UserError("template_rename_failed", "Could not rename the template.");
}
/** Rename a Library file on its own shelf. Every kind takes the same call. */
export async function renameLibraryAsset(
residency: Residency,
id: string,
name: string,
): Promise<void> {
const res = await backendFor(residency).fetch(
`/api/cut/library/${encodeURIComponent(id)}`,
{
method: "PUT",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ name: itemName(name) }),
},
);
if (res.ok) return;
const body = await apiJson<unknown>(res);
// An engine from before renames answers the route with nothing.
if (!body.error && residency === "local" && (res.status === 404 || res.status === 405))
throw new UserError("app_update_to_rename", "Update the Donkey app to rename files on this Mac.");
throw errorFromBody(body, new UserError("file_rename_failed", "Could not rename the file."));
}
export async function deleteTemplate(
residency: Residency,
id: string,
): Promise<void> {
const res = await backendFor(residency).fetch(
`/api/cut/library/templates/${id}`,
{
method: "DELETE",
},
);
if (!res.ok) throw new UserError("template_delete_failed", "Could not delete the template.");
}
/** Land a template's media in the open project, in `template.media` order, and
* return the stored file names. On the project's own shelf one call does the
* whole copy server-side; off it each file rides through the browser. */
async function copyTemplateMediaToProject(
projectId: string,
template: LibraryTemplateItem,
): Promise<TemplateMedia[]> {
if (template.residency === getBackend().kind) {
const res = await getBackend().fetch(
`/api/cut/library/templates/${template.id}/use`,
{
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ projectId }),
},
);
const body = await apiJson<{ media?: TemplateMedia[] }>(res);
if (!res.ok || !body.media)
throw replyError(res.status, body, new UserError("template_add_failed", "Could not add the template."));
return body.media;
}
const out: TemplateMedia[] = [];
for (const m of template.media) {
const fileName = await copyLibraryFileToProject(
projectId,
template.residency,
m.fileName,
);
out.push({ ...m, fileName });
}
return out;
}
/** Copy a template's media into the open project and re-materialize its clips,
* overlays, and captions at the playhead — everything editable, nothing baked. */
export async function addTemplateToProject(
projectId: string,
template: LibraryTemplateItem,
at?: number,
): Promise<void> {
const media = await copyTemplateMediaToProject(projectId, template);
const urls = await Promise.all(media.map((m) => storedMediaUrl(projectId, m.fileName)));
const s = useEditor.getState();
// Each copied media file (in template.media order) becomes a project asset;
// the layer/audio media indices resolve against this array. Enrichment gives
// the new clips their filmstrip thumbnails and waveform peaks. A video's
// separate recording binds to the copy of it.
const assetIds = media.map(() => crypto.randomUUID().slice(0, 8));
media.forEach((m, i) => {
const soundFrom = landedSoundFrom(m, assetIds);
const asset: MediaAsset = {
id: assetIds[i],
fileName: m.fileName,
name: m.name,
type: m.type,
duration: m.duration,
width: m.width,
height: m.height,
url: urls[i],
...(soundFrom ? { soundFrom } : {}),
};
s.addAsset(asset);
void enrichAsset(asset);
});
s.insertTemplate(template, assetIds, at ?? playheadAt());
}
/** Copy a library template into the project as a project template: its media
* land in the project's media folder and the template joins the Media panel.
* Nothing is placed on the timeline. */
export async function importTemplateToProject(
projectId: string,
template: LibraryTemplateItem,
): Promise<void> {
const media = await copyTemplateMediaToProject(projectId, template);
useEditor.getState().addTemplate({
name: template.name,
duration: template.duration,
media,
layers: template.layers,
audio: template.audio,
texts: template.texts,
cues: template.cues,
...(template.transitions ? { transitions: template.transitions } : {}),
...(template.stickers ? { stickers: template.stickers } : {}),
...(template.captions ? { captions: template.captions } : {}),
...(template.project ? { project: template.project } : {}),
});
}
/** Materialize a project template onto the timeline at the playhead. Its media
* already live in the project; assets are matched by file name and re-registered
* if the Media entry was removed. */
export async function addProjectTemplateToTimeline(
projectId: string,
template: LibraryTemplate,
at?: number,
) {
const urls = await Promise.all(
template.media.map((m) =>
useEditor.getState().assets.some((a) => a.fileName === m.fileName)
? null
: storedMediaUrl(projectId, m.fileName)
)
);
const s = useEditor.getState();
// A media file still in the project plays as it stands; a re-registered
// one binds to its separate recording again.
const existing = template.media.map((m) => s.assets.find((a) => a.fileName === m.fileName));
const assetIds = existing.map((a) => a?.id ?? crypto.randomUUID().slice(0, 8));
template.media.forEach((m, i) => {
if (existing[i]) return;
const soundFrom = landedSoundFrom(m, assetIds);
const asset: MediaAsset = {
id: assetIds[i],
fileName: m.fileName,
name: m.name,
type: m.type,
duration: m.duration,
width: m.width,
height: m.height,
url: urls[i] ?? mediaUrl(projectId, m.fileName),
...(soundFrom ? { soundFrom } : {}),
};
s.addAsset(asset);
void enrichAsset(asset);
});
useEditor.getState().insertTemplate(template, assetIds, at ?? playheadAt());
}
/** Copy a project asset into the shared library for reuse. It lands on the
* project's own shelf, where the server can copy the bytes itself. */
export async function saveAssetToLibrary(
projectId: string,
asset: MediaAsset,
): Promise<LibraryAsset> {
const residency = activeResidency();
const res = await backendFor(residency).fetch("/api/cut/library/save", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
projectId,
fileName: asset.fileName,
name: asset.name,
}),
});
const body = await apiJson<LibraryAsset>(res);
if (!res.ok) throw replyError(res.status, body, new UserError("library_save_failed", "Could not save to library."));
return { ...body, residency };
}