Da demo ao reel promo: demo web estilo Screen Studio

webapp-screencast

Você roteiriza a cena, o webapp-screencast a grava e edita. Saída: OUT/<name>.mp4 (1920×1080, 60 fps) mais um pôster .jpg. Tudo é um arquivo que você escreve (scenario.py, plan.py) e uma CLI. Sempre chame a CLI com --json (antes do subcomando): stdout é um objeto JSON (ok, error, caminhos, durações, avisos); o progresso vai para stderr. Exit 0 ok, 1 etapa falhou, 2 entrada inválida.

Chaves da API e do plano: reference.md. Leia antes de escrever scenario.py / plan.py.

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

webapp-screencast --json doctor

Se webapp-screencast estiver faltando: pip install git+https://github.com/dr-osmanovich/webapp-screencast.git (use o venv do projeto se houver), depois python -m playwright install chromium. doctor lista cada verificação com falha e sua fix. Node 22+ e ffmpeg são necessários para renderização.

1. Entenda o aplicativo (antes de qualquer gravação)

• Descubra como ele roda localmente (README, package.json scripts, Makefile, docker-compose) e sua URL. Uma pasta estática simples pode ser servida pelo próprio webapp-screencast (make --serve DIR).
• Encontre dados de demonstração/semente e contas de teste no repositório (fixtures, scripts seed, .env.example). Nunca grave dados de produção, clientes reais, pacientes ou credenciais reais. Se não existirem dados de demonstração seguros, pare e pergunte ao usuário.
• Descubra como redefinir o estado (script seed/reset, limpar localStorage). Cada take começa limpo.
• Escolha 3–5 batidas que mostrem o valor: gancho → ação → resultado → um detalhe → fim. 15–30 s de filmagem.
• Leia os componentes reais para obter seletores estáveis (ids, data-testid, roles). Não adivinhe.

2. Estrutura e roteiro

webapp-screencast --json init video/ --base-url http://127.0.0.1:3000 --title "Nome do produto"

Escreva video/scenario.py: CONFIG, login(page, cfg) e prepare(page, cfg) (opcionais), e run(take, page). Regras que economizam retakes:

• take.mark("nome") em cada batida; take.box("nome", seletor) (ou click(..., name=)) para tudo que a câmera ou um destaque deve enquadrar. Sempre marque hook primeiro e end por último.
• Aguarde o aplicativo com page.wait_for_selector(...) após as ações, depois take.hold(0.3–0.8).
• Posicione o ponteiro longe do texto antes de take.type(...); digite a cps 25–35.
• Em prepare() oculte toasts, banners de cookies, overlays de desenvolvimento; feche painéis laterais.
• Dicas de ferramentas nativas title= nunca renderizam headless — use um callout do plano.

3. Grave e inspecione

webapp-screencast --json record video/scenario.py --out video/out/footage [--base-url URL]
webapp-screencast --json inspect video/out/footage

Verifique se peak_fps ≥ 50 nas batidas movimentadas (menor no macOS → veja sinalizadores de GPU no reference) e se cada marca que você planejou está presente. Um seletor com falha gera um erro do Playwright no stderr: corrija o cenário e grave novamente — a filmagem é barata (≈ duração do take + 10 s).

4. Planeje, componha, olhe

Escreva video/plan.py usando as marcas e caixas que inspect imprimiu (nunca codifique segundos): segmentos de câmera que seguem a ação (zoom 1.4–1.7 na batida, volte para 1.0 entre cenas), um subtítulo curto por batida (≥ 0.3 s por palavra, sem sobreposições), cartões de introdução/saída.

webapp-screencast --json compose video/plan.py --footage video/out/footage --out video/out/composition
webapp-screencast --json snapshot video/out/composition --at 1,5,9,14 --out video/out/stills

Corrija todas as entradas de warnings. Olhe os stills (leia os PNGs / contact sheet): texto legível, câmera na ação, nada cortado, nenhum subtítulo cobrindo a coisa que descreve. Itere no plan.py com compose + snapshot apenas — não é necessário gravar novamente.

5. Renderize e entregue

A renderização leva aproximadamente 4–5 min por 20 s em um M1 — execute em segundo plano com um arquivo de log.

webapp-screencast --json render video/out/composition --out video/out/video.mp4
webapp-screencast --json poster video/out/video.mp4 --at 9.0

Confirme se o JSON mostra fps: 60 e a duração esperada. Entregue os caminhos do mp4 e do pôster. .gitignore o diretório out/; commit scenario.py + plan.py para que o vídeo possa ser refeito após mudanças na UI.

Único comando quando o cenário e o plano já estão bons: webapp-screencast --json make video/scenario.py video/plan.py --out video/out --base-url URL --poster-at 9 (--serve DIR para sites estáticos, --skip-render para parar após a verificação).

Com /brag (ou outra skill de vídeo de lançamento)

O Brag decide a história; o webapp-screencast fornece a filmagem real.

1. Execute o planejamento do brag: conceito, tom, batidas, título, texto. Pare antes de construir cenas de screenshot.
2. Transforme as batidas do brag em marcas scenario.py (uma marca por batida) e grave.
3. Coloque as falas do brag no plan.py: gancho → intro.title, legendas das batidas → subtitles, frase de encerramento / CTA → outro; mapeie o tom do brag para look (polido → graphite/ocean, divertido → sunset/violet, destaque = a cor da marca do aplicativo do seu CSS).
4. Componha, faça snapshot, renderize como acima na pasta de saída do brag; depois deixe o brag escrever o texto de compartilhamento. Apenas landscape 16:9 por enquanto; se o brag pedir vertical, avise e renderize landscape.