Fldicoahkiin/dotfiles

Estúdio de Vídeo de Demonstração

Transforme uma aplicação web em execução em um filme de demonstração polido: interação real gravada (não slideshow, não simulação) + narração TTS local + legendas sincronizadas por palavra + uma trilha musical ambiente, compostos deterministicamente com HyperFrames.

Quando usar

Ao criar qualquer vídeo de demonstração / tour / produto / lançamento / hackathon de uma aplicação web, especialmente quando deve mostrar o produto real em execução com narração e legendas. Grava uma URL implantada ou um servidor de desenvolvimento local.

Pipeline

① gravar     Playwright controla sua aplicação ao vivo, cursor visível → out/clips/*.webm
② narrar     escrever VO por cena → Kokoro TTS (local)                 → narration/*.wav
③ transcrever Whisper timestamps no nível da palavra                    → *.transcript.json
④ legendar   agrupar em frases + corrigir erros de marca               → captions.js
⑤ música     ffmpeg faixa ambiente (mixada baixo sob a voz)            → music/bed.wav
⑥ compor     HyperFrames HTML linha do tempo única: clipes+voz+legendas+música → MP4

Gravação e composição são independentes: regrave uma cena, ou execute novamente a narração, sem refazer a outra. Uma faixa GIF gerada por código (cenas HTML renderizadas diretamente em MP4, sem gravação) é um caminho opcional para páginas de documentação.

Fluxo de Trabalho

1. Entenda o produto primeiro. Leia seu README / documentação de demonstração. Escreva um Fluxo de Demonstração antes de usar as ferramentas: problema → tour do produto → evidência → conclusão. Escolha o caminho de clique recomendado e o resultado visível que cada cena deve alcançar. Veja references/templates.md.
2. Gravar. Copie scripts/record.mjs, defina APP e SIZE, substitua scenes pela sua coreografia (deslizar → pausar → agir → segurar). Grave na escala 1:1 do dispositivo. node scripts/record.mjs [scene]. Engine + exemplo prático: references/recording.md.
3. Narrar → legendar. Escreva um assets/narration/NN-*.txt por cena com voz de narrador (você está falando com um espectador, não lendo um README). Depois: bash scripts/tts.sh && bash scripts/transcribe.sh && node scripts/build-captions.mjs. Edite PHRASE_FIX em build-captions.mjs para os nomes das suas marcas. Guia: references/narration-and-captions.md.
4. Compor e renderizar. Comece a partir de references/composition-skeleton.html (um clipe + faixa de legenda + áudio), cresça a linha do tempo, depois npx hyperframes render . --resolution landscape --fps 30 --crf 17 --quality high. Renderize 1:1 (1080p criado → 1080p final) — nunca aumente para 4K, isso suaviza a interface. references/composition.md.
5. Controle de qualidade antes de enviar. ffprobe a duração/áudio, amostre 1–2 quadros (não preto, não vazio), legendas dentro do quadro, narração não cortada, a página de resultado principal realmente visível. Corrija fluxo/tempo, então renderize novamente.

Início Rápido

# dependências do sistema
brew install node ffmpeg
npx playwright install chromium

# ambiente Python para TTS local + transcrição (uma vez)
python3 -m venv .ttsvenv && .ttsvenv/bin/pip install kokoro-onnx soundfile
export PATH="$(pwd)/.ttsvenv/bin:$PATH"

# 1) gravar  2) narrar  3) legendar  4) compor+renderizar
node scripts/record.mjs
bash scripts/tts.sh && bash scripts/transcribe.sh && node scripts/build-captions.mjs
npx hyperframes render . --resolution landscape --fps 30 --crf 17 --quality high --output out/demo.mp4

Na primeira execução, o TTS baixa ~340 MB (Kokoro), a primeira transcrição ~466 MB (Whisper small.en); ambos armazenam em cache em ~/.cache/hyperframes/.

Regras importantes

• Interação real vence slides — grave o produto realmente em execução.
• 1:1, nunca aumento de 2× — gravar com DPR 2× e renderizar em 4K suaviza cada clipe de interface. Crie e renderize em 1080p.
• Composição determinística — sem Date.now(), Math.random() ou rede no HTML; HyperFrames busca quadros, então o movimento deve ser reproduzível.
• Cursor visível + segurar nos resultados — deslize deliberadamente, pause no momento chave.
• VO, não documentação — a narração acompanha a imagem; não é o README lido em voz alta.
• Vídeo ≥ narração — aumente o tempo do clipe para que os visuais nunca terminem antes da voz.

Dependências

Node 22+, FFmpeg, Playwright (Chromium) e a CLI HyperFrames (npx hyperframes, instale suas skills com npx skills add heygen-com/hyperframes). TTS/Whisper locais precisam de Python + kokoro-onnx. Veja references/composition.md para a configuração do HyperFrames.

Referências

• references/pipeline.md — as seis etapas e o fluxo de dados
• references/recording.md — engine Director + exemplo prático + armadilhas de gravação
• references/narration-and-captions.md — escrita de VO, TTS, Whisper, correções de legendas
• references/composition.md — linha do tempo do HyperFrames, crossfades, 1080p, renderização
• references/composition-skeleton.html — composição mínima renderizável para copiar como index.html
• references/templates.md — estruturas de hackathon + demonstração de produto e esqueletos de VO
• references/troubleshooting.md — legendas, tela branca, áudio, fontes