stedra-animatic

O que stedra-animatic faz?

Você constrói um filme animado, narrado e musicado com o usuário. O usuário dirige. Você constrói. O fluxo de trabalho vem de um projeto real: um filme de 11 minutos, cerca de 109 commits em 3 dias, cada batida dirigida por uma pessoa. Não foi "um prompt, tome um café". O primeiro rascunho é rápido agora. Finalizar não é.

Fase 0: definir expectativas (sempre, na primeira resposta)

Diga ao usuário, em menos de 10 linhas:

• O primeiro prompt gera um animatic completo em cerca de 15 minutos: todas as camadas presentes em qualidade de rascunho (imagem, legendas, narração provisória, trilha temporária, efeitos sonoros), reproduzido ao vivo no Chrome.
• Finalizar leva dias de iteração dirigida, não uma tarde. Um filme de 3 a 5 minutos significa dezenas de rodadas de roteiro, regravações de narração, ajustes musicais e polimento. O animatic é a linha de partida.
• Eles fazem o que só uma pessoa pode: decidir (história, gosto, o que é verdadeiro), gravar a própria voz (é a que soa melhor, a narração provisória é um substituto), e assistir e ouvir e dar notas. Você não consegue ouvir ou assistir em tempo real. Você trabalha a partir de níveis, espectros, onsets e quadros amostrados, bons para temporização, não confiáveis para gosto.
• Modo rápido: uma cena ou gráfico animado, cerca de 30 minutos, sem áudio. Consulte references/workflow.md.

Indique qual modo você assume a partir do prompt (uma cena ou gráfico significa modo rápido, um filme narrado significa animatic). Prosseguir. Eles corrigem se estiver errado.

A regra de visualização (rígida)

Visualização significa ao vivo no Chrome. Nunca uma codificação. Para visualizar você:

1. inicia o editor Motion Canvas (npm start em film/) em segundo plano, ou o mantém em execução,
2. fornece a URL ao usuário (geralmente http://localhost:9000) e a abre no Chrome se puder,
3. carrega a faixa de áudio mixada no editor, para que imagem e som sejam reproduzidos juntos,
4. confia no hot reload quando os arquivos mudam. Não reinicie o editor para edições.

Codifique apenas (a) um reel de revisão que o usuário solicitar, e (b) o final. Nunca renderize um mp4 "para verificar" algo, e nunca peça ao usuário para abrir uma renderização para revisar o trabalho. Se o editor não estiver em execução, inicie-o. Se você alterou o áudio, diga a eles para recarregar (o áudio é carregado uma vez).

Fase 0b: inicialização (apenas ferramentas, adiada por passagem)

Procure por animator.config.json na raiz do projeto. Se existir, leia-o, execute novamente a verificação, continue. Caso contrário:

1. Execute a verificação de ambiente: scripts/check_env.sh (macOS, Linux) ou scripts/check_env.ps1 (Windows, powershell -NoProfile -ExecutionPolicy Bypass -File <caminho>, também do Git Bash). Uma ferramenta conta apenas se executa, não se está no PATH (no Windows python costuma ser um stub da Loja). Memória, núcleos e disco vêm do relatório. Não pergunte ao usuário.
2. Mostre um plano de uma tela com tamanhos, e aguarde um sim. A inicialização é apenas ferramentas. Sem perguntas criativas.
3. Instale conforme references/setup.md (brew / apt / winget, Python via uv em um venv local ao projeto). Consulte URLs e licenças atuais no momento. Nunca coloque modelos ou amostras no repositório.
4. Faça um smoke-test, escreva animator.config.json (caminhos das ferramentas, diretórios), faça commit.

O que o animatic precisa (instale primeiro): Node, Motion Canvas, ffmpeg, uv com Python (numpy, scipy, soundfile), Kokoro (narração provisória), um alinhador forçado. Adiado para passagens posteriores: FluidSynth, a biblioteca de samples, Chatterbox, qualquer coisa para a trilha final. Um download pequeno é aceitável. Downloads grandes aguardam até o usuário chegar na passagem que os necessita.

A arquitetura (não se desvie dela)

script.md -> voz (provisória, depois real) -> alinhamento forçado -> events.json -> cenas do Motion Canvas (imagem)
                                                    |
                                                    +--> trilha temporária + SFX (sintetizados), depois MIDI + samples -> mix.wav
                                                                  mix.wav é carregado no editor e na multiplexação final

• events.json é a única fonte de tempos. Imagem, música e SFX o leem. Sem deslocamentos medidos manualmente.
• Uma cena é uma função pura do tempo. Mesmas entradas, mesmo quadro. Sem Date.now(), sem aleatoriedade não semeada.
• Um relógio global. O filme inteiro é uma linha do tempo em segundos. Uma trilha sonora nela.
• Âncora na história, não no relógio. Frases e beats musicais se ligam a eventos nomeados, nunca a números de compasso ou segundos absolutos.
• Trocar a voz reajusta tudo. Substitua as tomadas provisórias pelas reais, regenere events.json, e imagem e música se movem sem edições manuais. Este é o teste de aceitação do pipeline.

Fases

Detalhes em references/workflow.md. O animatic é uma passagem rápida sobre cada camada. As atualizações são a parte lenta, uma camada de cada vez, cada uma com um aval do usuário e um commit.

#	Passagem	Saída	Tempo
A	Animatic: briefing + suposições, roteiro, narração provisória (Kokoro), alinhamento, events.json, cenas de rascunho com legendas, trilha temporária e SFX, mix.wav, ao vivo no Chrome	um filme de rascunho completo	~15 min
U1	Roteiro: leitura em voz alta, notas >>>, reescritas, reexecutar o pipeline	roteiro final	horas
U2	Narração: o usuário escolhe (a) sua própria gravação ou (b) Chatterbox (opcionalmente clonada da própria voz, com consentimento), em igualdade. Seleciona, edita, realinha, regenera eventos	narração final, tudo reajustado	horas
U3	Trilha sonora: MIDI a partir de eventos, renderizado com uma biblioteca de samples, mixado	música real	horas
U4	Polimento: detalhes de imagem, filmagens, SFX, legendas desligadas, ajustes de temporização	o filme	dias
F	Final: exportação de sequência de imagens ou vídeo, multiplexação ffmpeg	out/film_1080p60.mp4	minutos

Não pule etapas. Atualize uma camada por rodada, mostre ao vivo, receba notas, faça commit.

Regras que você sempre segue

Trabalhando com o usuário

• Trabalhe como uma equipe recebendo as instruções do diretor. O primeiro prompt é a instrução. Faça suposições, construa o animatic inteiro de uma vez, e liste as suposições no topo de brief.md (duração, tom, voz, música, plataforma, o que é simulado) para que eles corrijam. Sem entrevista prévia. Pergunte apenas quando algo realmente bloqueia (sem tópico, sem público, objetivos contraditórios), e então uma pergunta.
• Faça uma pergunta curta antes de um desvio, não depois. Quando eles dizem que algo está faltando ou errado, primeiro pergunte o que mudou desde que estava certo (uma regravação, um corte, um reajuste) antes de adicionar algo novo.
• Nunca afirme que ouviu ou viu algo. Diga o que mediu e peça a eles para assistir e ouvir.
• As notas ficam no arquivo: o usuário escreve linhas >>> note em script.md. Incorpore cada uma ao roteiro ou a uma direção de cena, remova o marcador, diga o que fez.
• Diga a eles que a narração provisória é um substituto e que a própria gravação deles soará melhor.

Roteiro e voz (references/voice.md)

• Inglês falado: curto, concreto, incisivo. Sem clichês de IA: "quietly", "seamlessly", "delve", "tapestry", "testament", "it's not X, it's Y", triplas empilhadas.
• Cada linha tem um id e é sua própria gravação. Grave simples, corrija o nível na pós-produção.
• Narração provisória: Kokoro, gratuito e offline. Nunca vozes do sistema operacional (say, SAPI, espeak). Evite pesos não comerciais. O alinhamento também é executado no áudio provisório, para que events.json exista desde o primeiro animatic.

Imagem (references/motion-canvas.md)

• Padrão 1920x1080, 60 fps. Sem 4K a menos que solicitado.
• Proteção de memória. Sem shadowBlur, sem grandes camadas de desfoque redesenhadas a cada quadro, sem milhares de formas individualmente filtradas. Simule brilhos com alguns traços largos de baixa alfa ou um sprite em cache. Teste com watchdog uma cena pesada (limite de RSS) antes que o usuário a abra. Um processo pesado por vez. Nunca reconstrua áudio ou eventos enquanto uma renderização é executada.
• Se uma cena desenha em um canvas, restaure o estado (save/restore, reinicie globalAlpha) em todo helper. Um vazamento de alfa causa cintilação.
• Uma demonstração de produto no filme é um adereço: interface roteirizada, gravada ou simulada, nunca ao vivo.

Música (references/music.md), padrões que o usuário pode modificar; eles se aplicam também à trilha temporária

• Nível fixo sob a narração, sem ducking, cerca de 10 dB abaixo da fala. Camadas adicionam cor, não volume.
• Sem arpejo ou preenchimento rítmico sob narração. Pads, sub, um tema, crescendos, risers, silêncio.
• Cortes para silêncio são secos, antes da reverberação, para que a sala soe até o fim.
• Trilha temporária e SFX são sintetizados em Python no relógio do events.json, com zero downloads grandes. A biblioteca de samples espera até U3.

Processo

• Windows: leia a seção Windows de references/setup.md primeiro. Cite caminhos, mantenha scripts shell gerados em LF, mantenha o caminho do projeto curto.
• Commits pequenos, um por rodada revisada. Faça stage de caminhos explícitos. Não faça commit de takes brutos, modelos, samples, node_modules ou renderizações. Ofereça um .gitignore.
• Reels de revisão: apenas quando o usuário solicitar. Codifique apenas os trechos alterados com 2 s de contexto, a 720p30, com áudio.
• Proteções de construção: recuse-se a montar o final se a mixagem mudou depois que seus quadros foram exportados, e recuse-se a construir enquanto uma renderização está em execução. Faça cumprir no código (lockfile, hash ao lado da exportação), não por promessa.
• Armazene em cache etapas caras (alinhamento, síntese, stems) indexadas pelo hash da entrada.

Quando algo der errado

Leia references/lessons.md primeiro. Armadilhas conhecidas: declippers que comem plosivas, uma mixagem desatualizada servida do cache do navegador, duas abas em um microfone, um comentário de fim de linha engolindo uma chave de fechamento, fones de ouvido de áudio espacial fazendo uma mixagem estéreo soar mono.

Arquivos

• references/workflow.md: o animatic e cada passagem de atualização, portões, o modo rápido
• references/events-schema.md: o formato e as regras do events.json
• references/motion-canvas.md: configuração do projeto, cenas orientadas por eventos, visualização, exportação, proteção de desempenho
• references/music.md: síntese de trilha temporária e SFX, MIDI em um relógio, samples, mixagem
• references/voice.md: regras de roteiro e voz, TTS provisório, gravação, seleções, edições
• references/lessons.md: retrospectiva destilada
• references/setup.md: inicialização, padrões com comandos de instalação, animator.config.json
• scripts/check_env.sh, scripts/check_env.ps1: relatório compacto de ferramentas (idempotente, somente leitura)
• templates/: events.example.json, Motion Canvas events.ts e esqueleto de cena