Open source CapCut alternative.
TypeScript
import { createHash, randomBytes, randomInt, timingSafeEqual } from "node:crypto";
import { copyFile, mkdir, readdir, readFile, rename, rm, stat } from "node:fs/promises";
import os from "node:os";
import path from "node:path";
import { cutDataRoot } from "./dataDir";
import { assertLocalRuntime } from "./local-only";
import { mediaDir, mediaPath } from "./projects";
import { exists, uniqueName, writeJsonAtomic } from "./util";
/**
* The phone link: clips shot on an iPhone in the field, handed to this Mac over
* peer-to-peer Wi-Fi and held here until the editor takes them.
*
* The engine owns both halves of it. Pairing is a code the settings page mints
* and the phone answers with, which buys the phone a token it keeps; every clip
* after that arrives carrying the token. The app's listener is a pipe — it
* terminates the peer connection and forwards here, so the only place a device
* or a pending clip is written down is this Mac's disk.
*
* The inbox is a staging area, not storage: a clip sits in it until an open
* editor claims it into a project, wherever that project lives. That indirection
* is what lets a browser-resident project receive from a phone at all — the page
* pulls the bytes off loopback and writes them into its own OPFS.
*
* Two editors can be open on one Mac, so taking a clip is a claim rather than a
* read: the claim renames the record, which the filesystem performs for exactly
* one caller, and the loser finds nothing to rename. A claim that is never
* finished — the tab closed mid-import — lapses back into the inbox.
*/
const phoneRoot = () => path.join(cutDataRoot(), "phone");
const devicesPath = () => path.join(phoneRoot(), "devices.json");
const inboxRoot = () => path.join(phoneRoot(), "inbox");
const clipMetaPath = (id: string) => path.join(inboxRoot(), `${id}.json`);
/** A claimed clip's record, under a name a second claim cannot find. */
const claimedMetaPath = (id: string) => path.join(inboxRoot(), `${id}.claimed.json`);
/** A phone that has paired with this Mac. The token never lands on disk — only
* its hash, so a readable devices.json is not a credential. */
export interface PhoneDevice {
id: string;
name: string;
tokenHash: string;
pairedAt: number;
lastSeenAt: number;
}
/** A device as anything outside this module sees it. */
export type PhoneDeviceInfo = Omit<PhoneDevice, "tokenHash">;
/** A clip waiting in the inbox for an editor to claim it. */
export interface PhoneClip {
id: string;
/** The take's id on the phone, stable across re-sends. A phone that loses an
* acknowledgement sends the take again; this is how the second arrival is
* recognised as the copy already here. */
takeId: string;
deviceId: string;
deviceName: string;
/** The name the file takes when it lands in a project. */
fileName: string;
bytes: number;
/** When the phone shot it, by the phone's clock. */
capturedAt: number;
receivedAt: number;
durationSeconds?: number;
width?: number;
height?: number;
/** When an editor claimed it. Only on a claimed record. */
claimedAt?: number;
}
const hashToken = (token: string) => createHash("sha256").update(token).digest("hex");
/** Constant-time compare of two hex digests of equal length. */
function sameHash(a: string, b: string): boolean {
if (a.length !== b.length) return false;
return timingSafeEqual(Buffer.from(a, "hex"), Buffer.from(b, "hex"));
}
// MARK: Devices
/**
* Every change to the device list runs through here, one at a time.
*
* The list is read, changed and written back with awaits in between, so two of
* those interleaved would each write a list built before the other's change: an
* upload touching its device's last-seen stamp would put back a device the user
* had just unpaired, and the revoked token would keep working.
*/
let deviceWrites: Promise<unknown> = Promise.resolve();
function withDeviceList<T>(work: (devices: PhoneDevice[]) => Promise<T> | T): Promise<T> {
const next = deviceWrites.then(async () => work(await readDevices()));
// The chain carries on after a failure; one bad write does not wedge the rest.
deviceWrites = next.catch(() => {});
return next;
}
async function readDevices(): Promise<PhoneDevice[]> {
try {
const raw = await readFile(devicesPath(), "utf8");
const parsed = JSON.parse(raw) as { devices?: PhoneDevice[] };
return Array.isArray(parsed.devices) ? parsed.devices : [];
} catch {
return [];
}
}
async function writeDevices(devices: PhoneDevice[]): Promise<void> {
await mkdir(phoneRoot(), { recursive: true });
await writeJsonAtomic(devicesPath(), { devices });
}
/** A device with its token hash left behind — what leaves this module. */
function publicDevice(device: PhoneDevice): PhoneDeviceInfo {
return {
id: device.id,
name: device.name,
pairedAt: device.pairedAt,
lastSeenAt: device.lastSeenAt,
};
}
export function listPhoneDevices(): Promise<PhoneDeviceInfo[]> {
assertLocalRuntime();
return withDeviceList((devices) =>
devices.sort((a, b) => b.lastSeenAt - a.lastSeenAt).map(publicDevice)
);
}
export function removePhoneDevice(id: string): Promise<void> {
assertLocalRuntime();
return withDeviceList(async (devices) => {
await writeDevices(devices.filter((d) => d.id !== id));
});
}
/** The device a token belongs to, with its last-seen stamp moved up. Null for a
* token no paired device holds. */
export function phoneDeviceForToken(token: string): Promise<PhoneDeviceInfo | null> {
assertLocalRuntime();
if (!token) return Promise.resolve(null);
const hash = hashToken(token);
return withDeviceList(async (devices) => {
const device = devices.find((d) => sameHash(d.tokenHash, hash));
if (!device) return null;
device.lastSeenAt = Date.now();
await writeDevices(devices);
return publicDevice(device);
});
}
// MARK: Pairing
/** How long a pairing code is good for. Long enough to walk to the phone and
* type it, short enough that a code left on screen is not a standing key. */
const PAIRING_TTL_MS = 5 * 60 * 1000;
/** Wrong answers a window survives. Six digits is 810,000 codes, which is a lot
* to read off a screen and nothing at all to a machine in radio range working
* through them, so the window closes long before guessing pays. */
const PAIRING_ATTEMPTS = 3;
/** The open pairing window, in memory only: the engine dies with the app, and a
* code that outlived a restart would be a code nobody is watching. */
let pending: { code: string; expiresAt: number; attemptsLeft: number } | null = null;
/** Why the last window ended, for the card to explain itself. */
let lastClose: PhonePairingClose = null;
/** How a window ended: a phone took it, or someone guessed at it. */
export type PhonePairingClose = "paired" | "refused" | null;
/** Six digits in two groups — read aloud across a room, typed on a phone. */
const mintCode = () => `${randomInt(100, 1000)}-${randomInt(100, 1000)}`;
export interface PhonePairingWindow {
code: string;
expiresAt: number;
}
/** Open a pairing window, replacing any code still standing. */
export function openPhonePairing(): PhonePairingWindow {
assertLocalRuntime();
lastClose = null;
pending = {
code: mintCode(),
expiresAt: Date.now() + PAIRING_TTL_MS,
attemptsLeft: PAIRING_ATTEMPTS,
};
return { code: pending.code, expiresAt: pending.expiresAt };
}
/** The window still open, or null once it has lapsed. */
export function phonePairingWindow(): PhonePairingWindow | null {
if (pending && pending.expiresAt <= Date.now()) pending = null;
return pending ? { code: pending.code, expiresAt: pending.expiresAt } : null;
}
/** Why the window that is no longer open ended, for the card to say so. */
export function phonePairingClose(): PhonePairingClose {
return phonePairingWindow() ? null : lastClose;
}
export function closePhonePairing(): void {
pending = null;
lastClose = null;
}
/** Answer a pairing code with a device name, and the phone is paired: it gets
* back the token every later upload carries. A code is spent on first use, and
* a few wrong answers close the window rather than leaving it standing to be
* guessed at. Null when no window is open or the code is wrong. */
export function claimPhonePairing(
code: string,
deviceName: string
): Promise<{ device: PhoneDeviceInfo; token: string } | null> {
assertLocalRuntime();
const open = pending;
if (!open || open.expiresAt <= Date.now()) {
pending = null;
return Promise.resolve(null);
}
if (code.trim() !== open.code) {
open.attemptsLeft -= 1;
if (open.attemptsLeft <= 0) {
pending = null;
lastClose = "refused";
}
return Promise.resolve(null);
}
pending = null;
lastClose = "paired";
const token = randomBytes(32).toString("hex");
return withDeviceList(async (devices) => {
const device: PhoneDevice = {
id: crypto.randomUUID(),
name: deviceName.trim().slice(0, 60) || "iPhone",
tokenHash: hashToken(token),
pairedAt: Date.now(),
lastSeenAt: Date.now(),
};
devices.push(device);
await writeDevices(devices);
return { device: publicDevice(device), token };
});
}
// MARK: Inbox
/** How long a clip nothing has taken stays in the inbox. The inbox is staging,
* and a shoot nobody opened an editor for would otherwise sit here forever as a
* second full copy of itself. */
const CLIP_TTL_MS = 7 * 24 * 60 * 60 * 1000;
/** How long a claim holds before the clip goes back in the inbox. An editor that
* took a clip and died mid-import must not strand it, and an import still
* running must not have it taken away — a gigabyte take through a browser is
* minutes, not seconds. */
const CLAIM_TTL_MS = 30 * 60 * 1000;
export interface PhoneClipInput {
takeId: string;
fileName: string;
capturedAt?: number;
durationSeconds?: number;
width?: number;
height?: number;
}
/** Take a clip off a paired phone.
*
* The app stages each take in the system temp directory as it comes off the
* radio, and this moves that file into the inbox under an id of this Mac's
* choosing — a phone cannot name a path here. A move rather than a copy: a field
* take is gigabytes, and pushing one through loopback to write it again is the
* difference between instant and a minute. Across volumes the move falls back to
* a copy, which is what rename cannot do there.
*
* The bytes land before the record, and only the record makes a clip visible, so
* a transfer that breaks partway leaves nothing for an editor to find. The
* start-up sweep collects what it left behind.
*/
export async function addPhoneClip(
device: PhoneDeviceInfo,
stagedPath: string,
input: PhoneClipInput
): Promise<PhoneClip> {
assertLocalRuntime();
await mkdir(inboxRoot(), { recursive: true });
// The same take arriving twice is the phone sending one whose acknowledgement
// it never read. It already has a copy here.
const already = await findPhoneClipByTake(device.id, input.takeId);
if (already) {
await rm(stagedClipPath(stagedPath), { force: true });
return already;
}
const name = clipFileName(input.fileName);
const id = crypto.randomUUID();
const file = path.join(inboxRoot(), `${id}${path.extname(name)}`);
const staged = stagedClipPath(stagedPath);
try {
await rename(staged, file);
} catch {
await copyFile(staged, file);
await rm(staged, { force: true });
}
const clip: PhoneClip = {
id,
takeId: input.takeId,
deviceId: device.id,
deviceName: device.name,
fileName: name,
bytes: (await stat(file)).size,
capturedAt: input.capturedAt ?? Date.now(),
receivedAt: Date.now(),
...(input.durationSeconds ? { durationSeconds: input.durationSeconds } : {}),
...(input.width ? { width: input.width } : {}),
...(input.height ? { height: input.height } : {}),
};
await writeJsonAtomic(clipMetaPath(id), clip);
return clip;
}
/** A take this device already delivered, whichever state its record is in. */
async function findPhoneClipByTake(deviceId: string, takeId: string): Promise<PhoneClip | null> {
for (const clip of await allPhoneClips()) {
if (clip.deviceId === deviceId && clip.takeId === takeId) return clip;
}
return null;
}
/** Every record in the inbox, claimed or not. */
async function allPhoneClips(): Promise<PhoneClip[]> {
let names: string[];
try {
names = await readdir(inboxRoot());
} catch {
return [];
}
const clips = await Promise.all(
names
.filter((n) => n.endsWith(".json"))
.map(async (n) => {
try {
return JSON.parse(await readFile(path.join(inboxRoot(), n), "utf8")) as PhoneClip;
} catch {
return null;
}
})
);
return clips.filter((c): c is PhoneClip => c !== null);
}
/** Everything waiting and unclaimed, oldest shot first — the order a shoot
* happened in is the order it should land on a timeline. A record whose bytes
* are gone is not offered; the sweep collects it. */
export async function listPhoneClips(): Promise<PhoneClip[]> {
assertLocalRuntime();
await releaseLapsedClaims();
const unclaimed = (await allPhoneClips()).filter((c) => c.claimedAt === undefined);
const present = await Promise.all(unclaimed.map((c) => exists(clipFilePath(c))));
return unclaimed.filter((_, i) => present[i]).sort((a, b) => a.capturedAt - b.capturedAt);
}
/**
* Take a clip, if it is still there to take.
*
* The rename is the whole mechanism: two editors racing both try to move the
* same record, the filesystem performs exactly one of them, and the loser's
* rename finds no source. Nothing is read and written back, so there is no
* window between deciding and doing.
*/
export async function claimPhoneClip(id: string): Promise<PhoneClip | null> {
assertLocalRuntime();
await releaseLapsedClaims();
const safe = safeId(id);
let clip: PhoneClip;
try {
clip = JSON.parse(await readFile(clipMetaPath(safe), "utf8")) as PhoneClip;
await rename(clipMetaPath(safe), claimedMetaPath(safe));
} catch {
return null;
}
const claimed: PhoneClip = { ...clip, claimedAt: Date.now() };
await writeJsonAtomic(claimedMetaPath(safe), claimed);
return claimed;
}
/** Give a claimed clip back — the import failed, and the next pass should find
* it waiting. */
export async function releasePhoneClip(id: string): Promise<void> {
assertLocalRuntime();
const safe = safeId(id);
let clip: PhoneClip;
try {
clip = JSON.parse(await readFile(claimedMetaPath(safe), "utf8")) as PhoneClip;
} catch {
return;
}
delete clip.claimedAt;
await writeJsonAtomic(clipMetaPath(safe), clip);
await rm(claimedMetaPath(safe), { force: true });
}
/** Claims whose editor never came back. */
async function releaseLapsedClaims(): Promise<void> {
const cutoff = Date.now() - CLAIM_TTL_MS;
for (const clip of await allPhoneClips()) {
if (clip.claimedAt !== undefined && clip.claimedAt < cutoff) {
await releasePhoneClip(clip.id);
}
}
}
/** A clip's record whether or not it has been claimed. */
export async function readPhoneClip(id: string): Promise<PhoneClip | null> {
assertLocalRuntime();
const safe = safeId(id);
for (const file of [clipMetaPath(safe), claimedMetaPath(safe)]) {
try {
return JSON.parse(await readFile(file, "utf8")) as PhoneClip;
} catch {
// The other name, or neither.
}
}
return null;
}
/** Where a clip's bytes sit, by its record. */
function clipFilePath(clip: PhoneClip): string {
return path.join(inboxRoot(), `${clip.id}${path.extname(clip.fileName) || ".mov"}`);
}
/** The clip's file on disk, or null when the record or the bytes are gone. */
export async function phoneClipPath(id: string): Promise<string | null> {
const clip = await readPhoneClip(id);
if (!clip) return null;
const file = clipFilePath(clip);
return (await exists(file)) ? file : null;
}
/**
* Move a claimed clip straight into a project's media.
*
* For a project that lives on this Mac both ends are local disk, so the bytes
* never leave it: the editor asks for the move and the file is renamed into the
* project. The alternative is the page pulling gigabytes off loopback and
* pushing the same bytes back, which is two copies of a take through a tab that
* has to hold the whole thing in memory.
*/
export async function movePhoneClipToProject(id: string, projectId: string): Promise<string> {
assertLocalRuntime();
const clip = await readPhoneClip(id);
const file = clip ? clipFilePath(clip) : null;
if (!clip || !file || !(await exists(file))) throw new Error("That clip is gone.");
await mkdir(mediaDir(projectId), { recursive: true });
const base = path.basename(clip.fileName).replace(/[^\w.\-() ]+/g, "_").slice(-80);
const fileName = await uniqueName(base, (n) => mediaPath(projectId, n));
const destination = mediaPath(projectId, fileName);
try {
await rename(file, destination);
} catch {
await copyFile(file, destination);
await rm(file, { force: true });
}
await rm(claimedMetaPath(safeId(id)), { force: true });
await rm(clipMetaPath(safeId(id)), { force: true });
return fileName;
}
/** Drop a clip once an editor has it: the record and the bytes together. */
export async function removePhoneClip(id: string): Promise<void> {
assertLocalRuntime();
const file = await phoneClipPath(id);
if (file) await rm(file, { force: true });
await rm(clipMetaPath(safeId(id)), { force: true });
await rm(claimedMetaPath(safeId(id)), { force: true });
}
/**
* Clear what the inbox should not be holding, run once as the engine starts.
*
* Three kinds of leftovers: bytes with no record, from a transfer that broke
* before the record was written; records whose bytes are gone; and clips older
* than the inbox keeps, which is every take from a shoot nobody opened an editor
* for.
*/
export async function sweepPhoneInbox(): Promise<void> {
assertLocalRuntime();
let names: string[];
try {
names = await readdir(inboxRoot());
} catch {
return;
}
const cutoff = Date.now() - CLIP_TTL_MS;
const keeping = new Set<string>();
for (const clip of await allPhoneClips()) {
if (clip.receivedAt < cutoff || !(await exists(clipFilePath(clip)))) {
await removePhoneClip(clip.id);
continue;
}
keeping.add(path.basename(clipFilePath(clip)));
}
for (const name of names) {
if (name.endsWith(".json") || keeping.has(name)) continue;
await rm(path.join(inboxRoot(), name), { force: true });
}
await releaseLapsedClaims();
}
/** Clip ids are ours — uuids — so anything else is a path probe. */
function safeId(id: string): string {
if (!/^[0-9a-f-]{36}$/i.test(id)) throw new Error("Bad clip id.");
return id;
}
/** A staged clip is one the app just wrote to the system temp directory. The
* engine answers on loopback with no auth, so it takes a path from that caller
* only where the app puts them, and nowhere else on the disk. */
function stagedClipPath(raw: string): string {
const resolved = path.resolve(raw);
const staging = `${path.resolve(os.tmpdir())}${path.sep}`;
if (!resolved.startsWith(staging)) throw new Error("A staged clip lives in the temp directory.");
return resolved;
}
/** The name a clip lands under, reduced to a leaf this Mac is willing to write:
* the phone names its own takes, and a name is not a path. */
function clipFileName(raw: string): string {
const leaf = path.basename(raw ?? "").replace(/[/\\]/g, "").trim();
const ext = path.extname(leaf) || ".mov";
const stem = leaf.slice(0, leaf.length - path.extname(leaf).length) || "clip";
return `${stem.slice(0, 80)}${ext}`;
}