cosmicstack-labs/lazy-frames

Lazy Frames

O Lazy Frames renderiza vídeo a partir de uma especificação JSON tipada — uma composição é um arquivo spec.json cujas cenas declaram tempo, conteúdo e estilo; a CLI transforma isso em um MP4 determinístico, perfeito em pixels. O renderizador principal não precisa de nuvem nem chaves. Plugins revisados podem usar serviços externos explicitamente declarados; a mídia gerada é armazenada em cache localmente antes da renderização determinística.

Versão atual da CLI: [email protected].

• A mídia de site capturada é cortada ao centro por padrão em browser-frame, ui-callout e nas cenas parallax plana e com profundidade. Substitua params.position apenas quando o assunto exigir uma âncora diferente.
• Os comandos capture, check, gen, preview e render relatam fases em tempo real no stderr. A renderização relata porcentagens de quadros. Com --json, o stdout permanece JSON legível por máquina.

1. Começar pelo estado do projeto

Estado	Ação
Projeto existente com spec.json	Leia a especificação, faça a edição ou execute a operação solicitada. Pule o roteamento.
Solicitação nova com uma URL de site	Roteie para o fluxo de trabalho website-promo (§ 3).
Solicitação nova com um resumo de texto	Roteie para o fluxo de trabalho cinematic (§ 3).
Solicitação nova com filmagens existentes	Roteie para o fluxo de trabalho edit (§ 3).
Não claro	Faça uma pergunta: "Isso é sobre um site específico, um tópico/resumo ou filmagens de vídeo existentes?"

2. Pré-requisitos

node --version   # >= 20
ffmpeg -version  # obrigatório
python3 --version   # Python 3; no Windows `python` é suficiente
ls "/Applications/Google Chrome.app"  # macOS; Windows usa Chrome em Program Files, ou defina CHROME_PATH

Instale a partir do npm:

npm install lazy-frames
npx lazy doctor

Ou compile a partir do código-fonte:

npm install && npm run build

Verifique o ambiente:

node packages/cli/dist/index.js doctor

O doctor informa: plataforma/memória do Node, versão do Python + nível e disponibilidade do provedor (imagens processuais, profundidade, música, TTS). Narração local usa tts.say (macOS say ou Windows SAPI); provedores externos são instalados como plugins com escopo. Se image.mlx-photoreal não estiver disponível (esperado em máquinas <16 GB), o gerador de imagens processuais é usado em seu lugar — ainda produz imagens cinematográficas, apenas não fotorrealistas.

Plugins e provedores externos

ElevenLabs é incluído por padrão, mas ainda requer aprovação com escopo de projeto antes do uso em rede. Quando o usuário solicitar qualquer provedor ou capacidade de narrativa, pesquise no registro, inspecione seu status e permissões e pergunte antes de aprovar ou instalá-lo:

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

Estruturas do Marketplace podem ser instaladas, mas não podem ser executadas até que um adaptador revisado seja enviado. Nunca instale URLs de pacotes arbitrários ou armazene chaves de API em arquivos de projeto. O ElevenLabs lê ELEVENLABS_API_KEY do ambiente. Registro: https://lazy-frames.cosmicstack.ai/plugins/index.json

3. Fluxos de trabalho

website-promo

Entrada: uma URL. Saída: um MP4 de promoção/apresentação construído a partir dos visuais capturados do próprio site.

# 1. Capture o site (screenshots @2x, paleta, texto, fontes, logotipo)
node packages/cli/dist/index.js capture https://example.com projects/acme

# 2. Revise a especificação inicial gerada + os ativos capturados
cat projects/acme/spec.json
ls projects/acme/assets/sites/example.com/

# 3. Edite a especificação se necessário (ajuste cenas, texto, temporização, transições)

# 4. Valide + execute as verificações
node packages/cli/dist/index.js snapshot projects/acme --update
node packages/cli/dist/index.js check projects/acme

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

O comando capture escreve:

• assets/sites/<dominio>/hero.png + full.png (screenshots em 2x DPR)
• assets/sites/<dominio>/ledger.json (paleta, fontes, blocos de texto, metadados)
• Uma spec.json inicial com 5 cenas construídas a partir do conteúdo capturado
• Cenas de screenshot usam explicitamente { "x": "center", "y": "center" } a menos que a especificação substitua a âncora de corte

cinematic

Entrada: um resumo de texto ou tópico. Saída: um clipe cinematográfico de 30 a 60 segundos com imagens geradas, paralaxe de profundidade, narração, música, SFX.

# 1. Gere imagens processuais + mapas de profundidade correspondentes
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. Escreva spec.json referenciando os ativos gerados (consulte references/spec-format.md)

# 3. Crie um roteiro de narração vinculado às cenas e, em seguida, gere ativos de áudio opcionais
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 quadro computado localmente." --name n1

# 4. Valide + renderize
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: filmagens existentes (MP4) + um resumo. Saída: as filmagens compostas em um vídeo com sobreposições, correção de cor, transições.

Escreva uma especificação com cenas video-layer referenciando o arquivo de filmagens, além de cenas de tipografia/atmosfera para títulos e transições. O motor gerencia a busca de vídeo (extração de quadros determinística por máquina). Consulte references/scene-types.md para parâmetros de video-layer.

4. Contrato do agente

O trabalho do agente em todos os fluxos de trabalho:

1. Pesquise a entrada (leia o site, entenda o resumo, inspecione as filmagens).
2. Produza ou refine spec.json — uma especificação tipada válida (consulte references/spec-format.md).
3. Gere o roteiro de narração quando solicitado (lazy script <projeto> --apply) e revise seus trechos vinculados às cenas.
4. Gere ativos se necessário (lazy gen image, lazy gen music, lazy gen tts).
5. Execute lazy check e corrija todos os erros. Avisos são orientativos.
6. Execute lazy snapshot --update para estabelecer a linha de base de regressão.
7. Execute lazy check novamente — as verificações de snapshot + determinismo de busca devem passar.
8. Execute lazy preview e entregue a URL ao usuário. Pergunte se deve revisar ou renderizar.
9. Renderize apenas após aprovação. lazy render — nunca antes do usuário dar o sinal verde.
10. Verifique a saída: confirme que o arquivo existe, não está vazio e tem a duração esperada.
11. Informe o caminho de saída + sha256.

Regras inegociáveis

• Nunca renderize antes da aprovação do usuário. Sempre pause na pré-visualização.
• Nunca pule lazy check. Ele captura erros de esquema, ativos ausentes e não determinismo.
• Sempre execute lazy snapshot --update antes do primeiro lazy check em um novo projeto.
• Nunca edite .lazy/ — é gerado. Edite spec.json e renderize novamente.
• Nunca instale um plugin não revisado nem persista credenciais de provedor. Use o registro e variáveis de ambiente.
• Referencie ativos por caminhos relativos ao projeto na especificação (por exemplo, assets/gen/ridge-01.png).
• As cenas são sequenciais com sobreposição opcional. Sobreposição + fade/dissolve = crossfade.
• Toda temporização está em milissegundos. Os tempos de início são absolutos a partir do início da composição.
• Convenção de paleta: palette[0] = fundo, palette[1] = destaque, palette[2] = primeiro plano.
• Largura/altura devem ser pares (requisito h264 yuv420p).
• Fontes inclusas: Inter (corpo) e Space Grotesk (exibição). Sem fontes externas.
• O progresso pertence ao stderr. Comandos que usam --json reservam stdout para seu resultado JSON final.

5. Conceitos principais

Determinismo

Mesma especificação + mesma máquina = MP4 idêntico byte a byte (verificado por sha256). Três flags do Chrome garantem isso: --jitless (somente interpretador V8), --use-angle=swiftshader (renderização por software) e arredondamento de transformação de pixels inteiros no runtime. A renderização de texto subpixel CSS é não determinística entre sessões — o runtime ajusta todas as transformações para pixels inteiros.

Verificações (Gates)

lazy check executa duas verificações bloqueantes:

• Regressão de snapshot: renderiza quadros-chave (meio das cenas + meio das transições), faz hash de seus pixels e compara com snapshots/baseline.json. Desvio = erro com cena + timestamp.
• Determinismo de busca: renderiza 5 timestamps amostrados duas vezes em uma sessão do navegador, compara hashes.

Áudio

O áudio é declarativo na especificação (narration, music, sfx). O renderizador gera e armazena em cache áudio WAV canônico e então mixa via ffmpeg:

• Narração: say local ou um plugin TTS instalado, colocado em startMs ou ancorado em sceneId + offsetMs
• Música: sintetizador processual (pads de acordes + percussão) semeado por seed, em loop até a duração do vídeo
• SFX: whoosh/hit/rise/boom sintetizados, colocados em atMs com ganho

LUT / correção de cor

Duas camadas:

• Correção de estágio (style.grade): predefinição de filtro CSS na raiz da composição (rápido, sutil)
• LUT de saída (outputs[0].lut): arquivo .cube de LUT 3D aplicado via ffmpeg lut3d durante a codificação (correção de cor cinematográfica). LUTs inclusas: teal-orange, noir-film, faded-vintage.

6. Referências

Arquivo	URL	Leia para…
spec-format.md	https://lazy-frames.cosmicstack.ai/references/spec-format.md	criar um spec.json válido — esquema completo, todos os campos, padrões
scene-types.md	https://lazy-frames.cosmicstack.ai/references/scene-types.md	escolher um tipo de cena e configurar seus parâmetros
workflows.md	https://lazy-frames.cosmicstack.ai/references/workflows.md	passo a passo para os fluxos de trabalho website-promo, cinematic e edit
cli.md	https://lazy-frames.cosmicstack.ai/references/cli.md	todos os comandos da CLI com flags e exemplos
gates.md	https://lazy-frames.cosmicstack.ai/references/gates.md	uso das verificações de regressão de snapshot + determinismo de busca

Essas referências também estão disponíveis no pacote instalado em skill/references/ e no repositório em skill/references/.