Skip to content

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

docs(skills): CPU rendering per platform (lavapipe on Linux, WARP or lavapipe on Windows)

okanaslaba20c94d1f4
diff --git a/plugins/framefields/plugin.json b/plugins/framefields/plugin.json
index 9a6f71a5..a52d644f 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), 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.",
+ "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 a CPU renderer (Mesa lavapipe, Windows WARP) for slower rendering without one, 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.md
index 570fd607..82dc08b2 100644
--- a/plugins/framefields/skills/framefields-render/SKILL.md
+++ b/plugins/framefields/skills/framefields-render/SKILL.md
@@ -164,11 +164,13 @@ 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).
+Agents often run in sandboxes or CI runners with no GPU. framefields then renders on the CPU, 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.
+- **Linux:** install Mesa lavapipe, `apt-get install -y libvulkan1 mesa-vulkan-drivers`. Without a Vulkan driver at all, nothing can render.
+- **Windows:** Direct3D 12's WARP renderer is built in; lavapipe (e.g. from mesa-dist-win) works through Vulkan too.
+- **macOS:** always has a Metal GPU, VMs included; framefields' WebGPU build has no Vulkan, so lavapipe isn't used there.
- **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.
+- **Budget for speed:** about 12× slower than an Apple M1 Pro's GPU in our Linux 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 Pattern
diff --git a/plugins/framefields/skills/framefields/SKILL.md b/plugins/framefields/skills/framefields/SKILL.md
index 860c6550..3b6d1d15 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 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`).
+- **A GPU, or a CPU renderer.** macOS uses Metal (every Mac and macOS VM has a Metal GPU). Linux uses Vulkan, Windows Direct3D 12 or Vulkan. Without a GPU, framefields renders on the CPU: on Linux (a sandbox, CI runner or container) through Mesa lavapipe, installed with `apt-get install -y libvulkan1 mesa-vulkan-drivers`; on Windows through WARP (built into Windows) or lavapipe. 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 Linux 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. 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:
+Never go straight to a full video render. On a machine without a GPU every render runs on the CPU (lavapipe or WARP), 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.