diff --git a/AGENTS.md b/AGENTS.md
index ad43d8a..33af165 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -8,14 +8,14 @@ Use the `loop` CLI (`npx loop` or `node tool/bin/loop.js`) for every stage of th
| Command | Purpose | Output |
| :--- | :--- | :--- |
-| `loop new
[--mode showcase\|ambient] [--style ] [--scene ]` | Scaffold a loop project with `brief.json` / `showcase.json`, `sketch.js`, and preview HTML | `/sketch.js`, `/index.html` |
+| `loop new [--mode showcase\|ambient] [--style ] [--scene ] [--fps ]` | Scaffold a loop project with `brief.json` / `showcase.json`, `sketch.js`, and preview HTML | `/sketch.js`, `/index.html` |
| `loop sheet [--cols 4] [--every 8]` | Render every Nth frame into a numbered contact sheet for visual critique | `/sheet.png` |
| `loop story ` | Render Frame `0` plus the midpoint frame of each step in `showcase.json` | `/storyboard.png` |
| `loop seam ` | Measure frame-to-frame pixel deltas, last-to-first seam ratio, duplicate frames, and flicker | `/seam.json` |
| `loop legible ` | Audit caption reading time, WCAG contrast (`>= 4.5:1`), safe margins, and phone-width readability | `/legible.json` |
| `loop source-check [--repo ]` | Verify every `file:line` citation in `showcase.json` exists in the target repository | `/sources.json` |
| `loop audit ` | Run `seam`, `legible`, and `source-check` together as a unified quality gate | `/audit.json` |
-| `loop render [--formats gif,mp4,webm,png]` | Render full-resolution `loop.gif` / `showcase.gif`, `poster.png`, and (when FFmpeg is available) `loop.mp4` & `loop.webm` | `/loop.gif`, `/poster.png` |
+| `loop render [--fps ] [--formats gif,mp4,webp,webm,png\|all]` | Render full-resolution `loop.gif` / `showcase.gif`, `poster.png`, `loop.mp4` (FFmpeg or macOS AVFoundation), Animated WebP, and WebM at up to `60–120 fps` | `/loop.gif`, `/loop.mp4`, `/poster.png` |
| `loop serve [--port 4173]` | Launch interactive browser workbench with phase scrubber, seam oscilloscope, and mobile preview | `http://localhost:4173` |
| `loop doctor` | Check runtime capabilities (Pure-JS engine, Headless Chrome/Chromium, FFmpeg) | JSON / terminal diagnostic |
diff --git a/README.md b/README.md
index 406cea9..afd813c 100644
--- a/README.md
+++ b/README.md
@@ -206,9 +206,9 @@ loop-studio/
| `loop legible ` | Verify reading duration (`>= 0.5 + 0.3*words`), WCAG `4.5:1` contrast & phone margins | `legible.json` |
| `loop source-check [--repo ]` | Verify every `file:line` source citation in `showcase.json` exists | `sources.json` |
| `loop audit [--repo ]` | Run `seam`, `legible`, and `source-check` together as a single gate | `audit.json` |
-| `loop render ` | Render full-resolution `showcase.gif` / `loop.gif` and `poster.png` | `loop.gif`, `poster.png`, `seam.json` |
+| `loop render [--fps ] [--formats gif,mp4,webp,webm,png\|all]` | Render full-resolution `showcase.gif` / `loop.gif`, `poster.png`, `loop.mp4` (`30–120 fps` via FFmpeg or macOS AVFoundation), Animated `.webp`, and `.webm` | `loop.gif`, `loop.mp4`, `poster.png`, `seam.json` |
| `loop serve [--port 4173]` | Launch interactive browser workbench with phase scrubber & 400px phone view | `http://localhost:4173` |
-| `loop doctor` | Check runtime engines (SoftCanvas2D, GIF89a, PNG, FFmpeg, Chrome) | JSON diagnostic |
+| `loop doctor` | Check runtime engines (SoftCanvas2D, GIF89a, PNG, macOS AVFoundation, Animated WebP, FFmpeg, Chrome) | JSON diagnostic |
---
diff --git a/docs/tool.md b/docs/tool.md
index 252ecde..09c2ac9 100644
--- a/docs/tool.md
+++ b/docs/tool.md
@@ -18,8 +18,8 @@ The `loop` command (`tool/bin/loop.js`) drives project scaffolding, preview cont
Verifies every `"source": "file:line"` in `showcase.json` exists in the repository and writes `/sources.json`.
7. `loop audit [--repo ]`
Runs `seam`, `legible`, and `source-check` together and writes `/audit.json`.
-8. `loop render `
- Renders all frames `0..N-1` at full resolution and outputs `showcase.gif` / `loop.gif` and `poster.png` (plus `loop.mp4` / `loop.webm` when FFmpeg is present).
+8. `loop render [--fps ] [--formats gif,mp4,webp,webm,png|all] [--width ] [--height ]`
+ Renders all frames `0..N-1` at full resolution and outputs `showcase.gif` / `loop.gif`, `poster.png`, `loop.mp4` (via FFmpeg or native macOS AVFoundation at `30/60/120 fps`), Animated `.webp` (via `cwebp`+`webpmux` or FFmpeg), and `.webm` (when FFmpeg is present).
9. `loop serve [--port 4173]`
Opens the interactive browser workbench with phase scrubber and mobile width toggle.
10. `loop doctor`
diff --git a/skills/loop-render/SKILL.md b/skills/loop-render/SKILL.md
index 7b85fc3..e9b06cf 100644
--- a/skills/loop-render/SKILL.md
+++ b/skills/loop-render/SKILL.md
@@ -59,15 +59,21 @@ node tool/bin/loop.js audit --repo
### 8. Final Render (`loop render`)
Renders all $N$ frames (`0..N-1`) at full resolution and encodes:
-- `loop.gif` (or `showcase.gif` in showcase mode) using adaptive 256-color quantization + LZW encoding (or FFmpeg two-pass `palettegen`/`paletteuse` when FFmpeg is installed)
+- `loop.gif` (or `showcase.gif` in showcase mode) using adaptive 256-color quantization + LZW encoding (GIF89a frame delays use integer centiseconds, capping reliable browser playback at `50 fps` / `2 cs`)
- `poster.png` (Frame `0` at full resolution)
-- `loop.mp4` / `showcase.mp4` (`H.264 yuv420p` when FFmpeg is installed)
+- `loop.mp4` / `showcase.mp4` (`H.264 yuv420p` at exact requested `fps` — `24`, `30`, `60`, or `120 fps` — via **FFmpeg** or native **macOS AVFoundation**)
+- `loop.webp` / `showcase.webp` (24-bit Animated WebP with exact millisecond frame timing at `30–60+ fps` via `cwebp`+`webpmux` or FFmpeg)
- `loop.webm` (`VP9` when FFmpeg is installed and `--formats webm` is requested)
```bash
-node tool/bin/loop.js render --formats gif,png,mp4
+node tool/bin/loop.js render --fps 60 --formats mp4,webp,gif,png
```
+> [!TIP]
+> **Choosing Frame Rates (`> 20 fps`)**:
+> - For **GIFs**, use `20`, `25`, `30` (`3 cs` ≈ `33.3 fps`), or `50 fps` (`2 cs`, maximum reliable browser GIF speed).
+> - For **true `30 / 60 / 120 fps` smooth video**, pass `--fps 60` with `--formats mp4,webp,png` (MP4 files are typically `4×–10×` smaller than GIFs with zero 256-color banding).
+
### 9. Live Interactive Workbench (`loop serve`)
Opens an interactive studio in the browser with a frame-exact phase scrubber, live seam-jump bar chart, mobile width toggle, and instant PNG/sheet export:
```bash
diff --git a/tool/bin/loop.js b/tool/bin/loop.js
index fb3fd2e..484c259 100755
--- a/tool/bin/loop.js
+++ b/tool/bin/loop.js
@@ -5,7 +5,14 @@
import fs from "node:fs";
import path from "node:path";
import { fileURLToPath, pathToFileURL } from "node:url";
-import { encodePNG, encodeGIF, detectFFmpeg } from "../lib/encoders.js";
+import {
+ encodePNG,
+ encodeGIF,
+ encodeMP4,
+ encodeWebM,
+ encodeAnimatedWebP,
+ detectCapabilities
+} from "../lib/encoders.js";
import { analyzeSeam, analyzeLegibility, analyzeSources } from "../lib/analyzers.js";
import { renderAllFrames, renderContactSheet, renderStoryboard } from "../lib/compositor.js";
import { generatePreviewHtml, serveLoop } from "../lib/server.js";
@@ -44,7 +51,7 @@ function readJsonIfExists(filePath) {
}
}
-async function loadSketchProject(targetDir) {
+async function loadSketchProject(targetDir, flags = {}) {
const absDir = path.resolve(targetDir);
const sketchPath = path.join(absDir, "sketch.js");
if (!fs.existsSync(sketchPath)) {
@@ -54,10 +61,30 @@ async function loadSketchProject(targetDir) {
const sketchModule = await import(pathToFileURL(sketchPath).href + cacheBust);
const briefJson = readJsonIfExists(path.join(absDir, "brief.json"));
const showcaseJson = readJsonIfExists(path.join(absDir, "showcase.json")) || sketchModule.showcase || null;
+
+ const showcaseOverrides = showcaseJson
+ ? {
+ ...(showcaseJson.seconds ? { seconds: showcaseJson.seconds } : {}),
+ ...(showcaseJson.fps ? { fps: showcaseJson.fps } : {}),
+ ...(showcaseJson.width ? { width: showcaseJson.width } : {}),
+ ...(showcaseJson.height ? { height: showcaseJson.height } : {}),
+ ...(showcaseJson.palette ? { palette: showcaseJson.palette } : {})
+ }
+ : {};
+
+ const flagOverrides = {
+ ...(flags.fps ? { fps: Number(flags.fps) } : {}),
+ ...(flags.seconds ? { seconds: Number(flags.seconds) } : {}),
+ ...(flags.width ? { width: Number(flags.width) } : {}),
+ ...(flags.height ? { height: Number(flags.height) } : {}),
+ ...(flags.palette ? { palette: flags.palette } : {})
+ };
+
const meta = {
...(sketchModule.meta || {}),
...(briefJson || {}),
- ...(showcaseJson ? { seconds: showcaseJson.seconds || sketchModule.meta?.seconds || 10 } : {})
+ ...showcaseOverrides,
+ ...flagOverrides
};
return { absDir, sketchPath, sketchModule, briefJson, showcaseJson, meta };
}
@@ -95,18 +122,18 @@ function cmdNew(targetDir, flags) {
const showcaseData = {
title: path.basename(absDir),
says: "Loop Studio turns a one-line request into a checked, seamless loop.",
- seconds: 10,
- fps: 24,
- width: 800,
- height: 320,
+ seconds: Number(flags.seconds || 10),
+ fps: Number(flags.fps || 30),
+ width: Number(flags.width || 800),
+ height: Number(flags.height || 360),
palette,
scene,
stage: ["request", "sketch", "check", "loop.gif"],
steps: [
- { from: 8.5, to: 1.5, caption: "a request arrives: \"deep sea, slow, square\"", source: "README.md:12" },
- { from: 1.5, to: 5.0, caption: "a sketch is written, driven by the phase", source: "rules/AGENTS.md:8" },
- { from: 5.0, to: 7.0, caption: "the seam and legibility are measured", source: "skills/loop-render/SKILL.md:30" },
- { from: 7.0, to: 8.5, caption: "the verified loop drops out", source: "skills/loop-render/SKILL.md:54" }
+ { from: 8.75, to: 1.25, caption: "a request arrives: \"deep sea, square\"", source: "docs/contract.md:3" },
+ { from: 1.25, to: 3.75, caption: "sketch is drawn from the phase", source: "docs/contract.md:14" },
+ { from: 3.75, to: 6.25, caption: "seam and legibility are measured", source: "docs/tool.md:14" },
+ { from: 6.25, to: 8.75, caption: "the verified loop drops out", source: "docs/tool.md:24" }
]
};
const scPath = path.join(absDir, "showcase.json");
@@ -121,7 +148,7 @@ function cmdNew(targetDir, flags) {
style,
palette,
seconds: Number(flags.seconds || 4),
- fps: Number(flags.fps || 24),
+ fps: Number(flags.fps || 30),
width: Number(flags.width || 400),
height: Number(flags.height || 400),
seed: Number(flags.seed || 42)
@@ -137,7 +164,7 @@ function cmdNew(targetDir, flags) {
}
async function cmdSheet(targetDir, flags) {
- const { absDir, sketchModule, showcaseJson, meta } = await loadSketchProject(targetDir);
+ const { absDir, sketchModule, showcaseJson, meta } = await loadSketchProject(targetDir, flags);
const every = flags.every ? Number(flags.every) : undefined;
const cols = flags.cols ? Number(flags.cols) : 4;
const sheetCanvas = renderContactSheet(sketchModule, { ...meta, showcase: showcaseJson, every, cols });
@@ -147,8 +174,8 @@ async function cmdSheet(targetDir, flags) {
console.log(JSON.stringify({ status: "ok", file: outPath, width: sheetCanvas.width, height: sheetCanvas.height, bytes: pngBuf.length }, null, 2));
}
-async function cmdStory(targetDir) {
- const { absDir, sketchModule, showcaseJson, meta } = await loadSketchProject(targetDir);
+async function cmdStory(targetDir, flags) {
+ const { absDir, sketchModule, showcaseJson, meta } = await loadSketchProject(targetDir, flags);
const boardCanvas = renderStoryboard(sketchModule, showcaseJson, meta);
const pngBuf = encodePNG(boardCanvas.data, boardCanvas.width, boardCanvas.height);
const outPath = path.join(absDir, "storyboard.png");
@@ -156,9 +183,8 @@ async function cmdStory(targetDir) {
console.log(JSON.stringify({ status: "ok", file: outPath, width: boardCanvas.width, height: boardCanvas.height, bytes: pngBuf.length }, null, 2));
}
-async function cmdSeam(targetDir) {
- const { absDir, sketchModule, showcaseJson, meta } = await loadSketchProject(targetDir);
- // Render at evaluation resolution for fast & exact seam measurement
+async function cmdSeam(targetDir, flags) {
+ const { absDir, sketchModule, showcaseJson, meta } = await loadSketchProject(targetDir, flags);
const scale = meta.width > 400 ? 0.5 : 1;
const evalW = Math.max(120, Math.round((meta.width || 400) * scale));
const evalH = Math.max(80, Math.round((meta.height || 400) * scale));
@@ -175,8 +201,8 @@ async function cmdSeam(targetDir) {
if (!report.pass) process.exitCode = 1;
}
-async function cmdLegible(targetDir) {
- const { absDir, sketchModule, showcaseJson, meta } = await loadSketchProject(targetDir);
+async function cmdLegible(targetDir, flags) {
+ const { absDir, sketchModule, showcaseJson, meta } = await loadSketchProject(targetDir, flags);
const report = analyzeLegibility(sketchModule, showcaseJson, meta);
const outPath = path.join(absDir, "legible.json");
fs.writeFileSync(outPath, JSON.stringify(report, null, 2) + "\n", "utf8");
@@ -185,7 +211,7 @@ async function cmdLegible(targetDir) {
}
async function cmdSourceCheck(targetDir, flags) {
- const { absDir, showcaseJson } = await loadSketchProject(targetDir);
+ const { absDir, showcaseJson } = await loadSketchProject(targetDir, flags);
const repoRoot = flags.repo ? path.resolve(flags.repo) : REPO_ROOT;
const report = analyzeSources(showcaseJson, repoRoot);
const outPath = path.join(absDir, "sources.json");
@@ -195,7 +221,7 @@ async function cmdSourceCheck(targetDir, flags) {
}
async function cmdAudit(targetDir, flags) {
- const { absDir, sketchModule, showcaseJson, meta } = await loadSketchProject(targetDir);
+ const { absDir, sketchModule, showcaseJson, meta } = await loadSketchProject(targetDir, flags);
const repoRoot = flags.repo ? path.resolve(flags.repo) : REPO_ROOT;
const scale = meta.width > 400 ? 0.5 : 1;
@@ -238,30 +264,126 @@ async function cmdAudit(targetDir, flags) {
if (!pass) process.exitCode = 1;
}
-async function cmdRender(targetDir) {
- const { absDir, sketchModule, showcaseJson, meta } = await loadSketchProject(targetDir);
+function resolveFormats(flags, caps, briefJson) {
+ if (flags.formats) {
+ const raw = String(flags.formats)
+ .split(",")
+ .map((s) => s.trim().toLowerCase())
+ .filter(Boolean);
+ if (raw.includes("all")) {
+ const list = ["png", "gif"];
+ if (caps.macosAVFoundation || caps.ffmpeg) list.push("mp4");
+ if (caps.animatedWebP) list.push("webp");
+ if (caps.ffmpeg) list.push("webm");
+ return list;
+ }
+ return raw;
+ }
+ if (Array.isArray(briefJson?.formats) && briefJson.formats.length > 0) {
+ return briefJson.formats.map((s) => String(s).toLowerCase());
+ }
+ const defaults = ["png", "gif"];
+ if (caps.macosAVFoundation || caps.ffmpeg) defaults.push("mp4");
+ return defaults;
+}
+
+async function cmdRender(targetDir, flags) {
+ const { absDir, sketchModule, briefJson, showcaseJson, meta } = await loadSketchProject(targetDir, flags);
+ const caps = detectCapabilities();
+ const formats = resolveFormats(flags, caps, briefJson);
+
const { frames, width, height, fps, totalFrames } = renderAllFrames(sketchModule, {
...meta,
showcase: showcaseJson
});
- // 1. Poster PNG (Frame 0)
- const posterBuf = encodePNG(frames[0], width, height);
- const posterPath = path.join(absDir, "poster.png");
- fs.writeFileSync(posterPath, posterBuf);
-
- // 2. Animated GIF89a
- const gifBuf = encodeGIF(frames, width, height, fps);
const isShowcase = meta.mode === "showcase" || Boolean(showcaseJson);
- const primaryGifName = isShowcase ? "showcase.gif" : "loop.gif";
- const gifPath = path.join(absDir, primaryGifName);
- fs.writeFileSync(gifPath, gifBuf);
- if (isShowcase) {
- // Also write loop.gif alias for uniform tooling
- fs.writeFileSync(path.join(absDir, "loop.gif"), gifBuf);
+ const stem = isShowcase ? "showcase" : "loop";
+ const files = {};
+ const notes = [];
+
+ if (formats.includes("png") || formats.includes("poster")) {
+ const posterBuf = encodePNG(frames[0], width, height);
+ const posterPath = path.join(absDir, "poster.png");
+ fs.writeFileSync(posterPath, posterBuf);
+ files.poster = { path: posterPath, bytes: posterBuf.length, kb: Number((posterBuf.length / 1024).toFixed(1)) };
+ }
+
+ if (formats.includes("gif")) {
+ const gifBuf = encodeGIF(frames, width, height, fps);
+ const gifPath = path.join(absDir, `${stem}.gif`);
+ fs.writeFileSync(gifPath, gifBuf);
+ if (isShowcase) {
+ fs.writeFileSync(path.join(absDir, "loop.gif"), gifBuf);
+ }
+ const delayCs = Math.max(2, Math.round(100 / fps));
+ const effectiveGifFps = Number((100 / delayCs).toFixed(1));
+ if (fps > 50) {
+ notes.push(`GIF89a frame delay caps at 2cs (${effectiveGifFps}fps); use MP4 or WebP for true ${fps}fps playback.`);
+ }
+ files.gif = {
+ path: gifPath,
+ bytes: gifBuf.length,
+ kb: Number((gifBuf.length / 1024).toFixed(1)),
+ effectiveFps: effectiveGifFps
+ };
+ }
+
+ if (formats.includes("mp4")) {
+ if (caps.macosAVFoundation || caps.ffmpeg) {
+ const mp4Path = path.join(absDir, `${stem}.mp4`);
+ try {
+ const res = encodeMP4(frames, width, height, fps, mp4Path);
+ files.mp4 = {
+ path: res.path,
+ backend: res.backend,
+ fps,
+ bytes: res.bytes,
+ kb: Number((res.bytes / 1024).toFixed(1))
+ };
+ } catch (err) {
+ if (flags.formats) {
+ throw err;
+ }
+ notes.push(`Skipped default MP4: ${err.message.split("\n")[0]}`);
+ }
+ } else {
+ notes.push("Skipped MP4: install ffmpeg or run on macOS with Swift AVFoundation.");
+ }
+ }
+
+ if (formats.includes("webp")) {
+ if (caps.animatedWebP) {
+ const webpPath = path.join(absDir, `${stem}.webp`);
+ const res = encodeAnimatedWebP(frames, width, height, fps, webpPath);
+ files.webp = {
+ path: res.path,
+ backend: res.backend,
+ fps,
+ bytes: res.bytes,
+ kb: Number((res.bytes / 1024).toFixed(1))
+ };
+ } else {
+ notes.push("Skipped WebP: requires cwebp + webpmux or ffmpeg.");
+ }
+ }
+
+ if (formats.includes("webm")) {
+ if (caps.ffmpeg) {
+ const webmPath = path.join(absDir, `${stem}.webm`);
+ const res = encodeWebM(frames, width, height, fps, webmPath);
+ files.webm = {
+ path: res.path,
+ backend: res.backend,
+ fps,
+ bytes: res.bytes,
+ kb: Number((res.bytes / 1024).toFixed(1))
+ };
+ } else {
+ notes.push("Skipped WebM: install ffmpeg (`brew install ffmpeg`) for VP9 WebM encoding.");
+ }
}
- // 3. Measure seam on full render
const seam = analyzeSeam(frames, width, height);
fs.writeFileSync(path.join(absDir, "seam.json"), JSON.stringify(seam, null, 2) + "\n", "utf8");
@@ -276,10 +398,8 @@ async function cmdRender(targetDir) {
totalFrames,
seamScore: seam.seamScore,
duplicateFrames: seam.duplicateFrames,
- files: {
- gif: { path: gifPath, bytes: gifBuf.length, kb: Number((gifBuf.length / 1024).toFixed(1)) },
- poster: { path: posterPath, bytes: posterBuf.length, kb: Number((posterBuf.length / 1024).toFixed(1)) }
- }
+ files,
+ ...(notes.length ? { notes } : {})
},
null,
2
@@ -288,7 +408,7 @@ async function cmdRender(targetDir) {
}
function cmdDoctor() {
- const hasFFmpeg = detectFFmpeg();
+ const caps = detectCapabilities();
const chromePaths = [
"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
"/usr/bin/google-chrome",
@@ -305,7 +425,9 @@ function cmdDoctor() {
softCanvas2D: true,
pureJsGif89a: true,
pureJsPng: true,
- ffmpeg: hasFFmpeg,
+ macosAVFoundation: caps.macosAVFoundation,
+ animatedWebP: caps.animatedWebP,
+ ffmpeg: caps.ffmpeg,
headlessChrome: Boolean(chromeFound),
chromePath: chromeFound
}
@@ -320,14 +442,14 @@ function printHelp() {
console.log(`Loop Studio CLI (loop) — Deterministic Seamless Animation & Showcase Engine
Usage:
- loop new [--mode showcase|ambient] [--scene ] [--style ] [--palette ]
+ loop new [--mode showcase|ambient] [--scene ] [--style ] [--palette ] [--fps ]
loop sheet [--every ] [--cols ]
loop story
loop seam
loop legible
loop source-check [--repo ]
loop audit [--repo ]
- loop render
+ loop render [--fps ] [--formats gif,mp4,webp,webm,png|all] [--width ] [--height ]
loop serve [--port 4173]
loop doctor
`);
@@ -344,13 +466,13 @@ async function main() {
await cmdSheet(dir, flags);
break;
case "story":
- await cmdStory(dir);
+ await cmdStory(dir, flags);
break;
case "seam":
- await cmdSeam(dir);
+ await cmdSeam(dir, flags);
break;
case "legible":
- await cmdLegible(dir);
+ await cmdLegible(dir, flags);
break;
case "source-check":
await cmdSourceCheck(dir, flags);
@@ -359,7 +481,7 @@ async function main() {
await cmdAudit(dir, flags);
break;
case "render":
- await cmdRender(dir);
+ await cmdRender(dir, flags);
break;
case "serve":
serveLoop(dir, Number(flags.port || 4173), path.join(REPO_ROOT, "tool/lib/loop-kit.js"));
diff --git a/tool/lib/encoders.js b/tool/lib/encoders.js
index 4744732..e6730d9 100644
--- a/tool/lib/encoders.js
+++ b/tool/lib/encoders.js
@@ -1,9 +1,17 @@
-// Loop Studio — Pure-JS PNG & GIF89a Encoders + Optional FFmpeg Driver
-// Zero external npm dependencies required; uses Node's built-in node:zlib.
+// Loop Studio — Pure-JS PNG & GIF89a Encoders + Native MP4 (AVFoundation/FFmpeg), WebM & Animated WebP
+// Zero external npm dependencies required.
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
import zlib from "node:zlib";
+import { fileURLToPath } from "node:url";
import { spawnSync } from "node:child_process";
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const SWIFT_MP4_SCRIPT = path.resolve(__dirname, "../scripts/encode-mp4.swift");
+
const CRC_TABLE = new Uint32Array(256);
for (let n = 0; n < 256; n++) {
let c = n;
@@ -31,7 +39,7 @@ function pngChunk(type, data) {
return Buffer.concat([len, typeBuf, data, crcBuf]);
}
-export function encodePNG(rgba, width, height) {
+export function encodePNG(rgba, width, height, compressionLevel = 6) {
const signature = Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]);
const ihdr = Buffer.alloc(13);
ihdr.writeUInt32BE(width, 0);
@@ -53,7 +61,7 @@ export function encodePNG(rgba, width, height) {
}
}
- const compressed = zlib.deflateSync(raw, { level: 6 });
+ const compressed = zlib.deflateSync(raw, { level: compressionLevel });
return Buffer.concat([
signature,
pngChunk("IHDR", ihdr),
@@ -73,7 +81,6 @@ function buildGlobalPalette(frames, width, height) {
const data = frames[f];
for (let p = 0; p < totalPixels; p += pixStep) {
const idx = p * 4;
- // Quantize to 6-6-6 bits (18-bit key) to preserve exact UI/palette colors and smooth steps
const r = data[idx] & 0xfc;
const g = data[idx + 1] & 0xfc;
const b = data[idx + 2] & 0xfc;
@@ -89,7 +96,6 @@ function buildGlobalPalette(frames, width, height) {
const r = (key >> 16) & 0xff;
const g = (key >> 8) & 0xff;
const b = key & 0xff;
- // Avoid adding near-duplicate colors if we have plenty of candidates
let tooClose = false;
if (sorted.length > 256 && palette.length > 16) {
for (let i = 0; i < palette.length; i++) {
@@ -106,7 +112,6 @@ function buildGlobalPalette(frames, width, height) {
if (!tooClose) palette.push([r, g, b]);
}
- // Fill any remaining slots if needed
for (const [key] of sorted) {
if (palette.length >= 256) break;
const r = (key >> 16) & 0xff;
@@ -153,8 +158,8 @@ function mapFrameToIndices(rgba, totalPixels, palette, cache) {
// LZW encoder for GIF89a 8-bit indices
function lzwEncode(indices) {
const minCodeSize = 8;
- const clearCode = 1 << minCodeSize; // 256
- const eoiCode = clearCode + 1; // 257
+ const clearCode = 1 << minCodeSize;
+ const eoiCode = clearCode + 1;
const outBytes = [];
let bitBuf = 0;
@@ -170,9 +175,8 @@ function lzwEncode(indices) {
}
}
- let codeSize = minCodeSize + 1; // 9
- let nextCode = eoiCode + 1; // 258
- // Flat hash table / Map from (prefix << 8) | suffix -> code
+ let codeSize = minCodeSize + 1;
+ let nextCode = eoiCode + 1;
let table = new Map();
emitCode(clearCode, codeSize);
@@ -208,7 +212,6 @@ function lzwEncode(indices) {
outBytes.push(bitBuf & 0xff);
}
- // Pack into GIF sub-blocks of max 255 bytes
const chunks = [Buffer.from([minCodeSize])];
let offset = 0;
while (offset < outBytes.length) {
@@ -221,7 +224,7 @@ function lzwEncode(indices) {
chunks.push(block);
offset += size;
}
- chunks.push(Buffer.from([0x00])); // Block terminator
+ chunks.push(Buffer.from([0x00]));
return Buffer.concat(chunks);
}
@@ -229,15 +232,16 @@ export function encodeGIF(frames, width, height, fps = 24) {
const palette = buildGlobalPalette(frames, width, height);
const cache = new Map();
const totalPixels = width * height;
+ // GIF89a stores frame delay in centiseconds; 2cs (50fps) is the fastest reliable browser speed
const delayCs = Math.max(2, Math.round(100 / fps));
const header = Buffer.alloc(13);
header.write("GIF89a", 0, "ascii");
header.writeUInt16LE(width, 6);
header.writeUInt16LE(height, 8);
- header[10] = 0xf7; // Global Color Table flag (1), color res (7), sort (0), size 2^(7+1)=256
- header[11] = 0; // bg color index
- header[12] = 0; // pixel aspect ratio
+ header[10] = 0xf7;
+ header[11] = 0;
+ header[12] = 0;
const gct = Buffer.alloc(256 * 3);
for (let i = 0; i < 256; i++) {
@@ -246,7 +250,6 @@ export function encodeGIF(frames, width, height, fps = 24) {
gct[i * 3 + 2] = palette[i][2];
}
- // Netscape 2.0 infinite loop extension
const netscape = Buffer.from([
0x21, 0xff, 0x0b,
0x4e, 0x45, 0x54, 0x53, 0x43, 0x41, 0x50, 0x45, 0x32, 0x2e, 0x30,
@@ -257,32 +260,224 @@ export function encodeGIF(frames, width, height, fps = 24) {
for (let f = 0; f < frames.length; f++) {
const gce = Buffer.alloc(8);
- gce[0] = 0x21; // Extension Introducer
- gce[1] = 0xf9; // Graphic Control Label
- gce[2] = 0x04; // Byte size
- gce[3] = 0x04; // Disposal method 1 (Do not dispose / overwrite)
+ gce[0] = 0x21;
+ gce[1] = 0xf9;
+ gce[2] = 0x04;
+ gce[3] = 0x04;
gce.writeUInt16LE(delayCs, 4);
gce[6] = 0x00;
gce[7] = 0x00;
const imgDesc = Buffer.alloc(10);
- imgDesc[0] = 0x2c; // Image Separator
+ imgDesc[0] = 0x2c;
imgDesc.writeUInt16LE(0, 1);
imgDesc.writeUInt16LE(0, 3);
imgDesc.writeUInt16LE(width, 5);
imgDesc.writeUInt16LE(height, 7);
- imgDesc[9] = 0x00; // Use Global Color Table
+ imgDesc[9] = 0x00;
const indices = mapFrameToIndices(frames[f], totalPixels, palette, cache);
const lzw = lzwEncode(indices);
parts.push(gce, imgDesc, lzw);
}
- parts.push(Buffer.from([0x3b])); // GIF Trailer
+ parts.push(Buffer.from([0x3b]));
return Buffer.concat(parts);
}
+function findBinary(name, extraPaths = []) {
+ const direct = spawnSync("which", [name], { encoding: "utf8" });
+ if (direct.status === 0 && direct.stdout.trim()) {
+ return direct.stdout.trim().split("\n")[0];
+ }
+ for (const p of extraPaths) {
+ if (fs.existsSync(p)) return p;
+ }
+ return null;
+}
+
export function detectFFmpeg() {
- const res = spawnSync("ffmpeg", ["-version"], { encoding: "utf8" });
- return res.status === 0;
+ return Boolean(findBinary("ffmpeg", ["/opt/homebrew/bin/ffmpeg", "/usr/local/bin/ffmpeg"]));
+}
+
+export function detectCapabilities() {
+ const ffmpegPath = findBinary("ffmpeg", ["/opt/homebrew/bin/ffmpeg", "/usr/local/bin/ffmpeg"]);
+ const swiftPath = process.platform === "darwin" ? findBinary("swift", ["/usr/bin/swift"]) : null;
+ const cwebpPath = findBinary("cwebp", ["/opt/homebrew/bin/cwebp", "/usr/local/bin/cwebp"]);
+ const webpmuxPath = findBinary("webpmux", ["/opt/homebrew/bin/webpmux", "/usr/local/bin/webpmux"]);
+
+ return {
+ ffmpeg: Boolean(ffmpegPath),
+ ffmpegPath,
+ macosAVFoundation: Boolean(swiftPath && fs.existsSync(SWIFT_MP4_SCRIPT)),
+ swiftPath,
+ animatedWebP: Boolean((cwebpPath && webpmuxPath) || ffmpegPath),
+ cwebpPath,
+ webpmuxPath
+ };
+}
+
+export function encodeMP4(frames, width, height, fps = 30, outPath) {
+ const caps = detectCapabilities();
+ const absOut = path.resolve(outPath);
+
+ if (caps.ffmpegPath) {
+ const tmpRaw = path.join(os.tmpdir(), `loop-studio-${process.pid}-${Date.now()}.rgba`);
+ try {
+ const fd = fs.openSync(tmpRaw, "w");
+ for (const frame of frames) fs.writeSync(fd, frame);
+ fs.closeSync(fd);
+
+ const res = spawnSync(
+ caps.ffmpegPath,
+ [
+ "-y",
+ "-f", "rawvideo",
+ "-pix_fmt", "rgba",
+ "-s", `${width}x${height}`,
+ "-r", String(fps),
+ "-i", tmpRaw,
+ "-vf", "pad=ceil(iw/2)*2:ceil(ih/2)*2",
+ "-c:v", "libx264",
+ "-pix_fmt", "yuv420p",
+ "-movflags", "+faststart",
+ "-crf", "17",
+ absOut
+ ],
+ { encoding: "utf8" }
+ );
+ if (res.status !== 0) {
+ throw new Error(`ffmpeg MP4 encoding failed: ${res.stderr}`);
+ }
+ return { backend: "ffmpeg", path: absOut, bytes: fs.statSync(absOut).size };
+ } finally {
+ if (fs.existsSync(tmpRaw)) fs.unlinkSync(tmpRaw);
+ }
+ }
+
+ if (caps.macosAVFoundation) {
+ const tmpRaw = path.join(os.tmpdir(), `loop-studio-${process.pid}-${Date.now()}.rgba`);
+ try {
+ const fd = fs.openSync(tmpRaw, "w");
+ for (const frame of frames) fs.writeSync(fd, frame);
+ fs.closeSync(fd);
+
+ const res = spawnSync(
+ caps.swiftPath,
+ [SWIFT_MP4_SCRIPT, tmpRaw, String(width), String(height), String(fps), String(frames.length), absOut],
+ { encoding: "utf8" }
+ );
+ if (res.status !== 0) {
+ throw new Error(`macOS AVFoundation MP4 encoding failed: ${res.stderr || res.stdout}`);
+ }
+ return { backend: "macos-avfoundation", path: absOut, bytes: fs.statSync(absOut).size };
+ } finally {
+ if (fs.existsSync(tmpRaw)) fs.unlinkSync(tmpRaw);
+ }
+ }
+
+ throw new Error("No MP4 encoder found (install ffmpeg or run on macOS with Swift AVFoundation).");
+}
+
+export function encodeWebM(frames, width, height, fps = 30, outPath) {
+ const caps = detectCapabilities();
+ if (!caps.ffmpegPath) {
+ throw new Error("WebM encoding requires ffmpeg (install via `brew install ffmpeg`).");
+ }
+ const absOut = path.resolve(outPath);
+ const tmpRaw = path.join(os.tmpdir(), `loop-studio-webm-${process.pid}-${Date.now()}.rgba`);
+ try {
+ const fd = fs.openSync(tmpRaw, "w");
+ for (const frame of frames) fs.writeSync(fd, frame);
+ fs.closeSync(fd);
+
+ const res = spawnSync(
+ caps.ffmpegPath,
+ [
+ "-y",
+ "-f", "rawvideo",
+ "-pix_fmt", "rgba",
+ "-s", `${width}x${height}`,
+ "-r", String(fps),
+ "-i", tmpRaw,
+ "-c:v", "libvpx-vp9",
+ "-pix_fmt", "yuv420p",
+ "-b:v", "0",
+ "-crf", "24",
+ absOut
+ ],
+ { encoding: "utf8" }
+ );
+ if (res.status !== 0) {
+ throw new Error(`ffmpeg WebM encoding failed: ${res.stderr}`);
+ }
+ return { backend: "ffmpeg", path: absOut, bytes: fs.statSync(absOut).size };
+ } finally {
+ if (fs.existsSync(tmpRaw)) fs.unlinkSync(tmpRaw);
+ }
+}
+
+export function encodeAnimatedWebP(frames, width, height, fps = 30, outPath) {
+ const caps = detectCapabilities();
+ const absOut = path.resolve(outPath);
+ const durationMs = Math.max(8, Math.round(1000 / fps));
+
+ if (caps.cwebpPath && caps.webpmuxPath) {
+ const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "loop-studio-webp-"));
+ try {
+ const muxArgs = [];
+ for (let i = 0; i < frames.length; i++) {
+ const pngPath = path.join(tmpDir, `f_${i}.png`);
+ const webpPath = path.join(tmpDir, `f_${i}.webp`);
+ fs.writeFileSync(pngPath, encodePNG(frames[i], width, height, 1));
+ const cw = spawnSync(caps.cwebpPath, ["-quiet", "-q", "88", pngPath, "-o", webpPath], { encoding: "utf8" });
+ if (cw.status !== 0) {
+ throw new Error(`cwebp failed on frame ${i}: ${cw.stderr}`);
+ }
+ muxArgs.push("-frame", webpPath, `+${durationMs}+0+0+1-b`);
+ }
+ muxArgs.push("-loop", "0", "-o", absOut);
+
+ const mux = spawnSync(caps.webpmuxPath, muxArgs, { encoding: "utf8" });
+ if (mux.status !== 0) {
+ throw new Error(`webpmux failed: ${mux.stderr}`);
+ }
+ return { backend: "cwebp+webpmux", path: absOut, bytes: fs.statSync(absOut).size };
+ } finally {
+ fs.rmSync(tmpDir, { recursive: true, force: true });
+ }
+ }
+
+ if (caps.ffmpegPath) {
+ const tmpRaw = path.join(os.tmpdir(), `loop-studio-webp-${process.pid}-${Date.now()}.rgba`);
+ try {
+ const fd = fs.openSync(tmpRaw, "w");
+ for (const frame of frames) fs.writeSync(fd, frame);
+ fs.closeSync(fd);
+ const res = spawnSync(
+ caps.ffmpegPath,
+ [
+ "-y",
+ "-f", "rawvideo",
+ "-pix_fmt", "rgba",
+ "-s", `${width}x${height}`,
+ "-r", String(fps),
+ "-i", tmpRaw,
+ "-vcodec", "libwebp",
+ "-loop", "0",
+ "-q:v", "85",
+ absOut
+ ],
+ { encoding: "utf8" }
+ );
+ if (res.status !== 0) {
+ throw new Error(`ffmpeg WebP encoding failed: ${res.stderr}`);
+ }
+ return { backend: "ffmpeg", path: absOut, bytes: fs.statSync(absOut).size };
+ } finally {
+ if (fs.existsSync(tmpRaw)) fs.unlinkSync(tmpRaw);
+ }
+ }
+
+ throw new Error("No Animated WebP encoder found (requires cwebp+webpmux or ffmpeg).");
}
diff --git a/tool/scripts/encode-mp4.swift b/tool/scripts/encode-mp4.swift
new file mode 100644
index 0000000..f9587ff
--- /dev/null
+++ b/tool/scripts/encode-mp4.swift
@@ -0,0 +1,146 @@
+import Foundation
+import AVFoundation
+import CoreVideo
+import CoreMedia
+
+let args = CommandLine.arguments
+guard args.count >= 7,
+ let width = Int(args[2]),
+ let height = Int(args[3]),
+ let fps = Int(args[4]),
+ let totalFrames = Int(args[5]) else {
+ fputs("Usage: encode-mp4.swift \n", stderr)
+ exit(1)
+}
+
+let rawPath = args[1]
+let outPath = args[6]
+let encW = width % 2 == 0 ? width : width + 1
+let encH = height % 2 == 0 ? height : height + 1
+let safeFps = max(1, fps)
+
+let outURL = URL(fileURLWithPath: outPath)
+try? FileManager.default.removeItem(at: outURL)
+
+guard let fileHandle = FileHandle(forReadingAtPath: rawPath) else {
+ fputs("Cannot open raw RGBA file: \(rawPath)\n", stderr)
+ exit(1)
+}
+defer { try? fileHandle.close() }
+
+do {
+ let writer = try AVAssetWriter(outputURL: outURL, fileType: .mp4)
+ let bitRate = max(1_800_000, min(16_000_000, encW * encH * safeFps / 3))
+ let videoSettings: [String: Any] = [
+ AVVideoCodecKey: AVVideoCodecType.h264,
+ AVVideoWidthKey: encW,
+ AVVideoHeightKey: encH,
+ AVVideoCompressionPropertiesKey: [
+ AVVideoAverageBitRateKey: bitRate,
+ AVVideoProfileLevelKey: AVVideoProfileLevelH264HighAutoLevel,
+ AVVideoMaxKeyFrameIntervalKey: safeFps
+ ]
+ ]
+
+ let input = AVAssetWriterInput(mediaType: .video, outputSettings: videoSettings)
+ input.expectsMediaDataInRealTime = false
+
+ let sourceAttrs: [String: Any] = [
+ kCVPixelBufferPixelFormatTypeKey as String: kCVPixelFormatType_32BGRA,
+ kCVPixelBufferWidthKey as String: encW,
+ kCVPixelBufferHeightKey as String: encH
+ ]
+ let adaptor = AVAssetWriterInputPixelBufferAdaptor(
+ assetWriterInput: input,
+ sourcePixelBufferAttributes: sourceAttrs
+ )
+
+ guard writer.canAdd(input) else {
+ fputs("Cannot add AVAssetWriterInput\n", stderr)
+ exit(1)
+ }
+ writer.add(input)
+
+ guard writer.startWriting() else {
+ fputs("startWriting failed: \(writer.error?.localizedDescription ?? "unknown")\n", stderr)
+ exit(1)
+ }
+ writer.startSession(atSourceTime: .zero)
+
+ let frameByteCount = width * height * 4
+ let srcRowBytes = width * 4
+
+ for f in 0.. BGRA
+ dst[di] = src[si + 2]
+ dst[di + 1] = src[si + 1]
+ dst[di + 2] = src[si]
+ dst[di + 3] = src[si + 3]
+ }
+ }
+ }
+ }
+ CVPixelBufferUnlockBaseAddress(pixelBuffer, [])
+
+ let pts = CMTime(value: Int64(f), timescale: Int32(safeFps))
+ if !adaptor.append(pixelBuffer, withPresentationTime: pts) {
+ fputs("Failed to append frame \(f): \(writer.error?.localizedDescription ?? "unknown")\n", stderr)
+ exit(1)
+ }
+ }
+
+ input.markAsFinished()
+ let sem = DispatchSemaphore(value: 0)
+ writer.finishWriting {
+ sem.signal()
+ }
+ sem.wait()
+
+ if writer.status != .completed {
+ fputs("AVAssetWriter finished with status \(writer.status.rawValue): \(writer.error?.localizedDescription ?? "unknown")\n", stderr)
+ exit(1)
+ }
+} catch {
+ fputs("MP4 encoding error: \(error)\n", stderr)
+ exit(1)
+}
diff --git a/tool/test/run-evals.js b/tool/test/run-evals.js
index f4b693c..367bc9c 100644
--- a/tool/test/run-evals.js
+++ b/tool/test/run-evals.js
@@ -6,10 +6,12 @@
// each fail the exact check designed to catch them.
import fs from "node:fs";
+import os from "node:os";
import path from "node:path";
import { fileURLToPath, pathToFileURL } from "node:url";
import { analyzeSeam, analyzeLegibility, analyzeSources } from "../lib/analyzers.js";
import { renderAllFrames } from "../lib/compositor.js";
+import { detectCapabilities, encodeAnimatedWebP } from "../lib/encoders.js";
const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);
@@ -179,10 +181,43 @@ function testGalleryArtifacts() {
}
}
+async function testHighFpsRendering() {
+ console.log("\n=== 4. High-FPS (60 fps) Video Pipeline ===");
+ const p = path.join(REPO_ROOT, "skills", "styles", "particle-orbit", "template.js");
+ const mod = await import(pathToFileURL(p).href);
+ const { frames, width, height, fps, totalFrames } = renderAllFrames(mod, {
+ width: 160,
+ height: 160,
+ seconds: 1,
+ fps: 60
+ });
+ const seam = analyzeSeam(frames, width, height);
+ assert(
+ fps === 60 && totalFrames === 60 && frames.length === 60 && seam.pass,
+ `60fps render produces 60 exact frames with passing seam (seamScore=${seam.seamScore}, dup=${seam.duplicateFrames})`
+ );
+
+ const caps = detectCapabilities();
+ if (caps.cwebpPath && caps.webpmuxPath) {
+ const tmpWebp = path.join(os.tmpdir(), `loop-eval-60fps-${process.pid}.webp`);
+ try {
+ const res = encodeAnimatedWebP(frames.slice(0, 12), width, height, 60, tmpWebp);
+ const header = fs.readFileSync(tmpWebp).subarray(0, 12).toString("ascii");
+ assert(
+ res.bytes > 0 && header.startsWith("RIFF") && header.endsWith("WEBP"),
+ `60fps Animated WebP encodes cleanly (${res.bytes} bytes via ${res.backend})`
+ );
+ } finally {
+ if (fs.existsSync(tmpWebp)) fs.unlinkSync(tmpWebp);
+ }
+ }
+}
+
async function main() {
await testTemplates();
testNegativeGates();
testGalleryArtifacts();
+ await testHighFpsRendering();
console.log(`\n========================================`);
console.log(`Loop Studio Evals: ${passed} passed, ${failed} failed`);