toon-reel

Toon reel

you are directing and building a short animated story with the toon-reel-engine. Everything is Python: characters, sets, lights and cameras are code, and every frame is a pure function of time T. There is no timeline editor and no keyframe UI. You write data (keys, shot tables) and then you look at frames.

Layout of the engine (keep it: the relative imports depend on it):

tools/toon/            the engine: toon.py (renderer), rig.py (characters), anim.py (timing), cast/ props/ sets/ (kit)
tools/                 sound.py (stems from cues), mix_check.py (voice clarity), finish.py (-14 LUFS export),
                       thumb.py (cover), find_phrases.py (phrase times in a narration take)
episodes/starter/toon  THE TEMPLATE: "The Lamp", 12.5 s, four shots, one room, one person. Copy this to begin.
episodes/window/toon   THE FULL EXAMPLE: "The Man at the Window", 50 s, 13 shots, two worlds and a twist.
episodes/jeff, episodes/smilingman   support modules the full example and the kit import (not runnable episodes)

Comandos. python abaixo significa o interpretador que tem requirements.txt instalado (py no Windows). Os scripts próprios de um episódio (reel.py, build_tl.py, finalize.py) são executados a partir da pasta do episódio episodes/<nome>/toon. As ferramentas são executadas a partir da raiz do projeto: python tools/sound.py episodes/<nome>/toon.

Primeiro: encontrar ou configurar o motor

Trabalhe na própria pasta de projeto da pessoa, nunca dentro da pasta de instalação do plugin (ela é substituída na atualização).

1. Se a pasta de trabalho já tiver tools/toon/toon.py, use-a.
2. Caso contrário, o motor acompanha esta habilidade. Sua raiz fica duas pastas acima do diretório base desta habilidade (<dir da habilidade>/../..: contém tools/, episodes/, requirements.txt e .gitignore). Copie esses quatro itens para a pasta de trabalho, mantendo o layout, e informe a pessoa que você fez isso. Se a pasta não tiver tools/ (a habilidade foi copiada sozinha), clone https://github.com/wlr2/toon-reel-engine.
3. pip install -r requirements.txt, e verifique se ffmpeg -version funciona (5.1 ou superior). As legendas precisam de Arial Black, ou TOON_FONT definido para um .ttf sans serif pesado.
4. Prove a configuração antes de construir qualquer coisa, a partir de episodes/starter/toon: python build_tl.py, depois python reel.py --frame 5.0 deve escrever review/_f5.00.png.

A ordem é fixa

script -> timeline -> cast sheets + set frame -> blocking -> checks (2 rounds) -> preview -> master -> sound -> finish -> post.

Uma renderização master nunca começa antes que as verificações tenham passado e sido registradas. Mostre à pessoa a ficha do personagem e um quadro do cenário antes de animar, e uma ficha de keyframes rotulada antes do preview em resolução total. Pergunte antes de gastar dinheiro com qualquer coisa (TTS pago, SFX pago, renders em nuvem).

1. Roteiro (references/script.md)

O método de dez etapas: abrir na contradição mais específica, uma pergunta principal, uma cadeia de consequências, uma mudança a cada poucos segundos, escrito para fala e animação, um meio em movimento, um fim merecido com a frase de assinatura por último, enquadramento honesto ("UMA HISTÓRIA DE TERROR DA INTERNET" para creepypasta), uma tabela de planos cronometrada e, em seguida, uma edição de retenção. Se a pessoa lhe entregar um roteiro ou um esboço de cenas, as palavras dela e sua especificação prevalecem sobre qualquer regra interna aqui: nunca reescreva as falas dela, sugira mudanças e cite o que você mudaria.

Entregável: SCRIPT.md (três ganchos + a escolha, narração completa, tabela de planos cronometrada, contagem de palavras) e script.py.

2. A timeline, depois a voz

• script.py contém PHRASES (onde cada fala é colocada, seu texto, seus chunks de legenda com [palavra] para a palavra-chave vermelha) e MARKS (os beats da história em segundos, que se tornam os limites dos planos).
• python build_tl.py escreve timeline.json (total, marks, lines). O reel lê apenas timeline.json. No starter, funciona antes de qualquer áudio existir: as durações das frases são estimadas a partir das contagens de palavras, então você pode bloquear a imagem primeiro.
• A voz é uma tomada por falante, 48 kHz mono, de qualquer TTS ou um microfone (este repositório não fornece nenhum; ElevenLabs é pago, Kokoro é gratuito e local). Nunca acelere uma tomada para caber: corte um beat. Escreva números por extenso no texto que você envia para um TTS.
• python tools/find_phrases.py take.wav imprime o (início, fim) de cada frase na tomada. Coloque-os em PHRASES e execute build_tl.py novamente: ele corta as frases, as coloca e escreve audio/narration.wav. Em seguida, verifique novamente cada plano: as durações reais das frases diferem das estimativas.
• Os arquivos build_tl.py fornecidos lidam com um narrador. Para vários falantes, mantenha uma tomada por falante e adicione o falante a cada frase (uma pequena alteração em build_tl.py).
• Palavrões para o TikTok: bleep-os em um stem separado e coloque asteriscos nas legendas (f***ing).

3. Os arquivos do episódio (references/engine.md)

arquivo	função
script.py	falas, chunks de legenda, marcos
build_tl.py	timeline.json (+ audio/narration.wav)
looks.py	o elenco: cada look é um dicionário em rig.LOOK
scenes.py	o mundo: geometria do cenário, luzes, quem está onde no tempo T, as pistas de atuação
reel.py	SHOTS, legendas, render(T), as verificações e os comandos de renderização
cues.py	eventos sonoros para tools/sound.py
finalize.py	mixar os stems, multiplexar no render, executar tools/finish.py

Inicie um novo episódio copiando episodes/starter/toon para episodes/<nome>/toon. Seus reel.py, build_tl.py e finalize.py são genéricos e podem permanecer como estão; você substitui script.py, looks.py, scenes.py, a tabela SHOTS e cues.py. Não comece a partir de episodes/window/toon: seus reel.py, cues.py e verificações estão vinculados àquela história (dois mundos espelhados, marcos nomeados, uma câmera de virada personalizada). Leia-o para técnica: texturas, profundidade de campo, uma chave de rosto por mundo, mãos no vidro, uma transição entre mundos. Episódios maiores movem a atuação de scenes.py para um acting.py.

Um mundo precisa de dois métodos: draw(fr, cam, T), que desenha tudo e retorna {pid: resultado de rig.draw}, e cast(T), que retorna [(pid, look, pose)]. pid é o id de uma pessoa neste episódio ("nora"). Um mundo e uma timeline por localização; os planos apenas escolhem as câmeras.

4. Look (references/look.md)

Formas simples arredondadas, cabeças ligeiramente grandes, olhos grandes e expressivos, materiais mates com sombreamento suave de 3 stops e um contorno mais escuro na cor base. Cada personagem recebe sua própria silhueta, rosto e paleta projetados a partir do script (nunca um reskin de outro personagem de reel); personagens recorrentes permanecem no modelo. Faça uma ficha de modelo antes de animar, a partir de tools/toon: python -m cast.sheet ../../episodes/<nome>/toon/looks.py <look> (escreve assets/kit/cast/<look>.png na raiz do projeto, ou o caminho que você der como terceiro argumento).

5. Iluminação (references/lighting.md)

Três camadas em cada local: um ambiente frio (noite azul-arroxeada mantém detalhes), um key suave em cada rosto (de cima para frente, motivado por uma lâmpada ou janela), e luzes práticas quentes a várias distâncias que iluminam o que está perto delas. Os rostos são a coisa mais clara no quadro; o fundo é um pouco mais escuro e com menor contraste ao redor deles. Sombras de contato sob os pés, móveis e mãos que se tocam. Uma configuração de luz por local: a direção, cor e exposição se mantêm entre os cortes. Sem bloom, sem contornos brilhantes, sem pretos esmagados. Clima (chuva, neve, vento) anima em momentos calmos quando a história tem clima.

6. Câmera (references/camera.md)

• Um corte a cada 2-3 s. Cada plano serve a uma ação, uma expressão ou uma revelação.
• O gancho (0-3 s) é o plano móvel mais bonito do reel: câmera e personagem se movem a partir do quadro 1.
• Plano médio primeiro, depois closes combinados. Closes ficam dentro de ~35 graus da linha dos olhos.
• track(a, b, ease) faz um movimento limpo entre duas chaves (posição, alvo, px focal, horizonte). A câmera vira para enfrentar o alvo, mas não pode inclinar: a altura do alvo é ignorada. Enquadre para cima ou para baixo com a altura da câmera e horizonte (um valor menor coloca a linha dos olhos mais alta no quadro, o que parece olhar para baixo).
• Mantenha as câmeras >= 0,45 m de qualquer pessoa à vista: rig.draw não desenha ninguém mais perto do que isso.
• Legendas (Arial Black 66 px, branco, borda preta, palavra-chave #FF4D4D) nunca ficam sobre um rosto ou uma mão. Mova-as por plano com cap=(y, size).

7. Atuação e encenação (references/acting-staging.md)

Cada ação é uma cadeia com deslocamentos: olhos -> cabeça -> ombros -> corpo -> mãos, como preparação -> movimento -> acomodação. Reações saem com out/snap, acomodações com back. Apreensões alcançam antes de fechar. Uma pessoa que apenas vira a cabeça e os ombros pode ficar nos pés padrão; uma pessoa que anda ou vira o corpo precisa de pés plantados no espaço do mundo (ankle_R/ankle_L de rig.replant ou rig.gait), pisando um de cada vez. Leia as lições de encenação antes de bloquear qualquer coisa: cada uma é um bug que já aconteceu.

8. Verificações: o portão antes de cada master (references/checks.md)

1. python reel.py --check -> leia todo o review/reel_checks.txt. No starter, cada problema é uma linha ANOMALY: alcance, pés afundando, cotovelos hiperestendidos, inversão de cotovelo e joelho, saltos, pessoas muito próximas da lente, legendas sobre um rosto ou mão.
2. python reel.py --stills -> primeiro/meio/último quadro de cada plano (rodada 1).
3. python reel.py --sheet <SHOTS> -> cada quadro de planos de contato, caminhadas, giros e mudanças de oclusão em folhas espaçadas (rodada 2). Procure por divisões, membros saltando, cabeças através de coisas, coisas desaparecendo.
4. Corrija nos dados, execute novamente e registre cada anomalia em review/LOG.md (apenas anexe): tempo, plano, causa, correção, como verificado; além de flags aceitas com o motivo e o que você não pôde inspecionar.
5. Nunca afirme "sem anomalias" apenas a partir do código. O código verifica juntas, não imagens: ele não vê pessoas passando através de móveis ou umas das outras, props faltando uma mão, uma ordem de desenho errada ou um passo lateral de 0,8 m que parece uma abertura de pernas. Esses você encontra nas folhas.

9. Renderização (a partir da pasta do episódio)

• python reel.py --preview --full -> review/reel_preview.mp4 (1080x1920, silencioso). python finalize.py preview adiciona a mixagem -> review/preview.mp4. Mostre-o, obtenha um OK.
• python reel.py --master-par 12 -> video/reel_silent.mp4: o master em 12 processos (use sua contagem de núcleos).

10. Som, mixagem, finalização, pós (references/sound-finish.md)

• cues.py, depois, a partir da raiz do projeto python tools/sound.py episodes/<nome>/toon -> stems de música, efeitos sonoros e ambiente. Gravações reais para coisas reais (traga samples CC0 ou licenciados para assets/sfx/); síntese apenas para drones abstratos, risers e booms. As cues do starter são todas sintetizadas para que a cadeia funcione: substitua-as.
• python tools/mix_check.py episodes/<nome>/toon: a voz deve estar >= 10 dB acima dos beds em cada fala (cada fala falha até que haja uma tomada de narração real).
• python finalize.py final (pasta do episódio) -> tools/finish.py -> -14 LUFS, <= -2 dBTP, H.264 High, +faststart.
• Capa, a partir da raiz do projeto: python tools/thumb.py frame.png cover.jpg --line "TÍTULO:#F2EFE6:120".
• POST.md: legendas por plataforma, hashtags e um lembrete para ativar o upload em HD no aplicativo.

Palavras usadas aqui

• marco: um batida nomeada da história em segundos (MARKS), usada como limite de plano e para temporizar ações.
• estação: um ponto onde um personagem fica (x, z, voltado para) e o tempo em que ele pisa nela.
• pé plantado: um tornozelo fixo em uma posição do mundo (ankle_R/ankle_L), para que o pé não deslize.
• zona de clip: um clip em espaço de tela que esconde parte de um corpo atrás de algo (uma sebe, uma borda de parede).
• item de parede chato: cenário de parede chato (cortina, pôster); classifique-o tão atrás quanto sua parede.
• luz prática: uma fonte de luz que é visível no cenário (uma lâmpada, uma janela acesa).

Hábitos

• Olhe antes de afirmar. Renderize o quadro, leia a folha, então diga o que viu.
• Uma mudança, uma re-renderização dos planos afetados, uma re-verificação, com folhas.
• Quando uma encenação continua falhando, simplifique-a ou escolha um ângulo mais claro. Nunca esconda anatomia com desfoque, escuridão, cortes ou legendas.
• Escreva toda correção que a pessoa lhe der no review/LOG.md do episódio e, se for geral, em um STAGING_NOTES.md na raiz do projeto (leia-o no início de cada episódio). Nunca escreva na própria pasta do plugin.