Fldicoahkiin/demo-video-skill

Demo Video Studio

Transforme um aplicativo web em execução em um filme de demonstração polido: interação real gravada (não slideshow, não simulado) + narração TTS local + legendas sincronizadas com palavras + uma trilha sonora suave, compostos deterministicamente com HyperFrames.

Quando usar

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

Pipeline

① gravar    um dos três mecanismos (abaixo)                    → out/*.mp4|webm
② narrar    escrever VO por cena → Kokoro TTS (local)          → narracao/*.wav
③ transcrever Whisper timestamps em nível de palavra            → *.transcript.json
④ legendar  agrupar em frases + corrigir erros de marca        → legendas.js
⑤ música    base ambiente ffmpeg (mixada baixa sob a voz)      → musica/base.wav
⑥ compor    HyperFrames HTML uma linha do tempo: clipes+voz+legendas+música → MP4

① tem três mecanismos — escolha pelo alvo (referencias/visual-screen-studio.md):

Alvo	Mecanismo	Visual
Aplicativo web/desktop, macOS	Cap CLI — scripts/record-cap.mjs	Screen Studio nativo: zoom automático a partir de cliques reais, cursor elástico + desfoque de movimento, papel de parede / arredondamento / sombra, renderizado por GPU
Ferramenta CLI	VHS tape → mp4	terminal estilizado (preenchimento, margem, borda arredondada, barra de janela), determinístico
Headless / CI / Linux	Playwright — scripts/record.mjs	cursor sintético + ondulações; escreve <cena>.events.json (timestamps + coordenadas) para qualquer composição de zoom posterior

Qualquer que seja o mecanismo de gravação, sua saída é apenas o clipe alimentando ②–⑥ — gravação e composição permanecem independentes: regrave uma cena, ou execute novamente a narração, sem refazer o outro. Uma trilha GIF gerada por código (cenas HTML renderizadas diretamente em MP4, sem gravação) é um caminho lateral opcional para páginas de documentação.

Fluxo de Trabalho

0. Escolha o mecanismo COM o usuário — nunca silenciosamente. Analise o projeto real (aplicativo web? CLI? desktop? esta máquina tem sessão GUI? precisa rodar em CI?), depois apresente as opções de mecanismo com prós/contras para este projeto específico e deixe o usuário escolher. Exemplo para um aplicativo web num Mac: "Cap CLI fornece o visual do Screen Studio nativamente, mas precisa de permissão de gravação de tela e uma calibração inicial; Playwright roda em qualquer lugar e regrava cenas únicas rapidamente, mas não tem zoom automático; VHS não se aplica aqui." Detalhes dos mecanismos: referencias/visual-screen-studio.md.
1. Entenda o produto primeiro. Leia o README / documentação de demonstração. Escreva um Fluxo de Demonstração antes de tocar nas ferramentas: problema → walkthrough do produto → evidência → conclusão. Escolha o caminho de cliques recomendado e o resultado visível que cada cena deve alcançar. Veja referencias/modelos.md.
2. Grave. Copie scripts/record.mjs, defina APP e SIZE, substitua cenas pela sua coreografia (deslizar → pausar → agir → segurar). Grave na escala 1:1 do dispositivo. node scripts/record.mjs [cena]. Mecanismo + exemplo funcional: referencias/gravacao.md.
3. Narre → legende. Escreva um ativos/narracao/NN-*.txt por cena na voz de narrador (você está falando com um espectador, não lendo um README — esta é uma arte diferente do texto de marketing; a skill de marketing fornece tópico/gancho/storyboard, esta skill escreve as palavras faladas). Depois: bash scripts/tts.sh && bash scripts/transcrever.sh && node scripts/construir-legendas.mjs. Edite CORRECAO_FRASE em construir-legendas.mjs para os nomes de sua marca. A voz é trocável por contrato: a narração é um wav por cena (narracao/NN-*.wav) — substitua qualquer wav por uma gravação humana, uma dublagem chinesa ou outro TTS, execute novamente transcrever+legendas, recomponha; nada mais muda. Kokoro (local, Apache-2.0) é o padrão e tem vozes em mandarim; edge-tts é uma alternativa online gratuita. Guia: referencias/narracao-e-legendas.md.
4. Componha & renderize. Comece a partir de referencias/esqueleto-composicao.html (um clipe + trilha 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 autorado → 1080p saída) — nunca upscale para 4K, isso suaviza a interface. referencias/composicao.md.
5. Controle de qualidade antes de enviar. ffprobe a duração/áudio, amostre 1–2 quadros (não pretos, não vazios), legendas dentro do quadro, narração não cortada, a página de resultado chave realmente visível. Corrija fluxo/timing, depois re-renderize.

Início rápido

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

# ambiente virtual Python para TTS e transcrição locais (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/transcrever.sh && node scripts/construir-legendas.mjs
npx hyperframes render . --resolution landscape --fps 30 --crf 17 --quality high --output out/demo.mp4

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

Regras importantes

• Interação real supera slides — grave o produto realmente em execução.
• 1:1, nunca upscale 2× — gravar em 2× DPR e renderizar 4K suaviza todos os clipes de interface. Autor 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 + segure nos resultados — deslize deliberadamente, pause no payoff.
• VO, não documentação — a narração acompanha a imagem; não é o README lido em voz alta.
• Vídeo ≥ narração — adicione tempo ao 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. Por mecanismo (opcional): a rota Cap precisa de cap (curl -fsSL https://cap.so/install-cli.sh | sh) + cliclick (brew install cliclick) + permissão de gravação de tela; a rota de terminal precisa de vhs (brew install vhs). Todos gratuitos — tabela de licenciamento em referencias/visual-screen-studio.md. Veja referencias/composicao.md para a configuração do HyperFrames.

Referências

• referencias/pipeline.md — os seis estágios e fluxo de dados
• referencias/visual-screen-studio.md — os três mecanismos de gravação; ciclo de vida do Cap CLI, agrupamento de zoom, tapes VHS, o que não construir
• referencias/gravacao.md — Mecanismo Diretor + exemplo funcional + armadilhas de gravação
• referencias/narracao-e-legendas.md — escrita de VO, TTS, Whisper, correções de legendas
• referencias/composicao.md — linha do tempo HyperFrames, crossfades, 1080p, renderização
• referencias/esqueleto-composicao.html — composição mínima renderizável para copiar como index.html
• referencias/modelos.md — estruturas de hackathon + demonstração de produto e esqueletos de VO
• referencias/solucao-de-problemas.md — legendas, tela branca, áudio, fontes