Vídeos de treinamento do sistema
Grava o uso real de um sistema web e o transforma em vídeos de treinamento prontos: um vídeo curto por capítulo e um vídeo completo com marcadores de capítulo. Não há narração. Pequenas chamadas (callouts) explicam o que está acontecendo e por quê.
O método é fixo porque cada parte resolve um problema real de gravação. Apenas a aparência muda de um sistema para outro.
| Permanece igual em todo sistema | Vem do próprio sistema |
|---|---|
| Vídeo 1920 × 1080, 30 quadros por segundo, MP4 | Cores do cartão e da chamada, lidas de suas páginas |
| Cartão de título: logotipo, chamada principal (kicker), título, uma linha, faixa de cor | Cor do destaque, seta e anel de clique |
| Caixa de chamada com seta e destaque no elemento | Fontes de cabeçalho e corpo, incluindo fontes da web |
| Contador "Passo n de N" em um canto | Arredondamento de cantos, a partir de seus botões |
| Cursor lento, anéis de clique, zooms suaves, cortes rápidos (jump cuts) sobre carregamento | Logotipo |
| Efeitos sonoros, gerados em código | Chamadas claras ou escuras, conforme seu fundo |
| Cartões pretos de capítulo e marcadores no vídeo completo | Idioma e texto da direita para a esquerda (RTL) |
Regras e por que existem
- Uma cópia local com apenas dados fictícios. Os scripts clicam e salvam de verdade, e um vídeo pode ser compartilhado com qualquer pessoa. O mecanismo recusa endereços que não sejam locais. Apenas o proprietário do sistema pode definir
allowRemote: true, e somente para um servidor de teste que não contenha dados reais. Nunca aponte para um sistema em produção e nunca mostre nomes, e-mails ou documentos reais de pessoas. - O aplicativo não é alterado. Tudo reside na pasta
video-tour/do projeto, que tem seus próprios pacotes. Se uma tarefa não puder ser mostrada sem alterar o aplicativo, deixe-a de fora e reporte. - Os vídeos ficam fora do repositório. Eles vão para uma pasta externa a ele.
- Siga as regras do próprio projeto. Leia primeiro seu
CLAUDE.mdou similar. Se disser que o proprietário gerencia o git, não execute git. Em uma máquina pequena, execute uma tarefa pesada por vez. - Não finja o que o sistema não pode fazer. Uma tarefa que depende da data atual, de um serviço externo ou de um recurso com respostas variáveis (como um chatbot) é deixada de fora e reportada. Qualquer dado preparado antes da gravação é divulgado no relatório.
Passo 1: Reúna o que precisa, de uma vez
Primeiro, examine o projeto: README, package.json, documentação, dados de seed, contas de teste. Depois, pergunte o que ainda estiver faltando em uma única lista e não pare para perguntar novamente até o primeiro instante.
- Como iniciar o sistema localmente e seu endereço.
- Como redefinir os dados de teste. Sem uma redefinição, os capítulos colidem com os dados uns dos outros.
- Contas de teste, uma para cada função que os vídeos precisam.
- Para quem são os vídeos. Isso define quais tarefas importam e as palavras nos cartões.
- O idioma das chamadas. Padrão: o idioma das telas do sistema.
- Onde os vídeos devem ser salvos. Padrão: uma pasta ao lado do projeto.
Passo 2: Conheça o sistema e planeje os capítulos
Leia suas rotas, menu e qualquer documentação do usuário, e abra as páginas no sistema em execução. Em seguida, escreva um plano de capítulos: um capítulo para cada área com a qual uma pessoa realmente trabalha, cada um construído em torno de tarefas ("criar um pedido e enviá-lo para aprovação"), não um tour pelas telas. Um capítulo geralmente tem de 2 a 6 passos e dura de 1 a 4 minutos. Comece com um capítulo "Primeiros passos". Liste o que você planeja deixar de fora, com a razão.
Passo 3: Configure e leia a aparência do sistema
node ~/.claude/skills/system-training-videos/scripts/init.mjs <pasta do projeto> --out "<pasta do vídeo>"
cd <pasta do projeto>/video-tour && npm install && npx playwright install chromium
Preencha todos os TODO em video-tour/tour.config.mjs. Verifique se o login funciona executando o próximo comando, que o utiliza:
node video-tour/tour.mjs brand
Isso visita o sistema, lê sua aparência, escreve theme.json e o logotipo, e salva quatro prévias em <pasta do vídeo>/_work/brand/: title-card.png, chapter-card.png, callout.png e counter.png. Olhe para todas as quatro. A detecção de cores é um bom palpite, não um fato, então julgue-as como um espectador faria: isso se parece com o sistema? O logotipo correto está lá? O título está na fonte real do sistema? Corrija qualquer coisa com theme na configuração e execute brand novamente. Veja references/theme-and-config.md.
Passo 4: Capítulo 1, depois uma aprovação
Escreva o capítulo 1 (primeiro leia references/writing-chapters.md), depois:
node video-tour/tour.mjs make 1
make redefine os dados, faz um ensaio rápido, redefine novamente, grava, constrói e verifica. Olhe para a imagem estática (still) e para a folha de contato (contact sheet) que ele imprime.
Em seguida, pare e mostre ao proprietário o plano dos capítulos, as tarefas deixadas de fora e a imagem estática. Esta é a única aprovação. É barato mudar a aparência ou o plano agora, e caro após uma série completa. Após o OK, termine a série sem parar.
Passo 5: Os outros capítulos
Para cada capítulo: escreva-o, execute make e olhe para sua folha de contato. check captura o que pode ser medido: chamadas na tela com menos de 2,5 s, telas de carregamento na câmera, erros do navegador, níveis de som. Ele não consegue ver significado, então leia os quadros você mesmo para:
- uma chamada no elemento errado ou cortada na borda da tela;
- uma chamada, contador ou popup cobrindo o que o espectador precisa ver;
- uma mensagem de erro, uma página vazia ou qualquer coisa que não seja fictícia;
- um zoom que corta o que deveria mostrar.
Se algo na folha for duvidoso, extraia um quadro completo: ffmpeg -ss 20 -i chapter.mp4 -frames:v 1 frame.png.
Se um capítulo ainda falhar após duas rodadas de correções, pule-o, reporte e continue. Problemas vistos antes estão em references/troubleshooting.md.
Passo 6: O vídeo completo
Com todos os capítulos construídos e o sistema em execução:
node video-tour/tour.mjs join
Isso escreve <nome>-training.mp4 com um cartão de abertura, um cartão preto antes de cada capítulo, um cartão de encerramento, marcadores de capítulo e chapters.txt (linhas "00:00 Título", prontas para o YouTube). Verifique a duração e os marcadores:
ffprobe -v error -show_entries chapter=start_time:chapter_tags=title -of csv=p=0 <vídeo completo>
Passo 7: Relatório
Escreva para alguém que não é técnico, em frases curtas:
- O caminho e a duração de cada capítulo e do vídeo completo, em uma tabela.
- A pasta com uma imagem estática (still) por capítulo.
- A lista de capítulos com horários de início.
- O que foi deixado de fora ou pulado, e por quê.
- Dados preparados antes da gravação, que o vídeo não mostra.
- Pequenas imperfeições visuais que você viu e aceitou.
- Que você verificou o som medindo-o, não ouvindo-o, então uma pessoa deve ouvir um capítulo antes de compartilhar.
Em seguida, pare os servidores que você iniciou.
Arquivos de referência
references/writing-chapters.md: leia antes de escrever um capítulo. Cada ação, os padrões que mantêm um vídeo limpo e como escrever chamadas.references/theme-and-config.md: as configurações, o quebrandlê e como corrigir a aparência.references/troubleshooting.md: leia quando uma gravação falhar ou um quadro parecer errado.