omerozgul11/video-de-treinamento-de-app

Vídeo de treinamento de app

Crie um vídeo de treinamento profissional de um aplicativo real. O vídeo tem aproximadamente 1920 × 1080 H.264 com narração AAC. Cada frase falada é legendada, cada capítulo abre com um cartão e longas esperas são cortadas. É reproduzível: quando a interface muda, execute novamente a captura e renderização e o vídeo fica atualizado.

Como funciona:

1. Um storyboard contém o texto da narração, capítulos e identidade visual.
2. narrate.py fala cada segmento com a voz Kokoro offline: nenhum serviço em nuvem, nenhuma conta, nenhum custo.
3. Um script de captura dirige o aplicativo real com Playwright (movimento real do mouse, cursor visível e ondas de clique). Ele grava os quadros do screencast do Chrome e mantém cada segmento até que sua narração termine.
4. render.py monta os clipes, cartões, faixa de legendas e a faixa de narração com normalização de loudness.
5. review.py verifica o resultado e constrói uma folha de contato para inspecionar antes de publicar.

Os scripts estão em scripts/ ao lado deste arquivo. Leia references/storyboard.md antes de escrever a narração e references/capture-guide.md antes de escrever o script de captura. Ambos contêm lições que previnem as regravações comuns.

0. Configuração única

bash <skill>/scripts/setup.sh

Isso cria ~/.cache/app-training-video/ (substitua com TRAINING_VIDEO_HOME) contendo:

• um ambiente Python 3.10–3.13 privado com pacotes fixados;
• o modelo de voz Kokoro (~350 MB) e a fonte Inter, com verificação SHA-256;
• Chromium.

Execute cada script com o Python desse ambiente (PY=~/.cache/app-training-video/venv/bin/python) e passe o caminho para o storyboard. Se os arquivos de modelo já existirem em algum lugar, execute MODEL_SOURCE=<dir> primeiro para reutilizá-los. ffmpeg vem incluído (imageio-ffmpeg); nada é instalado globalmente.

1. Entenda o aplicativo e o público

Antes de escrever qualquer coisa, use o aplicativo (ou leia seu guia do usuário) e descubra:

• Quem assiste: novos clientes, equipe de campo, usuários internos.
• O único fluxo de trabalho que eles devem dominar: da entrada ao resultado.
• Quais dados de demonstração são seguros de mostrar.
• Como iniciar o aplicativo em um estado limpo: URL ou comando de inicialização, além de uma pasta de dados nova ou conta de demonstração.
• Identidade visual: nome da empresa, nome do produto, versão, logotipo PNG, cor de destaque, linhas de contato para o encerramento.

Pergunte ao usuário qualquer coisa que não encontrar. Seis a sete minutos é o ideal para um fluxo de trabalho completo, e 60 a 90 segundos para um recurso único.

2. Escreva o storyboard

Copie assets/storyboard.example.json para junto do projeto como storyboard.json e escreva seguindo references/storyboard.md. Em resumo:

• 10 a 35 segundos de fala por segmento;
• capítulos "n · Título", com card: "chapter" no primeiro segmento de cada capítulo;
• cartões intro e outro;
• siglas escritas por extenso para a voz, com caption_replacements restaurando a forma escrita.

Mostre a narração ao usuário antes de filmar: é barato mudar agora e caro depois.

3. Narre

$PY <skill>/scripts/narrate.py storyboard.json

Isso imprime a duração de cada segmento. Ele refala apenas segmentos cujo texto mudou. Ouça um ou dois WAVs em video-build/audio/ se a pronúncia for importante, ajuste a grafia e execute novamente.

4. Escreva e execute o script de captura

Copie scripts/capture_template.py para capture.py ao lado do storyboard, defina o caminho para os scripts/ da skill e escreva um bloco with rec.segment('<id>'): para cada segmento filmado, na ordem do storyboard. Dentro dele, execute exatamente o que a narração descreve:

• rec.click, rec.hover, rec.type, rec.drag, rec.scroll, rec.park;
• rec.cut() em torno de algo lento, aguardando um resultado visível.

O gravador recusa uma pasta frames/ não vazia, então quadros antigos nunca são misturados.

$PY capture.py storyboard.json

Cada segmento imprime sua duração filmada em relação à sua narração. A execução falha (status incomplete) no primeiro passo quebrado, qualquer erro de página ou qualquer segmento que não foi filmado. Corrija o passo, esvazie video-build/frames/ e execute novamente.

5. Renderize e revise

$PY <skill>/scripts/render.py storyboard.json
$PY <skill>/scripts/review.py storyboard.json

Saídas na pasta de construção:

• <nome_de_saida>.mp4
• legendas .srt
• -chapters.txt (cole em uma descrição do YouTube)
• -poster.jpg
• -timeline.json
• -review.jpg: uma imagem por segmento.

Abra a folha de contato e olhe, e verifique o MP4 em alguns pontos. Verifique:

• a tela correta em cada segmento;
• nenhum banner de erro, gráficos vazios ou diálogos soltos;
• o cursor nunca cobrindo o que está sendo explicado;
• legendas que são lidas corretamente.

Os seletores podem corresponder enquanto a tela está errada, portanto essa verificação é necessária antes de considerar o vídeo pronto.

6. Entregue

Dê ao usuário o MP4, o SRT (a maioria dos players carrega automaticamente quando os nomes coincidem) e a lista de capítulos. Mencione a duração e o tamanho. Para publicar, faça upload do MP4 e SRT juntos. Mantenha storyboard.json e capture.py com o projeto: após a próxima mudança na interface, reexecute as etapas 4–5 (e a etapa 3 se o texto mudou).

Solução de problemas

Sintoma	Correção
Need Python 3.10–3.13	Instale python3.12 ou defina PYTHON= antes de executar setup.sh
launch() expira embora o app tenha iniciado	O app está armazenando em buffer sua saída: execute servidores Python com python -u ou verifique a regex ready
Chromium falha ao iniciar no Linux	$PY -m playwright install --with-deps chromium
Localizador expira ou corresponde a dois elementos	Escopo para uma região, ou use get_by_role com exact=True (veja o guia de captura)
Segmento muito mais longo que sua narração	Algo lento não está dentro de rec.cut()
Pronúncia errada	Reescreva a grafia em speech, adicione uma regra em caption_replacements, execute narrate.py novamente
Legendas fora de sincronia	O tempo das legendas segue a duração da narração: encurte frases longas ou divida o segmento