Compositing, motion graphics, and 3D for code-first video — one npm package that AI agents drive with code.
Documentation · Website · Models · Discord · Examples
Add to your agent
Teach Claude Code, Cursor, Codex, Copilot, Hermes, and 70+ others how to author, animate, and render compositions:
npx skills add gatewai-dev/framefieldsFramefields is built for coding agents. It packs the capabilities usually split across three desktop creative suites—Photoshop-style compositing & VFX, After Effects-style typography & motion graphics, and Blender-style 3D scenes & cameras—into a single lightweight npm package.
- Zero Headless-Browser Overhead — No Chromium, no Puppeteer, no DOM reflows, and no screenshot pipeline. Renders directly on native GPU hardware via Dawn / WebGPU / Metal / Vulkan.
- Deterministic & Frame-Accurate — Discrete sample points, absolute frame clocks, and frame-accurate audio BeatGrids. No floating timers, no drift.
- Agent-First Workflow — Your coding agent writes TypeScript, inspects rendered frame grids, and exports hardware-encoded MP4s headlessly.
Every frame is rendered by framefields directly from TypeScript in examples/. Click a still to watch on YouTube:
pnpm add framefieldsStarting a new film? framefields init sets up the whole project: package.json, TypeScript, a film.ts to edit and a render.ts to render it, assets/ with Git LFS, and the Inter, JetBrains Mono, and Noto Color Emoji fonts:
pnpm dlx framefields init my-film --install # or: npx framefields init my-film --install
cd my-film && pnpm frames -- 0 30 60 # first frames in output/Run it inside an existing project to add framefields there; it only fills in what's missing and never overwrites your files. It asks nothing, so it works in CI and on remote servers too.
Requirements: Node.js ≥ 22. Native GPU acceleration via WebGPU / Dawn (macOS Metal, Linux Vulkan, Windows D3D12). Machines without a dedicated GPU can render on the CPU via Mesa lavapipe on Linux or WARP on Windows (~10–12× slower than GPU; suitable for headless CI and test frames).
import { Composition, Layer, LayerAnimation } from "framefields";
// 1. Create a 1080p60 composition
const comp = new Composition({
width: 1920,
height: 1080,
fps: 60,
durationFrames: 180, // 3 seconds
backgroundColor: "#090a0f",
fonts: ["assets/fonts/Inter.ttf", "assets/fonts/SpaceGrotesk.ttf"],
});
// 2. Physical snap-overshoot entrance animation
const entrance = LayerAnimation.create()
.fadeIn(0, 20, "power2.out")
.fromTo("y", 60, 0, { start: 0, end: 35, ease: "back.out(1.5)" })
.fromTo("scale", 0.92, 1.0, { start: 0, end: 35, ease: "back.out(1.2)" });
// 3. Assemble a responsive flex-layout card with Slug vector type
const heroCard = Layer.box({
width: 760,
height: 380,
background: "#141721",
borderRadius: 24,
borderColor: "#262b3d",
borderWidth: 1.5,
padding: 40,
children: [
Layer.flex({
dir: "column",
gap: 16,
children: [
Layer.text("FRAMEFIELDS ENGINE", {
fontSize: 16,
fontWeight: 700,
fill: "#6366f1",
letterSpacing: 2.0,
}),
Layer.text("Code-First Video", {
fontSize: 48,
fontWeight: 700,
fill: "#f8fafc",
fontFamily: "SpaceGrotesk",
}),
Layer.text("Direct GPU rendering without headless browser overhead.", {
fontSize: 20,
fill: "#94a3b8",
lineHeight: 28,
}),
],
}),
],
}).animate(entrance);
comp.add(heroCard);
// 4. Render to hardware-encoded MP4
const { filePath } = await comp.renderVideo({
outputPath: "output/hero.mp4",
quality: "high",
});
console.log(`Rendered to: ${filePath}`);
process.exit(0);Ready-made motion pieces you own: a mouse pointer with clicks and drags, a camera that zooms to them, window and device frames, word-timed captions, text reveals, counters, terminals, code blocks, title cards, lower thirds, logo reveals, backdrops, audio waveforms and more. Like a shadcn registry, framefields add copies a component's source into your project instead of hiding it in the package, so you can change any curve, glyph or layout.
npx framefields list # every component, one line each
npx framefields add mouse-pointer focus-zoom # writes src/components/<name>/import { MousePointer } from "./components/mouse-pointer/index.js";
const pointer = MousePointer({
path: [{ to: [400, 300] }, { to: [960, 540], click: true }],
});
comp.add(pointer);
// Every event is a cue: key a button press or a click sound to it.
const clickAt = pointer.cues.clicks[0].frame;Installed components import only framefields and the shared toolkit in framefields/components, and bring along any component they build on. Files you've edited are never overwritten unless you pass --overwrite.
Select a specific object with a point or box (SAM 2.1 Tiny or Small), or by description, several at once, or a whole group as one mask (SAM 3), and track it through video. Masks, bounds, motion and optional matched pose feed the existing vision signals; the same clip masks drive cutouts. The SAM code ships in framefields and loads only when a clip uses it; model weights download on first use, and SAM 3's are under Meta's SAM License, which you accept explicitly (see NOTICE.md).
const subject = Layer.video("assets/source.mp4", {
width: 1920, height: 1080, fit: "contain",
}).withVision({ mode: "matte" });
comp.add(subject);
const tracked = comp.vision(subject, {
sam2: { prompts: [{ frame: 0, points: [{ x: 0.5, y: 0.5, label: 1 }] }] },
});
const target = tracked.signals.objects.get(1);
// SAM 3 (Meta SAM License, accepted explicitly): every student in the shot as one mask, from one prompt
comp.vision(subject, {
acceptSamLicense: true,
sam3: { text: "students in black jackets", merge: true },
});Prompts use normalized source coordinates. Model files download lazily, inference runs locally, and cached source-frame results support seeking and time remapping. See the vision guide for choosing a model, corrections, several objects, backends, costs and mask alignment limits.
Framefields provides built-in access to the AI Gateway, allowing agents and developers to generate cinematic video, images, music, and voiceovers directly from code using hundreds of hosted models. Explore the full model catalog in the AI Gateway or read the integration guide in the documentation.
The gateway is optional. To use it, create a key at framefields.dev/dashboard and set FRAMEFIELDS_API_KEY. In a project made with framefields init, copy .env.example to .env and put the key there; render.ts loads it.
Everything else—including full API references, interactive tutorials, and guides—is available at framefields.dev/docs:
- AI Gateway & Asset Generation — Unified SDK for generating images, video clips, music, and voice via hundreds of hosted models
- Typography & Animators — Slug analytic vector text, After Effects-style range animators, and typewriter cadence
- WebGPU 2D VFX — 50+ shaders: 3D LUTs, Curves, Film Grain, Glassmorphism, and Blur
- Unified 3D Scenes — LookAt cameras, PBR materials, studio lighting, shadows, and glTF/GLB models
- Audio & Procedural SFX — BeatGrids, procedural whooshes/impacts, and audio-reactive signals
- On-Device Vision — ONNX models for detection, pose and cutouts (Apache-2.0), and prompted SAM 2.1 / SAM 3 video tracking (optional, Meta SAM License)
- Live Browser Preview — Localhost WebGPU player with scrubbing, waveform timeline, and frame-stepping
- Documentation: framefields.dev/docs
- Website: framefields.dev
- Discord: discord.gg/cbqMGGme5
- YouTube: @gatewai.studio
Licensed under Apache-2.0.