makerjackie/short-film

Curta Programático (short-film)

Transforme um tema em um curta-metragem: aproximadamente 30 segundos (ajustável entre 15 e 90 segundos), vertical 1080×1920, 24 fps; com tomadas em fundo de papel (paper plate) em estilo de traço à tinta e tomadas em fundo azul de blueprint (blueprint plate) intercaladas; cada evento cai em uma grade de batidas (bpm → batida → frame); cada pixel e cada amostra de áudio são calculados em JavaScript puro de navegador. A entrega é dist/<slug>.html (player autossuficiente), exports/<slug>.mp4 (com versões para celular e preview), e um pacote de publicação: imagem de capa para TikTok (captura de tela HTML), título e descrição recomendados.

Este skill encapsula uma pipeline já verificada. Ele vem com três componentes:

• foundation/ — O motor e as ferramentas, copiados para o novo projeto: src/core.js, src/lib.js, src/player.js, src/music.js (motor + uma trilha sonora de exemplo), e tools/ (build, verificação, captura de tela, renderização, geração de stubs, análise de áudio, pacote de publicação, fixtures de teste). Tudo é orquestrado por src/timeline.js, então cada curta não precisa modificar o código das ferramentas.
• templates/ — Quatro documentos de planejamento usados como ponto de partida para cada curta.
• reference/ — Consulte quando necessário: tipos de tomada, anatomia de cena, música, predefinições de plataforma; veja primeiro as três imagens de referência.

Veja primeiro reference/: contact-sheet.jpg é a folha de contato do curta de exemplo (examples/llm-evolution, um estilo "ATLAS" personalizado) — a densidade de detalhes e o acabamento são o padrão a ser seguido; paper-frame.jpg e blueprint-frame.jpg são um quadro completo de cada um dos dois fundos do estilo padrão existente (renderizados por tools/fixtures), servindo como alvo visual para curtas que usam o estilo padrão.

Veja o exemplo completo em examples/llm-evolution/: um curta de 24 tomadas que vai do neurônio aos grandes modelos de IA, incluindo documentos de planejamento, código-fonte, dist/ e pacote de publicação. Observe que ele é um produto de estilo personalizado (desviou do estilo padrão papel×blueprint com base em análise de referência), demonstrando toda a capacidade deste skill. Quando um modelo deixar você inseguro sobre a aparência de um documento preenchido, vá lá e leia o equivalente.

O Portão (The gate)

node tools/check.cjs é o portão: seis verificações (varredura de mídia, determinismo, varredura de código-fonte, linha do tempo, desenho, tempo de quadro), e a saída 0 significa aprovação. A partir da fase de stubs, enquanto o portão estiver vermelho, nenhuma etapa está concluída. Para cenários reais, ele leva menos de um minuto — deixe-o rodar até o fim.

Pipeline

0. Briefing (Brief)

Faça apenas uma rodada de perguntas: qual é o tema, o que o curta deve conter sobre ele, duração (padrão 30 segundos), e para qual plataforma será publicado (determina proporção de tela e área segura, veja reference/platform-presets.md). O resto você inventa, explicando o que inventou.

Critério de conclusão: o tema foi escrito em uma frase já revisada pelo usuário, e duração e plataforma estão definidas.

1. Configuração (Setup)

Crie a pasta do projeto com o slug do curta e copie foundation/ para dentro. Rode npm install em tools/ (Playwright; se faltar navegador, execute npx playwright install chromium). Confirme que ffmpeg está no PATH, ou defina o caminho do binário na variável FFMPEG. Copie os modelos para docs/ e escreva o tema em docs/CONTRACT.md na seção Goal.

Critério de conclusão: node tools/smoke.cjs passa, node tools/check.cjs --fixtures está verde, e node tools/render.cjs --fixtures --scale 0.5 produz exports/fixtures.mp4 com áudio. Este mini-curta fixtures prova que a ferramenta está funcionando antes de investir esforço no planejamento.

2. Pesquisa (Research)

Liste os estágios da história do tema, faça uma pesquisa na web para cada pergunta em aberto, e salve duas a quatro fontes completas e autoritativas em .tmp/research/. A pesquisa só chega a dois lugares a jusante: as referências temáticas na bíblia de arte e a seção Subject de cada tomada.

Critério de conclusão: cada estágio da história pode ser rastreado até uma fonte capturada.

3. Bíblia de Arte (Art bible)

Preencha docs/art-bible.md seguindo o modelo. As seções 1–9 são do estilo existente — já definidas; a seção 2.2 (paleta do tema, cada cor com nome hex específico e espelhada no bloco de anotações de src/lib.js), a tonalidade de identidade da seção 2.3 e a seção 10 (referência do tema) são reescritas para cada curta. A seção 10 termina com "erros a evitar", cada um acompanhado da forma correta de desenhar.

Se o usuário quiser um visual diferente do estilo existente, primeiro faça uma análise de referência seguindo o método de templates/reference-analysis.md, depois atualize as seções 1–9 de acordo.

Critério de conclusão: cada elemento a ser desenhado no storyboard tem regra de desenho e nome de paleta; src/lib.js está consistente com a seção 2.2; a lista de erros existe; e você já viu node tools/snap.cjs --fixtures --shot palette --samples 5 --sheet.

4. Storyboard (Storyboard)

Leia reference/shot-types.md e preencha docs/storyboard.md seguindo o modelo: logline; números (primeiro escolha bpm, batida = 60/bpm segundos, duração em compassos inteiros); tabela de resumo; atos mapeados a compassos; uma tabela de geometria compartilhada para cada forma que sobrevive a um corte de correspondência (match cut); e então uma entrada por tomada — 1 a 3 segundos, bordas na grade de batidas, alternando entre os dois fundos — com todas as oito subseções, e dicas de som com timestamps na grade.

Critério de conclusão: as tomadas preenchem exatamente [0, duração] sem lacunas; cada tomada tem todas as oito subseções; cada forma de corte de correspondência tem geometria compartilhada na tabela; o documento passa por uma autoverificação com olhar de crítico (números no texto consistentes com as tabelas, conteúdo obrigatório dentro da área segura — incluindo conteúdo aritmético). Erros de storyboard se propagam para cada cena; este é o momento mais barato para pegá-los.

5. Linha do Tempo (Timeline)

Escreva src/timeline.js baseado no storyboard (formato conforme o modelo do storyboard): título, bpm, duração, array shots (id, file, start, end, mode, title, transitionIn, brief) e uma lista plana de cues coletadas de cada subseção Sound. A fase de stubs testa esta etapa — erros de formato na linha do tempo falham ruidosamente.

6. Fase de Stubs (Stub pass)

node tools/stubgen.cjs gera cenas placeholder para cada tomada. Rode o portão, depois node tools/render.cjs --scale 0.5 --out exports/draft-stubs.mp4 e assista ao rascunho do começo ao fim. É um tiro de orientação: antes de desenhar qualquer cena real, prova que linha do tempo, cenas, portão, renderização e áudio estão todos funcionando.

Critério de conclusão: o portão está verde e o MP4 do rascunho mostra cada tomada em ordem, com cada transição no grid.

7. Cenas (Scenes)

Um agente por arquivo de cena — a propriedade do arquivo é lei (docs/CONTRACT.md). Cada agente de cena lê reference/scene-anatomy.md, sua entrada no storyboard, a bíblia de arte e a geometria compartilhada; então escreve src/scenes/NN-<id>.js, tira uma folha de contato (node tools/snap.cjs --shot <id> --samples 6 --sheet), revisa cada quadro e itera até que esteja de acordo com o briefing. snap --only pode renderizar uma única tomada enquanto os arquivos irmãos estão pela metade, então os agentes de cena podem trabalhar em paralelo.

Tomadas também podem compartilhar um módulo de desenho (layout centralizado, veja docs/CONTRACT.md "Dois layouts de código de cena") — nesse caso, cada src/scenes/NN-*.js é apenas um pequeno wrapper de registro com algumas linhas, e o desenho é centralizado em FILM.art. O exemplo examples/llm-evolution usa este estilo; é mais eficiente quando as tomadas compartilham a mesma geometria e diferem apenas em parâmetros.

Critério de conclusão: a folha de contato de cada tomada foi inspecionada visualmente e considerada conforme o briefing, e o portão está verde.

8. Música (Music)

Escreva src/music.js baseado em reference/music.md: mantenha o motor, substitua a tabela de acordes CH, a automação MIX.ride e toda a função score(), implemente cada cue nos tempos exatos de FILM.TIMELINE.cues, fazendo com que os acentos caiam nas transições.

Critério de conclusão: após node tools/audio/render-audio.cjs, node tools/audio/analyze.cjs .tmp/audio/score.wav --cues mostra que os inícios e as cues coincidem dentro de 10 ms, node tools/audio/peaks.cjs .tmp/audio/score.wav mostra margem abaixo do limite do compressor, e o portão está verde.

9. Rodadas de Crítica (Critic waves)

Primeiro coloque o curta inteiro em uma única folha: node tools/snap.cjs --samples 24 --sheet --scale 0.25. Tomadas que não são legíveis neste tamanho são P1 — corrija na composição, não adicione detalhes.

Depois revise cada tomada com base em quadros renderizados: tire novas folhas de contato e use um subagente crítico para avaliar composição, fidelidade ao storyboard, movimento e densidade. O crítico deve medir proporções chave da geometria no nível do pixel (notas de banda, regra dos terços, aritmética de área segura, posições da geometria compartilhada), e não apenas confiar nos olhos; e deve capturar ambos os lados de cada corte de correspondência para comparação.

Corrija em ondas — P1 primeiro, cada correção referenciando quadros de evidência, mantendo a propriedade do arquivo (restaure o agente dono), e tire novas capturas de tela após cada correção. O diretor revisa cada correção P1 em novos quadros. Teste o determinismo capturando o mesmo quadro em duas ordens diferentes e comparando hashes dos arquivos.

Critério de conclusão: cada correção P1 e P2 foi verificada em novos quadros, e o portão está verde.

10. Entrega (Deliver)

node tools/render.cjs gera o master (crf 16). Depois, a transcodificação:

ffmpeg -i exports/<slug>.mp4 -vf scale=720:1280 -c:v libx264 -crf 23 -preset medium -c:a aac -b:a 128k exports/<slug>-phone.mp4
ffmpeg -i exports/<slug>.mp4 -c:v libx264 -crf 23 -preset medium -c:a copy exports/<slug>-preview.mp4

node tools/build.cjs gera dist/<slug>.html. Assista ao master do começo ao fim com áudio, e abra o player HTML uma vez (clique ou espaço para tocar, setas para avançar quadro a quadro, ?shot=<id> para loop de tomada única).

Escreva exports/<slug>-shots.md: uma linha por tomada, explicando o que ela mostra.

Critério de conclusão: master, transcodificação para celular, arquivo HTML e exports/<slug>-shots.md existem, o portão está verde, e a exibição final não encontrou nada para corrigir.

11. Pacote de Publicação (Publish pack)

Use tools/publish.cjs para gerar a imagem de capa e o esqueleto do texto para publicação:

node tools/publish.cjs                          # Padrão: usa o quadro de hook da primeira tomada como capa
node tools/publish.cjs --at 2.5 --title "De um neurônio a uma máquina de linguagem" --platform tiktok

Ele faz duas coisas:

1. Imagem de capa (captura de tela HTML, padrão 1080×1920): renderiza um quadro do filme no momento --at como visual principal, sobrepõe título/subtítulo/marca, e gera exports/<slug>-cover.png. A página de capa pode usar fontes do sistema e imagens, pois não entra no HTML de entrega, não violando a regra "sem mídia".
2. Esqueleto de texto exports/<slug>-publish.md: candidatos a título, descrição, hashtags, lista de tomadas, duração/proporção/plataforma, etc. Título e descrição são pontos de partida, que você deve refinar na recomendação final seguindo as regras de reference/publish.md.

Critério de conclusão: exports/<slug>-cover.png foi gerado e visto pessoalmente (título dentro da área segura, legível, com gancho); o título e a descrição em exports/<slug>-publish.md foram refinados por você na recomendação final; a plataforma e a proporção correspondem ao briefing da etapa 0.