Vídeo de walkthrough
Transforme "explique este recurso" em um curto MP4: o aplicativo real na tela, uma voz explicando, legendas, um cursor que se move como o de uma pessoa e um anel em volta do que está sendo falado. O usuário fornece as instruções e revisa. Você faz todo o resto.
O trabalho tem um ponto de revisão que importa mais do que qualquer outro: o usuário aprova a narrativa antes de qualquer gravação. Uma mudança de redação custa segundos em um roteiro e minutos em um vídeo, e uma afirmação errada é muito mais barata de ser detectada no papel.
O que você precisa
- O código-fonte do aplicativo e uma instância que você possa abrir e fazer login (local ou ambiente de desenvolvimento/staging). Nunca grave em produção: a gravação clica em botões reais.
- Playwright no projeto do aplicativo (
node_modules/playwrightou@playwright/test). A maioria dos projetos com testes E2E já o possui. Se não:npm i -D playwright && npx playwright install chromium. ffmpegepython3no PATH.- Uma chave de texto-para-fala para a voz final (Murf ou ElevenLabs). Sem uma,
--provider sayusa a voz do macOS, que é suficiente para uma versão preliminar. Vejareferences/voices.md.
Verifique estes itens primeiro e diga claramente o que está faltando. Não peça ao usuário para colar uma chave de API no chat: peça para colocá-la em uma variável de ambiente ou em um arquivo ignorado pelo git e informe onde está.
O fluxo de trabalho
1. Receba as instruções
Você precisa de quatro coisas. Pergunte apenas o que a solicitação já não diz.
- Objetivo e público. "Alinhar com o CTO sobre a nova página de permissões" produz um vídeo diferente de "ensinar novos membros a publicar um aplicativo". O público decide a duração, o vocabulário e o quanto explicar.
- O fluxo. O que mostrar, em ordem. Se o usuário fornecer um, melhore-o e diga o que mudou e por quê: uma ordem melhor, uma etapa ausente, uma etapa que não acrescenta nada. Eles pediram um vídeo, não uma transcrição da lista deles.
- Duração. Padrão de 60 a 120 segundos e um tópico. Se o fluxo precisar de mais, proponha dois vídeos.
- Voz. Provedor e voz, se tiverem preferência. Caso contrário, use os padrões.
2. Percorra o fluxo no aplicativo real antes de escrever uma palavra
Execute o aplicativo, faça login com uma conta de demonstração e execute cada etapa do fluxo você mesmo com Playwright ou o navegador. Você está verificando que cada coisa que a narração afirmará é verdadeira.
É aqui que vem a maior parte do valor da habilidade. Os recursos são frequentemente descritos de memória ou da especificação, e o aplicativo faz algo ligeiramente diferente. Se o aplicativo não fizer o que o usuário disse que faz, pare e avise-o, com o que você observou. Não escreva narração que esconda o problema e não ignore a etapa silenciosamente.
Observe os rótulos exatos nos botões e menus enquanto estiver lá. A narração deve usar as palavras na tela.
3. Crie dados de demonstração
Um walkthrough em uma conta vazia ou semi-quebrada parece um relatório de bug. Crie o que a história precisa: uma organização, alguns usuários com funções diferentes, itens com nomes críveis. Use apenas nomes inventados (Acme, Northwind, example.com): esses vídeos são encaminhados.
Mantenha uma lista de tudo que você criar ou alterar. Você irá desfazê-la na etapa 9.
4. Escreva a narrativa e pare para revisão
Escreva-a como uma tabela e salve-a ao lado de onde o vídeo será gerado, como <nn>-<slug>.script.md:
| # | Na tela | Narração | ~seg |
|---|---|---|---|
| 1 | Lista de tarefas em repouso. Anel na lista. | Esta é a lista de tarefas da equipe. / Todos na equipe veem as mesmas tarefas. | 5 |
| 2 | Cursor para **Adicionar tarefa**, formulário abre. Digite um nome, clique em **Salvar tarefa**. | Para adicionar uma, selecione Adicionar tarefa, / dê um nome a ela, / e salve. | 7 |
A barra / marca a divisão da narração de uma cena em linhas de legenda. Leia references/narrative.md antes de escrever: aborda ritmo, comprimento da linha, cartões de antes/depois e os erros que tornam esses vídeos difíceis de seguir.
Mostre a tabela ao usuário e aguarde. Informe a duração total esperada. Se você mudou o fluxo deles, informe aqui. Continue somente quando eles aprovarem; se pedirem alterações, envie a tabela revisada novamente.
5. Gere a voz
Escreva a narração aprovada em scenes.json, uma entrada por linha, com as linhas divididas nas marcas /:
[{ "id": "02", "lines": ["Para adicionar uma, selecione Adicionar tarefa,", "dê um nome a ela,", "e salve."] }]
python3 scripts/tts.py scenes.json --audio-dir work/audio --provider murf
Isso escreve um clipe por cena e durations.json. A voz vem antes da gravação propositalmente: cada cena é mantida na tela pelo tempo que seu clipe durar, então os comprimentos dos clipes precisam existir primeiro. Reexecutar só regenera cenas cujo texto mudou.
6. Escreva o script de gravação e teste-o em seco
Copie example/record.cjs e reescreva suas cenas para este fluxo. scripts/walkthrough.cjs oferece:
| Auxiliar | Uso |
|---|---|
scene(id, async () => {...}) | Uma cena narrada. Mostra suas legendas e espera até a voz terminar. |
clickAt(locator) | Deslize o cursor até o elemento, mostre o pressionamento, clique. Use isto, não locator.click(), ou as coisas acontecem sem causa visível. |
moveTo(locator) | Aponte para algo sem clicar. |
typeInto(locator, text) | Clique em um campo e digite em velocidade legível. |
ring(locator) / ring(null) | Destaque o que a voz está falando; remova quando a voz passar para outro assunto. |
step('Etapa 2 de 4 · Salvar') | O rótulo no canto inferior esquerdo que informa ao espectador onde ele está. |
card({ title, subtitle }) | Cartão de título em tela cheia, para a cena de encerramento. |
card({ before, after }) | Comparação antes/depois. card(null) esconde. |
login: async (page) => {...} | Opção de record(). Faz login fora da câmera para que o vídeo comece onde a história começa. |
Prefira localizadores por função e rótulo (getByRole, getByLabel) em vez de CSS: eles sobrevivem a reformulações e são os nomes que a narração usa. Leia nomes da tela em tempo de execução quando os dados podem diferir entre ambientes.
Execute primeiro com dry:
node record.cjs <app-repo> work/rec work/audio/durations.json dry
Uma execução a seco não grava nada e não espera a voz, então um seletor errado custa segundos, não uma gravação completa. Corrija até que cada cena funcione.
7. Grave e monte
node record.cjs <app-repo> work/rec work/audio/durations.json
python3 scripts/mux.py --rec work/rec --audio-dir work/audio --output walkthrough-videos/<nn>-<slug>.mp4
O gravador imprime o comprimento do clipe de cada cena ao lado de quanto tempo suas ações levaram. Uma cena sinalizada com segundos de silêncio após a voz tem muitas coisas acontecendo para o que é dito: reduza as ações ou dê mais o que dizer à voz.
mux.py escreve o MP4, um .srt correspondente e <name>.sheet.jpg.
8. Verifique você mesmo antes do usuário
Abra a folha de contato: um quadro por cena. Procure um anel no elemento errado ou faltando, uma legenda cobrindo a coisa sendo discutida, uma cena na tela errada, um selo de ferramentas de desenvolvimento ou toast de erro no quadro, dados pessoais reais. Extraia quadros individuais com ffmpeg quando a folha for muito pequena para distinguir.
Em seguida, entregue o vídeo com: sua duração, o que mudou da narrativa aprovada, se algo mudou, e qualquer coisa que você não pôde verificar.
Quando o usuário quiser alterações, volte primeiro para a narrativa. Revise a tabela, mostre-a, obtenha a aprovação e regenere apenas o que mudou. A maioria dos feedbacks ("muito rápido", "perdi o que mudou", "mencione também o filtro") é feedback sobre o roteiro, e corrigi-lo apenas na gravação produz um vídeo que não corresponde mais ao seu roteiro.
9. Reverta as alterações
Desfaça o que a gravação alterou, usando a lista da etapa 3 e o que a própria gravação clicou: configurações alteradas, itens criados ou removidos, estado das contas de demonstração. Depois informe ao usuário o que foi restaurado e o que você deixou deliberadamente (dados de semente que ele pode querer para o próximo vídeo, por exemplo). Se algo não puder ser desfeito, avise.
Arquivos
Os entregáveis vão todos juntos em um lugar que o usuário possa encontrar, por padrão walkthrough-videos/ no projeto:
walkthrough-videos/
03-adicionar-uma-tarefa.mp4
03-adicionar-uma-tarefa.srt
03-adicionar-uma-tarefa.script.md
Mantenha os arquivos de trabalho (scenes.json, áudio, gravação bruta, o script de gravação) fora do repositório ou em uma pasta ignorada pelo git. Eles são grandes, e o script de gravação contém seletores para um momento na vida do aplicativo. O roteiro e o .srt valem a pena manter: eles tornam a próxima revisão uma pequena edição.
Coisas que dão errado
- Controles nativos não são gravados. Um menu suspenso
<select>nativo, um seletor de arquivo ou uma caixa de diálogo do navegador são desenhados pelo navegador fora da página. Aponte para o controle commoveTo, defina o valor comselectOption/setInputFilese deixe a narração dizer o que foi escolhido. - A sobreposição desaparece após a navegação. Ela é recriada a cada carregamento de página e a etapa atual e a legenda são restauradas. Se uma página substituir
document.bodypor completo, chamestep()novamente após ela se estabilizar. - Uma cena começa antes da página estar pronta. Espere pela coisa sobre a qual a cena é (
await locator.waitFor()) antes de chamarscene(), não dentro dela, para que o tempo de carregamento não seja narrado. - Os primeiros segundos são uma página em branco.
mux.pycorta tudo antes da primeira cena. Faça a navegação e a espera antes descene('01'). - Login na câmera. Use a opção
login. Ninguém precisa ver um campo de senha, e as credenciais não devem ficar visíveis em um vídeo compartilhado.