dyachkovp/product-motion

Product Motion

Vídeos curtos que mostram como uma funcionalidade funciona: a interface do produto em quadro, cursor clicando, texto sendo digitado, etiquetas aparecendo sob fragmentos de entrada, cartões surgindo em cascata, câmera guiando o olhar, voz narrando a ação. A abordagem foi testada em vídeos para diversos produtos; aqui está separada de uma marca específica.

Princípios

1. Quadro é função do tempo. O vídeo é uma página HTML onde render(t) calcula o estado do quadro no tempo, e scripts/render.py captura quadros um a um e entrega ao ffmpeg. Sem animações CSS, timers ou gravação de tela: sem travamentos ou dessincronização, qualquer momento pode ser verificado com um quadro isolado. O motor é templates/engine.js (references/engine.md).
2. Mostramos apenas o que existe no produto. Telas, legendas, estados — do código, protótipo, docs/ ou screenshots do projeto atual. Funções inexistentes não aparecem no vídeo. Dados — nomes curtos fictícios. O que for inventado para a cena (respostas, textos de estados) é informado ao usuário para conferência.
3. Estilo é do produto, não do skill. Cores, destaque, fontes, logotipos — do perfil de marca do projeto (motion/brand/), extraído de seu código (references/brand.md). O perfil neutro do skill é apenas para rascunho.
4. Não sintetizamos voz. TTS locais soam robóticos. O usuário recebe o texto e o prompt para Gemini TTS separadamente (ou grava a voz ele mesmo) e envia o arquivo; align_vo.py sincroniza por palavras. Até lá, o vídeo existe com legendas e música.
5. Primeiro com os olhos, depois render. Folhas de contato dos momentos-chave nos formatos escolhidos e verify_scene.py — antes do render completo. Erros de composição são mais baratos de detectar nos quadros.
6. Não adivinhamos decisões do usuário. Idioma, formatos, aceleração, música, publicação — a partir do briefing ou pergunta. Os padrões abaixo aplicam-se apenas quando o usuário não especificou o contrário.

Processo

0. Ambiente (uma vez por máquina)

python3 <skill>/scripts/check_env.py

Necessário Python 3.9+, ffmpeg/ffprobe, pip install playwright numpy scipy pillow (+ faster-whisper para locução), python -m playwright install chromium; para versão acelerada — ffmpeg com rubberband. Melhor em um venv do projeto ou próximo; não instale dependências sem consentimento do usuário — apenas sugira os comandos.

1. Briefing

Funcionalidade; duração (se não dito — 30–35 s para uma funcionalidade, 60–75 s para uma seção); público e propósito (tutorial, promo, investidor, landing page); idioma; formatos (se não dito — 16:9, vertical 9:16 sugerir). No máximo duas perguntas por vez; o restante — padrões razoáveis, informados na resposta. Detalhes — references/brief.md.

2. Fatos sobre a funcionalidade — do projeto atual

Leia o código e protótipo da funcionalidade, docs/, screenshots: telas, legendas exatas, placeholders, botões, estados, o que existe e o que não existe. Se não estiver claro o que o usuário vê após a ação principal, pergunte.

3. Perfil de marca — uma vez por projeto

Se não houver motion/brand/ no projeto — monte-o conforme references/brand.md: brand.css (tokens de variáveis CSS, temas, configuração tailwind), fontes locais com direitos verificados, logotipos. Mostre ao usuário um quadro de amostra antes do primeiro vídeo. Os vídeos seguintes usam o perfil pronto.

4. Roteiro

Tabela 'timecode · o que está no quadro · câmera/animação · fala' (references/storyboard.md: esqueletos por duração, densidade de texto 1.3–1.6 palavras por segundo, arquétipos de cena). Vídeo com mais de 30 s ou briefing incompleto — mostre a tabela e aguarde 'ok'; curto com briefing claro — pode montar imediatamente e mostrar a tabela junto com os primeiros quadros.

5. Projeto do vídeo

Se já houver um local para vídeos no projeto (promo/, design/motion/, etc.) — coloque lá; senão, motion/<slug>/.

python3 <skill>/scripts/new_project.py motion/<slug> --brand motion/brand --lang pt --title "Funcionalidade · Produto"

Conteúdo: video.html, plan.js, cues.js, tmap.js, engine.js, processing.js, base.css, brand/, build/, out/, README.md. build/ e out/*.mp4 grandes — em .gitignore do projeto, a menos que o usuário decida o contrário. Se houver docs/ no projeto, adicione um link curto para o vídeo e seu README.

6. plan.js e cenas

plan.js é a fonte única: duration, fps, canvas, language, product, audience, hold, falas vo[] (id, at, text, tts, subs), pronounce, emphasis, music. JSON estrito após window.PLAN =.

Em video.html, substitua o conteúdo de demonstração do template pelas telas da funcionalidade: build (elementos repetitivos), setup (medições E.measureAt + E.rect, chaves de câmera para ambos os formatos, cursor, cliques), scene(t). Eventos na tela — nas palavras das falas (E.sync('p3:palavra', fallback)). Telas escuras e modais — via E.dim() e em #app2. Receitas de cena — references/scenes.md, regras de movimento e câmera — references/motion.md. Pré-visualização com controle deslizante: video.html?preview=1 via python3 -m http.server da pasta do vídeo.

7. Verificação por quadros

python3 <skill>/scripts/verify_scene.py video.html --fmt both
python3 <skill>/scripts/render.py video.html stills --fmt both --times 1,6,9,12,15,19,23,27,31,34 --sheet

Abra build/stills/sheet_h.jpg e sheet_v.jpg: câmera focada na ação; etiquetas sob seus fragmentos; texto sem quebra ou corte; destaque apenas nos lugares corretos; na transição 'processamento → resultado', sem flash branco; em 9:16, texto grande, legendas acima do painel inferior. Corrija até os quadros-chave estarem limpos. Antes do primeiro render — references/pitfalls.md.

8. Locução

python3 <skill>/scripts/vo_pack.py plan.js            # --model 3.8 para Gemini 3.8 Flash TTS, --voice female

Forneça out/voiceover/tts_text.txt e tts_prompt.txt em dois blocos de código separados (texto no campo de texto, prompt no campo de estilo), voz (para voz masculina portuguesa — sugerir Schedar primeiro), solicitação para gravar em uma única tomada completa e tabela de timing.md. Também aceita gravação própria do usuário com o mesmo texto. Regras — references/voiceover.md.

9. Locução recebida → sincronização

python3 <skill>/scripts/align_vo.py plan.js voice.wav        # build/vo_aligned.wav, cues.js, out/subtitles.srt, relatório

Leia build/align_report.md: palavras 'verificar auditivamente' informe ao usuário com timecode; falas deslocadas é melhor corrigir em plan.js. O script para se a fala ultrapassar o quadro final (hold).

Aceleração — apenas sugestão. Se o vídeo 'arrastar', sugira retime.py (leitura +4.5 %, pausas mais curtas, um mapa de tempo para vídeo, voz, música e legendas). Execute a versão principal apenas com consentimento.

10. Música, mixagem, render, montagem

python3 <skill>/scripts/music.py plan.js --out build/music.wav                         # síntese de rascunho baseada na seção music
python3 <skill>/scripts/prepare_music.py plan.js track.mp3 --end-align --out build/music.wav   # ou faixa do usuário
python3 <skill>/scripts/mix.py build/music.wav build/vo_aligned.wav --out build/mix.wav
python3 <skill>/scripts/render.py video.html video --fmt h --out build/h_subs.mp4
python3 <skill>/scripts/render.py video.html video --fmt h --qs subs=0 --out build/h.mp4
python3 <skill>/scripts/assemble.py --video build/h.mp4 --audio build/mix.wav --out out/<slug>_16x9.mp4
python3 <skill>/scripts/assemble.py --video build/h_subs.mp4 --audio build/mix.wav --out out/<slug>_16x9_subs.mp4
#   … e o mesmo para --fmt v (_9x16, _9x16_subs), se vertical no briefing
python3 <skill>/scripts/verify_media.py plan.js out/*.mp4 --sheet

Render ≈ 2–5 minutos por minuto de vídeo por formato — execute em segundo plano ou em partes (--start/--end, montagem assemble.py --video part1 part2 …). Música sintetizada é temporária; para vídeo público, sugira uma faixa licenciada. Detalhes — references/audio.md. Sob solicitação — export_web.py (MP4 limpo, WebVTT, poster, quadro final) para player no site; não publique sem decisão separada do usuário.

O que entregar ao usuário

• Arquivos nos formatos escolhidos: <slug>_16x9.mp4, <slug>_16x9_subs.mp4 (+ _9x16), SRT, pacote de locução (antes da gravação de voz), folha de contato. Caminhos dos arquivos; se houver ferramenta de envio de arquivos, envie.
• Resumo: duração, o que está em cada cena; o que foi inventado e precisa de conferência com o produto; que a música é temporária; o que não foi verificado (por exemplo, não ouvido auditivamente).
• Atualize o README da pasta do vídeo: status, decisões do briefing, como remontar.
• Sem repetir o processo e sem propaganda de 'IA revolucionária'.

Arquivos do skill

templates/engine.js	motor de quadros: câmera, cursor, cliques, escurecimento e camada superior #app2, legendas (subs=0), mapa de tempo tmap.js, pré-visualização preview=1, medições, markup/grad/plural
templates/base.css	componentes baseados em tokens da marca: cabeçalho, campo com transbordo, etiquetas, dicas, processamento escuro, resultado, popovers, chat, avaliação, final
templates/brand/	perfil de marca neutro: brand.css, Manrope (OFL), logotipo placeholder
templates/processing.js	animação neutra de processamento (anéis, brilho de destaque, cartões voando)
templates/starter.html, plan.js	demo funcional de ≈36 segundos 'Busca Inteligente' no produto fictício Demo: gancho → entrada com etiquetas → sugestões → processamento → resultado com 'por quê' → salvar → avaliação → final
scripts/	check_env, new_project, verify_scene, render, vo_pack, align_vo, retime, music, prepare_music, mix, assemble, verify_media, export_web
references/	brief.md · brand.md · storyboard.md · scenes.md · motion.md · engine.md · voiceover.md · audio.md · pitfalls.md