spiritual-dev/explainer-short

O que explainer-short faz?

Crie um curto vídeo explicativo vertical: apresentador na metade inferior, motion graphics na metade superior e grandes chips de legenda no meio. Uma ideia por clipe. Tokens de tema controlam cor, tipo, borda arredondada e movimento, de modo que o mesmo roteiro possa parecer acolhedor, monocromático, de alto contraste ou lúdico.

Quando usar

• Um clipe de ensino ou explicação de produto vertical de 8 a 30 segundos
• Um pipeline HTML/Canvas reutilizável que exporta MP4
• Temas visuais intercambiáveis sem reescrever o código das cenas

Layout

+---------------------------+
|   motion / cards (1080)   |
|                           |
|---------------------------|  <- chip de legenda na junção
|   apresentador crop (960) |
|                           |
+---------------------------+
         1080 x 1920

Sistema de temas

Os temas ficam em template/themes/*.json (e sample/themes/ para a demonstração). O tema ativo é theme.json na pasta do projeto.

bash template/scripts/use-theme.sh warm          # ou mono | high-contrast | playful
# ou a partir de um projeto copiado:
bash scripts/use-theme.sh mono

Tokens (variáveis CSS após loadTheme):

Token	Função
--ink --mute	Texto
--bg --bg-hi --bg-lo	Fundo da cena
--surface --surface-2	Cartões
--accent --accent-2 --accent-3	Ênfase
--chip-bg --chip-fg	Chip de legenda
--radius-card --radius-chip --chip-size	Forma
--headline-weight	Peso do título
--font-sans --font-mono	Tipo (OFL woff2 em fonts/)

Predefinições: warm (padrão), mono, high-contrast, playful.

Edite um arquivo JSON, execute use-theme.sh novamente e recarregue. Sem etapa de build para o tema em si.

Troca de fonte

1. Coloque um woff2 com licença aberta em fonts/ e mantenha o arquivo de licença ao lado.
2. Defina fonts.sans / fonts.sans_file (e mono) no JSON do tema.
3. Aponte @font-face em index.html para o novo arquivo se o nome da família mudar.
4. Renderize novamente um quadro intermediário e confirme.

Padrões fornecidos: Inter + JetBrains Mono (SIL OFL). Os textos de licença estão em fonts/.

Início rápido (demonstração de tema, sem captura de apresentador)

npm install
node scripts/render_sample.mjs warm
node scripts/render_sample.mjs mono
# saída: sample/out/<preset>/<preset>.mp4 + quadros estáticos

Requer: Node 18+, Chrome ou Chromium do sistema, ffmpeg.

Pipeline completo do projeto (autocontido)

1. Copie template/ para uma nova pasta de projeto (ou trabalhe dentro de sample/).
2. Escreva cenas em main.js que chamem window.render(t) e usem variáveis CSS do tema.
3. Opcional: cabeça falante: coloque uma gravação, preencha src/edit.json, execute python3 src/edit.py (precisa de numpy + soundfile), depois python3 src/captions.py.
4. A partir da raiz da skill (após npm install):

PRESET=warm bash template/build.sh
# ou, para um projeto copiado:
SKILL_ROOT=/caminho/para/explainer-short PRESET=mono bash build.sh
# ou chame o renderizador diretamente:
node scripts/render.mjs --dir caminho/para/projeto --preset warm --out caminho/para/projeto/out/video.mp4

5. Se você tiver out/voice.wav, python3 mix.py normaliza a loudness para aproximadamente -14 LUFS / -1 dBTP e build.sh multiplexa.

template/scripts/render.mjs também é copiado ao lado do template, para que um projeto possa manter uma cópia local.

Regras de design

1. Uma ideia. Um objeto, uma promessa, concluída antes do fim.
2. Legível à distância de um braço. Tipo grande, alto contraste, poucas palavras na tela.
3. Os chips de legenda são a voz. Mantenha as dicas curtas; congele brevemente na última palavra.
4. Tematize, não codifique. Cores, bordas arredondadas e tamanho do chip vêm dos tokens.
5. Padrão de gosto neutro. "Warm" é o padrão; a pessoa escolhe uma predefinição.

Revisão antes do envio

Pontue cada eixo de 0 a 3. Envie somente se a média for pelo menos 2,3. O revisor independente mede o arquivo principal.

Eixo	O que procurar
Congelamento	Última legenda mantém ~0,3-0,5s; sem corte no meio da palavra
Loudness	Aproximadamente -14 LUFS integrados (medir com ffmpeg loudnorm)
Pico verdadeiro	<= -1 dBTP
Capa	Quadro final ou thumbnailOffset é um cartão de título claro
Tema	Tokens aplicados; nenhuma cor de marca codificada restante
Clareza	Um estranho entende o ponto sem áudio

Rubrica completa: references/review-rubric.md. Zonas seguras: references/cover.md.

Arquivos

Caminho	Função
package.json	Declara playwright-core
template/	Projeto inicial (HTML, tema, fontes, build.sh)
template/themes/	JSON de predefinições
template/theme.js	loadTheme() -> variáveis CSS em :root
sample/	Demonstração de tema autocontida de 12s
scripts/render.mjs	Renderização de quadros sem cabeça + multiplexação ffmpeg
scripts/render_sample.mjs	Invólucro de conveniência para predefinições de exemplo
references/	Estrutura, temas, rubrica de revisão, capa, finalização
docs/	Pré-visualizações de execuções verificadas

Lista de verificação do agente

• npm install concluído na raiz da skill
• Predefinição de tema escolhida (ou padrão warm)
• theme.json corresponde à predefinição
• Cenas usam variáveis CSS, não cores de marca codificadas
• Exemplo ou build completo produz MP4
• ffprobe confirma 1080x1920 e duração esperada
• Quadro intermediário parece adequado à marca para a predefinição
• Loudness ~ -14 LUFS e pico verdadeiro <= -1 dBTP quando há áudio
• Média da rubrica de revisão >= 2,3
• Nenhum resquício de marca pessoal ou de terceiros no projeto