cosmicstack-labs/lazy-frames

Lazy Frames

Lazy Frames génère une vidéo à partir d'une spécification JSON typée — une composition est un fichier spec.json dont les scènes indiquent le timing, le contenu et le style ; la CLI le transforme en un MP4 déterministe et pixel-parfait. Le moteur de rendu principal ne nécessite ni cloud ni clés. Les plugins vérifiés peuvent utiliser des services externes explicitement déclarés ; les médias générés sont mis en cache localement avant le rendu déterministe.

Version actuelle de la CLI : [email protected].

• Les captures de site web sont rognées au centre par défaut dans les scènes browser-frame, ui-callout et les scènes parallax (plate et en profondeur). Ne surchargez params.position que lorsque le sujet nécessite un ancrage différent.
• Les commandes capture, check, gen, preview et render affichent les phases en direct sur stderr. La commande render affiche les pourcentages des images. Avec --json, stdout reste un JSON lisible par machine.

1. Démarrer depuis l'état du projet

État	Action
Projet existant avec spec.json	Lire le spec, effectuer la modification ou exécuter l'opération demandée. Ignorer le routage.
Nouvelle demande avec une URL de site web	Router vers le workflow website-promo (§ 3).
Nouvelle demande avec un brief textuel	Router vers le workflow cinematic (§ 3).
Nouvelle demande avec une séquence existante	Router vers le workflow edit (§ 3).
Incertain	Poser une question : « S'agit-il d'un site web spécifique, d'un sujet/brief, ou d'une vidéo existante ? »

2. Prérequis

node --version   # >= 20
ffmpeg -version  # requis
python3 --version   # Python 3 ; sur Windows `python` est acceptable
ls "/Applications/Google Chrome.app"  # macOS ; Windows utilise Chrome dans Program Files, ou définissez CHROME_PATH

Installation depuis npm :

npm install lazy-frames
npx lazy doctor

Ou compilation depuis les sources :

npm install && npm run build

Vérifier l'environnement :

node packages/cli/dist/index.js doctor

Le diagnostic indique : plateforme/mémoire du nœud, version + niveau de Python et disponibilité des fournisseurs (imagerie procédurale, profondeur, musique, TTS). La narration locale utilise tts.say (macOS say ou SAPI Windows) ; les fournisseurs externes sont installés en tant que plugins dédiés. Si image.mlx-photoreal est indisponible (attendu sur les machines <16 Go), le générateur d'images procédurales est utilisé à la place — il produit toujours des images cinématiques, mais pas photoréalistes.

Plugins et fournisseurs externes

ElevenLabs est inclus par défaut mais nécessite toujours une approbation au niveau du projet avant toute utilisation réseau. Lorsque l'utilisateur demande un fournisseur ou une capacité de narration, cherchez dans le registre, inspectez son état et ses autorisations, et demandez avant d'approuver ou d'installer :

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

Les structures du Marketplace peuvent être installées mais ne peuvent pas s'exécuter tant qu'un adaptateur vérifié n'est pas livré. N'installez jamais d'URL de package arbitraire et ne stockez pas de clés API dans les fichiers du projet. ElevenLabs lit ELEVENLABS_API_KEY depuis l'environnement. Registre : https://lazy-frames.cosmicstack.ai/plugins/index.json

3. Workflows

website-promo

Entrée : une URL. Sortie : un MP4 promotionnel/démonstration construit à partir des visuels capturés du site.

# 1. Capturer le site (captures d'écran @2x, palette, contenu, polices, logo)
node packages/cli/dist/index.js capture https://example.com projects/acme

# 2. Examiner le spec de départ généré + les actifs capturés
cat projects/acme/spec.json
ls projects/acme/assets/sites/example.com/

# 3. Modifier le spec si nécessaire (ajuster les scènes, le contenu, le timing, les transitions)

# 4. Valider + exécuter les contrôles
node packages/cli/dist/index.js snapshot projects/acme --update
node packages/cli/dist/index.js check projects/acme

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

La commande capture écrit :

• assets/sites/<domain>/hero.png + full.png (captures d'écran en 2x DPR)
• assets/sites/<domain>/ledger.json (palette, polices, blocs de texte, métadonnées)
• Un spec.json de départ avec 5 scènes construites à partir du contenu capturé
• Les scènes de capture d'écran utilisent explicitement { "x": "center", "y": "center" } sauf si le spec remplace l'ancrage de recadrage

cinematic

Entrée : un brief textuel ou un sujet. Sortie : un clip cinématique de 30 à 60 secondes avec images générées, parallaxe de profondeur, narration, musique, effets sonores.

# 1. Générer des images procédurales + cartes de profondeur correspondantes
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. Écrire spec.json en référençant les actifs générés (voir references/spec-format.md)

# 3. Rédiger un script de narration lié à la scène, puis générer les actifs audio optionnels
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 "Chaque image calculée localement." --name n1

# 4. Valider + rendu
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

Entrée : une séquence existante (MP4) + un brief. Sortie : la séquence composée dans une vidéo avec overlays, étalonnage, transitions.

Écrivez un spec avec des scènes video-layer référençant le fichier de séquence, ainsi que des scènes de typographie/atmosphère pour les titres et les transitions. Le moteur gère la recherche dans la vidéo (extraction d'image déterministe par machine). Voir references/scene-types.md pour les paramètres de video-layer.

4. Contrat de l'agent

Le travail de l'agent dans tous les workflows :

1. Rechercher l'entrée (lire le site, comprendre le brief, inspecter la séquence).
2. Produire ou affiner spec.json — un spec typé valide (voir references/spec-format.md).
3. Générer le script de narration lorsque demandé (lazy script <project> --apply), puis examiner ses étapes liées à la scène.
4. Générer les actifs si nécessaire (lazy gen image, lazy gen music, lazy gen tts).
5. Exécuter lazy check et corriger chaque erreur. Les avertissements sont indicatifs.
6. Exécuter lazy snapshot --update pour établir la base de référence de régression.
7. Exécuter lazy check à nouveau — les contrôles de snapshot + déterminisme de recherche doivent passer.
8. Exécuter lazy preview et transmettre l'URL à l'utilisateur. Demander s'il faut réviser ou effectuer le rendu.
9. Effectuer le rendu uniquement après approbation. lazy render — jamais avant que l'utilisateur ne donne son accord.
10. Vérifier la sortie : confirmer que le fichier existe, n'est pas vide et a la durée attendue.
11. Signaler le chemin de sortie + sha256.

Règles non négociables

• Ne jamais effectuer le rendu avant l'approbation de l'utilisateur. Toujours s'arrêter à l'aperçu.
• Ne jamais ignorer lazy check. Il détecte les erreurs de schéma, les actifs manquants et le non-déterminisme.
• Toujours exécuter lazy snapshot --update avant le premier lazy check dans un nouveau projet.
• Ne jamais modifier .lazy/ — il est généré. Modifiez spec.json et relancez le rendu.
• Ne jamais installer un plugin non vérifié ni persister des identifiants de fournisseurs. Utilisez le registre et les variables d'environnement.
• Référencez les actifs par des chemins relatifs au projet dans le spec (ex : assets/gen/ridge-01.png).
• Les scènes sont séquentielles avec un chevauchement optionnel. Chevauchement + fondu/dissolution = fondu enchaîné.
• Tous les timings sont en millisecondes. Les heures de début sont absolues depuis le début de la composition.
• Convention de palette : palette[0] = arrière-plan, palette[1] = accent, palette[2] = premier plan.
• La largeur/hauteur doit être paire (exigence h264 yuv420p).
• Les polices sont fournies : Inter (corps) et Space Grotesk (affichage). Pas de polices externes.
• La progression appartient à stderr. Les commandes utilisant --json réservent stdout pour leur résultat JSON final.

5. Concepts clés

Déterminisme

Même spec + même machine = MP4 identique octet par octet (vérifié par sha256). Trois indicateurs Chrome imposent cela : --jitless (interpréteur V8 uniquement), --use-angle=swiftshader (rendu logiciel) et l'arrondi des transformations en pixels entiers dans l'exécution. Le rendu de texte CSS en sous-pixels est non déterministe d'une session à l'autre — l'exécution aligne toutes les transformations sur des pixels entiers.

Contrôles

lazy check exécute deux contrôles bloquants :

• Régression des snapshots : effectue le rendu des images clés (milieux de scène + milieux de transition), hache leurs pixels et compare avec snapshots/baseline.json. Toute dérive = erreur avec la scène + l'horodatage.
• Déterminisme de recherche : effectue le rendu de 5 horodatages échantillonnés deux fois dans une même session de navigateur, compare les hachages.

Audio

L'audio est déclaratif dans le spec (narration, music, sfx). Le moteur de rendu génère et met en cache un WAV canonique, puis le mixe via ffmpeg :

• Narration : say local ou un plugin TTS installé, placé à startMs ou ancré à sceneId + offsetMs
• Musique : synthèse procédurale (nappes d'accords + percussion) initialisée par seed, en boucle sur la durée de la vidéo
• Effets sonores : whoosh/hit/rise/boom synthétisés, placés à atMs avec gain

LUT / étalonnage

Deux couches :

• Étalonnage de scène (style.grade) : préréglage de filtre CSS sur la racine de la composition (rapide, subtil)
• LUT de sortie (outputs[0].lut) : fichier .cube LUT 3D appliqué via ffmpeg lut3d lors de l'encodage (étalonnage cinématique). LUT fournies : teal-orange, noir-film, faded-vintage.

6. Références

Fichier	URL	Lisez-le pour…
spec-format.md	https://lazy-frames.cosmicstack.ai/references/spec-format.md	rédiger un spec.json valide — schéma complet, tous les champs, valeurs par défaut
scene-types.md	https://lazy-frames.cosmicstack.ai/references/scene-types.md	choisir un type de scène et configurer ses paramètres
workflows.md	https://lazy-frames.cosmicstack.ai/references/workflows.md	instructions étape par étape pour les workflows website-promo, cinematic et edit
cli.md	https://lazy-frames.cosmicstack.ai/references/cli.md	toutes les commandes CLI avec indicateurs et exemples
gates.md	https://lazy-frames.cosmicstack.ai/references/gates.md	utilisation des contrôles de régression des snapshots + déterminisme de recherche

Ces références sont également disponibles dans le paquet installé sous skill/references/ et dans le dépôt sous skill/references/.