⚙️ Node 22+ e FFmpeg
Dois binários obrigatórios: Node.js na versão 22 ou superior e FFmpeg acessível no PATH. Sem eles o HyperFrames não consegue renderizar um único frame.
O HyperFrames usa ESM nativo e APIs de fs/promises presentes a partir do Node 18, mas a versão 22 traz o --experimental-strip-types e o V8 atualizado que acelera o parse das composições. Versões antigas (16, 18) podem funcionar parcialmente mas causam avisos e comportamentos inesperados no build-index.mjs.
- ✓ FFmpeg em
C:\ffmpeg\bin\ffmpeg.exe - ✓ PATH configurado na variável de sistema (não usuário)
- ✓ Node 22+ verificado com
node --version - ✓ Abrir novo terminal após alterar PATH
- ✗ Usar FFmpeg instalado pelo
chocosem verificar PATH - ✗ Node 16 ou 18 — causa erros no ESM nativo
- ✗ Testar
ffmpegno terminal antigo (PATH não atualizado) - ✗ ffmpeg.exe fora do subdiretório
bin
⌨️ ffmpeg -nostdin no git-bash
O gotcha mais silencioso do setup: rodar FFmpeg dentro do git-bash sem -nostdin causa exit 0 sem gerar nenhum arquivo. Nenhum erro visível — simplesmente nada é criado.
⚠️ Gotcha crítico — sai exit 0 sem arquivo
No git-bash (MinTTY), o FFmpeg tenta ler stdin e bloqueia silenciosamente. O processo termina com código 0 (sucesso), mas nenhum MP4 é gerado. É o bug mais difícil de diagnosticar porque tudo parece ter funcionado.
O CLI do HyperFrames (npx hyperframes render) passa -nostdin automaticamente nas chamadas internas ao FFmpeg. Você só precisa se preocupar se for invocar FFmpeg diretamente no git-bash para pós-processamento manual, script de concatenação etc.
🌐 Chrome headless do HyperFrames
O HyperFrames traz seu próprio Chrome headless — não depende do Chrome instalado no sistema. Um único comando baixa e vincula a versão exata testada com o CLI.
Versões diferentes do Chrome renderizam CSS e animações GSAP com diferenças sutis de pixel. Para que o output seja determinístico (mesmo HTML → mesmo MP4), o HyperFrames trava em uma versão específica do Chromium via Puppeteer, baixada e gerenciada internamente. Você não precisa tocar no Chrome do sistema.
Lê a versão travada no package.json do HyperFrames
O campo puppeteer.chromiumRevision define exatamente qual build do Chromium usar — nada de "latest".
Verifica cache local (~/.cache/puppeteer/)
Se o build já existe, pula o download. O segundo projeto criado não espera nada — instantâneo.
Baixa ~170MB do CDN do Chromium se necessário
Apenas na primeira vez ou quando a versão do HyperFrames é atualizada. Conexão estável recomendada.
🔊 TTS Kokoro
Narração PT-BR 100% local, sem chave de API. Kokoro tem seu próprio fonemizador de português, dispensando o espeak-ng. Na primeira execução, baixa ~340MB de modelo.
- ✓
pip install kokoro-onnx soundfile - ✓ Python 3.10+ no PATH
- ✓ Primeira execução: aguardar ~340MB de download
- ✓ Voz padrão:
pf_doracom--speed 0.98
- ✗ espeak-ng — Kokoro não precisa e cria conflito
- ✗ Outros pacotes TTS que dependem de espeak
- ✗ Interromper o primeiro download do modelo
- ✗ Usar
speed 1.0+— soa mecânico em PT-BR
espeak-ng fonemiza português pobremente — pronúncia robótica em palavras técnicas. Kokoro tem seu próprio fonemizador PT-BR treinado especificamente para o idioma.
O modelo (~340MB) é cacheado em ~/.cache/kokoro/. Da segunda invocação em diante, a geração de um trecho de 10s leva menos de 2 segundos.
🩺 npx hyperframes doctor
O comando de diagnóstico verifica toda a stack de uma vez: Node, FFmpeg, Chrome e Kokoro. Se algo estiver errado, ele diz exatamente o que falta.
Especialmente em ambiente novo ou após atualizar o HyperFrames. O npx hyperframes render falha no meio do processo se uma dependência estiver faltando — o doctor detecta isso antes.
Node.js — versão mínima 18, recomendada 22+
Lê process.version e compara com o campo engines do package.json.
FFmpeg — executa ffmpeg -version e parseia a saída
Verifica se o binário está acessível via PATH e mostra o caminho completo encontrado.
Chrome — verifica cache do Puppeteer
Checa se o build travado está em ~/.cache/puppeteer/. Se não, sugere rodar browser ensure.
Kokoro — importa o módulo Python e verifica
Executa python -c "import kokoro_onnx" e import soundfile. Versões mínimas checadas.
📦 Iniciar um projeto
Com o ambiente pronto, o próximo passo é criar a estrutura do projeto. O template blank + --non-interactive gera tudo sem perguntas — ideal para scripts e CI.
O --example blank cria um projeto mínimo com a estrutura de pastas correta mas sem cenas pré-construídas — você parte do zero. É o ponto de entrada recomendado para aprender o pipeline, pois cada arquivo que aparece foi criado intencionalmente.
init blank- ✓ Leia o
design.mdpara entender a paleta - ✓ Rode
node scripts/fetch-fonts.mjsantes do render - ✓ Use
narration-template.shcomo base de roteiro - ✓ Rode
doctoruma vez no projeto novo
- ✗ Renderizar sem rodar
fetch-fonts.mjs→ fonte não encontrada - ✗ Ignorar o
design.mde inventar paleta - ✗ Pular o
npm installapós o init - ✗ Usar espaços no nome do projeto (ex:
meu video)
Cada projeto tem um design.md com a paleta principal, tipografia e estilo visual. Para vídeos INEMA.CLUB, a paleta padrão é: fundo #0D1321, acento âmbar #FACC15, textos em branco/cinza. O Claude lê este arquivo antes de escrever qualquer cena.
📋 Resumo do Módulo 2.2
O que você aprendeu neste módulo
- ✓ Node.js 22+ instalado e verificado com
node --version - ✓ FFmpeg em
C:\ffmpeg\binadicionado ao PATH do sistema - ✓ Chrome headless instalado via
npx hyperframes browser ensure - ✓ TTS Kokoro instalado (
pip install kokoro-onnx soundfile), sem espeak-ng - ✓
npx hyperframes doctorretornando "All systems go" - ✓ Primeiro projeto criado com
npx hyperframes init <nome> --example blank --non-interactive - ✓
fetch-fonts.mjsexecutado, fontes baixadas - ✓ Entendido por que
-nostdiné necessário no git-bash
narration-template.sh, gere os arquivos de áudio com Kokoro (pf_dora --speed 0.98) e meça as durações com ffprobe para sincronizar com as cenas.