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`);