jdrurka/explainer-skill

Explainer

Um explicador sem rosto é uma narração sobre um mundo animado contínuo construído em código (um corte transversal, um mecanismo ampliado, uma mão segurando um objeto), com legendas no topo e sem música. A saída é um mp4 1080×1920.

Leia estes antes de escrever:

• script-craft.md: como o roteiro é moldado (gancho, reviravolta, imagine, mecanismo, virada, CTA) e ritmado.
• craft-rules.md: o que faz os visuais parecerem vivos e com profundidade. Uma primeira passagem competente quebra a maioria deles.

A parte difícil é a metáfora visual para cada batida. A segunda mais difícil é manter cada quadro em movimento e iluminado com profundidade. Código é a parte fácil.

Modos

• Único (padrão): ir do conceito ao vídeo final sem parar. Tome as decisões você mesmo e as reporte no final.
• Revisão: se o usuário pedir para revisar ou aprovar, pare duas vezes: após o roteiro, e após o storyboard. Revise a partir das notas deles e continue.

Verificação de configuração (uma vez)

ffmpeg no PATH, remotion/node_modules presente (caso contrário execute npm install em remotion/), e FISH_API_KEY no .env (copie .env.example). Sem a chave, construa tudo com voice --placeholder e diga ao usuário que o passo final é uma reexecução do voice mais uma renderização.

Layout

projects/<conceito>/ (o conceito é um slug, como como-geladeiras-funcionam):

• script.txt, storyboard.md
• composition.tsx (pilha de camadas), timeline.ts (TL), captions.ts, words.ts (gerado), scenes/S01.tsx …
• public/vo.wav, vo/ (take bruto e alinhamento), out/ (renderizações, stills)

A biblioteca principal é remotion/src/core (as cenas a importam como ../../../remotion/src/core):

• makeTimeline → TL.at("frase"), TL.end("frase")
• Captions, Drift, Bokeh, Vignette, handheld, Backdrop, Dust, Footnote
• Camera (WorldSvg, camAt, toScreen), Label, Sparks, Snow / Rain
• easings, ramp, keys, rand, fontes SANS / MONO

Ferramentas: python3 bin/explainer.py … (execute -h)

Comando	Faz
new <c>	Gera o scaffold do projeto
voice <c> [--voice-id ID] [--speed 1.0]	Take Fish Audio com timestamps das palavras → words.ts, mais public/vo.wav a −14 LUFS. Imprime o wpm
voice <c> --placeholder [--wpm 200]	Áudio silencioso e temporizações sintéticas, sem chamada de API
stills <c> <seg>…	Quadros naqueles segundos → uma folha de contato em out/. Olhe para ela
studio <c>	Preview ao vivo no Remotion Studio (para o usuário)
render <c> [--blur]	mp4 a 60 fps em out/. --blur renderiza a 240 fps e faz média para 60 para motion blur (~4× mais lento)
qa <c>	Portão de vivacidade: quadros congelados < 10%, nenhuma execução congelada ≥ 0,3 s. Sai com 1 em FALHA e nomeia cada trecho congelado

Fluxo de trabalho

1. Roteiro. Execute new <c>.

   • Se o usuário forneceu um roteiro, use-o palavra por palavra (corrija apenas numerais e símbolos para palavras).
   • Caso contrário, escreva script.txt a partir de script-craft.md: formato de objeto cotidiano por padrão (270–320 palavras), formato de sistema para produtos e redes. Execute sua lista de verificação.
   • Modo de revisão: pare para aprovação.

2. Voz. Execute voice <c>, depois verifique o wpm impresso (mire em 190–215; reexecute com o --speed sugerido se estiver fora).

   • A voz é --voice-id, senão FISH_VOICE_ID, senão o padrão da Fish. O id de uma voz clonada funciona da mesma forma.
   • O modelo é --model, senão FISH_MODEL, senão s2.1-pro.
   • Autorize contra words.ts, não script.txt. A voz soletra números, e TL.at() e as frases de legenda devem corresponder às palavras faladas.

3. Storyboard (storyboard.md). Preencha a seção Mundo primeiro, depois uma linha por batida. Para inventar a metáfora de uma batida, pergunte o que o espectador veria se pudesse:

   • Ampliar: uma vista em corte transversal ou explodida.
   • Raio-X: dentro do objeto.
   • Câmera lenta: uma onda viajando, uma peça comutando.
   • Medir: um indicador subindo ou descendo.

   O cenário "imagine" se torna o mundo de excursão, e cada batida de mecanismo retorna ao diagrama principal. Execute as verificações do storyboard.

   • Modo de revisão: pare para aprovação.

4. Construir. Escreva um arquivo de cena por take do storyboard em scenes/ e adicione cada um a composition.tsx.

   • Cada cena é uma função pura de t que retorna null fora de sua janela.
   • Temporização: cada evento está atrelado a TL.at("palavras exatas"). Nunca escreva segundos brutos.
   • Continuidade: batidas que compartilham um diagrama vivem em UMA cena com UM caminho de câmera (A4).
   • Movimentos: cada cena entra movendo-se, sobrepondo a saída da cena anterior (A2).
   • Prefixe ids SVG por cena.

5. Iterar. Execute stills nas palavras-chave de cada take e compare-as com as regras de ofício A e B. Depois execute render e qa. Corrija cada trecho CONGELADO em seu próprio take dando a ele um portador de movimento (A1b). Escreva as frases de captions.ts manualmente: um substantivo-chave destacado (âmbar, surge quando falado) por frase.

6. Entregar. A render final deve passar no qa (use --blur se o usuário quiser o máximo de polimento). Dê ao usuário:

   • o caminho do mp4
   • o roteiro
   • um resumo de uma linha por batida do storyboard
   • qualquer voz placeholder que ainda precise de um take real

Bandeiras vermelhas: pare e corrija

Pensamento	Regra
"Um novo cenário para esta batida mantém a coisa fresca"	C1: um diagrama principal mais 1–2 mundos de excursão. Conte-os
"Fique completamente parado no payoff para causar suspense"	A1c: pare o sujeito, mantenha a câmera e o ambiente em movimento
"Adicione uma base musical, granulação ou um drop no payoff"	D, B8: apenas voz, sem granulação; profundidade vem da iluminação
"Fade in" / "crossfade para a próxima cena"	A2: entre, saia e faça a transição movendo-se
"O drift global o manterá vivo"	A1b: cada take precisa de um movimentador de médio porte a 10–60 px/s
"Corte para uma câmera mais próxima para esta batida" (mesmo diagrama)	A4: um mundo, uma câmera; passe os keyframes
"Iluminação uniforme está bem, é um diagrama"	B1: queda na escuridão, luz de contorno, vinheta
"Pinte tudo de uma cor quando ativar"	B4: propague a partir da causa, com uma frente e fluxo
"Um retângulo é suficiente para o objeto"	B2: uma passagem de anatomia; construa o que um pull-out revelará
"Parece bom para mim, pule o qa"	E: qa deve PASSAR; olhos não percebem congelamentos