Files
CenaForge/.claude/skills/cenaforge/SKILL.md
T
MateuusandClaude Opus 5.5 f165659e4e Painel: ordenar fila de cortes, horário específico ao publicar e capas preservadas
Clipador (fila de cortes)
- Seletor "Ordenar": mais novos, mais antigos, maior/menor nota da IA, sinal
  mais forte e mais longos; a escolha fica lembrada no navegador.
- A fila abre filtrada pela sessão que está gravando.
- Gancho automático logo abaixo da câmera e legenda desviada enquanto o gancho
  a cobriria; posição do gancho editável no painel.

Publicação
- "Publicar este corte" ganha "Horário específico": um dia e hora para todas
  as redes ou um diferente por rede (timing "at" + scheduledAt por rede na rota
  POST /api/publishing/clips/[id]), com validação e testes.
- Capa do vídeo publicado copiada para output/publishing/covers/: apagar a
  sessão no Clipador não quebra mais a miniatura do dashboard; jobs antigos
  migram no ciclo de sincronização.
- Dashboard só usa capa que existe no disco; corrige a regex do número do
  episódio (link do episódio).
- Canais de publicação: seletor compacto de canais e detalhe reorganizado.
- Publicador: confirmação pela página pública quando o YouTube Studio fica com
  a caixa de envio aberta; estatísticas por rede.

Skill cenaforge 1.44.0 com as regras e a armadilha das capas.

Testes: painel 68/68, Clipador 279, Publicador 84.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 19:54:13 -03:00

29 KiB
Raw Blame History


name: cenaforge description: Produz e altera vídeos narrativos do projeto CenaForge — cena 3D (rua) ou do documentário (2D: título, contador, mapa do litoral de SP, kind: "doc2d"; 3D da biblioteca de cenas godot/library/, ex.: ilha com farol de dia/entardecer/noite, náufragos no costão, kind: "doc3d"; peças godot/kits/: pessoa articulada com poses e barco; cena dentro de outra) descrita por JSON, animada por tempo de cena na Godot, gravada pelo Movie Maker e convertida em MP4 pelo FFmpeg. Use sempre que o pedido envolver criar, renderizar ou ajustar um vídeo, episódio ou cena (câmera, movimento, cenário, personagem, moto, luz, texto e opções A/B, áudio, resolução), validar um MP4, gerar narração (TTS: Edge, Piper, Kokoro, Google, Azure Speech) ou escolher/filtrar voz, clonar voz a partir de uma gravação (Chatterbox, com consentimento), vozes de personagem (RVC/Applio) ou transcrição com tempos para legenda (.srt) pelo serviço de voz local ou pela página Vozes do painel, histórias interativas com vertentes e votação A–D, lineares ou documentais (vídeo único sobre fatos reais, com fontes) e onde ficam as regras de roteiro (doc/roteiro/), leitor de roteiro do painel (trechos, narração × duração alvo, fontes), criar cena 3D nova na biblioteca (template.gd + manifest.json, guia doc/godot/cenas.md, tarefa "Cena no Godot" do agente), montagem do vídeo documental em MP4 no painel ("Gerar vídeo automático" num clique: plano por regras, fotos reais do Wikimedia Commons, narração e cenas 2D/3D da Godot; "Gerar de novo" por trecho e "Refazer tudo do zero"; estilo "Tudo em 3D" com cartão de foto real por cima e cartões de informação em sequência; ou manual: áudio por trecho com números por extenso, visual por trecho — foto com fundo desfocado, animação 2D, cena 3D da biblioteca, clipe ou cartela —, texto na tela, legenda e créditos, pelo FFmpeg), excluir história no painel (vai para data/trash/), escolha de agente e modelo (Claude/Codex) no painel, mensagem ou correção ao agente durante a execução (Corrigir agora / Enviar ao terminar), termos episódio × vídeo na interface, contas e dashboard (métricas simuladas) do painel, Clipador (cortes automáticos de live da Twitch/Kick/YouTube, verticais 9:16 ou horizontais 16:9 para YouTube, com duração configurável e mínimo garantido, qualidade de gravação configurável até 2K: chat e emotes, heurística, varredura da IA, juízes analista e editor pela CLI, contexto do jogo e perfil do jogo editável/refinável pela IA, webcam achada sem IA e layout do corte, rastreio de reação do rosto do streamer (YuNet, MediaPipe, expressões que reforçam o corte), legenda com hashtags do canal, do jogo e do momento, editor de cortes em tela cheia no padrão de editor de vídeo, com timeline de uma trilha por camada e projeto de edição feito pela IA (trechos com layout próprio e trecho mudo, câmera inteira e editável na Fonte, legenda animada editável arrastando, gancho em tarja animada, fontes empacotadas, textos, zoom, reenquadramento do jogo com keyframes, camadas inseridas (recorte da tela em destaque), chat da live na tela, narração, música, capa também no início, export pelo FFmpeg), retomada de live que caiu, cortes duplicados descartados (o rejeitado ou apagado não volta), render que falha, fila de aprovação com apagar corte (um, selecionados ou a aba inteira), relógio da gravação e cadência do resumo no cartão da sessão, prévia do editor igual ao render (legenda e recorte), "não sai corte" (live fria × regras) e fontes ligadas aos canais de publicação), publicação automática em YouTube, TikTok e Instagram (serviço Publicador, canais de publicação, conectar rede pela API oficial ou sessão logada, aprovação manual ou automática, horários bons e limite por dia, botão "Publicar" no corte aprovado, inclusive sem fonte ligada e com "Horário específico" por rede, ordenar a fila de cortes, capa que sumiu do dashboard, fila "Publicações", Configurações, job que falhou, pede login ou pede "Confira na rede", "Já saiu: informar o link" quando o vídeo foi ao ar mas o job falhou, YouTube Studio que "não confirmou" a publicação, botão "Publicar no " nos cartões de Publicações), números dos posts (views, curtidas, comentários) lidos das redes e mostrados no Dashboard (leitura automática a cada N horas, "Atualizar números agora"), chamar a API do painel por script (cabeçalhos Origin e JSON; criar história com agente por POST /api/stories), agente que parou no limite de uso ou morreu ao reiniciar o painel, instalar/subir o projeto (setup.bat, start.bat, pnpm dev), ou trocar/adicionar ferramentas de 3D, voz ou render neste repositório — mesmo que o usuário não diga "skill" nem "CenaForge".

CenaForge — vídeo a partir de cena descrita por JSON

Versão da skill: 1.44.0 (17/11/2026) — histórico em CHANGELOG.md. Mantida pelo subagente cenaforge-skill-updater (ver "Manutenção" no fim).

Regra zero

O repositório é a fonte de verdade. Esta skill resume e aponta. Se algo aqui divergir do código, o código vence — siga o código e acione a manutenção da skill.

Documentos do projeto que você deve consultar quando o assunto for o deles:

  • README.md → comandos, contrato JSON completo (seção "Configuração de cena"), estrutura.
  • doc/TEST_RESULT.md → evidências, tempos medidos, problemas já resolvidos.
  • doc/PROMPT_TESTE_VIDEO_GODOT.md → especificação original e visão futura (seção 15).
  • voice/README.md → serviço de voz: instalação, vozes, contrato HTTP, GPU/CPU.
  • clipper/README.md → Clipador (cortes de live): heurística, juiz, API, .env, limites.
  • doc/publicacao/PLANO.md + PESQUISA.md → publicação nas redes (contratos, fatos datados); publisher/README.md → instalar o Publicador e criar o app de cada rede. Resumo para agir: references/publishing.md.

Para planejar, produzir ou publicar uma peça (episódio ou corte de live), siga a metodologia de 8 etapas da skill content-pipeline (.claude/skills/content-pipeline/SKILL.md): ela diz o que fazer e quando cada etapa está pronta; esta skill dá o como técnico de cada etapa.

Pipeline

config/<id>.json
  └─ pnpm render ─► output/runs/<data>-<id>-<perfil>/scene.json   (perfil aplica a resolução)
       ├─ Godot --headless --validate-only          valida o contrato (sem GPU)
       ├─ godot/override.cfg temporário             fixa a resolução do filme
       ├─ Godot --write-movie frame.png --fixed-fps N   (janela + GPU; quadro N ⇒ t = N/fps)
       ├─ confere PNGs (contínuos, quantidade, tamanho, não vazios)
       ├─ FFmpeg -start_number <aquecimento> → MP4 H.264 yuv420p (+ áudio AAC opcional)
       ├─ FFprobe (codec, dimensões, FPS, quadros decodificados, duração ±1 quadro)
       └─ inspect/ (quadros 0,5 s · 4 s · 8 s · 11 s extraídos do MP4) + report.json

Cenas do documentário, mesmo lançador e protocolo: kind doc2d ou doc3d faz o render.ts passar res://scenes/doc.tscn (godot/scripts/doc/doc_main.gd serve as duas). { id, kind, video: { width, height, fps, durationSeconds ≤ 120 }, template, params } — doc2d: template title|counter|map (params no cabeçalho de godot/scripts/doc/doc2d_canvas.gd); doc3d: template = pasta de godot/library/ (hoje island e castaways; cena inexistente → erro listando as disponíveis). params.variant (inteiro) muda layout/câmera. Prévia: pnpm render -- --config stories/<id>/godot/<file_key>-tNN.json --profile preview (2D: 2,7–4,3 s; ilha: 9–14 s; náufragos: 5,8–15,6 s, por 4–5 s de cena). template.gd que não compila reprova na validação (SCENE_SCRIPT_INVALID, código 2, Parse Error no render.log; gotchas 129). Cena 3D nova = pasta nova na biblioteca, seguindo doc/godot/cenas.md (contrato, manifesto, determinismo, kits godot/kits/, cena dentro de outra, teste olhando o inspect/); detalhes em references/panel.md.

Várias histórias (estrutura)

O quê Onde
Roteiros stories/<história>/biblia.md, stories/<história>/<file_key>.md (file_key = ep01, ep02-b…)
Opções do episódio (A–D) stories/<história>/<file_key>.choices.json
Cena do episódio config/<história>-<file_key>.json (ex.: new_scene.py --id <história>-ep02)
Assets da história / biblioteca stories/<história>/assets/<tipo>/<id>/ · assets/library/<tipo>/<id>/ (cada um com asset.json)
Estado (episódios, vertentes, votos, canais de publicação, fila de publicação, métricas, execuções) data/cenaforge.db (esquema v8; backup antes de migrar em data/backups/), gerido pelo painel (panel/, http://127.0.0.1:4500) — detalhes em references/panel.md
Serviço de voz voice/ (http://127.0.0.1:4510); clonagem em voice/clone/worker.py (127.0.0.1:4511, venv voice/.venv-clone); pesos e estado em data/voice/
Clipador (cortes de live) clipper/ (http://127.0.0.1:4520); banco e blocos em data/clipper/, cortes em output/clipper/<sessão>/ — ver references/clipper.md
Publicador (envio às redes) publisher/ (http://127.0.0.1:4530); dados em data/publisher/ — ver references/publishing.md
Portas locais faixa 4500–4599 (painel = 4500, voz = 4510, clonagem = 4511, Clipador = 4520, Publicador = 4530, navegador do modo sessão = 4540–4549)

Assets catalogados ainda não são carregados pela Godot (falta o nó adaptador de GLB). Formatos (stories.kind): interactive, linear e documentary (vídeo único sobre fatos reais, fonte por fato, sem A/B; vira MP4 pela montagem documental do painel, num clique). 1ª linha de stories/<id>/biblia.md: Formato: interativa | linear | documental. Regras de roteiro: fonte única em doc/roteiro/ (Claude via cenaforge-story-writer e Codex) — mudar regra de texto é editar esses .md, não o código. Interativa = 2–4 vertentes, mas o overlay só desenha choiceA/choiceB. Tabela, agentes e exclusão em references/panel.md. O painel é do usuário: não inicie/encerre pnpm panel.

Receita: fazer ou ajustar um vídeo

  1. pnpm run doctor (não pnpm doctor: no pnpm 11 é o diagnóstico do próprio pnpm).
  2. Copie config/demo-street.json para config/<id>.json e edite só o JSON se a mudança couber no contrato (textos, tempos, distância, cores, câmera, luz existente, seed, casas).
  3. pnpm render -- --config config/<id>.json --profile preview (42–44 s nesta máquina). Opções: --keep-frames (mantém os PNGs), --debug-frame-index (desenha quadro/tempo na imagem), --warmup-frames N (padrão 3). Reverificar um MP4: pnpm verify -- --file <mp4> (lê as expectativas do scene.json da mesma pasta).
  4. Leia o report.json da pasta da execução: status precisa ser success e todas as checks com ok: true.
  5. Olhe as imagens (inspect/contact-sheet.png e, se mexeu em movimento/câmera, uma tira de 1 quadro/s — ver "Validação"). Ajuste e repita.
  6. Só então --profile final (1080×1920, ~2 min 40 s).
  7. Ao responder, informe: caminho do MP4 e da config, comando exato, verificações que passaram, o que foi inspecionado visualmente e o que não foi (ex.: vídeo não assistido em player).

Onde mexer para cada tipo de mudança

Mudança Arquivo(s) Também atualizar
Texto, tempos, cor, câmera, preset de luz existente, seed config/*.json nada
Campo novo no JSON godot/scripts/core/scene_config.gd (validar + normalizar) tabela do README, exemplos em config/, godot/tests/run_tests.gd
Perfil de movimento godot/scripts/core/timeline_controller.gd testes de continuidade/determinismo
Enquadramento / preset de câmera godot/scripts/view/camera_controller.gd, CAMERA_PRESETS em scene_config.gd README
Cenário (rua, casas, postes, morro) godot/scripts/builders/street_builder.gd modo de fundo novo: BACKGROUND_MODES em scene_config.gd
Preset de luz dicionário LIGHTING em street_builder.gd + lista LIGHTING_PRESETS em scene_config.gd README
Moto e entregador godot/scripts/builders/rider_builder.gd (frente em −Z, WHEEL_RADIUS) asset novo: RIDER_ASSETS em scene_config.gd
Texto final / opções A/B godot/scripts/view/overlay_controller.gd —
Fachadas distantes godot/scripts/builders/facade_painter.gd → pnpm prepare-assets —
Cena 2D do documentário (modelo, desenho, lugar do mapa) contrato godot/scripts/doc/doc_config.gd (TEMPLATES_2D; doc3d validado contra godot/library/); desenho e PRESETS (costa, places) godot/scripts/doc/doc2d_canvas.gd; protocolo godot/scripts/doc/doc_main.gd (cena godot/scenes/doc.tscn) lugar novo: MAP_PLACES em panel/src/lib/montage-godot.ts igual a PRESETS.places; modelo novo: DOC2D_TEMPLATES e planScene no mesmo arquivo + SceneEditor em montage-editor.tsx
Cena 3D do documentário (nova ou ajuste) godot/library/<id>/template.gd (extends Node3D: setup(cfg, viewport_size), apply(t), state_signature()) + manifest.json; peças .gd da cena na pasta; peças gerais em godot/kits/ (person.gd, boat.gd, fora do painel); outra cena como cenário (embedded: true); referências godot/library/island/ e castaways/ nada no painel nem em godot/scripts/ (lista, formulário e escolha por keywords saem do manifesto); guia doc/godot/cenas.md
Render, conversão, verificação scripts/lib/render.ts (ramo doc2d/doc3d: cena doc.tscn, sem checagem da moto, MIN_AVERAGE_LUMA_DOC2D), frames.ts, verify.ts scripts/tests/launcher.test.ts
Áudio no MP4 (audio.file) scripts/lib/audio.ts testes do lançador
Serviço de voz (TTS, RVC, transcrição, Azure, clonagem) voice/app/ (engine.py, catalog.py, config.py, errors.py, rvc.py, stt.py, main.py) · worker voice/clone/worker.py voice/tests/, voice/README.md
Vozes padrão / pesos baixados voice/voices/catalog.json / voice/models.lock.json (URL fixada em commit + sha256) voice/README.md
Instalação / subida setup.bat → scripts/setup.ps1 (UTF-8 com BOM; passo 6b = Clipador, 6b2 = Publicador) · start.bat → scripts/dev.ts README.md
Publicação nas redes (Publicador, despachante, canais de publicação, fila, Configurações) publisher/app/ · panel/src/lib/ (publisher.ts, publishing.ts, publishing-rules.ts, dispatcher.ts, settings.ts) · panel/src/instrumentation.ts · botão "Publicar" do corte components/clip-publish.tsx · números dos posts: publisher/app/platforms/stats.py + session/stats.py, panel/src/lib/metrics-sync.ts, metrics.ts, components/metrics-view.tsx, dashboard-controls.tsx — tabela em references/publishing.md publisher/tests/ (test_stats.py), panel/src/lib/publishing-*.test.ts, doc/publicacao/PLANO.md se mudar o contrato
Localizar executáveis / encoders scripts/lib/tools.ts references/tools.md
Painel: páginas, API, votação, agentes (prompt por provedor, lista de modelos models(), mensagem durante a execução sendFollowUp) panel/src/app/, panel/src/lib/ (agents.ts, prompts.ts, decisions.ts, assets.ts, renders.ts); console em components/agent-console.tsx panel/README.md; AGENTS.md se mudar regra do Codex
Painel: página Vozes (/voices) servidor panel/src/lib/voice.ts + panel/src/app/api/voice/*; cliente panel/src/components/voice-*.ts(x) (voice-client.ts tipos e uploadWithProgress; voice-cards.tsx catálogo e filtros; voice-clone-form.tsx; AzureForm em voice-studio.tsx) voice/README.md se mudar o contrato; largura de Select/Input: gotchas item 62
Regra de roteiro (idioma, overlay, ficção, documental, formato de biblia.md/epNN.md) doc/roteiro/comum.md, ficcao.md, documental.md nada no código; .claude/agents/cenaforge-story-writer.md só aponta para lá
Painel: vertentes, votação A–D, contas, dashboard, excluir história (deleteStory), migração do banco branches.ts, decisions.ts, flow.ts, accounts.ts, metrics.ts, stories.ts, db.ts em panel/src/lib/ — ver references/panel.md panel/README.md
Clipador: captura e qualidade de gravação (capture.py), retomada de live, chat/emotes, heurística, duplicados, varredura, juízes, jogo, formato (vertical/horizontal), duração mínima (fit_window), layout/webcam, rastreio de reação (rosto), legenda, gancho/tarja e fontes (assets/fonts/), reenquadramento e camadas inseridas (reframe.py), render, apagar cortes (clip_delete.py, tabela deleted_clips), editor de cortes, página /clipper, canais nas contas clipper/app/ · panel/src/lib/clipper.ts (regex ALLOWED, métodos METHODS + timeout por rota) · panel/src/components/clipper-*.tsx e clip-editor*.ts(x) — tabela em references/clipper.md clipper/tests/, clipper/README.md; peso novo em clipper/models.lock.json (URL imutável + sha256)
Hashtags da legenda do corte (canal, jogo, momento) clipper/app/hashtags.py (+ judge.py, intel.py, worker.py; painel clipper-games.tsx) — ver references/clipper.md clipper/tests/test_hashtags.py
Painel: leitor de roteiro (trechos, narração, fontes; página /stories/[storyId]/episodes/[number]/roteiro) parser puro panel/src/lib/script-doc.ts (parseScript, WORDS_PER_SECOND) + panel/src/components/script-reader.tsx — ver references/panel.md formato do roteiro em doc/roteiro/ (cabeçalho da tabela de trechos)
Painel: montagem documental (um clique ou manual; estilo mixed/3d; áudio, visual e cartão de foto por trecho → MP4) estado/banco/modo automático/"Gerar de novo" panel/src/lib/montage.ts; FFmpeg sem banco montage-ffmpeg.ts (cartão, textos em sequência); plano do trecho (planShot, planShot3d) e render Godot sem banco montage-godot.ts; biblioteca scene-library.ts; fotos image-search.ts; fala por extenso speech-text.ts; UI components/montage-editor.tsx; rotas app/api/episodes/[id]/montage/ — ver references/panel.md doc/roteiro/comum.md e documental.md se mudar regra de narração/trecho
Painel: formato de história novo item em STORY_FORMATS (panel/src/components/story-formats.ts) + StoryKind/STORY_KINDS (panel/src/lib/types.ts) + migração do CHECK de stories.kind (db.ts) + GUIDE_BY_KIND/FORMAT_LABEL em prompts.ts (+ guia novo em doc/roteiro/ se as regras forem outras) + termo da unidade em unitTerms (story-formats.ts) select com descrição: DescribedSelect em forms.tsx; layout do Fluxo em story-flow.tsx
Painel: pedir confirmação / mostrar aviso (nunca confirm()/alert() nativos) askConfirm/showAlert/confirmSubmit de panel/src/components/confirm-dialog.tsx (host único já em app/layout.tsx) — ver references/panel.md —
Painel: modal com conteúdo ou passo a passo Dialog + Steps de panel/src/components/dialog.tsx (padrão para todo modal novo) —
Painel: logo / ícones panel/src/components/logo.tsx e panel/src/app/icon.svg juntos (grade de 32); ícones em icons.tsx com shrink-0 —
Ferramenta nova (gerador 3D, motor de voz…) ver references/tools.md esta skill, via manutenção

Invariantes — não quebrar

  • Estado visual = função pura de t. Em render, t = quadro / fps; nunca use delta nem relógio do sistema para posição, câmera ou overlay. evaluate_at_time(t) é a única fonte.
  • Determinismo: aleatoriedade só pelo RandomNumberGenerator com a seed da config. A mesma config gera o mesmo stateDigest (prévia e final iguais). Se o digest mudar sem você ter mexido em movimento/câmera/overlay, algo saiu do controle.
  • Convenção da cena: Y é altura, a moto anda em −Z, a câmera fica atrás em +Z. Modelo importado entra por nó adaptador, não mudando a convenção.
  • Sem class_name nos scripts: o projeto roda sem importação do editor. Use const X := preload("res://...").
  • Caminhos relativos partem da raiz do repositório (Godot e lançador). Em --write-movie, use sempre caminho absoluto.
  • Subprocesso sem shell, argumentos em lista; código ≠ 0, timeout ou cancelamento é falha.
  • JSON nunca vira código; campos desconhecidos são rejeitados.
  • Identificadores em inglês; comentários, mensagens e textos de UI em português.
  • Publicação: nunca marque published sem ID/URL remota; nada sai sem aprovação (humana ou automática ligada pelo usuário); modo sessão só com o usuário logando à mão — sem stealth, captcha ou senha automatizada. Agente não dispara envio real sem pedido do usuário: para testar, use as suítes (sem rede). Regras em references/publishing.md.
  • API do painel (/api/**, guarda em panel/src/proxy.ts): só Host local; POST/PUT/PATCH/DELETE por script mandam Origin: http://127.0.0.1:4500 e Content-Type: application/json (sem eles: 403/415 — gotchas, item 125).
  • Fora do escopo atual: Meshy. O Applio do serviço de voz é uma cópia própria em voice/vendor/applio; o Applio pessoal do usuário não se instala nem se modifica.

Voz e legenda

Fonte: voice/README.md (vozes, campos do catálogo por motor, Azure, clonagem, contrato HTTP, GPU/CPU). Não duplique aqui. Resumo para agir:

  • Instalar: setup.bat (opções -NoRvc, -Cpu, -Clone). Subir: start.bat ou pnpm dev (painel 4500 + voz 4510 + clonagem 4511 se voice/.venv-clone existir + Clipador 4520 + Publicador 4530); só a voz: pnpm voice. Testes: pnpm test:voice (pytest, motores falsos), pnpm test:clipper e pnpm test:publisher. Porta ocupada ou parte não instalada = aviso e o resto sobe.
  • Painel → Vozes (/voices): Catálogo (sub-abas por motor, busca, filtros, ouvir, voz de personagem .pth + .index com origem e licença, voz clonada, testar .srt) e Serviço (dispositivo, Whisper, RVC, Azure). Configurações gravam voice/.env e o scripts/dev.ts reinicia voz e clonagem sozinho.
  • Toda rota, exceto GET /health, exige X-Service-Key (VOICE_SERVICE_KEY em voice/.env; o worker de clonagem usa a mesma). Nunca copie chaves (serviço, Azure) para a skill nem para logs.
  • Catálogo voice/voices/catalog.json: 76 vozes (12 Edge, 3 Piper, 45 Kokoro, 2 Google, 14 Azure; contagens e motores em voice/README.md e references/tools.md). Padrão pt-br-antonio (Edge). Offline: Piper e Kokoro (pt-BR nativas kokoro-pf-dora fem., kokoro-pm-alex, kokoro-pm-santa). Online (502 engine_unavailable sem internet): Edge, Google e Azure — sem VOICE_AZURE_KEY as vozes Azure somem; chave pelo painel (PUT /api/voice/azure, nunca volta ao cliente) ou voice/.env.
  • Voz nova no catalog.json (peso no models.lock.json com URL imutável + sha256) aparece sozinha (_refresh_voices_if_changed em voice/app/main.py; POST /v1/voices/reload força). Mudança de código em voice/app/ ou motor novo exige reiniciar o start.bat (gotchas, item 53).
  • Vozes do usuário: data/voice/user-voices.json. Personagem = voz base + RVC (sem Applio: 501 rvc_disabled; .pth que não é RVC: 422 rvc_failed).
  • Voz clonada (kind: "clone", Chatterbox; detalhes em voice/README.md): gravação de 10–30 s, consentimento obrigatório (consent: true); worker fora → 503 clone_unavailable; ignora speed; texto longo em partes (gotchas, item 66). Nunca imite pessoa real sem autorização.
  • Narração para vídeo: POST /v1/synthesize com params.format: "wav"; legenda: POST /v1/transcribe com X-Detail: words (palavras com start/end).
  • O render da Godot não chama o serviço (a montagem documental chama: um áudio por trecho, e a cena Godot dura a fala + pausa). Na cena da rua, gere o WAV e aponte audio.file (com audio.enabled: true).
  • Fumaça (serviço no ar): voice/.venv/Scripts/python voice/scripts/smoke.py --detail words. VOICE_DEVICE=auto só olha a GPU na subida: jogo aberto depois → troque o dispositivo em Vozes (gotchas, "Serviço de voz").

Validação antes de dizer "pronto"

  1. pnpm test (lançador + Godot headless) e pnpm typecheck.
  2. Render de prévia com status: success.
  3. Inspeção visual lendo os PNGs de inspect/. Critérios: nada preto; câmera fora de geometria; personagem apoiado na moto; perspectiva dos objetos próximos muda; rodas giram; fundo sem rotação nem borda de plano aparente; texto sem corte e legível; luz consistente. Cena 3D do documentário: checklist de doc/godot/cenas.md (assunto no meio da tela vertical, horizonte sem emenda, variant 0/1/2 diferentes).
  4. Movimento/câmera alterados → tira de 1 quadro por segundo:
    ffmpeg -i <mp4> -vf "select='not(mod(n\,<fps>))',scale=180:-1,tile=<colunas>x<linhas>" -frames:v 1 -fps_mode vfr <pasta-da-execução>/inspect/strip.png
    
    colunas × linhas ≥ duração em segundos (7x2 serve até 14 s). Os quadros de inspect/ são fixos em 0,5 · 4 · 8 · 11 s (INSPECTION_TIMES em render.ts; tempos ≥ duração são pulados, então cena 2D curta só tem 0,5 e 4 s); acima de 12 s, ou para ver o fim de uma cena 2D, use a tira.
  5. Diga separadamente: código escrito, testes, MP4 gerado, inspeção visual feita/pendente.

Economia de tokens

Use os scripts de .claude/skills/cenaforge/scripts/ (runs_summary.py, inspect_strip.py, new_scene.py, check_skill.py, clean_runs.py, frame_check.py, check_script.py). Cena: frame_check.py --last e abra no máximo UMA imagem por render; roteiro: check_script.py stories/<história>. Enredo, diálogos e textos A/B → subagente cenaforge-story-writer (segue doc/roteiro/). Quem faz o quê: references/token-economy.md; repetitivo ou caro → cenaforge-token-auditor.

Armadilhas já conhecidas

Leia references/gotchas.md antes de mexer em render, resolução, tempo, GDScript, pnpm, painel, serviço de voz, Clipador ou publicação. Resumo: 1º quadro da Godot sai incompleto (aquecimento de 3 quadros); delta não é 1/fps; resolução fixada na inicialização (override.cfg); --write-movie relativo falha em silêncio com código 0; regex em node -e/heredoc no bash perde as barras invertidas (item 44: edite pelo Edit); reiniciar o pnpm panel mata o agente em execução e o limite de uso do Claude/Codex para a tarefa no meio — continue no outro provedor (itens 131–132); Claude do painel com OAuth expirado e gasto alto de tokens dos agentes (133–135); modo sessão "navegador abriu mas não respondeu" com a porta viva (Chrome 157 sem DevToolsActivePort, 137); "no column named origin" ao publicar corte com o pnpm dev ligado desde antes da v7 (138: migra sozinho na 1ª requisição depois da recarga do db.ts); envio de corte > 50 MB no modo sessão recusado com "Cannot transfer files larger than 50Mb" (139: is_local=True no connect_over_cdp; a mensagem ao usuário é a genérica "navegador travou"); TikTok publicou mas o job falhou sem o link (140: find_video_url recarrega a lista por ~3 min; use "Já saiu: informar o link"); job novo cancelado por regra antiga porque o laço do despachante guarda o tick velho no HMR (141); TikTok em modo sessão com "Locator.click: Timeout" na legenda por aviso "Entendi" por cima (142: click_through/dismiss_tips, só fechar avisos); correção que "não pegou" = serviço Python rodando código antigo (sem --reload): compare o início do processo com o LastWriteTime do arquivo antes de validar (143); legenda com #RobRun/#ROBRUN ou perfil do jogo sem hashtags (144); Instagram em modo sessão com "não achei o botão" (o botão agora é "Postar" e os botões do fluxo ficam presos ao diálogo, 145) e rótulo de IA coberto pela lista de hashtags (sem force=True, 146; valide seletor com prepare, sem publicar); reel do Instagram saindo 1:1 (formato "Original" em keep_original_shape, 147); corte nunca leva rótulo de IA (148); vídeo apagado na rede: ação "Apaguei na rede" (149); script python -I ignora PYTHONIOENCODING (150); YouTube "não confirmou" mas o vídeo saiu (ytcp-button, 151); números do Instagram sem curtidas (grade antes da API, 152); curl -d com acento no Git Bash (153: --data-binary @arquivo); repositório Gitea PÚBLICO: procure segredos antes de subir, commit só a pedido (154); capa de vídeo publicado some ao apagar a sessão do Clipador (155: cópia em output/publishing/covers/); .tsx/.ts do painel em CRLF (63).

Manutenção desta skill

Depois de qualquer melhoria que mude como o projeto funciona, acione o subagente cenaforge-skill-updater com: o que mudou e por quê, arquivos tocados e evidência (comando + resultado). Não edite à mão no meio de outra tarefa.