Skip to content

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

feat(cli): render and preview by name, here or in the cloud

okanasl7edabea03e98
diff --git a/.changeset/local-render-preview.md b/.changeset/local-render-preview.md
new file mode 100644
index 00000000..357d2226
--- /dev/null
+++ b/.changeset/local-render-preview.md
@@ -0,0 +1,5 @@
+---
+"framefields": minor
+---
+
+`framefields render <name>` renders a named render on this machine and `framefields preview <name>` plays it in the browser, reading the same `framefields.json` render as `--cloud`, so a render writes the same file wherever it runs. Both load the module with the project's own tsx and framefields. A local render first downloads pinned assets that are missing; the preview streams them from their bucket instead (redirecting the page to the remote's `publicUrl` or a signed URL, and mixing the soundtrack over HTTP), so an agent in a cloud sandbox previews footage without downloading it. `init`'s `render` and `preview` scripts now call the CLI.
diff --git a/CLAUDE.md b/CLAUDE.md
index b93594d4..590d6099 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -13,13 +13,13 @@ Code-first video engine on native WebGPU (Dawn) in Node, no browser. pnpm + turb
- Keep this file current when structure or dev patterns change but do not bloat it.
## Repo map
-- `packages/framefields`: public SDK. `Composition`, `Layer.*`, `LayerAnimation`, `Signal`, effects (`src/effects/classes.ts`), `FontManager`, `renderFrameGrid`. `src/index.ts` is the export surface. CLI in `src/cli/` (`init`, `add`, `list`, `fonts add|list`, `assets add|push|pull|status`, `check`, `renders`, `render --cloud`); `framefields.json` (`cli/config.ts`) holds the components folder, fonts, named `renders` that the CLI, `renderCloud` and the dashboard pick by name, and `storage` remotes plus sha256-pinned `assets`; `framefields/cloud` (`renderCloud`) is the GPU-free client for api.framefields.dev; `init` never prompts or overwrites, and its file templates are strings in `templates.ts` (a test parses them).
+- `packages/framefields`: public SDK. `Composition`, `Layer.*`, `LayerAnimation`, `Signal`, effects (`src/effects/classes.ts`), `FontManager`, `renderFrameGrid`. `src/index.ts` is the export surface. CLI in `src/cli/` (`init`, `add`, `list`, `fonts add|list`, `assets add|push|pull|status`, `check`, `renders`, `render [--cloud]`, `preview`; local render and preview run `cli/local-worker.ts` with the project's own tsx and framefields); `framefields.json` (`cli/config.ts`) holds the components folder, fonts, named `renders` that the CLI, `renderCloud` and the dashboard pick by name, and `storage` remotes plus sha256-pinned `assets`; `framefields/cloud` (`renderCloud`) is the GPU-free client for api.framefields.dev; `init` never prompts or overwrites, and its file templates are strings in `templates.ts` (a test parses them).
- `packages/components`: the component registry `framefields add` copies into user projects (shadcn-style). `defineComponent`/`bind` contract in `src/core/contract.ts`, shared helpers in `src/core/` (keys, color, layout, surface, theme). Components import only `framefields` and `../core`. Registry items declare font needs (e.g. emoji); CLI fonts are pinned by URL, size and SHA-256 in `cli/fonts.ts`. Prop docs in `components.json` are generated (drift test). Tree-shake size budgets are tested.
- `packages/compositions`: Yoga layout (`utils/layout/resolve-layout.ts`), program schema (`program/schema.ts`), lint (`program/lint.ts`), animation/evaluator.
- `packages/webgpu-renderers`: WGSL shaders, 2D/3D pipelines, Slug text (`src/slug/`), audio DSP.
- `packages/renderer`: headless Node renderer (Dawn, WebCodecs/mediabunny).
- `packages/vision-sam`: SAM 2.1 Tiny/Small and SAM 3 trackers (Apache-2.0 code; SAM 3 weights need runtime SAM License acceptance), private; `framefields` bundles it as a lazy chunk (`clip-vision.ts` imports it dynamically for `comp.vision(..., { sam2 | sam3 })`; `index.ts` re-exports types only) and exposes the trackers as `framefields/sam`. No weights ship; `packages/framefields/NOTICE.md` covers their licenses. Pins in `src/models/registry.ts`.
-- `packages/storage`: content-addressed assets on any S3-compatible bucket (R2 first): manifest format, SigV4 client (aws4fetch), verified downloads. Shared by the CLI (`framefields/storage`) and the render worker, which fetches pinned assets after LFS.
+- `packages/storage`: content-addressed assets on any S3-compatible bucket (R2 first): manifest format, SigV4 client (aws4fetch), verified downloads, and the locator the preview uses to redirect missing pinned files to their bucket. Shared by the CLI (`framefields/storage`), the preview and the render worker, which fetches pinned assets after LFS.
- `packages/core`: shared types, `Effect` base, signals, `emojiPresentation` (the one UTS #51 rule used by layout, preload and lint).
- Others: `renderers`, `media`, `node-sdk`, `server-utils`, `client-utils`, `tensor-webgpu`, `vision`, `tsconfig`.
- `nodes/node-*`: one VFX/audio/layout node each (`src/shared/`, `src/renderers/`, `src/index.ts`). Only `node-compositor` has a `SKILL.md`; update it when Compositor behavior changes (guarded by `skillmd-check.test.ts`). Effect renderers declare `reach` and `maxPixelScale` (node-sdk) when they can: without `maxPixelScale` a scaled-up leaf using the effect stays at layout resolution.
diff --git a/apps/renderer-service/src/git/assets.ts b/apps/renderer-service/src/git/assets.ts
index af6af8a5..46f02e57 100644
--- a/apps/renderer-service/src/git/assets.ts
+++ b/apps/renderer-service/src/git/assets.ts
@@ -4,12 +4,10 @@ import path from "node:path";
import {
type AssetEntry,
AssetError,
- type AssetManifest,
downloadVerified,
hashFile,
ManifestError,
- parseAssets,
- parseStorage,
+ readProjectManifest,
readUrl,
type StorageConfig,
} from "@framefields/storage";
@@ -96,22 +94,11 @@ export async function fetchAssets(
};
}
-async function readManifest(
- workdir: string,
-): Promise<{ storage?: StorageConfig; assets?: AssetManifest } | undefined> {
- const file = path.join(workdir, "framefields.json");
- if (!existsSync(file)) return undefined;
+async function readManifest(workdir: string) {
try {
- const raw = JSON.parse(await fs.readFile(file, "utf8")) as {
- storage?: unknown;
- assets?: unknown;
- };
- if (raw.assets === undefined) return undefined;
- const storage =
- raw.storage === undefined ? undefined : parseStorage(raw.storage);
- return { storage, assets: parseAssets(raw.assets, storage) };
+ return await readProjectManifest(workdir);
} catch (err) {
- if (err instanceof ManifestError || err instanceof SyntaxError)
+ if (err instanceof ManifestError)
throw new RenderError("ASSET_MANIFEST_INVALID", err.message, {
hint: "`npx framefields assets status` reads the same file locally.",
});
diff --git a/packages/framefields/src/cli.ts b/packages/framefields/src/cli.ts
index 4e96ec20..24c52dcc 100644
--- a/packages/framefields/src/cli.ts
+++ b/packages/framefields/src/cli.ts
@@ -9,7 +9,9 @@
* npx framefields fonts list the fonts you can install
* npx framefields assets add|push|pull|status media on your own bucket
* npx framefields renders the renders named in framefields.json
+ * npx framefields render <name> render on this machine's GPU
* npx framefields render <name> --cloud render on api.framefields.dev
+ * npx framefields preview <name> play it in the browser
*/
import { readFileSync } from "node:fs";
import { join, relative, resolve } from "node:path";
@@ -35,6 +37,7 @@ import {
type PackageManager,
shownPath,
} from "./cli/init.js";
+import { runLocal } from "./cli/local.js";
import { openRegistry } from "./cli/registry.js";
import { AI_DASHBOARD } from "./cli/templates.js";
@@ -67,13 +70,19 @@ Commands:
assets pull Download missing assets, checked against their sha256.
assets status Which assets are here, missing or changed.
renders List the renders named in framefields.json.
- render [name|entry] --cloud
- Render on api.framefields.dev from the pushed commit of
- this git repo, and download the video. Needs
- FRAMEFIELDS_API_KEY. A render named in framefields.json
+ render [name|entry]
+ Render on this machine: a render named in framefields.json
(its fields are the defaults; flags override them), or a
module (--export defaults to buildFilm). Without either,
- the project's only named render.
+ the project's only named render. Pinned assets missing
+ here are downloaded first.
+ render [name|entry] --cloud
+ The same render on api.framefields.dev, from the pushed
+ commit of this git repo, downloaded to the same file.
+ Needs FRAMEFIELDS_API_KEY.
+ preview [name|entry]
+ Play it in the browser (localhost, WebGPU). Pinned assets
+ that aren't here stream from their bucket.
Options for check:
--export <name> Composition or builder export (default buildFilm).
@@ -83,6 +92,10 @@ Options for check:
--warnings-as-errors Fail on lint warnings.
--json Machine-readable check, component list, or font list result.
+Options for render and preview:
+ --export, --select, --codec, --quality and --output (render) override the
+ named render's fields, locally and with --cloud.
+
Options for render --cloud:
--workers <n|auto> 1 (default) renders on one GPU. auto measures the film
first and splits it across as many GPUs as stay
@@ -133,6 +146,8 @@ Examples:
npx framefields add mouse-pointer focus-zoom
npx framefields fonts add emoji
npx framefields assets add assets/footage
+ npx framefields preview film
+ npx framefields render film
npx framefields render film --cloud --plan
`;
@@ -202,10 +217,30 @@ async function main(argv: string[]): Promise<number> {
overwrite: values.overwrite,
json: values.json,
});
+ if (command === "preview" || (command === "render" && !values.cloud)) {
+ if (names.length > 1) {
+ process.stderr.write(
+ `Usage: framefields ${command} [name|entry] [--export <name>]\n`,
+ );
+ return 2;
+ }
+ return runLocal(
+ command === "preview" ? "preview" : "render",
+ {
+ entry: names[0],
+ export: values.export,
+ select: values.select,
+ codec: values.codec,
+ quality: values.quality,
+ output: values.output,
+ },
+ log,
+ );
+ }
if (command === "render") {
- if (names.length > 1 || !values.cloud) {
+ if (names.length > 1) {
process.stderr.write(
- "Usage: framefields render [name|entry] --cloud [--workers auto] [--plan]\nLocal renders run your project's render script (`npm run render`).\n",
+ "Usage: framefields render [name|entry] --cloud [--workers auto] [--plan]\n",
);
return 2;
}
diff --git a/packages/framefields/src/cli/assets.test.ts b/packages/framefields/src/cli/assets.test.ts
index f88a61f4..72bca3e5 100644
--- a/packages/framefields/src/cli/assets.test.ts
+++ b/packages/framefields/src/cli/assets.test.ts
@@ -64,7 +64,7 @@ function fakeR2() {
return new Response(null, {
headers: { "content-length": String(body.length) },
});
- return new Response(body);
+ return new Response(new Uint8Array(body));
};
return { fetch: handler as typeof fetch, objects, log };
}
diff --git a/packages/framefields/src/cli/check.ts b/packages/framefields/src/cli/check.ts
index 84ac3f74..5e7c0a9f 100644
--- a/packages/framefields/src/cli/check.ts
+++ b/packages/framefields/src/cli/check.ts
@@ -1,9 +1,8 @@
import { spawn } from "node:child_process";
-import { createRequire } from "node:module";
import { resolve } from "node:path";
-import { fileURLToPath, pathToFileURL } from "node:url";
import { type CheckReport, failedCheck } from "./check-result.js";
import { ownVersion } from "./init.js";
+import { projectNodeArgs } from "./project-node.js";
export interface CheckOptions {
/** Module path, resolved from the project working directory. */
@@ -30,28 +29,8 @@ export async function runCheck(options: CheckOptions): Promise<CheckReport> {
throw new Error("--timeout must be a positive integer in milliseconds");
const fail = (code: string, message: string) =>
failedCheck(entry, exportName, sdkVersion, code, message);
- const source = import.meta.url.endsWith(".ts");
- const args = source ? ["--conditions=development"] : [];
- // TypeScript belongs to the consumer project; it is already in init's scaffold.
- if (source || /\.[cm]?tsx?$/.test(entry)) {
- try {
- const require = createRequire(resolve("package.json"));
- args.push("--import", pathToFileURL(require.resolve("tsx")).href);
- } catch {
- return fail(
- "missing_ts_loader",
- "Install the project's tsx dev dependency to check a TypeScript entry.",
- );
- }
- }
- args.push(
- fileURLToPath(
- new URL(
- source ? "./check-worker.ts" : "./cli/check-worker.mjs",
- import.meta.url,
- ),
- ),
- );
+ const args = projectNodeArgs(entry, "check-worker");
+ if ("error" in args) return fail("missing_ts_loader", args.error);
return new Promise((done) => {
const child = spawn(process.execPath, args, {
stdio: ["ignore", "pipe", "pipe", "ipc"],
diff --git a/packages/framefields/src/cli/cloud.ts b/packages/framefields/src/cli/cloud.ts
index d81b1767..5598498c 100644
--- a/packages/framefields/src/cli/cloud.ts
+++ b/packages/framefields/src/cli/cloud.ts
@@ -13,7 +13,12 @@ import {
type CloudRenderStatus,
renderCloud,
} from "../cloud/index.js";
-import { CONFIG_FILE, findRender, readConfig } from "./config.js";
+import {
+ CONFIG_FILE,
+ findRender,
+ type RenderSpec,
+ readConfig,
+} from "./config.js";
export interface CloudCliOptions {
/** A render named in framefields.json, or a module path. Optional when framefields.json has one render. */
@@ -59,13 +64,7 @@ export async function runCloudRender(
}
const spec = target.name ? findRender(cwd, target.name) : undefined;
const codec = (o.codec ?? spec?.codec ?? "h264") as "h264" | "vp9";
- const outputPath =
- o.output ??
- spec?.output ??
- path.join(
- "output",
- `${target.name ?? path.basename(target.entry ?? "").replace(/\.[^.]+$/, "")}.${codec === "vp9" ? "webm" : "mp4"}`,
- );
+ const outputPath = renderOutput(target, spec, codec, o.output);
// A plan of a one-worker render would only ever say "one worker".
const planWorkers =
o.plan && (workers ?? spec?.workers ?? 1) === 1 ? "auto" : workers;
@@ -143,6 +142,22 @@ export function renderCommand(o: CloudCliOptions): string {
].join(" ");
}
+/** What a render named `name` (or the module `entry`) produces, wherever it runs. */
+export function renderOutput(
+ target: { name?: string; entry?: string },
+ spec: RenderSpec | undefined,
+ codec: string,
+ output?: string,
+): string {
+ const base =
+ target.name ?? path.basename(target.entry ?? "").replace(/\.[^.]+$/, "");
+ return (
+ output ??
+ spec?.output ??
+ path.join("output", `${base}.${codec === "vp9" ? "webm" : "mp4"}`)
+ );
+}
+
/**
* What `framefields render [arg]` renders: a render named in framefields.json,
* or a module path; with no argument, the project's only named render.
@@ -158,7 +173,7 @@ export function pickRender(
return {
error: names.length
? `Name the render: ${names.join(", ")}. \`framefields renders\` lists them.`
- : `Name a module, e.g. \`framefields render src/film.ts --cloud\`, or add "renders" to ${CONFIG_FILE}.`,
+ : `Name a module, e.g. \`framefields render src/film.ts\`, or add "renders" to ${CONFIG_FILE}.`,
};
}
if (renders[arg]) return { name: arg };
diff --git a/packages/framefields/src/cli/local-worker.ts b/packages/framefields/src/cli/local-worker.ts
new file mode 100644
index 00000000..3a7382c0
--- /dev/null
+++ b/packages/framefields/src/cli/local-worker.ts
@@ -0,0 +1,76 @@
+/**
+ * Runs a render or a preview of the user's module in its own Node process
+ * (with the project's TypeScript loader), for `framefields render` and
+ * `framefields preview`. Its options arrive over IPC; it reports back over
+ * IPC and exits, since GPU and encoder threads keep Node alive otherwise.
+ *
+ * It uses the project's own framefields, as the cloud worker does: a second
+ * copy of the engine next to the one the film imports would not share its
+ * decoders.
+ */
+import { pathToFileURL } from "node:url";
+import type { startPreview } from "../preview/index.js";
+import { pickComposition } from "./pick-composition.js";
+
+export interface LocalJob {
+ mode: "render" | "preview";
+ /** Absolute module path. */
+ entry: string;
+ export: string;
+ /** File URL of the project's framefields entry (for the preview). */
+ engine: string;
+ args?: unknown;
+ select?: string;
+ /** render: where the video goes. */
+ outputPath?: string;
+ codec?: string;
+ quality?: string;
+ /** preview: the page's title. */
+ title?: string;
+}
+
+export type LocalResult =
+ | { ok: true; filePath?: string }
+ | { ok: false; message: string };
+
+async function run(job: LocalJob): Promise<LocalResult> {
+ if (job.mode === "preview") {
+ // The project's framefields: known only at runtime.
+ const engine = (await import(job.engine)) as {
+ startPreview: typeof startPreview;
+ };
+ const session = await engine.startPreview(
+ { entry: job.entry, export: job.export },
+ { title: job.title },
+ );
+ process.stdout.write(`Preview at ${session.url}\n`);
+ await session.closed;
+ return { ok: true };
+ }
+ const mod: Record<string, unknown> = await import(
+ pathToFileURL(job.entry).href
+ );
+ const comp = await pickComposition(mod, job);
+ const result = await comp.renderVideo({
+ outputPath: job.outputPath,
+ ...(job.codec && { codec: job.codec }),
+ ...(job.quality && { quality: job.quality }),
+ });
+ await result.cleanup?.();
+ return { ok: true, filePath: result.filePath };
+}
+
+process.once("message", (job: LocalJob) => {
+ process.channel?.ref();
+ run(job).then(
+ (result) => process.send?.(result, () => process.exit(0)),
+ (error: unknown) =>
+ process.send?.(
+ {
+ ok: false,
+ message: error instanceof Error ? error.message : String(error),
+ } satisfies LocalResult,
+ () => process.exit(1),
+ ),
+ );
+});
diff --git a/packages/framefields/src/cli/local.ts b/packages/framefields/src/cli/local.ts
new file mode 100644
index 00000000..1f31c282
--- /dev/null
+++ b/packages/framefields/src/cli/local.ts
@@ -0,0 +1,144 @@
+/**
+ * `framefields render [name|entry]` and `framefields preview [name|entry]`
+ * on this machine. They read the same named renders in framefields.json as
+ * `--cloud`, so a render goes to the same file wherever it runs.
+ *
+ * A local render first downloads pinned assets that are missing here; a
+ * preview doesn't need to: the page streams them from their bucket.
+ */
+import { spawn } from "node:child_process";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { AssetsError, megabytes, pullAssets } from "./assets.js";
+import { pickRender, renderOutput } from "./cloud.js";
+import { findRender, readConfig } from "./config.js";
+import type { LocalJob, LocalResult } from "./local-worker.js";
+import { projectNodeArgs } from "./project-node.js";
+
+export interface LocalCliOptions {
+ /** A render named in framefields.json, or a module path. */
+ entry?: string;
+ export?: string;
+ select?: string;
+ codec?: string;
+ quality?: string;
+ output?: string;
+ /** Project folder. Default `process.cwd()`. */
+ cwd?: string;
+}
+
+export async function runLocal(
+ mode: LocalJob["mode"],
+ o: LocalCliOptions,
+ log: (line: string) => void,
+): Promise<number> {
+ const cwd = o.cwd ?? process.cwd();
+ const target = pickRender(o.entry, cwd);
+ if ("error" in target) {
+ log(target.error);
+ return 2;
+ }
+ const spec = target.name ? findRender(cwd, target.name) : undefined;
+ const entry = path.resolve(cwd, spec?.entry ?? (target.entry as string));
+ const codec = o.codec ?? spec?.codec ?? "h264";
+ if (codec !== "h264" && codec !== "vp9") {
+ log(`--codec must be h264 or vp9, not "${codec}".`);
+ return 2;
+ }
+ const engine = projectEngine(entry);
+ if (!engine) {
+ log("framefields isn't installed in this project: `npm i framefields`.");
+ return 2;
+ }
+ const job: LocalJob = {
+ mode,
+ entry,
+ engine,
+ export: o.export ?? spec?.export ?? "buildFilm",
+ args: spec?.args,
+ select: o.select ?? spec?.select,
+ codec,
+ quality: o.quality ?? spec?.quality,
+ outputPath: path.resolve(cwd, renderOutput(target, spec, codec, o.output)),
+ title: spec?.title ?? target.name,
+ };
+ if (mode === "preview" && (job.args !== undefined || job.select))
+ log(
+ "The preview calls the export without args or select; it shows what the export returns by default.",
+ );
+ if (mode === "render" && !(await ensureAssets(cwd, log))) return 1;
+ const result = await runWorker(job, cwd);
+ if (!result.ok) {
+ log(result.message);
+ return 1;
+ }
+ if (result.filePath)
+ log(`Rendered ${path.relative(cwd, result.filePath) || result.filePath}`);
+ return 0;
+}
+
+/** The framefields the film imports, resolved from its module. */
+function projectEngine(entry: string): string | undefined {
+ try {
+ return pathToFileURL(createRequire(entry).resolve("framefields")).href;
+ } catch {
+ return undefined;
+ }
+}
+
+/** Downloads pinned assets missing here; false (after saying why) when it can't. */
+async function ensureAssets(
+ cwd: string,
+ log: (line: string) => void,
+): Promise<boolean> {
+ const assets = readConfig(cwd).config.assets ?? {};
+ if (Object.keys(assets).length === 0) return true;
+ try {
+ const { downloaded, changed } = await pullAssets({ cwd, log });
+ if (downloaded.length) {
+ const bytes = downloaded.reduce((n, p) => n + (assets[p]?.size ?? 0), 0);
+ log(
+ `Downloaded ${downloaded.length} pinned assets (${megabytes(bytes)}).`,
+ );
+ }
+ if (changed.length)
+ log(
+ `Rendering local edits of pinned assets: ${changed.join(", ")}. \`framefields assets add\` pins them for the cloud.`,
+ );
+ return true;
+ } catch (err) {
+ if (!(err instanceof AssetsError)) throw err;
+ log(err.message);
+ return false;
+ }
+}
+
+function runWorker(job: LocalJob, cwd: string): Promise<LocalResult> {
+ const args = projectNodeArgs(job.entry, "local-worker");
+ if ("error" in args)
+ return Promise.resolve({ ok: false, message: args.error });
+ return new Promise((done) => {
+ const child = spawn(process.execPath, args, {
+ cwd,
+ stdio: ["inherit", "inherit", "inherit", "ipc"],
+ });
+ let result: LocalResult | undefined;
+ child.on("message", (message: LocalResult) => {
+ result = message;
+ });
+ child.on("error", (error) => done({ ok: false, message: error.message }));
+ child.on("close", (code, signal) =>
+ done(
+ result ??
+ (signal === "SIGINT" || code === 130
+ ? { ok: false, message: "Stopped." }
+ : {
+ ok: false,
+ message: `The ${job.mode} exited without a result (code ${code}, signal ${signal}).`,
+ }),
+ ),
+ );
+ child.send(job);
+ });
+}
diff --git a/packages/framefields/src/cli/pick-composition.test.ts b/packages/framefields/src/cli/pick-composition.test.ts
new file mode 100644
index 00000000..84d2b0fa
--- /dev/null
+++ b/packages/framefields/src/cli/pick-composition.test.ts
@@ -0,0 +1,51 @@
+import { describe, expect, it } from "vitest";
+import { Composition } from "../index.js";
+import { pickComposition } from "./pick-composition.js";
+
+const comp = (width: number) =>
+ new Composition({ width, height: 36, fps: 10, durationFrames: 10 });
+
+describe("pickComposition", () => {
+ it("takes a Composition, or calls a builder with the render's args", async () => {
+ const film = comp(64);
+ expect(
+ await pickComposition({ buildFilm: film }, { export: "buildFilm" }),
+ ).toBe(film);
+ const built = await pickComposition(
+ { build: (args: { width: number }) => comp(args.width) },
+ { export: "build", args: { width: 128 } },
+ );
+ expect(built.toSpec().width).toBe(128);
+ });
+
+ it("picks one of several by select, as the cloud worker does", async () => {
+ const a = comp(64);
+ const b = comp(96);
+ expect(
+ await pickComposition(
+ { cuts: () => ({ wide: a, tall: b }) },
+ { export: "cuts", select: "tall" },
+ ),
+ ).toBe(b);
+ expect(
+ await pickComposition(
+ { plan: { outputs: [{ name: "teaser", composition: a }] } },
+ { export: "plan" },
+ ),
+ ).toBe(a);
+ await expect(
+ pickComposition({ cuts: { wide: a, tall: b } }, { export: "cuts" }),
+ ).rejects.toThrow(
+ 'returns several compositions (wide, tall): name one with "select"',
+ );
+ });
+
+ it("names a missing or wrong export", async () => {
+ await expect(
+ pickComposition({ other: 1 }, { export: "buildFilm" }),
+ ).rejects.toThrow('no export named "buildFilm". Exports: other');
+ await expect(
+ pickComposition({ buildFilm: 42 }, { export: "buildFilm" }),
+ ).rejects.toThrow("must be a Composition");
+ });
+});
diff --git a/packages/framefields/src/cli/pick-composition.ts b/packages/framefields/src/cli/pick-composition.ts
new file mode 100644
index 00000000..40e6fd44
--- /dev/null
+++ b/packages/framefields/src/cli/pick-composition.ts
@@ -0,0 +1,63 @@
+import type { Composition } from "../index.js";
+
+export interface PickOptions {
+ export: string;
+ args?: unknown;
+ select?: string;
+}
+
+/**
+ * The composition an export yields, read the way the cloud worker reads it:
+ * a Composition, a function returning one (called with `args`), or several
+ * by name (a record, or `{ outputs: [{ name, composition }] }`) picked with
+ * `select`.
+ */
+export async function pickComposition(
+ mod: Record<string, unknown>,
+ job: PickOptions,
+): Promise<Composition> {
+ if (!(job.export in mod))
+ throw new Error(
+ `The module has no export named "${job.export}". Exports: ${Object.keys(mod).join(", ") || "none"}.`,
+ );
+ let value = mod[job.export];
+ if (typeof value === "function" && !isComposition(value))
+ value = await (value as (args: unknown) => unknown)(job.args);
+ if (isComposition(value)) return value;
+ const named = namedOutputs(value);
+ if (!named)
+ throw new Error(
+ `Export "${job.export}" must be a Composition, a function returning one, or compositions by name.`,
+ );
+ const names = Object.keys(named);
+ const pick = job.select ?? (names.length === 1 ? names[0] : undefined);
+ if (!pick || !named[pick])
+ throw new Error(
+ `Export "${job.export}" returns several compositions (${names.join(", ")}): name one with "select".`,
+ );
+ return named[pick];
+}
+
+function namedOutputs(value: unknown): Record<string, Composition> | undefined {
+ if (typeof value !== "object" || value === null) return undefined;
+ const outputs = (value as { outputs?: unknown }).outputs;
+ const entries = Array.isArray(outputs)
+ ? outputs.map((o: { name?: string; composition?: unknown }, i) => [
+ o?.name ?? `output-${i}`,
+ o?.composition,
+ ])
+ : Object.entries(value);
+ if (!entries.length || !entries.every(([, c]) => isComposition(c)))
+ return undefined;
+ return Object.fromEntries(entries) as Record<string, Composition>;
+}
+
+/** Duck-typed: the project may load its own copy of framefields. */
+function isComposition(value: unknown): value is Composition {
+ return (
+ typeof value === "object" &&
+ value !== null &&
+ typeof (value as Composition).renderVideo === "function" &&
+ typeof (value as Composition).toSpec === "function"
+ );
+}
diff --git a/packages/framefields/src/cli/project-node.ts b/packages/framefields/src/cli/project-node.ts
new file mode 100644
index 00000000..3b585ee6
--- /dev/null
+++ b/packages/framefields/src/cli/project-node.ts
@@ -0,0 +1,37 @@
+/**
+ * Node arguments to run a CLI worker against the user's project: the
+ * project's own tsx loader for a TypeScript entry (TypeScript belongs to the
+ * consumer project; init's scaffold has it), and the worker script, from
+ * source when the CLI runs from source.
+ */
+import { createRequire } from "node:module";
+import { resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+export function projectNodeArgs(
+ entry: string,
+ worker: "check-worker" | "local-worker",
+): string[] | { error: string } {
+ const source = import.meta.url.endsWith(".ts");
+ const args = source ? ["--conditions=development"] : [];
+ if (source || /\.[cm]?tsx?$/.test(entry)) {
+ try {
+ const require = createRequire(resolve("package.json"));
+ args.push("--import", pathToFileURL(require.resolve("tsx")).href);
+ } catch {
+ return {
+ error:
+ "Install the project's tsx dev dependency to load a TypeScript entry.",
+ };
+ }
+ }
+ args.push(
+ fileURLToPath(
+ new URL(
+ source ? `./${worker}.ts` : `./cli/${worker}.mjs`,
+ import.meta.url,
+ ),
+ ),
+ );
+ return args;
+}
diff --git a/packages/framefields/src/cli/templates.ts b/packages/framefields/src/cli/templates.ts
index b453bd37..ed3ba684 100644
--- a/packages/framefields/src/cli/templates.ts
+++ b/packages/framefields/src/cli/templates.ts
@@ -32,8 +32,8 @@ export const SCRIPTS: Record<string, string> = {
"check:render": "tsc --noEmit -p . && framefields check film --render --json",
frames: "tsx src/render.ts frames",
grid: "tsx src/render.ts grid",
- preview: "tsx src/render.ts preview",
- render: "tsx src/render.ts",
+ preview: "framefields preview film",
+ render: "framefields render film",
"render:cloud": "framefields render film --cloud",
};
@@ -196,44 +196,30 @@ export async function buildFilm(): Promise<Composition> {
export const RENDER_TS = `import { existsSync } from "node:fs";
import fs from "node:fs/promises";
import path from "node:path";
-import { HeadlessMediaRenderer, frameCount, startPreview } from "framefields";
+import { HeadlessMediaRenderer, frameCount } from "framefields";
import { buildFilm } from "./film.js";
+// Quick looks at the film: \`npm run frames -- 0 30 60\` and \`npm run grid\`.
+// \`npm run render\` and \`npm run preview\` use the "film" render in
+// framefields.json instead (\`framefields render film\`, \`framefields preview film\`).
+
// Optional settings such as FRAMEFIELDS_API_KEY (see .env.example).
const ENV = path.resolve(import.meta.dirname, "../.env");
if (existsSync(ENV)) process.loadEnvFile(ENV);
const OUT = path.resolve(import.meta.dirname, "../output");
// \`npm run frames -- 0 30\` needs the \`--\`; pnpm passes it through: drop it.
-const [mode = "video", ...args] = process.argv
+const [mode = "frames", ...args] = process.argv
.slice(2)
.filter((a) => a !== "--");
-if (mode === "preview") {
- // The page runs film.ts itself and renders it with WebGPU in the browser.
- const session = await startPreview({
- entry: new URL("./film.ts", import.meta.url),
- export: "buildFilm",
- });
- console.log(\`Preview at \${session.url}\`);
- await session.closed; // until its tab closes or the next preview replaces it
- process.exit(0);
-}
-
const film = await buildFilm();
await fs.mkdir(OUT, { recursive: true });
-if (mode === "frames") {
- const renderer = new HeadlessMediaRenderer();
- for (const frame of (args.length ? args : ["0"]).map(Number)) {
- const png = await film.renderFrame({ frame, renderer });
- const file = path.join(OUT, \`f\${String(frame).padStart(4, "0")}.png\`);
- await fs.writeFile(file, png);
- console.log(\`Wrote \${path.relative(process.cwd(), file)}\`);
- }
-} else if (mode === "grid") {
+if (mode === "grid") {
+ const last = frameCount(film.durationMs ?? (await film.computeDuration()), film.fps) - 1;
const png = await film.renderFrameGrid({
- frames: args.length ? args.map(Number) : [...new Set([0, Math.floor((frameCount(film.durationMs ?? await film.computeDuration(), film.fps) - 1) / 2), frameCount(film.durationMs ?? await film.computeDuration(), film.fps) - 1])],
+ frames: args.length ? args.map(Number) : [...new Set([0, Math.floor(last / 2), last])],
columns: 4,
cellWidth: 480,
showLabels: true,
@@ -241,12 +227,13 @@ if (mode === "frames") {
await fs.writeFile(path.join(OUT, "grid.png"), png);
console.log("Wrote output/grid.png");
} else {
- const result = await film.renderVideo({
- outputPath: path.join(OUT, "output.mp4"),
- quality: "high",
- });
- await result.cleanup?.();
- console.log(\`Exported \${result.filePath}\`);
+ const renderer = new HeadlessMediaRenderer();
+ for (const frame of (args.length ? args : ["0"]).map(Number)) {
+ const png = await film.renderFrame({ frame, renderer });
+ const file = path.join(OUT, \`f\${String(frame).padStart(4, "0")}.png\`);
+ await fs.writeFile(file, png);
+ console.log(\`Wrote \${path.relative(process.cwd(), file)}\`);
+ }
}
// Native GPU and encoder threads keep Node alive; always exit explicitly.
@@ -263,7 +250,7 @@ ${run("typecheck")}
${run("frames")} -- 0 30 60 # PNGs in output/
${run("grid")} # a contact sheet of the motion
${run("preview")} # play it in the browser
-${run("render")} # output/output.mp4
+${run("render")} # output/film.mp4
${run("render:cloud")} # on cloud GPUs, from the pushed commit
\`\`\`
diff --git a/packages/framefields/src/preview/index.ts b/packages/framefields/src/preview/index.ts
index f976220d..a377e56b 100644
--- a/packages/framefields/src/preview/index.ts
+++ b/packages/framefields/src/preview/index.ts
@@ -6,6 +6,8 @@ import type { AddressInfo } from "node:net";
import path from "node:path";
import { fileURLToPath, pathToFileURL } from "node:url";
import type { VirtualMediaData } from "@framefields/core";
+import { type AssetLocator, openAssetLocator } from "@framefields/storage";
+import { inputStore } from "@framefields/webgpu-renderers";
import { encodeStereoWav } from "../audio/index.js";
import { HeadlessMediaRenderer } from "../renderer/index.js";
import {
@@ -191,6 +193,18 @@ export async function startPreview(
// Changes run one at a time: each reads and rewrites notes.json.
let noteQueue: Promise<unknown> = Promise.resolve();
+ // Assets framefields.json pins but that aren't on disk (an agent's
+ // sandbox, a fresh clone) stream from their bucket: the page is
+ // redirected there, and the soundtrack mix reads them over HTTP.
+ const assets = await openAssetLocator(path.dirname(entry)).catch(
+ (err: unknown) => {
+ say(`pinned assets are off: ${(err as Error).message}`);
+ return undefined;
+ },
+ );
+ if (assets) inputStore.setMissingMediaResolver((file) => assets.url(file));
+ const unreadable = new Set<string>();
+
const target = await loadTarget(entry, exportName);
const meta = await resolveMeta(target, title, session, notes?.dir ?? null);
// The project's own code, bundled against the browser engine; the engine
@@ -286,6 +300,7 @@ export async function startPreview(
if (reason === "replaced") say("stopped: a newer preview took over");
for (const client of sseClients) client.end();
sseClients.clear();
+ if (assets) inputStore.setMissingMediaResolver();
server.close(() => {
resolve();
resolveClosed(reason);
@@ -353,7 +368,7 @@ export async function startPreview(
if (roots.some((r) => isInside(r, file))) {
size = await fs.promises.stat(file).then(
(st) => (st.isFile() ? st.size : -1),
- () => -1,
+ () => assets?.entry(file)?.size ?? -1,
);
}
sendJson(res, 200, { exists: size >= 0, size: Math.max(0, size) });
@@ -492,6 +507,11 @@ export async function startPreview(
await sendFile(req, res, file);
return;
}
+ if (
+ assets &&
+ (await redirectToBucket(res, assets, file, unreadable, say))
+ )
+ return;
}
sendJson(res, 404, { error: "not found" });
} catch (err) {
@@ -691,6 +711,35 @@ const CONTENT_TYPES: Record<string, string> = {
".txt": "text/plain; charset=utf-8",
};
+/**
+ * Sends the page to the bucket for a pinned asset that isn't on disk. The
+ * bucket must allow this page's origin (CORS): the engine reads media with
+ * `fetch`. True when it answered.
+ */
+async function redirectToBucket(
+ res: http.ServerResponse,
+ assets: AssetLocator,
+ file: string,
+ unreadable: Set<string>,
+ say: (line: string) => void,
+): Promise<boolean> {
+ if (!assets.entry(file)) return false;
+ const url = await assets.url(file);
+ if (url) {
+ res.writeHead(302, { location: url, "cache-control": "no-store" });
+ res.end();
+ return true;
+ }
+ const rel = path.relative(assets.root, file);
+ if (!unreadable.has(rel)) {
+ unreadable.add(rel);
+ say(
+ `${rel} is pinned on a private remote and there are no keys here: set its FRAMEFIELDS_STORAGE_* keys, give the remote a publicUrl, or \`npx framefields assets pull\``,
+ );
+ }
+ return false;
+}
+
/** Serves a file, with byte ranges so video can seek without loading it whole. */
async function sendFile(
req: http.IncomingMessage,
diff --git a/packages/framefields/src/preview/preview.test.ts b/packages/framefields/src/preview/preview.test.ts
index 25c160d2..ffe66b11 100644
--- a/packages/framefields/src/preview/preview.test.ts
+++ b/packages/framefields/src/preview/preview.test.ts
@@ -168,6 +168,75 @@ describe("startPreview", () => {
}
});
+ it("sends the page to the bucket for pinned assets that aren't on disk", async () => {
+ const project = await fs.promises.mkdtemp(
+ path.join(os.tmpdir(), "gf-project-"),
+ );
+ const sha = "ab".repeat(32);
+ const raw = "cd".repeat(32);
+ process.env.FRAMEFIELDS_STORAGE_RAW_ACCESS_KEY_ID = "id";
+ process.env.FRAMEFIELDS_STORAGE_RAW_SECRET_ACCESS_KEY = "secret";
+ try {
+ const src = path.join(project, "src");
+ await fs.promises.mkdir(src, { recursive: true });
+ await fs.promises.writeFile(path.join(project, "package.json"), "{}");
+ const endpoint = "https://acct.r2.cloudflarestorage.com";
+ await fs.promises.writeFile(
+ path.join(project, "framefields.json"),
+ JSON.stringify({
+ storage: {
+ default: "media",
+ remotes: {
+ media: {
+ endpoint,
+ bucket: "films",
+ publicUrl: "https://media.example.com",
+ },
+ raw: { endpoint, bucket: "raw" },
+ },
+ },
+ assets: {
+ "assets/intro.mp4": { sha256: sha, size: 1234 },
+ "assets/raw.mov": { sha256: raw, size: 99, remote: "raw" },
+ },
+ }),
+ );
+ const comp = path.join(src, "comp.ts");
+ await fs.promises.writeFile(
+ comp,
+ "export default function build() { return { fps: 10, durationMs: 1000, width: 64, height: 36 }; }",
+ );
+ const session = await start({ entry: comp }, { open: false, port: 0 });
+ const get = (rel: string) =>
+ fetch(`${session.url}@fs${path.join(project, rel)}`, {
+ redirect: "manual",
+ });
+ const intro = await get("assets/intro.mp4");
+ expect(intro.status).toBe(302);
+ expect(intro.headers.get("location")).toBe(
+ `https://media.example.com/sha256/ab/${sha}`,
+ );
+ const signed = new URL(
+ (await get("assets/raw.mov")).headers.get("location") ?? "",
+ );
+ expect(signed.origin + signed.pathname).toBe(
+ `${endpoint}/raw/sha256/cd/${raw}`,
+ );
+ expect(signed.searchParams.get("X-Amz-Signature")).toMatch(
+ /^[0-9a-f]{64}$/,
+ );
+ expect((await get("assets/other.mp4")).status).toBe(404);
+ const stat = await fetch(
+ `${session.url}@framefields/stat?path=${encodeURIComponent(path.join(project, "assets/intro.mp4"))}`,
+ ).then((r) => r.json());
+ expect(stat).toEqual({ exists: true, size: 1234 });
+ } finally {
+ delete process.env.FRAMEFIELDS_STORAGE_RAW_ACCESS_KEY_ID;
+ delete process.env.FRAMEFIELDS_STORAGE_RAW_SECRET_ACCESS_KEY;
+ await fs.promises.rm(project, { recursive: true, force: true });
+ }
+ });
+
it("names a missing export", async () => {
await expect(
startPreview({ entry, export: "film" }, { open: false, port: 0 }),
diff --git a/packages/framefields/tsdown.config.ts b/packages/framefields/tsdown.config.ts
index c1f0b272..cf27d889 100644
--- a/packages/framefields/tsdown.config.ts
+++ b/packages/framefields/tsdown.config.ts
@@ -19,6 +19,7 @@ export default defineConfig({
"src/storage/index.ts",
"src/cli.ts",
"src/cli/check-worker.ts",
+ "src/cli/local-worker.ts",
],
format: ["esm"],
clean: true,
diff --git a/packages/storage/src/index.ts b/packages/storage/src/index.ts
index 202bc420..0637f56e 100644
--- a/packages/storage/src/index.ts
+++ b/packages/storage/src/index.ts
@@ -17,6 +17,13 @@ export {
hashFile,
redactQuery,
} from "./files.js";
+export {
+ type AssetLocator,
+ findProjectDir,
+ openAssetLocator,
+ type ProjectManifest,
+ readProjectManifest,
+} from "./locate.js";
export {
type AssetEntry,
type AssetManifest,
diff --git a/packages/storage/src/locate.ts b/packages/storage/src/locate.ts
new file mode 100644
index 00000000..581bfbad
--- /dev/null
+++ b/packages/storage/src/locate.ts
@@ -0,0 +1,112 @@
+/**
+ * Finding a project's pinned assets from file paths: what a preview or an
+ * engine asks for is an absolute path, and a pinned file that isn't on disk
+ * is read from its bucket instead.
+ */
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { dirname, join, relative, sep } from "node:path";
+import { Bucket, credentialsFromEnv } from "./bucket.js";
+import {
+ type AssetEntry,
+ type AssetManifest,
+ ManifestError,
+ parseAssets,
+ parseStorage,
+ pickRemote,
+ readUrl,
+ type StorageConfig,
+} from "./manifest.js";
+
+const FILE = "framefields.json";
+
+export interface ProjectManifest {
+ storage?: StorageConfig;
+ assets: AssetManifest;
+}
+
+/** The nearest folder at or above `dir` holding a framefields.json. */
+export function findProjectDir(dir: string): string | undefined {
+ for (let at = dir; ; at = dirname(at)) {
+ if (existsSync(join(at, FILE))) return at;
+ if (dirname(at) === at) return undefined;
+ }
+}
+
+/** The `storage` and `assets` of the project at `dir`; undefined without assets. */
+export async function readProjectManifest(
+ dir: string,
+): Promise<ProjectManifest | undefined> {
+ const file = join(dir, FILE);
+ if (!existsSync(file)) return undefined;
+ let raw: { storage?: unknown; assets?: unknown };
+ try {
+ raw = JSON.parse(await readFile(file, "utf8")) as typeof raw;
+ } catch (err) {
+ throw new ManifestError(
+ `${FILE} is not valid JSON: ${(err as Error).message}`,
+ );
+ }
+ if (raw.assets === undefined) return undefined;
+ const storage =
+ raw.storage === undefined ? undefined : parseStorage(raw.storage);
+ return { storage, assets: parseAssets(raw.assets, storage) };
+}
+
+export interface AssetLocator {
+ /** The project folder (where framefields.json is). */
+ readonly root: string;
+ /** The pinned entry for an absolute path, if the project pins it. */
+ entry(file: string): AssetEntry | undefined;
+ /**
+ * A URL to read a pinned file from: its public domain or own URL, else
+ * a GET signed with the remote's keys from the environment. Undefined
+ * when the file isn't pinned, or is private and there are no keys.
+ */
+ url(file: string): Promise<string | undefined>;
+}
+
+/** Signatures last 6 h and are reused for 5, so long sessions keep working. */
+const SIGNED_SEC = 6 * 3600;
+const REUSE_MS = 5 * 3600 * 1000;
+
+/**
+ * Pinned-asset lookup for the project at or above `dir`, or undefined when
+ * it pins none.
+ */
+export async function openAssetLocator(
+ dir: string,
+ options: {
+ env?: Readonly<Record<string, string | undefined>>;
+ fetch?: typeof fetch;
+ } = {},
+): Promise<AssetLocator | undefined> {
+ const root = findProjectDir(dir);
+ const manifest = root && (await readProjectManifest(root));
+ if (!root || !manifest) return undefined;
+ const signed = new Map<string, { url: string; at: number }>();
+ const entry = (file: string) => {
+ const rel = relative(root, file).split(sep).join("/");
+ return rel.startsWith("../") ? undefined : manifest.assets[rel];
+ };
+ return {
+ root,
+ entry,
+ async url(file) {
+ const pinned = entry(file);
+ if (!pinned) return undefined;
+ const open = readUrl(pinned, manifest.storage);
+ if (open) return open;
+ const cached = signed.get(pinned.sha256);
+ if (cached && Date.now() - cached.at < REUSE_MS) return cached.url;
+ const { name, remote } = pickRemote(manifest.storage, pinned.remote);
+ const keys = credentialsFromEnv(name, options.env);
+ if (!keys) return undefined;
+ const url = await new Bucket(remote, keys, {
+ fetch: options.fetch,
+ }).presign(pinned.sha256, SIGNED_SEC);
+ signed.set(pinned.sha256, { url, at: Date.now() });
+ return url;
+ },
+ };
+}
diff --git a/packages/webgpu-renderers/src/input-store.ts b/packages/webgpu-renderers/src/input-store.ts
index aa8a23d3..081840d8 100644
--- a/packages/webgpu-renderers/src/input-store.ts
+++ b/packages/webgpu-renderers/src/input-store.ts
@@ -50,11 +50,29 @@ async function assertReadableFile(
}
}
+/**
+ * Where to read a local media file that isn't on disk: a URL for it (a
+ * project's asset pinned on a bucket), or undefined.
+ */
+export type MissingMediaResolver = (
+ filePath: string,
+) => Promise<string | undefined>;
+
class InputStore {
private store = new Map<
string,
{ promise: Promise<Input>; refCount: number }
>();
+ private resolveMissing?: MissingMediaResolver;
+
+ /**
+ * Reads local files that are missing from disk from the URL `resolver`
+ * gives, with HTTP range requests, so a clip pinned on a bucket plays
+ * without being downloaded. Unset with no argument.
+ */
+ setMissingMediaResolver(resolver?: MissingMediaResolver): void {
+ this.resolveMissing = resolver;
+ }
async acquire(url: string): Promise<Input> {
if (!url) throw new Error("Cannot acquire Input for empty URL");
@@ -73,10 +91,7 @@ class InputStore {
| InstanceType<typeof FilePathSource>
| InstanceType<typeof UrlSource>;
if (filePath !== null) {
- // FilePathSource opens lazily; check now so a bad path fails
- // with its name instead of deep inside the first decode.
- await assertReadableFile(filePath, url);
- source = new FilePathSource(filePath);
+ source = await this.localSource(filePath, url);
} else {
source = new UrlSource(resolvedUrl);
}
@@ -114,6 +129,24 @@ class InputStore {
}
}
+ private async localSource(
+ filePath: string,
+ url: string,
+ ): Promise<
+ InstanceType<typeof FilePathSource> | InstanceType<typeof UrlSource>
+ > {
+ try {
+ // FilePathSource opens lazily; check now so a bad path fails
+ // with its name instead of deep inside the first decode.
+ await assertReadableFile(filePath, url);
+ return new FilePathSource(filePath);
+ } catch (err) {
+ const remote = await this.resolveMissing?.(filePath);
+ if (remote) return new UrlSource(remote);
+ throw err;
+ }
+ }
+
release(url: string): void {
if (!url) return;
const resolvedUrl = resolveInputUrl(url, isNodeRuntime());
diff --git a/plugins/framefields/skills/framefields-render/SKILL.md b/plugins/framefields/skills/framefields-render/SKILL.md
index 4ce3327b..46a6cbe6 100644
--- a/plugins/framefields/skills/framefields-render/SKILL.md
+++ b/plugins/framefields/skills/framefields-render/SKILL.md
@@ -354,12 +354,17 @@ CLI Usage:
tsx src/render.ts frames 0 18 36 72
# Live player for the user (run in the background; re-run after changes and the open tab reloads):
-tsx src/render.ts preview
+npx framefields preview film
-# Render full master video:
-tsx src/render.ts
+# Render the full video on this machine, to the render's output in framefields.json:
+npx framefields render film
+
+# The same render on framefields cloud GPUs, to the same file:
+npx framefields render film --cloud
```
+`framefields render <name>` and `framefields preview <name>` load the module with the project's own tsx and framefields, like the cloud worker, and call the export with the render's `args` (and `select`); the preview calls it without them. A local render downloads pinned assets that are missing first; the preview streams them from their bucket.
+
### Reading render progress
`renderVideo` logs its own progress to stderr, one short `[framefields]` line per event. The log stays short however long the film is, about 15 lines for an export:
diff --git a/plugins/framefields/skills/framefields/SKILL.md b/plugins/framefields/skills/framefields/SKILL.md
index 6503656f..46098e2b 100644
--- a/plugins/framefields/skills/framefields/SKILL.md
+++ b/plugins/framefields/skills/framefields/SKILL.md
@@ -170,33 +170,19 @@ export async function buildFilm(): Promise<Composition> {
```
```typescript
-// src/render.ts
+// src/render.ts: quick looks (frames, a contact sheet). Full renders and the preview use the CLI.
import fs from "node:fs/promises";
import path from "node:path";
-import { HeadlessMediaRenderer, startPreview } from "framefields";
+import { HeadlessMediaRenderer } from "framefields";
import { buildFilm } from "./film.js";
const OUT = path.resolve(import.meta.dirname, "../output");
-const [mode = "video", ...args] = process.argv.slice(2);
-
-if (mode === "preview") {
- // The page runs film.ts itself and renders it with WebGPU in the browser.
- const session = await startPreview({ entry: new URL("./film.ts", import.meta.url), export: "buildFilm" });
- console.log(`Preview at ${session.url}`);
- await session.closed; // until its tab closes or the next preview replaces it
- process.exit(0);
-}
+const [mode = "frames", ...args] = process.argv.slice(2);
const film = await buildFilm();
await fs.mkdir(OUT, { recursive: true });
-if (mode === "frames") {
- const renderer = new HeadlessMediaRenderer();
- for (const frame of args.map(Number)) {
- const png = await film.renderFrame({ frame, renderer });
- await fs.writeFile(path.join(OUT, `f${String(frame).padStart(4, "0")}.png`), png);
- }
-} else if (mode === "grid") {
+if (mode === "grid") {
const png = await film.renderFrameGrid({
frames: args.length ? args.map(Number) : [0, 10, 20, 30, 45, 60, 75, 89],
columns: 4,
@@ -205,12 +191,11 @@ if (mode === "frames") {
});
await fs.writeFile(path.join(OUT, "grid.png"), png);
} else {
- const result = await film.renderVideo({
- outputPath: path.join(OUT, "output.mp4"),
- quality: "high",
- });
- await result.cleanup?.();
- console.log(`Exported ${result.filePath}`);
+ const renderer = new HeadlessMediaRenderer();
+ for (const frame of (args.length ? args : ["0"]).map(Number)) {
+ const png = await film.renderFrame({ frame, renderer });
+ await fs.writeFile(path.join(OUT, `f${String(frame).padStart(4, "0")}.png`), png);
+ }
}
// Native GPU and encoder threads keep Node alive; always exit explicitly.
@@ -224,12 +209,14 @@ Add scripts to `package.json`:
"typecheck": "tsc --noEmit -p .",
"frames": "tsx src/render.ts frames",
"grid": "tsx src/render.ts grid",
- "preview": "tsx src/render.ts preview",
- "render": "tsx src/render.ts",
+ "preview": "framefields preview film",
+ "render": "framefields render film",
"render:cloud": "framefields render film --cloud"
}
```
+`framefields render film`, `framefields render film --cloud` and `framefields preview film` all read the `film` render below, so a render writes the same file wherever it runs: switching between this machine and the cloud is the `--cloud` flag, nothing else. Flags (`--export`, `--select`, `--codec`, `--quality`, `--output`) override the render's fields either way.
+
`framefields.json` names what the project renders; `film` is the scaffold's. Add an entry per cut (teaser, vertical edit) so the CLI, `framefields check` and the dashboard pick it by name:
```json
@@ -267,7 +254,11 @@ Footage, audio, Lottie files, LUTs and generated media are too big for plain git
3. `npx framefields assets add assets/footage` hashes the files (a folder means every file in it), uploads what the bucket lacks, records them under `assets` and adds them to `.gitignore`. Commit `framefields.json` and `.gitignore`. Adding a changed file again records the new version.
4. In a fresh clone or container, `npx framefields assets pull` downloads what's missing and checks every byte; it leaves files changed locally alone unless `--overwrite`. `assets status` lists each asset as `ok`, `missing` or `changed`; `assets push` re-uploads what the bucket lacks.
-Code references assets by path as usual (`Layer.video("assets/footage/intro.mp4")`); nothing in the film changes. A missing pinned file makes `framefields check` say to run `assets pull`.
+Code references assets by path as usual (`Layer.video("assets/footage/intro.mp4")`); nothing in the film changes. Where the files aren't on disk (a fresh clone, a cloud agent's sandbox):
+
+- `framefields preview` streams them from the bucket: the page is redirected to the remote's `publicUrl` (or a URL signed with the remote's keys), so nothing is downloaded into the sandbox. The bucket needs a CORS rule allowing the preview's origin; see the assets guide (https://framefields.dev/docs/guides/assets/#preview-from-the-bucket).
+- `framefields render` downloads the missing ones first (`assets pull`), then renders.
+- `framefields check` says to run `assets pull`.
**Or Git LFS**, when the project already uses it or there's no bucket. `npx framefields init` writes the LFS `.gitattributes`. In fresh clones LFS media are ~130-byte pointer files that decode as blank frames, so run `git lfs pull` first, and never add `*.mp4` to `.gitignore` for LFS-tracked footage. Every clone and every cloud render worker downloads LFS objects from the git host, which bills that bandwidth to the repo owner; a bucket with no egress fees avoids it.