Code-first video & image, rendered natively on WebGPU.
docs(skills): rendering without a GPU (lavapipe), tested on every feature
okanasld0d77eab0435
diff --git a/plugins/framefields/plugin.json b/plugins/framefields/plugin.jsonindex bff54a33..9a6f71a5 100644--- a/plugins/framefields/plugin.json+++ b/plugins/framefields/plugin.json@@ -22,7 +22,7 @@"interface": {"displayName": "Framefields","shortDescription": "Code-first video on WebGPU",- "longDescription": "Framefields teaches your coding agent to make videos with code. The skills cover setting up a project with the framefields npm package, building compositions (layout, typography, keyframed animation, 3D scenes, audio), applying effects and color grading, on-device vision such as subject cutouts and tracking, and rendering: single frames, contact sheets, and MP4 export with built-in QA. Everything renders natively on WebGPU in Node.js, without a browser or desktop creative suite.\n\nIntended for developers and agents producing motion graphics, product videos, and programmatic films. Limitations: the plugin contains skills only; rendering needs Node.js 22 or later and a WebGPU-capable GPU (Metal or Vulkan), and the vision features download open model weights from Hugging Face on first use. framefields is in beta, so APIs may change.",+ "longDescription": "Framefields teaches your coding agent to make videos with code. The skills cover setting up a project with the framefields npm package, building compositions (layout, typography, keyframed animation, 3D scenes, audio), applying effects and color grading, on-device vision such as subject cutouts and tracking, and rendering: single frames, contact sheets, and MP4 export with built-in QA. Everything renders natively on WebGPU in Node.js, without a browser or desktop creative suite.\n\nIntended for developers and agents producing motion graphics, product videos, and programmatic films. Limitations: the plugin contains skills only; rendering needs Node.js 22 or later and a WebGPU-capable GPU (Metal or Vulkan), or Mesa lavapipe for slower CPU rendering on Linux, and the vision features download open model weights from Hugging Face on first use. framefields is in beta, so APIs may change.","developerName": "Framefields","category": "Design","capabilities": [diff --git a/plugins/framefields/skills/framefields-render/SKILL.md b/plugins/framefields/skills/framefields-render/SKILL.mdindex 9dee605f..570fd607 100644--- a/plugins/framefields/skills/framefields-render/SKILL.md+++ b/plugins/framefields/skills/framefields-render/SKILL.md@@ -162,6 +162,15 @@ Pass `qa: true` to have the engine check the output while it renders (see **Buil---+## Rendering Without a GPU++Agents often run in Linux sandboxes or CI runners with no GPU. framefields then renders on the CPU through Mesa lavapipe, with the same output for every feature (text, media, Lottie, effects, 3D, vision; vision inference moves to the CPU too).++- **Install the driver:** `apt-get install -y libvulkan1 mesa-vulkan-drivers`. Without a Vulkan driver at all, nothing can render.+- **Confirm it:** `await describeGpu()` returns `software: true`.+- **Budget for speed:** about 12× slower than an Apple M1 Pro's GPU in our test (the smoke project's three videos: 9.7 min against 49 s); it scales with CPU cores. Frames, grids and short exports are fine. Vision layers are the slowest part.+- **Long films:** render on a GPU machine, or push the project and submit it to the framefields render worker (Docker or RunPod, renders a git commit on a GPU). Its project checklist and job format: https://framefields.dev/docs/guides/render-service/+## Production Render Script PatternProduction projects structure their `src/render.ts` to support both quick frame probes and full exports from the CLI:diff --git a/plugins/framefields/skills/framefields/SKILL.md b/plugins/framefields/skills/framefields/SKILL.mdindex d1c8f7cb..860c6550 100644--- a/plugins/framefields/skills/framefields/SKILL.md+++ b/plugins/framefields/skills/framefields/SKILL.md@@ -21,7 +21,7 @@ This skill takes a project from nothing to a verified first render. For anything## 1. Check the environment- **Node.js 22 or later.** Run `node --version`. Older versions fail at import.-- **A WebGPU-capable GPU.** macOS uses Metal; Linux and Windows use Vulkan. Linux without a GPU falls back to a CPU Vulkan driver (Mesa lavapipe) when one is installed, 10–100× slower; `describeGpu()` reports `software: true` then. Machines with neither cannot render.+- **A GPU, or Linux with lavapipe.** macOS uses Metal; Linux and Windows use Vulkan. On Linux without a GPU (a sandbox, CI runner or container), framefields renders on the CPU through Mesa lavapipe: install it with `apt-get install -y libvulkan1 mesa-vulkan-drivers`. Every feature renders the same there (text, media, Lottie, effects, 3D, vision), only slower: about 12× slower than an M1 Pro's GPU in our test. `describeGpu()` reports `software: true`. Fine for frames, grids and short exports; for long films, use a GPU machine or the render worker (`framefields-render`).- **An ES module project.** The project's `package.json` needs `"type": "module"`.## 2. Install@@ -246,7 +246,7 @@ Video inputs (`Layer.video("assets/footage/clip.mp4")`), Lottie animations (`Lay## 4. Verify, cheapest step first-Never go straight to a full video render. Rendering needs a WebGPU-capable GPU (Metal on macOS, Vulkan on Linux/Windows); CPU rendering through lavapipe works on 2.2 but is far slower. Each step catches problems in seconds that a video render takes minutes to show:+Never go straight to a full video render. On a machine without a GPU every render runs on the CPU (lavapipe), so the cheap steps matter even more. Each step catches problems in seconds that a video render takes minutes to show:1. `npm run typecheck`2. `npm run frames -- 0 30 60` and look at the PNGs in `output/`. A black frame usually means a missing font, a layer outside the canvas, or opacity stuck at 0.