Skip to content

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

8.6 KB
Raw Blame
/**
 * The files `framefields init` writes: the project layout the framefields
 * setup skill describes. `film.ts` only builds; `render.ts` renders frames,
 * a grid, the live preview or the video; `theme.ts` holds the numbers.
 */
import type { RenderSpec } from "./config.js";

/**
 * Packages with install scripts. framefields needs exactly one (skia-canvas
 * downloads its native binary); the others work without theirs.
 */
const ALLOWED_SCRIPTS = ["skia-canvas"];
const DENIED_SCRIPTS = [
	"sharp",
	"webgpu",
	"onnxruntime-node",
	"node-av",
	"esbuild",
	"protobufjs",
];

/** Dev tools the scripts use, at versions the scaffold is tested with. */
export const DEV_DEPENDENCIES: Record<string, string> = {
	"@types/node": "^24.1.0",
	tsx: "^4.20.3",
	typescript: "^5.8.3",
};

export const SCRIPTS: Record<string, string> = {
	typecheck: "tsc --noEmit -p .",
	check: "tsc --noEmit -p . && framefields check film --json",
	"check:render": "tsc --noEmit -p . && framefields check film --render --json",
	frames: "tsx src/render.ts frames",
	grid: "tsx src/render.ts grid",
	preview: "framefields preview film",
	render: "framefields render film",
	"render:cloud": "framefields render film --cloud",
};

/** The named render `init` records in framefields.json. */
export function defaultRenders(name: string): Record<string, RenderSpec> {
	return {
		film: {
			title: name,
			entry: "src/film.ts",
			export: "buildFilm",
			workers: "auto",
			output: "output/film.mp4",
		},
	};
}

/**
 * The `package.json` fields a framefields project needs. npm reads
 * `allowScripts`, pnpm its `pnpm` block, bun `trustedDependencies`.
 */
export function packageFields(o: {
	framefieldsVersion: string;
	packageManager?: string;
}) {
	return {
		type: "module",
		...(o.packageManager && { packageManager: o.packageManager }),
		scripts: SCRIPTS,
		dependencies: { framefields: `^${o.framefieldsVersion}` },
		devDependencies: DEV_DEPENDENCIES,
		allowScripts: Object.fromEntries([
			...ALLOWED_SCRIPTS.map((p) => [p, true]),
			...DENIED_SCRIPTS.map((p) => [p, false]),
		]),
		pnpm: {
			onlyBuiltDependencies: ALLOWED_SCRIPTS,
			ignoredBuiltDependencies: DENIED_SCRIPTS,
		},
		trustedDependencies: ALLOWED_SCRIPTS,
	};
}

export const TSCONFIG = `${JSON.stringify(
	{
		compilerOptions: {
			module: "NodeNext",
			moduleResolution: "NodeNext",
			target: "ES2022",
			strict: true,
			skipLibCheck: true,
			noEmit: true,
			types: ["node"],
		},
		include: ["src/**/*"],
	},
	null,
	"\t",
)}\n`;

/** Lines `init` makes sure `.gitignore` has. */
export const GITIGNORE = [
	"node_modules/",
	"output/",
	"scratch/",
	".DS_Store",
	".env",
];

/** Where the AI gateway's keys come from. */
export const AI_DASHBOARD = "https://framefields.dev/dashboard";

/** Optional settings; `render.ts` loads `.env` when there is one. Commit this, not `.env`. */
export const ENV_EXAMPLE = `# Copy to .env (git-ignored). Everything here is optional.

# framefields AI gateway: generate images, video, music, voice and 3D from code.
# Create a key at ${AI_DASHBOARD}
FRAMEFIELDS_API_KEY=
`;

/** Media, LUTs and fonts go to Git LFS; renders stay out of Git. */
export const GITATTRIBUTES = [
	"assets/**/*.mp4 filter=lfs diff=lfs merge=lfs -text",
	"assets/**/*.mov filter=lfs diff=lfs merge=lfs -text",
	"assets/**/*.webm filter=lfs diff=lfs merge=lfs -text",
	"assets/**/*.mp3 filter=lfs diff=lfs merge=lfs -text",
	"assets/**/*.wav filter=lfs diff=lfs merge=lfs -text",
	"assets/**/*.cube filter=lfs diff=lfs merge=lfs -text",
	"assets/**/*.lottie filter=lfs diff=lfs merge=lfs -text",
	"assets/fonts/**/*.ttf filter=lfs diff=lfs merge=lfs -text",
	"assets/fonts/**/*.otf filter=lfs diff=lfs merge=lfs -text",
];

export const THEME_TS = `import { registerFonts as registerInstalledFonts } from "./components/fonts.js";

export const W = 1920;
export const H = 1080;
export const FPS = 30;
export const INK = "#0E0D0C";
export const PAPER = "#EEE9E0";
/** Installed by \`framefields init\` (assets/fonts), registered below. */
export const SANS = "Inter";
export const MONO = "JetBrains Mono";

/**
 * Register the film's fonts. Fonts framefields installed
 * (\`npx framefields fonts add <role>\`) come from the generated
 * components/fonts.ts; register any others here with \`FontManager.register\`.
 */
export async function registerFonts(): Promise<void> {
	await registerInstalledFonts();
}
`;

export const FILM_TS = `import { Composition, Layer, LayerAnimation } from "framefields";
import { FPS, H, INK, PAPER, registerFonts, SANS, W } from "./theme.js";

const DURATION = 3 * FPS; // frames

/** Builds the film. Only builds: no rendering or writes, so tests, the preview and renders share it. */
export async function buildFilm(): Promise<Composition> {
	// Fonts must be registered before any text layer is built.
	await registerFonts();

	const film = new Composition({
		width: W,
		height: H,
		fps: FPS,
		durationMs: (DURATION / FPS) * 1000,
		backgroundColor: INK,
	});

	film.add(
		Layer.text("Hello, framefields", {
			id: "title",
			position: "absolute",
			x: 0,
			y: H / 2 - 60,
			width: W,
			height: 120,
			fontFamily: SANS,
			fontSize: 96,
			fontWeight: 700,
			fill: PAPER,
			align: "center",
		}).animate(
			LayerAnimation.create()
				.fadeIn(0, 20, "power2.out")
				.fromTo("y", H / 2 - 20, H / 2 - 60, {
					start: 0,
					end: 30,
					ease: "expo.out",
				}),
		),
	);

	return film;
}
`;

export const RENDER_TS = `import { existsSync } from "node:fs";
import fs from "node:fs/promises";
import path from "node:path";
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 = "frames", ...args] = process.argv
	.slice(2)
	.filter((a) => a !== "--");

const film = await buildFilm();
await fs.mkdir(OUT, { recursive: true });

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(last / 2), last])],
		columns: 4,
		cellWidth: 480,
		showLabels: true,
	});
	await fs.writeFile(path.join(OUT, "grid.png"), png);
	console.log("Wrote output/grid.png");
} else {
	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.
process.exit(0);
`;

export function readme(name: string, run: (script: string) => string): string {
	return `# ${name}

A film built with [framefields](https://www.npmjs.com/package/framefields).

\`\`\`bash
${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/film.mp4
${run("render:cloud")}        # on cloud GPUs, from the pushed commit
\`\`\`

- \`framefields.json\` names the renders: \`film\` is \`buildFilm\` in \`src/film.ts\`. Add an
  entry under \`renders\` for each cut (a teaser, a vertical edit) and render or check it by
  name: \`npx framefields render teaser --cloud\`, \`npx framefields check teaser\`.
- \`src/film.ts\` builds the composition, \`src/theme.ts\` holds sizes, colors and fonts,
  \`src/render.ts\` renders it.
- \`npx framefields list\` shows ready-made components; \`npx framefields add <name>\` copies
  one into \`src/components/\`.
- Optional: the AI gateway generates images, video, music, voice and 3D from code. Copy
  \`.env.example\` to \`.env\` and set \`FRAMEFIELDS_API_KEY\` (keys at ${AI_DASHBOARD}).
- \`render:cloud\` renders on framefields' GPUs with the same key, and splits a long film
  across several (\`-- --plan\` shows workers, time and cost first). It renders the
  commit you pushed, not uncommitted changes.
- Footage, audio and fonts live in \`assets/\` and are tracked with Git LFS
  (\`git lfs install\` once per machine, \`git lfs pull\` after cloning).
`;
}