cosmicstack-labs/lazy-frames

Lazy Frames

Lazy Frames rendert Videos aus einem typisierten JSON-Spec – eine Komposition ist eine spec.json-Datei, deren Szenen Timing, Inhalt und Stil deklarieren; die CLI wandelt sie in ein deterministisches, pixelgenaues MP4 um. Der Kern-Renderer benötigt weder Cloud noch Schlüssel. Geprüfte Plugins können explizit deklarierte externe Dienste nutzen; generierte Medien werden vor dem deterministischen Rendern lokal zwischengespeichert.

Aktuelle CLI-Version: [email protected].

• Erfasste Website-Medien werden standardmäßig zentriert in browser-frame, ui-callout sowie in parallax-Szenen (flach und mit Tiefe) beschnitten. Überschreibe params.position nur, wenn das Motiv einen anderen Ankerpunkt erfordert.
• capture, check, gen, preview und render melden Live-Phasen auf stderr. Render meldet Rahmenprozentsätze. Mit --json bleibt stdout sauberes, maschinenlesbares JSON.

1. Start vom Projektzustand

Zustand	Aktion
Bestehendes Projekt mit spec.json	Das Spezifikation lesen, die Änderung vornehmen oder den angeforderten Vorgang ausführen. Routing überspringen.
Neue Anfrage mit einer Website-URL	Zum Workflow website-promo weiterleiten (§ 3).
Neue Anfrage mit einer Textbeschreibung	Zum Workflow cinematic weiterleiten (§ 3).
Neue Anfrage mit vorhandenem Filmmaterial	Zum Workflow edit weiterleiten (§ 3).
Unklar	Eine Frage stellen: „Geht es um eine bestimmte Website, ein Thema/eine Beschreibung oder um vorhandenes Videomaterial?“

2. Voraussetzungen

node --version   # >= 20
ffmpeg -version  # erforderlich
python3 --version   # Python 3; unter Windows ist `python` in Ordnung
ls "/Applications/Google Chrome.app"  # macOS; Windows verwendet Chrome in „Program Files“ oder setze CHROME_PATH

Installation von npm:

npm install lazy-frames
npx lazy doctor

Oder aus dem Quellcode erstellen:

npm install && npm run build

Umgebung überprüfen:

node packages/cli/dist/index.js doctor

doctor meldet: Node-Plattform/Speicher, Python-Version + -Stufe und Verfügbarkeit von Anbietern (prozedurale Bilder, Tiefe, Musik, TTS). Lokale Sprachausgabe verwendet tts.say (macOS say oder Windows SAPI); externe Anbieter werden als bereichsbezogene Plugins installiert. Wenn image.mlx-photoreal nicht verfügbar ist (erwartet auf Rechnern mit <16 GB), wird stattdessen der prozedurale Bildgenerator verwendet – erzeugt immer noch filmische Standbilder, nur nicht fotorealistisch.

Plugins und externe Anbieter

ElevenLabs ist standardmäßig enthalten, erfordert aber dennoch eine projektbezogene Genehmigung vor der Netzwerknutzung. Wenn der Benutzer einen Anbieter oder eine Storytelling-Funktion anfordert, durchsuche die Registry, überprüfe seinen Status und die Berechtigungen und frage nach, bevor du es genehmigst oder installierst:

node packages/cli/dist/index.js plugin search tts
node packages/cli/dist/index.js plugin info elevenlabs
node packages/cli/dist/index.js plugin install elevenlabs -p projects/cine

Marketplace-Gerüste können installiert werden, aber erst ausgeführt werden, wenn ein geprüfter Adapter ausgeliefert wird. Installiere niemals willkürliche Paket-URLs oder speichere API-Schlüssel in Projektdateien. ElevenLabs liest ELEVENLABS_API_KEY aus der Umgebung. Registry: https://lazy-frames.cosmicstack.ai/plugins/index.json

3. Workflows

website-promo

Eingabe: eine URL. Ausgabe: ein Werbe-/Präsentations-MP4, das aus den eigenen erfassten visuellen Elementen der Website erstellt wurde.

# 1. Website erfassen (Screenshots @2x, Farbpalette, Text, Schriftarten, Logo)
node packages/cli/dist/index.js capture https://example.com projects/acme

# 2. Das generierte Start-Spec und die erfassten Assets überprüfen
cat projects/acme/spec.json
ls projects/acme/assets/sites/example.com/

# 3. Das Spec bei Bedarf bearbeiten (Szenen, Text, Timing, Übergänge anpassen)

# 4. Validieren + Prüfungen ausführen
node packages/cli/dist/index.js snapshot projects/acme --update
node packages/cli/dist/index.js check projects/acme

# 5. Rendern
node packages/cli/dist/index.js render projects/acme

Der Capture-Befehl schreibt:

• assets/sites/<domain>/hero.png + full.png (Screenshots mit 2x DPR)
• assets/sites/<domain>/ledger.json (Farbpalette, Schriftarten, Textblöcke, Metadaten)
• Ein Start-spec.json mit 5 Szenen, die aus dem erfassten Inhalt erstellt wurden
• Screenshot-Szenen verwenden explizit { "x": "center", "y": "center" }, es sei denn, das Spezifikation überschreibt den Zuschneideanchor

cinematic

Eingabe: eine Textbeschreibung oder ein Thema. Ausgabe: ein 30–60 s filmischer Clip mit generierten Standbildern, Tiefen-Parallax, Sprachausgabe, Musik, Soundeffekten.

# 1. Prozedurale Standbilder + passende Tiefenkarten generieren
node packages/cli/dist/index.js gen image -p projects/cine --seed 21 --style ridge --palette "#070B14,#F59E4C,#F4F7FB" --name ridge-01
node packages/cli/dist/index.js gen image -p projects/cine --seed 42 --style dune --palette "#070B14,#7FB7D9,#F4F7FB" --name dune-01

# 2. spec.json schreiben, das auf die generierten Assets verweist (siehe references/spec-format.md)

# 3. Szenenverknüpfte Erzählung entwerfen, dann optionale Audio-Assets generieren
node packages/cli/dist/index.js script projects/cine --apply
node packages/cli/dist/index.js gen music -p projects/cine --mood calm --bpm 90 --bars 12 --seed 21
node packages/cli/dist/index.js gen tts -p projects/cine --text "Every frame computed locally." --name n1

# 4. Validieren + rendern
node packages/cli/dist/index.js snapshot projects/cine --update
node packages/cli/dist/index.js check projects/cine
node packages/cli/dist/index.js render projects/cine

edit

Eingabe: vorhandenes Filmmaterial (MP4) + eine Beschreibung. Ausgabe: das Filmmaterial, das in ein Video mit Überlagerungen, Grading und Übergängen eingebettet ist.

Schreibe ein Spec mit video-layer-Szenen, die auf die Filmmaterialdatei verweisen, sowie Typografie-/Atmosphären-Szenen für Titel und Übergänge. Die Engine steuert die Videopositionierung (deterministische, maschinenabhängige Frameextraktion). Siehe references/scene-types.md für video-layer-Parameter.

4. Agentenvertrag

Die Aufgabe des Agenten erstreckt sich über alle Workflows:

1. Recherchiere die Eingabe (lese die Website, verstehe die Beschreibung, inspiziere das Filmmaterial).
2. Erstelle oder verfeinere spec.json – ein gültiges typisiertes Spec (siehe references/spec-format.md).
3. Generiere das Erzählskript auf Anfrage (lazy script <project> --apply), überprüfe dann seine szenenverknüpften Abschnitte.
4. Generiere Assets bei Bedarf (lazy gen image, lazy gen music, lazy gen tts).
5. Führe lazy check aus und behebe alle Fehler. Warnungen sind nur Hinweise.
6. Führe lazy snapshot --update aus, um die Regressionsbasislinie zu erstellen.
7. Führe erneut lazy check aus – Snapshot- und Such-Determinismus-Prüfungen müssen bestanden werden.
8. Führe lazy preview aus und übergib die URL dem Benutzer. Frage, ob überarbeitet oder gerendert werden soll.
9. Rendere erst nach Genehmigung. lazy render – niemals, bevor der Benutzer nicht grünes Licht gegeben hat.
10. Überprüfe die Ausgabe: bestätige, dass die Datei existiert, nicht leer ist und die erwartete Dauer hat.
11. Melde den Ausgabepfad + sha256.

Unverhandelbare Regeln

• Rendere niemals vor der Benutzerfreigabe. Halte immer bei der Vorschau an.
• Überspringe niemals lazy check. Es erfasst Schemafehler, fehlende Assets und Nichtdeterminismus.
• Führe immer lazy snapshot --update vor dem ersten lazy check in einem neuen Projekt aus.
• Bearbeite niemals .lazy/ – es wird generiert. Bearbeite spec.json und rendere erneut.
• Installiere niemals ein ungeprüftes Plugin oder speichere Anbieter-Anmeldedaten. Verwende die Registry und Umgebungsvariablen.
• Verweise im Spec auf Assets mit projektspezifischen Pfaden (z. B. assets/gen/ridge-01.png).
• Szenen sind sequenziell mit optionaler Überlappung. Überlappung + Ein-/Ausblenden = Überblendung.
• Alle Zeitangaben sind in Millisekunden. Startzeiten sind absolut zum Kompositionsbeginn.
• Farbpaletten-Konvention: palette[0] = Hintergrund, palette[1] = Akzent, palette[2] = Vordergrund.
• Breite/Höhe müssen gerade sein (h264 yuv420p Anforderung).
• Schriftarten sind gebündelt: Inter (Fließtext) und Space Grotesk (Überschriften). Keine externen Schriftarten.
• Fortschritt gehört auf stderr. Befehle, die --json verwenden, reservieren stdout für ihr endgültiges JSON-Ergebnis.

5. Schlüsselkonzepte

Determinismus

Gleiches Spec + gleicher Rechner = byte-identisches MP4 (überprüft durch sha256). Drei Chrome-Flags erzwingen dies: --jitless (nur V8-Interpreter), --use-angle=swiftshader (Software-Rendering) und Integer-Pixel-Transformationsrundung in der Laufzeit. CSS-Subpixel-Text-Rendering ist sitzungsübergreifend nichtdeterministisch – die Laufzeit rundet alle Transformationen auf ganze Pixel.

Prüfungen

lazy check führt zwei blockierende Prüfungen durch:

• Snapshot-Regression: rendert Keyframes (Szenenmittelpunkte + Übergangsmittelpunkte), hasht deren Pixel und vergleicht sie mit snapshots/baseline.json. Abweichung = Fehler mit Szene + Zeitstempel.
• Such-Determinismus: rendert 5 abgetastete Zeitstempel zweimal in einer Browsersitzung und vergleicht die Hashes.

Audio

Audio ist deklarativ im Spec (narration, music, sfx). Der Renderer generiert und zwischenspeichert kanonische WAV-Audiodateien und mischt dann über ffmpeg:

• Sprachausgabe: lokal say oder ein installiertes TTS-Plugin, platziert bei startMs oder verankert an sceneId + offsetMs
• Musik: prozeduraler Synthesizer (Akkordflächen + Percussion) mit Startwert seed, auf Videodauer geloopt
• Soundeffekte: synthetisierte Whoosh/Hit/Rise/Boom, platziert bei atMs mit Verstärkung

LUT / Grading

Zwei Ebenen:

• Stufen-Grading (style.grade): CSS-Filter-Voreinstellung auf der Kompositionswurzel (schnell, subtil)
• Ausgabe-LUT (outputs[0].lut): 3D LUT .cube-Datei, angewendet über ffmpeg lut3d während der Kodierung (filmischer Farbgrad). Gebündelte LUTs: teal-orange, noir-film, faded-vintage.

6. Referenzen

Datei	URL	Lies sie, um…
spec-format.md	https://lazy-frames.cosmicstack.ai/references/spec-format.md	ein gültiges spec.json zu erstellen – vollständiges Schema, alle Felder, Standardwerte
scene-types.md	https://lazy-frames.cosmicstack.ai/references/scene-types.md	einen Szenentyp auszuwählen und seine Parameter zu konfigurieren
workflows.md	https://lazy-frames.cosmicstack.ai/references/workflows.md	Schritt-für-Schritt-Anleitung für die Workflows „website-promo“, „cinematic“ und „edit“
cli.md	https://lazy-frames.cosmicstack.ai/references/cli.md	jeden CLI-Befehl mit Flags und Beispielen
gates.md	https://lazy-frames.cosmicstack.ai/references/gates.md	Verwendung der Snapshot-Regression und Such-Determinismus-Prüfungen

Diese Referenzen sind auch im installierten Paket unter skill/references/ und im Repository unter skill/references/ verfügbar.