🎬 Pipeline: HTML → MP4

O HyperFrames renderiza uma página HTML cena por cena, captura cada frame como imagem PNG e usa o FFmpeg para montar o vídeo final — com áudio WAV sincronizado.

Entender o fluxo ponta-a-ponta evita surpresas: cada etapa tem um artefato concreto (HTML, WAV, MP4) que você pode inspecionar.

HTML → frames PNG → FFmpeg → MP4; cada cena é um estado da página.

O Chrome headless gerenciado pelo HyperFrames renderiza cada frame da animação. O FFmpeg mescla os frames com os áudios WAV e gera o arquivo MP4 final.

Saber que são dois processos separados ajuda a diagnosticar: problemas visuais → Chrome; problemas de áudio/timing → FFmpeg.

Puppeteer/Chrome, FFmpeg, pipeline de dois estágios.

O Kokoro é um modelo TTS que roda localmente via Python (kokoro-onnx). Gera arquivos WAV de alta qualidade sem nenhuma chamada a serviço externo.

Elimina custo variável e dependência de internet. O modelo (~340 MB) baixa uma vez e fica na máquina.

kokoro-onnx, voz pf_dora, ONNX runtime, WAV local.

Todo o pipeline (TTS, render, encode) acontece localmente. Depois do setup inicial, você produz vídeos sem internet e sem custos por uso.

Remove o medo de custos escalando e garante que o projeto pode ser reproduzido em qualquer máquina com os pré-requisitos instalados.

Offline-first, custo zero por vídeo, reprodutível.

O HyperFrames suporta os dois formatos principais. O mesmo roteiro gera um vídeo 16:9 (YouTube, horizontal) e um 9:16 (Shorts, TikTok, Reels) automaticamente.

Uma produção, duas entregas. O CSS da cena adapta o layout para cada formato via media query ou variável.

1920×1080, 1080×1920, multi-formato, reproveitamento.

Ideal para vídeos explicativos animados com narração (tutoriais, onboarding, lançamentos). Não é para capturas de tela ao vivo, entrevistas ou vídeos com face-cam.

Saber o escopo certo evita frustração. O HyperFrames brilha em conteúdo motion-graphics + narração; não substitui gravação ao vivo.

Motion-graphics, narração TTS, conteúdo técnico estruturado.

Node 22 LTS é o mínimo exigido. No Windows, o FFmpeg vai em C:\ffmpeg\bin e, no git-bash, use sempre ffmpeg -nostdin para evitar travamentos de stdin.

Versões antigas do Node podem quebrar o CLI. A flag -nostdin é um gotcha clássico no Windows que trava o render silenciosamente.

Node 22+, FFmpeg no PATH, -nostdin no git-bash.

O HyperFrames usa um Chrome isolado, baixado via npx hyperframes browser ensure. Ele fica em cache local e não interfere com o Chrome que você usa no dia a dia.

Usar o Chrome pessoal pode causar conflitos de perfil. O browser isolado garante ambiente limpo e reprodutível.

npx hyperframes browser ensure, cache local, Puppeteer isolado.

Instale com pip install kokoro-onnx soundfile. Na primeira execução, o modelo (~340 MB) é baixado automaticamente e cacheado. As execuções seguintes são offline.

Sem o Kokoro instalado, a geração de narração falha. O download demora na primeira vez — planeje isso no setup.

pip install kokoro-onnx soundfile, download único ~340 MB, cache local.

O comando npx hyperframes doctor checa Node, FFmpeg, Chrome e Kokoro de uma vez e imprime o status de cada dependência. Verde em tudo = pronto para criar.

Economiza tempo de depuração: em vez de descobrir a falha no meio do render, você identifica o problema antes de começar.

npx hyperframes doctor, checklist de deps, diagnóstico rápido.

Crie o scaffolding com npx hyperframes init <nome> --example blank. Gera as pastas audio/, frames/, os scripts e o HTML de entrada já com a estrutura correta.

Partir do template certo evita erros de estrutura que só aparecem na hora do render.

npx hyperframes init, --example blank, pastas audio/ e frames/.

O design.md define a paleta, tipografia e regras visuais do seu canal. Copie-o da referência do skill para dentro do projeto e referencie nas instruções ao Claude.

Sem um design.md, cada vídeo pode ter visual diferente. Ter o arquivo garante consistência de identidade visual.

design.md, house-style, paleta #0D1321, identidade visual.

O SCRIPT.md é um Markdown com uma seção por cena. O arco ideal: hook (por quê assistir) → princípio (conceito base) → avançado (detalhe prático) → CTA (próximo passo).

Roteiro bem estruturado antes de programar evita retrabalho de animação. A narrativa guia o visual, não o contrário.

SCRIPT.md, 6–9 cenas, arco hook→CTA, uma ideia por cena.

Com 6–9 cenas e ~100 segundos de narração total, o vídeo fica com ~1:50 de duração — ideal para Shorts e vídeos curtos no YouTube.

Textos longos por cena geram áudios longos que esticam a animação além do suportado. Cada cena deve ter no máximo 3–4 frases curtas.

~100s total, 3–4 frases por cena, ritmo de atenção.

O TTS lê literalmente o texto. Escreva "SKILL ponto M D" em vez de "SKILL.md", "M J S" em vez de ".mjs", "N P X" em vez de "npx" — ou o resultado soa estranho.

É um dos gotchas mais comuns. Ouvir "SKILL ponto MD" natural vs o modelo tentando pronunciar "skill-dot-md" literalmente faz diferença enorme na qualidade percebida.

Texto fonético, expansão de siglas, revisar a narração em voz alta.

Use a voz pf_dora com --speed 0.98 para uma fala natural e levemente mais pausada. O resultado é um arquivo WAV por cena em audio/.

A velocidade padrão (1.0) pode soar acelerada. O ajuste 0.98 é sutil mas melhora a clareza sem perder o ritmo.

voz pf_dora, --speed 0.98, WAV por cena, pasta audio/.

Após gerar os WAVs, use ffprobe -show_entries format=duration em cada arquivo para obter a duração exata em segundos. Esses valores alimentam o array AUDIO[] no build-index.

Durações estimadas geram vídeos com áudio cortado ou silêncio no fim. ffprobe dá o número exato que o HyperFrames precisa.

ffprobe -show_entries format=duration, duração real em segundos, AUDIO[] array.

Além da voz padrão pf_dora, o Kokoro oferece pm_alex (masculino neutro) e pm_santa (masculino mais grave) para variedade ou personalização de canal.

Escolher a voz antes de gravar tudo evita retrabalho. Teste as três com 2–3 frases do roteiro e decida antes de gerar todos os WAVs.

pf_dora, pm_alex, pm_santa, teste antes de gerar tudo.

O build-index.mjs é o gerador: lê o AUDIO[], chama as funções de cena e produz o index.html final que o HyperFrames vai renderizar. Copie do template e edite.

Entender a estrutura do gerador permite customizar sem medo. Cada parte tem responsabilidade clara: dados, HTML de cena, animação.

build-index.mjs, gerador, template copiado e editado.

O array AUDIO[] mapeia cada cena ao seu arquivo WAV e à duração exata (em segundos, com decimais) obtida do ffprobe. Ex.: { file: 'audio/scene1.wav', dur: 12.34 }.

É a fonte única de verdade do timing. Todos os cálculos de animação derivam das durações reais do AUDIO[] — nunca estime.

AUDIO[], durações reais, fonte única de verdade, ffprobe.

Cada cena é uma função sceneN() que retorna HTML posicionado absolutamente dentro do container de vídeo. Os elementos começam invisíveis e o GSAP os anima.

Separar HTML de cena em funções mantém o código organizado e facilita editar uma cena sem afetar as outras.

sceneN(), posição absoluta, opacity 0 inicial, GSAP anima.

A função anim(i, t) recebe o índice da cena e o timeline GSAP e adiciona as animações. O GSAP interpola os valores frame a frame, garantindo que o Chrome captura movimentos fluidos.

GSAP é o padrão no HyperFrames porque garante timing determinístico — mesmo frame sempre igual, essencial para captura headless.

anim(i, t), GSAP timeline, timing determinístico, frame perfeito.

O array CAPTIONS[] define o texto de legenda de cada cena, exibido na faixa inferior do vídeo. Pode ser o texto completo da narração ou um resumo em bullets.

Legendas melhoram acessibilidade e aumentam retenção em plataformas onde o vídeo toca sem som por padrão.

CAPTIONS[], faixa inferior, acessibilidade, vídeo sem som.

Três constantes controlam o timing de toda animação: LEAD=0.5 (pausa antes da narração), TAIL=0.9 (hold após o fim da fala) e FADE=0.45 (duração do fade entre cenas). Mudar aqui afeta tudo uniformemente.

Ter uma fonte única de timing é o que garante que áudio e animação estejam sempre sincronizados. Nunca hard-code segundos nas funções de cena.

LEAD=0.5, TAIL=0.9, FADE=0.45, fonte única, sincronismo áudio+visual.

O comando npx hyperframes lint verifica o HTML gerado: durações, referências de áudio, estrutura do timeline e erros de sintaxe. Deve retornar 0 erros antes de prosseguir.

Render com erros de lint pode produzir vídeos silenciosos, cortados ou com cenas faltando. Lint barato agora evita render caro depois.

npx hyperframes lint, 0 erros, validação prévia ao render.

O npx hyperframes inspect --samples 16 abre o Chrome headless, captura 16 frames distribuídos pelo vídeo e exibe miniaturas para inspeção visual rápida de layout.

Texto cortado, elementos fora da tela ou sobreposições só aparecem visualmente. O inspect detecta antes de desperdiçar minutos de render.

npx hyperframes inspect --samples 16, miniaturas, problemas de layout.

O modo --quality draft rende em resolução reduzida e velocidade maior, para uma pré-visualização rápida do vídeo completo antes do render final.

O draft permite conferir sequência, transições e timing sem esperar o render completo. Corrija no draft, não no high.

--quality draft, preview rápido, iteração barata.

Extraia frames do draft com FFmpeg (ffmpeg -i draft.mp4 -vf fps=1 frames/%04d.png) e compartilhe com o usuário para validação visual. O Claude não consegue ouvir o áudio.

A validação humana antes do render final captura problemas subjetivos (texto muito pequeno, cores fora, ordem errada) que o lint não detecta.

ffmpeg -vf fps=1, frames PNG, validação humana, o Claude não ouve.

Após aprovação do draft, rode --quality high --fps 30 para o render completo. Gera o MP4 final em resolução total, pronto para upload.

O render high demora mais e não deve ser repetido. Aprovação do draft antes garante que o esforço de render vai no arquivo certo.

--quality high --fps 30, render final, não repetir sem validação.

Rode o render duas vezes com os parâmetros de formato diferentes (ou use a flag --both se disponível no seu projeto). O resultado é o arquivo horizontal (16:9) e o vertical (9:16) prontos para distribuição.

YouTube e Shorts têm alcances diferentes. Gerar as duas versões no mesmo render maximiza distribuição sem retrabalho de conteúdo.

16:9 YouTube, 9:16 Shorts, duas versões, distribuição multi-plataforma.