Files
CenaForge/.claude/skills/cenaforge/references/tools.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

20 KiB
Raw Blame History

Ferramentas do CenaForge

Inventário do que o pipeline usa, do que está planejado e de como avaliar uma ferramenta nova. Versões abaixo foram verificadas na data indicada; ao trocar de versão, rode o render de prévia e registre aqui (via cenaforge-skill-updater).

Em uso

Ferramenta Versão testada Papel Como é localizada Verificada em
Godot (edição padrão, GDScript) 4.7.2.stable.official (ed1daf0bf) monta e anima a cena (rua 3D main.tscn; documentário em doc.tscn: 2D por doc2d_canvas.gd, _draw + SystemFont Segoe UI/Arial/DejaVu; 3D pela biblioteca godot/library/: island com FastNoiseLite, MultiMesh, shader de mar e ProceduralSky; castaways sobre os kits godot/kits/ com malha por SurfaceTool); Movie Maker grava PNG GODOT_BIN → PATH (godot, godot4) → .tools/godot-<versão>/Godot_v*-stable_win64.exe 16/11/2026 (reconferida 17/11/2026; doc2d e doc3d island/castaways com render ok em 17/11/2026)
Renderizador Godot Mobile (Vulkan) sombras direcionais, MSAA 4x, névoa, tonemap método mobile, msaa_3d=2 (4x) e sombra 4096 em project.godot; névoa e tonemap Filmic em street_builder.gd; ACES + névoa na ilha (godot/library/island/template.gd) 16/11/2026 (ilha: 17/11/2026)
FFmpeg 7.1.1 essentials (gyan.dev) PNG → MP4; áudio AAC; quadros de inspeção; montagem documental do painel (zoompan, boxblur + overlay na foto horizontal, drawtext, concat -c copy; panel/src/lib/montage-ffmpeg.ts, fonte Segoe UI Bold/Arial Bold) FFMPEG_BIN → PATH 16/11/2026 (montagem: 17/11/2026)
FFprobe 7.1.1 verificação do MP4 e duração do áudio FFPROBE_BIN → PATH 16/11/2026
Encoder de vídeo libx264 (preset medium, CRF 18) H.264 yuv420p ordem: libx264 → h264_nvenc → libopenh264 (tools.ts) 16/11/2026
Node.js 24.19.0 (mínimo ≥ 20.10) lançador — 16/11/2026
pnpm 11.22.0 scripts e lockfile — 16/11/2026
tsx 4.23.15 executa o TypeScript do lançador devDependency 16/11/2026
TypeScript 7.0.2 (compilador nativo) pnpm typecheck devDependency 16/11/2026
@types/node 24.19.2 tipos devDependency 16/11/2026
Next.js / React / Tailwind 16.4.6 / 19.3.0 / 4.3.3 painel (panel/) dependências do workspace 16/11/2026
@xyflow/react 13.0.1 árvore de vertentes na aba Fluxo (panel/src/components/story-flow.tsx) dependência do painel 16/11/2026
SQLite node:sqlite (Node 24) banco do painel, sem dependência nativa embutido 16/11/2026
Codex CLI 0.169.0 (@openai/codex) agente no painel (codex exec --json -m <slug>, sandbox workspace-write); modelos lidos de ~/.codex/models_cache.json (panel.md, "Agentes e modelos") CODEX_BIN → .exe no PATH → codex.js ao lado do codex.cmd do npm 17/11/2026
API do Wikimedia Commons (commons.wikimedia.org/w/api.php) sem versão (HTTP público, sem chave; User-Agent genérico) fotos reais por trecho na montagem documental (panel/src/lib/image-search.ts), com autor, licença e página de origem nos créditos chamada direta do painel 17/11/2026 (ep01.montage.json: 5 fotos do Commons com licença CC registrada; MP4 de 88,3 s; licença não conferida na página de cada foto)
Claude Code CLI 2.1.314 agente chamado pelo painel (-p, stream-json, --resume, --model claude-*-5-5/claude-fable-5-2) CLAUDE_BIN → PATH (claude.exe) 17/11/2026

Estilo Cartoon (cartoon/, 17/11/2026; contrato e uso em cartoon.md):

Ferramenta Versão Papel Evidência (17/11/2026)
Remotion (remotion, @remotion/bundler, @remotion/renderer, @remotion/cli) 4.0.535 (fixada; conferida em cartoon/node_modules) cenas 2D vetoriais em React → MP4 por trecho exemplo de 6 s (180 quadros) em 11,8 s; 3 trechos reais (~21 s de vídeo) em 25,2 s (1º 11,2 s, depois ~4 s cada). Medido pelo dono, não reexecutado aqui
React / react-dom 19.3.0 componentes das cenas idem
Chrome Headless Shell baixado pela Remotion no 1º render (~120 MB; versão não registrada); CARTOON_CHROME aponta outro Chrome renderiza os quadros idem
Fontes Anton e Bebas Neue assets/fonts/ (publicDir = assets) texto das etiquetas e legenda ver licenças em "Clipador"

Licença da Remotion: grátis para pessoa física e empresa pequena; empresa maior paga. Conferir os termos antes de uso comercial (não verificado aqui). Testes: npx tsx --test tests/*.test.ts em cartoon/ (5 de spec.test.ts + 11 de motion.test.ts); painel: montage-cartoon.test.ts (10). Cartoon 16/16 reexecutado em 17/11/2026; painel 78/78 informado pelo dono.

Hardware do teste de referência: i9-13900K, 64 GB, RTX 2060 SUPER. Tempos: prévia 540×960 42–44 s; final 1080×1920 ~160 s. A etapa de render da Godot ocupa 94–96% do total, dominada pela codificação PNG (105 ms/quadro na prévia, 404 ms no final; ~90–91% do total); GPU 1,9/4,5 ms por quadro. Cena 2D (doc2d, 17/11/2026, report.json): prévia 540×960 de 5 s em 2,7–4,3 s; final 1080×1920 de 4,4–14,3 s em 7,4–21,5 s por cena (9 cenas). Cena 3D island (doc3d, 17/11/2026, report.json): prévia 540×960 de 5 s em 9,4–14,3 s (Godot 9–13 s, 13 execuções); final 1080×1920 de 9,1 s em 42,9 s (Godot 39,1 s). Cena 3D castaways (17/11/2026, report.json): prévia 540×960 de 4–5 s em 5,8–15,6 s (65 execuções teste-cast-*); final 1080×1920 de 2,8–12,3 s em 9,8–89,7 s por cena (11 cenas da montagem dos náufragos).

Serviço de voz (voice/) — instalado, ainda fora do render

Serviço FastAPI local em 127.0.0.1:4510, cópia adaptada do dropsz_voice (o original não é alterado). Instalado por setup.bat → scripts/setup.ps1; fixações em voice/requirements*.txt e voice/models.lock.json. Consumido pela página Vozes do painel (panel/src/lib/voice.ts). Evidência (16/11/2026): pnpm test:voice → 133 passed (conferido nesta manutenção; inclui Kokoro/Google/Azure simulado/clone e flag offline por motor); legenda pelo painel na CPU: 6,5 s de fala em 2,5 s, 14 palavras e .srt; fumaça voice/scripts/smoke.py gerou os WAV das três vozes e a transcrição em output/voice-smoke/; setup completo rodou 2x com saída 0 (repetível); torch 2.11.0+cu128, cuda True; VoiceConverter do Applio importa no voice/.venv com device cuda:0; pré-requisitos em voice/vendor/applio/rvc/models/ (predictors/rmvpe.pt, predictors/fcpe.pt, embedders/contentvec/pytorch_model.bin). Catálogo com 76 vozes (16/11/2026): 12 Edge, 3 Piper, 45 Kokoro, 2 Google, 14 Azure (contagem conferida no catalog.json; as Azure só aparecem com VOICE_AZURE_KEY). Antes, com 15 (informado): fetch_models.py --group v1 conferiu sha256 de cadu/jeff; load_catalog(verify=True) carregou 15; amostras transcritas com Whisper small — Edge todas pt (prob ≥ 0,99), cadu correto, jeff erra palavras longas. edresson (Piper low, 16 kHz) fora de propósito. Piper não tem feminina pt-BR; a feminina offline agora é kokoro-pf-dora. Kokoro (informado, 16/11/2026): as 54 vozes leram frase pt-BR, transcrição com Whisper small → 45 com 100% das palavras e idioma pt entraram; excluídas af_bella, af_nicole, bf_alice, bf_emma, bf_isabella, bm_fable, em_santa, ff_siwis, jf_alpha. Nenhum render usou o serviço ainda — o WAV entra no vídeo só via audio.file.

Ferramenta Versão verificada Papel
uv 0.11.26 cria voice/.venv (o Python do sistema não é tocado)
Python 3.12.13 voice/.venv
FastAPI / uvicorn 0.159.1 / 0.54.0 HTTP (uvicorn app.main:build --factory, chamado por scripts/dev.ts)
edge-tts 7.3.1 12 vozes online do catálogo (pt-br-*, pt-pt-*, multi-*)
piper-tts / onnxruntime 1.8.0 / 1.31.0 vozes pt-br-faber, pt-br-cadu, pt-br-jeff (offline, CPU, medium 22050 Hz)
kokoro-onnx / phonemizer / espeakng-loader 0.6.1 / 3.6.0 / 0.2.4 45 vozes kokoro-* (offline, CPU; Kokoro-82M fp16, Apache-2.0; um modelo + voices-v1.0.bin do release model-files-v1.1 de thewh1teagle/kokoro-onnx)
gTTS 2.5.4 google-pt-br, google-pt-pt (online; API não oficial do Google Tradutor; só normal/lenta)
faster-whisper / ctranslate2 / av 1.2.1 / 4.8.3 / 19.0.2 transcrição com tempos; modelos base, small, medium, large-v3-turbo
nvidia-cublas-cu12 / nvidia-cudnn-cu12 12.9.2.10 / 9.26.0.51 DLLs CUDA 12 para o Whisper na GPU (só com GPU NVIDIA)
Applio 3.7.0 (voice/vendor/applio) RVC: vozes de personagem
torch / torchaudio 2.11.0+cu128 (com GPU) ou 2.11.0+cpu (sem) motor do Applio; o setup pede a variante explícita

Clonagem de voz (voice/.venv-clone, opcional: setup.bat -Clone)

Venv separado porque o Chatterbox conflita com o voice/.venv (gotchas, item 65). Worker voice/clone/worker.py (stdlib, 127.0.0.1:4511, mesma X-Service-Key) chamado pelo CloneEngine. Detalhes e formato da voz clonada: voice/README.md, "Clonagem de voz".

Ferramenta Versão verificada (16/11/2026) Papel
Python 3.12.13 voice/.venv-clone
chatterbox-tts 0.1.7 (Chatterbox Multilingual, Resemble AI, MIT; pt suportado) clonagem a partir de 10–30 s de gravação; WAV 24 kHz; marca d'água PerTh; sem velocidade
torch / torchaudio 2.6.0+cu124 (torch.cuda.is_available() = True) fixado pelo Chatterbox
numpy / transformers 1.26.4 / 5.2.0 fixados pelo Chatterbox
Pesos ResembleAI/chatterbox, revisão main (~3,3 GB em data/voice/models/clone-hf/) não fixados em commit nem sha256 (gotchas, item 64)

Evidência informada (16/11/2026, RTX 2060 SUPER 8 GB, worker real na GPU; não registrada em doc/TEST_RESULT.md): modelo carregou em 10 s (pesos já baixados); referência sintética de 10,7 s (Kokoro pm_alex); fala 1: 6,0 s de áudio em 20,5 s (inclui condicionamento); fala 2: 7,1 s em 10,5 s; Whisper small transcreveu as duas exatamente (idioma pt, prob. 1,0). Não testado: CPU, referência de voz humana real, fluxo completo pelo painel (upload → síntese).

Medições informadas (16/11/2026, i9-13900K, RTX 2060 SUPER 8 GB; não registradas em doc/TEST_RESULT.md): Edge ~2,5–3 s por fala de ~6 s; Piper ~0,02 s (modelo já carregado); Whisper small na CPU 2,7 s para 6,5 s de fala com palavras. Kokoro (CPU): kokoro-pf-dora 3,2 s de áudio em 2,4 s (1ª síntese, carrega o modelo); depois pm-alex 0,6 s, am-michael 0,7 s. Google: google-pt-br 4,8 s de áudio em 0,8 s. GPU disputada: ver gotchas.md.

Não verificado: conversão RVC com modelo real (VOICE_ENABLE_RVC=1, mas nenhum .pth instalado), Whisper large-v3-turbo (só small baixado em data/voice/models/whisper/) e o download de modelo de Whisper disparado pelo painel.

Clipador (clipper/) — cortes de live, fora do render da Godot

Serviço FastAPI em 127.0.0.1:4520. Instalado no passo 6b do scripts/setup.ps1, com as versões fixadas em clipper/requirements*.txt. Detalhes e evidência em clipper.md. Evidência: pnpm test:clipper → 270 passed (17/11/2026, com apagar cortes e veto do rejeitado no juiz e na fila; sem dependência Python nova nem ferramenta nova). Fase 1 (16/11/2026): uma live real da Twitch gerou 5 cortes H.264 1080×1920 + AAC. Horizontal 1920×1080: só render de teste conferido no ffprobe (informado); nenhum corte horizontal de live ainda.

Ferramenta Versão verificada (16/11/2026) Papel
Python 3.12.13 clipper/.venv (criado pelo uv)
FastAPI / uvicorn / httpx / websockets 0.159.1 / 0.54.0 / 0.28.1 / 17.4 HTTP do serviço; chamadas à voz; chat da Kick (Pusher)
Streamlink 8.6.3 (reconferido em 17/11/2026) captura de live/VOD (clipper/.venv/Scripts/streamlink.exe); qualidade por --stream-sorting-excludes e, na Twitch, --twitch-supported-codecs h264,h265 (clipper/app/capture.py). HEVC real da Twitch não testado (nenhuma live 2K no ar)
pytest 9.1.1 (fixado em requirements-dev.txt) pnpm test:clipper
FFmpeg 7.1.1 essentials, com filtro ass (libass) — reconferido em 17/11/2026 blocos -f segment, render vertical e horizontal, legenda queimada com fontsdir, reenquadramento (perspective eval=frame), camadas (alphamerge/overlay); decodifica HEVC; sem libdav1d (AV1 não é pedido na captura); NVENC quando houver (CLIPPER_ENCODER=auto; horizontal com NVENC não testado)
Fontes empacotadas (assets/fonts/) google/fonts no commit 7af0d90b4d532ffa4b041937b560c6df4e7b1e95, sha256 em fonts.lock.json ASS do Clipador e prévia do editor no painel. Licenças: Luckiest Guy Apache-2.0; Bangers, Anton, Bebas Neue, Poppins ExtraBold OFL-1.1 (texto ao lado de cada .ttf)
Codex CLI / Claude Code CLI 0.169.0 (reconferida em 17/11/2026) / 2.1.314 (as mesmas da tabela "Em uso") juízes analista + editor, varredura, câmera e pesquisa do jogo (codex --search exec … -i <img> … -), sem chave de API; padrão Codex gpt-6-luna. Claude: não testado
APIs públicas de emotes 7TV / BTTV / FFZ sem versão (HTTP público, sem chave) catálogo de emotes do canal e globais (clipper/app/emotes.py, cache 1 h; 7TV dá 404 em canal sem 7TV). Coberto só por teste sem rede; chamada real não registrada

Rastreio de reação (clipper/app/face.py + reaction.py; detalhes em clipper.md). Versões conferidas no clipper/.venv em 16/11/2026 (importlib.metadata). Evidência (doc/FACE_BAKEOFF.md): bancada e rastreio de 144 blocos numa cópia do banco; em 17/11/2026, serviço real ao vivo (instância 4521, 25/25 blocos, 1,71 s/bloco, p95 2,20 s, CPU média 16,8 % de um núcleo) e download real dos 4 pesos com sha256 conferido. Só CPU; GPU não testada.

Ferramenta / peso Versão verificada Licença Papel
mediapipe (Face Landmarker face_landmarker.task float16/1) 1.2.3 Apache-2.0 478 pontos + 52 blendshapes; 5–7 ms/quadro na bancada; bloco de 30 s em 1,71 s ao vivo (com gravação + transcrição juntas)
opencv-contrib-python (cv2.FaceDetectorYN) + YuNet face_detection_yunet_2026may.onnx 5.0.0.93 (cv2 5.0.0) Apache-2.0 / MIT (peso) acha a câmera pelo rosto no quadro inteiro (piso de confiança 0,7: gotchas, item 92). Sem opencv-python-headless junto (gotchas, item 80)
numpy 2.5.5 BSD séries e recorte
onnxruntime + OpenSeeFace osf_lm_model3_opt.onnx / osf_mnv3_detection_opt.onnx 1.32.0 MIT / BSD-2-Clause (pesos) plano B (só posição, sem expressões; sem linha de rosto ao analista). Pesos reais no face.py em 17/11/2026: rosto 96,7–100 %, 12,3–13,9 ms/quadro (MediaPipe no mesmo trecho: 94,4–100 %, 9,8–13,2)

Pesos fixados em clipper/models.lock.json (commit/caminho versionado + sha256), baixados em data/clipper/models/. Descartados por licença (não integrar): SCRFD/InsightFace (pesos não comerciais), YOLO-Face (GPL/AGPL), LibreFace (não comercial), OpenFace 3.0 (só pesquisa), Py-Feat (licença indefinida) — doc/PLANO_RASTREIO_REACAO.md.

Publicador (publisher/) — instalado, sem envio real registrado

Serviço FastAPI em 127.0.0.1:4530 (detalhes em publishing.md e publisher/README.md). Instalado no passo 6b2 do scripts/setup.ps1; versões fixadas em publisher/requirements*.txt. Evidência (17/11/2026): pnpm test:publisher → 71 passed (rede e navegador simulados; reconferido pela skill depois das revisões de segurança).

Ferramenta Versão verificada (17/11/2026, publisher/.venv) Papel
Python 3.12.13 publisher/.venv (criado pelo uv)
FastAPI / uvicorn / pydantic / httpx 0.159.1 / 0.54.0 / 2.14.1 / 0.28.1 HTTP do serviço e chamadas às APIs das redes
playwright (Python) 1.65.2 só o driver para connect_over_cdp no Chrome/Edge do usuário (não rodar playwright install)
pytest 9.1.1 pnpm test:publisher
Chrome ou Edge instalado versão da máquina (não registrada) modo sessão: aberto como processo normal, CDP em 4540–4549
DPAPI do Windows (CryptProtectData) do sistema cofre data/publisher/vault.bin

Planejadas ou candidatas — NÃO integradas

Ferramenta Para quê Situação
Meshy gerar modelos GLB (personagens, objetos) e rig citada na especificação; não testada
Mixamo animações para personagens com rig citada como não obrigatória; não testada
.glb carregado por GLTFDocument em tempo de execução (Godot) modelos prontos dentro de cenas da biblioteca (library/<id>/assets/) só documentado em doc/godot/cenas.md; nenhum .glb no repositório nem render com ele (17/11/2026). Personagens e barcos atuais são procedurais (godot/kits/)
Serviço de voz no render narração por fala e legenda automática a partir de X-Detail: words próxima etapa; scripts/lib/audio.ts ainda não chama o serviço
Applio pessoal + projetos de narração do usuário modelos RVC já treinados existe no PC do usuário; não instalar nem modificar; possível origem de .pth/.index para data/voice/models/rvc/<id>/ — não testado
Modelo RVC neutro pt-BR primeira voz de personagem e teste RVC ponta a ponta nenhum com licença clara: voice-models.com não tem pt-BR neutro; Adam (ElevenLabs), Jorge (Loquendo) e E-Girl têm licença não informada; no Hugging Face (16/11/2026) só imitações de personagem/dublador sem licença → não usar; user-voices.json segue sem voz
Azure Speech (motor azure, REST sem SDK, WAV riff-24khz-16bit-mono-pcm) 14 vozes neurais pt-BR azure-* (chave do usuário; plano F0 0,5 M caracteres/mês, informado) código pronto (AzureEngine em voice/app/engine.py, card no painel), mas sem chave real: testado só com urlopen simulado → não validado; nenhuma dependência nova
Vozes SAPI do Windows (Microsoft Maria Desktop pt-BR; Daniel/Maria OneCore) TTS local sem download existem na máquina; não integradas (robóticas)
Vozes "do TikTok/CapCut" famosas (Galvão Bueno, Ludmilla, narrador do CapCut Pro) — proprietárias ou imitação de pessoa real → não copiar. Equivalentes genéricos já no catálogo: Edge (Antonio/Francisca/Thalita) e Google
APIs oficiais: YouTube Data API v3, TikTok Content Posting API, Instagram API with Instagram Login envio pelo Publicador (publisher/app/platforms/*_api.py) código pronto, testado só com chamadas simuladas; nenhuma conta conectada nem envio real. Fatos e limites em doc/publicacao/PESQUISA.md (rupload do Instagram a testar)
Modo sessão logada (YouTube Studio, TikTok Studio, instagram.com) envio pelo site com a sessão do usuário código pronto, seletores não validados com conta real; viola os termos das redes
Chat do YouTube no Clipador sinal de chat em lives do YouTube exige a API do YouTube; não integrado (hoje só áudio + transcrição)
Saída AVI/MJPEG do Movie Maker reduzir o tempo gasto em PNG ideia; não medida

Não afirme que uma candidata "funciona" ou "está integrada" até haver evidência registrada aqui.

Como avaliar e adotar uma ferramenta nova

Antes de integrar, registre nesta tabela a resposta a cada item:

  1. Origem e licença — fonte oficial, licença de uso dos arquivos gerados, custo.
  2. Interface — CLI, API ou só interface gráfica; precisa de rede/conta? Funciona offline?
  3. Saída — formato (GLB, FBX, WAV…), escala, orientação dos eixos, materiais, esqueleto, animações incluídas. Lembre: rig corporal não garante lip sync nem atuação facial.
  4. Encaixe no pipeline — onde entra (preparação de assets, nunca dentro do render), qual nó adaptador corrige escala/orientação, como fica determinística.
  5. Teste mínimo — um asset/arquivo real passando pelo render de prévia, com inspeção visual.
  6. Versão fixada — versão exata testada, data, e onde o lançador a encontra.

Depois de adotada: mover para "Em uso", atualizar scripts/lib/tools.ts se o lançador a chama, README e a tabela "Onde mexer" do SKILL.md. Dependência Python do serviço de voz: fixe a versão em voice/requirements*.txt, peso novo em voice/models.lock.json com URL imutável (commit no Hugging Face — nunca resolve/main — ou asset de release versionado no GitHub) e sha256, e rode pnpm test:voice + a fumaça.