Gerador de vídeos narrativos (Godot + FFmpeg), painel Next.js, serviço de voz, Clipador de lives e Publicador para YouTube, TikTok e Instagram. Inclui a leitura das visualizações dos posts para o Dashboard e o botão "Publicar no <rede>" nos cartões das publicações. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
229 lines
28 KiB
Markdown
229 lines
28 KiB
Markdown
---
|
||
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, 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), 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.42.0** (17/11/2026) — histórico em [CHANGELOG.md](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](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](references/panel.md#biblioteca-de-cenas-3d-godotlibrary).
|
||
|
||
## 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 v7; backup antes de migrar em `data/backups/`), gerido pelo painel (`panel/`, http://127.0.0.1:4500) — detalhes em [references/panel.md](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](references/clipper.md) |
|
||
| Publicador (envio às redes) | `publisher/` (http://127.0.0.1:4530); dados em `data/publisher/` — ver [references/publishing.md](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](references/panel.md#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](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` — tabela em [references/publishing.md](references/publishing.md) | `publisher/tests/`, `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](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](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](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](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](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](references/panel.md#montagem-documental) | `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](references/panel.md#confirmação-e-aviso-componentsconfirm-dialogtsx) | — |
|
||
| 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](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](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](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:
|
||
```sh
|
||
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](references/token-economy.md); repetitivo ou caro →
|
||
**`cenaforge-token-auditor`**.
|
||
|
||
## Armadilhas já conhecidas
|
||
|
||
Leia [references/gotchas.md](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).
|
||
|
||
## 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.
|