lazy-frames README

The project's README from github.com/cosmicstack-labs/lazy-frames. As one markdown file: README.md.

Lazy Frames — agentic video generation, byte-stable and fully local

Lazy Frames

npm version license

Agentic video generation. Feed a skill URL to your AI agent — it captures, authors a spec, runs the gates, and renders a pixel-perfect MP4. The core runs fully locally with no keys; reviewed plugins can opt into explicitly declared external services.

Same spec + same machine = byte-identical MP4, every time.

Part of CosmicStack.AI.

Give it to your agent

Paste the raw Markdown skill URL into your AI agent:

https://lazy-frames.cosmicstack.ai/skill.md

For example: Read this skill, then make a promo video for https://example.com.


Install

From npm

npm install lazy-frames

Then run any command via npx:

npx lazy doctor
npx lazy capture https://example.com projects/acme
npx lazy render projects/acme

From source (for development or the agentic skill)

git clone https://github.com/cosmicstack-labs/lazy-frames.git
cd lazy-frames
npm install && npm run build
node packages/cli/dist/index.js doctor

Prerequisites

Dependency Required for Check
Node.js ≥ 20 CLI + engine node --version
ffmpeg + ffprobe encoding + audio ffmpeg -version
Google Chrome headless rendering lazy doctor (Windows: Chrome/Edge in Program Files, or CHROME_PATH)
Python 3 audio sidecar (music, TTS, SFX) python3 --version or python --version; override with LAZY_PYTHON
Local TTS narration (say or Windows SAPI) lazy doctor
ELEVENLABS_API_KEY Optional ElevenLabs plugin lazy doctor

Run npx lazy doctor to verify all providers and see your hardware tier.

Quick start

Website promo — from URL to MP4

npx lazy capture https://example.com projects/acme
npx lazy snapshot projects/acme --update
npx lazy check projects/acme
npx lazy preview projects/acme       # review in browser
# ... approve ...
npx lazy render projects/acme         # byte-stable MP4

lazy capture writes screenshots @2x, palette, copy blocks, fonts, logo, and a starter spec.json.

Cinematic — generated stills + depth parallax + audio

npx lazy gen image -p projects/cine --seed 21 --style ridge --name r01
npx lazy gen music -p projects/cine --mood calm --bpm 90 --seed 21 --name bgm
# write spec.json referencing assets/gen/r01.png + r01.depth.png
npx lazy render projects/cine

Plugin marketplace

The Lazy Frames Plugin Marketplace indexes folder-owned, schema-validated extensions and their exact permissions. ElevenLabs is the only plugin included by default; running install grants project-scoped approval for external access:

npx lazy plugin install elevenlabs -p projects/cine
export ELEVENLABS_API_KEY="your-key"
npx lazy script projects/cine --provider elevenlabs --voice YOUR_VOICE_ID --apply
npx lazy render projects/cine

Each narration beat is anchored with sceneId and offsetMs, so the spoken line starts on the intended screen. Generated audio is normalized to canonical WAV and cached; the API key is never written to project files. Plugin dependencies are fingerprint-locked in the project, while consent is stored separately as a user-local, project-scoped approval.

Browse 16 plugins across voice, storytelling, visuals, audio, captions, and delivery, or run npx lazy plugin search. The other integrations are installable scaffolds: their manifests and permission locks work now, while execution remains blocked until a reviewed adapter ships.

Contributors add one self-contained plugins/<id>/manifest.json folder and run npm run plugins:build; the CLI registry, machine index, marketplace card, and detail page are generated from that folder.

CLI commands

Command What it does
lazy doctor Environment + provider capability report
lazy capture <url> [project] Capture a website → screenshots, palette, copy, starter spec
lazy gen image Generate procedural still + matching depth map
lazy gen music Generate procedural music WAV
lazy gen tts Generate TTS narration WAV (macOS say or Windows SAPI)
lazy script <project> Draft editable, scene-linked narration beats
lazy plugin search Search reviewed plugins by name or capability
lazy plugin info <id> Inspect status, provider, permissions, and detail URL
lazy plugin install <id> Install a fingerprinted plugin into a project
lazy check <project> Validate spec + run snapshot & determinism gates
lazy snapshot <project> --update Establish/refresh the regression baseline
lazy render <project> Render to MP4 (byte-stable, with audio)
lazy preview <project> Scrubbable timeline preview at localhost:4173, with mixed audio when the spec has it

Scene types

Type What it does
typography Text reveals: titles, quotes, lockups (4 reveal styles)
stat-hit Count-up numbers, labels, bars
browser-frame Screenshot in a browser chrome mockup with cursor
ui-callout Screenshot with dimmed mask, hotspot spotlight, label
atmosphere Drifting gradient blobs — ambient backdrops
parallax 2.5D camera move over a still (flat or depth-map mode)
video-layer Footage playback with trim, speed, grade
three-scene Deterministic 3D: cube/ico/grid/particles (canvas 2D)

Plus: 7 transitions (cut, fade, dissolve, whip-pan, light-leak, dip-to-black, luma-wipe), stage-level CSS grade presets, output-level 3D LUT pipeline, and declarative audio (narration + music + SFX).

Agentic skill

Lazy Frames ships with a complete agent skill. Point any coding agent at skill/SKILL.md — it contains the full routing rules, agent contract, and reference docs. The agent reads the skill (not the source code) and knows how to capture, author, check, preview, and render.

skill/
  SKILL.md                    ← entry point + routing + agent contract
  references/
    spec-format.md             ← full spec schema
    scene-types.md             ← all 8 scene types
    workflows.md               ← website-promo / cinematic / edit
    cli.md                     ← every CLI command
    gates.md                   ← determinism + snapshot gates

Determinism

Same spec + same machine = byte-identical MP4 (SHA-256 verified). Enforced by:

Examples

Verify

npm run verify:demo        # byte-stability (two renders, sha256 compare)
npm run verify:cinematic   # gen assets + gates + audio determinism

Architecture

spec.json (typed JSON)
  ├─ @lazy/engine       compile spec → HTML composition + channel data
  ├─ @lazy/renderer     headless Chrome (jitless + swiftshader) → frames → ffmpeg → MP4
  ├─ @lazy/capture      site screenshots + palette/copy/font/logo extraction
  ├─ @lazy/gen-sidecar  Python: procedural music, TTS (say), SFX synthesis
  └─ @lazy/cli          lazy capture | gen | check | snapshot | render | preview | doctor

License

MIT © CosmicStack Labs

lazy-frames (cosmicstack-labs/lazy-frames)

Searching Database…

What is this?Lazy Frames is an agentic video generation tool: you feed a skill URL to your AI coding agent, which captures source material, authors a spec, and renders it into a pixel-perfect, byte-stable MP4, with the core pipeline running fully locally and no cloud required.
Is this a CLI tool or a library I import?It is a Node.js CLI (the `lazy` command, run via npx) paired with an agent skill file that coding agents read to drive capture, authoring, checking, and rendering — it is not a library you import into your own code.
How do I get it running?Install with `npm install lazy-frames` (or build from source for development) and run commands through npx, e.g. `npx lazy capture` to scrape a site or `npx lazy render` to produce the MP4. Run `npx lazy doctor` first to verify your environment.
What do I need installed besides the npm package?Node.js 20 or newer, ffmpeg + ffprobe for encoding, Google Chrome for headless rendering, and Python 3 for the audio sidecar (music, TTS, SFX); narration uses macOS say or Windows SAPI, with an optional ElevenLabs API key for the plugin.
Do all the plugin integrations in the marketplace actually work?Only the ElevenLabs plugin is enabled by default. The rest of the marketplace entries are installable scaffolds whose manifests and permission locks function now, but their execution stays blocked until a reviewed adapter ships.
Does my data or any API keys leave my machine?The core engine needs no keys and runs entirely locally; only explicitly reviewed plugins like ElevenLabs reach external services, and even then the API key is never written to project files.
How does it guarantee the same output every run?It renders with V8's --jitless flag, software rendering via --use-angle=swiftshader, integer-pixel CSS transforms, putImageData for canvas scenes, and bitexact ffmpeg encoding, so the same spec on the same machine yields a SHA-256 identical MP4.
What kinds of scenes can I build?Eight built-in scene types cover typography reveals, stat-hit count-ups, browser-frame mockups, UI callouts, atmosphere backdrops, parallax/depth moves, video-layer footage, and deterministic three-scene 3D, plus 7 transitions and grade/LUT presets.
Why point the agent at a skill file instead of the source code?skill/SKILL.md encodes the full routing rules and agent contract for capturing, authoring, checking, previewing and rendering, so the agent follows a defined workflow instead of having to reverse-engineer the codebase.
How many plugins are in the marketplace and what do they cover?16 reviewed plugins span voice, storytelling, visuals, audio, captions, and delivery, and can be searched with `npx lazy plugin search`.
Size
4 MB
Stars
165
Updated
CommitAug 19
Age
2mo
Commits · 90 Days