cosmicstack-labs/lazy-frames

Lazy Frames

Lazy Frames renderiza video a partir de un spec JSON tipado — una composición es un archivo spec.json cuyas escenas declaran temporización, contenido y estilo; la CLI lo convierte en un MP4 determinista y perfecto. El motor de renderizado principal no necesita nube ni claves. Los complementos revisados pueden usar servicios externos explícitamente declarados; el contenido generado se almacena en caché localmente antes del renderizado determinista.

Versión actual de la CLI: [email protected].

• El contenido del sitio web capturado se recorta centrado por defecto en browser-frame, ui-callout y en las escenas parallax planas y de profundidad. Sobreescribe params.position solo cuando el sujeto requiere un anclaje diferente.
• capture, check, gen, preview y render reportan fases en vivo en stderr. Render reporta porcentajes de fotogramas. Con --json, stdout permanece limpio como JSON legible por máquina.

1. Iniciar desde el estado del proyecto

Estado	Acción
Proyecto existente con spec.json	Leer el spec, realizar la edición o ejecutar la operación solicitada. Omitir el enrutamiento.
Solicitud nueva con una URL	Enrutar al flujo de trabajo website-promo (§ 3).
Solicitud nueva con un resumen de texto	Enrutar al flujo de trabajo cinematic (§ 3).
Solicitud nueva con metraje existente	Enrutar al flujo de trabajo edit (§ 3).
No claro	Preguntar: "¿Se trata de un sitio web específico, un tema/resumen o metraje de video existente?"

2. Requisitos previos

node --version   # >= 20
ffmpeg -version  # requerido
python3 --version   # Python 3; en Windows `python` es suficiente
ls "/Applications/Google Chrome.app"  # macOS; Windows usa Chrome en Program Files, o establece CHROME_PATH

Instalar desde npm:

npm install lazy-frames
npx lazy doctor

O compilar desde la fuente:

npm install && npm run build

Verificar el entorno:

node packages/cli/dist/index.js doctor

Doctor reporta: plataforma Node/memoria, versión de Python + nivel y disponibilidad de proveedores (imágenes procedurales, profundidad, música, TTS). La narración local usa tts.say (macOS say o Windows SAPI); los proveedores externos se instalan como complementos con ámbito. Si image.mlx-photoreal no está disponible (esperado en máquinas con <16 GB), se usa el generador de imágenes procedurales — aún produce fotogramas cinemáticos, simplemente no fotorrealistas.

Complementos y proveedores externos

ElevenLabs está incluido por defecto, pero aún requiere aprobación a nivel de proyecto antes de uso en red. Cuando el usuario solicite cualquier proveedor o capacidad narrativa, busca en el registro, inspecciona su estado y permisos, y pregunta antes de aprobarlo o instalarlo:

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

Los scaffolds del marketplace pueden instalarse pero no pueden ejecutarse hasta que llegue un adaptador revisado. Nunca instales URLs de paquetes arbitrarios ni almacenes claves API en archivos del proyecto. ElevenLabs lee ELEVENLABS_API_KEY del entorno. Registro: https://lazy-frames.cosmicstack.ai/plugins/index.json

3. Flujos de trabajo

website-promo

Entrada: una URL. Salida: un MP4 promocional/muestra construido a partir de los elementos visuales capturados del sitio.

# 1. Capturar el sitio (capturas de pantalla @2x, paleta, texto, fuentes, logo)
node packages/cli/dist/index.js capture https://example.com projects/acme

# 2. Revisar el spec inicial generado + los activos capturados
cat projects/acme/spec.json
ls projects/acme/assets/sites/example.com/

# 3. Editar el spec si es necesario (ajustar escenas, texto, temporización, transiciones)

# 4. Validar + ejecutar compuertas
node packages/cli/dist/index.js snapshot projects/acme --update
node packages/cli/dist/index.js check projects/acme

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

El comando capture escribe:

• assets/sites/<domain>/hero.png + full.png (capturas de pantalla a 2x DPR)
• assets/sites/<domain>/ledger.json (paleta, fuentes, bloques de texto, metadatos)
• Un spec.json inicial con 5 escenas construido a partir del contenido capturado
• Las escenas de captura de pantalla usan explícitamente { "x": "center", "y": "center" } a menos que el spec anule el ancla de recorte

cinematic

Entrada: un resumen de texto o tema. Salida: un clip cinemático de 30–60 s con fotogramas generados, paralaje de profundidad, narración, música, SFX.

# 1. Generar fotogramas procedurales + mapas de profundidad correspondientes
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. Escribir spec.json referenciando los activos generados (ver references/spec-format.md)

# 3. Redactar guión vinculado a escenas, luego generar activos de audio opcionales
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 "Cada fotograma calculado localmente." --name n1

# 4. Validar + renderizar
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

Entrada: metraje existente (MP4) + un resumen. Salida: el metraje compuesto en un video con superposiciones, gradación, transiciones.

Escribir un spec con escenas video-layer que referencien el archivo de metraje, más escenas de tipografía/atmósfera para títulos y transiciones. El motor gestiona la búsqueda de video (extracción de fotogramas determinista por máquina). Ver references/scene-types.md para los parámetros de video-layer.

4. Contrato del agente

El trabajo del agente en todos los flujos de trabajo:

1. Investigar la entrada (leer el sitio, entender el resumen, inspeccionar el metraje).
2. Producir o refinar spec.json — un spec tipado válido (ver references/spec-format.md).
3. Generar el guión narrativo cuando se solicite (lazy script <project> --apply), luego revisar sus compases vinculados a escenas.
4. Generar activos si es necesario (lazy gen image, lazy gen music, lazy gen tts).
5. Ejecutar lazy check y corregir cada error. Las advertencias son orientativas.
6. Ejecutar lazy snapshot --update para establecer la línea base de regresión.
7. Ejecutar lazy check de nuevo — las compuertas de instantánea + determinismo de búsqueda deben pasar.
8. Ejecutar lazy preview y pasar la URL al usuario. Preguntar si revisar o renderizar.
9. Renderizar solo después de la aprobación. lazy render — nunca antes de que el usuario diga "adelante".
10. Verificar la salida: confirmar que el archivo existe, no está vacío, tiene la duración esperada.
11. Reportar la ruta de salida + sha256.

Reglas no negociables

• Nunca renderices antes de que el usuario apruebe. Siempre pausa en la vista previa.
• Nunca te saltes lazy check. Detecta errores de esquema, activos faltantes y no determinismo.
• Siempre ejecuta lazy snapshot --update antes del primer lazy check en un proyecto nuevo.
• Nunca edites .lazy/ — es generado. Edita spec.json y vuelve a renderizar.
• Nunca instales un complemento no revisado ni persistas credenciales de proveedores. Usa el registro y las variables de entorno.
• Referencia activos por rutas relativas al proyecto en el spec (por ejemplo, assets/gen/ridge-01.png).
• Las escenas son secuenciales con superposición opcional. Superposición + desvanecido/disolución = fundido cruzado.
• Toda la temporización está en milisegundos. Los tiempos de inicio son absolutos desde el inicio de la composición.
• Convención de paleta: palette[0] = fondo, palette[1] = acento, palette[2] = primer plano.
• Ancho/alto deben ser pares (requisito de h264 yuv420p).
• Las fuentes están incluidas: Inter (cuerpo) y Space Grotesk (títulos). Sin fuentes externas.
• El progreso va en stderr. Los comandos que usan --json reservan stdout para su resultado JSON final.

5. Conceptos clave

Determinismo

Mismo spec + misma máquina = MP4 byte-identico (verificado por sha256). Tres marcas de Chrome garantizan esto: --jitless (solo intérprete V8), --use-angle=swiftshader (renderizado por software) y redondeo de transformación de píxeles enteros en el runtime. El renderizado de texto subpíxel CSS es no determinista entre sesiones — el runtime ajusta todas las transformaciones a píxeles enteros.

Compuertas

lazy check ejecuta dos compuertas bloqueantes:

• Regresión de instantánea: renderiza fotogramas clave (puntos medios de escena + puntos medios de transición), hashea sus píxeles y compara con snapshots/baseline.json. Deriva = error con escena + marca de tiempo.
• Determinismo de búsqueda: renderiza 5 marcas de tiempo muestreadas dos veces en una sesión del navegador, compara hashes.

Audio

El audio es declarativo en el spec (narration, music, sfx). El renderizador genera y almacena en caché audio WAV canónico, luego mezcla mediante ffmpeg:

• **Narración:say local o un complemento TTS instalado, colocado en startMs o anclado a sceneId + offsetMs
• Música: sintetizador procedural (pads de acordes + percusión) con semilla seed, repetido hasta la duración del video
• SFX: whoosh/hit/rise/boom sintetizados, colocados en atMs con ganancia

LUT / gradación

Dos capas:

• Gradación de escena (style.grade): preajuste de filtro CSS en la raíz de la composición (rápido, sutil)
• LUT de salida (outputs[0].lut): archivo .cube LUT 3D aplicado mediante ffmpeg lut3d durante la codificación (gradación de color cinemática). LUTs incluidos: teal-orange, noir-film, faded-vintage.

6. Referencias

Archivo	URL	Léelo para…
spec-format.md	https://lazy-frames.cosmicstack.ai/references/spec-format.md	redactar un spec.json válido — esquema completo, todos los campos, valores predeterminados
scene-types.md	https://lazy-frames.cosmicstack.ai/references/scene-types.md	elegir un tipo de escena y configurar sus parámetros
workflows.md	https://lazy-frames.cosmicstack.ai/references/workflows.md	paso a paso para los flujos de trabajo website-promo, cinematic y edit
cli.md	https://lazy-frames.cosmicstack.ai/references/cli.md	cada comando CLI con indicadores y ejemplos
gates.md	https://lazy-frames.cosmicstack.ai/references/gates.md	regresión de instantánea + uso de la compuerta de determinismo de búsqueda

Estas referencias también están disponibles en el paquete instalado en skill/references/ y en el repositorio en skill/references/.