Files
CenaForge/.claude/skills/cenaforge/references/cartoon.md
T
MateuusandClaude Opus 5.5 3f600c55b1 Cartoon: rig, movimento e lip sync dos personagens
- cartoon/src/rig.ts, motion.ts e lipsync.ts: esqueleto do personagem,
  curvas de movimento e sincronia labial no estilo Cartoon (Remotion)
- CharacterFigure/CharacterCard/Shot/overlays e spec atualizados
- Painel: estúdio de personagens e montagem cartoon ajustados
- Documentação em doc/cartoon/animacao.md e personagens.md; skill atualizada

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 23:39:12 -03:00

159 lines
14 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Estilo Cartoon (`cartoon/`, Remotion, sem Godot)
Pacote do workspace (`pnpm-workspace.yaml`: `panel` + `cartoon`; nome `cenaforge-cartoon`). Cada trecho da montagem
documental vira um MP4 de desenho 2D com a duração do áudio. Versões e medição: [tools.md](tools.md).
**Princípio (dono, 17/11/2026): a ferramenta "sabe como faz".** Nada de cenário ou template pronto reaproveitado: cada
cena é montada **por peças** a partir do texto (parque de dia, cemitério, bunker…). **Personagens** são o contrário:
criados uma vez, na biblioteca, e reaproveitados em várias histórias. Não crie "cena pronta" nova; crie peça ou regra.
Guias do projeto (fonte de detalhe, não duplicar aqui): `doc/cartoon/cenas.md` (camadas, receitas por situação,
composição), `doc/cartoon/personagens.md` (ficha, agente), `doc/cartoon/animacao.md` (expressões e movimento, guia do agente), estudo de referência `doc/estudo-estilo-cartoon-explicativo.md`.
## Contrato da cena (`cartoon/src/spec.ts`, `schemaVersion` 1; `validateSpec` recusa o resto)
- `width`/`height`/`fps`/`durationS`/`seed`; `camera {push, panX}`; `hud {badge, label, clock, clockMinutesPerSecond}`;
`props` (ícone `house|generator|fuel|battery|phone|door|eye|bulb|solar|warning|money|clock`, `label`, `tone`
`info|danger|ok`, `shake`, `rings`, `crossed`); `texts` (`onomatopoeia|tag|counter|big`); `words [{text, startS, endS,
tone key|danger}]`; `card`. Posições em fração do quadro (0–1).
- `scene.kind`: `street|house|plain|blueprint|card` (cenas antigas) ou **`place`** (por peças). `palette`
(`night|sepia|day|dusk|gray`, `PALETTES` em `places.tsx`), `place`, `light` (`none|spot|vignette`).
- `place {ground grass|street|dirt|floor|sand|water|none, indoor, fog, horizon, elements[{kind, x, z, scale, flip, color}]}`;
`z` 0 = frente, 1 = fundo. 24 peças em `ELEMENTS`: tree, deadtree, pine, bush, rock, mountain, cloud, bench, lamp,
gravestone, cross, fence, house, building, car, sign, door, window, table, bed, shelf, crate, tent, fire.
Peça nova = entrada em `ELEMENTS` + desenho em `cartoon/src/places.tsx`.
- `grain` (0 desliga, padrão 0,11): textura de papel sobre a cena (`Grain` em `overlays.tsx`, feTurbulence com mix-blend overlay;
também no `CharacterCard`).
- `actors`: `person` com `character {name, caption, look}`, `expression`, `pose`, `item` (objeto na mão), `flip`,
`framing` `full|medium|close` (Shot: zoom 1/1,9/2,9 e base y = `y`/0,98/1,15; a etiqueta vai para o lado),
`face`/`body` (ajustes finos do rig), `timeline` (ações de movimento, até 40); `spec.audioEnv {fps, values}`
(campos antigos `label`/`hair`/`glasses`/`pointing` ainda valem); `crowd` (entra antes do personagem, atrás, pés em y 0,6).
## Peças (`cartoon/src/`)
`places.tsx` (paletas, chão, peças, `LightLayer`), `scenes.tsx` (fundos antigos, espaço 1080×1920), `actors.tsx` (multidão,
pessoa antiga), `CharacterFigure.tsx` (personagem), `icons.tsx`, `overlays.tsx` (etiqueta amarela, onomatopeia com tremor,
anéis de som, X vermelho, HUD com relógio, legenda palavra por palavra em blocos de até 3), `Shot.tsx` (empurrão de
câmera), `Root.tsx` (composições `Shot` = trecho **vazio**, `Sample` = exemplo do Studio, `Character` = cartão),
`colors.ts` (cores sem Remotion; `theme.ts` só carrega fontes). Fontes Anton e Bebas Neue de `assets/fonts/`.
## Render
`tsx cartoon/render.ts --jobs <json>` (`[{spec, out}]`) | `--spec x --out y` | `--sample --out y` | **imagem parada de
personagem:** `tsx cartoon/render.ts --still --props x.json --out y.png [--frame N]`. Empacota uma vez e renderiza todos;
**última linha do stdout = JSON `{ok, results|error}`**. O 1º render baixa o Chrome Headless Shell (~120 MB);
`CARTOON_CHROME` aponta outro Chrome. Studio: `pnpm --filter cenaforge-cartoon studio`. Testes (dentro de `cartoon/`):
`npx tsx --test tests/*.test.ts`; tipos: `pnpm --filter cenaforge-cartoon typecheck`.
## Personagens (biblioteca)
- **Contrato** `cartoon/src/character.ts` (`Character`, `schemaVersion` 1): `id`, `name`, `caption`, `description`,
`kind` `cartoon|3d`, `look {build slim|average|heavy, height 0,6–1,2, skin, hair{style short|side|bun|long|curly|spiky|
bald|cap, color}, beard none|stubble|mustache|full|goatee, glasses none|round|square|sun, brows thin|thick,
top{shirt|jacket|hoodie|dress|uniform, color, accent}, bottom pants|shorts|skirt, shoes}`. `EXPRESSIONS`/`POSES`
vêm do rig (reexportados). `validateLook`.
**Acabamento (17/11/2026), campos OPCIONAIS do `look`:** `head` (`HEAD_SHAPES` round|oval|square|wide), `nose` (`NOSES`
button|curve|round|long|wide), `lids` (0–0,8, pálpebra de base), `wrinkles` (0–1), `belly` (bool), `accessories`
(`ACCESSORIES`: towel, whistle, tie, vest, helmet, watch, badge, apron, scarf, headset, chain) e `accessoryColor`.
- **Desenho** `CharacterFigure.tsx`: SVG puro (sem Remotion), `viewBox` 200×440, pés em (100,440), escrito sobre o rig (seção
"Rig, movimento e fala"). O painel importa o mesmo componente (prévia ao vivo): dependência `"cenaforge-cartoon": "workspace:*"` em
`panel/package.json`, `transpilePackages` em `panel/next.config.ts`, `exports` do pacote `./character`, `./figure`, `./spec`, `./motion`, `./rig`.
- **Arquivos:** `assets/characters/<id>/character.json`; elenco da história `stories/<id>/cast.json` (`{"cast":[ids]}`).
- **Painel** `panel/src/lib/characters.ts`: `listCharacters`/`getCharacter`/`saveCharacter`/`deleteCharacter` (não apaga
quem está em elenco), `describeToLook` (descrição pt-BR → `look` + `caption` por regras: idade, gênero, criança,
profissão → uniforme/cor, cabelo, barba, óculos, corpo, cor de roupa; **e o acabamento**: `nose`, `lids`, `wrinkles`,
`head`, `belly` e `accessories` por idade, "barrigudo", "narigudo", "cansado" e profissão — técnico: apito + relógio;
obra: capacete + colete laranja; porteiro: crachá; merendeira: avental; roupeiro: toalha; empresário: gravata + relógio;
`PROFESSIONS` inclui técnico, porteiro, merendeira, roupeiro, operário, empresário), `getCast`/`setCast`. Rotas: `GET/POST
/api/characters`, `GET/PUT/DELETE /api/characters/[id]`, `POST /api/characters/[id]/agent`, `GET/PUT
/api/stories/[storyId]/cast`. Página `/characters` (aba "Personagens"; `components/character-studio.tsx`: criar pela
descrição, prévia com expressão/pose, formulário peça por peça — inclui Cabeça, Nariz, Pálpebra, Rugas, Barriga, Cor dos acessórios e chips de Acessórios —,
"Refinar com o agente", apagar).
- **Agente:** `AgentKind` `"character"` (`types.ts`; `agents.ts`: orçamento US$ 0,5, Sonnet, Claude preferido; `prompts.ts`
manda ler SÓ `doc/cartoon/personagens.md` e gravar a ficha).
- Para testar a API com acento use Python/UTF-8 (gotchas 153); o `id` sai do nome sem acento.
## Rig, movimento e fala (FERRAMENTA, não template)
Princípio do dono: expressão e movimento são **parâmetros contínuos e ações combináveis**; os presets são só atalhos.
Detalhe e exemplos: `doc/cartoon/animacao.md`.
- **`rig.ts`:** `FaceParams` (`browL/browR {y, tilt}` tilt + = ponta de dentro sobe, `eyeL/eyeR` 0–1,35, `pupil`,
`gazeX/gazeY`, `mouthOpen`, `smile` −1…1, `mouthWidth`, `mouthRound`, `lid` (pálpebra, somada ao `lids` do personagem: surpreso/medo −0,5, sono 0,6, desconfiado 0,45; os presets usam `lid` em vez de fechar o olho), `teeth`, `blush`, `sweat`, `tears`, `anger`) e
`BodyParams` (`lean`, `headTilt`, `headTurn` −1…1, `headNod`, `armL/armR/legL/legR {raise, bend}` em 2 segmentos, `crouch`).
20 `EXPRESSION_PRESETS` (neutral, smile, happy, laugh, proud, sad, cry, worried, angry, furious, surprised, scared,
shocked, suspicious, smirk, confused, disgusted, sleepy, determined, embarrassed) e 17 `POSE_PRESETS` (stand, point, wave,
hold, arms_up, celebrate, shrug, think, hands_on_hips, cross_arms, facepalm, cover_mouth, defend, reach, sit, kneel,
lean_in). `faceOf`/`bodyOf(nome, ajuste)`, `withFace`/`withBody` (aceitam `brows`/`eyes`/`arms`/`legs`), `blendFace`/`blendBody`.
- **`motion.ts`:** `Action {do, at|atP|cue, dur, cueEnd, expression/face, pose/body, to, dir, times, height, text}`; `ACTIONS`:
express, pose, walk, run, enter, exit, jump, nod, shake_head, tremble, bounce, fall, sit, stand_up, turn, talk, look, emote,
wave. `evaluate(actor, t, durationS, seed, {words, env})` → `{face, body, x, dx, dy, rot, sx, sy, flip, emote}`; `startOf`
resolve `cue` pela palavra falada (prefixo normalizado); piscar em intervalos variados, respirar e balanço sempre ligados;
`validateTimeline` (até 40 ações). `Shot.tsx` aplica `evaluate` por ator (posição/giro/escala/espelho no container).
- **`lipsync.ts`:** `visemeAt(palavras, t, env)` (forma por letra: a abre, e/i esticam, o/u arredondam, m/b/p fecham, f/v
dentes; vogal pesa 1,7 e consoante 0,8; coarticulação na 2ª metade da letra; fecha 60 ms após a palavra; `env` fecha nas
pausas), `emphasisAt` (sobrancelhas no pico), `speak(face, viseme)` (mantém cantos/sobrancelhas/olhos da expressão). `talk`
usa as palavras entre `cue` e `cueEnd`, ou `text` repartido por `dur`.
- **Desenho:** prop `state` (de `evaluate`); sem ele usa `expression`/`pose` + vida. Boca contínua com `clipPath`; olho de
riso em arco; balão de emote; mão no rosto desenhada por cima da cabeça. **Acabamento do desenho:** pálpebra recortada
(`clipPath` por olho) com borda mais escura; 5 narizes; rugas; cabeça por formato (`headPath`) com sombra de baixo e
brilho na testa; orelha com dobra; mão com polegar; tronco com sombra lateral, gola em V e zíper; barriga = elipse + curva
de volume (**só a sombra em elipse parecia mancha**); `Accessories` (capacete e fone na cabeça, relógio no pulso esquerdo).
**Armadilha:** a curva quadrática só chega à
METADE do controle, então os controles da boca ficam no dobro da abertura.
- **Painel:** `character-studio.tsx` lista as 20 expressões e 17 poses em pt-BR e tem "Movimento (prévia)" (`MovePreview`,
loop de 2,6 s). `CharacterCard` aceita framing `"face"` (recorte do rosto). Agente `character` lê `animacao.md` se o
pedido falar de expressão/movimento.
## Plano no painel (`panel/src/lib/montage-cartoon.ts`, sem banco)
- Tipos vêm de `"cenaforge-cartoon/spec"` (não há mais espelho). `planCartoon(shot, ctx, variant)` com
`PlanContext {hud, cast, palette}` por regras do texto:
- **Lugar:** `LOCATIONS` por palavra (cemitério, bunker/porão, hospital/escritório, casa/quarto, parque, floresta,
acampamento, praia, sítio, rua/cidade) → `placeFor` (peças espalhadas pela semente, longe do centro; cada lugar traz
paleta/luz própria). Sem lugar reconhecido cai nas cenas antigas.
- **Personagem:** `expressionOf`/`poseOf` pelo texto; quem é citado pelo nome entra com a aparência da biblioteca; com 1
personagem só, ele aparece nos trechos pares ou quando o texto diz "ele/ela"; objeto pequeno vai para a mão (`item`).
- **Enquadramento do personagem** (`framing`): `close` quando ele fala sozinho (há `talk`, 1 personagem); `medium` sozinho
sem objetos nem multidão; `full` no resto.
- Ícones por palavra-chave; "pessoas/vizinhos" vira multidão; "nunca/não" + perigo risca o objeto; sons viram
onomatopeia (motor só com gerador/motor/moto/carro perto; barulho genérico = "Crec"); texto na tela numérico vira `big`,
senão etiqueta; `variant` troca arranjo e seed.
- `wordTimings` (transcreve o áudio com `detail: "words"`; sem o serviço, reparte o texto pela duração; gotchas 156).
`cartoonKey(scene, duração, audio.key)` decide se está atual. `renderCartoonShots`: specs em
`stories/<id>/cartoon/`, MP4 em `output/cartoon/<story>-<file_key>/`.
- **`lib/montage.ts`:** `VisualKind` `"cartoon"`; `ShotVisual.cartoon`/`cartoonVariant`/`cartoonKey`;
`SavedMontage.cartoonPalette` (`CARTOON_PALETTES`); `cartoonCtx(ep)` monta o contexto com o elenco da história. O
automático planeja tudo em cartoon no estilo `"cartoon"`; a etapa 3b renderiza **todos** os trechos desatualizados numa
execução; em `buildSegment` o trecho cartoon **não** recebe texto na tela nem legenda do FFmpeg (já vêm na cena). Mudar a
paleta, ou `PATCH {replanCartoon: true}`, apaga o plano dos trechos Cartoon automáticos (replanejados na próxima
geração); "Gerar de novo" troca `cartoonVariant`; `hudFor` = 2 primeiras palavras do título + "Ep. N".
- **UI** (`montage-editor.tsx`, recebe `storyId`): opção de estilo, bloco `CartoonSetup` (paleta da série + elenco por chips,
só no estilo Cartoon), botão "Cartoon" no trecho, `CartoonPreview`.
- **Movimento pelo texto:** `timelineFor(texto, x)` (`EMOTIONS` por palavra → `express` com `cue`; `MOVES` por verbo → ações;
`quoteOf`: fala entre aspas/travessão → `talk` com `cue`/`cueEnd`; começa `neutral` se houver `express`).
`audioEnvelope(file)` (FFmpeg mono 8 kHz, RMS por quadro normalizado pelo p95; ~199 quadros para 6,6 s) →
`cartoonSpec(scene, dur, words, env)`; `montage.ts` passa o env.
- **Testes:** `panel/src/lib/montage-cartoon.test.ts` (10).
## Medido (17/11/2026)
Mesmo personagem em parque (`day`), cemitério (`dusk` + fog + `vignette`) e bunker (`sepia` + `spot` + indoor): 3 trechos de
4 s em ~2,6–2,8 s cada. Plano com elenco "Marta" → parque de dia (acenando) e cemitério (com medo, "Crec") renderizados.
Testes (antes do rig): painel 77/77, cartoon 5/5.
Rig/movimento (17/11/2026, informado pelo dono): grade das 20 expressões conferida de perto; personagem falando narração
real (ilha ep01-01) com `worried` mantida e "não" balançando a cabeça na palavra; sequência enter→jump→sit→stand_up→wave→
scared+"!"→tremble→fall de 7 s renderizada em 5,6 s. Testes: painel 78/78 e `tsc` ok (informados); cartoon 16/16
(`tests/motion.test.ts` 11 novos) reexecutado na skill. Renders não reexecutados.
Acabamento de ilustração (17/11/2026, informado pelo dono; referência: reel de série de cartoon, cujos personagens são
ilustrações paradas com textura, só a câmera desliza — o rig mantém a animação): 4 personagens criados só pela descrição
(porteiro 64, técnico barrigudo 52, mestre de obra 38, merendeira 70) saíram com os detalhes certos; close falando
renderizado. Testes: cartoon 16/16 reexecutado na skill; painel 78/78 e `tsc` informados. Renders não reexecutados.
## Ainda não existe (próximo passo)
Vistas especiais da referência: corte do subsolo, mapa visto de cima, painel/gráfico, celular, tela dividida. Agente que
escreve o spec de cada trecho (em vez das regras de `planCartoon`). Personagem `kind: "3d"` existe só na ficha. Não prometa.