- Configurações → IA (/settings/ai): um cartão por IA para instalar/atualizar a CLI pelo painel, ligar, entrar com a conta (OAuth pela própria CLI, num terminal) ou colar a chave de API, e testar. Chaves cifradas com a DPAPI do Windows em data/ai/vault.bin; só vão para a CLI no ambiente da chamada. - Gemini CLI como terceiro agente do painel (stream-json, edição automática, shell só o liberado). - IA reserva: execução que cai por indisponibilidade (cota, 429, login, chave, rede) pausa a IA e recomeça a mesma tarefa na próxima pronta da ordem; migração v10 (agent_runs.fallback_of). - Configurações viraram subpáginas (IA, Publicação, Apps das redes, Navegador, Sobre os modos), também no menu lateral; links antigos apontam para a subpágina certa. - Contrato com o Clipador em doc/ia.md; skill do CenaForge atualizada até a 1.51.0. O login gratuito do Gemini CLI para conta pessoal foi encerrado pelo Google (IneligibleTierError): para conta pessoal, use a chave do AI Studio. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
31 KiB
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; estilo "Cartoon" (desenho 2D em Remotion, pacote cartoon/: lugares montados por peças a partir do texto, sem cenário pronto; biblioteca de personagens criados uma vez e reaproveitados entre histórias — aba "Personagens", elenco por história, agente "character" —; paleta da série, etiquetas, onomatopeias e legenda palavra por palavra; personagem com rig de expressões e ações de movimento combináveis, fala sincronizada com a narração, acabamento de ilustração: formato de cabeça, nariz, pálpebra, rugas, acessórios de profissão, enquadramento close/medium e textura de papel); 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 Code, Codex ou Gemini CLI) no painel, IA (provedores, entrar com a conta ou chave de API no cofre, ordem e IA reserva quando uma cai por cota/login/rede, Configurações em subpáginas), 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 bilíngue (português para ler, inglês para a IA) editável/refinável pela IA, com missões, gatilhos de fim de missão e outros nomes (aliases), cadastro e apagar jogo pelo painel, tradução do perfil e semente do GTA VI, 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), interface em subpáginas (Cortes com modal, Sessões, Fontes, Jogos, Ajustes), parar a sessão à mão (pausa o monitor da fonte, "Religar"), idioma da fonte, da sessão e do canal de publicação (en-US, es-419), 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, hashtag do TikTok que não vira hashtag (legenda colada), 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.51.0 (18/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 v10; 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
pnpm run doctor(nãopnpm doctor: no pnpm 11 é o diagnóstico do próprio pnpm).- Copie
config/demo-street.jsonparaconfig/<id>.jsone edite só o JSON se a mudança couber no contrato (textos, tempos, distância, cores, câmera, luz existente, seed, casas). 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 doscene.jsonda mesma pasta).- Leia o
report.jsonda pasta da execução:statusprecisa sersuccesse todas ascheckscomok: true. - Olhe as imagens (
inspect/contact-sheet.pnge, se mexeu em movimento/câmera, uma tira de 1 quadro/s — ver "Validação"). Ajuste e repita. - Só então
--profile final(1080×1920, ~2 min 40 s). - 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 |
| IA: provedores (Claude/Codex/Gemini), login ou chave, cofre, IA reserva, Configurações → IA | panel/src/lib/ai.ts (+ agents.ts, app/api/ai/), components/ai-settings.tsx, settings-shell.tsx; juiz: clipper/app/ai_settings.py, judge.py — contrato doc/ia.md, resumo em references/ai.md |
panel/src/lib/ai.test.ts, clipper/tests/test_ai_fallback.py |
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áginas /clipper/* (grupo (studio)), pausa do monitor e idioma, canais nas contas |
clipper/app/ · panel/src/lib/clipper.ts (regex ALLOWED, métodos METHODS + timeout por rota) · panel/src/components/clipper-*.tsx (moldura clipper-shell.tsx, páginas em panel/src/app/clipper/(studio)/) 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/cartoon; á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 |
Estilo Cartoon: lugar por peças (places.tsx, LOCATIONS em montage-cartoon.ts), contrato spec.ts, plano pelo texto, legenda por palavra, paleta da série |
cartoon/src/ + cartoon/render.ts + panel/src/lib/montage-cartoon.ts, montage.ts, montage-editor.tsx (CartoonSetup) — lugar novo = peça/regra, nunca cena pronta; guia doc/cartoon/cenas.md; tudo em references/cartoon.md |
cartoon/tests/spec.test.ts, panel/src/lib/montage-cartoon.test.ts; Remotion em references/tools.md |
Personagem do Cartoon (criar uma vez, reaproveitar em várias histórias; elenco por história) e sua expressão/movimento/fala (rig.ts, motion.ts, lipsync.ts: parâmetros e ações combináveis, não animação pronta; guia doc/cartoon/animacao.md; acabamento de ilustração: look com cabeça/nariz/pálpebra/rugas/barriga/acessórios, grain, framing) |
contrato cartoon/src/character.ts, desenho CharacterFigure.tsx; panel/src/lib/characters.ts, app/api/characters/, app/characters/, components/character-studio.tsx; ficha assets/characters/<id>/character.json, elenco stories/<id>/cast.json; agente character (prompts.ts, agents.ts) — references/cartoon.md |
doc/cartoon/personagens.md, animacao.md; cartoon/tests/motion.test.ts, testes do painel |
| 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 usedeltanem relógio do sistema para posição, câmera ou overlay.evaluate_at_time(t)é a única fonte. - Determinismo: aleatoriedade só pelo
RandomNumberGeneratorcom aseedda config. A mesma config gera o mesmostateDigest(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_namenos scripts: o projeto roda sem importação do editor. Useconst 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.
- Chave de API das IAs só pelo cofre do painel (
data/ai/vault.bin, DPAPI) e só no ambiente da chamada; nunca em arquivo, log, prompt ou nesta skill; não troque o login global das CLIs (semcodex login --with-api-key). - Publicação: nunca marque
publishedsem 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 empanel/src/proxy.ts): só Host local; POST/PUT/PATCH/DELETE por script mandamOrigin: http://127.0.0.1:4500eContent-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.batoupnpm dev(painel 4500 + voz 4510 + clonagem 4511 sevoice/.venv-cloneexistir + Clipador 4520 + Publicador 4530); só a voz:pnpm voice. Testes:pnpm test:voice(pytest, motores falsos),pnpm test:clipperepnpm 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+.indexcom origem e licença, voz clonada, testar.srt) e Serviço (dispositivo, Whisper, RVC, Azure). Configurações gravamvoice/.enve oscripts/dev.tsreinicia voz e clonagem sozinho. - Toda rota, exceto
GET /health, exigeX-Service-Key(VOICE_SERVICE_KEYemvoice/.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 emvoice/README.mde references/tools.md). Padrãopt-br-antonio(Edge). Offline: Piper e Kokoro (pt-BR nativaskokoro-pf-dorafem.,kokoro-pm-alex,kokoro-pm-santa). Online (502 engine_unavailablesem internet): Edge, Google e Azure — semVOICE_AZURE_KEYas vozes Azure somem; chave pelo painel (PUT /api/voice/azure, nunca volta ao cliente) ouvoice/.env. - Voz nova no
catalog.json(peso nomodels.lock.jsoncom URL imutável + sha256) aparece sozinha (_refresh_voices_if_changedemvoice/app/main.py;POST /v1/voices/reloadforça). Mudança de código emvoice/app/ou motor novo exige reiniciar ostart.bat(gotchas, item 53). - Vozes do usuário:
data/voice/user-voices.json. Personagem = voz base + RVC (sem Applio:501 rvc_disabled;.pthque não é RVC:422 rvc_failed). - Voz clonada (
kind: "clone", Chatterbox; detalhes emvoice/README.md): gravação de 10–30 s, consentimento obrigatório (consent: true); worker fora →503 clone_unavailable; ignoraspeed; texto longo em partes (gotchas, item 66). Nunca imite pessoa real sem autorização. - Narração para vídeo:
POST /v1/synthesizecomparams.format: "wav"; legenda:POST /v1/transcribecomX-Detail: words(palavras comstart/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(comaudio.enabled: true). - Fumaça (serviço no ar):
voice/.venv/Scripts/python voice/scripts/smoke.py --detail words.VOICE_DEVICE=autosó olha a GPU na subida: jogo aberto depois → troque o dispositivo em Vozes (gotchas, "Serviço de voz").
Validação antes de dizer "pronto"
pnpm test(lançador + Godot headless) epnpm typecheck.- Render de prévia com
status: success. - 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 dedoc/godot/cenas.md(assunto no meio da tela vertical, horizonte sem emenda,variant0/1/2 diferentes). - Movimento/câmera alterados → tira de 1 quadro por segundo:
colunas × linhas ≥ duração em segundos (7x2 serve até 14 s). Os quadros de
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.pnginspect/são fixos em 0,5 · 4 · 8 · 11 s (INSPECTION_TIMESemrender.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. - 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, publicação ou Cartoon. As que mais custam caro:
- 1º quadro da Godot sai incompleto (aquecimento de 3 quadros);
deltanão é 1/fps; resolução fixada na inicialização (override.cfg);--write-movierelativo falha em silêncio com código 0. - Regex em
node -e/heredoc/Python sem string raw perde ou corrompe\e(itens 44 e 162): edite pelo Edit. - Reiniciar o
pnpm panelmata o agente em execução; limite de uso: a IA reserva recomeça a tarefa sozinha; sem ela, continue à mão no outro provedor (131–135, 168–172; references/ai.md). - Correção que "não pegou" = serviço Python rodando código antigo (sem
--reload): compare o início do processo com oLastWriteTimedo arquivo antes de validar (143). - IA, login e chave (168–172). Publicação/modo sessão (137–155, 158–159), Cartoon (156, 157, 160–165) e Clipador (144, 166, 167): ver o item citado em gotchas.
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.