demo-video

Vídeo de demonstração

Grava a aplicação real (nunca um mock ou um vídeo antigo) em um navegador headless novo, narra com Edge TTS, queima legendas e renderiza um MP4. Uma demonstração consiste em dois arquivos escritos para seu processo, narration.json e flow.cjs; todo o resto é o comando demo-video-kit nesta pasta. O exemplo prático está em examples/todomvc/.

<kit> abaixo significa node <esta pasta>/bin/demo-video-kit.js (esta pasta é, por exemplo, ~/.claude/skills/demo-video); quando o projeto do usuário tem o kit instalado, npx demo-video-kit funciona da mesma forma. <kit> help lista todos os comandos.

A solicitação determina o trabalho

Solicitação	Faça
"Criar uma demonstração para "	Todo o fluxo de trabalho abaixo, em demos/<processo>/ do projeto do usuário
" as telas mudaram, refaça a demonstração"	Execute a seco as novas telas (passo 2), corrija flow.cjs e, se as palavras não couberem mais, narration.json; depois passos 4 a 8
"Adicionar caixas ao vídeo existente" (sem nova gravação)	Meça as caixas na aplicação em execução, escreva annotations.json, execute <kit> annotate <diretório-demo> (veja Destaques)
"... sem destaques"	Deixe de fora toda opção highlight; nada mais muda
"Alterar a voz / velocidade / redação"	Edite narration.json (voice, rate, text do segmento), depois passos 4 a 8: a duração dos clipes determina o tempo na tela, então o vídeo é sempre gravado novamente

Regras (sempre)

1. Real e novo. Uma nova sessão de navegador; a aplicação real; dados reais. Nunca finja um resultado, um número ou um status; anuncie o sucesso apenas após a aplicação mostrá-lo.
2. Seguro. Apenas ambiente local ou de teste: cada execução realmente cria o que o fluxo criar. Nunca imprima ou armazene credenciais: elas vêm do ambiente (por exemplo DEMO_EMAIL, DEMO_PASSWORD); uma senha aparece apenas como pontos. Solicite uma conta de teste se nenhuma for conhecida.
3. Imagem. 1920x1080, 16:9, 30 fps, MP4 H.264 + AAC, gravado headless para que nada seja cortado. Um cursor visível que desliza até cada alvo e um anel de clique leve; sem zoom, sem movimentos de câmera, sem transições sofisticadas. Antes de agir em qualquer elemento, role-o completamente para a vista; leia páginas longas de cima para baixo, devagar o suficiente para ler.
4. Som. Edge TTS, voz padrão en-IN-NeerjaNeural (liste outras com <kit> voices en- ou outro filtro). Um clipe por segmento de narração; os clipes nunca se sobrepõem; a narração descreve apenas o que está na tela ou está prestes a acontecer naquela cena.
5. Nenhum intervalo maior que 7 segundos. Nenhum trecho sem narração pode atingir 7 segundos. Quando o gravador alertar, ou verify.py falhar, aumente ou divida a narração desse segmento, ou acelere suas ações, e grave novamente.
6. Ritmo. Sem pressa: cada valor digitado deve estar visível antes de prosseguir.
7. Siga a aplicação. Derive rotas, rótulos e botões da aplicação em execução (execução a seco), nunca da memória. Nomeie os botões como a aplicação faz.
8. As saídas ficam fora do git. Áudio gerado, builds e MP4s não são commitados a menos que solicitado.
9. Destaques. Toda demonstração marca o que a narração aponta com uma caixa vermelha, a menos que a solicitação diga "sem destaques".

Destaques

Uma caixa vermelha (4 px, #E11D48, 6 px de distância do elemento) é desenhada ao vivo na página enquanto o vídeo grava, de modo que acompanha a rolagem e faz parte da imagem. Caixa por padrão: cada item de menu clicado no caminho para a tela, os botões que iniciam o processo, cada bloco de dados inserido em uma página de revisão e o botão de envio final. Não coloque caixa em cada campo sendo digitado: o cursor e a digitação já o mostram.

API em flow.cjs:

• goto / click / type / pick (loc, ..., { highlight }): highlight: true coloca caixa no elemento para onde o cursor vai; highlight: <localizador> coloca caixa em outro elemento (por exemplo, sua linha ou bloco inteiro).
• Uma caixa permanece até o cursor se mover para o próximo alvo. { keep: true } mantém também as caixas atuais; k.clearHighlights() as remove; k.highlight(loc) adiciona uma sem mover o cursor.
• Cada caixa adiciona uma entrada highlight a marks em build/timeline-raw.json.

Para um vídeo já gravado sem caixas, <kit> annotate <diretório-demo> as desenha posteriormente a partir de annotations.json. Este é um plano alternativo; gravar novamente é mais fácil e mais preciso.

Fluxo de trabalho

1. Configuração. Execute <kit> doctor (veja Configuração) e verifique se a aplicação responde em sua URL.
2. Execução a seco. Com as ferramentas de navegador do Playwright, percorra o fluxo real sem gravar e sem o envio final: anote a rota de cada tela, rótulos e nomes getByRole, opções de menu suspenso, diálogos, o botão final e o que acontece após ele.
3. Escreva a demonstração: <kit> init <diretório-demo> --url <url da aplicação> cria um ponto de partida que já executa; ou copie examples/todomvc/. Em seguida, edite:
   • narration.json: título, voz, taxa, pronounce (escrito → falado) e segmentos {id, scene, text}. Divida uma cena em vários segmentos sempre que suas ações demorarem, de modo que a narração de cada segmento dure aproximadamente o mesmo tempo que suas ações.
   • flow.cjs: runDemo(__dirname, async (k) => { ... }) com um k.segment(id, async (at, clip) => { ... }) por segmento de narração. Use k.click / k.type / k.pick / k.goto / k.scrollBy; at(segundos) espera por um ponto no clipe (por exemplo clip.cues[0].end). Aguarde elementos, nunca "network idle". Retorne o que foi verificado. Mantenha require(process.env.DEMO_KIT || 'demo-video-kit'): o comando define DEMO_KIT.
4. Produza. <kit> run <diretório-demo> (com DEMO_BASE_URL e quaisquer credenciais no ambiente) executa áudio, gravação, renderização e verificação. Cada linha WARNING do gravador e cada linha FAIL da verificação quebram a regra 5: corrija e execute novamente. Após alterar apenas flow.cjs, --from record pula o áudio; após alterar apenas legendas ou codificação, --from render pula a gravação.
5. Veja o resultado. build/check/contact-sheet.png: cada quadro mostra a tela cheia, o cursor, a etapa correta, legendas legíveis e caixas nos elementos que a narração nomeia. O vídeo é <diretório-demo>/<nome da pasta>.mp4.
6. Entregue. Informe o caminho do MP4, duração, formato, maior intervalo, o que a execução criou e qualquer coisa que difira da solicitação porque a aplicação funciona de forma diferente.

Configuração

Node 18+ e Google Chrome (ou Microsoft Edge: o gravador usa este como alternativa, ou defina DEMO_BROWSER=msedge). Execute npm install uma vez nesta pasta; as vozes (msedge-tts), ffmpeg (ffmpeg-static) e playwright-core vêm com ele, e o gravador baixa o próprio ffmpeg pequeno do Playwright na primeira execução. <kit> doctor verifica tudo isso, incluindo acesso à internet, que as vozes precisam.

Armadilhas conhecidas

Armadilha	Evite
Faixa cinza, página cortada na parte inferior	Nunca grave em uma janela de navegador visível; demo-kit.cjs grava headless em 1920x1080
waitForLoadState('networkidle') trava em aplicações que fazem polling	Aguarde um elemento em vez disso
Um diálogo de interface headless reporta como oculto	Aguarde um campo dentro dele, não o diálogo
Escape dentro de um menu suspenso fecha o diálogo inteiro	Escolha uma opção em vez de pressionar Escape
Um trecho silencioso enquanto muitos campos são digitados	Divida a narração desse segmento; type() aceita { delay } (padrão 32 ms)
Rótulos mostrados em maiúsculas por CSS	Corresponda ao texto real, não à caixa exibida
Uma caixa em torno apenas do rótulo, não seu bloco	Coloque caixa no pai do rótulo (xpath=..) ou avô (xpath=../..)