Skip to content

Code-first video & image, rendered natively on WebGPU.

11.9 KB
Raw Blame
/**
 * Cloud renders on api.framefields.dev: the project renders from git on
 * framefields' GPU workers, billed to the account that owns the API key.
 *
 * ```ts
 * import { renderCloud } from "framefields/cloud";
 *
 * const result = await renderCloud({
 *   render: "film", // a render named in framefields.json
 *   outputPath: "output/film.mp4",
 *   onProgress: (s) => console.log(s.status, s.progress.frames),
 * });
 * ```
 *
 * Without a framefields.json, name the module instead: `entry: "src/film.ts"`
 * (and `export`, `workers`, …). Options passed here override the named
 * render's.
 *
 * `workers: "auto"` probes the film on one worker first, then splits it into
 * as many chunks as stay efficient: short films stay on one worker, long ones
 * spread out up to `maxWorkers`. `dryRun: true` returns that plan with the
 * estimated cost and renders nothing. Aborting `signal` cancels the render;
 * GPU time already used is charged.
 */
import { createWriteStream } from "node:fs";
import fs from "node:fs/promises";
import path from "node:path";
import { Readable } from "node:stream";
import { pipeline } from "node:stream/promises";
import type { ReadableStream as WebReadableStream } from "node:stream/web";
import { AssetsError, prepareCloudAssets } from "../cli/assets.js";
import { CONFIG_FILE, findRender, readConfig } from "../cli/config.js";
import { type CloudSource, resolveGitSource } from "./git-source.js";

export { type CloudSource, resolveGitSource, toHttps } from "./git-source.js";

export const FRAMEFIELDS_API_URL = "https://api.framefields.dev";

export interface CloudRenderOptions {
	/** A render named in `cwd`'s framefields.json; its fields are the defaults here. */
	render?: string;
	/** The module that builds the composition, relative to `cwd`. Required without `render`. */
	entry?: string;
	/** Its export: a Composition, or a function returning one. Default `buildFilm`. */
	export?: string;
	/** Passed to the export when it is a function. */
	args?: unknown;
	/** When the export returns several compositions, the one to render. */
	select?: string;
	/** 1 (default) renders on one worker; a number or "auto" splits the film. */
	workers?: number | "auto";
	/** Upper bound for "auto" (the API caps it too). */
	maxWorkers?: number;
	codec?: "h264" | "vp9";
	quality?: string;
	/** Probe and plan only: returns the plan and estimated cost, renders nothing. */
	dryRun?: boolean;
	/** Download the finished video here. */
	outputPath?: string;
	/** Project folder. Default `process.cwd()`. */
	cwd?: string;
	/** Instead of reading repo, branch and commit from git. */
	source?: CloudSource;
	/** Default `process.env.FRAMEFIELDS_API_KEY`. */
	apiKey?: string;
	/** Default `process.env.FRAMEFIELDS_API_URL`, else https://api.framefields.dev. */
	apiUrl?: string;
	/** Called with every status poll. */
	onProgress?: (status: CloudRenderStatus) => void;
	/** Called for each warning (uncommitted changes). Default: stderr. */
	onWarning?: (message: string) => void;
	/** Called as assets upload before the render. Default: stderr. */
	onLog?: (message: string) => void;
	/** Aborting cancels the cloud render. */
	signal?: AbortSignal;
	/** Status poll interval, ms. Default 3000. */
	pollMs?: number;
}

export type CloudRenderPhase =
	| "probing"
	| "holding"
	| "rendering"
	| "stitching"
	| "planned"
	| "completed"
	| "failed"
	| "cancelled";

export interface CloudRenderPlan {
	workers: number;
	/** Render time of the whole film on one GPU, seconds. */
	workSec: number;
	/** Expected wall time with this plan, seconds. */
	etaSec: number;
	chunks: { start: number; end: number; workSec: number }[];
}

export interface CloudRenderStatus {
	id: string;
	status: CloudRenderPhase;
	workers: number;
	plan?: CloudRenderPlan;
	progress: {
		frames: number;
		totalFrames: number | null;
		etaSec: number | null;
	};
	/** Charged so far (final once the render ended), USD. */
	costUsd: number;
	gpuSeconds: number;
	/** The planned render's estimated charge, USD. */
	estimateUsd?: number;
	/** The commit rendered. */
	sha?: string;
	output?: { url: string; bytes?: number };
	error?: { code: string; message: string };
}

export interface CloudRenderResult extends CloudRenderStatus {
	/** Where the video was downloaded (`outputPath`). */
	filePath?: string;
}

/** A cloud render that failed, was cancelled, or was refused by the API. */
export class CloudRenderError extends Error {
	constructor(
		message: string,
		readonly code: string,
		readonly status?: CloudRenderStatus,
	) {
		super(message);
		this.name = "CloudRenderError";
	}
}

const DONE = new Set<CloudRenderPhase>([
	"planned",
	"completed",
	"failed",
	"cancelled",
]);

/** Starts a cloud render and waits for it; resolves when it completed (or was planned). */
export async function renderCloud(
	options: CloudRenderOptions,
): Promise<CloudRenderResult> {
	const api = cloudClient(options);
	const cwd = options.cwd ?? process.cwd();
	const o = withNamedRender(cwd, options);
	const resolved = options.source
		? { source: options.source, entry: o.entry, warnings: [] }
		: resolveGitSource(cwd, o.entry);
	const warn =
		options.onWarning ??
		((m: string) => process.stderr.write(`framefields: ${m}\n`));
	for (const w of resolved.warnings) warn(w);
	const assets = await cloudAssets(cwd, options);

	let status = await api.start({
		source: Object.keys(assets).length
			? { ...resolved.source, assets }
			: resolved.source,
		target: {
			entry: resolved.entry,
			export: o.export ?? "buildFilm",
			...(o.args !== undefined && { args: o.args }),
			...(o.select && { select: [o.select] }),
		},
		render: {
			codec: o.codec ?? "h264",
			...(o.quality && { quality: o.quality }),
		},
		workers: o.workers ?? 1,
		...(o.maxWorkers && { max_workers: o.maxWorkers }),
		dry_run: options.dryRun ?? false,
		...(o.name && { name: o.name }),
		...(o.title && { title: o.title }),
	});
	options.onProgress?.(status);

	try {
		while (!DONE.has(status.status)) {
			await sleep(options.pollMs ?? 3000, options.signal);
			status = await api.status(status.id);
			options.onProgress?.(status);
		}
	} catch (err) {
		if (options.signal?.aborted) {
			const final = await api.cancel(status.id).catch(() => status);
			throw new CloudRenderError(
				"The cloud render was cancelled.",
				"cancelled",
				final,
			);
		}
		throw err;
	}

	if (status.status === "failed" || status.status === "cancelled")
		throw new CloudRenderError(
			status.error
				? `Cloud render ${status.status}: ${status.error.message} (${status.error.code})`
				: `Cloud render ${status.status}.`,
			status.error?.code ?? status.status,
			status,
		);
	if (status.status === "completed" && options.outputPath && status.output) {
		await download(status.output.url, options.outputPath, options.signal);
		return { ...status, filePath: options.outputPath };
	}
	return status;
}

/**
 * Uploads assets the bucket lacks and signs reads of private ones: the
 * workers download each asset framefields.json pins at the commit.
 */
async function cloudAssets(
	cwd: string,
	options: CloudRenderOptions,
): Promise<Record<string, string>> {
	try {
		return await prepareCloudAssets({
			cwd,
			signal: options.signal,
			log:
				options.onLog ??
				((m: string) => process.stderr.write(`framefields: ${m}\n`)),
		});
	} catch (err) {
		if (err instanceof AssetsError)
			throw new CloudRenderError(err.message, `assets_${err.code}`);
		throw err;
	}
}

/**
 * The options with a named render's fields filled in where the caller left
 * them out, plus the name and title the dashboard shows.
 */
export function withNamedRender(
	cwd: string,
	options: CloudRenderOptions,
): CloudRenderOptions & { entry: string; name?: string; title?: string } {
	if (!options.render) {
		if (!options.entry)
			throw new CloudRenderError(
				"Name a render from framefields.json (render) or a module (entry).",
				"invalid_request",
			);
		return { ...options, entry: options.entry };
	}
	const spec = findRender(cwd, options.render);
	if (!spec) {
		const names = Object.keys(readConfig(cwd).config.renders ?? {});
		throw new CloudRenderError(
			names.length
				? `No render named "${options.render}" in ${CONFIG_FILE}. Renders: ${names.join(", ")}.`
				: `No render named "${options.render}": ${CONFIG_FILE} has no "renders".`,
			"render_not_found",
		);
	}
	const defined = Object.fromEntries(
		Object.entries(options).filter(([, v]) => v !== undefined),
	) as CloudRenderOptions;
	return {
		entry: spec.entry,
		export: spec.export,
		args: spec.args,
		select: spec.select,
		workers: spec.workers,
		maxWorkers: spec.maxWorkers,
		codec: spec.codec,
		quality: spec.quality,
		...defined,
		name: spec.name,
		title: spec.title ?? spec.name,
	} as CloudRenderOptions & { entry: string; name: string; title: string };
}

/** The API calls behind `renderCloud`, for callers who track renders themselves. */
export function cloudClient(
	options: Pick<CloudRenderOptions, "apiKey" | "apiUrl">,
) {
	const key = options.apiKey ?? process.env.FRAMEFIELDS_API_KEY;
	if (!key)
		throw new CloudRenderError(
			"No API key. Set FRAMEFIELDS_API_KEY (keys at https://framefields.dev/dashboard/keys) or pass apiKey.",
			"invalid_api_key",
		);
	const base = (
		options.apiUrl ??
		process.env.FRAMEFIELDS_API_URL ??
		FRAMEFIELDS_API_URL
	).replace(/\/+$/, "");
	const call = async (method: string, route: string, body?: unknown) => {
		const res = await fetch(`${base}/v1/render${route}`, {
			method,
			headers: {
				Authorization: `Bearer ${key}`,
				"Content-Type": "application/json",
			},
			...(body !== undefined && { body: JSON.stringify(body) }),
		});
		const json = (await res.json().catch(() => ({}))) as ApiStatus & {
			error?: { type?: string; message?: string };
		};
		if (!res.ok)
			throw new CloudRenderError(
				json.error?.message ??
					`api.framefields.dev answered HTTP ${res.status}`,
				json.error?.type ?? `http_${res.status}`,
			);
		return fromApi(json);
	};
	return {
		start: (body: unknown) => call("POST", "", body),
		status: (id: string) => call("GET", `/${encodeURIComponent(id)}`),
		cancel: (id: string) => call("DELETE", `/${encodeURIComponent(id)}`),
	};
}

/** The API's snake_case status. */
interface ApiStatus {
	id: string;
	status: CloudRenderPhase;
	workers?: number;
	plan?: {
		workers: number;
		work_sec: number;
		eta_sec: number;
		chunks: CloudRenderPlan["chunks"];
	};
	progress?: {
		frames?: number;
		total_frames?: number | null;
		eta_sec?: number | null;
	};
	cost_usd?: number;
	gpu_seconds?: number;
	estimate_usd?: number;
	sha?: string;
	output?: { url: string; bytes?: number };
	error?: { code: string; message: string };
}

function fromApi(s: ApiStatus): CloudRenderStatus {
	return {
		id: s.id,
		status: s.status,
		workers: s.workers ?? 1,
		...(s.plan && {
			plan: {
				workers: s.plan.workers,
				workSec: s.plan.work_sec,
				etaSec: s.plan.eta_sec,
				chunks: s.plan.chunks,
			},
		}),
		progress: {
			frames: s.progress?.frames ?? 0,
			totalFrames: s.progress?.total_frames ?? null,
			etaSec: s.progress?.eta_sec ?? null,
		},
		costUsd: s.cost_usd ?? 0,
		gpuSeconds: s.gpu_seconds ?? 0,
		...(s.estimate_usd !== undefined && { estimateUsd: s.estimate_usd }),
		...(s.sha && { sha: s.sha }),
		...(s.output && { output: s.output }),
		...(s.error && { error: s.error }),
	};
}

async function download(url: string, file: string, signal?: AbortSignal) {
	const res = await fetch(url, { signal });
	if (!res.ok || !res.body)
		throw new CloudRenderError(
			`Downloading the render failed: HTTP ${res.status}`,
			"download_failed",
		);
	await fs.mkdir(path.dirname(path.resolve(file)), { recursive: true });
	await pipeline(
		Readable.fromWeb(res.body as WebReadableStream),
		createWriteStream(file),
	);
}

function sleep(ms: number, signal?: AbortSignal): Promise<void> {
	return new Promise((resolve, reject) => {
		if (signal?.aborted) return reject(signal.reason);
		const timer = setTimeout(resolve, ms);
		signal?.addEventListener(
			"abort",
			() => {
				clearTimeout(timer);
				reject(signal.reason);
			},
			{ once: true },
		);
	});
}