vishalvana-belwo/belwo-claude-skills

Criar um vídeo de demonstração narrado

Você escreve um arquivo de cenas: cada cena é um trecho de narração mais os cliques que acontecem enquanto ela é reproduzida. Os scripts convertem a narração em fala, controlam o aplicativo em um Chromium headless em resolução fixa 1600×900 enquanto capturam a tela, e geram um MP4 com a narração e legendas embutidas. Um cursor visível, ondulações de clique, anéis de destaque e cartões de título são adicionados sobre a página.

Todos os comandos abaixo usam PY, que significa python no Windows e python3 no macOS, e DV, que significa "${CLAUDE_SKILL_DIR}/scripts/demo_video.py". Cada comando imprime linhas de status simples (SCENE …, RECORDED …, CHECK OK, ERROR …); leia-as em vez de adivinhar.

1. Configuração (uma vez por máquina)

PY "${CLAUDE_SKILL_DIR}/scripts/setup_env.py"

Isso cria um ambiente privado em ~/.claude-demo-video com Playwright, Chromium e edge-tts, depois verifica o ffmpeg. Termina com READY, ou com exatamente o que está faltando. ffmpeg é uma ferramenta do sistema: peça permissão ao usuário antes de instalá-lo (winget install --id Gyan.FFmpeg -e no Windows, brew install ffmpeg no macOS). Os scripts também procuram nas pastas de instalação comuns (WinGet, Chocolatey, Scoop, Homebrew). Se o ffmpeg estiver em outro lugar, defina DEMO_VIDEO_FFMPEG_DIR apontando para sua pasta em todos os comandos.

2. Combine o vídeo com o usuário antes de escrever qualquer coisa

Pergunte ou confirme pelo contexto:

• Quem vai assistir e por quê (um revisor aprovando um recurso, um cliente, novos funcionários). Isso define o tom e o que explicar.
• O que mostrar, em que ordem. Proponha uma lista de cenas com uma linha cada e obtenha a aprovação. Mire em 3 a 8 minutos.
• Voz. O padrão é uma voz neural natural em inglês (edge-tts). Informe ao usuário que o texto da narração é enviado ao serviço de fala da Microsoft para gerar o áudio. Deve conter apenas explicações de funcionalidades, nunca dados. A alternativa é a voz do sistema offline (--offline): nada sai da máquina, mas soa robótico.
• Dados. Grave apenas dados de demonstração: pessoas fictícias, e-mails @example.com, projetos claramente falsos. Nunca grave registros reais de clientes ou funcionários, e nunca aponte o gravador para produção.

3. Prepare o aplicativo

• O aplicativo deve estar em execução e acessível a partir desta máquina, geralmente uma build local.
• Se as telas precisarem de dados, escreva um script de seed e um script de limpeza correspondente para os dados de demonstração, e execute o seed. Marque as linhas de demonstração (por exemplo, IDs começando com DEMO-) para que a limpeza não possa afetar outros dados.
• Certifique-se de que e-mails e notificações de saída estejam desativados, ou que sejam enviados apenas para endereços falsos, porque o walkthrough clica em botões reais (enviar, aprovar…).
• Cenas que alteram dados (aprovar, excluir) só podem ser gravadas uma vez por seed. Reexecute o seed antes de cada nova tentativa.

4. Escreva o arquivo de cenas

Crie-o no projeto do usuário, por exemplo demo-videos/<nome>.py, nunca dentro da pasta da skill. Comece a partir de ${CLAUDE_SKILL_DIR}/reference/scenes-template.py. Para um exemplo real completo, veja ${CLAUDE_SKILL_DIR}/reference/zentrio-timesheet-example.py, que gerou um vídeo de aprovação de 6 minutos.

CONFIG = {'url': 'https://localhost:7101/MyTimesheet', 'ready': '#tsCards .tsw-card', 'sign_in': True}

async def week(r):
    await r.click('.tsw-row:has-text("Approval screen")')
    await r.spot('.tsw-panel', 3)

SCENES = [
    ('week', "Clique em uma linha de tarefa e o painel de registro abre logo abaixo dela.", week),
]

• CONFIG['url'] é a primeira página. ready é um seletor que só fica visível quando a página está carregada e o login foi feito. É como o gravador sabe que o login funcionou.
• Narração: uma a três frases curtas faladas por cena. Explique por que algo é importante, não apenas o que está na tela. Escreva números e símbolos como devem ser ditos ("dois ponto três zero"). Não coloque dados na narração.
• As ações são executadas enquanto a narração é reproduzida. Mantenha-as mais curtas que a narração; o gravador espera a narração terminar antes de iniciar a próxima cena.

Ajudantes de cena (r é o gravador; qualquer outra coisa está disponível como r.page, a página do Playwright):

Ajudante	Faz
await r.goto('/path', wait_for=sel)	abre uma página (relativa a CONFIG['url'])
await r.click(target, dx=.5, dy=.5)	move o cursor visível até lá e clica; dx/dy escolhem o ponto dentro do elemento
await r.move_to(target)	move o cursor sem clicar
await r.type(target, 'text')	clica em um campo e digita nele visivelmente
await r.select(target, value)	escolhe uma opção de dropdown
await r.press('ControlOrMeta+K')	atalho de teclado (Ctrl no Windows, Cmd no macOS)
await r.spot(target, seconds, pad)	anel de destaque laranja
await r.card(kicker, title, lines, bullets) / await r.uncard()	cartão de título em tela cheia (introdução, resumo, encerramento)
await r.confirm_click(target, show=4)	para botões que chamam confirm(): mostra um diálogo similar, depois aceita
await r.download(target)	clica em um download e retorna o caminho do arquivo salvo
await r.show_file(path)	mostra um arquivo local, por exemplo uma prévia HTML que você criou de um relatório baixado
await r.scroll_top(), await r.scroll_x(selector, px)	rolagem suave
await r.clear_toasts(selector)	remove notificações toast que cobrem botões
await r.wait(seconds)	pausa

target é uma string de seletor CSS ou Playwright ('button:has-text("Approve")') ou um Locator (r.page.locator('tr', has_text='Aarav').first).

5. Gere a narração, grave e revise

PY DV voice  demo-videos/<nome>.py     # áudio por cena; imprime a duração de cada cena
PY DV record demo-videos/<nome>.py     # controla o aplicativo e captura frames
PY DV stills demo-videos/<nome>.py     # dois stills por cena em <nome>-video/stills/

Login. Com 'sign_in': True, se o aplicativo não estiver logado, uma janela do navegador abre e o gravador imprime SIGN_IN_NEEDED. Peça ao usuário para fazer login nessa janela. Nunca digite credenciais ou peça senhas. A sessão é salva em <nome>-video/.profile para que novas tentativas não precisem de outro login.

Revise cada still antes de construir, lendo as imagens:

• página certa, painel aberto, cursor onde a narração diz;
• nada cobrindo a ação (toasts, banners de cookies, menu de perfil);
• a imagem não está esticada ou cortada;
• nenhum dado pessoal real na tela.

Uma linha SCENE_ERROR ou um still errado significa corrigir a função daquela cena e gravar novamente (re-seed primeiro se as cenas alteraram dados). reference/lessons.md lista as falhas vistas até agora e suas correções. Leia quando algo parecer estranho.

6. Construa, verifique e entregue

PY DV build demo-videos/<nome>.py [--out "caminho/Nome.mp4"]
PY DV check "caminho/Nome.mp4" --size 1600x900

run faz voz, gravação, stills, construção e verificação de uma vez, quando as cenas já funcionam. Informe ao usuário o caminho e a duração do vídeo, e o que ele mostra. Não faça upload ou compartilhe em nenhum lugar a menos que ele peça.

7. Limpeza

• PY DV clean demo-videos/<nome>.py exclui o login salvo. Faça isso sempre ao terminar, porque ele contém uma sessão real. --all também remove frames, stills e áudio.
• Execute o script de limpeza dos dados de demonstração e pare quaisquer processos do aplicativo que você tenha iniciado.

Notas de plataforma

• macOS: use python3. As legendas são desenhadas pelo Chromium e sobrepostas ao vídeo, então ficam iguais em qualquer lugar e não precisam de um ffmpeg compilado com libass (o do Homebrew não tem). A gravação é headless, então telas Retina não alteram o tamanho do vídeo.
• --headed grava em uma janela visível. Use apenas quando um aplicativo recusar navegadores headless, e peça ao usuário para não tocar ou redimensionar a janela enquanto grava.
• DEMO_VIDEO_HOME move o ambiente privado; DEMO_VIDEO_FFMPEG_DIR aponta para uma pasta do ffmpeg.