Code-first video & image, rendered natively on WebGPU.
/**
* 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 },
);
});
}