promo-video

promo-video — do SaaS que roda local ao vídeo de marketing finalizado

O objetivo: o usuário abre o Claude na pasta do seu produto (ou uma pasta vazia), explica o que deseja mostrar, e sai com um MP4 impressionante que mostra seu produto real, não mockups aproximados. A história é validada com ele ANTES de codificar. Tudo que se move na tela é medido (coordenadas capturadas), tudo que se ouve é gerado (zero direitos autorais).

O skill foi construído produzindo um vídeo real (Trkly, 41 s, 11 capturas, música sincronizada) e codifica tudo que foi aprendido: as armadilhas do Remotion, Playwright, lint, e o que torna um vídeo de produto confiável.

Arquivos do skill

Caminho	Função
scripts/setup.mjs	Scaffold completo do projeto Remotion (deps, Playwright, skills Remotion, templates, música)
scripts/capture.mjs	Captura declarativa das páginas reais (plano JSON → PNG @2x + boxes.json)
scripts/boxes-to-ts.mjs	boxes.json → src/story/boxes.ts tipado
scripts/make-music.mjs	Música + SFX sintetizados (drop e golpe final parametrizáveis)
scripts/probe.mjs	Verifica um MP4 renderizado (duração, faixas) sem ffmpeg
templates/	Componentes (BrowserFrame, Cursor, Caption, Callout, DotGrid), cenas, brand.ts, plano de captura de exemplo, CLAUDE.md do projeto
templates/examples/Demo.example.tsx	A demo completa de referência (28 s, 11 capturas, scroll, digitação, chips) para ler antes de escrever a sua
references/scenario.md	Modelo de roteiro + regras de escrita das legendas
references/pitfalls.md	Todas as armadilhas encontradas (Remotion, Playwright, lint, áudio, Windows)
references/checklist.md	O que verificar antes de entregar

<skill> abaixo = a pasta deste SKILL.md (~/.claude/skills/promo-video, .claude/skills/promo-video ou o cache do plugin). Verifique com ls antes de executar um script.

Fluxo de trabalho

0. Alinhar (5 minutos) — e VALIDAR o roteiro antes de codificar

Faça a si mesmo (ou ao usuário, de uma só vez) as seguintes perguntas:

1. O produto: nome, uma frase, URL local (npm run dev em qual porta?) ou URL de produção. Existe uma barreira de login/assinatura? → é preciso uma forma de removê-la para filmar (flag de demo no app, conta de teste, cookies). NUNCA peça senha para digitar você mesmo: o usuário faz login em um navegador e fornece os cookies, ou ativa um modo demo.
2. O que ele quer mostrar: 3 a 5 momentos específicos (uma página, um filtro, um clique, um resultado). Cada momento = uma captura + uma ação do cursor + uma legenda.
3. A dor que o produto resolve, em uma frase familiar (« Cansado de…? »).
4. O formato: 16:9 padrão (X, LinkedIn, YouTube, landing). 9:16 apenas se solicitado explicitamente (TikTok/Reels) — os templates foram projetados para 1920x1080.
5. O CTA final: URL, « Link na bio », « Teste grátis »… e a tagline.

Em seguida, escreva o roteiro no chat usando references/scenario.md como modelo: 8 cenas, durações, texto na tela, o que se vê, e proponha a escolha técnica (capturas reais via Playwright, recomendado). Aguarde o « vai » do usuário. Se ele disser « deixo com você », é um vai: não faça mais perguntas, tome decisões e documente-as.

Escreva o roteiro validado em SCENARIO.md na raiz do projeto de vídeo: é a referência para todas as cenas e para ajustes futuros.

1. Scaffold do projeto de vídeo

Sempre um projeto separado do produto (pasta irmã <produto>-video): Remotion + Chromium não têm lugar no build do SaaS, e o tsc de um next build incluiria os arquivos de vídeo.

node <skill>/scripts/setup.mjs ../meusaaS-video --name "MeuSaaS" --domain meusaaS.app --base http://localhost:3000 --accent "#f97316" --desc "uma frase"

O script: create-video --blank (Tailwind v4 incluso), remotion add de pacotes (transitions, google-fonts, media, zod, + whisper-webgpu e video-matting que são dependências opcionais do Studio sem as quais ele exibe erros), Playwright 1.63 + Chromium, os skills oficiais do Remotion (npx skills add remotion-dev/skills), cópia dos templates, CLAUDE.md do projeto, launch.json (Studio na porta 3012 — altere --port se ocupada), e uma música padrão. Conte de 3 a 5 minutos.

Em seguida: npm run lint no projeto deve estar verde antes de qualquer modificação (o esqueleto compila com caixas placeholder).

2. Extrair a identidade visual do produto

Abra o CSS do produto (globals.css, tailwind.config, variáveis :root) e preencha src/brand.ts: cor de destaque, fundo escuro, texto, fonte Google (altere o import @remotion/google-fonts/<Font>), logo (copie o PNG para public/logo.png), domínio. Não adivinhe as cores: leia-as. Todos os componentes leem brand, nenhuma cor está codificada nas cenas.

3. Capturar o produto real

O produto deve estar rodando (peça ao usuário para iniciar o servidor, ou inicie via preview_start, nunca no Bash). Se uma barreira bloquear o conteúdo, remova-a ANTES (modo demo, cookies no plano: "cookies": [...], ou "localStorage": {...}).

Escreva capture-plan.json (modelo: capture-plan.example.json, documentação completa no início de scripts/capture.mjs): uma etapa por ação. Para cada momento do roteiro:

• shot do estado anterior, click/type da ação, settle, shot do estado posterior;
• box para cada elemento que o cursor vai mirar ou que um destaque vai envolver (botões, opções de menu, campo de pesquisa, primeira linha de uma tabela, badge, seção);
• para uma página longa, viewport alto (ex. 1920x3400) com "group": "tall" — nunca use shotFull em um layout h-screen/painel rolável, ele captura apenas o viewport;
• uma geração de IA: shot durante o carregamento, waitGone do spinner (timeout longo), shot do resultado.

node <skill>/scripts/capture.mjs capture-plan.json      # PNG @2x + public/shots/boxes.json
node <skill>/scripts/boxes-to-ts.mjs                    # -> src/story/boxes.ts

Veja cada captura (ferramenta Read) antes de continuar: conteúdo indesejado (dados de teste feios, bug de exibição, nome de usuário), popover mal aberto, página não carregada. Corrija no plano (adicione um wait, um filtro na URL, um css para esconder um elemento) e recapture. Se você identificar um bug do produto, anote-o para a entrega — não o corrija no produto sem solicitação.

4. Música

setup.mjs já gerou public/audio/ (music + click/whoosh/pop/impact). A música é estruturada: introdução tensa → drop → groove → golpe final → final. Faça o drop coincidir com a chegada do produto na tela e o golpe final com a assinatura:

node <skill>/scripts/make-music.mjs --drop 8 --end 36 --total 42.5 [--bpm 120] [--transpose -2] [--seed 7]

120 BPM = 15 quadros por batida a 30 fps: alinhe as cenas em múltiplos de 15. Se o usuário fornecer um mp3, coloque-o em public/audio/music.wav|mp3 e adapte Story.tsx — verifique a licença antes.

5. Escrever as cenas

Leia templates/examples/Demo.example.tsx por inteiro: é o modelo do que se espera (zoom da câmera para cada elemento clicado, cursor que chega em arco e clica, captura seguinte em fade, destaque + etiqueta, scroll de uma captura alta, digitação letra por letra, chips que aparecem, legenda em tela cheia por ideia, flash branco nos cortes fortes, pulsação na batida). Depois adapte Demo.tsx: SHOTS (capturas e limites), ZOOM (keyframes da câmera), SCROLL, CURSOR (os cliques disparam os sons), os Callout, as Caption.

Regras de direção:

• Uma ideia por legenda, 3 a 6 palavras + um grupo em destaque. Nunca duas legendas ao mesmo tempo.
• Zoom para o que se quer que seja lido (1,4 a 1,7) e depois retorno a 1: o espectador deve poder ler os rótulos reais. Uma captura em largura total sem zoom não é legível.
• O cursor mostra antes de clicar: ele chega 15 a 25 quadros antes do clique, nunca teletransportado.
• Uma ação = estado anterior → clique → estado posterior, com o fade de 4 quadros dos SHOTS.
• Nenhuma coordenada fixa: tudo vem de boxes. Se faltar um número, adicione uma box ao plano.
• Textos de cópia e cenas (Hook/Tension/Outro) passam pelas props de Story → editáveis no Studio.

Verifique durante o processo com stills, não no Studio reduzido:

npx remotion still Demo out/check.png --frame=120 --scale=0.5

Veja cada still (ferramenta Read). Procure: texto cortado na borda da janela, etiqueta sobrepondo um elemento lido, cursor no lugar errado, captura ainda não exibida, legenda cobrindo a ação. Corrija, re-renderize, até que cada momento chave esteja limpo.

6. Renderizar e verificar

npm run lint
npx remotion render Story out/<slug>-story.mp4
node <skill>/scripts/probe.mjs out/<slug>-story.mp4     # duração, faixa de vídeo, faixa de áudio

Não conclua « está bom » confiando apenas na renderização: renderize 6 a 10 stills nos momentos chave da versão final e veja-os. Você não pode ouvir o mix: informe isso ao usuário e indique como ajustar (volume em Story.tsx, parâmetros de make-music.mjs).

7. Entregar

Envie o MP4 (SendUserFile) e um resumo que se sustente sozinho: onde está o arquivo, duração/formato, a lista de cenas com o que se vê, o que foi verificado e o que não foi (o som), os bugs do produto identificados durante a filmagem, como recapturar se a UI mudar (3 comandos), e as variantes fáceis (9:16, versão de 15 s, outro idioma = props de Story). Veja references/checklist.md.

O que torna o vídeo « impressionante » (por ordem de impacto)

1. O produto real na tela, legível (zoom), com um cursor que faz ações reais.
2. O drop musical sincronizado com a chegada do produto, flash branco no corte.
3. As legendas: curtas, familiares, uma por ideia, uma palavra em destaque.
4. Os destaques que apontam exatamente o elemento do qual se fala (badge de preço real, botão).
5. O ritmo: nunca mais de 2 s sem que algo aconteça; 40 s no máximo no total.
6. Os microdetalhes: fade entre capturas, pulsação na batida, chips que aparecem, SFX de clique.

Carregue references/pitfalls.md antes de escrever código Remotion e releia references/checklist.md antes de entregar.