Plextrang/story-shorts

Story Shorts: qualquer ideia entra, um curta animado sai

Este skill é um motor de cinema mais um fluxo de trabalho. O motor (engine/) renderiza três.js quadro a quadro no Chrome headless: personagens 2D em canvas no estilo boneco de papel em um mundo 3D com sombreamento cartoon e contorno a tinta, movimentos de câmera e dissoluções, uma sobreposição 2D para gráficos explicativos, legendas embutidas e uma mixagem de som baseada em eventos temporizados. Cada filme escreve apenas sua camada de história: quem está nele, onde acontece, os planos, os gráficos e o plano de som. Um novo filme começa a partir do ponto de partida em branco (starter/: dois personagens placeholder, dois lugares, quatro planos). examples/floating-scale/ é um filme finalizado, apenas para referência. Nunca reutilize seus personagens ou história.

Leia estes conforme precisar:

• reference/rules.md: as regras de história e imagem. Leia primeiro.
• reference/story-templates.md: seis formatos de história. Escolha um por filme.
• reference/engine-api.md: como escrever um filme no motor (personagens, poses, mundos, adereços, planos, gráficos, sinais).
• reference/transitions.md: regra 11 na prática (movimentos de câmera, encenação para continuidade, cortes mantidos).
• reference/sound.md: voz, música e efeitos, com Epidemic Sound ou ferramentas gratuitas.
• reference/lessons.md: bugs já encontrados e suas correções. Verifique antes de depurar qualquer coisa.

Antes de começar: faça duas perguntas

1. A ideia. Uma frase é suficiente: "um faroleiro que tem medo do escuro", "a maratona olímpica de 1904", "e se a gravidade caísse pela metade por um dia". Peça se o usuário ainda não deu. Pergunte sobre duração apenas se for relevante para ele (padrão cerca de 60 s).
2. Ferramentas de som. Pergunte: "Você tem Epidemic Sound (com seu conector Claude), ou devo usar as ferramentas gratuitas?"
   • Epidemic Sound (recomendado): narração Epidemic para o narrador e personagens, uma faixa musical Epidemic cortada para a história, efeitos e ambiência Epidemic. Precisa do conector MCP Epidemic Sound no Claude Code.
   • Gratuito: Kokoro TTS para as vozes (scripts/kokoro_voice.py), uma trilha e efeitos sintetizados em código.
   • Não misture os dois em um mesmo filme sem declarar no README do filme.

Depois execute python scripts/check_setup.py e corrija qualquer item marcado como AUSENTE antes de escrever qualquer código do filme.

O fluxo de trabalho (sem necessidade de aprovações, a menos que o usuário as peça)

1. Novo projeto. python scripts/new_film.py <pasta> "Título" copia o motor e o ponto de partida em branco, escreve uma linha do tempo placeholder e instala film/node_modules do zero. Trabalhe apenas dentro dessa pasta.
2. História (docs/STORY.md, script/lines.json).
   • Escolha o modelo de história que se encaixa na ideia (reference/story-templates.md) e diga qual você escolheu e por quê.
   • Escreva o roteiro: uma entrada por fala (id, falante, início, texto). Narração mais algumas falas de personagens; cerca de 150 palavras por minuto de filme.
   • Escreva a lista de planos com uma leitura silenciosa por plano: o que um espectador mudo entende apenas pela imagem.
   • Nomeie os lugares. Uma mudança de lugar é a única razão para uma dissolução; dentro de um lugar a câmera se move.
   • Fatos devem ser verdadeiros, com números reais. Personagens, história e mundo são originais.
3. Elenco (film/src/story/cast.js).
   • Uma chave por personagem (igual ao id do falante). Comece cada um a partir de uma predefinição e sobrescreva cores, proporções e características até que sejam próprios deste filme (reference/engine-api.md, "Characters"). Adicione uma nova aparência em character.js atrás de uma nova flag feat quando a história precisar.
   • Renderize node film/tools/charsheet.mjs e olhe cada folha antes de construir qualquer plano.
4. Mundo e adereços (story/world.js, story/set.js, opcional story/props.js).
   • Construa cada lugar a partir de worldkit.js mais seus próprios marcos. Coloque cada marco em SET. Dê aos adereços heróis os estados que a história precisa.
5. Bloqueie a imagem (story/shots.js, story/overlay.js).
   • Substitua os quatro planos do ponto de partida pelos planos do filme. Marque os tempos a partir da linha do tempo (K.wordAt, K.lineAt), nunca a partir de segundos fixos. Até que a voz exista, python tools/build_timeline.py --placeholder.
   • Encene para continuidade desde o início (regra 11): uma atuação por personagem por lugar, adereços em suas marcas.
   • Explique com diagramas 2D (regra 4). Liste cada ação visível em CUES.
6. Voz.
   • Gere cada fala como seu próprio clipe em audio/vo/raw/<id>.mp3|wav (Epidemic, ou scripts/kokoro_voice.py).
   • python <repo>/scripts/prepare_voice.py (adicione --atempo-off para Kokoro) corta as pontas silenciosas e define o ritmo.
   • python tools/build_timeline.py, python tools/captions.py, depois cd film && node tools/cues.mjs.
   • Nunca corte um clipe em momentos de sussurro. Re-verifique o enquadramento: os marcadores se moveram com a voz real.
7. Revise a imagem antes de qualquer renderização completa:
   • node framecheck.mjs --step 4 deve imprimir "framing OK".
   • node tools/poptest.mjs --out ../render/pop verifica cada borda para pops; bash tools/movesheet.sh verifica movimentos.
   • bash tools/sheet.sh <nome> "<tempos>" faz folhas de contato. Olhe para elas e verifique cada plano contra sua leitura silenciosa. Faça pelo menos duas rodadas completas.
8. Som (audio/sound_plan.json, reference/sound.md).
   • Epidemic: baixe a faixa e os efeitos em audio/epidemic/, preencha music, effects e ambience, depois cd audio/epidemic_mix && python mix_film.py && python autolevel.py && python qc.py && python sync_check.py.
   • Gratuito: preencha synth, depois cd audio/synth && python music.py && python build_fx.py && python mix.py && python cue_presence.py.
   • Metas: −14 LUFS, pico verdadeiro ≤ −1.3 dBTP, voz pelo menos 6 dB clara em cada fala, sem intervalos silenciosos, cada efeito dentro de um quadro.
9. Renderize, monte, entregue.
   • cd film && node render.mjs --from 0 --to <quadros-1> --scale 1.5 --workers 2 --jpg --out ../render/frames.
   • bash tools/assemble.sh escreve out/<Título>.mp4 e out/contact_sheet.jpg, e mede o resultado. Ele se recusa a executar se um worker travado deixou um quadro vazio.
   • Se o earshot estiver instalado: bash audio/tools/es.sh critique out/<Título>.mp4, visando "nível de lançamento".
   • Escreva o README.md do filme: logline, medições, cada corte mantido e por quê, os sons usados e pontos fracos honestos. Nunca afirme que o filme é bom: você não pode assisti-lo ou ouvi-lo em velocidade total. Liste o que o usuário deve verificar visualmente e auditivamente, depois pare e aguarde a revisão.

Não negociáveis (detalhes em reference/rules.md)

• Ele se lê com o som desligado. Mostre o problema antes da solução. Mostre cada fala na tela enquanto é dita.
• Sem metáforas literais; explique com um diagrama 2D claro.
• Adereços se leem de relance. Use planos médios e abertos com figuras inteiras, mantenha a faixa de legenda (62–78 % da altura) limpa, e ninguém é cortado no final.
• Mesmo lugar significa um movimento de câmera, um novo lugar significa uma dissolução, e um corte permanece apenas com uma razão declarada.
• Cada ação visível tem um som audível, e a narração permanece clara durante todo o caminho.
• Apenas personagens, histórias e mundos originais. Nunca copie personagens ou aparência de um programa existente, e nunca reutilize o filme de exemplo.
• Trabalhe apenas dentro da própria pasta do filme. Instale tudo do zero lá; nunca vincule a outro projeto.