Walkthrough video

O que Walkthrough video faz?

Transforma uma aplicação web em execução em um vídeo narrado finalizado, que pode ser regenerado sempre que a aplicação mudar. Tudo é executado localmente: sem editor de vídeo, sem serviço pago.

texto da narração -> voz local -> um WAV por cena + timings de legenda
aplicação real -> cenas Playwright -> clipes + tempos de marcador   -> assemble.py -> walkthrough.mp4 + .srt

Por que funciona assim: a filmagem é a aplicação real, portanto é sempre verdadeira; etapas lentas (uma resposta de IA, um carregamento de página) são cortadas durante a gravação; e "marcadores" registrados por cada cena permitem que o montador sincronize o momento chave com as palavras correspondentes.

Antes de começar

1. Pergunte apenas o que está faltando: qual é a aplicação e o que o vídeo deve mostrar, quem assiste, a duração alvo (2 a 4 minutos funciona bem), o tom.
2. Verifique as ferramentas (detalhes em references/setup.md): Node 20+, Playwright com Chromium, FFmpeg com xfade, zoompan, loudnorm, libx264 e Python 3.11 ou 3.12 com kokoro-onnx. Instale a voz (cerca de 350 MB) fora do repositório, por exemplo em ~/video-tools.
3. Copie os arquivos de trabalho para o projeto do usuário e mantenha a saída gerada fora do git:

   mkdir -p e2e/video-kit && cp -R <este skill>/scripts/. e2e/video-kit/ && cp <este skill>/templates/*.mjs e2e/video-kit/
   printf '\ne2e/video-kit/clips/\ne2e/video-kit/vo/\ne2e/video-kit/build/\ne2e/video-kit/*.mp4\ne2e/video-kit/*.srt\ne2e/video-kit/spec.json\ne2e/video-kit/.*.json\n' >> .gitignore
   

   Os scripts escrevem sua saída junto a si mesmos, por isso são copiados em vez de executados a partir daqui.
4. Leia references/toolkit-api.md uma vez. Ele documenta os helpers do gravador e a sintaxe PLAN. Não reescreva rec.mjs, speak.py, overlays.mjs ou assemble.py; edite apenas as partes que o guia nomeia.

O fluxo de trabalho: três portões

Pare em cada portão e aguarde o usuário. A redação e a estrutura são baratas de mudar antes da gravação e caras depois.

Portão 1: storyboard. Analise o projeto (seus documentos, rotas, testes Playwright existentes) e proponha de 8 a 12 cenas. Para cada uma: o que está na tela, a narração (20 a 35 palavras, simples) e como será gravada. Inclua slides de abertura se o usuário quiser contexto: o problema, o que foi feito ou auditado, a solução e a stack. Não descreva nada que a aplicação não faça realmente; pergunte se não tiver certeza.

Portão 2: redação e voz. Escreva chunks.txt como linhas cena|texto, com cerca de 12 palavras cada (cada linha se torna uma legenda). Adicione nomes de produtos e siglas a PRONOUNCE em speak.py. Execute python speak.py e informe a duração de cada cena. O usuário ouve e aprova antes de qualquer gravação.

Portão 3: gravar, montar, verificar.

1. Escreva as cenas em scenes.mjs (comece de scenes.template.mjs), um clipe por cena, nomeado scene-N para corresponder ao plano padrão. Grave uma cena de cada vez em segundo plano: node scenes.mjs <nome>. Regrave apenas as que falharem.
2. Renderize os slides se usados (slides.template.mjs), depois preencha PLAN e LABEL em assemble.py: qual clipe mostra em qual cena, e qual marcador cai em qual linha de narração.
3. Execute python assemble.py all. Ele gera walkthrough.mp4 e walkthrough.srt.
4. Verifique o resultado a partir de uma folha de contatos (um ou dois quadros por cena, lado a lado) em vez de várias imagens separadas: nomes, datas, legendas, nada cortado, nada privado. Corrija, remonte, entregue.

Regras importantes

• Privacidade. Use uma conta de demonstração ou teste. Desfoque ou cubra qualquer coisa que mostre pessoas reais, e-mails, números de telefone, nomes de conta, chaves, IDs, tokens ou faturamento (opts.cover, opts.init). Nunca manipule senhas: quando uma cena precisar de login, peça ao usuário para fazer login manualmente uma vez em um navegador visível (templates/auth.template.mjs) e reutilize a sessão salva. Nunca digite ou mostre senhas ou códigos 2FA na câmera. Mantenha .env, logins salvos e perfis de navegador fora do git.
• Não aja em contas reais. Nunca clique em nada que envie, publique, agende ou exclua em contas reais. Passe o mouse sobre o botão e diga o que ele faz.
• Sem funcionalidades inventadas. Descreva apenas o que o código e a aplicação em execução fazem.
• Voz e áudio do microfone não podem ser capturados pelo navegador. Mostre a interface e diga o que acontece.
• Verifique as portas antes de iniciar servidores; pare o que você iniciou. Execute qualquer coisa que demore mais de um minuto (gravação, voz, montagem) em segundo plano e aguarde, em vez de fazer polling em um loop.
• Mantenha as respostas curtas. Relate o que você fez, os caminhos dos arquivos e qualquer coisa que você não pôde verificar.

Lições de uso real

Leia references/lessons.md antes de escrever as cenas. A versão resumida: verifique se os dados semeados realmente existem (dados de teste aleatórios podem conflitar com dados antigos); aguarde um localizador que prove que uma página lenta foi renderizada; limpe os filtros de pesquisa lembrados antes de digitar; feche pop-ups; vincule diretamente a registros; envolva floreios não essenciais para que uma falha não pare uma cena; e mantenha os 200 px inferiores dos slides livres para legendas.

Arquivos

• scripts/rec.mjs gravador: cursor deslizante, ondas de clique, zoom, marcadores, think() para cortar esperas.
• scripts/speak.py narração para WAVs e timings de legenda.
• scripts/overlays.mjs legendas, etiquetas e cartões de título como imagens.
• scripts/assemble.py reajusta o tempo dos clipes à voz, junta, sobrepõe, mixa áudio, escreve MP4 e SRT.
• templates/ pontos de partida para cenas, um login salvo, slides e o arquivo de narração.
• references/ o guia do kit de ferramentas, configuração e lições.

Quando algo falha

• A fala falha com espeakng_loader/phontab: No such file: veja references/setup.md.
• Uma cena expira esperando por texto: a página pode não ter terminado de renderizar, ou um filtro lembrado está ocultando o item. Faça uma captura de tela no momento da falha e veja.
• O vídeo mostra uma espera: envolva a etapa lenta em think().
• A imagem e a voz perdem sincronia: regrave a cena, porque os tempos dos marcadores mudam sempre que um script é alterado.