Estilo Cartoon (novo, sem Godot) - Pacote cartoon/ (Remotion 4.0.535): cada trecho é um spec JSON desenhado em React/SVG e renderizado em MP4; render em lote (empacota uma vez) e imagem parada (--still). - Cenas montadas por peças, sem cenário pronto: paletas (noite, sépia, dia, entardecer, cinza), lugar com chão, interno/externo, névoa e 24 peças posicionadas por profundidade, foco de luz e vinheta; etiquetas, onomatopeias, ondas de som, X vermelho, painel do topo e legenda palavra por palavra. - Montagem documental: "Cartoon" como estilo do vídeo e tipo de visual do trecho; plano por regras pelo texto (lugar, objetos, expressão, pose), tempos das palavras pela transcrição do áudio, "Gerar de novo" por trecho, paleta da série e elenco da história. Personagens - Aba Personagens: criar pela descrição, ajustar peça por peça com prévia ao vivo, refinar com o agente (tarefa nova "Personagem"); fichas em assets/characters/ e elenco em stories/<id>/cast.json. O mesmo personagem sai igual em qualquer cena, mudando expressão, pose e objeto na mão. TikTok - Hashtags passam a ser digitadas e confirmadas na lista de sugestões do TikTok Studio (coladas, viravam texto). Diagnóstico de alcance em doc/publicacao/TIKTOK_DIAGNOSTICO.md. Docs: estudo das referências, doc/cartoon/ (personagens e cenas) e skill cenaforge 1.46.0. Testes: painel 77/77, cartoon 5/5, Publicador 87/87. 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); 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, 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.46.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
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 |
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/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) | 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; 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.
- 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 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); Cartoon: voz não dá tempo por palavra (156), plano genérico sem lugar reconhecido (157), exemplo vazando em todo trecho por defaultProps (160), palavra-chave do plano errando o assunto (161) e \b virando 0x08 em edição por script (162); TikTok com #tag colada vira texto (158: digitar e confirmar a sugestão; falta validar com vídeo real); páginas públicas do TikTok em série devolvem SlardarWAF (159).
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.