CenaForge: primeira versão pública

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>
This commit is contained in:
2026-11-17 16:35:09 -03:00
co-authored by Claude Opus 5.5
commit 84f30bbc2d
484 changed files with 74826 additions and 0 deletions
+670
View File
@@ -0,0 +1,670 @@
# Histórico da skill cenaforge
Versão semântica da **skill** (não do projeto):
- **patch** — correção de texto, dado ou caminho;
- **minor** — capacidade, ferramenta, preset, comando ou armadilha nova;
- **major** — mudança incompatível no contrato JSON ou no pipeline.
Mantido pelo subagente `cenaforge-skill-updater`. Entradas mais novas no topo.
## 1.42.0 — 17/11/2026
Instagram sem corte quadrado, corte sem rótulo de IA e ação "Apaguei na rede".
- `references/publishing.md`: regra do formato "Original" (`keep_original_shape`), corte nunca leva rótulo de IA, ação
`removed`/`markRemoved`; evidência do 1º reel real.
- `references/gotchas.md`: itens novos 147 (reel 1:1; `common.find` olha até 6 ocorrências), 148 (rótulo de IA em corte;
"Perfil gerado por IA" provavelmente do perfil, não confirmado), 149 ("Apaguei na rede"), 150 (`python -I` e
`PYTHONIOENCODING`).
- `SKILL.md`: versão e resumo de armadilhas.
- Evidência: `pnpm test:publisher` → 78 passed (reexecutado). Informados, não reexecutados: `test:panel` 66/66, typecheck,
ensaio ao vivo sem publicar. Não verificado: publicação real com o formato novo (precisa reiniciar o `pnpm dev`).
## 1.41.0 — 17/11/2026
Modo sessão do Instagram: botão "Postar", seletores presos ao diálogo, `prepare`/`upload`, rótulo de IA e link do reel.
- `references/publishing.md`: regra "Instagram em modo sessão" (fluxo, `prepare` sem clicar, `find_ai_switch`,
`close_suggestions`, `find_reel_url`, ensaio sem publicar, o que foi e o que não foi validado); evidência; linha do
"Primeiro envio real" atualizada.
- `references/gotchas.md`: itens novos 145 (botão Postar e "Compartilhar" do feed) e 146 (sugestões de hashtag por cima do
rótulo de IA; sem `force=True`); nota "Relacionadas".
- `SKILL.md`: versão e resumo de armadilhas.
- Evidência: `pnpm test:publisher` → 78 passed (reexecutado). Informado, não reexecutado: ensaio ao vivo com conta real.
Não verificado: Compartilhar, confirmação e `find_reel_url` com conta real; falta reiniciar o `pnpm dev`.
## 1.40.0 — 17/11/2026
Hashtags da legenda dos cortes, espera do link do TikTok com recarga da lista e armadilha do serviço com código antigo.
- `references/clipper.md`: seção "Hashtags da legenda" (`hashtags.py`: `to_tag`, `fold`, `split_hashtags`, `compose`,
`build_caption`; campo `hashtags` no veredito e no perfil do jogo; painel), linha em "Onde mexer", `hashtags` no `PUT
/v1/games`, evidência e "Não verificado".
- `references/publishing.md`: `find_video_url` com 12 cargas × 5 leituras (~3 min) e progresso; mensagem do painel
"Saiu na rede…" (`readPublisherJob`); evidência.
- `references/gotchas.md`: item 140 atualizado (2ª versão); itens novos 143 (processo mais antigo que o arquivo: rodou código
antigo) e 144 (hashtags do perfil/cortes antigos).
- `SKILL.md`: versão, `description`, linha em "Onde mexer" e resumo de armadilhas.
- API do perfil: `GameRefineIn.section` aceita `"hashtags"` e `GameProfileIn.hashtags` (máx. 20) evita apagar as tags ao
salvar o perfil à mão (corrigido pelo coordenador; registrado em `clipper.md`).
- Evidência: `pnpm test:clipper` → 278 passed e `pnpm test:publisher` → 76 passed (ambos reexecutados). Informados, não
reexecutados: `test:panel` 65/65, typecheck, validação ao vivo do link.
## 1.39.0 — 17/11/2026
Modo sessão (TikTok): aviso de novidade do Studio bloqueava o clique na legenda.
- `references/gotchas.md`: item 142 (sintoma, causa, `TIP_BUTTONS`/`dismiss_tips`/`click_through`, regra de só fechar
avisos "entendi", mensagens de `browser_error_text`, testes); nota "Relacionadas".
- `references/publishing.md`: linha do modo sessão (`click_through`, `dismiss_tips`, `browser_error_text`), regra "Avisos de
novidade do site", evidência.
- `SKILL.md`: versão e resumo de armadilhas.
- Evidência: `pnpm test:publisher` → 76 passed (reexecutado); funções, usos em `tiktok_studio.py`, testes e captura
`20261117-134508` conferidos. Não verificado: envio real depois da correção (falta reiniciar o `pnpm dev`); a imagem
não foi aberta (o aviso é o descrito por quem chamou).
## 1.38.0 — 17/11/2026
Primeiro post real no TikTok (modo sessão), link do vídeo e ação "Já saiu: informar o link".
- `references/publishing.md`: regra do link do TikTok (`find_video_url`, `caption_key`), ação `mark-published`
(`parseVideoUrl`, `markPublished`, rota, UI), registro do primeiro envio real, evidência; nota do `tick` no despachante;
removida a frase "nenhuma rede teve envio real" (TikTok validado; YouTube/Instagram em sessão seguem sem validação).
- `references/gotchas.md`: itens 140 (publicou sem confirmar o link) e 141 (`tick` do despachante preso no HMR).
- `SKILL.md`: versão, `description` e resumo de armadilhas.
- Evidência: `pnpm test:publisher` → 74 passed (reexecutado); `find_video_url`, `parseVideoUrl`, `markPublished`, rota,
UI e bloco do `tick` conferidos no código. Informados e não reexecutados: `test:panel` 65/65, typecheck, validação ao
vivo da lista, o post real. Pendente: reiniciar o `pnpm dev` para valer `find_video_url` e `is_local`.
## 1.37.0 — 17/11/2026
Modo sessão do Publicador: envio de arquivo > 50 MB (cortes de 100–108 MB) falhava no TikTok.
- `references/gotchas.md`: item 139 (sintoma, causa `connect_over_cdp` tratado como remoto, correção `is_local=True` em
`runner.py` e `browser.py`, mensagem genérica "navegador travou", reinício do `pnpm dev`); nota "Relacionadas".
- `references/publishing.md`: linha do modo sessão (`is_local`, mensagem genérica) e evidência.
- `SKILL.md`: versão e resumo de armadilhas.
- Evidência: `pnpm test:publisher` → 73 passed (reexecutado); `is_local` conferido nos dois arquivos e na assinatura do
playwright 1.65.2. Não verificado: envio real (falta reiniciar o `pnpm dev`); captura PNG existe, mas não foi aberta.
## 1.36.1 — 17/11/2026
Correção: migração do banco do painel agora se aplica sozinha no HMR (`checkedThisModule` em `panel/src/lib/db.ts`).
- `references/gotchas.md`: item 138 reescrito (migra na 1ª requisição depois da recarga; sintoma só se o `db.ts` não
recarregou; remédio: qualquer requisição ou reiniciar); item 51 e nota "Relacionadas" ajustados.
- `references/panel.md` e `references/publishing.md`: removida a afirmação de que só reiniciar migra.
- `SKILL.md`: versão e resumo de armadilhas.
- Evidência (informada, 17/11/2026): `GET /api/publishing/summary` levou o banco real a `user_version` 7 com backup
`cenaforge-v6-2026-11-17T16-28-39-725Z.db`; typecheck verde, `test:panel` 63/63. Código de `db()` conferido; testes não reexecutados.
## 1.36.0 — 17/11/2026
Clipador: botão "Publicar" nos cortes aprovados (publicação manual sem fonte ligada) e banco v7 (`publish_jobs.origin`).
- `references/publishing.md`: linhas "Onde mexer" (UI, rota, `publishClip`) e do banco (v7); regras do botão e de
`origin` (`manual` não é cancelado por fonte desligada); evidência (63/63, informada).
- `references/gotchas.md`: item 138 ("no such column: origin" até reiniciar o `pnpm dev`); nota "Relacionadas" até v7.
- `references/panel.md`: esquema v7. `references/clipper.md`: ponteiro na regra "Aprovar publica".
- `SKILL.md`: versão, esquema v7, linha de publicação, `description` e resumo de armadilhas.
- Não verificado: testes e typecheck não reexecutados aqui (vêm do relato); sem conta real; `doc/publicacao/PLANO.md` §7c não lido.
## 1.35.0 — 17/11/2026
Modo sessão do Publicador com Chrome 157: `owns_port` deixou de depender só do `DevToolsActivePort`.
- `references/gotchas.md`: item 137 (sintoma, causa, marca `CenaForgeWindow.json` + `listener_pid`, aviso de janela já
aberta com o perfil, reiniciar `pnpm dev`); nota nas "Relacionadas".
- `references/publishing.md`: linha do modo sessão cita a marca; evidência registra 73 passed (informado).
- `SKILL.md`: versão e resumo de armadilhas.
- Não verificado: `pnpm test:publisher` não reexecutado aqui; teste ao vivo e 73 passed vêm do relato; versão do Chrome não conferida.
## 1.34.0 — 17/11/2026
Economia de tokens do juiz do Clipador (`clipper/app/judge.py`): `codex_lean_overrides` e `--setting-sources` no Claude.
- `references/token-economy.md`: subseção "Juiz do Clipador" com medições (Codex ~77 mil → ~35 mil caracteres fixos;
Claude 3,7 → 2,6 mil tokens, 5,5 → 2,8 s) e propostas não implementadas (pré-filtro, juntar analista+editor).
- `references/clipper.md`: bullet de custo fixo na seção Juízes.
- `references/gotchas.md`: item 136 (cota esgotada pelo juiz; vale só após reiniciar o Clipador).
- Não verificado: resposta do modelo Codex com a configuração enxuta (cota esgotada na medição).
## 1.33.0 — 17/11/2026
Economia de tokens dos agentes do painel: flags enxutas do Claude CLI, teto de gasto, overrides do Codex e dois scripts
novos (`frame_check.py`, `check_script.py`).
- `references/token-economy.md`: scripts novos na tabela; regras duras (uma imagem por render, pesquisa curta, resume
caro); seção "Custo fixo dos agentes do painel" com as medições (62,4 → 14,9 mil tokens, 8,0 → 4,3 s; #6, #7, #8).
- `references/gotchas.md`: novos 133 (OAuth expirado em `~/.claude`), 134 (execução cara: causas e correções),
135 (`-c mcp_servers={}` não desliga; `collaboration` fica).
- `SKILL.md`: lista de scripts e resumo de armadilhas (133–135); versão.
- Não verificado: reexecução do `tsc`/testes do painel (informado como passou); `frame_check.py` conferido só por `--help`.
## 1.32.0 — 17/11/2026
Cenas 3D com personagens: kits `godot/kits/` (`person.gd`, `boat.gd`), ilha com noite e uso como cenário
(`embedded`), cena nova `castaways` (náufragos da Ilha das Cobras), `SCENE_SCRIPT_INVALID` no `doc_main.gd`. Montagem
"Tudo em 3D" com cartão de foto e cartões de informação em sequência; `POST /api/stories`. Fluxo provado de ponta a
ponta (história → cena → MP4 de 101,7 s).
- `SKILL.md`: `description` cita náufragos, kits, cena dentro de outra, "Tudo em 3D", cartão de foto, `POST
/api/stories` e agente parado (limite/reinício); bloco do documentário lista `island` e `castaways`, tempo de prévia
e `SCENE_SCRIPT_INVALID`; "Onde mexer" ganha kits/`embedded` e `planShot3d`/cartão; resumo de armadilhas cita 131–132.
- `references/panel.md`: banco real em v6 (conferido); `style`, `inset`/`InsetCard`, textos `; depois:`; `planShot3d`;
`applyInternetImage(..., "inset")` sem repetir fotos entre principais e cartões; `regenerateShot(..., target)` e rota
`{index, target?}`; cartão no FFmpeg (62%, borda 12 px, 21%, fades) e fonte menor > 26 caracteres; ilha (`night`,
`variant` só câmera, `embedded`/`environment`/`sea_detail`, métodos públicos); `castaways` e kits; `POST /api/stories`;
evidência de ponta a ponta.
- `references/gotchas.md`: novos 129 (template que não compila: laço infinito → `SCENE_SCRIPT_INVALID`), 130 ("shadows
a native class"), 131 (reiniciar o painel mata o agente), 132 (limite de uso → outro provedor); item 9 ampliado;
item 125 cita a mensagem e que só parte das rotas usa `readJson`.
- `references/tools.md`: Godot cita `castaways`/kits; tempos medidos do `castaways` (prévia 5,8–15,6 s, 65 execuções;
finais 9,8–89,7 s); candidata nova "`.glb` por `GLTFDocument`" (só documentado, sem teste).
## 1.31.0 — 17/11/2026
Correções das revisões de segurança e correção da publicação automática: migração v6 do painel, guarda da API
(`panel/src/proxy.ts`), idempotência por `clientRef`, `mayBeLive`, reencaixe de agendados vencidos, `unlinked`, e
endurecimento do Publicador (pastas permitidas, janela do navegador, ACL, capturas, PKCE em memória, loggers).
- `SKILL.md`: `description` cita "Confira na rede" e chamada da API do painel por script; esquema v6; invariante nova
da API do painel (`Origin` + JSON, gotchas 125).
- `references/publishing.md`: "Onde mexer" com `paths.py` (`output/`/`stories/`/`assets/`, `data/` recusado), `acl.py`,
`db.py` v2 (`client_ref`), `browser.py` (`DevToolsActivePort`, fechamento), `step_pause`/`fill_text`, funções novas
das regras (`needsReflow`, `clientRefFor`, `mayBeLive`), banco v6 e linha "Guarda da API do painel"; regras novas
(idempotência, `confirm: true`, reencaixe > 30 min, `unlinked`/`linked_at`, cancelar no ciclo, rótulo de IA por
cautela, janela do modo sessão, capturas, segurança do Publicador); evidência 71 passed / 59/59 e bancos reais
(painel ainda v5, Publicador v2).
- `references/gotchas.md`: itens 118 (`mayBeLive`/409), 119 (401/403/404 e timeout ficam na fila), 121 (`unlinked`),
122 (religar zera `linked_at`) ampliados; novos 125 (API do painel 403/415 a curl), 126 (reencaixe do agendado),
127 (OAuth: Publicador reiniciado / espera de 10 min), 128 (janela do modo sessão fecha sozinha).
- `references/panel.md`: banco v6 e guarda da API (`proxy.ts`, `readJson`).
- `references/tools.md`: evidência do Publicador 71 passed (versões reconferidas, sem mudança).
## 1.30.0 — 17/11/2026
Publicação automática em YouTube, TikTok e Instagram: serviço Publicador (`publisher/`, 4530), despachante do painel
(laço de 20 s em `instrumentation.ts`), migração v5, telas "Canais de publicação", "Publicações" e "Configurações";
"Canais" do Clipador viram "Fontes" na UI. Tira da skill o "publicação é a próxima fase / nada fala com as redes".
- `references/publishing.md` (novo): papéis painel × Publicador × Clipador, subida/instalação/testes, tabela "onde
mexer" (serviço, uploaders, seletores `SELECTORS`, `publishing-rules.ts`, rotas, telas, `Dialog`/`Steps`,
`NoticeBar`/`PublishChips`, `actions[]`), regras (nunca `published` sem link, aprovar = vídeo inteiro,
`auto_since`, episódio sempre manual, limite diário em "Na hora", `publishAt` não usado, modo sessão com "Entendi o
risco"), resumo dos fatos das plataformas apontando para `doc/publicacao/PESQUISA.md`, evidência e lacunas.
- `SKILL.md`: `description` cita publicação; docs de `doc/publicacao/` e `publisher/README.md`; esquema v5; linha do
Publicador e portas 4530 e 4540–4549; "Onde mexer" ganha publicação, passo 6b2 do setup e `Dialog`; invariante "fora
do escopo: publicação real" trocada por regras de publicação; `pnpm test:publisher`; seção de voz compactada.
- `panel.md`: banco v5 e `test:panel`; "Contas e dashboard" → "Canais de publicação e dashboard" (sem `mock`; métricas
simuladas, `publications` real com `simulated = 0`; card "Fontes de corte").
- `clipper.md`: linha "Fontes" e linha nova "Publicação dos cortes" (`GET /v1/clips` com `channel=`/`ids=`); regra
"Aprovar só marca o corte" substituída.
- `gotchas.md`: seção nova "Publicação", itens 118–124 (terminou sem link, job esperando/409, `expired`, jobs
cancelados ao exportar, automática não pega cortes antigos, "Na hora" agendado, TikTok só "Somente eu"); item 51
cita v5.
- `tools.md`: seção do Publicador com versões do `publisher/.venv` (Python 3.12.13, FastAPI 0.159.1, uvicorn 0.54.0,
pydantic 2.14.1, httpx 0.28.1, playwright 1.65.2, pytest 9.1.1) e 55 passed; candidata "publicação próxima fase"
trocada por APIs oficiais e modo sessão "código pronto, sem envio real".
## 1.29.1 — 17/11/2026
Correção: a limpeza da fila antes do render (`discard_pending_duplicates`) agora usa o mesmo veto do juiz.
- `clipper.md`: "Duplicados" diz que saem da fila os pendentes iguais a um corte pronto, aprovado, publicado,
rejeitado, apagado num desses estados ou a um pendente mais antigo (antes dizia que não comparava com rejeitados);
"Apagar cortes" cita a limpeza da fila; evidência 270 passed (medido; informado 269) com o teste novo.
- `tools.md`: evidência do Clipador 270 passed.
## 1.29.0 — 17/11/2026
Clipador: apagar cortes (um, lote ou aba inteira; o momento apagado não volta), veto do rejeitado depois do juiz e
varredura que conta propostas. Painel: "Apagar" e seleção discreta na fila, relógio da gravação e cadência do resumo
no cartão da sessão, prévia do editor igual ao render na legenda e no recorte. (A 1.28.0 é de outra sessão, publicada
em paralelo.)
- `SKILL.md`: `description` cita apagar corte, rejeitado/apagado que não volta, relógio e cadência, prévia igual ao
render e "não sai corte"; linha do Clipador em "Onde mexer" cita `clip_delete.py`/`deleted_clips` e `METHODS`.
- `clipper.md`: banco v10 (`deleted_clips`); linha nova "Apagar cortes" em "Onde mexer"; `KEPT_STATUSES`/
`VETO_STATUSES`; seção nova "Apagar cortes" (rotas, recusas, o que some, marca, `METHODS`, ids mostrados);
duplicados reescritos (rejeitado e apagado vetam; descartado não; `discard_pending_duplicates` não olha rejeitado);
varredura grava `proposals`/`created`; editor: porte da legenda e `ffmpegCropFill` com regra de mudar junto;
linha da página `/clipper` cita `SelectionPill`, `RecordingClock`, `SummaryCadence`; evidência (268 passed,
`tsc` exit 0, banco real em v10) e lacunas.
- `panel.md`: aba Sessões ganha relógio (`CLOCK_TICK_MS` 250, `CLOCK_MAX_AHEAD_S` 45) e cadência (`scanIntervalS` de
`/status`); fila ganha "Apagar" e seleção discreta; `METHODS` na regra de rota nova; prévia do editor deixa de ser
"aproximada" na legenda e no recorte; evidência.
- `gotchas.md`: itens 114 ("não sai corte" = live fria), 115 (resumo "travado"), 116 (barra de seleção reprovada),
117 (prévia 1–3 px deslocada / legenda diferente).
- `tools.md`: evidência do Clipador 268 passed.
## 1.28.0 — 17/11/2026
Biblioteca de cenas 3D na Godot (`kind: "doc3d"`, `godot/library/<id>/`, primeira: `island`) e montagem documental com
fotos reais do Wikimedia Commons, "Gerar de novo" por trecho e "Refazer tudo do zero". Tira o aviso "doc3d em
desenvolvimento".
- `SKILL.md`: `description` cita a biblioteca 3D, criar cena nova (`doc/godot/cenas.md`, tarefa "Cena no Godot"), fotos
do Commons, "Gerar de novo" e "Refazer tudo do zero"; parágrafo "Cenas do documentário" reescrito (`doc2d`/`doc3d`,
`variant`, erro de cena inexistente, tempos); "Onde mexer" ganha a linha da cena 3D (`template.gd` + `manifest.json`)
e cita `scene-library.ts`/`image-search.ts`; "Validação" aponta o checklist do guia; seções de voz, tokens e
armadilhas compactadas.
- `panel.md`: "Montagem documental" reescrita — `VISUAL_KINDS` com rótulos, `ShotVisual.search`/`auto`, pergunta da
tela antes da fala, licença opcional, `SceneEditor` 3D pelo manifesto; subseções novas "Plano do trecho"
(`scriptEntities`, ordem do `planShot`, modelos 2D com `variant`), "Fotos da internet" e "Biblioteca de cenas 3D";
"Gerar o MP4" com `replan`, `regenerateShot` e foto com fundo desfocado; rota `.../montage/regenerate`; tarefa
`godot` do agente e `?prompt=`; evidência (13 prévias da ilha, final 3D, erro de cena inexistente, MP4 88,33 s).
- `gotchas.md`: 110 vale para `doc3d`; 44 ampliado (`node -e` quebrou o build do painel); novos 111 (espuma por
elipse no shader do mar) e 112 (Next dev roda o módulo antigo na 1ª montagem pós-edição).
- `tools.md`: Godot também monta a biblioteca 3D (ACES na ilha), tempos medidos da `island`; FFmpeg com `boxblur`;
API do Wikimedia Commons em uso.
## 1.27.0 — 17/11/2026
Cenas 2D do documentário na Godot (`kind: "doc2d"`: título, contador, mapa do litoral de SP) e vídeo documental
automático num clique no painel. Corrige a skill onde dizia que "Animação 2D (Godot)" não existia e que o documental
saía só pelo FFmpeg, sem Godot.
- `SKILL.md`: `description` cita cena 2D e "Gerar vídeo automático"; parágrafo do `doc2d` no Pipeline (contrato,
comando de prévia, tempos); "Várias histórias" e "Voz e legenda" atualizados; "Onde mexer" ganha a linha da cena
2D (`godot/scripts/doc/`: `doc_config.gd`, `doc2d_canvas.gd`, `doc_main.gd`; cena `doc.tscn`; `MAP_PLACES` =
`PRESETS.places`) e cita o ramo `doc2d` do `render.ts`; `doc3d` marcado como em desenvolvimento e o `montage-godot.ts`; "Validação": quadros de inspeção pulados em cena curta. Seção de voz
compactada (detalhes já em `voice/README.md`).
- `panel.md`: "Montagem documental" reescrita — `godot2d` disponível (`scene`/`sceneKey`), botão "Gerar vídeo
automático" + modo manual ("Só montar"), `SceneEditor` e "Prévia da cena", config em
`stories/<id>/godot/<file_key>-tNN.json`; subseções "Cena 2D: plano e render" (`planScene` por regras,
`MAP_PLACES`, `renderGodotScene`) e "Gerar o MP4" (`startMontageRender(id, { auto })`, `montageJob`); `godot2d` sem
texto na tela; rotas `.../montage/scene` e `{auto}`, GET com `templates` e `job`; evidência e lacunas.
- `gotchas.md`: item 110 (checagens da rua reprovavam a cena 2D: luma ≈ 13 < 20 e sem moto).
- `tools.md`: Godot também desenha as cenas 2D (`doc.tscn` + `doc2d_canvas.gd`, SystemFont), reconferida 4.7.2 em 17/11/2026; tempos
medidos do `doc2d`.
## 1.26.0 — 17/11/2026
Clipador: duração mínima garantida, gancho em tarja animada, fontes empacotadas, reenquadramento do jogo com keyframes,
camadas inseridas e qualidade de gravação configurável (até 2K). Painel: editor com Programa 16:9, trilhas ENQ/INS,
câmera editável na Fonte e prévia de texto pelas métricas da fonte.
- `SKILL.md`: `description` cita mínimo garantido, qualidade de gravação, tarja, fontes, reenquadramento, camadas e
câmera editável na Fonte; linha do Clipador em "Onde mexer" cita `capture.py`, `fit_window`, `assets/fonts/` e
`reframe.py`.
- `clipper.md`: banco v9 (`sessions.capture_json`); linha das fontes empacotadas; "Onde mexer" ganha qualidade de
gravação, busca em `.ts`/emenda de resolução e reenquadramento/camadas, e cita `fit_window`, `min_target`, grupos
`hook`/`capture`, `ass_filter` e as chaves novas das rotas de settings; "Configuração do corte" reescreve a duração
(≥ `minS` + 1 s em todo corte automático) e ganha `hook`, fontes e `capture.quality`; seção nova "Qualidade de
gravação"; editor: sai "Programa sempre 9:16", campos `style`/`bg`/`color`/`font`/`anim`, `inset` e `reframe`,
limite de 0,48 da largura, custo medido, a IA não propõe reframe/camadas; regra de aplicar por edição pontual;
evidência (251 passed) e lacunas.
- `panel.md`: modal do corte em 5 abas (Gancho, "Qualidade da gravação"); cartão da sessão "gravando em"; editor:
trilhas INS/ENQ, Programa por `frames`, fontes por `FontFace`, keyframes, câmera na Fonte, arquivos novos
(`clip-editor-fonts.tsx`, `clip-editor-keyframes.tsx`, `clip-editor-source.tsx`, `rect-geometry.ts`), atalhos `[`/`]`
e Ctrl+C/V; gestos da Fonte sem os botões antigos; evidência.
- `gotchas.md`: itens novos 103 (corte automático curto), 104 (`\blur` com contorno), 105 (`fontsdir` e nome da
família), 106 (`crop` × `perspective` `eval=frame`, `in` começa em 1), 107 (busca em `.ts`, HEVC cinza), 108 (emenda
de resolução na retomada), 109 (updater do `setState` puro); 86 ampliado (CDP: `Fetch` antes de navegar, Ctrl+Z
como `keyDown`); 87 ampliado (aplicar por edição pontual com agentes em paralelo).
- `tools.md`: evidência do Clipador 251 passed; Streamlink e FFmpeg reconferidos (8.6.3 / 7.1.1) com os usos novos;
linha das fontes empacotadas (commit do google/fonts + licenças).
## 1.25.0 — 17/11/2026
Painel: modal de confirmação/aviso global no lugar de `window.confirm`/`window.alert`.
- `SKILL.md`: linha nova em "Onde mexer" (`askConfirm`/`showAlert`/`confirmSubmit` de
`components/confirm-dialog.tsx`; proibidos `confirm()`/`alert()` nativos).
- `panel.md`: seção nova "Confirmação e aviso" (API, `confirmSubmit` com `requestSubmit` + `data-confirmed="1"`,
`tone: "danger"`, `<ConfirmHost />` único em `app/layout.tsx` com fila e `<dialog>` nativo, `Button` com
`ComponentProps<"button">`/`ref`); "Excluir história" deixa de citar `window.confirm` (agora `confirmSubmit` +
`showAlert`); evidência.
## 1.24.0 — 17/11/2026
Painel: montagem documental (áudio e visual por trecho → MP4 pelo FFmpeg). Substitui o aviso "a montagem
documental não existe".
- `SKILL.md`: `description` cita a montagem documental; "Várias histórias" diz que o documental vira MP4 pela
montagem do painel; "Onde mexer" ganha a linha da montagem (`montage.ts`, `montage-ffmpeg.ts`, `speech-text.ts`,
`montage-editor.tsx`, rotas `.../montage/`); "Voz e legenda": só o render da Godot não chama o serviço.
- `panel.md`: seção nova "Montagem documental" (trecho = linha "t (s)", áudio por parágrafo, texto falado por
extenso, `VISUAL_KINDS`, upload com licença, `.montage.json`, `audioKey`, `startMontageRender`/`profile =
'documentary'`, parâmetros do FFmpeg, rotas, `/api/files` com .webm/.mov/.mkv); evidência e lacunas.
- `gotchas.md`: item 52 ampliado (tsx pela raiz, `f:/` não é URL); itens novos 99 (importar `db.ts` marca execuções
como `interrupted`), 100 (`fileUrl()` + `&v=`), 101 (markdown no texto na tela), 102 (duração real da fala ×
tempo da tabela).
- `tools.md`: FFmpeg também usado pela montagem documental (7.1.1 reconferido).
## 1.23.0 — 17/11/2026
Painel: leitor de roteiro.
- `SKILL.md`: `description` cita o leitor de roteiro e que a montagem documental em MP4 não existe; "Várias
histórias" avisa que o documental ainda não vira MP4; "Onde mexer" ganha a linha do leitor (`script-doc.ts`,
`script-reader.tsx`, página `.../roteiro`).
- `panel.md`: seção "Leitor de roteiro" (`parseScript`, papéis das seções, tabela "t (s)", `WORDS_PER_SECOND` 2,5,
alertas 1,1×/1,15×, markdown sem HTML cru, páginas que usam, episódio documental sem "Montar cena"); evidência.
## 1.22.0 — 17/11/2026
Painel: mensagem ao agente durante a execução, termos episódio × vídeo e leitura UTF-8 no Codex.
- `SKILL.md`: `description` cita correção/mensagem durante a execução e termos episódio × vídeo; "Onde mexer" —
linha de agentes cita `sendFollowUp` e `agent-console.tsx`; formato novo inclui `unitTerms`.
- `panel.md`: seção "Mensagem com o agente rodando" ("Corrigir agora"/"Enviar ao terminar", rota
`POST /api/agent/runs/[id]/messages`, `ActiveRun.emit/followUp/progressed`, continuação antes do "end" com
`followUpRunId`, só no fim ao vivo); "Formatos de história" ganha `unitTerms` e o episódio sem título no
documental; nota do `Get-Content -Encoding UTF8`; evidência e lacunas.
- `gotchas.md`: item 97 (Codex retomado cedo demais esquece o pedido — medido no 0.169) e item 98 (PowerShell 5.1
lê UTF-8 sem BOM como ANSI → "história").
## 1.21.0 — 17/11/2026
Regras de roteiro numa fonte única (`doc/roteiro/`) e exclusão de história no painel.
- `SKILL.md`: `description` cita `doc/roteiro/` e excluir história; "Várias histórias" aponta as regras de roteiro
para `doc/roteiro/` (sai "restrições do `cenaforge-story-writer`") e cita a 1ª linha `Formato:` da `biblia.md`;
"Onde mexer" ganha a linha "Regra de roteiro" (editar os .md, não o código), a linha do painel cita
`deleteStory`/`stories.ts`, e formato novo usa `GUIDE_BY_KIND`/`FORMAT_LABEL` no lugar de "regras no prompt";
"Economia de tokens": subagente segue `doc/roteiro/`, sem busca na web ("a confirmar").
- `panel.md`: "Formatos de história" resume os três guias (sai `DOCUMENTARY_RULES`/`DOCUMENTARY_SCRIPT_FORMAT` e o
detalhe do documental duplicado); "Agentes e modelos" descreve `writingRules(provider, kind)`; seção nova
"Excluir história" (recusas, `data/trash/<id>-<timestamp>/`, transação, CASCADE/SET NULL, sem exclusão de asset
da biblioteca); evidência e lacunas.
- `gotchas.md`: item 96 aponta para `doc/roteiro/` e `writingRules` (saem `fictionRules`/`DOCUMENTARY_RULES`).
## 1.20.0 — 17/11/2026
Painel: formato de história documental, prompt sensível ao agente e lista de modelos dinâmica.
- `SKILL.md`: `description` cita histórias lineares/documentais e escolha de agente/modelo; esquema do banco v4;
formatos `interactive`/`linear`/`documentary` em "Várias histórias"; "Onde mexer" — formato novo exige também
migração do CHECK (`db.ts`), regras em `prompts.ts` e layout do Fluxo; linha de agentes cita `prompts.ts`,
`models()` e `AGENTS.md`.
- `panel.md`: banco v4 (reconstrói `stories` para o CHECK aceitar `documentary`) e migração só ao reiniciar o
`pnpm panel`; novas seções "Formatos de história" (tabela dos três `kind`, ficha de pauta e roteiro do documental,
`DOCUMENTARY_RULES`/`DOCUMENTARY_SCRIPT_FORMAT`) e "Agentes e modelos" (`buildPrompt` por `provider`, `models()`:
Codex por `models_cache.json`/`config.toml`, Claude com ids `claude-*`, `DEFAULT_MODEL` = `claude-sonnet-5-5` em
scene/branches, seletor no "Nova história com IA"); linha "Gerar vertentes" sem o modelo `sonnet` fixo; evidência.
- `gotchas.md`: item 29 com os filtros novos de stderr (Codex "unrecognized configuration setting", Claude
`unrecognized_model`); item 51 generalizado (cache em `globalThis.__cenaforgeDb`, v4); item 96 novo (Codex
aplicando as restrições de ficção a pedido documental).
- `tools.md`: linhas do Codex CLI e do Claude Code CLI citam a escolha de modelo; versões reconferidas (0.169.0 /
2.1.314).
## 1.19.0 — 17/11/2026
Rastreio de reação testado ao vivo (instância isolada na 4521; `doc/FACE_BAKEOFF.md`, "Testes de 17/11 — ao vivo").
- `clipper.md`: `locate_cam` com `ReactionParams.min_cam_score` 0,7; sem linha "Rosto do streamer" com o plano B
OpenSeeFace (`FaceService.summary`); receita da instância de teste isolada (`CLIPPER_DATA_DIR`/`CLIPPER_OUTPUT_DIR`
dentro do repo, `sqlite_sequence` de `sessions` em 90000); evidência nova (download real, OSF × MediaPipe, serviço
real com 25 blocos, lofigirl, painel; pytest 170 passed e tsc do painel conferidos); "Não verificado" do rastreio
trocado (download, plano B, serviço real e painel saem; entram câmera cheia/escura/minúscula, GPU, live > 15 min,
linha do rosto no juiz ao vivo, interruptor real).
- `gotchas.md`: itens 92 (câmera falsa em live sem câmera), 93 (chave da voz colidindo em banco de teste novo),
94 (analista lendo "sem reação" com o plano B) e 95 (WARNING de pesquisa a cada 30 s com juiz `off`).
- `tools.md`: evidência do serviço real ao vivo; números ao vivo do MediaPipe; OpenSeeFace deixa de ser "não testado"
(medido com os pesos reais); piso 0,7 citado no YuNet.
## 1.18.0 — 17/11/2026
Clipador: formato horizontal, durações novas, legenda com fala rápida, retomada de live, render que falha e cortes
duplicados; modal do corte em abas e aba Sessões refeita no painel.
- `clipper.md`: corte vertical ou horizontal; banco em `user_version` 8 (`clips.aspect`); "Onde mexer" ganha a linha de
retomada/render/duplicados (`worker.py`, `test_resume.py`, `test_render_and_duplicates.py`), cita `DEFAULTS`/`merge`/
`validate`, `ASPECTS`/`FRAME_SIZES`/`CANVAS_SIZES`, `resolved_mode` = `full`, `aspects`/`frames` das rotas de settings,
o SHA de referência do vertical e `Aspect`/`aspectOf`/`withFormat`; a linha da legenda deixa de ser "caminho antigo"
(`clean_words`/`group_words`/`caption_blocks`, usada pelo worker e pelo editor). Analista com 6 ou 8 frames;
`backtrackS` padrão 120 s; `duration` corrigido (padrão 60/90/120; `minS` 5–120). Nova seção "Retomada, render que
falha e cortes duplicados" (com `POST /v1/sessions/{id}/resume`). Editor: `settings.format` por corte, Programa ainda
em 9:16; `cover.atStart` agora também na `preview-render` com `fromS` = 0 (sai o "só no export"). Regra de reiniciar
só com a suíte verde; nota do `FakeJudge.ask`; evidência (170 passed medido) e lacunas novas.
- `gotchas.md`: itens 87 (reinício com código intermediário → cortes presos em `rendering`), 88 (retomada que checava
uma vez só), 89 (juiz recua o corte → duplicados), 90 (legenda empilhada com fala rápida) e 91
(`[contain:inline-size]`); item 77 ganha "a cópia herda sessões" e a 4521 de outra sessão; item 86 ganha
`requestStage: "Response"`; item 69 cita os 8 frames.
- `panel.md`: modal em quatro abas, `clipper-client.ts` (`Aspect`, `withFormat`), fila em 16:9, cartão da aba Sessões
(`sessionHealth`, altura fixa, "Retomar gravação").
- `tools.md`: evidência do Clipador → 170 passed; FFmpeg faz render vertical e horizontal (NVENC horizontal não testado).
- `SKILL.md`: `description` e linha do Clipador em "Onde mexer" citam formato, duração, retomada e duplicados.
## 1.17.0 — 16/11/2026
Redesenho do editor de cortes do Clipador (padrão de editor de vídeo) e camadas novas do projeto de edição.
- `clipper.md`: modo `cam_only` (`MODES`, `resolved_mode`, queda para `blur`); "Onde mexer" cita `normalize_cuts`,
`pick_hook`, `chat_events`, `build_filter`/`build_project_ass`, `chat_for`, `clipper/tests/test_editor_layers.py`,
os tipos espelhados no painel e os tokens `--color-nle-*`; regra do gancho por `pick_hook`; tabela dos campos
`cuts[].mode`, `cuts[].muted`, `overlays[].x`, `chat` e `cover.atStart` (só no export) com limites; ponteiro para
"Mexer com a mão" do README; limites (uma trilha de vídeo, sem B-roll); evidência (136 passed, teste de UI por
CDP informado) e lacunas refeitas.
- `panel.md`: seção "Editor de cortes" reescrita — desenho NLE, disposição com Camadas e monitor "Fonte · Programa",
trilhas C1/V3/V2/CAM/V1/A1/A2/A3/CH, modais no lugar das abas do inspetor, tabela de papel por arquivo (novos
`clip-editor-ui.tsx` e `clip-editor-layers.tsx`), gestos, "Salvar projeto", atalhos atuais (Ctrl+K, Ctrl+Shift+clique,
Ctrl+E, V/C/N, Home/End, ?). Sai a disposição antiga (inspetor em abas).
- `gotchas.md`: item 44 cita escapes como `\b`; item 73 cita o serviço antigo recusando `cam_only`; item 76 passa a
apontar para `pick_hook` (tempo da gravação no gancho); novos itens 85 (camadas do canvas achadas pelo cursor) e
86 (interceptar escritas em teste de UI sobre corte real).
- `tools.md`: evidência do Clipador → 136 passed.
- `SKILL.md`: `description` cita o editor no padrão de editor de vídeo e as camadas novas.
## 1.16.0 — 16/11/2026
Rastreio de reação do Clipador (câmera achada sem IA + expressões do rosto do streamer).
- `clipper.md`: pasta `data/clipper/models/` + `clipper/models.lock.json`; "Onde mexer" ganha `face.py`/`_face_loop`/
`face_bench.py` e `reaction.py` (`ReactionParams`), e cita `_face_moments`/`face_*` em `scoring.py`, `detect_cam`
local primeiro e `CAM_RETRY_S` em `intel.py`, a linha "Rosto do streamer" do analista e os componentes do painel
(`FaceSignal`, interruptor, selo da câmera); fonte de corte `face`; `faceTrack` no `PUT /v1/judge`; `detect-cam`
com YuNet, `?ai=true` e `cam_json.source`; timeout de 30 s de `face(/reset)`; nova seção "Rastreio de reação"
(stack e licenças, fluxo, sinal, regras de corte, modelos, rotas, bancada); evidência da bancada e lacunas; sai a
nota dos 2 testes de rosto instáveis (120 passed em 2 execuções).
- `tools.md`: tabela do rastreio (mediapipe 1.2.3, opencv-contrib-python 5.0.0.93, numpy 2.5.5, onnxruntime 1.32.0,
pesos e licenças) e descartados por licença; evidência do Clipador → 120 passed.
- `gotchas.md`: itens 79 (import do MediaPipe 1.2.3), 80 (`opencv-python-headless` junto), 81 (jawOpen/eyeWide não
sobem; risada pelo sorriso), 82 (agrupar pelo centro do grupo), 83 ("sustos" do rastreio perdendo o rosto) e 84
(neutro sorridente sem pico).
- `SKILL.md`: `description` e linha do Clipador em "Onde mexer" citam o rastreio de reação e o `models.lock.json`.
## 1.15.0 — 16/11/2026
Chat com a IA por seção no perfil do jogo (aba Jogos do Clipador).
- `clipper.md`: `POST /v1/games/{id}/refine` documenta `section` (`Literal`, 422 se inválido), `history` (máx. 20;
IA vê 8 turnos de 400 caracteres) e a resposta `{games, reply}`; `notes[].section?`; `REFINE_SCHEMA`,
`PROFILE_SECTIONS`, nova assinatura de `refine_game` e `Intel.refine` → `(profile, reply)`; painel com chat por
seção (padrão de "Confirmar na web" difere da API); evidência com IA simulada e lacuna da IA real.
- `panel.md`: redesenho do card do jogo em `clipper-games.tsx` (selo de iniciais, cartões por seção, `AiChat`,
selo "novo", chips de gírias, Fontes/Memória recolhidas).
## 1.14.0 — 16/11/2026
Editor de cortes do Clipador (`/clipper/edit/<id>`) e render único pelo projeto de edição.
- `clipper.md`: banco detalha v4 `edits` e v7 `origin`/`ai_project_json` + regra "nunca alterar migração aplicada";
pasta `edit-<id>/` (proxy, TTS); "Onde mexer" ganha `editor.py`, `editor_render.py`, `editor_api.py`,
`layout_chain` e a página do editor, e marca `media.render_vertical` como fora do render de cortes; timeout de
5 min do proxy; nova seção "Editor de cortes" (caminho do render, projeto da IA, origem/rejudge, tempo, validação,
rotas) apontando para o README e `doc/clip-editor-research.md`; evidência e lacunas do editor.
- `panel.md`: seção "Editor de cortes" (tela cheia sem mudar o layout raiz, disposição, componentes `clip-editor*`,
autosave com `rev`, atalhos) e botão "Editar"/"Continuar edição" em `clipper-queue.tsx`.
- `gotchas.md`: item 57 aponta para `editor_render.py`; novos itens 74 (palavra de duração zero), 75 (capa vazia
com mjpeg/faixa "tv"; `-g` curto em teste), 76 (gancho longo), 77 (instância de teste sobre cópia do banco:
`keep_hours = 0`, sem monitor/varredura) e 78 (emoji monocromático no libass).
- `SKILL.md`: `description` e linha do Clipador em "Onde mexer" citam o editor de cortes.
## 1.13.0 — 16/11/2026
Perfil do jogo editável no Clipador (aba Jogos).
- `clipper.md`: banco corrigido para `user_version` 7 (v4 `edits`, v5 `face_track`, v6 `games.notes_json`/`edited_at`,
v7 `edits.origin`/`ai_project_json`); "Onde mexer" cita `clean_profile`/`save_profile`/`refine`/`delete_note` e
`REFINE_SYSTEM`/`refine_game`; nova seção "Perfil do jogo" (rotas `PUT /v1/games/{id}`, `POST …/refine`,
`DELETE …/notes/{index}`, campos novos de `GET /v1/games`, pedido guardado × edição à mão); timeout de 8 min do
proxy vale para `research|refine`; evidência e lacunas.
- `panel.md`: `clipper-games.tsx` com Editar, Pedir à IA e pedidos guardados.
- `SKILL.md`: `description` cita o perfil do jogo editável.
## 1.12.0 — 17/11/2026
Fase 2 do Clipador.
- `SKILL.md`: `description` cita emotes, varredura da IA, juízes analista/editor, contexto do jogo, webcam e layout do
corte; linha do Clipador em "Onde mexer" cita o timeout por rota do proxy.
- `clipper.md`: banco v3 (colunas e tabelas `games`/`emotes`); "Onde mexer" com `emotes.py`, `intel.py`, `layout.py`,
`clipper-cut-settings.tsx`, `clipper-games.tsx`; novas seções "Como os momentos nascem" (mínimo proporcional, chat
fraco, varredura, aprendizado dos emotes), "Juízes" (analista + editor, `analystModel`, `backtrackS`, `-i`/`--search`
do Codex) e "Configuração do corte" (camadas, modos, rotas, timeouts do proxy); evidência da fase 2
(`pnpm test:clipper` → 46 passed) e lacunas (UI nova contra o serviço novo, juiz `claude`).
- `gotchas.md`: item 59 aponta para o mínimo proporcional; novos itens 68 (chat pequeno sem corte), 69 (título preso à
transcrição), 70 (crédito sobre o rosto no `cam_top`), 71 (cor ASS `&H00BBGGRR&` × `&HBBGGRR&`), 72 (download de
emotes fora da thread do chat), 73 (reiniciar o Clipador após código novo).
- `panel.md`: seção da página `/clipper` (modal do corte, aba Jogos e emotes, cartão com análise e recuo do início).
- `tools.md`: evidência do Clipador atualizada (46 passed, sem dependência nova); papel das CLIs nos juízes; APIs
públicas de emotes 7TV/BTTV/FFZ (chamada real não registrada).
## 1.11.0 — 16/11/2026
- `SKILL.md`:
- `description` cita Azure Speech, filtros de voz e clonagem de voz (Chatterbox, com consentimento);
- estrutura e portas: worker de clonagem na 4511 (`voice/.venv-clone`);
- "Onde mexer": arquivos do serviço de voz (`catalog.py`, `config.py`, `errors.py`, `voice/clone/worker.py`) e
do painel (`voice-cards.tsx`, `voice-clone-form.tsx`, `AzureForm`);
- "Voz e legenda" reescrita e enxugada: `setup.bat -Clone`, aba Catálogo com sub-abas, busca e filtros,
catálogo 62 → 76 vozes (14 Azure ocultas sem chave), Azure pelo painel/`voice/.env`, voz clonada
(`kind: "clone"`, consentimento, `503 clone_unavailable`, sem `speed`, marca d'água). Detalhes ficam no `voice/README.md`.
- `tools.md`: evidência `pnpm test:voice` → 133 passed; nova subseção "Clonagem de voz" (Python 3.12.13,
chatterbox-tts 0.1.7, torch/torchaudio 2.6.0+cu124, numpy 1.26.4, transformers 5.2.0, verificados no venv)
com os tempos do teste na GPU; Azure continua em candidatas como "código pronto, sem chave real".
- `gotchas.md`: item 44 ampliado (aspas, gravar o script em arquivo); item 53 cita `azure`/`clone` e o
reinício do worker; novos itens 62 (`w-full` fixo em `Select`/`Input` e `cx()` sem merge), 63 (`.tsx` CRLF),
64 (Xet travando o download, pesos não fixados), 65 (venv separado), 66 (timeout em fala clonada longa),
67 (`speed` ignorado e marca d'água PerTh).
## 1.10.1 — 16/11/2026
- `SKILL.md`: logo após "Documentos do projeto", um ponteiro para a skill `content-pipeline`
(metodologia de 8 etapas: o *quê* e o portão de cada etapa). Esta skill continua sendo o *como*
técnico. O conteúdo da `content-pipeline` não foi duplicado.
## 1.10.0 — 16/11/2026
- Novo `references/clipper.md`: Clipador (`clipper/`, 127.0.0.1:4520), banco `data/clipper/clipper.db`
(v2), pastas de blocos e cortes, tabela "Onde mexer", juiz pela CLI sem chave de API (Codex
`gpt-6-luna` padrão, Claude ou off; `PUT /v1/judge`), regras, evidência da live real e lacunas.
O arquivo aponta para `clipper/README.md` em vez de duplicá-lo.
- `SKILL.md`:
- `description` cita o Clipador;
- `clipper/README.md` entra nos documentos de consulta;
- estrutura ganhou a linha do Clipador, portas 4500/4510/4520 e banco do painel v3;
- "Onde mexer" ganhou a linha do Clipador e o passo 6b do setup;
- subida/testes incluem `pnpm test:clipper` e o aviso quando o Clipador não está instalado ou a porta está ocupada;
- a invariante de escopo agora diz que a publicação real em qualquer rede segue fora, que é a próxima fase pedida pelo usuário e que "Aprovar" só marca o corte;
- a seção "Manutenção" foi enxugada.
- `gotchas.md`:
- nova seção "Clipador", itens 57–61: `-ss` antes do `-i` com o filtro `ass`, `.upper()` quebrando a tag `\c`, falsos positivos com o chat calmo, pico escolhido antes do filtro de assentado, e hora do chat por `wall_end`;
- item 28 agora inclui o juiz do Clipador (`codex.js`);
- item 51 cita a migração v3.
- `tools.md`:
- nova seção do Clipador com versões verificadas: Python 3.12.13, FastAPI 0.159.1, uvicorn 0.54.0, httpx 0.28.1, websockets 17.4, Streamlink 8.6.3, pytest 9.1.1 e FFmpeg com libass;
- candidatas novas: publicação dos cortes (próxima fase) e chat do YouTube.
- `panel.md`: banco v3 (`account_channels`) e card/rotas "Canais de live".
## 1.9.0 — 16/11/2026
- "Voz e legenda": catálogo 15 → 62 vozes, motores novos `kokoro` (offline, CPU; feminina pt-BR
offline `kokoro-pf-dora`) e `google` (gTTS, online, só normal/lenta); campos do catálogo
`kokoroVoice`/`kokoroLang`/`googleLang`/`googleTld`; `ONLINE_ENGINES`; rótulo
offline/online nos selects do painel (`voiceOptionLabel()`); regra de URL do lock ampliada
para release versionado no GitHub. `description` cita os quatro motores.
- `tools.md`: kokoro-onnx 0.6.1, phonemizer 3.6.0, espeakng-loader 0.2.4, gTTS 2.5.4; teste das
54 vozes Kokoro (45 aprovadas) e tempos de síntese; `pnpm test:voice` → 127 passed; candidatas
Azure Speech e SAPI do Windows; vozes famosas do TikTok/CapCut marcadas "não copiar".
- `gotchas.md`: item 53 ampliado (motor novo exige reiniciar); itens 54 (int8 do Kokoro não roda),
55 (avisos "constant folding" do fp16), 56 (cache do sha256 na recarga do catálogo).
## 1.8.0 — 16/11/2026
- "Voz e legenda": catálogo recarrega sozinho (`_refresh_voices_if_changed` em
`voice/app/main.py`, chamado em `GET /v1/voices`, `GET /v1/voices/{id}` e
`POST /v1/synthesize`); catálogo com defeito mantém as vozes atuais. Substitui a instrução da
1.6.0 de chamar `POST /v1/voices/reload` após editar o catálogo (a rota segue para forçar).
- `gotchas.md`: item 53 (uvicorn sem `--reload` no `scripts/dev.ts`: código novo exige reiniciar).
- `tools.md`: evidência `pnpm test:voice` → 124 passed.
## 1.7.0 — 16/11/2026
- Novo `references/panel.md`: banco v2 (backup em `data/backups/`, `foreign_key_check`),
árvore de vertentes (`branch_count` 1–4, `file_key`, `status`, `branches_status`), votação A–D,
`prepareBranches` + fila em `onAgentRunClosed`, contas (redes `mock`) e dashboard com métricas
simuladas; evidência e lacunas.
- `SKILL.md`: estrutura com `<file_key>` e `.choices.json`; limitação do overlay (só A/B);
painel é do usuário; linha "Onde mexer" das vertentes/contas/dashboard; `description` ampliado.
- `tools.md`: `@xyflow/react` 13.0.1.
- `gotchas.md`: itens 48–52 (clique no xyflow, rolagem do canvas, `grid-cols-1`, conexão em
`globalThis`, `.mts` + `file:///`).
- Pedido como 1.6.0, mas essa versão já tinha sido usada por outra rodada (catálogo de vozes).
## 1.6.0 — 16/11/2026
- "Voz e legenda": catálogo base com 15 vozes (Piper offline faber/cadu/jeff; Edge pt-BR, pt-PT e
`multi-*`), ponteiro para a tabela de `voice/README.md`; voz nova no catálogo entra com
`POST /v1/voices/reload`, sem reiniciar.
- `tools.md`: papéis de edge-tts/piper atualizados, evidência do catálogo de 15 vozes, `edresson`
fora; RVC pt-BR no Hugging Face sem licença clara → nada em `user-voices.json`.
- `gotchas.md`: itens 45–47 (Edge `NoAudioReceived`, acentos no teste manual do Piper,
`faster_whisper.decode_audio` com o PyAV do venv — só teste avulso).
## 1.5.0 — 16/11/2026
- Página Vozes do painel (`/voices`): seção "Voz e legenda" (ouvir, voz de personagem com
origem/licença, legenda + `.srt`, configurações que gravam `voice/.env` e reiniciam o serviço);
`description` cita `.srt` e a página.
- "Onde mexer": linhas da página Vozes (`panel/src/lib/voice.ts`, `api/voice/*`, `voice-*`),
formato de história (`STORY_FORMATS` + `StoryKind`, `DescribedSelect`) e logo/ícones
(`logo.tsx` + `app/icon.svg` juntos, `shrink-0`).
- `VOICE_DEVICE=auto` agora escolhe CPU com GPU ocupada na subida; `422 rvc_failed`.
- `tools.md`: 122 testes, medição da legenda na CPU, modelos RVC candidatos sem licença.
- `gotchas.md`: item 31 reescrito (auto + nova medição); itens 40–44 (órfão na 4510, `.pth`
não-RVC, ícone que some, grade da barra lateral, heredoc que perde `\\`); números estáveis.
## 1.4.1 — 16/11/2026
- `gotchas.md`: itens 37–39 do `setup.ps1` (`Select-Object -First 1` no `nvidia-smi` escondia a
GPU, variante explícita do torch no `uv`, `ErrorActionPreference` e stderr do uv).
- `tools.md`: torch `2.11.0+cu128` com CUDA verificado, `VoiceConverter` em `cuda:0`,
pré-requisitos do Applio baixados, setup repetível (2x saída 0); RVC ponta a ponta segue não verificado.
## 1.4.0 — 16/11/2026
- Serviço de voz (`voice/`, 127.0.0.1:4510): seção "Voz e legenda" no `SKILL.md` apontando para
`voice/README.md`; linhas novas em "Várias histórias" e "Onde mexer" (serviço, catálogo/lock,
`setup.bat`/`start.bat`); `description` cobre narração, RVC, transcrição e instalação/subida.
- Escopo: painel/API/banco saíram de "fora do escopo" (já existem); Applio próprio em
`voice/vendor/applio`, Applio pessoal do usuário continua intocável.
- `tools.md`: seção do serviço de voz com versões verificadas (uv 0.11.26, Python 3.12.13,
edge-tts 7.3.1, piper-tts 1.8.0, faster-whisper 1.2.1, ctranslate2 4.8.3, Applio 3.7.0,
torch 2.11.0), evidência `pnpm test:voice` 117 passed; integração com o render como candidata.
- `gotchas.md`: itens 30–36 (cuBLAS na 1ª inferência, GPU disputada, Edge 403, lock do Piper,
LRU no Windows, `\\` no `package.json`, BOM do `setup.ps1`).
## 1.3.0 — 16/11/2026
- Codex CLI 0.169.0 integrado ao painel (flags e eventos verificados); `AGENTS.md` na raiz.
- Novo agente `cenaforge-dashboard-designer` (opus, a pedido do usuário: design exige mais capacidade) para a interface do painel.
- `gotchas.md`: itens 27–29 (Codex fora de Git, shims do npm, ruído do stderr).
## 1.2.1 — 16/11/2026
- Convenção de portas: faixa 4500–4599; painel movido de 4310 para 4500.
## 1.2.0 — 16/11/2026
- Estrutura para várias histórias: `stories/<história>/`, `config/<história>-epNN.json`,
assets por história e biblioteca `assets/library/`.
- Painel Next.js (`panel/`, `pnpm panel`, porta 4310): histórias, episódios, render com player,
votação A/B, assets e agentes Claude/Codex pela CLI. Linha na tabela "Onde mexer".
- `tools.md`: Next.js, `node:sqlite`, Claude Code CLI 2.1.314; Codex como candidato não testado.
- `gotchas.md`: itens 22–26 (porta, `.cmd`, Next 16.4, `.mts`, stdin do `claude -p`).
## 1.1.1 — 16/11/2026
- `godot/scripts/` organizado em `core/` (main, scene_config, timeline_controller),
`builders/` (street_builder, rider_builder, facade_painter) e `view/` (camera_controller,
overlay_controller); caminhos da tabela "Onde mexer" atualizados.
- Pasta `stories/` criada com guia de estrutura (usada pelo `cenaforge-story-writer`).
## 1.1.0 — 16/11/2026
- Economia de tokens: `references/token-economy.md` (modelo por tarefa, regras de leitura barata).
- Scripts Python (biblioteca padrão) em `scripts/`: `runs_summary.py`, `inspect_strip.py`,
`new_scene.py`, `check_skill.py`, `clean_runs.py`, mais `_common.py`. Testados nos casos
normal e de erro.
- Agentes novos: `cenaforge-story-writer` (sonnet; enredo, diálogos, overlay em `stories/`) e
`cenaforge-token-auditor` (sonnet; encontra repetição e cria scripts).
## 1.0.1 — 16/11/2026
Correções vindas da primeira auditoria do `cenaforge-skill-updater` (rodada sem edição):
- "Onde mexer": listas fechadas do contrato (`LIGHTING_PRESETS`, `RIDER_ASSETS`,
`BACKGROUND_MODES`) apontadas em `scene_config.gd`.
- Receita: opções do `render` e `pnpm verify`; tempo da prévia corrigido para 42–44 s.
- Validação: comando da tira generalizado para qualquer FPS/duração, gravando em `inspect/`;
aviso de que os quadros de `inspect/` são fixos até 11 s.
- `tools.md`: origem real das configurações do renderizador; proporção do tempo de render corrigida.
- `gotchas.md`: cabeçalho diz quais itens têm registro no TEST_RESULT; seção inclui TypeScript.
## 1.0.0 — 16/11/2026
- Criação da skill a partir da prova de conceito validada (ver `doc/TEST_RESULT.md`).
- Pipeline JSON → Godot 4.7.2 (Mobile) → PNG → FFmpeg 7.1.1 (libx264) → FFprobe.
- Receita de vídeo, mapa "onde mexer", invariantes, checklist de validação.
- `references/tools.md`: inventário com versões verificadas e critérios para ferramentas novas.
- `references/gotchas.md`: 21 armadilhas observadas no teste.
+228
View File
@@ -0,0 +1,228 @@
---
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.
@@ -0,0 +1,510 @@
# Clipador (`clipper/`) — cortes automáticos de live
Fonte completa: **`clipper/README.md`**. Ele cobre a arquitetura, as regras da heurística, o juiz, a API,
o `.env` e os limites. Este arquivo só diz onde mexer e o que não pode quebrar. Não copie o README para cá.
## O que é
Serviço FastAPI local (Python 3.12, `clipper/.venv`) em `127.0.0.1:4520`. Ele grava uma live (Twitch, YouTube
ou Kick) ou um VOD, lê o chat, transcreve pelo serviço de voz e pede o veredito a uma IA pela CLI. Depois
renderiza cortes verticais (1080×1920, padrão) ou horizontais (1920×1080, YouTube). Toda rota, exceto `GET /health`, exige `X-Service-Key` (`CLIPPER_SERVICE_KEY` de
`clipper/.env`; nunca copie a chave).
| O quê | Onde |
|---|---|
| Banco do Clipador | `data/clipper/clipper.db` (`PRAGMA user_version` 10, `SCHEMA` em `clipper/app/db.py`: v1 tabelas, v2 `settings`, v3 jogo/varredura/emotes/configuração do corte — colunas novas em `sessions`, `channels.settings_json`, `chat.emotes`, `clips.learned`, tabelas `games` e `emotes`; v4 `edits` (`clip_id`, `project_json`, `rev`, `cover`, `exported_at`, `created_at`, `updated_at`); v5 `face_track`; v6 `games.notes_json`/`games.edited_at`; v7 `edits.origin` (`ai`/`user`) + `edits.ai_project_json`; v8 `clips.aspect` (`vertical`/`horizontal`, padrão `vertical`, gravado no render); v9 `sessions.capture_json` (o que a captura gravou de fato; sessões antigas `NULL`); v10 tabela `deleted_clips` (marca do corte apagado, `ON DELETE CASCADE` com a sessão)). Migra ao subir o serviço. **Nunca altere uma migração já aplicada** (o banco real estava em v4 quando a v7 nasceu): coluna nova = `ALTER` numa versão nova |
| Blocos gravados (`.ts` de 30 s + `segments.csv`) e frames | `data/clipper/sessions/<id>/` (frames em `frames/`) |
| Pesos do rastreio de reação (YuNet, MediaPipe, OpenSeeFace) | `data/clipper/models/`, fixados (URL imutável + sha256) em `clipper/models.lock.json` |
| Cortes prontos | `output/clipper/<sessão>/clip-<id>.mp4` + `clip-<id>.jpg` |
| Arquivos do editor (proxy, TTS) | `output/clipper/<sessão>/edit-<id>/` (narração em `tts-<hash12>.wav`) |
| Fontes empacotadas (ASS e prévia do painel) | `assets/fonts/` **plana** (Luckiest Guy Apache-2.0; Bangers, Anton, Bebas Neue, Poppins ExtraBold OFL-1.1; licença ao lado de cada `.ttf`), fixadas em `assets/fonts/fonts.lock.json` (URL presa a commit do google/fonts + sha256 + `family` = nome dentro do arquivo). Fonte nova: arquivo na pasta + entrada no lock (gotchas, item 105) |
| Vínculo canal → conta (painel) | tabela `account_channels` em `data/cenaforge.db` (migração **v3** do painel, `panel/src/lib/db.ts`; sem chave estrangeira para o canal) |
## Onde mexer
| Mudança | Arquivo(s) | Também atualizar |
|---|---|---|
| Captura (Streamlink → bomba Python → `ffmpeg -f segment`), linha do tempo, hora do chat, metadados (`title`/`category`) | `clipper/app/worker.py`, `sources.py` | `clipper/tests/` |
| Qualidade de gravação (`capture.quality`, argumentos do Streamlink, `OPTIONS` com GB/h, `record_run` → `sessions.capture_json`) | `clipper/app/capture.py`; validação `CAPTURE_QUALITIES` em `layout.py`; gravação do 1º bloco em `worker.py` | `clipper/tests/test_capture_quality.py` |
| Busca de quadro dentro de bloco `.ts` (`seek_args`, `grab_frame`) e emenda de resolução/codec (`uniform_segments`) | `clipper/app/media.py`; `clipper/app/editor_render.py`; `face.grab_bgr` e tamanho do quadro por bloco (`_frame_size`) em `face.py` | gotchas, itens 107–108 |
| Retomada de live (`Engine.live_check`, `keep_live`, `RESUME_DELAYS_S`, `resume_interrupted`), render que falha (`recover_orphan_renders`, `ORPHAN_RENDER_S` 300, `MAX_RENDER_ATTEMPTS` 3), cortes duplicados (`SAME_PEAK_S` 10, `SAME_MOMENT_OVERLAP` 0,6, `KEPT_STATUSES`/`VETO_STATUSES`, `discard_pending_duplicates`) | `clipper/app/worker.py` | `clipper/tests/test_resume.py`, `clipper/tests/test_render_and_duplicates.py` |
| Apagar cortes (`delete_clip`, `delete_many`, `select_ids`, `MAX_BATCH` 500, recusas `BUSY`/`PUBLISHED`/`CHANGED`, marca `marks`/`mark_spans`, arquivos só dentro das pastas do Clipador) | `clipper/app/clip_delete.py`; rotas em `main.py` (`ClipsDeleteIn`); marca lida em `worker.py` (veto depois do juiz) e na varredura (`intel.py`) | `clipper/tests/test_clip_delete.py`; `METHODS` em `panel/src/lib/clipper.ts`; seção "Apagar cortes" abaixo |
| Chat (IRC anônimo da Twitch com `CAP REQ :twitch.tv/tags` → emotes nativos e `room-id`; Pusher da Kick, emotes `[emote:id:NOME]`) | `clipper/app/chat.py` | — |
| Heurística: pesos, base de 3 min, mínimo proporcional (`_required_messages`), reações (`min_reactions`), chat fraco (`sparse_rate` 0,5 msg/s), momentos do chat/áudio/rosto (`_chat_moments`/`_audio_moments`/`_face_moments`; `face_*` em `Params`), `pick_peaks`, `fit_window` (duração de todo corte automático) | `Params` e funções em `clipper/app/scoring.py`; alvo `min_target` em `layout.py` | `clipper/tests/test_scoring.py` (regressões de falso positivo, chat fraco e rosto), `test_duration_banner_fonts.py` |
| Rastreio de reação — E/S: backends (MediaPipe; plano B OpenSeeFace), download sob demanda com sha256, recorte FFmpeg 6 qps, laço `face` | `clipper/app/face.py` (`for_scoring`, `must_wait`, `view`, `reset`); laço `_face_loop` e uso de `must_wait` na decisão do corte em `worker.py`; bancada `clipper/tools/face_bench.py` | `clipper/tests/test_face.py`, `clipper/models.lock.json`, `doc/FACE_BAKEOFF.md` |
| Rastreio de reação — lógica pura: sinal por segundo contra o neutro do streamer, rótulos, `reaction_moments`, `summarize` (linha do analista), `locate_cam` (câmera pelo rosto) | `ReactionParams` e funções em `clipper/app/reaction.py` | `clipper/tests/test_reaction.py` |
| Emotes: catálogo 7TV/BTTV/FFZ (canal + global, TTL 1 h, fonte que falha é ignorada), emojis, peso aprendido (`LEARN_UP`/`LEARN_DOWN` 0,3/0,15) | `clipper/app/emotes.py`; ingestão e aprendizado em `clipper/app/intel.py` (`ingest_chat`, `learn_from_clip`) | `clipper/tests/test_intel.py` |
| Contexto do jogo (categoria a cada `GAME_CHECK_S` 600, `screen_game`, perfil pela web; `clean_profile`, `save_profile`, `refine`, `delete_note`), varredura (`SCAN_*`), webcam (`detect_cam`: YuNet local primeiro, IA só se não achar ou `use_ai`; `CAM_RETRY_S` 300), opções `OPTION_DEFAULTS` (inclui `faceTrack`) | `clipper/app/intel.py` | README do Clipador |
| Juízes (analista + editor), prompts, glossário `CHAT_GLOSSARY`, linha "Rosto do streamer: …" do analista, schemas, chamada da CLI, pesquisa e refino do jogo (`PROFILE_SYSTEM`/`research_game`, `REFINE_SYSTEM`/`refine_game`), câmera | `clipper/app/judge.py`; montagem dos 6 frames do analista (8 se o trecho passa de 80 s) em `worker.py` | README do Clipador |
| Hashtags da legenda (`to_tag`, `fold`, `split_hashtags`, `compose`, `build_caption`; `MAX_TAGS` 8, `GAME_TAGS` 3, `MOMENT_TAGS` 4) | `clipper/app/hashtags.py`; uso em `judge_clip` de `worker.py`; campo `hashtags` em `judge.py` (`VERDICT_SCHEMA`, `PROFILE_SCHEMA`, `Verdict.hashtags`) e `PROFILE_LISTS`/`clean_profile`/`Intel.session_game` em `intel.py` — ver "Hashtags da legenda" abaixo | `clipper/tests/test_hashtags.py` |
| Configuração do corte: camadas padrão ← canal ← sessão ← projeto (`DEFAULTS`, `merge`, `validate`), `format.aspect` (`ASPECTS`, `FRAME_SIZES`, `CANVAS_SIZES`, `aspect()`), `MODES` (5 modos, inclui `cam_only`), `resolved_mode` (queda para `blur` sem câmera; `full` no horizontal), retângulos, legenda, crédito, `duration` (`min_target`), `hook` (`HOOK_STYLES`, `HOOK_ANIMS`, `HOOK_FONT`), `capture`; fontes empacotadas (`PACKAGED_FONTS`, `font_files`, `ass_filter` = `ass=` com `fontsdir` só se o ASS usar uma delas); cadeia de layout reutilizável `layout_chain(settings, src, dst, tail, suffix, mode)` (usada por `video_filter` e pelo editor) | `clipper/app/layout.py`; rotas de settings em `main.py` (devolvem `aspects`, `frames`, `fontFiles`, `hookStyles`, `hookAnims` e `captureQualities`) | `clipper/tests/test_format_and_captions.py` (o vertical precisa continuar batendo com `clipper/tests/data/vertical_golden_sha256.json`); modo novo também em `LayoutMode`/`MODE_LABEL` de `panel/src/components/clipper-client.ts` e `resolvedMode` de `clip-editor-model.ts`; grupo novo também em `CutSettings` (`Aspect`, `aspectOf`, `withFormat` para serviço antigo) |
| Projeto de edição: modelo, tempo sessão↔saída, `normalize_cuts`, `validate_project`, `auto_project` (projeto da IA), `pick_hook` (texto do gancho), `CAPTION_PRESETS`, `SUGGEST_SCHEMA`/`clean_suggestion` | `clipper/app/editor.py` | `clipper/tests/test_editor.py`, `clipper/tests/test_editor_layers.py`; tipos espelhados em `panel/src/components/clip-editor-model.ts` |
| Render do corte (ASS animado, gancho e tarja `banner`, textos, barra, chat na tela `chat_events`, filtergraph, trecho mudo, áudio, proxy, forma de onda, capa e capa no início) | `clipper/app/editor_render.py` (`render_project`, `build_filter`, `build_project_ass`); cores ASS via `layout.ass_color`/`ass_inline_color` | [gotchas.md](gotchas.md) itens 57, 71, 74–78, 104–105 |
| Reenquadramento do jogo (`reframe.keys`, `perspective_filter`) e camadas inseridas (`kind: "inset"`, decoração numpy/OpenCV), `EASES`, `MAX_KEYS` 60, `MAX_INSETS` 12 | `clipper/app/reframe.py`; validação em `editor.py`; grafo em `editor_render.py` | `clipper/tests/test_reframe_insets.py`; interpolação espelhada em `clip-editor-model.ts` (`easeAt`, `interpolate`, `reframeAt`) — as duas precisam dar o mesmo valor; gotchas, item 106 |
| Rotas do editor, `ensure_edit`, `render_clip_edit`, `chat_for` (mensagens da sessão para o chat na tela) | `clipper/app/editor_api.py`; chamado por `Engine.render_clip` em `worker.py` | `ALLOWED` e timeout em `panel/src/lib/clipper.ts` |
| Legenda (tempo saneado: `clean_words`, `group_words`, `caption_blocks`; `build_ass`) e crédito — usada pelo render do editor e pelo worker, nos dois formatos | `clipper/app/subtitles.py` (`MIN_WORD_S` 0,06, `MIN_STEP_S` 0,04). `media.render_vertical` ainda existe em `media.py`, mas **não** é mais usado pelo render de cortes | `clipper/tests/test_format_and_captions.py`; [gotchas.md](gotchas.md) itens 57–58, 70, 90 |
| Rotas HTTP | `clipper/app/main.py` (editor: `editor_api.py`) | `ALLOWED` em `panel/src/lib/clipper.ts` (o proxy recusa caminho fora da regex) e o timeout por rota no mesmo arquivo |
| Variáveis do `.env` | `clipper/app/config.py` + `clipper/.env.example` | tabela do README do Clipador |
| Página `/clipper` | `panel/src/app/clipper/page.tsx`, `panel/src/components/clipper-*.tsx` (`clipper-cut-settings.tsx` modal do corte em 5 abas, com Gancho e "Qualidade da gravação"; `clipper-games.tsx` aba Jogos e emotes (editar perfil, pedir à IA, pedidos guardados); `clipper-queue.tsx` cartão com a análise, reação do rosto (`FaceSignal`, `FACE_LABEL`), recuo do início `START_STEPS`, botão "Editar"/"Continuar edição", "Apagar" e seleção discreta (`SelectionPill`); `clipper-judge.tsx` interruptor "Rastrear a reação do streamer"; `clipper-sessions.tsx` cartão da sessão (`sessionHealth`, selo de quem achou a câmera, relógio `RecordingClock`, cadência `SummaryCadence`) e cabeçalho em `clipper-studio.tsx`), cliente `clipper-client.ts` | [panel.md](panel.md) |
| Página do editor `/clipper/edit/[clipId]` | `panel/src/app/clipper/edit/[clipId]/page.tsx` + `panel/src/components/clip-editor*.ts(x)` (papel de cada arquivo em [panel.md](panel.md#editor-de-cortes)); tokens `--color-nle-*` e bloco `.nle` em `panel/src/app/globals.css` | [panel.md](panel.md#editor-de-cortes) |
| Ponte e proxy do painel | `panel/src/lib/clipper.ts` + `panel/src/app/api/clipper/[...path]/route.ts` | — |
| Fontes (canais de live) nos canais de publicação | `linkChannel`/`endChannel`/`accountsForChannel` em `panel/src/lib/accounts.ts`; rotas `panel/src/app/api/accounts/[id]/channels/`; card "Fontes de corte" em `account-manager.tsx`. Na UI "Canais" virou **"Fontes"**; código e rotas seguem `channels` | [panel.md](panel.md) |
| Publicação dos cortes | despachante do painel lê `GET /v1/clips` com `channel=` (fontes, separadas por vírgula), `status=ready,approved` e `ids=`; aprova (`PATCH status=approved`) e marca `published` | [publishing.md](publishing.md) |
## Como os momentos nascem (resumo; regras completas no README)
- `source` do corte: `chat`, `audio`, `face` (rosto forte com apoio), `ai` (varredura) ou `manual`.
- **Chat:** mínimo nos 8 s do pico = 3× a mediana recente, entre 4 (`min_peak_floor`) e 12 (`min_peak_messages`), e
≥ 2 reações (texto ou emote) — ou o dobro do mínimo em mensagens. Emote soma bônus + peso aprendido do canal.
- **Áudio:** sempre sem chat; também com chat fraco (< `sparse_rate` 0,5 msg/s).
- **Varredura** (`scanEnabled`, `scanIntervalS` 180, 60–900): a IA vê até 7 frames + fala + chat + perfil do jogo e
propõe 0–2 momentos; proposta com nota < 4 (`SCAN_MIN_PROPOSAL`) não vai aos juízes. Cada janela grava em
`sessions.memory_json` `proposals` (quantas a IA propôs) e `created` (quantas viraram candidato) e loga
"varredura <sessão> lo–hi s: N proposta(s), M candidato(s)": é por aí que se sabe se ela não propôs ou se foi barrada.
- **Aprendizado dos emotes:** aprovar/rejeitar no painel = ±0,3/0,15 nos emotes de −10 s a +6 s do pico, uma vez por
corte (`clips.learned`); a decisão da IA conta com `factor=0.5`. Peso limitado a −1…3.
## Juízes (decisão do usuário: pela CLI, sem chave de API)
- Provedores `codex` (padrão `gpt-6-luna`; lista de `~/.codex/models_cache.json`), `claude` (`haiku`/`sonnet`/`opus`)
ou `off` (só a heurística).
- **ANALISTA** vê 6 frames (8 se o trecho passa de 80 s) + fala + chat + glossário e devolve `situation`, `what_happened`, `screen`, `speech`,
`chat_meaning`, `confidence` (0–1) e início/fim da ação. **EDITOR** vê só texto + a análise e escreve título,
legenda, nota e corte. Os dois podem recuar até `duration.backtrackS` (padrão 120 s) antes do candidato.
- `PUT /v1/judge`: provedor, `model` (editor), `analystModel` (vazio = o mesmo), `minScore`, `scanEnabled`,
`scanIntervalS`, `vision`, `camDetect`, `faceTrack`. Fica na tabela `settings`, sem reiniciar; o `.env` só dá o valor inicial.
- Codex: cada imagem com seu `-i`, todas antes do `-` final; `--search` é opção **global** (antes de `exec`).
- Custo fixo: cada chamada é um processo novo (2 por candidato). `codex_lean_overrides(search, config_file=None)` em
`judge.py` enxuga o Codex; o Claude leva `--setting-sources project,local`. Números e limites em
[token-economy.md](token-economy.md); teste: `test_codex_lean_overrides`. Vale após reiniciar o Clipador (gotcha 136).
- Não adicione chave de API ao juiz sem pedido do usuário. Corte manual é renderizado mesmo com nota baixa.
## Hashtags da legenda (`hashtags.py`)
Pedido do dono (17/11/2026): a IA põe as # certas, do jogo e da missão. A legenda do corte = texto + hashtags + crédito,
montada por `build_caption(text, tags, credit)` (partes separadas por linha em branco; o crédito é "🎥 Créditos: link").
- **Quem escolhe o quê:** o sistema fixa o **canal** (nome do streamer) e as do **jogo** (até 3 de `profile.hashtags`;
sem perfil ou sem a seção, o nome do jogo). A IA escolhe só as do **momento** (2–4 no campo `hashtags` do veredito:
missão, atividade, evento, modo, lugar, item ou personagem, de preferência com termos do perfil; sem genéricas e sem
repetir canal ou jogo). `JUDGE_SYSTEM` manda a `caption` sem hashtags; `split_hashtags` tira as que vierem no texto
e as junta às do momento.
- `compose(streamer, game, profile, moment)`: canal → jogo → até 4 do momento, sem repetidas (`fold`: sem #, acento e
maiúscula), até 8. `to_tag`: "ROB RUN" → `#ROBRUN`, "perseguição policial" → `#PerseguiçãoPolicial`; sem letra → `None`.
- `Verdict.hashtags` é tupla (padrão `()`); `_clean` aceita resposta sem `hashtags`. `_MOMENT` (varredura) **não** tem o
campo. Sem juiz ou com o juiz falhando, ainda saem as tags do canal e do jogo.
- Perfil do jogo: `PROFILE_SCHEMA` ganhou `hashtags` (3–6 que o público usa no TikTok, Shorts e Reels BR, a principal
primeiro); `PROFILE_SECTIONS` ganhou "Hashtags"; `clean_profile` normaliza com `to_tag`/`fold`. `game_context` também
passa as `mechanics` como termos para as tags do momento. `Intel.session_game(session)` devolve (nome, perfil) com o
mesmo critério do contexto.
- Painel: seção "Hashtags" (violeta, chips, editável, com chat) em `SECTIONS` e `ProfileView` de `clipper-games.tsx`;
`GameProfile.hashtags?` em `clipper-client.ts`. Armadilha de perfil sem a seção e de cortes antigos: gotchas, item 144.
- API: `GameRefineIn.section` aceita `"hashtags"` (chat da seção) e `GameProfileIn.hashtags` (lista, máx. 20) existe;
sem esse campo, salvar o perfil à mão apagaria as hashtags. Campo novo no perfil = acrescentar nos dois modelos de
`main.py`. Teste: `test_api_accepts_hashtags_in_profile_edit_and_section_chat`.
- Só vale depois de reiniciar o Clipador (gotchas, item 143). Limite: tags do momento dependem da CLI real; não testado
com IA real.
## Configuração do corte
- `GET/PUT /v1/channels/{id}/settings` (padrão do streamer) e `/v1/sessions/{id}/settings` (`settings_json`,
sobrescreve campo a campo). Modos `auto|blur|cam_top|game_only|cam_only`; `cam`/`game` = retângulos 0–1 do quadro
original. `cam_only` = câmera do streamer na tela inteira; `cam_top` e `cam_only` sem câmera marcada caem em `blur`.
- `format.aspect`: `vertical` (padrão, 1080×1920) ou `horizontal` (1920×1080, YouTube). No horizontal: quadro original
inteiro (ou `layout.game` recortado para preencher); `cam_only` continua valendo; `auto`/`blur`/`cam_top`/`game_only`
viram quadro inteiro (`resolved_mode` = `full`). ASS num quadro lógico 2560×1440 → tamanhos em px do JSON saem a
75 %; legenda automática a 85 % da altura; crédito no canto direito. Tabela de tamanhos no README do Clipador.
- `duration`: padrão `{minS: 60, maxS: 90, backtrackS: 120}`; limites `minS` 5–120, `maxS` 15–180, `backtrackS` 0–120 e
`minS` < `maxS` (senão `LayoutError`). Para Shorts de terceiros, baixe o canal para ≤ 60 s. **Todo corte automático
sai com ≥ `minS` + 1 s e ≤ `maxS`** (`layout.min_target` = `minS` + 1,1 s, por `scoring.fit_window`): heurística,
varredura, juízes, `auto_project` (depois de silêncios e aparos), remoção de silêncio e "IA sugere". Faltando
material, o corte cresce para trás (no começo da gravação, para a frente); gravação menor que o mínimo não inventa
vídeo. "Cortar agora" e a edição à mão continuam livres. Não reintroduza ajuste de início/fim fora de `fit_window`
(gotchas, item 103).
- `hook` (estilo do gancho que o projeto da IA põe na abertura): `{style: plain|banner, bg, color, font,
anim: pop|fade|none|slide, seconds 1–8}`; padrão `banner`, `#00FF00`, `#FFFFFF`, Luckiest Guy, `slide`, 3 s. Tudo em
ASS, sem filtro extra (entrada `slide` em duas camadas: gotchas, item 104).
- Fontes (`caption.font`, `hook.font`, `font` dos textos): as do Windows (Arial Black, Arial, Impact, Verdana, Segoe UI
Black, Trebuchet MS) e as empacotadas de `assets/fonts/` (sha256 conferido ao carregar). Nome = família de dentro do
arquivo ("Poppins ExtraBold").
- `capture.quality`: `best` (padrão) | `1440p` | `1080p` | `720p` | `480p` (teto), por canal e por sessão (não por
corte); vale na **próxima** gravação ou retomada. `CLIPPER_QUALITY` não é mais lida. Detalhes em "Qualidade de
gravação" abaixo.
- `GET …/settings` devolve `own`, `effective`, `defaults` (com `format`, `duration` e `hook`), `modes`, `fonts`,
`fontFiles` (`{família: "assets/fonts/…ttf"}`), `hookStyles`, `hookAnims`, `aspects`, `frames`
(`{vertical, horizontal: {width, height, canvasWidth, canvasHeight}}`) e `captureQualities`
(`[{id, label, maxHeight, gbPerHour, gbPerHourMax, hint}]`). O formato do arquivo renderizado fica em `clips.aspect` e
sai no JSON do corte (antes do 1º render, `vertical`).
- Webcam: `POST /v1/sessions/{id}/detect-cam` (YuNet local em 12 quadros, sem IA; a IA olha 3 frames só se o local
não achar rosto e `vision` estiver ligada, ou com `?ai=true`) ou automática nos 2 primeiros blocos, se `camDetect`.
`cam_json.source` = `yunet` | `ai` | `manual`. Prévia sem salvar (no formato efetivo): `POST …/preview`; quadro: `GET …/frame?t=`.
- Jogo da sessão: `PUT /v1/sessions/{id}/game` trava a troca automática. Emotes do canal:
`GET /v1/emotes?channel=twitch-<login>`.
- Timeouts do proxy do painel: 8 min para `games/*/(research|refine)`, 5 min para
`clips/*/(proxy|preview-render|retranscribe|tts|suggest|waveform)`, 3 min para `detect-cam|preview|check`, 30 s para
`sessions/*/face(/reset)`, 2 min o resto.
## Qualidade de gravação (`capture.py`)
Fonte completa (tabelas de nomes de stream e de custo): seção "Qualidade de gravação" de `clipper/README.md`.
- Streamlink: `best` (ignora `audio_only` e `*_portrait`); teto = `--stream-sorting-excludes >{teto}60` com
`best,worst-unfiltered` (sem nada abaixo do teto, pega a menor variante: nunca falha pela qualidade). Twitch com
`best`/`1440p`: `--twitch-supported-codecs h264,h265` (o 2K vem em HEVC). AV1 não é pedido (FFmpeg local sem
libdav1d). Sem opção de 30/60 qps (o topo é quase sempre 60 qps; o corte sai em 30 qps).
- Gravado de fato: `ffprobe` do 1º bloco de cada execução → `sessions.capture_json` → `capture` em
`GET /v1/sessions/{id}` (`quality`, `width`, `height`, `fps`, `codec`, `kbps`, `gbPerHour`, `fromIdx`, `runs`,
`mixed`); `null` = sessão antiga (≤ 720p). Painel: "gravando em L×A · fps" no cartão da sessão.
- Medido (17/11/2026, trecho real do skipnho): disco/hora 720p60 1,5 GB, 1080p60 3,6 GB; 1440p60 4,7–4,9 GB/h só com
blocos **gerados** do 1080p (nenhuma live 2K no ar). Render de 60 s com NVENC 6,2–6,7 s em qualquer resolução. A
câmera recortada no vertical sai mais nítida em 1080p que em 720p; 2K ampliado não ganha nada.
- O que existe nas plataformas (17/11/2026): Twitch quase sempre até `1080p60` (+ `*_portrait` em 9 de 143 canais);
Kick até `1080p60`; YouTube pelo Streamlink para em 1080p, até em live "4K".
- Retomada pode trocar de qualidade: o render e o proxy uniformizam o trecho que atravessa a emenda (gotchas, item 108).
## Retomada, render que falha e cortes duplicados (`worker.py`)
Regras completas em "Armadilhas já resolvidas" do README do Clipador.
- **Retomada:** `Engine.live_check` devolve `live` / `offline` ("No playable streams…") / `unknown` (timeout, erro,
JSON inválido). `keep_live` tenta de novo com esperas `RESUME_DELAYS_S` (0, 10, 20, 40, 60, 90, 120 s ≈ 5,7 min)
antes de processar; enquanto tenta, a sessão fica `interrupted`. Vale na subida e para a captura que cai no meio da
live. Só processa depois de esgotar as tentativas ou de ver `offline` 2 vezes seguidas; 3 retomadas seguidas sem
bloco novo desistem. `POST /v1/sessions/{id}/resume` vale para qualquer live que não esteja gravando.
- **Render:** qualquer exceção no render marca o corte `error` com a mensagem e a fila segue. `rendering` órfão há
mais de 5 min volta para `pending`; na 3ª vez vira `error`.
- **Duplicados:** o candidato guarda a janela original (`reasons.candidateStartS/EndS`) e não nasce se o pico estiver a
≤ 10 s de outro corte ou sobrepuser o trecho final ou a janela original de qualquer corte (inclusive `discarded`).
O corte apagado conta como existente (marca em `deleted_clips`, ver "Apagar cortes").
Depois do juiz, o trecho final é conferido contra `VETO_STATUSES` (= `KEPT_STATUSES` pendente/renderizando/pronto/
aprovado/publicado **+ `rejected`**) e contra os apagados que estavam num desses estados: "mesmo momento" (pico a
≤ 10 s ou ≥ 60 % do trecho mais curto coberto) vira `discarded` com "Duplicado do corte N (mesmo momento | que você
rejeitou | que você apagou)" (`judge.duplicateOf`). O descartado pela IA **não** veta o trecho final. "Cortar agora"
(manual) só ganha `judge.warning`. Antes de cada render, `discard_pending_duplicates` usa o **mesmo veto**: tira da
fila o pendente/renderizando igual a um corte pronto, aprovado, publicado ou rejeitado, a um apagado que estava num
desses estados ou a um pendente mais antigo, com o mesmo motivo "Duplicado do corte N (…)". Descartado pela IA não
veta; manual, exportado do editor e o que está renderizando agora nunca saem. Duplicados já prontos não são
mexidos: rejeite ou apague à mão.
## Apagar cortes (`clip_delete.py`)
Fonte completa: seção "Apagar cortes" e tabela "API" de `clipper/README.md`.
| Rota | Faz |
|---|---|
| `DELETE /v1/clips/{id}[?confirmPublished=true]` | 200 `{id, sessionId, status, removedFiles, left: [{file, reason}]}`; 404 `not_found`; 409 `{error, code}` com `busy_candidate`, `busy_rendering`, `published` ou `changed` |
| `POST /v1/clips/delete` `{ids: [≤ 500]}` **ou** `{statuses, sessionId?}`, `confirmPublished?` | 200 `{requested, remaining, deleted, failed: [{id, code, reason}]}`; 400 sem os dois, com os dois ou `sessionId` com `ids`; 422 acima de 500 ou estado inválido |
- Recusa `candidate`, `rendering` e o `pending` que o motor já pegou (`engine._rendering`, sob o mesmo `engine.lock`
do render). `published` só com `confirmPublished`. Cada corte do lote segue as mesmas regras; recusado vai em `failed`.
- Some: linha em `clips`, `edits`, `clip-<id>.*`/`clip-<id>-*` em `output/clipper/<sessão>/`, a pasta `edit-<id>/` e os
quadros do juiz `frames/clip<id>-*.jpg`. Os blocos `.ts` ficam (são da sessão). Só apaga dentro de
`CLIPPER_OUTPUT_DIR`/`CLIPPER_DATA_DIR`, com caminho resolvido; link ou junção some só o link; o que não pôde vai em
`left` com o motivo.
- **O momento apagado não volta:** a marca em `deleted_clips` (pico, trecho final, janela original, estado) entra no
anti-duplicado do candidato (`find_new_clips`), na varredura (`mark_spans`), no veto depois do juiz e na limpeza da
fila antes do render (`discard_pending_duplicates`), nos dois só se o estado era de `VETO_STATUSES`. Não apague a marca para "liberar" o momento sem pedido.
- Proxy do painel: `METHODS` em `panel/src/lib/clipper.ts` aceita só POST em `clips/delete` e só GET/PATCH/DELETE em
`clips/{id}` (outro método = 405). O painel manda os **ids que está mostrando**, nunca `statuses`: corte que chega
depois da confirmação não é apagado junto. UI em [panel.md](panel.md#página-clipper-clipador).
## Rastreio de reação (rosto do streamer)
Fonte completa: seção "Rastreio de reação" de `clipper/README.md`; plano e licenças em `doc/PLANO_RASTREIO_REACAO.md`;
medições em `doc/FACE_BAKEOFF.md`. Roda no PC, sem IA. Opção `faceTrack` (padrão ligada; `PUT /v1/judge`).
- **Stack (licenças livres para publicar):** YuNet `face_detection_yunet_2026may.onnx` (MIT, `cv2.FaceDetectorYN` do
OpenCV 5) acha a câmera; MediaPipe Face Landmarker (Apache-2.0, 478 pontos + 52 blendshapes) mede expressões;
OpenSeeFace `.onnx` (BSD-2) é o plano B (só posição, sem expressões). **Não use** SCRFD/InsightFace, YOLO-Face,
LibreFace, OpenFace 3.0 nem Py-Feat: licença incompatível com publicação.
- **Fluxo:** `face.py` (E/S) recorta a câmera +10 % pelo FFmpeg (~384 px, 6 qps, `rgb24` por pipe) → MediaPipe em
modo VIDEO, um landmarker por bloco → tabela `face_track` (status `done`/`no_cam`/`error`), `cx`/`cy`/`size` no
**quadro inteiro**. `reaction.py` (lógica pura, sem cv2/mediapipe) faz o resto. Câmera trocada → série refeita.
- **Câmera pelo rosto** (`locate_cam`): grupo de rostos estável em ≥ 50 % dos quadros **e** confiança média do grupo
≥ `ReactionParams.min_cam_score` (0,7). Webcam real dá 0,92–0,94; desenho de rosto em live sem câmera dá 0,61–0,66
(gotchas, item 92). Não baixe esse piso sem medir.
- **Sinal:** z robusto de cada canal contra o neutro dos últimos 180 s do próprio streamer; rótulos `risada`, `grito`,
`susto`, `choque`, `raiva`, `confuso`. Ajuste por `ReactionParams` (pisos por canal, pesos, limiares).
- **Cortes:** rosto **reforça, não manda.** `reasons.face` + bônus ≤ 0,6 em momentos do chat/áudio; fonte `face` só
com z ≥ 6 **e** apoio (áudio suavizado ≥ 1,5 ou ≥ 2 mensagens de reação). A decisão do corte espera o rosto do
trecho (no máximo 2 blocos atrás da transcrição). O analista recebe a linha "Rosto do streamer: …" — exceto
quando a série da sessão é do plano B OpenSeeFace (sem blendshapes): aí `FaceService.summary` não manda linha.
- **Modelos:** `setup.ps1` passo 6b baixa e confere o sha256; o serviço baixa sob demanda se faltar. Falha de modelo
não marca blocos: nova tentativa em 5 min. Modelo novo = entrada em `clipper/models.lock.json` com URL imutável +
sha256 + licença.
- **Dependências** (`clipper/requirements.txt`): `mediapipe`, `opencv-contrib-python`, `numpy`, `onnxruntime` —
versões em [tools.md](tools.md). Nunca instale `opencv-python-headless` junto (gotchas, item 80).
- **Rotas:** `GET /v1/sessions/{id}/face?from=&to=` (série, `signal`, picos, câmera, progresso) e
`POST …/face/reset`. Ambas na regex `ALLOWED` do painel.
- **Bancada** (lê o banco só para leitura, saída em `output/face-bench/`):
`clipper\.venv\Scripts\python.exe clipper\tools\face_bench.py --session 3`. Armadilhas: [gotchas.md](gotchas.md) itens 79–84 e 92–95.
- **Instância de teste isolada** (receita em "Variáveis" de `clipper/README.md`): `CLIPPER_PORT=4521`,
`CLIPPER_DATA_DIR=output/<teste>/data`, `CLIPPER_OUTPUT_DIR=output/<teste>/clips` no ambiente (padrões:
`data/clipper` e `output/clipper`; as duas precisam ficar **dentro** do repo, senão `ConfigError` em
`clipper/app/config.py`), juiz `off`, e o `sqlite_sequence` de `sessions` do banco novo em 90000 antes da 1ª sessão
(gotchas, item 93). Cuidados com cópia do banco real: item 77.
## Editor de cortes (`/clipper/edit/<id>`)
Fonte completa: seção "Editor de cortes" de `clipper/README.md` (campos do projeto, render, medições, limitações).
Pesquisa de referência (OpenCut, effectcraft, Descript, Submagic etc.; nenhum código copiado):
`doc/clip-editor-research.md`.
- **Um caminho só de render:** `Engine.render_clip` (`worker.py`) → `editor_api.ensure_edit` (gera o projeto da IA se
o corte não tem) → `editor_api.render_clip_edit` → `editor_render.render_project` (FFmpeg). Não reintroduza
render que contorne o projeto de edição.
- **Formato:** o projeto pode trocar o formato só daquele corte em `settings.format` (mesma validação de
`layout.validate`); projeto antigo sem `format` segue canal/sessão. Export, `preview-render` e capa saem no formato do
corte (1080×1920 ou 1920×1080). O Programa do painel segue o formato do corte (tamanhos de `frames`; em 16:9 no
horizontal).
- **Projeto da IA** (`editor.auto_project`): trecho `action_start_s − 0,8 s … reaction_end_s + 0,8 s`, encaixado em
palavras e depois em `fit_window` (≥ `minS` + 1 s, ≤ `maxS`; o início só adianta se o mínimo continuar); tira vãos
≥ 2 s sem fala, quietos (< −38 dBFS) e a mais de ±3 s do pico; legenda
Whisper preset `pop` (tempo saneado por `subtitles.py`); gancho por `pick_hook` (regra abaixo) no estilo do grupo
`hook`; zoom 1,25× no `peak_s` (no rosto em `cam_top`); capa no pico; `meta.origin = "ai"` com data, modelo e passos.
**A IA não propõe reenquadramento nem camadas inseridas** (o analista não devolve região da tela).
- **Gancho (`editor.pick_hook`):** o `hook` do analista só vale se tiver ≤ 8 palavras, ≤ 48 caracteres e nenhum tempo
da gravação (3+ dígitos seguidos de "s"); senão vale o título do editor. Em qualquer caso a menção ao tempo
("Aos 5085s, …") é removida, a 1ª letra vira maiúscula e o texto para em palavra inteira até 60 caracteres.
- **Origem:** `edits.ai_project_json` guarda o projeto da IA ("Projeto da IA" no editor volta a ele). PUT do editor
marca `origin = 'user'`. Rejudge (corte volta a `pending`) apaga **só** edit de origem `ai`; o do usuário fica.
- **Tempo:** `cuts`, palavras, textos, zoom, narração e capa em tempo da sessão; só o gancho em tempo de saída.
- **Validação forte** em `validate_project` (3–180 s, limites de quantidade, texto escapado no ASS, áudio só de
`assets/` ou dos TTS do editor, nada vira shell). Campo novo no projeto = validação com valor padrão (projeto
antigo continua abrindo) + teste em `clipper/tests/` + tipo em `clip-editor-model.ts`.
- `clip_view` devolve `edit: {updatedAt, exportedAt, cover, origin}` (o painel decide "Editar"/"Continuar edição").
Campos das camadas (tabela completa do projeto em "Tempo e modelo do projeto" do README):
| Campo | Regra |
|---|---|
| `cuts[].mode` | layout só daquele trecho: um de `MODES` ou `null` (= o do corte) |
| `cuts[].muted` | trecho sem o áudio da live (`volume=0` no trecho; narração e música continuam). `normalize_cuts` só junta trechos encostados com o mesmo `mode` **e** o mesmo `muted` |
| `overlays[].x` (gancho e texto) | posição horizontal 0,05–0,95; ausente = 0,5. `y` 0,04–0,96. No zoom, `x`/`y` (0–1) são o foco |
| `overlays[]` `hook`/`text`: `style`, `bg`, `color`, `font`, `anim` | opcionais. `style` `plain` (padrão) ou `banner` (tarja na largura toda, centrada em `y`, maiúsculas em até 2 linhas; a fonte diminui em vez de cortar palavra); `font` = uma de `fonts`; `anim` ganhou `slide`. Sem esses campos, renderiza idêntico ao de antes |
| `overlays[]` `kind: "inset"` | camada inserida: `start`/`end` (sessão), `src` `{x, y, w, h}` (recorte 0–1 do quadro original), `x`/`y` (centro na saída), `size` 0,1–1 da largura, `border` (`#RRGGBB`/null), `borderW` 0–40 (6), `radius` 0–200 (18), `shadow` (true), `anim` `pop`\|`fade`\|`slide`\|`none`, `keys` opcionais `[{t, x, y, size, ease}]`. Até 12. Ordem do array = empilhamento: acima do vídeo e do zoom, abaixo do ASS (legenda, gancho, textos, chat). **Não entra na capa** |
| `reframe` | `{keys: [{t, cx, cy, w, ease: smooth\|linear\|hold}]}`, até 60, `t` em tempo da sessão, `cx`/`cy`/`w` (0,05–1) absolutos no quadro original; a altura sai da área do jogo do layout do trecho (nunca distorce). Com keys, `layout.game` é ignorado; não vale em `cam_only`; no `blur`, `game_only` e horizontal ocupa a tela toda. A capa usa a janela parada do instante dela |
| `chat` | chat da live na tela: `enabled` (padrão `false`), `x` 0–0,9 (borda esquerda), `y` 0,1–0,98 (base do bloco), `width` 0,25–0,96, `lines` 1–10, `size` 18–64, `showUser`. `chat_events` redesenha o bloco a cada mensagem; ele some 9 s depois da última (`CHAT_HOLD_S`) |
| `cover.atStart` | a capa também cobre os 2 primeiros quadros do MP4 (0 s). Exige `cover.enabled`; `render_clip_edit` gera a capa antes do vídeo e a passa como `cover_file`. `preview-render` também põe a capa quando `fromS` = 0 |
**Editar com a mão** (arrastar e aparar palavra, deslizar e dividir trecho, mover texto/legenda/chat no monitor,
marcar a câmera só daquele corte): tabela "Mexer com a mão" do README; componentes e atalhos em
[panel.md](panel.md#editor-de-cortes).
Limites do editor (lista completa em "Limitações" do README):
- **Uma trilha de vídeo só, sem B-roll.** A timeline é o tempo da sessão: um pedaço não vai para outra camada nem
toca fora da ordem da gravação. Não prometa reordenar trechos.
- A prévia do Programa é um canvas; a exata é `preview-render` (no formato do corte). Legenda e recorte de câmera/jogo
já saem como no render: blocos por `cleanWords`/`groupWords`/`captionBlocks` (porte de `subtitles.py`, constantes em
`CAPTION_TIMING` de `clip-editor-model.ts`) e recorte por `ffmpegCropFill` (arredondamento par do FFmpeg, tamanho da
gravação de `session.capture`). **Mudou constante ou regra em `subtitles.py`, ou a cadeia `layout_chain`, mude o
porte junto.** Tarja a ~2 px do render (informado).
- Reenquadramento no 9:16 com câmera em cima: a área do jogo é 1080×1268 (proporção ~0,85), então um inventário 16:10
não cabe inteiro; a janela mostra no máximo 0,48 da largura. No 16:9 cabe.
- Custo medido (corte 61, 60 s, NVENC): sem nada 6,1–6,2 s; com reenquadramento 7,1–9,5 s; com reenquadramento +
2 camadas 15,8–20,5 s.
- Campo novo (`cam_only`, `muted`, `chat`, `cover.atStart`, texto com `x`, `style`/`font` do gancho, `reframe`, `inset`)
só vale no serviço reiniciado (gotchas, item 73).
Rotas (todas com `X-Service-Key`; todas na regex `ALLOWED`):
| Rota | Faz |
|---|---|
| `GET/PUT/DELETE /v1/clips/{id}/edit` | projeto; PUT manda `rev` e recebe 409 se outro salvou antes |
| `POST …/proxy` `{lo,hi}` · `GET …/waveform?lo=&hi=` | prévia 480p (`-g 15`) e forma de onda (50 picos/s) da janela |
| `POST …/preview-render` `{fromS, durationS ≤ 10, project?}` | prévia real de poucos segundos |
| `POST …/export` | volta para a fila de render → `ready` |
| `POST …/retranscribe` `{startS, endS}` (≤ 90 s) | Whisper de novo no trecho |
| `POST …/tts` `{text, voice, speed}` | narração pelo serviço de voz (4510) |
| `POST …/suggest` | IA (`Judge.ask`) sugere gancho, título, início/fim, trechos mortos e zooms |
Teste local do editor sem tocar no serviço do usuário: instância na faixa 4500–4599 (ex.: 4521) sobre **cópia** do
banco, com as regras do item 77 de [gotchas.md](gotchas.md). Teste de UI no painel do usuário sobre um corte real:
intercepte as escritas (item 86) e ache as camadas do canvas pelo cursor (item 85).
## Perfil do jogo (aba Jogos)
Toda rota abaixo devolve a lista inteira (mesma forma de `GET /v1/games`).
| Rota | Faz |
|---|---|
| `GET /v1/games` | perfis com `status`, `model`, `researchedAt`, `editedAt`, `notes` (`[{text, at, section?}]`) e `profile` |
| `POST /v1/games/{id}/research` | refaz o perfil do zero pela web (`RESEARCH_TIMEOUT_S` 420); os pedidos guardados entram no prompt |
| `PUT /v1/games/{id}` | grava o perfil editado à mão: `name`, `summary`, `genre`, `mechanics`, `clip_worthy`, `avoid`, `jargon`, `news`, `hashtags`, `sources` |
| `POST /v1/games/{id}/refine` | `{instruction, search, section, history}` → `{games, reply}`. `instruction` 3–1500 caracteres; `search` padrão `true` (`false` = sem web, `TIMEOUT_S` 240); `section` `""` \| `summary` \| `clip_worthy` \| `avoid` \| `mechanics` \| `news` \| `jargon` \| `hashtags` \| `sources` (`Literal` em `GameRefineIn` de `main.py`, inválido dá 422); `history` `[{role: "user"\|"ai", text ≤1500}]`, máx. 20. A IA devolve o perfil inteiro + `reply` (1–2 frases do que mudou); guarda o pedido (com `section`) e marca `edited_at` |
| `DELETE /v1/games/{id}/notes/{index}` | esquece um pedido guardado (o perfil atual fica como está) |
- `clean_profile` (`intel.py`) normaliza tudo que entra: apara, tira vazios e duplicados, no máximo 20 itens por lista.
São guardados os últimos 30 pedidos.
- **Pedido guardado sobrevive a "Pesquisar de novo"** (`research_game(name, title, notes)`; `PROFILE_SYSTEM` manda
priorizar os pedidos sobre a pesquisa). **Edição à mão não sobrevive.** Por isso o painel pede confirmação
quando há `editedAt`. Para algo durar, prefira o pedido à IA.
- Refino (`judge.py`): `refine_game(name, profile, instruction, search, section, history)` usa `REFINE_SCHEMA`
(= `PROFILE_SCHEMA` + `reply`) e `PROFILE_SECTIONS` (chave → título). A IA vê só os últimos 8 turnos do
`history`, 400 caracteres cada. `REFINE_SYSTEM` manda mexer só na seção em foco e transformar pedido genérico
em item concreto ("reação do streamer conta" → "Streamer grita, xinga ou ri alto logo depois de uma morte ou fuga").
`Intel.refine(...)` (`intel.py`) devolve `(profile, reply)`.
- Painel (`clipper-games.tsx`): o cabeçalho tem selo de iniciais e os botões "Conversar com a IA" (perfil inteiro),
"Editar" (uma linha por item) e "Pesquisar de novo". Cada seção é um cartão com "Pedir à IA", que abre o chat
daquela seção (`AiChat`: Enter envia, Shift+Enter quebra linha, chave "Confirmar na web" **desligada** por
padrão no painel, embora a API use `search=true` por padrão). Item recém-acrescentado aparece com selo "novo".
"Memória da IA" lista os pedidos guardados (com a seção) e tem X. A conversa só existe enquanto o chat está
aberto. O que fica salvo é o pedido. Tipo `Game` em `panel/src/components/clipper-client.ts`
(`editedAt?`, `notes?[].section?`). Detalhes visuais em [panel.md](panel.md).
## Regras
- **Aprovar publica** nas redes dos canais de publicação ligados à fonte (pelo despachante do painel; aprovar vale
para todas as redes). O painel marca o corte `published` quando todos os jobs dele saíram. Exportar no editor
volta o corte para `pending` e cancela os jobs ainda não enviados (voltam quando o corte fica pronto de novo).
Regras em [publishing.md](publishing.md). Corte aprovado **sem fonte ligada** (ou em outra rede) sai pelo botão
**"Publicar"** do cartão (`clip-publish.tsx`; em `published` vira "Publicar em outra rede"): ver publishing.md.
- **Direitos autorais.** Todo corte leva o crédito do canal. Marque `authorized` nos canais que autorizaram.
- Mudança de código em `clipper/app/` só entra no ar depois de reiniciar o serviço. O `scripts/dev.ts` sobe o
uvicorn sem `--reload` (gotchas, itens 53 e 73). O painel é do usuário, então peça a ele que reinicie — e só com a
suíte verde: reinício no meio de uma edição carrega código intermediário (gotchas, item 87). Agente que edita o
serviço trabalha numa cópia e aplica em `clipper/app/` por **edição pontual**, nunca sobrescrevendo o arquivo
inteiro: vários agentes e outras sessões mexem em `clipper/` ao mesmo tempo.
- Nada de rede (APIs de emotes, CLI) na thread do chat: use `EmoteCatalog.cached()` e baixe em thread à parte
(gotchas, item 72).
- Subprocesso sem shell. A CLI do Codex é chamada pelo `codex.js` (gotchas, item 28).
## Testes e evidência
Os testes não chamam a CLI de IA: `FakeJudge.ask` (`clipper/tests/test_sources_and_api.py`) sempre falha, e o serviço
segue pelo caminho de "IA fora". Juiz falso novo precisa cobrir `ask` também.
Hashtags da legenda (17/11/2026): `pnpm test:clipper` → **278 passed** (reexecutado nesta manutenção; bate com o
informado). Testes novos em `clipper/tests/test_hashtags.py`. O perfil do ROB RUN no banco ainda não tem `hashtags`
(informado; não conferido no banco).
Apagar cortes, veto do rejeitado, varredura contada e prévia igual ao render (17/11/2026):
- `pnpm test:clipper` → **270 passed** (medido na 1.29.1; o coordenador informou 269 — o disco já tinha outro teste
novo; na 1.29.0 eram 268). Testes novos: `test_clip_delete.py` (14); em `test_render_and_duplicates.py`, veto do
rejeitado, contagem da varredura e `test_queue_cleanup_uses_the_same_veto_as_the_judge` (limpeza da fila).
- `npx tsc --noEmit -p panel` → exit 0, sem erro (medido nesta manutenção; o lote informou erros de outra sessão em
`montage-editor.tsx`/`lib/montage*.ts`, já resolvidos quando rodei).
- Banco real `data/clipper/clipper.db` em `user_version` 10 (lido só para leitura nesta manutenção).
- Informado: diagnóstico "não sai corte" da sessão 3 (README, "Armadilhas já resolvidas"; gotchas, item 114);
legenda do painel em 22 conferências contra o Python; teste de ponta a ponta no corte 61 (projeto montado no editor,
capturado do PUT interceptado, render por `editor_render.render_project`) com enquadramento, inserção e legenda
iguais em 2/3,5/5/6,5/8 s; observador só leitura depois da retomada (01:30–01:46): corte 68 pronto e aprovado,
69 e 70 descartados, 71 pronto em 8 s.
Duração mínima, tarja do gancho, fontes, reenquadramento, camadas e qualidade de gravação (17/11/2026):
- `pnpm test:clipper` → **251 passed** (medido nesta manutenção; bate com o informado). Testes novos:
`test_duration_banner_fonts.py` (19), `test_reframe_insets.py` (10), `test_capture_quality.py` (17).
- `npx tsc --noEmit -p panel` → exit 0 (medido nesta manutenção; uma 1ª rodada deu erro em `confirm-dialog.tsx`,
de outro trabalho que ainda estava sendo escrito, e passou depois que ele terminou).
- Informado: medições de render, disco e nitidez acima e no README; prévia da tarja a ≤ ~2 px do render; interpolação
do painel × `reframe.py` em 41 conferências.
Formato horizontal, legenda com fala rápida, retomada, render que falha e duplicados (17/11/2026):
- `pnpm test:clipper` → **170 passed** e `npx tsc --noEmit -p panel` → exit 0, ambos medidos nesta manutenção (o lote
informou 169; o disco já tinha mudanças de outro lote em andamento). Testes novos: `test_format_and_captions.py`,
`test_resume.py`, `test_render_and_duplicates.py`; o vertical bate com o SHA de referência
(`tests/data/vertical_golden_sha256.json`).
- Informado: render horizontal real 1920×1080 conferido no ffprobe; legenda medida numa cópia do banco (3 projetos,
sessão 3 do skipnho): 63 de 286 eventos sobrepostos antes, 0 de 299 depois (README, "Tempo da legenda").
- Informado: capturas por CDP com as escritas interceptadas — modal "Configuração do corte" em 1920×1080 e 1366×768;
aba Sessões sem mudança de posição/altura entre atualizações automáticas.
Redesenho do editor e camadas novas (16/11/2026):
- `pnpm test:clipper` → 136 passed na época e `npx tsc --noEmit -p panel` → exit 0.
`clipper/tests/test_editor_layers.py` (6 testes): projeto antigo ganha os padrões, `cam_only` enche a tela,
`mode`/`muted` sobrevivem sem juntar, texto com `x` e bloco de chat no ASS, capa no início, e um render real pelo
FFmpeg com as camadas novas.
- Informado pelo coordenador, Chrome sem janela por CDP em `/clipper/edit/25` do painel, com as escritas
interceptadas (nada gravado): palavra aparada pela direita 34→21 px e pela esquerda 21→12 px com a outra borda
parada; mover −6 px com a largura igual; clique simples não move; Ctrl+Shift+clique divide (1→2 trechos) e Ctrl+Z
desfaz; marcar a câmera mudou a área de "21% × 24% em 2%, 43%" para "25% × 35% em 5%, 45%"; câmera inteira e chat
na tela aparecem na prévia.
Rastreio de reação (16–17/11/2026):
- `cd clipper; .venv\Scripts\python -m pytest` → 120 passed na época (2 execuções seguidas);
`npx tsc --noEmit -p panel` limpo (informado). Versões instaladas no `clipper/.venv` conferidas (ver tools.md);
os 4 pesos já estão em `data/clipper/models/`.
- `doc/FACE_BAKEOFF.md` (cópia do banco, sessão 3 do skipnho): MediaPipe achou rosto em 97,8–100 % dos quadros dos 6
trechos, 5–7 ms/quadro; bloco de 30 s em 1,47 s de média (p95 2,05 s); 144/144 blocos `done`, rosto em 85,1 % dos quadros;
após calibração 114 picos, 0 no trecho calmo, 0 cortes novos de fonte `face`, 14 dos 21 momentos do chat com
`reasons.face`. **O rosto não separou aprovados de descartados** nos cortes 10–13 — por isso é só reforço.
Rastreio de reação ao vivo (16–17/11/2026; seção "Testes de 17/11 — ao vivo" de `doc/FACE_BAKEOFF.md`):
- `cd clipper; .venv\Scripts\python -m pytest` → 170 passed e `npx tsc --noEmit -p panel` → exit 0 (conferidos
nesta manutenção).
- Download real dos 4 modelos para pasta vazia (0,28–0,91 s cada), sha256 conferido, nenhum `.part`; sha256 errado e
URL 404 → `FaceUnavailable` com `.part` apagado; arquivo corrompido → baixado de novo.
- Plano B OpenSeeFace com pesos reais × MediaPipe (sessão 3, blocos 54/66/80): rosto 96,7–100 % × 94,4–100 %;
12,3–13,9 × 9,8–13,2 ms/quadro (FFmpeg + modelo ÷ 180); `size` do OSF ~18 % menor; OSF dá sinal 0 (sem picos, sem erro).
- Serviço real, instância 4521, twitch.tv/skipnho (sessão 90001, 722 s, 25 blocos, juiz `off`): câmera `yunet` em
12/12 quadros, confiança 0,864; 25/25 `done`, atraso de 0–1 bloco; 1,71 s/bloco (p95 2,20 s) com gravação +
transcrição + chat juntos; fim do bloco → rosto gravado 1,4–9,4 s; CPU média 16,8 % de um núcleo, pico 90 % na
reconstrução após reset; rosto em 99,8 % dos segundos; `GET …/face` 200; `POST …/face/reset` 200 (ocioso) / 202
(bloco em andamento), refez 19 blocos em ~45 s; 2 cortes do chat, um com `reasons.face` grito z 12,7 (o outro,
decidido durante a reconstrução, sem rosto, como desenhado). Queda do `start.bat` no meio → sessão retomada sozinha.
- twitch.tv/lofigirl (sem câmera, sessão 90002): falso positivo achado e corrigido (gotchas, item 92); refeito →
`hasWebcam: false`, 8 blocos `no_cam`.
- Painel em 127.0.0.1:4500/clipper sem erro de console; selo, interruptor e chip de reação vistos só com respostas GET
alteradas no navegador (o serviço do usuário rodava o código antigo).
Editor de cortes, 1ª versão (16/11/2026):
- `pnpm test:clipper` → 120 passed na época.
- Informado pelo coordenador, instância de teste em 127.0.0.1:4521 sobre cópia do banco (sessão 3 do skipnho, já
derrubada e cópia apagada): tempos na tabela "Medido" do README; export do corte 9 editado (início −20 s, 2 trechos
removidos, legenda `pop` com palavra trocada e ênfase, gancho com caixa, zoom 1,5×, barra) = 55,6 s H.264
1080×1920 30 fps + AAC em ~9 s; corte 10 rejulgado pela IA real → projeto da IA → MP4 33,8 s em 24 s; quadros
inspecionados; editor em tela cheia no Chrome sem janela sem rolagem nem erro de console; `pnpm typecheck` e
`npx tsc --noEmit -p panel` limpos.
Chat por seção do perfil (16/11/2026, informado pelo coordenador, IA simulada em banco temporário): `refine`
com `section=clip_worthy` acrescentou o item, devolveu `reply`, recebeu 2 turnos de histórico e salvou a nota com
`section`; seção inválida recusada pelo pydantic; `tsc --noEmit` do painel limpo; `import app.main` ok; captura
de `localhost:4500/clipper?tab=jogos` com o chat aberto em "O que rende corte". **IA real não testada** (serviço
não reiniciado).
Perfil editável do jogo (informado pelo coordenador, banco temporário): migração até `user_version` 7,
`save_profile` deduplicou lista, `refine` guardou o pedido e marcou `edited_at`, a pesquisa recebeu as notas,
`delete_note` limpou; `tsc --noEmit` do painel limpo; `import app.main` ok. O serviço no ar precisa ser reiniciado
para migrar (o banco real estava em v4).
Fase 2 (17/11/2026):
- `pnpm test:clipper` → 46 passed (sem rede, juiz falso); `pnpm typecheck` e `npx tsc --noEmit -p panel` limpos.
Conferido nesta manutenção.
- Informado pelo coordenador, numa cópia do banco da live do skipnho (chat de ~0,15 msg/s):
- jogo ROB RUN pela categoria e perfil pesquisado (~15–35 s por jogo);
- webcam achada no canto inferior esquerdo (~5 s); render `cam_top` de 59 s inspecionado;
- varredura de 2 janelas sem falso positivo (~7 s por janela com `gpt-6-luna`);
- corte do lag: título "O lag jogou ele em três lugares ao mesmo tempo", `lag_ou_bug`, confiança 0,93, início
recuado 35 s, ~18 s nos dois juízes.
Fase 1 (16/11/2026, `twitch.tv/alanzoka`, sessão 2): 21 blocos (617,97 s), 490 mensagens, 4 cortes do chat aprovados
pelo `codex:gpt-6-luna` (notas 7,4–8,5) e 1 manual (nota 3,0) renderizado; `clip-4.mp4` H.264 1080×1920 + AAC.
Não verificado:
- hashtags: juiz e pesquisa de jogo com a CLI real (o campo `hashtags` do veredito e do perfil); UI da seção "Hashtags"
contra o serviço reiniciado;
- apagar: rota no serviço real do usuário; arquivo em uso no Windows (deve voltar em `left`); pedido do editor em
andamento gravando em `edit-<id>/` depois de apagar; relógio da sessão com movimento reduzido, aba escondida e
larguras de 1024/1280; a faixa do topo em `clipper-studio.tsx` ainda mostra o `durationS` real (sem o relógio);
- duração, gancho, reenquadramento, camadas e captura: live 2K real e HEVC real da Twitch pela captura; gravação longa
em 1080p ou 2K com o serviço real; juiz e varredura reais com as durações novas; render real de um projeto feito no
editor com reenquadramento e camadas comparado com a prévia (pendente, depois do reinício do serviço); camadas na
capa (não entram por desenho);
- formato e retomada: juízes, varredura e "IA sugere" com a CLI real depois da mudança de prompts; retomada automática
contra live real; horizontal com NVENC e com fonte que não é 16:9; corte horizontal de ponta a ponta numa live;
gravação real do `format` pelo modal (as escritas foram interceptadas);
- editor: música e efeitos com arquivo real (não há áudio em `assets/`; só o filtergraph em teste unitário);
arrastes com mouse humano (só por CDP, e nem todos: deslizar o corpo do clipe, arrastar texto/zoom/narração na
timeline, mover texto/gancho/legenda/chat no Programa, "Editar"/"Ocultar" da transcrição, "Salvar projeto" e
minimizar painéis não têm medição registrada); export real pelo serviço do usuário (4520) de um projeto com
`cam_only`, `muted`, `chat` ou `cover.atStart` — as escritas do teste de UI foram interceptadas, e o serviço
precisa ser reiniciado para o código novo e a migração v7 (gotchas, item 73);
- rastreio de reação: câmera em tela cheia, escura ou minúscula; GPU; live > 15 min (`LIVE_WINDOW_S` 900 s não foi
ultrapassada); a linha "Rosto do streamer" chegando ao juiz analista ao vivo (juiz `off` no teste); interação real
com o interruptor `faceTrack` contra o serviço novo (só com respostas simuladas no navegador); câmera que muda de
lugar no meio da live. O serviço do usuário só pega a correção do `min_cam_score` depois de reiniciar o `start.bat`;
- editar/refinar perfil pela UI contra o serviço reiniciado; `refine` com IA real (com e sem `search`);
- a UI nova (modal do corte, aba Jogos e emotes) contra o serviço novo no ar — o serviço do usuário ainda roda o
código antigo;
- juiz com a CLI do Claude (analista, editor, varredura, câmera e pesquisa);
- chat da Kick e lives do YouTube ponta a ponta; VOD; render com NVENC.
@@ -0,0 +1,701 @@
# Armadilhas conhecidas
Cada item: **sintoma → causa → correção → onde está tratado**. Observadas na implementação da
prova de conceito com Godot 4.7.2 / FFmpeg 7.1.1 / pnpm 11.22 (16/11/2026). Registro formal em
`doc/TEST_RESULT.md`: itens 1–5, 7, 13–15, 17 e 18; itens 30–33 estão em `voice/README.md`
("GPU e CPU"); itens 57–61 estão em `clipper/README.md` ("Armadilhas já resolvidas"); itens 74–76, 87–90 e 103–108 também estão lá e o 78 na seção "Limitações" do editor; itens 79, 81–84 e 92–95 estão em `doc/FACE_BAKEOFF.md` (o 93 também em "Variáveis" de `clipper/README.md`) (o 80, no comentário de `clipper/requirements.txt`); itens 118–128 (publicação) seguem `doc/publicacao/` e o código; itens 129–132 foram informados em 17/11/2026 e conferidos no código (`doc_main.gd`, `doc/godot/cenas.md`) e no banco (`agent_runs` 5, 7 e 8); itens 62–67, 77, 85–86, 91, 99–102, 109–112 e as ampliações do 52, do 44, 77, 86 e 87 foram informados em 16–17/11/2026 (não estão em `doc/TEST_RESULT.md`); os demais vieram de erros de compilação ou instalação durante a implementação.
Ao descobrir uma nova, registre aqui via `cenaforge-skill-updater`. Os números são estáveis
(outros textos os citam): item novo entra na seção do assunto com o próximo número livre.
## Render (Godot Movie Maker)
1. **Primeiro quadro diferente** (azulado, sombra diagonal errada).
Causa: sombras e radiância do céu ainda não prontas no 1º quadro.
Correção: 3 quadros de aquecimento em t = 0, descartados com `-start_number 3`.
Onde: `--warmup-frames` em `main.gd`; `render.ts` passa `-start_number`.
2. **`delta` não é 1/fps** mesmo com `--fixed-fps` (0,025; 0,0333; 0,0417…).
Correção: tempo da cena = contador de quadros / fps. Nunca use `delta` em render.
Onde: `_process_render` em `main.gd`.
3. **Resolução do filme travada na inicialização.** `--resolution` e `content_scale_size` em
runtime não mudam o arquivo; janela de 1080×1920 não cabe numa tela de 1080 px.
Correção: `godot/override.cfg` temporário com o viewport do perfil e janela menor
(stretch `viewport`, aspect `keep`). A cena aborta (código 3) se o viewport ≠ config.
Onde: `render.ts` escreve/remove o arquivo; checagem em `main.gd`.
Consequência: render manual sem o lançador só sai em 540×960.
4. **`--write-movie` relativo grava em `godot/`, e falha em silêncio.** Com a pasta
inexistente, nenhum PNG é gravado e a Godot sai com código 0 dizendo "Done recording".
Correção: caminho absoluto; o lançador confere os PNGs; `main.gd` aborta se a pasta não existe.
Lição: log de sucesso não prova nada — confira arquivos.
5. **Quantidade de quadros.** Chamar `quit()` no `_process` do último quadro ainda grava esse
quadro: total de PNGs = aquecimento + fps × duração, índices contínuos a partir de 0,
padrão `frame%08d.png`, mais `frame.wav` (silencioso, descartado).
6. **Modo `--headless` não renderiza 3D válido.** Use só para validação, testes e preparação
de assets. O render abre uma janela e precisa de backend gráfico.
7. **Custo do render é a codificação PNG** (~105 ms/quadro em 540×960, ~404 ms em 1080×1920),
não a GPU. Não prometa tempo sem medir.
110. **Cena do documentário (`doc2d`/`doc3d`) reprovada como "quadro preto" ou "moto não termina no ponto".** Causa: as
checagens do lançador eram da rua — o fundo escuro do documentário (#0d0d10) tem luma ≈ 13, abaixo do piso 20
(`MIN_AVERAGE_LUMA`), e não há moto. Correção: com `kind` `doc2d` ou `doc3d`, `render.ts` pula a checagem da moto e usa
`MIN_AVERAGE_LUMA_DOC2D` = 4. Fundo novo mais escuro que isso → ajuste o piso, não desligue a checagem.
129. **Render de cena `doc3d` não termina e enche a pasta de PNGs** (17/11/2026: 39 mil quadros, "apply em Nil" em laço).
Causa: `template.gd` com erro de compilação; o protocolo seguia sem a cena. Correção: `doc_main.gd` carrega o script
na validação e, se `can_instantiate()` falha, sai com `SCENE_SCRIPT_INVALID` (código 2, `EXIT_INVALID_CONFIG`); os
`Parse Error` com a linha ficam no `render.log` do run. No render, cena sem `setup`/`apply` também sai com
`SCENE_SCRIPT_INVALID`. Se um render antigo travar assim: encerre a Godot **e** o lançador e apague
`output/.render.lock`. Erros de GDScript mais comuns: itens 9 e 130.
## GDScript (Godot 4.7) e TypeScript do lançador
8. **`class_name` depende do cache do editor.** O projeto roda sem importação prévia; use
`const X := preload(...)`.
9. **`var x := dicionario.campo + 1.0`** não compila (tipo não inferível a partir de Variant). Idem
`var x := dict.get("k")`, `var p := nodes[i]` e retorno de método de kit chamado por variável tipada como `Node3D`.
Declare o tipo (`var x: float = ...`) ou use `=`.
10. **Comparar valor não-objeto com `null`**: prefira `typeof(v) == TYPE_NIL`.
11. **`quit()` é adiado para o fim do quadro**: depois de chamar, marque um sinalizador
(`_halted`) para o `_process` seguinte não rodar com estado incompleto.
12. **Dentro de comentário de bloco TypeScript, `*/`** (ex.: `godot-*/`) encerra o comentário.
130. **"shadows a native class"**: constante com nome de classe do Godot (`const Sky := preload(...)`, `Camera3D`,
`Environment`) não compila. Use outro nome (`SkyRig` em `godot/library/castaways/template.gd`). Guia: "Testar" em
`doc/godot/cenas.md`.
## Composição visual
13. Título longo quebra linha: o rótulo cresce para cima (alinhado embaixo) para não invadir as
opções. Reserve ~18% inferior livre para a interface da plataforma.
14. No fim do plano, câmera baixa (~1,1 m) com leve inclinação para baixo põe o entregador na
metade superior e mantém o horizonte; câmera alta deixa o texto cobrindo o personagem.
15. Borda do plano do morro vira linha reta no céu: a cumeeira de volumes irregulares resolve.
16. Câmera lateral perto dos postes (x = meia pista + 0,5 m): mantenha ≥ 1 m de folga no offset.
17. Rodas: a ~4 m/s giram ~26°/quadro; acima de 30°/quadro a simetria de 60° dos raios pode
causar efeito estroboscópico.
111. **Espuma do mar desenhada por elipse não acompanha a costa** (anel regular em volta de uma ilha irregular).
Causa: a elipse no shader do mar ignora o contorno real do terreno. Correção: removida; a cor turquesa perto da
costa já marca a transição. Espuma futura precisa seguir a altura do terreno, não uma forma fixa. Onde:
`_build_ocean` em `godot/library/island/template.gd`.
## Ferramentas
18. **`pnpm doctor`** é comando nativo do pnpm 11 → use `pnpm run doctor`.
19. **pnpm 11 bloqueia scripts de instalação** não aprovados (erro `ERR_PNPM_IGNORED_BUILDS`).
O `esbuild` está recusado em `pnpm-workspace.yaml` (`allowBuilds: esbuild: false`) e funciona assim.
20. **pnpm repassa o `--`** para o script; o parser do lançador ignora um `--` solto.
21. Executável principal da Godot (não o `_console.exe`) escreve stdout em pipe normalmente;
use-o para poder encerrar a árvore com `taskkill /T`.
44. **Heredoc ou `node -e "..."` no Bash do agente quebra com barra invertida e aspas** (`\\` vira `\`; escapes como
`\b` de regex se perdem; às vezes o script inteiro falha). Em 17/11/2026 um `node -e` com regex quebrou o build do
painel duas vezes. Texto com barra invertida (caminhos Windows, `package.json`, regex) ou
script com aspas aninhadas: edite com Edit/Write, ou grave o script num arquivo (scratchpad) com
Write e execute o arquivo, nunca inline.
## Painel
22. **Portas:** o CenaForge usa a faixa **4500–4599** (painel = 4500). A 3100 já é de outro
aplicativo nesta máquina. `EADDRINUSE` = porta ocupada: escolha outra da faixa, nunca
encerre o processo alheio.
23. **Node não executa `.cmd`/`.bat` sem shell** (ex.: `pnpm.cmd`). O painel chama o lançador
como `node node_modules/tsx/dist/cli.mjs scripts/cli.ts render …` e procura só `.exe`.
24. **Next.js 16.4** vem com `cacheComponents` ligado; o painel desliga (dados sempre dinâmicos)
e chama `connection()` antes de ler o SQLite. `params` de página/rota é `Promise`.
25. **Script `.ts` dentro de `panel/`** roda como CommonJS (sem `"type": "module"`): para
`await` no topo, use `.mts`.
26. **`claude -p` reclama de stdin** se a entrada não for fechada: o painel usa `stdio: ["ignore", …]`.
27. **Codex fora de repositório Git** recusa rodar sem `--skip-git-repo-check`. `codex exec resume`
não aceita `--sandbox` nem `-C`: use `-c sandbox_mode="workspace-write"` e o cwd do processo.
28. **Shims do npm no Windows** (`codex`, `codex.cmd`, `codex.ps1`): o sem extensão é script de
shell e o `.cmd` exige shell. O painel (`agents.ts`) e o juiz do Clipador (`clipper/app/judge.py`)
executam `node <pacote>/bin/codex.js`.
29. **Ruído das CLIs no stderr.** Codex: configuração pessoal do usuário (`~/.codex/config.toml`,
servidor MCP fora do ar) e "Codex is ignoring N unrecognized configuration setting"; Claude Code:
`[claude-code:unrecognized_model]` para id fora da lista interna dele (ex.: `claude-fable-5-2`), mas
o modelo roda normalmente. O painel filtra esses padrões (`STDERR_NOISE` em `panel/src/lib/agents.ts`);
os avisos de configuração do Codex chegam como item `error`, exibidos como nota.
42. **Ícone some no menu recolhido:** SVG dentro de flex encolhe a 0 px ao lado de texto
`nowrap`. Correção: `shrink-0` nos ícones (`panel/src/components/icons.tsx`).
43. **Grade na barra lateral cresce até a largura do texto.** Correção: `flex-col` + `min-w-0`
(`panel/src/components/sidebar-nav.tsx`).
48. **Nó do `@xyflow/react` 13 não responde a clique** sem `onNodeClick` no canvas.
Correção: o clique sobe até o nó e é tratado no `onNodeClick` (`components/story-flow.tsx`).
49. **Foco dentro do canvas rola o contêiner** e desalinha a árvore. Correção: `onScrollCapture`
desfaz a rolagem e `setCenter` traz o nó focado para a vista (`story-flow.tsx`).
50. **Grade sem `grid-cols-1` estoura no celular** (colunas implícitas crescem até o conteúdo).
Correção: declarar `grid-cols-1` na base e as colunas extras só nos breakpoints.
51. **Mudança de esquema não aparece no painel em dev** (ex.: v4 → criar história documental falha no
CHECK de `stories.kind`). Causa: a conexão do SQLite fica em `globalThis.__cenaforgeDb`
(`panel/src/lib/db.ts`) e a migração só rodava ao abrir o banco. Hoje a marca `checkedThisModule` faz a 1ª
chamada de `db()` depois da recarga do código migrar o banco aberto (item 138); se o `db.ts` não foi recarregado,
faça uma requisição ao painel ou peça ao usuário que reinicie o `pnpm panel` (é dele: não reinicie você). Conferir:
`PRAGMA user_version` do `data/cenaforge.db` = `MIGRATIONS.length`.
52. **`tsx` com `await` no topo** exige arquivo `.mts`, e o import de módulo local precisa de URL
`file:///` (caminho Windows cru com `C:\` ou `f:/` não é URL e falha no loader ESM). Node puro não resolve
import `.ts` sem extensão: rode pelo tsx da raiz, `node node_modules/tsx/dist/cli.mjs <script>.mts`, com
imports `file:///<raiz-do-repo>/panel/src/lib/<módulo>.ts`. Complementa o item 25.
62. **Classe de largura não pega em `Select`/`Input`** do `panel/src/components/ui.tsx`.
Causa: a classe base tem `w-full` fixo e `cx()` só concatena (não faz merge de Tailwind como o
`tailwind-merge`); `w-48` passado junto perde para o `w-full`. Correção: controlar a largura com
um `<div>` em volta (ex.: barra de filtros de `voice-cards.tsx`).
63. **Patch por string falha nos `.tsx` do painel**: os arquivos são CRLF. Correção: normalizar o
fim de linha antes de procurar o trecho (ou usar a ferramenta Edit) e gravar de volta em CRLF.
96. **Codex aplica as restrições de ficção a um pedido documental.** Causa: o Codex lia
`.claude/agents/cenaforge-story-writer.md` como instrução, mas é um subagente do Claude. Correção: as
regras saíram do subagente para `doc/roteiro/` (`comum.md` + `ficcao.md`/`documental.md`); o prompt
(`writingRules(provider, kind)` em `panel/src/lib/prompts.ts`) manda o Codex ler só o guia do formato e
escrever sozinho, e o `AGENTS.md` da raiz tem a mesma regra. Regra nova de texto vai para os .md, não
para o subagente nem para o código.
97. **Codex retomado depois de interrompido esquece o pedido original.** Medido com o Codex 0.169 (`exec` +
`taskkill /T /F` + `exec resume <thread>`): matando logo no `thread.started`, a sessão retomada não tinha o
pedido (respondeu "Nenhuma"); matando depois de um `agent_message`, lembrou (respondeu "BANANA"). O 1º
`item.completed` pode ser um item `error` de MCP pessoal, que não conta como progresso. Correção:
"Corrigir agora" (`sendFollowUp` em `panel/src/lib/agents.ts`) exige `session_id` e `progressed` (algum
evento que não seja `system`, `stderr` nem `error`); antes disso, recusa e sugere "Enviar ao terminar".
98. **Acentos quebrados no Codex** ("história" no console). Causa: o Windows PowerShell 5.1 lê arquivo UTF-8
sem BOM como ANSI. Correção: o prompt do Codex (`panel/src/lib/prompts.ts`) manda ler texto com
`Get-Content -Raw -Encoding UTF8`. Mesma raiz do item 36 (script `.ps1` precisa de BOM).
99. **Script de teste marca como `interrupted` o que o painel está rodando.** Causa: importar `lib/db.ts` (direto
ou por outro módulo do painel) abre o banco, e a abertura roda `UPDATE renders/agent_runs SET status =
'interrupted' WHERE status = 'running'`. Correção: script fora do painel não importa nada que toque o banco;
por isso o FFmpeg da montagem documental fica em `panel/src/lib/montage-ffmpeg.ts`, sem banco.
100. **Parâmetro extra some da URL de arquivo.** Causa: `fileUrl()` (`panel/src/components/ui.tsx`) já devolve
`/api/files?path=...`. Correção: anexar com `&v=...` (ex.: quebra de cache do áudio em `montage-editor.tsx`).
101. **Asterisco no vídeo documental** (`*Bothrops insularis*`). Causa: o "texto na tela" do roteiro vem com
markdown. Correção: `loadMontage` (`panel/src/lib/montage.ts`) tira `**`, `__`, `*`, `_`, crase e aspas externas.
102. **Trecho do MP4 mais longo que a tabela do roteiro** (trecho 1: roteiro 0–2 s, fala 4,08 s). Não é erro: a
montagem segue a duração real de cada fala (+ pausa), não a coluna "t (s)". Para encurtar, corte o texto falado.
112. **Primeira montagem logo depois de editar `panel/src/lib/` sai com o comportamento antigo** (17/11/2026: a 1ª saiu
sem o fundo desfocado da foto; a 2ª, certa). Causa provável (não isolada): o Next dev ainda executa o módulo antigo
logo após a edição. Correção: confira os quadros da primeira saída depois de mexer no servidor; se vier com o
comportamento antigo, gere de novo antes de concluir.
109. **Ctrl+Z do editor de cortes não desfaz slider, arraste nem setas** (só em dev). Causa: o React em modo estrito roda
o updater do `setState` duas vezes; a chave/hora de agrupamento ficava num ref alterado dentro do updater, e a 2ª
execução "agrupava consigo mesma". Correção: o updater é **puro** — chave e hora moram no próprio estado. Regra
para todo `setState((s) => …)` do painel: nada de ref, relógio ou efeito lá dentro (leia `Date.now()` antes). Onde:
`useHistory` em `panel/src/components/clip-editor-model.ts`.
131. **Agente do painel morre ao reiniciar o `pnpm panel`** (execução #5, cena do estádio, ficou `interrupted`). Causa: o
agente é processo filho do painel, e a abertura do banco marca `running` como `interrupted` (item 99). Correção: não
reinicie o painel com agente rodando; se precisar (ex.: migração, item 51), espere terminar. O painel é do usuário.
132. **Agente para no meio por limite de uso** (17/11/2026: Claude na #7, "You've hit your 5-hour limit", e Codex na #8,
"You've hit your usage limit"; as duas ficaram `error`). A mensagem aparece no console (`data/logs/agents/<id>.jsonl`);
na #7 a coluna `agent_runs.error` ficou só "success". Correção: abra nova execução no **outro provedor** com o
contexto de onde parou (arquivos já feitos, o que falta); a #8 (Codex) continuou a cena `castaways` da #7 (Claude).
133. **Claude do painel falha com "Failed to authenticate: OAuth session expired".** Causa: o painel lança o `claude` sem
`CLAUDE_CONFIG_DIR`, ou seja com `~/.claude`, e o OAuth dessa config estava expirado (17/11/2026), mesmo com outra
conta ativa no terminal. Correção: rode `claude` e `/login` nessa config, ou suba o `pnpm panel` com
`CLAUDE_CONFIG_DIR` da conta ativa (o painel é do usuário, item 131). Onde: `panel/src/lib/agents.ts`.
134. **Execução do agente custa milhões de tokens / dura dezenas de minutos.** Causas medidas: (a) Codex abrindo ~100
imagens em resolução cheia (#8: 6,83 milhões de tokens de entrada, 29 min); (b) página web inteira na pesquisa
(#6: 1,06 milhão); (c) custo fixo de plugins/MCP/skills do usuário carregados pela CLI (#7: ~49 mil por chamada);
(d) retomar conversa longa. Correção: `frame_check.py` + uma imagem por render, pesquisa curta, flags enxutas
do painel, nova execução em vez de resume. Detalhes em [token-economy.md](token-economy.md).
135. **`-c mcp_servers={}` não desliga os MCPs do Codex, e `collaboration` (`spawn_agent` etc., ~5,4 mil caracteres) não
sai por `-c features.*`.** Causa: o Codex mescla tabelas do `-c` com o `config.toml`. Correção: um
`-c mcp_servers.<nome>.enabled=false` por servidor (lidos do `config.toml`) e `plugins."<id>".enabled=false` para
computer-use. A `collaboration` fica; é parte do fixo. Onde: `codexLeanOverrides` em `panel/src/lib/agents.ts`.
## Serviço de voz (`voice/`)
Medidas em 16/11/2026, RTX 2060 SUPER 8 GB, Windows 11.
30. **Whisper na GPU só falha na 1ª inferência** com `RuntimeError: Library cublas64_12.dll is
not found`: o `ctranslate2` enxerga a GPU mesmo sem cuBLAS/cuDNN.
Correção: aquecimento real na subida (`FasterWhisperEngine.warmup()`, 1 s de tom **sem VAD** —
com VAD o silêncio não chega ao modelo e a falha passa) e queda para CPU `int8` com aviso no log.
Onde: `voice/app/stt.py` (`warmup`), `voice/app/main.py`; DLLs em `voice/requirements-cuda.txt`.
31. **GPU disputada por jogo** (98% de uso, 7,4/8 GB): 6,5 s de fala levaram 41–124 s na GPU
contra 2,7 s na CPU; noutra medição (99%, 7,2 GB) a legenda de 6,5 s ficou > 8 min presa na GPU.
Correção: `VOICE_DEVICE=auto` consulta o `nvidia-smi` na subida e usa CPU com < 2048 MiB livres
ou ≥ 85% de uso (log: `GPU ocupada por outro programa (99% de uso, 1593 MiB livres)`); depois
do reinício a mesma legenda pelo painel levou 2,5 s (14 palavras + `.srt`). Só vale na subida:
jogo aberto depois → reinicie o serviço ou use `VOICE_DEVICE=cpu`. Onde: `voice/app/device.py`.
32. **Edge TTS 403** (`WSServerHandshakeError` de `speech.platform.bing.com`) desde out/2026 com
`edge-tts` 7.2.8. Correção: `edge-tts==7.3.1` em `voice/requirements.txt`, sem patch.
33. **sha256 do Piper divergente:** o lock apontava para `resolve/main` e o arquivo mudou no
Hugging Face. Correção: URL fixada no commit `e9ab671f2a0e50a701b34361136ba3e6a3a9eb0c` em
`voice/models.lock.json`. Regra: todo peso novo com URL imutável (commit no HF ou release
versionado no GitHub) e sha256.
34. **LRU do cache empatava no Windows** (`time.time_ns()` anda em passos de ~1 ms).
Correção: `Store._tick()` estritamente crescente em `voice/app/store.py`.
35. **Caminho Windows em script do `package.json`:** o `cmd` não aceita `voice/.venv/...` como
executável; use barra invertida, escrita `\\` no JSON (ver `test:voice`:
`cd voice && .venv\\Scripts\\python -m pytest`).
36. **`scripts/setup.ps1` precisa ser UTF-8 com BOM**: o PowerShell 5.1 lê sem BOM como ANSI e
estraga os acentos. Mantenha o BOM ao editar.
37. **GPU detectada como "sem GPU"** (RTX 2060 SUPER → torch `+cpu`).
Causa: `nvidia-smi ... | Select-Object -First 1` corta o pipeline, o PowerShell mata o
processo e `$LASTEXITCODE` ≠ 0.
Correção: capturar a saída inteira com `@(nvidia-smi ...)` e usar `[0]`. Onde: `scripts/setup.ps1`.
38. **`uv pip install torch==2.11.0` aceita a variante errada já instalada** (`2.11.0+cpu`
satisfaz). Correção: pedir `torch==2.11.0+cu128` (ou `+cpu`) explicitamente. Evidência: na
2ª rodada o uv trocou `- torch==2.11.0+cpu` por `+ torch==2.11.0+cu128`. Onde: `scripts/setup.ps1`.
39. **stderr do uv vira `NativeCommandError`** com `$ErrorActionPreference = "Stop"` no
PowerShell 5.1. Correção: `"Continue"` e conferir `$LASTEXITCODE` em `Run()`. Onde:
`scripts/setup.ps1`.
40. **Serviço órfão segurando a 4510** (`WinError 10048`) após reinício pelo `voice/.env`.
Causa: o `exit` do processo antigo chega depois de o novo subir; um sinalizador global
`restarting` fazia o lançador sair no `--voice-only` e largar o novo processo.
Correção: `WeakSet` dos processos substituídos + `process.on("exit", stopAll)`; checagem de
porta livre antes de subir. Onde: `scripts/dev.ts`.
41. **`.pth` que não é RVC** derruba o Applio com `KeyError: 'config'`.
Correção: vira `422 rvc_failed` com mensagem clara. Onde: `voice/app/rvc.py`, `voice/app/errors.py`.
45. **Edge TTS `NoAudioReceived` intermitente** (visto com `en-US-AndrewMultilingualNeural`, 1ª
tentativa). O serviço não repete: vira `502 engine_unavailable` (`EdgeEngine` em
`voice/app/engine.py`). Correção: repetir a requisição (a 2ª deu certo).
46. **Acentos estragados ao testar o Piper na linha de comando no Windows**
(`echo ... | python -m piper`: "até" vira lixo). Causa: stdin/stdout fora de UTF-8. Correção:
`PYTHONUTF8=1` ou `PYTHONIOENCODING=utf-8` no teste manual. O serviço não é afetado.
47. **`faster_whisper.decode_audio(caminho)` falha** com o PyAV do `voice/.venv`
(`open() got an unexpected keyword argument 'metadata_errors'`). Só em teste avulso: decodifique
com ffmpeg para PCM 16 kHz mono e passe o array numpy. O serviço não é afetado: decodifica os
bytes com o próprio `voice/app/decode.py` (`av.open` em memória).
53. **Mudança de código em `voice/app/` não entra no ar** com `pnpm dev`/`pnpm voice`.
Causa: `scripts/dev.ts` sobe o uvicorn sem `--reload`; só reinicia sozinho quando
`voice/.env` muda. Correção: reiniciar o serviço (o painel é do usuário: peça). Mudança de
catálogo (`catalog.json`, `models.lock.json`, `user-voices.json`) não precisa: é relida na
próxima consulta de vozes ou síntese.
Exceção: voz de **motor novo** (ex.: `kokoro`, `google`, `azure`, `clone` em 16/11/2026) com o serviço ainda no
código antigo → a recarga falha (`motor desconhecido`), as vozes atuais ficam e o log avisa;
só aparece depois de reiniciar (`start.bat` / `pnpm dev`). O worker de clonagem também só
reinicia sozinho quando `voice/.env` muda.
54. **`kokoro-v1.0.int8.onnx` não roda no onnxruntime 1.31.0** (`NOT_IMPLEMENTED` em
`ConvInteger(10)`). Correção: usar `kokoro/kokoro-v1.0.fp16.onnx` (é o que está no
`voice/models.lock.json`).
55. **Kokoro fp16 inunda o log com centenas de avisos "constant folding"** do onnxruntime ao criar
a sessão. Correção: `SessionOptions.log_severity_level = 3` (e threads limitadas) em
`KokoroEngine`, `voice/app/engine.py`. Não é erro; ignore se aparecer em teste avulso.
56. **Recarga do catálogo lenta com muitas vozes Kokoro** (todas apontam para o mesmo onnx de
~160 MB e o sha256 era recalculado por voz). Correção: cache de `sha256_file` por
(caminho, mtime, tamanho) em `voice/app/catalog.py` — 62 vozes: 0,3 s → 0,01 s (informado).
64. **Download dos pesos do Chatterbox trava** (~3,3 GB de `ResembleAI/chatterbox` para
`data/voice/models/clone-hf/`): o protocolo Xet do Hugging Face baixou 256 MB em 9 min.
Correção: `HF_HUB_DISABLE_XET=1` (com ele baixou tudo); o worker já define isso e
`HF_HUB_DISABLE_SYMLINKS_WARNING=1`. Onde: `voice/clone/worker.py`. Atenção: a revisão é `main`,
**não fixada em commit** nem conferida por sha256 (foge da regra do `models.lock.json`).
65. **Chatterbox não cabe no `voice/.venv`**: fixa `numpy<2`, torch 2.6 e transformers 5.2.0.
Correção: venv próprio `voice/.venv-clone` (Python 3.12, torch/torchaudio 2.6.0+cu124) e worker
HTTP separado na 4511, chamado pelo `CloneEngine`. Nunca instale `chatterbox-tts` no
`voice/.venv`. Onde: `scripts/setup.ps1` (`-Clone`), `voice/clone/requirements.txt`.
66. **Fala clonada longa estoura o tempo**: ~1,5 s de processamento por s de áudio na GPU (RTX 2060
SUPER) pode passar de `VOICE_SYNTH_TIMEOUT_S=90`. Correção: sintetizar textos longos em partes
(o worker já divide em trechos ≤ 280 caracteres, mas o tempo total da requisição conta). A 1ª
fala inclui o condicionamento da referência (6,0 s de áudio em 20,5 s; a 2ª, 7,1 s em 10,5 s).
67. **`speed` não muda a voz clonada** e todo áudio sai com marca d'água inaudível PerTh. Não é
defeito: o Chatterbox não tem controle de velocidade. Para outro ritmo, use outro motor.
## Clipador (`clipper/`)
Itens 57–61 observados em 16/11/2026 na live real (`twitch.tv/alanzoka`) e nos testes. Contexto em
[clipper.md](clipper.md).
57. **Legenda some ou sai deslocada no corte.** Causa: com `-ss` depois do `-i`, o filtro `ass` vê
o tempo do bloco, não o do corte. Correção: `-ss` **antes** do `-i`. Onde: `clipper/app/editor_render.py`
(render atual) e `clipper/app/media.py` (caminho antigo).
58. **Tag ASS inválida na legenda palavra a palavra.** Causa: `.upper()` na linha ASS inteira transformava a
tag `\c` em `\C`, que é inválida. Correção: maiúsculas só no texto da palavra. Onde:
`clipper/app/subtitles.py` (`build_ass`).
59. **Falsos positivos com o chat calmo.** Causa: o emote `clip5k1hmm` casava com `\bclip`, e 3
mensagens já davam razão 2,35. Além disso, o começo da gravação não tinha base de comparação.
Correção: "clip" só como palavra inteira, mínimo de mensagens nos 8 s do pico (hoje proporcional,
item 68) e 60 s de aquecimento. Onde: `clipper/app/scoring.py` (`Params`, `warmup_s`); há teste
de regressão em `clipper/tests/test_scoring.py`.
60. **Ao vivo, a explosão do chat era cortada cedo.** Causa: um pico menor do começo da explosão
fechava antes do pico maior, que ainda estava crescendo. Correção: o pico é escolhido olhando a
série inteira e só depois é filtrado pelo "assentado" (`limit_s`). Onde: `pick_peaks` em
`clipper/app/scoring.py`.
61. **Chat e vídeo desalinhados na Twitch.** Causa: o Streamlink pausa durante o anúncio filtrado.
Correção: o tempo da mensagem é convertido pela hora real em que cada bloco chegou (`wall_end`
da tabela `segments`), não pelo relógio desde o início. Onde: `clipper/app/worker.py`.
Observadas em 17/11/2026 (fase 2) numa cópia do banco da live do skipnho e nos testes:
68. **Live de chat pequeno nunca gerava corte.** Causa: com ~0,15 msg/s, o mínimo fixo de 12 mensagens
nos 8 s do pico era inalcançável. Correção: mínimo = 3× a mediana recente, entre 4 e 12, exigindo
≥ 2 reações (texto ou emote); com chat < 0,5 msg/s o áudio também propõe momentos; e a varredura da
IA cobre o resto. Onde: `_required_messages`, `_chat_moments`, `_audio_moments` em
`clipper/app/scoring.py`; varredura em `clipper/app/intel.py`.
69. **Título preso à frase solta da transcrição** ("Jogando três jogos ao mesmo tempo" num momento de
lag). Causa: um único juiz só com texto. Correção: ANALISTA com 6 frames (8 se o trecho passa de 80 s) + glossário de gírias do
chat (`CHAT_GLOSSARY`: "server chinês" = lag) e EDITOR que escreve a partir da análise. Onde:
`clipper/app/judge.py`; frames montados em `clipper/app/worker.py`.
70. **Crédito em cima do rosto no `cam_top`.** Causa: crédito no topo fica sobre a webcam. Correção:
no `cam_top` o crédito do topo desce para o pé do painel da câmera (`cam_panel_height`). Onde:
`clipper/app/subtitles.py`.
71. **Cor errada na legenda ASS.** Causa: formatos diferentes — a linha `Style` usa `&H00BBGGRR&` (com
alfa) e a tag `\c` inline usa `&HBBGGRR&` (sem alfa); ambos em BGR, não RGB. Correção: sempre
converter por `ass_color` (Style) ou `ass_inline_color` (tag). Onde: `clipper/app/layout.py`.
72. **Chat travando ao baixar emotes.** Causa: APIs de 7TV/BTTV/FFZ podem demorar (FFZ) ou dar 404
(7TV em canal sem 7TV). Correção: a thread do chat só lê `EmoteCatalog.cached()`; o download
(`names()`, cache de 1 h, fonte com falha ignorada) roda em thread à parte ao chegar o `room-id`.
Onde: `ingest_chat` em `clipper/app/intel.py`, `clipper/app/emotes.py`.
73. **Código novo do Clipador "não funciona" no painel.** Causa: o uvicorn sobe sem `--reload`; a UI
nova (o Next em dev recarrega sozinho) chama rotas ou manda campos que o serviço antigo não conhece — ex.: um
serviço anterior ao `cam_only` recusa o projeto do editor que usa esse modo (`validate_project` → 400).
Correção: reiniciar o Clipador (`start.bat` / `pnpm dev`, que é do usuário — peça a ele; ele pode estar
gravando). Mesmo padrão do item 53.
Observadas em 16/11/2026 no editor de cortes, numa cópia do banco (sessão 3 do skipnho) e nos testes:
74. **Projeto do editor recusado com 400.** Causa: o Whisper devolve palavra com duração zero (ex.: "queria"
1020,10–1020,10). Correção: palavra com fim ≤ início ganha 50 ms. Onde: `clipper/app/editor.py`
(leitura das palavras e `validate_project`).
75. **Capa sai vazia.** Causa: o mjpeg do FFmpeg 7.1 recusa yuv420p marcado como faixa "tv" (blocos do libx264).
Correção: o quadro intermediário da capa é PNG. Em teste, bloco sintético precisa de `-g` curto; senão o `-ss`
não acha quadro e o grab sai vazio. Onde: capa em `clipper/app/editor_render.py`; `clipper/tests/test_editor.py`.
76. **Gancho vira frase longa cortada ou mostra o tempo da gravação** ("Aos 5085s, ele solta que…", corte 25 do
skipnho). Causa: o `hook` do analista às vezes é uma frase descritiva. Correção: só vale com ≤ 8 palavras, ≤ 48
caracteres e sem tempo da gravação; senão usa o título do editor. A menção ao tempo é sempre removida e o texto
nunca para no meio de palavra (≤ 60 caracteres). Onde: `pick_hook` em `clipper/app/editor.py` (usado por
`auto_project` e `default_project`).
77. **Instância de teste do Clipador apaga a gravação real.** Causa: a cópia do banco aponta para os mesmos `.ts`;
o prune por `CLIPPER_KEEP_HOURS` e o monitor/varredura da cópia agiriam sobre os arquivos e canais reais.
Correção: na instância de teste, **sempre** `keep_hours = 0` (pula o prune), canais com `monitor = 0` na cópia e
sem monitor/varredura/contexto (subclasse de `Engine` que só sobe a fila de cortes); porta na faixa 4500–4599
(ex.: 4521). Derrube a instância e apague a cópia ao terminar. Onde: `prune` em `clipper/app/worker.py`.
A cópia também **herda as sessões**: um `Engine` completo retoma as `interrupted` na subida (`keep_live`), pode
gravar uma live de verdade e chamar a CLI de IA. Ao terminar, encerre a árvore de processos inteira (uvicorn,
streamlink, ffmpeg). Há várias sessões do Claude neste projeto ao mesmo tempo: uma instância na 4521 pode ser de
outra sessão — confira antes de derrubar ou usar.
78. **Emoji sai monocromático no vídeo.** Causa: o libass do FFmpeg não desenha emoji colorido. Sem correção por
enquanto (limitação registrada no README do Clipador); não prometa emoji colorido na legenda ou no gancho.
Observadas em 16–17/11/2026 no rastreio de reação (bancada e calibração numa cópia do banco, sessão 3 do skipnho;
registro em `doc/FACE_BAKEOFF.md`):
79. **`ImportError` ao carregar o MediaPipe.** Causa: `from mediapipe.tasks import python` não existe no
`mediapipe` 1.2.3. Correção: importar os submódulos (`from mediapipe.tasks.python import vision`,
`from mediapipe.tasks.python.core.base_options import BaseOptions`), e só dentro da função (o serviço e os
testes sobem sem cv2/mediapipe). Onde: backend `mediapipe` em `clipper/app/face.py`.
80. **`cv2` quebrado ou sem `FaceDetectorYN`.** Causa: `opencv-python-headless` instalado junto do
`opencv-contrib-python` (os dois brigam pelo mesmo módulo `cv2`). Correção: só `opencv-contrib-python`, o que
vem com o MediaPipe. Onde: comentário em `clipper/requirements.txt`.
81. **Risada não aparece no sinal.** Causa: em live, `jawOpen` quase nunca passa de 0,1 e `eyeWide*` fica em ~0,
mesmo com recorte apertado. Correção: risada sai do sorriso (`mouthSmile*`), com z relativo ao neutro do próprio
streamer; não exija boca aberta. Onde: `label` e `ReactionParams` em `clipper/app/reaction.py`.
82. **Streamer partido em dois na detecção da câmera.** Causa: agrupar os rostos comparando com o 1º membro do
grupo; quando ele se inclinou (0,8 largura de rosto) virou outro grupo. Correção: agrupar pelo **centro**
(média corrente) do grupo, tolerância `cluster_faces` 1,0. Onde: `locate_cam` em `clipper/app/reaction.py`.
83. **"Sustos" falsos.** Causa: o rastreio perde o rosto por instantes e o centro "pula", virando movimento grande.
Correção: movimento só rotula (não entra na intensidade) e só vale com rosto em ≥ 80 % do segundo
(`motion_min_present`). Onde: `clipper/app/reaction.py`.
84. **Streamer de neutro sorridente não gera pico** (corte 12 aprovado sem pico). Causa: o z é relativo ao normal
dele, que já é alto. Sem correção: limitação do sinal relativo (`smile_raw` só ajuda no rótulo). Por isso o rosto
só reforça o corte (bônus ≤ 0,6) e nunca decide sozinho; não o use como juiz.
Observadas em 17/11/2026 nos testes ao vivo do rastreio (instância isolada na 4521; seção "Testes de 17/11 — ao vivo"
de `doc/FACE_BAKEOFF.md`):
92. **Live sem câmera ganha "webcam"** (twitch.tv/lofigirl). Causa: o YuNet achou um rosto de 24×34 px colado na
borda (a tela de um notebook desenhado) em 8 de 12 quadros, score 0,61–0,66, e o `locate_cam` aceitou só pela
presença estável. Webcam real dá 0,92–0,94. Correção: confiança média do grupo ≥ `ReactionParams.min_cam_score`
(0,7). Onde: `locate_cam` em `clipper/app/reaction.py`; teste em `clipper/tests/test_reaction.py`.
93. **Instância de teste com banco novo pega a transcrição de outra sessão.** Causa: o serviço de voz (4510) é
compartilhado e guarda a transcrição pela chave `clipper-<sessão>-<bloco>`; num banco novo as sessões recomeçam
do 1 e colidem com as do banco real. Correção: antes da 1ª sessão, subir o `sqlite_sequence` de `sessions` do
banco de teste (ex.: 90000), além de `CLIPPER_DATA_DIR`/`CLIPPER_OUTPUT_DIR` dentro do repo. Onde: receita em
"Variáveis" de `clipper/README.md`; pastas em `clipper/app/config.py`.
94. **Analista lê "sem reação marcante no rosto" com o plano B.** Causa: o OpenSeeFace não tem blendshapes; os canais
saem 0 e o resumo dizia que não houve reação, o que é falso. Correção: com a série da sessão no backend
`openseeface`, `FaceService.summary` devolve "" (nenhuma linha de rosto vai ao analista). Onde: `clipper/app/face.py`.
95. **WARNING "pesquisa de jogo falhou: IA desligada" a cada 30 s** com o juiz `off`. Causa: `research_pending`
tentava pesquisar o jogo mesmo com a IA desligada. Correção: sai cedo se `judge.enabled` for falso (o jogo fica
`pending`). Onde: `Intel.research_pending` em `clipper/app/intel.py`.
Observadas em 16/11/2026 no teste de UI do editor de cortes redesenhado (Chrome sem janela por CDP):
85. **Teste automático não acha texto, legenda nem chat no monitor Programa.** Causa: a prévia é um `<canvas>`; as
camadas não são elementos do DOM. Correção: mover o ponteiro sobre o canvas e ler `style.cursor` — `"move"` =
há camada arrastável ali (`hitAt` em `panel/src/components/clip-editor-preview.tsx`). Trilhas e palavras da
timeline são DOM normal.
86. **Teste de UI grava no corte real do usuário.** Causa: o editor salva sozinho 1,2 s depois de cada mudança e o
painel (4500) fala com o Clipador real (4520). Correção: interceptar toda requisição não-GET de
`*/api/clipper/*` (domínio `Fetch` do CDP) e responder sem repassar; conferir depois que nada mudou. Para
simular dados (ex.: sessão em outro estado), altere só a **resposta** do GET (`requestStage: "Response"`). Para
testar gravação de verdade, use a instância sobre cópia do banco (item 77). Ligue o `Fetch` **antes** de navegar,
senão os GET da carga da página passam sem alteração. Atalho com Ctrl (Ctrl+Z) precisa ir como evento `keyDown`.
Observadas em 16–17/11/2026 no serviço do usuário (sessão 3 do skipnho) e no painel; 87–90 também em "Armadilhas já
resolvidas" de `clipper/README.md`:
87. **Cortes presos em `rendering` sem mensagem; a capa sai e o vídeo não** (10 cortes, ids 42–58). Causa: o serviço foi
reiniciado no meio de uma edição de código e subiu com uma versão intermediária da legenda (casava a ênfase por
`id()` da palavra → `KeyError` quando o saneamento mudava palavras); a exceção escapava do render e o corte ficava
em `rendering` para sempre. Correção: qualquer exceção no render vira `error` com a mensagem; `rendering` órfão há
> 5 min volta para `pending` (3ª vez = `error`). Regra: **só reinicie o serviço com a suíte verde**; agente que
edita `clipper/app/` trabalha numa cópia e aplica no fim **por edição pontual** (trecho a trecho), nunca
sobrescrevendo o arquivo inteiro: vários agentes e outras sessões mexem em `clipper/` ao mesmo tempo e a cópia
inteira apagaria o trabalho deles. Onde: `render_clip`, `recover_orphan_renders` em `clipper/app/worker.py`.
88. **Live no ar foi para `processing` depois de reiniciar o serviço.** Causa: a retomada da subida checava uma vez só,
e timeout/erro do `streamlink --json` pareciam "offline". Correção: `Engine.live_check` separa `live`/`offline`/
`unknown` e `keep_live` tenta de novo (`RESUME_DELAYS_S` 0…120 s); a sessão fica `interrupted` enquanto tenta; a
captura que cai no meio passa pelo mesmo caminho. Onde: `clipper/app/worker.py`; teste `clipper/tests/test_resume.py`.
89. **O mesmo momento vira vários cortes** (pico 1149 s → cortes 42, 47, 49, 51, 52 em cima do 9). Causa: o juiz recua o
trecho para antes do pico (ainda mais com `backtrackS` 120), e a checagem comparava o candidato só com o trecho
final dos cortes. Correção: comparar também o pico e a janela original (`reasons.candidateStartS/EndS`), em
qualquer estado, e conferir de novo depois do juiz (`judge.duplicateOf`). Onde: `clipper/app/worker.py`
(`SAME_PEAK_S`, `SAME_MOMENT_OVERLAP`, `discard_pending_duplicates`); teste `clipper/tests/test_render_and_duplicates.py`.
90. **Legenda uma em cima da outra com fala rápida.** Causa: o fim de cada bloco (fim da última palavra, no mínimo
+0,25 s) passava do início do seguinte e o libass empilha eventos ativos ao mesmo tempo; o Whisper também devolve
palavras de 0 s e palavras que começam juntas. Correção: `clean_words` (ordem, 60 ms mínimos, 40 ms entre inícios,
sem sobreposição) e `caption_blocks` (fim do bloco cortado no início do seguinte); ênfase casada nos tempos
originais. Onde: `clipper/app/subtitles.py`; teste `clipper/tests/test_format_and_captions.py`.
91. **Texto truncado longo alarga a página `/clipper`.** Causa: cartão dentro da grade das abas cresce com o conteúdo
intrínseco mesmo com `truncate`. Correção: `[contain:inline-size]` no cartão. Onde: cartão da sessão em
`panel/src/components/clipper-sessions.tsx`.
Observadas em 17/11/2026 (duração mínima, tarja do gancho, fontes, reenquadramento, camadas e qualidade de gravação;
103–108 também em "Armadilhas já resolvidas" de `clipper/README.md`):
103. **Cortes automáticos mais curtos que o mínimo** (mínimo 60: cortes 43 = 54,6 s, 55 = 46,8 s, 61 = 43,8 s). Causa:
`auto_project` adiantava o início para o `action_start_s` do analista sem reimpor o mínimo; juiz e varredura
limitavam o fim sem recuar o início. Correção: todo corte automático passa por `scoring.fit_window` com
`layout.min_target` (`minS` + 1 s + 0,1 s de folga, ≤ `maxS`); faltando material, cresce para trás. "Cortar agora"
e a edição à mão continuam livres. Teste: `clipper/tests/test_duration_banner_fonts.py`.
104. **Texto da tarja não desfoca na entrada `slide`.** Causa: com contorno (`\bord` > 0), o `\blur` do libass desfoca
só a borda e o preenchimento fica nítido. Correção: duas camadas ASS — preenchimento com `\bord0` e `\blur18`→0, e
o contorno por baixo. Assentado, sai idêntico ao de antes (0 px de diferença aos 1500 ms, informado). Onde:
gancho/texto `banner` em `clipper/app/editor_render.py`.
105. **Fonte empacotada ignorada pelo libass** (cai numa fonte padrão, sem erro). Causa: o `fontsdir` não lê subpastas,
e a família no ASS precisa ser o nome **dentro** do arquivo ("Poppins ExtraBold", não "Poppins"). Correção:
`assets/fonts/` plana; `family` em `assets/fonts/fonts.lock.json`; no Windows, caminho absoluto entre aspas com
`:` escapado (`layout.ass_filter`). O `fontsdir` só entra quando o ASS usa fonte empacotada, para o filtro de
projetos antigos (e o SHA de referência do vertical) não mudar.
106. **Zoom variável no tempo não sai com `crop`.** Causa: o `crop` do FFmpeg avalia `w`/`h` uma vez só (posição por
quadro, tamanho fixo); `scale` com `eval=frame` + `crop` fixo falhou no encoder e arredonda a posição a pixel
inteiro. Correção: `perspective` com `eval=frame` (4 cantos por quadro, subpixel) e depois `scale`. O contador
`in` do `perspective` começa em **1** (com `in/30` a janela ia 1 quadro adiantada). Grafo > 20 000 caracteres vai
por arquivo (`-/filter_complex`). Onde: `perspective_filter` em `clipper/app/reframe.py`; `editor_render.py`.
107. **Quadro errado ao buscar dentro de um bloco `.ts`.** Causa: o demuxer mpegts trata todo pacote como ponto de
busca; `-ss` antes do `-i` cai num quadro P → em H.264 sai o próximo quadro-chave (até 2 s depois), em **HEVC**
sai quadro **cinza** (frames do juiz, capa e YuNet; a câmera não era achada). Um 2º `-ss` depois do `-i` também
erra com áudio no bloco. Correção: `media.seek_args` busca 4 s antes, `-copyts -start_at_zero` e
`select='gte(t,alvo)'` (usado por `grab_frame` e `face.grab_bgr`). Render e proxy (concat demuxer) já buscavam certo.
108. **Vídeo para no meio do corte, sem erro** (corte de 35 s com 20 s de vídeo). Causa: o trecho atravessa a emenda de
uma retomada em outra resolução ou codec (H.264 → HEVC) e o concat + `filter_complex` corta o vídeo ali.
Correção: `uniform_segments` (`editor_render.py`) converte os blocos do trecho num intermediário uniforme só
nesse caso (render e proxy); o proxy faz `fps` antes do `scale`; `face.py` mede o tamanho do quadro por bloco.
Observadas em 17/11/2026 (diagnóstico da sessão 3, cartão da sessão, apagar cortes e prévia do editor; 114 também em
"Armadilhas já resolvidas" de `clipper/README.md`):
114. **"Não está gerando cortes".** Causa quase sempre: a **live esfriou**, não as regras. Sessão 3 (cópia do banco):
chat de 0,27–0,39 msg/s e 56–78 reações a cada 500 s caiu para 0,04–0,10 msg/s e 2–10 reações; nenhum pico da
heurística em 8872–10350 s, nem com as regras antigas; as antigas dariam 3 candidatos a mais (2 de rosto fraco com
nota 2,5 e 1 na cena do corte 61, rejeitado); zona proibida 34 % × 24 %. Correção: antes de mexer em regra, olhe
msg/s e reações (`GET /v1/sessions/{id}/timeline`) e `proposals`/`created` da varredura em `sessions.memory_json`
(e no log). Onde: `clipper/app/intel.py` (contagem), `worker.py` (`VETO_STATUSES`).
115. **"Agora na live" parece travado e o tempo gravado anda aos saltos.** Causa: o resumo só muda a cada janela da
varredura (`scanIntervalS`, 180 s) e `durationS` sobe por bloco (30 s). Correção: relógio local que corre entre as
consultas, com teto de 45 s ("aguardando o bloco"), e contagem "próximo em m:ss". Onde: `RecordingClock` e
`SummaryCadence` em `panel/src/components/clipper-sessions.tsx`.
116. **Barra de seleção presa no topo da fila reprovada pelo dono.** Causa: ação em massa ocupando espaço e cobrindo
o conteúdo. Correção: controles discretos no canto ("Selecionar", "⋯"), caixa do cartão só no hover/foco/modo de
seleção e pílula flutuante pequena; nada pode empurrar a lista. Vale para toda ação em massa nova. Onde:
`panel/src/components/clipper-queue.tsx`.
117. **Prévia do editor 1–3 px deslocada do render** (corte 61, câmera 18 % × 23 %) e blocos de legenda diferentes.
Causa: o FFmpeg recorta em pixel **par** no yuv420 e o `scale … increase` arredonda; a prévia dividia em subpixel;
a legenda do painel não saneava os tempos como `subtitles.py`. Correção: `ffmpegCropFill` com o tamanho de
`session.capture` e porte `cleanWords`/`groupWords`/`captionBlocks` (`CAPTION_TIMING`). Onde:
`panel/src/components/clip-editor-model.ts`; mudou `subtitles.py` ou `layout_chain`, mude o porte junto.
136. **Juiz do Clipador esgota a cota do ChatGPT / chamadas lentas e caras.** Causa: cada chamada do juiz é um processo
novo de CLI (2 por candidato) e o Codex carrega ~77 mil caracteres fixos (~19 mil tokens) antes do prompt; uma live de
3,7 h (75 candidatos, ~150 chamadas) gastou ~2,9 milhões de tokens só de fixo. Correção: `codex_lean_overrides`
(features/MCP/plugins off, `system` em `model_instructions_file`) e `--setting-sources project,local` no Claude.
**Só vale depois de reiniciar o Clipador (porta 4520)**: o código é lido na partida. Detalhes em
[token-economy.md](token-economy.md). Onde: `clipper/app/judge.py`.
## Publicação (Publicador + despachante do painel)
Regras de projeto informadas em 17/11/2026 (código em `panel/src/lib/publishing*.ts` e `publisher/app/`); nenhuma
observada num envio real ainda. Contexto em [publishing.md](publishing.md).
118. **Job em "Com problema" dizendo que o Publicador terminou sem confirmar o link.** Causa: o Publicador devolveu
`done` sem `remoteId`/`url` (comum no modo sessão quando a tela não mostra o link). Correção: por regra nunca vira
`published` sem ID/URL (ou rascunho) — `readPublisherJob` grava `failed`. **Confira na rede** antes de "Tentar de
novo", senão o vídeo sai duas vezes. Mesmo cuidado com `failed` "interrompido" (Publicador fechado no meio). Todo
`failed` que chegou ao Publicador tem `mayBeLive`: a UI pergunta "Confira na rede se o vídeo já saiu" e a API
responde 409 ao `retry` sem `{confirm: true}` (`retryJob` em `publishing.ts`).
119. **Job parado em "Esperando: …" sem falhar.** Causas, nesta ordem: painel fechado (o laço de 20 s roda dentro do
`pnpm panel`); publicação pausada em Configurações; Publicador fora (503 → "inicie com pnpm dev"); perfil não
`connected` no Publicador (409 → o job **fica na fila** e a rede é reconsultada); "Publicador indisponível ou mal
configurado" (401/403/404: `PUBLISHER_SERVICE_KEY` diferente ou Publicador antigo — reinicie o `pnpm dev`).
Timeout/conexão caída também deixa na fila: o reenvio usa o mesmo `clientRef` e não duplica. Onde: `sendDue`.
120. **Rede em `expired` ou `needs_login`.** Causa: autorização oficial vencida (ex.: YouTube em "Testing" vence em 7
dias) ou a rede pediu login/captcha no modo sessão. Correção: reconectar em Canais de publicação ("Entrar de
novo"/reabrir a janela); nunca automatizar login nem captcha.
121. **Jobs de um corte cancelados sozinhos.** Causa: exportar no editor (ou re-renderizar) volta o corte para
`pending`; jobs não enviados viram `canceled` com `cancel_reason = 'source_changed'`. Encerrar a fonte ou a
história no canal faz o mesmo com `unlinked` ("a fonte/história foi desligada deste canal"). Correção: nenhuma —
voltam sozinhos quando o corte fica pronto de novo ou a fonte é religada. Já enviado não é cancelado.
122. **Ligou a aprovação automática e os cortes antigos não saíram.** Não é erro: só cortes criados depois de ligar
(`accounts.auto_since`) e depois de ligar a fonte ao canal são aprovados sozinhos; religar uma fonte encerrada
zera `linked_at`, então os cortes do intervalo desligado também não. Antigos: aprovar à mão.
123. **"Na hora" virou agendado.** Causa: limite diário da rede (`daily_limit`) já atingido; vai para o próximo
horário bom livre. Correção: subir o limite ou esperar.
124. **TikTok oficial publica só como "Somente eu".** Causa: app sem auditoria só permite `SELF_ONLY` (conta privada)
e a auditoria para uso próprio provavelmente é negada (`doc/publicacao/PESQUISA.md`). Correção: modo Rascunho
(`tiktok_mode = 'draft'`, até 5 pendentes/24 h) ou sessão logada.
125. **API do painel responde 403 "Acesso recusado…" ou 415 a `curl`/script.** Causa: `panel/src/proxy.ts` só aceita
Host 127.0.0.1/localhost/[::1] e exige, em POST/PUT/PATCH/DELETE, `Origin` do mesmo host (ou `Sec-Fetch-Site:
same-origin`), senão "Acesso recusado: pedido sem origem do próprio painel"; `readJson` (`lib/http.ts`, usado em parte
das rotas; as outras leem `request.json()` direto) exige `Content-Type: application/json`. Correção:
`curl -X POST -H "Origin: http://127.0.0.1:4500" -H "Content-Type: application/json" -d '{}' http://127.0.0.1:4500/api/...`.
Não afrouxe a guarda (anti DNS rebinding e CSRF; teste em `panel/src/lib/proxy.test.ts`).
126. **Agendado saiu em outro horário depois de reabrir o painel.** Causa: horário automático (`schedule_source =
'auto'`) vencido há > 30 min (`STALE_AFTER_MS`) é reencaixado no próximo horário bom, sem rajada. Horário manual e
"Publicar agora"/"Tentar de novo" não são reencaixados. Onde: `needsReflow` (`publishing-rules.ts`), `promoteDue`.
127. **Conectar pela API oficial não conclui.** Causas: o Publicador reiniciou no meio (o `code_verifier` do PKCE fica
só em memória) ou o passo a passo parou de esperar (10 min, `WAIT_LIMIT_MS` em `connect-wizard.tsx`). Correção:
clicar **Conectar** de novo.
128. **Janela do navegador do modo sessão fecha sozinha.** Não é erro: fecha depois de cada envio e do "Já entrei"
(saída limpa; mata após 10 s) e quando ociosa (5 min; 15 min se aberta para login), para a porta CDP ficar aberta o
mínimo. Fica aberta se a rede pedir login/captcha. Onde: `publisher/app/platforms/session/browser.py`.
137. **Modo sessão: o Chrome abre, a conta está logada, a porta 4540 responde em `/json/version`, mas o painel diz "O
navegador abriu mas não respondeu".** Causa (17/11/2026): o **Chrome 157 (157.0.8103.79) não grava
`DevToolsActivePort` no perfil quando a porta é fixa** (`--remote-debugging-port=4540`), e `owns_port` dependia só
desse arquivo. Correção: `owns_port` usa o `DevToolsActivePort` quando existe; senão usa a marca
`CenaForgeWindow.json` (`{"pid","port"}`, gravada por `write_window_mark` logo depois do `Popen`) e exige que o PID
que escuta na porta (`listener_pid`, `GetExtendedTcpTable` via ctypes, sem psutil) seja exatamente o da marca e que o
executável (`process_exe_name`, `QueryFullProcessImageNameW`) seja `chrome.exe`/`msedge.exe`. `active_port` também lê
a marca; `open()` apaga marca e `DevToolsActivePort` velhos. Medido ao vivo: `listener_pid(4540)` = `chrome.exe`
lançado pelo Publicador (o PID do `Popen` é o próprio processo que escuta). **Só vale depois de reiniciar o
`pnpm dev`** (o Publicador roda sem `--reload`). Variante: se o processo sai logo, o Chrome entregou a URL a uma
janela já aberta com o mesmo perfil (sem a nossa porta); `_wait_cdp(port, user_dir, process)` detecta e mostra "Já
existe uma janela do navegador aberta com este perfil. Feche essa janela (a conta continua logada) e tente de
novo." — feche a janela, não mexa no código. Testes: `test_owns_port_without_devtools_file_uses_window_mark` e
`test_wait_cdp_explains_when_profile_window_is_already_open` em `publisher/tests/test_hardening.py`. Onde:
`publisher/app/platforms/session/browser.py`.
138. **"Publicar" no cartão do corte (ou desligar fonte) falha com "table publish_jobs has no column named origin".**
Causa (17/11/2026, `POST /api/publishing/clips/75`): a v7 do banco (`publish_jobs.origin`) não tinha sido aplicada
no banco já aberto; `INSERT ... origin` e `accounts.endChannel` (`AND origin = 'link'`) quebram. Hoje o `db()` migra
sozinho: a conexão fica em `globalThis.__cenaforgeDb`, e a marca de módulo `checkedThisModule` (some a cada recarga
do código pelo HMR) faz a 1ª chamada depois da recarga rodar `migrate()` no banco aberto, com backup em
`data/backups/` (`cenaforge-v<antiga>-<data>.db`). Medido: um `GET /api/publishing/summary` no painel em execução
levou o banco real a `user_version` 7, com a coluna `origin` e o backup `cenaforge-v6-2026-11-17T16-28-39-725Z.db`.
O sintoma ainda aparece se o próprio `db.ts` não foi recarregado (módulo antigo, sem a marca); na prática qualquer
edição em `db.ts` o recarrega. Correção: fazer qualquer requisição ao painel (ex.: `GET /api/publishing/summary`,
com `Origin` se não for GET, item 125) ou, se ainda falhar, pedir ao usuário que reinicie o `pnpm dev` (o painel é
dele; reiniciar mata agente em execução, item 131). Conferir: `PRAGMA user_version` de `data/cenaforge.db` =
`MIGRATIONS.length`. Onde: `db()` em `panel/src/lib/db.ts`, `publishClip` em `panel/src/lib/publishing.ts`.
139. **Modo sessão (TikTok): job falha com "Locator.set_input_files: Cannot transfer files larger than 50Mb to a browser
not co-located with the server", embora o login e a navegação tenham funcionado.** Sintoma (17/11/2026): a captura
`data/publisher/logs/20261117-133245-tiktok-*.png` mostra o TikTok Studio logado na tela "Selecione o vídeo a
enviar"; a falha foi só na entrega do arquivo. A mensagem ao usuário é a genérica "O navegador travou ou mudou de
página no meio do envio" (todo `PlaywrightError` cai nela, `_with_page`); o texto real vem depois de "Detalhe:". Causa:
com `connect_over_cdp` o Playwright trata o navegador como remoto e recusa `set_input_files` acima de 50 MB; os
cortes do Clipador têm 100–108 MB (`clip-52.mp4` com 107,9 MB). Correção: `is_local=True` no `connect_over_cdp`
(parâmetro existe no playwright 1.65.2 da `publisher/.venv`, conferido na assinatura), em `_with_page`
(`runner.py`, com comentário) e em `BrowserManager.close` (`browser.py`). Só `127.0.0.1` com porta conferida como
nossa (`owns_port`); não use para endereço remoto. **Só vale depois de reiniciar o `pnpm dev`** (o Publicador roda sem
`--reload`). Evidência: `pnpm test:publisher` → 73 passed (reexecutado na skill, 17/11/2026); **envio real ainda não
refeito**. Ao ver "travou ou mudou de página", leia o "Detalhe" antes de culpar o navegador. Onde:
`publisher/app/platforms/session/runner.py`, `publisher/app/platforms/session/browser.py`.
140. **TikTok em modo sessão publicou, mas o job falhou com "não confirmou o link".** Sintoma (17/11/2026, 1º envio real,
público às 13:35): o vídeo está no ar (`https://www.tiktok.com/@vortplay/video/7709179978520284437`) e o painel marcou
`failed`. Causa: depois de publicar, o Studio vai para `/tiktokstudio/content`, mas a linha nova só mostra o
`<a href="/@conta/video/<id>">` alguns segundos depois; o código antigo procurava `a[href*='/video/']` por só 5 s.
Correção (2ª versão, 17/11/2026): `find_video_url(page, caption, sleep, attempts=12, reads=5, progress)` espera 5 s e, a
cada tentativa, abre ou RECARREGA `CONTENT_URL` (a lista não se atualiza sozinha; o vídeo novo entra depois de
processar), lê 5 vezes a cada 3 s, até 12 cargas (~3 min), e só aceita o link da linha (até 10 ancestrais do `<a>`)
que contém `caption_key(caption)` (24 primeiros caracteres da legenda sem #hashtags/@menções): nunca pega o link de
outro vídeo. Sem link: step "…não apareceu na lista do Studio em ~3 min; link não encontrado"; o painel mostra "Saiu
na rede, mas o link do vídeo não apareceu a tempo… use 'Já saiu: informar o link'" (`readPublisherJob`). O seletor `video_link` saiu
de `SELECTORS`. Validado ao vivo, só leitura (informado): legenda certa → link; legenda de outro corte → `None`. Se
acontecer de novo: **confira na rede antes de "Tentar de novo"** (publicaria duas vezes) e use "Já saiu: informar o
link" (`mark-published`, `publishing.md`). Só vale depois de reiniciar o `pnpm dev` (item 137). Teste:
`test_tiktok_link_waits_for_the_list_and_matches_caption` (`publisher/tests/test_browser.py`). Onde:
`publisher/app/platforms/session/tiktok_studio.py`.
141. **Job manual novo cancelado como "unlinked" (regra antiga) ou despachante ignorando código novo.** Causa: o laço de
`panel/src/instrumentation.ts` (`startDispatcher`) guarda a função `tick` em `globalThis` e o HMR não a substitui;
o laço seguia com o `dispatcherTick` antigo (sem a regra de `origin = 'manual'`). Correção: no fim de
`panel/src/lib/publishing.ts`, ao carregar o módulo, `if (state.tick && state.tick !== dispatcherTick) state.tick =
dispatcherTick`. Regra: todo estado de laço guardado em `globalThis` precisa ser reapontado quando o módulo recarrega.
Se o sintoma voltar com outro módulo, aplique o mesmo padrão; reiniciar o `pnpm dev` é do usuário (item 131). Onde:
`panel/src/lib/publishing.ts` (bloco final), `panel/src/lib/dispatcher.ts`.
142. **Modo sessão (TikTok): falha com "Locator.click: Timeout 30000ms exceeded … waiting for locator("div[contenteditable='true'].public-DraftEditor-content")".**
Sintoma (17/11/2026): a captura `data/publisher/logs/20261117-134508-tiktok-*.png` mostra o vídeo já carregado e,
por cima da página escurecida, um aviso de novidade do Studio, "Veja a prévia do seu vídeo no seu celular", com o botão
**Entendi**. Causa: o aviso bloqueia o clique na legenda (o seletor está certo). O Studio também pré-preenche a legenda
com o nome do arquivo ("clip-75"), mas `fill_text` já faz Ctrl+A/Delete. Correção em `common.py`: `TIP_BUTTONS` aceita só
`^(Entendi|Entendido|Ok, entendi|Got it)$`; `dismiss_tips(page, sleep, rounds=3)` fecha esses avisos;
`click_through(locator, sleep, timeout_ms=8000)` clica e, no timeout, fecha os avisos e tenta de novo (sem aviso
para fechar, relança o erro original); `fill_text` usa `click_through`. Em `tiktok_studio.py`, `dismiss_tips` roda
antes da legenda e antes de "Publicar", e todos os cliques (privacidade, mostrar mais, IA, Publicar, Publicar agora)
passam por `click_through`. **Regra:** por esse caminho só se fecham avisos de "entendi"; nunca aceitar ou recusar
opções (verificação de conteúdo, música etc.). Outro aviso novo com outro texto de botão: acrescente-o a `TIP_BUTTONS`
só se fechá-lo não mudar o post. Mensagens: `browser_error_text(detail)` em `runner.py` troca o genérico "O navegador
travou…" por frases para clique com timeout ("aviso do site aberto por cima…"), timeout comum, arquivo > 50 MB e janela
fechada; o "Detalhe" técnico continua depois. Testes: `test_click_through_closes_tip_and_retries` e
`test_browser_error_text_explains_common_failures` (`publisher/tests/test_browser.py`); `pnpm test:publisher` → 76
passed (reexecutado na skill, 17/11/2026). **Só vale depois de reiniciar o `pnpm dev`** (item 137); o post desse envio
não chegou a ser feito e a correção **não foi testada num envio real**. O upload de 100+ MB funcionou nesse envio, o
que indica que o `is_local` (item 139) já valia. Onde: `publisher/app/platforms/session/common.py`,
`publisher/app/platforms/session/tiktok_studio.py`, `publisher/app/platforms/session/runner.py`.
143. **Corrigi o código, mas o envio/corte seguinte ainda se comportou como antes.** Sintoma (17/11/2026): o envio das
13:50 no TikTok durou 25 s, menos que a busca nova do link, e saiu sem link. Causa: o processo do Publicador (uvicorn
:4530) começou às 13:34:25; `tiktok_studio.py` (13:46), `common.py` e `runner.py` (13:46–13:47) foram gravados depois,
e o serviço roda sem `--reload`: rodou o código ANTIGO. Vale também para o Clipador (:4520) e a voz. Diagnóstico:
comparar o início do processo com a data dos arquivos, antes de culpar a correção:
`Get-CimInstance Win32_Process -Filter "Name='python.exe'" | Select ProcessId,CreationDate,CommandLine` (PowerShell) e
`Get-Item <arquivo> | Select LastWriteTime`. Arquivo mais novo que o processo = reiniciar o `pnpm dev` (do usuário,
item 131). Só dê "validado" a mudança em serviço depois de confirmar que o processo é posterior ao arquivo.
144. **Legenda do corte com `#RobRun` e `#ROBRUN` alternando ou tags genéricas (`#clã`, `#loot`).** Causa (antes de
17/11/2026): o juiz escrevia 3–5 hashtags livres na legenda. Hoje a legenda sai de `build_caption`
(`clipper/app/hashtags.py`): texto sem hashtags, tags de `compose` (canal, até 3 do jogo, até 4 do momento, sem
repetidas por `fold`, até 8) e crédito. Se o perfil do jogo **não tem `hashtags`** (caso do ROB RUN até a pesquisa ou
a edição), vale só o nome do jogo (`#ROBRUN`): use "Pesquisar de novo" ou edite a seção "Hashtags" na aba Jogos.
Legenda de corte antigo não muda; só corte novo ou "Mandar de novo para a IA". Só vale depois de reiniciar o
Clipador (item 143). Teste: `clipper/tests/test_hashtags.py`.
145. **Modo sessão (Instagram): "Já entrei" responde "não achei o botão Criar do Instagram" com a conta logada.**
Causa (17/11/2026, inspecionado ao vivo): no layout novo a barra lateral só tem ícones; o botão é `<a>` com
`<svg aria-label="Postar">` e abre direto o diálogo "Criar novo post" (sem submenu), com o `input[type=file]` dentro
do diálogo. O usuário também rodava código antigo (item 143). Correção: `SELECTORS["create"]` aceita "Postar"
(svg, link, botão); mensagem "botão Postar". Risco ligado: no feed cada post tem um botão de ícone "Compartilhar", e
`role=button ^Compartilhar$` podia clicá-lo; `next`, `share` e `reels_notice_ok` agora são CSS presos a `_DIALOG`
(`div[role='dialog']`). Teste: `test_buttons_of_the_flow_are_searched_inside_the_dialog`. Onde:
`publisher/app/platforms/session/instagram_web.py`. Fluxo e validação: [publishing.md](publishing.md).
146. **Instagram: rótulo de IA não liga, ou a legenda troca `#teste` por `#testemunho`.** Causa: com a legenda terminando
em `#tag`/`@menção`, o Instagram abre a lista de sugestões POR CIMA dos interruptores; um clique forçado
(`force=True`) no rótulo de IA caiu na lista (ensaio de 17/11/2026). O interruptor é `input role=switch` sem nome
acessível (achado pelo texto da linha, `find_ai_switch`). Correção: `close_suggestions` digita um espaço no fim
(Esc NÃO serve: fecha a caixa de criação); clique forçado removido; depois do clique `_is_on` confere e, se não ligou,
`PublishError` (não publica sem o rótulo). Teste: `test_instagram_links_and_hashtag_suggestions`. Regra geral: nunca
`force=True` em seletor de modo sessão (clica no que estiver por cima). Para validar seletor com conta real sem
publicar, rode só `prepare` e descarte o rascunho.
147. **Instagram: o reel saiu em 1:1 (quadrado), sem o topo do rosto do streamer; o TikTok saiu certo.** Sintoma
(17/11/2026, 1º reel real `/reel/Df2cezTNhY7/`, corte 68). Causa: a etapa "Cortar" do diálogo vem em 1:1 e o fluxo
clicava em "Avançar" direto. Correção: `keep_original_shape(page, sleep)` (`instagram_web.py`), chamada em `prepare`
antes dos "Avançar": clica em `svg[aria-label='Selecionar corte']` (ou 'Select crop') dentro do diálogo, escolhe
"Original" (opções: Original, 1:1, 9:16, 16:9) e fecha o menu. Sem o ícone ou sem a opção, `PublishError`: **não
publica cortado**. Sub-armadilha: o botão "Original" tem o texto mais o `<title>` do svg ("Ícone de contorno de
foto"), então `:text-is('Original')` não casa; usa-se `("role","button", r"^\s*Original\b")` e `:has-text` no
diálogo. Também `common.find` com `visible=True` agora olha até 6 ocorrências (`nth`) até achar uma visível (a
primeira pode ser cópia escondida); os falsos de teste ganharam `nth`. Validado (informado): ensaio sem publicar
mostrou a prévia "Novo reel" com o vídeo inteiro 9:16, rosto completo, legenda e rótulo de IA; rascunho descartado.
O usuário apagou o reel cortado à mão (a página mostra "Esta página não está disponível"). **Só vale depois de
reiniciar o `pnpm dev`** (item 143); nenhum envio real feito com o formato novo. Onde:
`publisher/app/platforms/session/instagram_web.py` (`SELECTORS["crop_toggle"]`, `["crop_original"]`), `common.py`.
148. **Corte publicado com rótulo de IA, ou "Perfil gerado por IA" sob o nome no Instagram.** Regra (pedido do dono,
17/11/2026): corte nunca leva rótulo de IA. Em `sendDue` (`publishing.ts`): `aiGenerated = job.source_kind === "clip"
? false : aiGeneratedFor(...)`, mesmo com o canal em "always". O texto "Perfil gerado por IA" visto no reel NÃO veio do
post: o job tinha `aiGenerated: False` e o canal estava em `ai_label=auto`. Provável rótulo do PERFIL (talvez foto de
perfil feita com IA e metadados); **não confirmado**. Episódio segue a regra de `aiGeneratedFor`.
149. **Vídeo publicado foi apagado na rede e o painel ainda o mostra como publicado (ou não deixa publicar de novo).**
Correção: ação "Apaguei na rede" (`removed`), só em job `published`. `markRemoved(id)` (`publishing.ts`) faz UPDATE
condicional para `canceled`/`user`, zera `url`, `remote_id`, `published_at`, grava o step "Apagado da rede por você…"
e apaga `publications WHERE job_id` (métricas saem em cascata). Depois, "Publicar" no corte reenvia com `attempts`+1
(novo `clientRef`). O painel NÃO apaga nada na rede: apague direto lá primeiro (a UI confirma). Rota
`POST /api/publishing/jobs/[id]/removed`; cliente `markJobRemoved`; botão em Publicadas (`publishing-board.tsx`).
Usada no job 3 (Instagram do corte 68). Teste em `publishing-db.test.ts`.
150. **Script Python de diagnóstico com `-I` imprime `?`/falha ao escrever acentos no Windows.** `python -I` ignora
`PYTHONIOENCODING` e `PYTHONUTF8`. Correção: no script, `sys.stdout.reconfigure(encoding="utf-8")`.
Relacionadas, já registradas acima:
- `codex.cmd` sem shell: item 28.
- Script de patch com regex (`\b`) passado por heredoc: item 44.
- Publicador roda sem `--reload`: mudança em `publisher/app/` só vale depois de reiniciar o `pnpm dev` (itens 137, 139, 140, 142, 143, 145 e 147; o Clipador também: 144).
- Migração do painel (v3 … v7) é aplicada na 1ª requisição depois da recarga do `db.ts`; reiniciar o `pnpm panel`/`pnpm dev` só se isso não bastar: itens 51 e 138 (reiniciar mata agente em execução: item 131).
@@ -0,0 +1,516 @@
# Painel: confirmação e aviso, formatos de história, leitor de roteiro, montagem documental (fotos do Commons, cenas 2D/3D e biblioteca, um clique), vertentes, votação, agentes (e mensagem durante a execução), exclusão, canais de publicação e dashboard
Fonte: código em `panel/src/lib/` e `panel/README.md`. O painel é do usuário: ele roda
`pnpm panel`; não inicie, não encerre, nada de `next build` com o dev ligado.
## Confirmação e aviso (`components/confirm-dialog.tsx`)
**Regra:** nada de `confirm()`/`alert()` nativos no painel (hoje não sobra nenhum em `panel/src/`). Use:
| Função | Uso |
|---|---|
| `askConfirm({ title, message?, confirmLabel?, cancelLabel?, tone? })` | `Promise<boolean>`; `false` em Cancelar, Esc ou clique no fundo. O handler que pergunta vira `async`: `if (!(await askConfirm({...}))) return;` |
| `showAlert({ title, message?, okLabel?, tone? })` | `Promise<void>`; um botão só (padrão "Entendi"), `role="alertdialog"` |
| `confirmSubmit(options, when?)` | `onSubmit` de `<form action={serverAction}>`: segura o envio, pergunta e, se confirmou, `form.requestSubmit(submitter)` com `data-confirmed="1"` (o 2º submit passa sem perguntar). `when()` decide se precisa perguntar. Usado em `delete-story-button.tsx` e `forms.tsx` |
- `tone: "danger"` → botão de confirmar vermelho e foco inicial em **Cancelar** (Enter não apaga por engano).
- `<ConfirmHost />` montado **uma vez** em `app/layout.tsx`; pedidos entram numa fila (um por vez; antes do host
montar, esperam num backlog). É `<dialog>` nativo com `showModal()`, então abre por cima de outros modais nativos
(ex.: `CutSettingsDialog` de `clipper-cut-settings.tsx`). Não monte um segundo host.
- `Button` (`components/ui.tsx`) tipa as props como `ComponentProps<"button">` e aceita `ref` (React 19).
## Banco (`data/cenaforge.db`, esquema v7)
- Migração em `panel/src/lib/db.ts` (lista `MIGRATIONS`). Banco com dados → cópia em `data/backups/`
antes de migrar (`cenaforge-v<atual>-<data>.db`). `foreign_keys = OFF` fora da transação e `PRAGMA
foreign_key_check` antes do `COMMIT` de cada versão.
- v3: `account_channels` (conta ↔ canal de live do Clipador; `status` `active`/`ended`). O canal
vive em `data/clipper/clipper.db`, então não há chave estrangeira para ele.
- v4: reconstrói `stories` (SQLite não altera CHECK) para `kind` aceitar `'documentary'`; mesmas
colunas e ids.
- v5: publicação real — `publish_jobs`, `app_settings`, `clip_auto_approvals`; `account_networks` e `publications`
reconstruídas (sem `mock`; `publications.clip_id`/`job_id`); colunas novas em `accounts` (`approval_mode`, `timing`,
`ai_label`, `auto_since`) e `episodes` (`approved_at`, `approved_render_id`, `publish_title`, `publish_caption`).
Detalhe em [publishing.md](publishing.md) e `doc/publicacao/PLANO.md` §4.
- v6: reconstrói `publish_jobs` (ids preservados) com `schedule_source` (`auto`/`manual`/`now`) e `cancel_reason`
`unlinked`. Banco real em v6 (`PRAGMA user_version`, conferido em 17/11/2026, antes da v7).
- v7: `publish_jobs.origin` (`link`/`manual`, padrão `link`): job criado pelo botão "Publicar" do corte. Ver publishing.md.
- API: toda rota `/api/**` passa por `panel/src/proxy.ts` (Host local; escrita exige `Origin` do painel) e corpo por
`readJson` (415 sem `Content-Type: application/json`) — gotchas, item 125.
- A conexão fica em `globalThis.__cenaforgeDb`; a marca de módulo `checkedThisModule` faz a 1ª chamada de `db()` depois
de recarregar o código rodar `migrate()` no banco aberto (backup em `data/backups/`) → esquema novo entra na 1ª
requisição, sem reiniciar. Só se o `db.ts` não foi recarregado é preciso reiniciar o `pnpm panel` (gotchas, itens 51 e 138).
- Testes do painel: `pnpm --filter cenaforge-panel test:panel` (`panel/src/lib/*.test.ts`, node:test via tsx). Teste que
importa algo que abre o banco precisa de `CENAFORGE_ROOT` numa pasta temporária (gotchas, item 99).
## Formatos de história (`kind`)
Lista em `STORY_FORMATS` (`components/story-formats.ts`, rótulo curto `storyFormatLabel`) + tipo
`StoryKind`/`STORY_KINDS` (`lib/types.ts`). Formato novo também exige migração do CHECK em `db.ts`.
| `kind` | O que é | Arquivos |
|---|---|---|
| `interactive` | episódios ~12 s terminando em votação A–D (2–4 vertentes) | `biblia.md`, `<file_key>.md`, `.choices.json` |
| `linear` | episódios de ficção em sequência, sem votação (`branch_count` = 1) | `biblia.md`, `epNN.md` |
| `documentary` | **vídeo único** vertical sobre tema real, nomes reais, fato com fonte, sem votação | `biblia.md` = ficha de pauta; `ep01.md` = roteiro (formatos em `doc/roteiro/documental.md`) |
- Regras de texto e formato dos arquivos: **`doc/roteiro/`**, fonte única para Claude e Codex.
`comum.md` (idioma, onde escrever, estrutura do vídeo curto, limites do overlay, produção, retorno;
tabela formato → guia) + `ficcao.md` (interativa/linear: sem cidade, marca ou pessoa real, A/B no fim,
formato de `biblia.md` e `ep<NN>.md`) ou `documental.md` (nomes reais, fato com fonte, mito × fato,
45–90 s, ficha de pauta e roteiro). 1ª linha da `biblia.md`: `Formato: interativa | linear | documental`.
- Aba Fluxo: tudo que não é `interactive` usa layout em linha (`story-flow.tsx`).
- Termos na interface: `unitTerms(kind)` (`story-formats.ts`) → `{one, One, many, Many, code(n)}`. Série =
"episódio"/`ep01`; documental = "vídeo" (`code(1)` = "vídeo", `code(n)` = "vídeo n"). Usado no console do
agente (campo "Episódio" vira "Vídeo"; `StoryOption` tem `kind`), no cartão da página inicial, na página da
história (aba, contagem, criar) e na do episódio (breadcrumb, eyebrow "Vídeo documental", metadata). Texto
novo que fale da unidade usa `unitTerms`, não "episódio" fixo. O **arquivo** continua `episodeCode` (`ep01.md`).
- `createStoryFromTextAction`: no documental o episódio nasce sem título ("Abertura" só em série).
## Leitor de roteiro (`lib/script-doc.ts` + `components/script-reader.tsx`)
- `parseScript(md)` (puro, sem servidor) → título, metadados, `facts` (pares `Chave: valor` separados por " · "),
seções com `role` deduzido do título (`hook`, `shots`, `sources`, `needs`, `cover`, `overlay`, `summary`, `ending`,
`consequences`, `other`), `shots`, `targetSeconds`, `narrationWords`. Trechos = a **primeira tabela cuja 1ª coluna
é "t (s)"/tempo**; as outras colunas são achadas pelo cabeçalho (imagem/b-roll, texto na tela, narração/diálogo).
Mudar o cabeçalho em `doc/roteiro/` (`documental.md`, `ficcao.md`) pode quebrar a leitura.
- Tempo falado = palavras / `WORDS_PER_SECOND` (2,5). Alertas: narração total > 1,1× a duração alvo; trecho com
narração > 1,15× a duração dele ("mais longa que o trecho").
- `ScriptReader` não usa HTML cru: markdown em linha próprio (negrito, itálico, código, links/URLs com
`target="_blank" rel="noopener noreferrer"`). Mostra resumo, "Copiar narração" (`components/copy-button.tsx`),
"Gerar áudio em Vozes" (só um link para `/voices`; não leva o texto), gancho, régua do vídeo com âncoras
`#trecho-N`, cartão por trecho, texto de capa com contagem de caracteres, fontes com domínio, necessidades de
produção e o .md original recolhido.
- Usado em `app/stories/[storyId]/episodes/[number]/page.tsx` e na página só de leitura `.../[number]/roteiro/page.tsx`.
Página da história: botão "Ler roteiro" → último episódio com roteiro.
- Documental na página do episódio: roteiro primeiro (`order-first`), título do roteiro, eyebrow "Vídeo documental";
sem "Montar cena" nem render da rua 3D — no lugar, o passo a passo "Como este vídeo é feito" e o card "Montagem do
vídeo" (seção abaixo).
## Montagem documental
Card "Montagem do vídeo" (`components/montage-editor.tsx`) na página do vídeo documental. Regras de texto em
`doc/roteiro/comum.md` e `documental.md` (seção "Como o vídeo é montado"). **Decisão do dono (17/11/2026): a geração
é automática, num clique; o admin só revisa e troca.**
- **Um trecho = uma linha da tabela "t (s)"** do roteiro (`parseScript`). Cada trecho tem:
- **áudio próprio**, um parágrafo por vez (decisão do dono: áudio longo deixa a voz estranha), gerado do **texto
falado**: editável, nasce de `toSpokenText(narração)` (`lib/speech-text.ts`: números até bilhões, decimais
"0,0055" → "zero vírgula zero zero cinquenta e cinco", milhar "1.500", km, m², ha, cm, kg, %, "por m²"). Texto na
tela que é pergunta e que a narração não repete entra antes da fala ("Uma cobra por metro quadrado? Não. ...");
- **visual** (`VISUAL_KINDS` em `lib/montage.ts`; rótulo da UI entre parênteses): `image` (Foto), `godot2d`
(Animação 2D), `godot3d` (Cena 3D da biblioteca), `video` (Clipe: envio ou render Godot já feito), `card`
(Cartela, sem arquivo). Pode misturar. `ShotVisual`: `scene` + `sceneKey` (Godot), `search {queries, pick}` (foto
da internet), `auto` (escolhido pelo automático; trocar à mão grava `auto: false`), `inset` (cartão de foto por
cima do visual; na UI, `InsetCard`: "Outra foto", "Tirar", "Pôr foto da internet").
- **Estilo do vídeo** (`style` no `.montage.json`, `PATCH {style}`; seletor "Estilo do vídeo" no topo): `"mixed"`
(padrão: foto, 2D e 3D) ou `"3d"` ("Tudo em 3D": todo trecho vira cena 3D da biblioteca, fotos só em cartão).
Regras de roteiro para isso: "Vídeo todo em 3D" em `doc/roteiro/documental.md` (coluna Imagem = tomada 3D,
`[foto: termos]`, cenas 3D que faltam em "Necessidades de produção").
- **Cartões de informação em sequência:** texto na tela `A; depois: B; depois: C` mostra as partes uma após a outra,
dividindo o tempo do trecho.
- Topo do card: **"Gerar vídeo automático"** (etapa do `job` + Cancelar), **"Refazer tudo do zero"** (`replan`) e
modo manual: voz pt-BR, velocidade 0,7–1,3 na UI (o servidor aceita 0,5–2), legenda, "Gerar N áudios", "Só montar".
- Por trecho: estilos em grade (3 colunas; 5 a partir de `sm`), **"Gerar de novo"** (ou "Buscar na internet" na foto
sem arquivo) e `SceneEditor`: 2D = modelo (`DOC2D_TEMPLATES`) + campos; 3D = seletor da biblioteca + formulário
gerado do manifesto + link "Peça uma nova ao agente" (`/agent?kind=godot&story=…&prompt=…`). "Prévia da cena" =
`renderShotScene` ← `POST .../montage/scene`.
- Envio de visual (multipart): **licença opcional** (padrão "não informada", decisão do dono), crédito e link
opcionais; vira asset da história (`AssetKind` `image`/`video`). Também dá para escolher da biblioteca/assets da
história ou dos renders Godot com `status = 'success'`.
- Estado: `stories/<id>/<file_key>.montage.json` (`voiceId`, `speed`, `captions`; por índice `spoken`, `visual`,
`audio{file, durationMs, key}`). Áudio: `stories/<id>/audio/<file_key>-NN.ogg`. Config de cada cena Godot:
`stories/<id>/godot/<file_key>-tNN.json`. `audioKey` = hash de voz + velocidade + texto falado; `sceneKey` = hash
de `kind` + modelo + params + duração (fala + pausa). Mudou → aparece desatualizado.
### Plano do trecho (`lib/montage-godot.ts`, sem banco, sem IA)
- `scriptEntities(md)`: nomes científicos (itálico binomial, `*Bothrops insularis*`) e lugares de `MAP_PLACES` citados.
- `planShot(shot, {species, places, library}, variant)`, nesta ordem:
1. `planScene` deu `map` ou `counter` → cena 2D;
2. 1ª oração da coluna Imagem cita animal ou objeto real (placa, pesquisador, navio, foto…) → foto; buscas = nome
científico, "Farol <ilha>" (se fala de farol), a ilha; nada achado → cena 2D de reserva;
3. `matchLibrary(coluna Imagem)` → cena 3D (`paramsFor` escolhe cada `select` pelas keywords das opções);
4. título 2D.
- `planShot3d(shot, ctx, index)` (estilo `"3d"`): cena `doc3d` por `matchLibrary` na coluna Imagem, depois na Imagem +
narração, senão a primeira da biblioteca; `params` por `paramsFor` + `variant = índice do trecho`. Cartão de foto
(`insetQueries`) só com `[foto: termos]` na coluna Imagem ou animal real (`ANIMAL`) na 1ª oração — aí busca os nomes
científicos do roteiro; barco, navio e personagem ficam na cena 3D, sem cartão. Biblioteca 3D vazia → erro pedindo
cena ao agente.
- `planScene(shot)`: ≥ 2 lugares conhecidos, ou 1 lugar + "mapa/litoral/km" → `map` com rota cidade → ilha e rótulo
"N km" (tirado do texto); número no texto na tela → `counter` (kicker = texto antes do número; rótulo completado
pela narração, ex.: "jararacas por hectare"); resto → `title`. "São Paulo" só vira marcador se o texto disser
cidade/capital ("litoral de São Paulo" é o estado).
- `MAP_PLACES` **tem de ficar igual** a `PRESETS["litoral-sp"].places` de `godot/scripts/doc/doc2d_canvas.gd` (a
Godot resolve lat/lon pelo nome).
- `renderGodotScene` grava o JSON (`kind` `doc2d`/`doc3d`, 1080×1920, 30 fps, duração da fala + pausa) e chama
`scripts/cli.ts render --config <json> --profile final` pelo `node_modules/tsx/dist/cli.mjs` (sem shell); o MP4 é
lido da linha `MP4: ...` da saída.
- Modelos 2D (`variant` muda o visual): `title` (3 layouts por `variant % 3` — centro, editorial à esquerda com
barra, embaixo com sublinhado; destaque brasa/ciano/violeta), `counter` (conta em pt-BR 1.500 / 0,0055 com anel que
fecha; `grid` opcional), `map` (voo: começa aberto, zoom 0,45 em `variant` par ou 0,62 em ímpar, desce até a rota em
1,6 s, a linha começa em 1,5 s e o destino pulsa; terra estendida 8° além dos limites; km pela haversine se faltar o
rótulo; "Mapa ilustrativo" no rodapé — a costa é aproximada).
### Fotos da internet (`lib/image-search.ts`)
- `searchCommons(q)`: API do Wikimedia Commons, sem chave, User-Agent genérico; `filetype:bitmap`, menor lado ≥ 900
px, descarta títulos com mapa/diagrama/logo/brasão/bandeira/gráfico; URL em 1600 px. `searchFirst(queries)` tenta
as buscas em ordem; `downloadImage` baixa.
- `applyInternetImage(ep, shot, queries, startPick, used, "main" | "inset")` (`lib/montage.ts`) pula imagem já usada
noutro trecho (`sourceUrl`; fotos principais e cartões juntos) e cria o asset `image` com crédito (autor), licença e
origem (página do Commons), que vão para a cartela de créditos. `"inset"` grava no cartão do trecho.
- Medido (17/11/2026, informado): "Bothrops insularis" → fotos reais da espécie (Butantan, Otavio Marques); "Ilha da
Queimada Grande" → farol e navio da Marinha; termo genérico ("aves migratórias") → lixo. Por isso as buscas usam
nomes do roteiro, nunca descrições genéricas.
### Biblioteca de cenas 3D (`godot/library/`)
- Cena = `godot/library/<id>/template.gd` (`extends Node3D`: `setup(cfg, viewport_size)`, `apply(t)`,
`state_signature()`) + `manifest.json` (`id`, `kind: "doc3d"`, `label`, `description`, `keywords`, `params` com
`type` `select`|`bool`|`number`|`text`, `default` e `options[{value, label, keywords}]`). Guia para agentes:
`doc/godot/cenas.md`.
- O painel lê sem banco (`lib/scene-library.ts`): `listLibrary()`, `matchLibrary(texto, lib)` (mais keywords
achadas), `paramsFor(cena, texto)`. Cena nova aparece sozinha no seletor, no formulário e na escolha automática.
- `island` ("Ilha costeira"): terreno FastNoiseLite com sementes fixas, 5.200 árvores em MultiMesh,
rochas, farol listrado com lanterna pulsando; mar por shader com `uniform scene_time` (determinístico), turquesa
perto da costa, plano de 16 km (horizonte sem emenda); ProceduralSky, ACES, névoa leve. Params `shot`
`orbit`|`approach`|`lighthouse`|`lowpass`, `time` `day`|`sunset`|`night` (céu escuro, lua azulada, farol forte),
`lighthouse` (bool); `variant` muda **só a câmera** (ângulo e sentido). Como cenário de outra cena: `embedded: true`
(sem câmera própria), `environment: false` (sem céu e luz), `sea_detail: true` (malha fina do mar perto da câmera);
métodos `height_at` (ruído) / `ground_at` (malha desenhada: apoio de pés e pedras) / `ground_normal`,
`sea_height(x, z, t)`, `set_sea_state(escala)`, `set_sea_focus(x, z)`, `rock_list()`, `lighthouse_position()`.
- `castaways` ("Náufragos no costão", caso real da Ilha das Cobras, 2019): `moment`
`arrival`|`sinking`|`swimming`|`waiting`|`rescue`|`boarding`|`departure` (keywords tiradas da coluna Imagem do
roteiro), `camera` `medium`|`close`|`wide`, `variant`. Peças na pasta: `shore.gd` (estende a ilha com laje de
costão), `actor.gd` (estende `person.gd`), `cast.gd` (elenco e barcos), `sky.gd` (céu por hora, mistura noite → dia),
`verify.gd` (determinismo e apoio: `Godot --headless --path godot --script res://library/castaways/verify.gd` →
`CASTAWAYS_OK 84 estados`). Feita pelo agente do painel: Claude (#7) e Codex (#8), cada um parou no limite de uso.
- **Kits** `godot/kits/` (não são cenas; o painel não lista): `person.gd` — pessoa low-poly com juntas `hips`, `spine`,
`chest`, `neck`, `head`, `shoulder|elbow|hip|knee_l/r`; `build({shirt, pants, skin, hair, shoes, vest, height,
sleeveless, shorts})`, `pose(action, t)` (`idle`, `walk`, `run`, `swim`, `sit`, `wave`, `kneel`, `lie`, `exhausted`),
`blend(a, b, t, k)`. `boat.gd` — lancha/pesqueiro ~8 m (casco SurfaceTool, cabine, mastro, luzes de navegação):
`build({hull, stripe, cabin, lights})`, `float_on(t, intensidade)`, `sink(0..1)`, `deck()` (convés). Uso, cena
dentro de outra e `.glb` por `GLTFDocument` em tempo de execução: `doc/godot/cenas.md`.
- Cena nova pelo painel: tarefa "Cena no Godot" do agente (seção "Agentes e modelos").
### Gerar o MP4 (`startMontageRender(id, { auto, replan })`)
- `auto: false` ("Só montar"): exige áudio atualizado e visual em todos os trechos (menos cartela); as cenas Godot
(2D e 3D) desatualizadas são renderizadas também neste modo.
- `auto: true` ("Gerar vídeo automático"): planeja com `planShot` os trechos sem visual (com `replan: true`, "Refazer
tudo do zero", também os `auto` e as cenas Godot antigas sem a marca; o que o admin escolheu fica); sem voz usa a
pt-BR padrão do serviço (`getStatus`); gera os áudios que faltam; renderiza as cenas Godot com `sceneKey` velha; monta.
- `regenerateShot(id, index, target)` (`POST .../montage/regenerate {index, target}`): `"visual"` (padrão) — cena Godot
→ `variant + 1` e re-render; foto da internet → próxima da busca (sem repetir as dos outros trechos); foto enviada →
busca; cartela e clipe → erro. `"inset"` → outra foto no cartão (busca do cartão, do `planShot3d` ou nomes
científicos; sem termos → pede `[foto: termos]`). `"remove-inset"` → tira o cartão.
- Uma montagem por vez. Progresso em memória: `montageJob(episodeId)` → `job: { renderId, progress }` no GET (não
sobrevive a reiniciar o painel). Grava em `renders` com `profile = 'documentary'`; saída
`output/documentary/<story>-<file_key>-<stamp>/<story>-<file_key>.mp4`, log `data/logs/renders/<id>.log`.
- FFmpeg em `lib/montage-ffmpeg.ts` (**sem banco**, testável sozinho: gotchas, item 99): `buildSegment`,
`buildCredits`, `concatSegments`. 1080×1920, 30 fps, H.264 CRF 20 + AAC 48 kHz estéreo.
- Foto horizontal (aspecto > 0,8): fundo = a própria foto desfocada (`boxblur=32`, brilho −0,12), foto a 118% da
largura (até 62% da altura), zoom de 8%, um pouco acima do meio. Foto vertical: cobre a tela com `zoompan`. Pares
aproximam, ímpares afastam. A entrada de áudio varia com o visual (`audioInput`). Vídeo: `-stream_loop -1` + crop.
- Texto na tela (y = 13%; na cartela, centro) e legenda (y = 74%) por `drawtext` com `textfile=` e
`expansion=none`; grafo em `-filter_complex_script`; cwd = pasta de saída (arquivos relativos). **`godot2d` não
recebe o texto na tela** (a cena já mostra); `godot3d` recebe; a legenda continua em todos. Texto na tela com
mais de 26 caracteres usa fonte 54 (senão 66); `; depois:` divide em partes sequenciais.
- Cartão de foto (`plan.inset`): foto a 62% da largura com borda branca de 12 px, topo a 21% da altura; entra em
0,3 s (fade de 0,35 s subindo 50 px) e sai 0,4 s antes do fim; crédito "Foto: autor" embaixo.
- Legenda = narração escrita em pedaços de até 30 caracteres, tempo proporcional; pedaço < 12 caracteres junta
ao anterior.
- Duração do trecho = fala real + `PAD_S` 0,35 s (último + `LAST_PAD_S` 0,9 s), não o tempo da tabela (gotchas,
item 102). Cartela final de 3,5 s (`CREDITS_S`) com créditos das imagens e domínios das fontes (só se houver).
Junção com `-c copy`.
- Rotas: `GET|PATCH /api/episodes/[id]/montage` (GET traz também `templates` e `job`), `POST .../montage/audio`
(`{index}`), `POST .../montage/scene` (`{index}`), `POST .../montage/regenerate` (`{index, target?}`),
`POST .../montage/upload` (multipart), `POST .../montage/render` (`{auto, replan}`) e
`DELETE .../montage/render?render=<id>`. `/api/files` serve também `.webm`, `.mov` e `.mkv`.
- **Provado de ponta a ponta (17/11/2026, "Tudo em 3D"):** agente `story` (Codex, #6) pesquisou e escreveu
`stories/naufragos-na-ilha-das-cobras/ep01.md` com fontes; agentes `godot` #7 (Claude) e #8 (Codex) fizeram
`castaways`; "Refazer tudo do zero" planejou 11 trechos (1–9 `castaways` nos momentos certos, 10–11 `island` orbit
com cartão da jararaca, fotos do Commons diferentes). MP4 em `output/documentary/naufragos-na-ilha-das-cobras-ep01-*/`:
101,7 s, 1080×1920, h264 + aac (ffprobe). Cenas finais 1080×1920 de 2,8–12,3 s em 9,8–89,7 s cada (`report.json`);
total ~9 min (informado). Quadros conferidos pelo agente que montou (não refeito aqui).
## Agentes e modelos (`lib/agents.ts`, `lib/prompts.ts`)
- `buildPrompt({ kind, provider, ... })` inclui `writingRules(provider, story.kind)` (guias em
`GUIDE_COMMON`/`GUIDE_BY_KIND`): no **Claude** manda delegar ao subagente `cenaforge-story-writer`
informando o formato (o subagente é uma casca que lê `doc/roteiro/`; sem WebSearch, fato sem fonte fica
"a confirmar"); no **Codex** manda ler os guias e escrever sozinho, sem usar `.claude/agents/` (mesma
regra no `AGENTS.md`).
- Lista de modelos = `models()` (não há mais constante fixa):
- Codex: lê `models_cache.json` de `$CODEX_HOME` (padrão `~/.codex`), que a CLI do Codex atualiza
sozinha; filtra `visibility === "list"`, ordena por `priority`. Primeira opção "Padrão da CLI (…)"
= `model = "..."` do `config.toml`. O id vai em `codex exec -m <slug>`. Em 17/11/2026: 8 modelos
(gpt-6.1-sol, gpt-6-astra, gpt-6.1-terra, gpt-6-sol, gpt-6-luna, gpt-5.6-sol/terra/luna).
- Claude: `claude-fable-5-2`, `claude-opus-5-5`, `claude-sonnet-5-5`, `claude-haiku-5-5` (via
`claude --model`); apelidos `opus`/`sonnet`/`haiku` ainda aceitos ao retomar execuções antigas.
- Padrão: `DEFAULT_MODEL` só vale no Claude (`scene` e `branches` = `claude-sonnet-5-5`; demais = padrão
da CLI); no Codex, sempre o do `config.toml`. Provedor preferido por tarefa: `PREFERRED_PROVIDER`
(story/script/branches = Codex; `godot` = Claude).
- Tarefa `godot` ("Cena no Godot", `AgentKind` em `lib/types.ts`): o prompt (`prompts.ts`) manda seguir
`doc/godot/cenas.md`, reaproveitar a biblioteca (`godot/library/island/` de referência), renderizar e olhar os
quadros, e não mexer em `godot/scripts/`, `scripts/` nem `panel/`. O console (`/agent`) aceita `?prompt=` como
pedido inicial (link "Peça uma nova ao agente" do `SceneEditor`).
- "Nova história com IA" (`components/story-composer.tsx`) tem seletor de modelo (campo `model`, lido
em `createStoryFromTextAction`, `app/actions.ts`). Por script: `POST /api/stories {text, title?, kind?, provider?,
model?}` (`app/api/stories/route.ts`; `kind` padrão `documentary`, texto 20–20.000 caracteres) cria a história + ep01
e dispara o agente `story` → `{storyId, episodeId, runId}` (cabeçalho `Origin`: gotchas, item 125).
- O agente roda dentro do processo do painel: reiniciar o `pnpm panel` o mata (gotchas, item 131). Limite de uso do
Claude/Codex para a tarefa no meio: continue no outro provedor com o contexto (item 132).
- Prompt do Codex manda ler texto no PowerShell com `Get-Content -Raw -Encoding UTF8` (gotchas, item 98).
### Mensagem com o agente rodando
- Console (`components/agent-console.tsx`): durante a execução a caixa de pedido fica liberada com dois botões —
**"Corrigir agora"** (também Ctrl+Enter: interrompe e retoma a mesma sessão com a correção) e **"Enviar ao
terminar"** (fila; envia quando o agente fechar). Uma mensagem por vez: a nova substitui a da fila.
- Rota `POST /api/agent/runs/[id]/messages` com `{text, mode: "now"|"queue"}` → `sendFollowUp(id, text, mode)`.
`ActiveRun` tem `emit`, `followUp` e `progressed` (vira `true` no 1º evento que não seja `system`, `stderr`
nem `error`). "now" exige `session_id` **e** `progressed` (senão recusa: gotchas, item 97); marca a execução
`cancelled` (error "interrompida para correção") e chama `killTree`.
- No `close`, havendo `followUp`, `startRun({..., resumeRunId: id})` roda **antes** de avisar os ouvintes, então o
"end" do SSE já leva `followUpRunId` (`followUpRunOf(id)`, `resume_of = id`) e o console troca para a
continuação, mostrando o texto do usuário como pedido. Falhou a continuação (executor ocupado, sem
`session_id`) → evento de erro pedindo para reenviar.
- A rota de events só manda `followUpRunId` no fim **ao vivo** (`finish(true)`): abrir uma execução antiga do
histórico não pula para a continuação.
## História interativa = árvore de vertentes
| Conceito | Onde |
|---|---|
| Vertentes por episódio | `stories.branch_count` (1–4; linear = 1; interativa ≥ 2, escolhido na criação, campo `branchCount` de `createStory` em `stories.ts`) |
| Arquivos do episódio | `file_key` (`ep01`, `ep02-b`) → `stories/<id>/<file_key>.md`, `stories/<id>/<file_key>.choices.json`, `config/<id>-<file_key>.json` |
| Estado do episódio | `status` `main` / `candidate` / `discarded`; `branch_label`; `branches_status` `none`/`queued`/`running`/`ready`/`error` |
| Votação A–D | `decisions.ts`: `parseVote(text, letras)`, `tally`, `leader()`, `closeDecision`; votos em `votes_json` |
| Gerar vertentes | `branches.ts`: `prepareBranches` cria as candidatas e **uma** execução de agente (tarefa `branches`; Codex preferido — modelo em "Agentes e modelos") que escreve roteiro, cena e `.choices.json` de cada vertente |
| Fila | um agente por vez; o próximo `queued` é puxado em `onAgentRunClosed` |
| Fechar votação | `closeDecision`: vencedora vira `main`, irmãs `discarded`, e o próximo nível é preparado sozinho (`prepareBranches(..., { auto: true })`) |
| Árvore na tela | `flow.ts` (`storyFlow`, layout em árvore próprio) + `components/story-flow.tsx` (`@xyflow/react` 13.0.1); aba Fluxo da história |
Regra: só o **próximo nível** é gerado — nunca a árvore inteira de uma vez.
Limitação: o overlay da Godot só tem `choiceA`/`choiceB` (`scene_config.gd`); C/D existem só no
`.choices.json` e no painel. Cores das opções: `CHOICE_STYLE` em `components/ui.tsx`, tokens
`--color-option-c`/`--color-option-d` em `app/globals.css`.
## Canais de publicação e dashboard
- Canal de publicação = tabela `accounts` (no código continua "account"; na UI, "Canal de publicação", rota
`/accounts`, `components/account-manager.tsx`): várias histórias ativas por canal, uma história em vários canais.
Redes conectadas de verdade (API oficial ou sessão logada) — tudo de publicação em [publishing.md](publishing.md).
- Dashboard (`metrics.ts`, `/dashboard`, primeiro item do menu; `metrics-view.tsx`,
`dashboard-controls.tsx`): totais, por rede/conta/história/episódio, melhores e piores.
Métricas continuam **simuladas** (`simulated = 1`; `simulateMetrics` / `clearSimulated`); publicação real grava
`publications` com `simulated = 0`. Não apresente números simulados como reais.
- Fontes do Clipador (no código `channels`): card "Fontes de corte" em `account-manager.tsx`, rotas
`POST /api/accounts/<id>/channels` (ligar) e `DELETE /api/accounts/<id>/channels/<channelId>` (encerrar). Cortes
das fontes ligadas entram na fila de publicação do canal. Veja [clipper.md](clipper.md).
- Página da história: abas Episódios | Fluxo | Contas.
## Excluir história
- `deleteStory(id)` (`lib/stories.ts`) ← `deleteStoryAction` (`app/actions.ts`, campo `storyId`, redireciona
para "/") ← `components/delete-story-button.tsx` (`confirmSubmit` com `tone: "danger"`; erro no modo `compact`
por `showAlert`). Aparece como ícone (`compact`) no canto
inferior direito do cartão em "Biblioteca · Em produção" (`app/page.tsx`, **fora** do `<Link>`: botão dentro de
`<a>` é inválido) e como "Excluir" no cabeçalho de `app/stories/[storyId]/page.tsx`.
- Recusa se houver `agent_runs` `running` da história ou `renders` `running` de algum episódio dela.
- **Arquivos primeiro, banco depois; nada é apagado de vez:** `stories/<id>/` (com `.choices.json` e
`assets/`) → `data/trash/<id>-<timestamp>/stories/`; `config/<id>-<file_key>.json` dos episódios do banco →
`.../config/`. Recuperar = mover de volta à mão (não há botão). MP4s em `output/` não são movidos.
- Depois, numa transação: apaga `assets` com `scope='story'` (sem isso ficariam órfãos, pois
`assets.story_id` é `SET NULL`) e a linha de `stories`. CASCADE leva episódios, comentários, decisões,
publicações/métricas e `account_stories`; `agent_runs.story_id` e `renders.episode_id` viram NULL (histórico fica).
- Ainda **não existe** exclusão de asset da biblioteca (`assets/library/`).
## Página `/clipper` (Clipador)
- `clipper-cut-settings.tsx`: modal "Configuração do corte" em cinco abas — Formato e duração (com a seção
"Qualidade da gravação" e o disco por hora de cada opção, de `captureQualities`) · Câmera e layout · Legenda (com
seletor de fonte) · Gancho (estilo, cores, fonte, animação de entrada, "Ver a entrada") · Crédito — com a prévia ao
lado mudando de proporção (`frames` da rota de settings). Durações mostradas como "1:30 · 90 s", com o padrão lido
de `defaults`. Desenhar o retângulo da câmera sobre o quadro (`…/frame`),
prévia (`…/preview`), achar webcam (`…/detect-cam`), salvar na sessão ou como padrão do canal.
- `clipper-client.ts`: tipo `Aspect`, `format` em `CutSettings`, `aspect?` em `Clip`, `aspectOf()` (ausente =
vertical) e `withFormat()` (completa a resposta de um serviço antigo sem `format`). Na fila (`clipper-queue.tsx`)
o corte horizontal aparece em 16:9.
- Aba Sessões (`clipper-sessions.tsx`; cabeçalho em `clipper-studio.tsx`): cartão com cabeçalho (tempo gravado,
"gravando em L×A · fps" de `capture` e ações), frase de saúde (`sessionHealth()`), painel "o que está acontecendo" (resumo da IA + jogo), quatro blocos
(Chat, Transcrição, IA assistiu, Cortes) e barra de ferramentas. **Altura fixa por desenho**: nada pode pular na
atualização automática. "Retomar gravação" aparece em toda live que não está gravando (botão principal só em
`interrupted`). Cartão na grade leva `[contain:inline-size]` (gotchas, item 91).
- **Relógio da gravação** (`RecordingClock`): o tempo gravado corre segundo a segundo entre as consultas
(`setInterval` de `CLOCK_TICK_MS` 250 ms por cartão, só gravando e com a aba visível); ressincroniza com o
`durationS` real sem voltar. Passou `CLOCK_MAX_AHEAD_S` (45 s) além do último `durationS`: para e mostra
"aguardando o bloco" com o selo em alerta (ao voltar à aba, espera 6 s antes de acusar).
- **Cadência do resumo** (`SummaryCadence`): ao lado de "Agora na live", "atualiza a cada 3 min · próximo em m:ss";
atrasou, "gerando o próximo resumo…". O intervalo vem de `/status` → `judge.options.scanIntervalS`
(`useScanInterval`; reserva 180 = `OPTION_DEFAULTS` de `intel.py`). Existe porque o dono achou que o resumo
travava (gotchas, item 115).
- `clipper-games.tsx`: aba Jogos e emotes. O card do jogo tem selo de iniciais (primeira + última palavra, cor
por `hueOf`) e os botões "Conversar com a IA", "Editar" e "Pesquisar de novo". Cada seção é um cartão com
barra colorida, contador e "Pedir à IA", que abre o chat inline `AiChat` (balões, atalhos de pedido por seção,
indicador de digitação, "+N itens novos / −N removidos"). Item novo fica verde com selo "novo". Gírias viram
chips, e Fontes e "Memória da IA" ficam recolhidas. A aba também mostra os emotes do canal com usos e peso.
Rotas e regras em [clipper.md](clipper.md#perfil-do-jogo-aba-jogos).
- `clipper-queue.tsx`: cartão do corte mostra a análise do juiz e recua/avança o início (`START_STEPS`
−30/−10/−5/−2/+2 s). `clipper-judge.tsx`: modelos do editor e do analista, varredura, visão, câmera.
- `clipper-queue.tsx` também tem o botão "Editar" (ou "Continuar edição" se `edit.origin === "user"`) que abre o
editor.
- **Apagar na fila** (`clipper-queue.tsx`; regras do serviço em [clipper.md](clipper.md#apagar-cortes-clip_deletepy)):
"Apagar" em cada cartão, com confirmação no próprio cartão. Seleção **discreta** (o dono reprovou uma barra presa
no topo e pediu "bem sutil, no cantinho"; gotchas, item 116): no canto da linha das abas, "Selecionar" e o menu
"⋯" ("Apagar todos desta aba (N)", modal com a contagem e aviso do filtro de sessão); a caixa de cada cartão só
aparece no hover, no foco ou no modo de seleção; com o modo ligado, a pílula flutuante `SelectionPill` no canto de
baixo ("N selecionados · Selecionar todos · Apagar · ✕", vermelho só no hover). Esc sai do modo. Nada disso ocupa
espaço na página. Manda os ids mostrados em lotes de `CLIP_DELETE_MAX` por `POST clips/delete`; resultado em
aviso fixo (`deleteSummary`). Estados que não se apagam: `UNDELETABLE_CLIP` em `clipper-client.ts`.
- Toda rota nova do serviço precisa entrar na regex `ALLOWED` de `panel/src/lib/clipper.ts` (e, se for lenta, no
timeout por rota do mesmo arquivo; se só alguns métodos valem, em `METHODS`). Detalhes em [clipper.md](clipper.md).
## Editor de cortes
Página `/clipper/edit/[clipId]` (`panel/src/app/clipper/edit/[clipId]/page.tsx`). Projeto, rotas e render em
[clipper.md](clipper.md#editor-de-cortes-clippereditid); fonte completa em `clipper/README.md`.
- **Tela cheia sem mexer no layout raiz:** o componente cobre o rail com `nle fixed inset-0 z-[70]` e trava a rolagem
do documento só nessa página. Tudo cabe em 100vh; cada painel rola sozinho.
- **Desenho de editor de vídeo (NLE):** cores só pelos tokens `--color-nle-*` (classes `bg-nle-panel`,
`text-nle-dim`…) e pelo bloco `.nle` de `panel/src/app/globals.css`; peças prontas em `clip-editor-ui.tsx`. Não use
os tokens do resto do painel dentro do editor.
- Disposição: cabeçalho (Fila, desfazer/refazer, "Projeto da IA", descartar, título e origem, estado do salvamento,
**Salvar projeto**, botões que minimizam Camadas, Transcrição/Chat e Propriedades, "IA sugere", atalhos, status,
Exportar) · Camadas |
Transcrição/Chat | monitor "Fonte · Programa" | Propriedades · timeline na largura toda + medidor de áudio. Em
tela estreita os painéis da esquerda viram abas de um painel só.
- Trilhas da timeline, uma por camada: C1 legenda, V3 textos, V2 zoom, INS inserções, ENQ enquadramento (keyframes
do reenquadramento), CAM câmera (layout de cada trecho), V1 vídeo (miniaturas), A1 áudio da live (forma de onda;
"MUDO" no trecho mudo), A2 narração, A3 música e efeitos, CH chat.
- **Programa no formato do corte:** tamanho vem de `frames` (`frameOf`, `FALLBACK_FRAMES`; sem `W`/`H` fixos), 16:9 no
horizontal; "Formato" do corte em Propriedades › Vídeo. Aviso quando a duração sai do mínimo/máximo (a edição é livre).
- **Fontes na prévia** (`clip-editor-fonts.tsx`): as empacotadas vêm por `fetch` + `FontFace` de `/api/files`
(`fontFiles` da rota de settings); a prévia só desenha depois de carregadas. Tamanho do texto pelas métricas do
arquivo, como o libass: px = tamanho ASS × unitsPerEm / (usWinAscent + usWinDescent), passo de linha = tamanho.
(Antes a prévia saía ~40 % maior que o render.) `FontPicker` = seletor com amostra.
- **ENQ e INS** (`clip-editor-keyframes.tsx`): keyframes ◆ suave / ◇ linear / ■ segurar; arrastar, duplo clique troca
a curva, Delete, Ctrl+C/V, `[` `]` pulam de key. Na Fonte, a janela do reenquadramento tem proporção travada e
auto-key no playhead; o recorte da inserção é desenhado na Fonte e posicionado no Programa, com keyframes de
posição/tamanho, aparência e subir/descer na ordem. Interpolação em `clip-editor-model.ts` (`easeAt`,
`interpolate`, `reframeAt`, `insetAt`), alinhada a `clipper/app/reframe.py`: mudou uma, mude a outra.
- **Câmera editável na Fonte** (`clip-editor-source.tsx`, geometria em `rect-geometry.ts`, compartilhada com o modal):
alças, mover, desenhar numa área vazia, setas (Shift = tamanho). Propriedades "Câmera e layout deste trecho" separa
"Layout · só este trecho" de "Posição da câmera · corte inteiro"; "Usar esta câmera nos próximos cortes da sessão"
grava na sessão (os cortes existentes não mudam). Mudança de layout do corte passa por `editLayout(p, fn)`.
- Fluxos secundários abrem em modal (`ModalKind` = `export` | `ai` | `narration` | `keys`), não em aba.
| Arquivo (`panel/src/components/`) | Papel |
|---|---|
| `clip-editor.tsx` | estado, atalhos, autosave, cabeçalho, disposição dos painéis, som da prévia e medidor (`AudioMeters`) |
| `clip-editor-model.ts` | tipos (`EditProject`, `EditCut`, `ChatOverlay`/`CHAT_DEFAULT`, `InsetOverlay`) e operações puras do projeto (`removeRange`, `keepRange`, `resolvedMode`, `editLayout`, `frameOf`, interpolação de keys, `bannerLayout`); `useHistory` (updater puro: gotchas, item 109) |
| `clip-editor-fonts.tsx` | fontes empacotadas no navegador (`loadPackagedFonts`, `usePackagedFonts`), métricas (`fontMetrics`, `canvasFont`) e `FontPicker` |
| `clip-editor-keyframes.tsx` | trilhas/propriedades ENQ e INS (`ReframeLayer`, `ReframeKeyProps`, `InsetsLayer`, `InsetProps`, `moveInsetOrder`, `KeyGlyph`) |
| `clip-editor-source.tsx` · `rect-geometry.ts` | monitor Fonte (`SourceMonitor`: câmera, jogo, janela do reenquadramento, recorte da inserção) · geometria de retângulo 0–1 (alças, mover, setas), também usada pelo modal do corte |
| `clip-editor-ui.tsx` | peças do desenho NLE: ícones, `IconBtn`, `Btn`, `Modal` (`<dialog>` nativo), `PropSection`/`PropRow`, `Scrub`, `Keycap` |
| `clip-editor-layers.tsx` | painel Camadas: selecionar, ligar/desligar e criar no playhead |
| `clip-editor-timeline.tsx` | régua, trilhas, lâmina, ímã e todos os arrastes (`DRAG_START_PX` = 4) |
| `clip-editor-preview.tsx` | monitor Programa (canvas no formato do corte sobre o proxy, camadas arrastáveis, tarja, inserções e reenquadramento) |
| `clip-editor-transcript.tsx` | transcrição e chat: Tirar, Manter, Editar (troca o texto e reparte o tempo), Ocultar/Mostrar (só da legenda), Ênfase |
| `clip-editor-inspector.tsx` | Propriedades da seleção e os modais (`ExportModal`, `AiModal`, `NarrationModal`, `ShortcutsModal` com a lista `KEYS`) |
- Gestos (tabela "Mexer com a mão" de `clipper/README.md`): arrastar o corpo move palavra/grupo, texto, zoom,
narração e trecho (o trecho desliza sobre a gravação); bordas aparam; no Programa, arrastar muda `x`/`y` de texto,
gancho e chat e a altura da legenda; no Fonte, o alternador Câmera / Área do jogo (`SourceTargetToggle`) escolhe o
retângulo, e mover/alças/desenhar grava `settings.layout.cam`/`game` só daquele corte. O arraste de mover só começa depois de 4 px.
- Autosave 1,2 s com `rev` (409 = outro salvou); "Salvar projeto"/Ctrl+S salva na hora. Desfazer por instantâneos.
- Atalhos (fonte: `KEYS`; atalho novo entra lá e no `onKey` de `clip-editor.tsx`): Espaço tocar/pausar, K pausar,
J/L ±2 s, ←/→ um quadro (Shift = 1 s), Home/End, V seleção, C lâmina, S ou Ctrl+K dividir no playhead,
Ctrl+Shift+clique dividir onde clicar, Q/W começar/terminar o trecho no playhead, Delete, N ímã, Ctrl+roda zoom da
timeline, Ctrl+Z / Ctrl+Shift+Z / Ctrl+Y, Ctrl+S salvar, Ctrl+E exportar, `[`/`]` keyframe anterior/seguinte,
Ctrl+C/Ctrl+V copiar/colar keyframe no playhead, Esc, ? atalhos.
- A prévia do navegador segue o render na legenda (`captionBlocks`, porte de `subtitles.py`) e no recorte de câmera/jogo
(`ffmpegCropFill`, tamanho de `session.capture`); o resto é aproximado e a exata é "Prévia real" (`preview-render`,
FFmpeg). Porte e regra de manutenção em [clipper.md](clipper.md#editor-de-cortes-clippereditid); diferença de 1–3 px:
gotchas, item 117.
- Teste automático da UI: armadilhas 85 (camadas do canvas) e 86 (não gravar no corte real) em [gotchas.md](gotchas.md).
## Evidência e lacunas (16/11/2026)
Teste ponta a ponta numa cópia do banco real (`CENAFORGE_ROOT` temporário, PATH sem CLIs de
agente), informado pelo coordenador: 10 grupos de casos passando (migração preservou 1 história,
1 episódio, 5 comentários; votos `{A:1,B:0,C:2}` → C; fluxo com 7 nós; contas; 14 publicações e
42 fotografias simuladas); typecheck limpo; `/dashboard`, `/accounts`, `?tab=flow` e APIs → 200.
Não verificado: "Preparar vertentes" com agente real; árvore no navegador com dados reais (só
com dados injetados); opções C/D no vídeo (o overlay não as desenha).
Formato documental e modelos (17/11/2026, informado pelo coordenador): `tsc --noEmit` do painel OK;
v4 aplicada numa cópia do banco v3 (stories 2→2, episodes 2→2, agent_runs 3→3, `foreign_key_check`
vazio; CHECK rejeita `kind` inválido e aceita `documentary`); `codexModels()` contra o `~/.codex` real →
9 opções; `claude -p --model claude-fable-5-2` e `claude-haiku-5-5` → "ok". Conferido pela skill: o
`data/cenaforge.db` real ainda está em `user_version` 3 (painel não reiniciado). Não verificado: história
documental criada de ponta a ponta pelo painel (Claude ou Codex) e render de um vídeo documental.
Guias `doc/roteiro/` e exclusão de história (17/11/2026, informado pelo coordenador): `tsc --noEmit` do painel OK
(reconferido pela skill); numa cópia do banco v4, excluir uma história → stories 2→1, episodes 2→1, agent_runs 3→3
(`story_id` da execução virou NULL), `foreign_key_check` vazio. Não verificado: o clique na UI (painel não
reiniciado), o `renameSync` para `data/trash/` no Windows com arquivo aberto e um roteiro real escrito pelos
guias novos (Claude ou Codex). Pela leitura do código: se um `renameSync` falhar no meio, a exceção sobe antes da
transação — a história continua no banco, mas o que já foi movido está na lixeira (devolver à mão).
Mensagem durante a execução e termos episódio × vídeo (17/11/2026, informado pelo coordenador): `tsc --noEmit` do
painel OK (reconferido pela skill); retomada do Codex 0.169 testada à parte com `gpt-6-luna`, sandbox read-only
(gotchas, item 97). Não verificado: o clique na UI (painel não reiniciado) e a retomada do Claude depois de
interrompido (o `--resume` já existia).
Leitor de roteiro (17/11/2026): `parseScript` no `stories/a-ilha-da-queimada-grande-conhecida-como/ep01.md` real →
9 trechos, 176 palavras (≈ 70 s, alvo 72 s), papéis hook/shots/cover/sources/needs (reconferido pela skill via `tsx`);
`tsc --noEmit` do painel e capturas do Chrome headless das três páginas: informados pelo coordenador.
Montagem documental (17/11/2026): `tsc --noEmit` do painel sem erros (reconferido pela skill). Informado pelo
coordenador: `numberToWords` 16/16 casos; teste isolado do `montage-ffmpeg.ts` com 3 trechos reais e
`pt-br-antonio` (Edge) → falas 6,82 / 13,16 / 13,37 s, cada segmento montado em 0,8–1,3 s, `final.mp4` de 38,48 s
(= falas + pausas + créditos, pelo ffprobe), h264 1080×1920 30 fps + aac 48 kHz estéreo, quadros conferidos (zoom,
texto, legenda, cartela, créditos); no painel ao vivo, GET da montagem do episódio 3 → 9 trechos com texto falado por
extenso, áudio do trecho 1 gerado em 3 s. Conferido pela skill: `ep01.montage.json` da Ilha da Queimada Grande com
`pt-br-antonio`, `durationMs` 4080. Não verificado: "Montar vídeo" completo pelo painel (faltam imagens) e
cancelamento (`DELETE .../montage/render`).
Cenas 2D e vídeo automático (17/11/2026). Conferido pela skill: os 9 `report.json` das cenas do episódio da Ilha
(`output/runs/20261117-0422*-ep01-t0N-final`) com `status: success`, 7,4–21,5 s cada; prévias 540×960 de mapa,
contador e título em 2,7–4,3 s (`*-teste-*-preview`, configs em `data/tmp/`). Informado: `planScene` nos 9 trechos
reais → títulos, mapa (Itanhaém → ilha, 35 km) e 2 contadores. Não verificado: cancelamento no meio de uma cena;
`godot/tests/` não tem caso de `doc2d` nem de `doc3d`.
Biblioteca 3D, fotos do Commons e "Gerar de novo" (17/11/2026). Conferido pela skill: com os nomes atuais
(`doc.tscn`, `godot/scripts/doc/`), 13 prévias `teste-ilha-*` (4 tomadas × 3 iterações + 1) com `status: success`,
540×960 × 5 s em 9,4–14,3 s no total (Godot 9–13 s); cena da ilha em final 1080×1920 de 9,1 s em 42,9 s (Godot 39,1 s;
`...-ep01-t07-final` das 04:46); `teste-inexistente` (`campo-futebol`) falha no `godotValidate` com "não existe na
biblioteca (godot/library/). Disponíveis: ["island"]"; prévias de mapa, contador e título v1/v2 em 2,9–3,9 s;
dois MP4 de `ep01` (04:46 e 04:48) h264 1080×1920 + aac, 88,33 s (ffprobe); `pnpm test` → 38 passaram;
`npx tsc --noEmit -p panel` → exit 0; `ep01.montage.json` com fotos do Commons nos trechos 1, 3, 4, 8 e 9 (licenças
CC BY, BY-SA e CC0 registradas), mapa, 2 contadores e `island`, todos `auto: true`. Informado: no painel ao vivo, "Refazer tudo do zero" no episódio 3 → fotos do
Commons diferentes nos trechos 1, 3, 4 e 9 (jararaca) e 8 (ilha + navio), mapa, 2 contadores e o farol 3D ao
entardecer, MP4 em 1 min 44 s; quadros e captura da UI conferidos. Não verificado: cena 3D criada pelo agente do painel
(execução #5, campo de futebol, em andamento), "Gerar de novo" de foto enviada e licença das fotos do Commons uma a uma.
Modal de confirmação (17/11/2026): `tsc --noEmit` do painel sem erros e nenhum `confirm(`/`alert(` nativo em
`panel/src/` (reconferidos pela skill; `askConfirm`/`showAlert`/`confirmSubmit` em 15 componentes). Informado pelo
coordenador: no navegador (http://localhost:4500/) o modal abre com título e descrição acessíveis, Esc fecha sem
excluir e Confirmar reenvia o formulário com o mesmo submitter (2º submit com `data-confirmed="1"`). Não verificado:
cada uma das 25 chamadas trocadas, uma a uma, na UI.
Editor de cortes com tarja, fontes, Programa 16:9, ENQ/INS e câmera na Fonte (17/11/2026): `npx tsc --noEmit -p panel`
→ exit 0 (reconferido pela skill). Informado: prévia da tarja a ≤ ~2 px do render; interpolação do painel ×
`reframe.py` em 41 conferências; testes de UI por CDP com as escritas interceptadas (gotchas, item 86). Render real
de um projeto do editor com enquadramento e inserção comparado com a prévia: ver o lote abaixo.
Apagar na fila, relógio da sessão e prévia igual ao render (17/11/2026): `npx tsc --noEmit -p panel` → exit 0
(reconferido pela skill). Informado pelo coordenador: porte da legenda em 22 conferências contra o Python; corte 61
montado no editor e renderizado pelo serviço com enquadramento, inserção e legenda iguais à prévia em
2/3,5/5/6,5/8 s. Não verificado: apagar pela UI contra o serviço real; relógio com movimento reduzido, aba escondida
e larguras de 1024/1280; a faixa do topo de `clipper-studio.tsx` ainda usa o `durationS` real.
@@ -0,0 +1,212 @@
# Publicação em YouTube, TikTok e Instagram (Publicador + despachante do painel)
Fonte completa: `doc/publicacao/PLANO.md` (contrato HTTP do Publicador §3, banco §4, despachante §5, telas §6) e
`doc/publicacao/PESQUISA.md` (fatos das plataformas, datados de 17/11/2026, reverificar a cada 3 meses). Instalação,
apps das redes e regras do modo sessão: `publisher/README.md`. Aqui só o que um agente precisa para agir.
## Quem faz o quê
```
Painel (4500) = cérebro ──► Publicador (4530) = executor ──► YouTube / TikTok / Instagram
canais, regras, fila cofre DPAPI, OAuth, perfis de API oficial OU Chrome/Edge via CDP (4540–4549)
publish_jobs, laço 20 s navegador, jobs (um por vez)
└──► Clipador (4520): lê cortes ready/approved (GET /v1/clips?channel=&status=&ids=), aprova e marca published
```
- **Despachante**: `panel/src/instrumentation.ts` → `startDispatcher` (`lib/dispatcher.ts`, `TICK_INTERVAL_MS` 20 s,
guarda em `globalThis` contra laço duplo no HMR) → `dispatcherTick` (`lib/publishing.ts`, que ao carregar troca
`dispatcherState().tick` pela versão nova: sem isso o laço usa as regras antigas, gotchas 141). **Só publica com o
`pnpm panel` aberto** (o painel é do usuário: não inicie nem encerre).
- **Publicador** (`publisher/`, Python 3.12 FastAPI): não conhece canal, história nem corte; recebe arquivo +
metadados + `profileId` (`<accountId>--<platform>`). Toda rota exige `X-Service-Key` (`PUBLISHER_SERVICE_KEY` em
`publisher/.env`), exceto `GET /health` e `GET /oauth/callback/{platform}` (validada por `state`). Dados em
`data/publisher/` (`publisher.db`, `vault.bin` DPAPI, `browser/<profileId>/`, `logs/` com capturas das falhas).
- Subir: `pnpm dev` (sobe depois do Clipador; sem `publisher/.venv` ou chave, pula com aviso). Instalar: `setup.bat`
(passo 6b2 do `scripts/setup.ps1`). Testes: `pnpm test:publisher` (pytest, sem rede nem navegador) e
`pnpm --filter cenaforge-panel test:panel` (node:test via tsx em `panel/src/lib/*.test.ts`, banco temporário por
`CENAFORGE_ROOT`). Typecheck do painel: `pnpm --filter cenaforge-panel typecheck`.
## Onde mexer
| Mudança | Arquivo(s) |
|---|---|
| Contrato HTTP, fila, cofre, OAuth | `publisher/app/` (`main.py` rotas, `service.py` regras, `worker.py` fila, `vault.py`, `db.py` (v2: `jobs.client_ref` UNIQUE), `paths.py` (`file`/`cover` só de `output/`, `stories/`, `assets/`; `data/` recusado), `acl.py` (ACL de `data/publisher` só para o usuário), `config.py`) |
| API oficial de uma rede | `publisher/app/platforms/{youtube,tiktok,instagram}_api.py` |
| Modo sessão (navegador) | `publisher/app/platforms/session/` (`browser.py` abre Chrome/Edge normal com `--user-data-dir` e `--remote-debugging-port`, confere a porta pelo `DevToolsActivePort` do perfil ou, se o Chrome 157+ não o gravar (porta fixa), pela marca `CenaForgeWindow.json` + PID que escuta (`owns_port`, `listener_pid`; gotchas 137), fecha a janela (`IDLE_CLOSE_S`/`LOGIN_IDLE_CLOSE_S`); `runner.py` (`_with_page` conecta com `connect_over_cdp(..., is_local=True)`: sem isso arquivo > 50 MB é recusado, gotchas 139; `browser_error_text(detail)` traduz o `PlaywrightError` em frase específica (clique com timeout, timeout, arquivo > 50 MB, janela fechada) ou, no resto, "O navegador travou ou mudou de página"; o "Detalhe" técnico vem depois); `common.py`: `step_pause`, `fill_text`, `click_through`, `dismiss_tips`, `TIP_BUTTONS`, `screenshot`, `prune_screenshots`); seletores no dicionário `SELECTORS` de `youtube_studio.py`, `tiktok_studio.py`, `instagram_web.py` |
| Cliente do Publicador no painel | `panel/src/lib/publisher.ts` |
| Regras puras (horário bom, limite, ações do job, sincronização de cortes, leitura do resultado, reencaixe, idempotência) | `panel/src/lib/publishing-rules.ts` (`placeJob`, `nextFreeSlot`, `planClipSync`, `readPublisherJob`, `jobActions`, `aiGeneratedFor`, `tagsFromCaption`, `needsReflow`/`STALE_AFTER_MS`, `clientRefFor`, `mayBeLive`, `parseVideoUrl`) + `publishing-rules.test.ts` |
| Fila, aprovação, envio, episódio | `panel/src/lib/publishing.ts` (`approveJob`, `placeApproved`, `retryJob`, `sendDue`, `promoteDue`, `pollPublishing`, `finishFromPublisher`, `markPublished`) + `publishing-db.test.ts` |
| Pausar tudo, horários bons, fuso | `panel/src/lib/settings.ts` (tabela `app_settings`) |
| Banco | `panel/src/lib/db.ts`: **v5** (`account_networks` reconstruída sem `mock`, `publish_jobs`, `publications` com `clip_id`/`job_id`, `app_settings`, `clip_auto_approvals`, colunas novas em `accounts` e `episodes`), **v6** (`publish_jobs` reconstruída: `schedule_source` `auto`/`manual`/`now`, `cancel_reason` aceita `unlinked`) e **v7** (`publish_jobs.origin` `link`/`manual`, padrão `link`) |
| "Publicar" no cartão do corte (sem fonte ligada) | UI `panel/src/components/clip-publish.tsx` (`ClipPublishButton` + diálogo; usado em `clipper-queue.tsx`, em `approved` e, como "Publicar em outra rede", em `published`; `useClipPublishing().reload()`); cliente `publishClip` em `publishing-client.ts`; rota `POST /api/publishing/clips/[id]` (`app/api/publishing/clips/[id]/route.ts`); servidor `publishClip` em `publishing.ts` |
| Guarda da API do painel | `panel/src/proxy.ts` (Next 16: o middleware se chama `proxy`; `checkRequest` exportado) + `proxy.test.ts`; `readJson` em `panel/src/lib/http.ts` (415 sem JSON) |
| Rotas | `/api/settings` e `/api/settings/apps/[platform]`, `/api/publisher/status`, `/api/publishing/jobs[/[id][/[action]]]`, `/api/publishing/summary`, `/api/episodes/[id]/approve`, `/api/accounts/[id]/networks/[platform]/(connect|token|check|reopen|creator-info)` |
| Telas | `/accounts` "Canais de publicação" (`account-manager.tsx`, `account-networks.tsx`, `connect-wizard.tsx`), `/publishing` "Publicações" (`publishing-board.tsx`, `publishing-client.ts`), `/settings` "Configurações" (`settings-panel.tsx`) |
| Modal novo (qualquer tela) | `Dialog` + `Steps` de `panel/src/components/dialog.tsx` (`<dialog>` nativo, foco preso, Esc fecha). Confirmação simples continua em `askConfirm` (panel.md) |
| Avisos e chips de estado por rede | `NoticeBar` e `PublishChips` em `panel/src/components/publishing-ui.tsx` |
Botões de um job vêm de `actions[]` da API (`jobActions` no servidor); a UI não decide sozinha o que oferecer.
No texto visível do Clipador "Canais" virou **"Fontes"**; código, tabelas e rotas continuam `channels`.
## Regras que não podem quebrar
- **Nunca `published` sem ID/URL remota** (ou rascunho confirmado). `done` sem link ⇒ `failed` com aviso para
conferir na rede antes de "Tentar de novo" (evita publicar duas vezes). Publicador fechado no meio de um envio ⇒
`failed` "interrompido — tente de novo": também conferir na rede.
- **Aprovar vale para o vídeo inteiro** (todas as redes e canais daquela origem); tirar uma rede = cancelar o job dela.
- **Aprovação automática** (`accounts.approval_mode = 'auto'`) só pega cortes criados depois de ligá-la
(`accounts.auto_since`) **e** depois de a fonte ser ligada ao canal. Episódio **sempre** precisa do clique
"Aprovar para publicar" (exige render final).
- "Na hora" (`timing = 'now'`) respeita o limite diário (`account_networks.daily_limit`); passou do limite, agenda no
próximo horário bom.
- `publishAt` nativo do YouTube **não é usado** (o painel manda `null`); o agendamento é do despachante.
- **Modo sessão viola os termos das três redes**: a UI exige marcar "Entendi o risco". Proibido stealth/patchright/
stealth.js, resolver captcha ou digitar senha; login, captcha ou checkpoint ⇒ `needs_login` e o usuário resolve.
Não rode `playwright install` (só o driver; o navegador é o Chrome/Edge do usuário).
- Segredos nunca voltam ao navegador (só `configured: true/false`) e nunca vão para logs nem para esta skill.
- **Idempotência:** o painel manda `clientRef = "<publish_jobs.id>:<attempts>"`; o Publicador devolve **200** com o job
existente (201 = novo). `attempts` só sobe em "Tentar de novo"/reaprovação. Timeout, conexão caída, 5xx ou
401/403/404 ao criar ⇒ o job **fica na fila** e reenvia com o mesmo `clientRef`; outro 4xx ⇒ `failed`.
- **`mayBeLive`** (falhou depois de chegar ao Publicador): `POST /api/publishing/jobs/<id>/retry` sem `{confirm: true}` ⇒ 409; a UI pergunta
"Confira na rede se o vídeo já saiu". Agente não manda `confirm: true` sem o usuário ter conferido.
- Agendamento automático vencido há > 30 min (painel fechado) é reencaixado no próximo horário bom; horário manual,
"Publicar agora" e "Tentar de novo" saem como estão.
- Encerrar fonte/história cancela os jobs não enviados (`unlinked`); religar zera `linked_at` (a automática não pega
cortes do intervalo desligado). Cancelar no meio de um ciclo vale (UPDATEs condicionais; se o Publicador já criou o
envio, o painel cancela lá). Aprovação automática é registrada em `clip_auto_approvals` antes do PATCH no Clipador.
- **Botão "Publicar" do corte** (`POST /api/publishing/clips/<id>`, corpo `{accountId, platforms[], timing?: "now"|"best_slot"}`,
resposta `{jobs, skipped[{platform, reason}], placed}`; `publishClip`): serve para corte aprovado cuja fonte **não** está
ligada a canal (`account_channels`) ou para outra rede. O clique é a aprovação humana. `timing` omitido = o do canal.
`"now"` força `queued` com `schedule_source='now'` e ignora o limite do dia. Job existente cancelado, `failed` ou
`needs_login` é reaproveitado (`attempts`+1 via `placeApproved`, que ganhou `opts.timing`); rede não conectada,
pausada, já publicada, na fila, agendada, enviando ou "pode ter saído" (`mayBeLive`) entra em `skipped` com motivo.
O diálogo lista essas redes bloqueadas com o motivo. Título e legenda são os do cartão.
- **`publish_jobs.origin`**: `link` (criado pelo vínculo fonte↔canal) ou `manual` (botão "Publicar"). Job `manual` **não**
é cancelado por "fonte desligada" (`planClipSync` com `ExistingJob.origin`, `linkActive`, `accounts.endChannel` só
cancela `origin = 'link'`); corte editado, rejeitado ou apagado ainda cancela o job. Armadilha de migração: gotchas 138.
- Rótulo de IA: se não der para ler a voz do episódio, vai ligado por cautela. **Corte (`source_kind = 'clip'`) nunca leva
o rótulo**, nem com o canal em "always" (`sendDue`; gotchas 148).
- **"Apaguei na rede"** (`removed`): `POST /api/publishing/jobs/<id>/removed`; `markRemoved` (`publishing.ts`) aceita só
`published`, volta o job a `canceled`/`user`, zera url/remote_id/published_at e apaga a `publications` do job; `jobActions`
de `published` = `["removed"]`; cliente `markJobRemoved`; botão em Publicadas com confirmação. O painel não apaga nada na
rede (apague lá primeiro); depois "Publicar" no corte reenvia com `attempts`+1. Gotchas 149.
- Modo sessão: a janela fecha depois de cada envio e do "Já entrei" (pede saída limpa, mata após 10 s); fica aberta
se a rede pedir login/captcha; ociosa fecha em 5 min (15 min se aberta para login). Capturas só da área visível,
nunca em login/captcha, apagadas após 7 dias. Ritmo: "intervalo mínimo entre envios" (30 s, `publisher/README.md`).
- Segurança do Publicador: ACL de `publisher/.env` e `data/publisher/` restrita ao usuário (`setup.ps1` + `acl.py`);
`code_verifier` do PKCE só em memória; loggers `httpx`/`httpcore` silenciados (o token do Instagram vai na URL).
- **Link do vídeo no TikTok** (`find_video_url(page, caption, sleep, attempts=12, reads=5, progress)` em
`tiktok_studio.py`): a lista "Publicações" (`/tiktokstudio/content`) **não se atualiza sozinha** e o vídeo novo só entra
depois de processar. Espera 5 s; a cada tentativa abre ou **recarrega** `CONTENT_URL` e lê 5 vezes (a cada 3 s); até 12
cargas (~3 min), com progresso "Publicado. Esperando o vídeo aparecer na lista do Studio… (n de 12)". **Só aceita o link
cuja linha (até 10 ancestrais do `<a>`) contém `caption_key(caption)`** (primeiros 24 caracteres da legenda sem #hashtags
e @menções): nunca devolve o link de outro vídeo. Sem achar, `PublishResult` sem link e step "Publicado no TikTok
(Studio), mas o vídeo não apareceu na lista do Studio em ~3 min; link não encontrado" ⇒ job `failed` (regra "nunca
`published` sem URL"). No painel, `readPublisherJob` (`publishing-rules.ts`) reconhece `done` sem link com step
começando em "Publicado no " e diz "Saiu na rede, mas o link do vídeo não apareceu a tempo… use 'Já saiu: informar o
link' (não use 'Tentar de novo')". Não há seletor `video_link` (links relativos). Gotchas 140 e 143.
- **"Já saiu: informar o link"** (`mark-published`): `POST /api/publishing/jobs/<id>/mark-published` com `{url}`
(`markPublished` em `publishing.ts`; `MarkPublishedDialog` em `publishing-board.tsx`; cliente `markJobPublished`;
`PublishJobAction` ganhou `"mark-published"`). Aparece em job `failed` (sempre; botão principal se `mayBeLive`) e
`needs_login` (só se `mayBeLive`). `parseVideoUrl(platform, url)` (`publishing-rules.ts`) valida e devolve
`{url, remoteId}`: TikTok `/@conta/video/<id>`; YouTube shorts, `watch?v=` ou `youtu.be`, normalizado para `/shorts/<id>`;
Instagram `reel(s)` ou `p`; outro formato ou rede ⇒ erro. Faz UPDATE condicional para `published` com url e
remote_id, `recordPublication` (registro real) e `kickDispatcher` (marca o corte `published` no Clipador). Use só depois
de conferir na rede que o vídeo está lá; o agente não inventa o link.
- **Primeiro envio real (TikTok, modo sessão, 17/11/2026 13:35):** público, `https://www.tiktok.com/@vortplay/video/7709179978520284437`
(informado; login, upload, legenda, privacidade e "Publicar" funcionaram com conta real). O job terminou `failed` por falta
do link (gotchas 140) e foi marcado como publicado pela rota acima. Seletores do TikTok validados nesse envio; **YouTube e
Instagram em modo sessão: só o ensaio sem publicar (próxima regra); YouTube segue sem validação.**
- **Instagram em modo sessão** (`publisher/app/platforms/session/instagram_web.py`; layout novo de 17/11/2026, barra
lateral só de ícones). Fluxo: o botão é `<a>` com `<svg aria-label="Postar">` e abre DIRETO o diálogo "Criar novo
post" (sem submenu; `create_post` só para o layout antigo), com o `input[type=file]` dentro do diálogo.
- `SELECTORS["create"]` aceita "Postar" (svg, link, botão); erro: "o botão Postar".
- `next`, `share` e `reels_notice_ok` são CSS presos a `_DIALOG` (`div[role='dialog']`): no feed cada post tem um
botão de ícone "Compartilhar" e o seletor global podia clicá-lo (teste `test_buttons_of_the_flow_are_searched_inside_the_dialog`).
- Envio dividido: `prepare(page, spec, progress, sleep)` faz tudo até devolver o locator do Compartilhar **sem
clicar**; `upload` chama `prepare`, clica e espera "compartilhado". Todo clique passa por `click_through`.
- **Rótulo de IA**: `input type=checkbox role=switch` SEM nome acessível, direto no painel (não em "Configurações
avançadas", que só abre como plano B do layout antigo). `find_ai_switch` casa a linha (`AI_ROW_TEXT`, até 6
ancestrais por `innerText`); `_is_on` lê `aria-checked`/`is_checked`; confere de novo depois do clique e, se não
ligou, `PublishError` (não publica sem o rótulo). Sem clique forçado (gotchas 145).
- **Formato "Original"** (`keep_original_shape(page, sleep)`, chamada em `prepare` antes dos "Avançar"): a etapa "Cortar"
vem em 1:1 e cortaria o vídeo vertical (o 1º reel real saiu quadrado, gotchas 147). Clica em
`svg[aria-label='Selecionar corte']`/'Select crop' no diálogo e escolhe "Original" (`SELECTORS["crop_toggle"]`,
`["crop_original"]`; opções Original, 1:1, 9:16, 16:9) e fecha o menu. Sem o ícone ⇒ `PublishError`, nunca publica cortado.
- `close_suggestions(page, text)`: legenda terminando em `#tag`/`@menção` ganha um espaço no fim (Esc fecharia a caixa).
- **Link do reel**: o endereço não muda após compartilhar. `find_reel_url(page, caption, sleep, attempts=6,
per_load=3, progress)` acha o link do perfil (`_PROFILE_HREF_JS`: `/<conta>/` com `textContent` "Perfil" ou foto do
perfil no `alt`; a barra recolhida esconde o texto), abre `/<conta>/reels/`, abre os 3 mais novos ainda não
conferidos e aceita o primeiro cuja página contém `caption_key(caption)` (agora em `common.py`, também usada pelo
TikTok); recarrega até 6 vezes, 20 s entre elas (~3 min). `MEDIA` aceita `/<conta>/reel/<código>/`. Sem link ⇒
`PublishResult` sem URL ⇒ job `failed` ⇒ "Já saiu: informar o link".
- **Ensaio sem publicar** (jeito seguro de validar seletores com conta real): rodar `prepare` com o navegador do
perfil, conferir o resultado e descartar o rascunho ("Descartar"); nunca clicar em Compartilhar sem pedido do usuário.
- Validado ao vivo (informado, 17/11/2026, ensaio com `ai_generated=True`): Postar, arquivo `clip-29.mp4`, Avançar ×2,
legenda "…#teste" intacta, rótulo de IA LIGADO, Compartilhar achado e não clicado, rascunho descartado, 0 diálogos no
fim. `_PROFILE_HREF_JS` voltou `/vortplay27/`. **Não validados com conta real:** clique em Compartilhar, a
confirmação "compartilhado" e `find_reel_url` (a conta ainda não tinha reels). Só vale depois de reiniciar o `pnpm dev`.
- **Avisos de novidade do site (modo sessão):** o TikTok Studio abre avisos por cima da página ("Veja a prévia do seu vídeo
no seu celular" → **Entendi**) que bloqueiam cliques. Todo clique do `tiktok_studio.py` passa por `click_through`
(timeout 8 s; se falhar, `dismiss_tips` fecha os avisos e tenta de novo; sem aviso, relança o erro) e `dismiss_tips`
roda antes da legenda e antes de "Publicar". `TIP_BUTTONS` só aceita `^(Entendi|Entendido|Ok, entendi|Got it)$`:
**nunca aceitar ou recusar opções por esse caminho**, só fechar avisos. Gotchas 142.
## Fatos das plataformas (resumo; detalhe e fontes em `doc/publicacao/PESQUISA.md`)
- YouTube: projeto não verificado já publica público (desde 02/11/2026); `videos.insert` 100 envios/dia; app em
"Testing" perde a autorização em 7 dias (pôr "In production").
- TikTok: sem auditoria, Direct Post só `SELF_ONLY` (conta privada) ou rascunho (até 5 pendentes/24 h); auditoria
para uso próprio provavelmente negada.
- Instagram: conta Profissional; conta própria sem App Review; token colado (a Meta não aceita redirect localhost),
vale 60 dias, renovado quando faltam < 10; `rupload` com arquivo local via `graph.instagram.com` ainda **a testar**.
## Evidência (17/11/2026)
Depois das revisões de segurança e correção, reconferido pela skill: `pnpm test:publisher` → 71 passed (depois da correção do Chrome 157, informado: 73 passed; gotchas 137);
`pnpm --filter cenaforge-panel test:panel` → 59/59; typecheck do painel e da raiz sem erro (informados também:
`test:launcher` 17/17, `test:clipper` 270 passed). Bancos reais: `data/cenaforge.db` ainda em `user_version` 5 (a v6
entrava só com o painel reaberto; hoje a 1ª requisição depois da recarga do `db.ts` migra — gotchas, itens 51 e 138); `data/publisher/publisher.db` em 2. Não
verificado: conexão de qualquer rede pela UI (nos dois modos), envio real, renovação de token, seletores do modo
sessão, laço do despachante com o painel ao vivo, fechamento da janela do navegador num envio real.
Botão "Publicar" do corte (informado, 17/11/2026; não reexecutado aqui): typecheck do painel verde; `test:panel` 63/63,
com testes novos em `publishing-rules.test.ts` ("publicado à mão (origin manual)…") e em `publishing-db.test.ts`
(seção "Publicar" no cartão do corte: job manual com rede não conectada pulada, `endChannel` não cancela o manual,
recusas); teste de migração agora espera a v7. **Não testado com conta real.** Plano: `doc/publicacao/PLANO.md` §7c.
Envio de arquivo grande no modo sessão (informado e reconferido, 17/11/2026): a 1ª tentativa real no TikTok chegou ao
TikTok Studio logado e falhou em `set_input_files` (> 50 MB, gotchas 139). Correção `is_local=True` aplicada;
`pnpm test:publisher` → 73 passed (então). O envio real depois disso funcionou (ver "Primeiro envio real" acima).
Link do TikTok e "Já saiu" (informado, 17/11/2026): `pnpm test:publisher` → **74 passed** (reexecutado na skill; teste novo
`test_tiktok_link_waits_for_the_list_and_matches_caption` em `publisher/tests/test_browser.py`); `test:panel` 65/65 e
typecheck verdes (informados, não reexecutados); `parseVideoUrl` em `publishing-rules.test.ts`, `markPublished` em
`publishing-db.test.ts`. `find_video_url` validado ao vivo só de leitura na lista real (informado): a legenda certa
devolveu o link, a de outro corte `None`. **`find_video_url` e `is_local` só valem depois de reiniciar o `pnpm dev`.**
Espera do link com recarga da lista (informado, 17/11/2026): `find_video_url` com 12 cargas × 5 leituras; validado ao vivo,
só leitura, achou `https://www.tiktok.com/@vortplay/video/7709183805373877524` (2º post real, 13:50); o job 1 foi marcado
publicado por `mark-published`. `pnpm test:publisher` → **76 passed** (reexecutado; teste
`test_tiktok_link_waits_for_the_list_and_matches_caption` agora recarrega e confere "2 de 12"). `test:panel` 65/65 e typecheck
verdes (informados, não reexecutados; teste novo da mensagem "Saiu na rede…"). **O envio das 13:50 rodou código antigo** (gotchas
143): a espera nova ainda **não foi exercitada num envio real**.
Aviso por cima da legenda (informado e reconferido, 17/11/2026): o 2º envio real no TikTok (captura `20261117-134508`)
falhou no clique da legenda por causa do aviso "Entendi" (gotchas 142); o upload de 100+ MB passou (`is_local` valendo).
`pnpm test:publisher` → **76 passed** (reexecutado; testes novos `test_click_through_closes_tip_and_retries` e
`test_browser_error_text_explains_common_failures`). O post não chegou a ser feito; **correção não testada num envio
real e só vale depois de reiniciar o `pnpm dev`.**
Instagram em modo sessão (informado e reconferido, 17/11/2026): `pnpm test:publisher` → **78 passed** (reexecutado; testes
novos `test_instagram_links_and_hashtag_suggestions` e `test_buttons_of_the_flow_are_searched_inside_the_dialog` em
`publisher/tests/test_browser.py`). Ensaio ao vivo sem publicar: ver regra "Instagram em modo sessão". O "Já entrei" do
usuário falhou porque o Publicador rodava código antigo (gotchas 143): reiniciar o `pnpm dev`.
1º reel real e formato (informado, 17/11/2026): o reel `/reel/Df2cezTNhY7/` (corte 68) saiu 1:1; o usuário o apagou e a
página mostra "Esta página não está disponível" (conferido). Corrigido com `keep_original_shape` (gotchas 147); ensaio sem
publicar validou a prévia 9:16 inteira com legenda e rótulo de IA; rascunho descartado. `pnpm test:publisher` → **78 passed**
(reexecutado). `test:panel` 66/66 e typecheck verdes (informados, não reexecutados; teste novo de `markRemoved`).
**Formato "Original" só vale depois de reiniciar o `pnpm dev`; o painel (`removed`, corte sem rótulo) já vale.** Não validado:
publicação real com o formato novo.
@@ -0,0 +1,82 @@
# Economia de tokens no CenaForge
Mantido pelo agente `cenaforge-token-auditor`. Princípio: o modelo caro decide e revisa; texto
narrativo vai para modelo mais barato; trabalho mecânico vai para script.
## Quem faz o quê
| Tarefa | Quem | Por quê |
|---|---|---|
| Arquitetura, pipeline de render, depuração, revisão final de entrega | modelo principal | erro aqui custa mais que os tokens |
| Enredo, bíblia da história, episódios, diálogos, título e opções A/B | `cenaforge-story-writer` (sonnet) | texto criativo não precisa do modelo mais caro; já respeita os limites do JSON |
| Dezenas de variações de título/opção, resumo de log, classificação | subagente com `model: haiku` | tarefa curta e repetitiva |
| Interface do painel (design, logo, componentes) | `cenaforge-dashboard-designer` (opus) | decisão do usuário: qualidade visual pede o modelo mais capaz |
| Atualizar a skill | `cenaforge-skill-updater` | confere fatos sem poluir o contexto principal |
| Achar onde algo está no código | agente `Explore` | devolve a conclusão, não os arquivos |
| Achar desperdício e criar scripts | `cenaforge-token-auditor` (sonnet) | — |
## Scripts (rode em vez de improvisar comandos)
Todos em `.claude/skills/cenaforge/scripts/`, Python 3.10+ só com biblioteca padrão. Rode a
partir da raiz do repositório.
| Script | Substitui | Uso |
|---|---|---|
| `runs_summary.py` | ler `report.json`/`render.log` inteiros | `python .claude/skills/cenaforge/scripts/runs_summary.py --last 3 --details` |
| `inspect_strip.py` | extrair e ler vários quadros soltos | `python .claude/skills/cenaforge/scripts/inspect_strip.py output/runs/<execução>` → lê só `inspect/strip.png` |
| `new_scene.py` | ler e reescrever o JSON inteiro | `python .claude/skills/cenaforge/scripts/new_scene.py --id <id> --set overlay.title="..." --set rider.travelMeters=36` (cria e valida) |
| `check_skill.py` | conferir caminhos/comandos da skill à mão | `python .claude/skills/cenaforge/scripts/check_skill.py` |
| `clean_runs.py` | listar e apagar execuções à mão | `python .claude/skills/cenaforge/scripts/clean_runs.py` (simula) · `--apply` (apaga) |
| `frame_check.py` | abrir vários quadros/QA para ver se a cena ficou boa | `python .claude/skills/cenaforge/scripts/frame_check.py --last` · `<output/runs/execução>` · `--config data/tmp/<id>-teste.json [--profile preview]` (renderiza e confere). Resume `report.json` e mede cada `inspect/t*.png` (luminância ESCURO < 0,08 / ESTOURADO > 0,92, contraste CHAPADO < 0,04, movimento PARADO < 0,004, enquadramento FORA se o detalhe foge > 30% do centro) e diz qual UMA imagem abrir. Saída 0 ok · 2 atenção · 1 falha |
| `check_script.py` | reler o roteiro à mão | `python .claude/skills/cenaforge/scripts/check_script.py stories/<história>` (ou um `ep*.md`): mesmas regras do leitor do painel (`script-doc.ts`, 2,5 palavras/s, "Duração:", tabela com 1ª coluna t (s)); avisa narração fora de ±15% do alvo, trecho que não cabe no tempo, buracos, coluna Imagem vazia, `meta.json` (title ≤ 60, logline) e `*.choices.json` (≤ 60, distintas) |
## Regras de leitura barata
- **Render:** depois do `pnpm render`, leia só o resumo impresso ou `runs_summary.py`. Abra o
`render.log` apenas se houver falha, e com `grep` (ex.: `grep -E "ERROR|SCRIPT|frames at"`).
- **Imagens:** uma `contact-sheet.png` ou `strip.png` por verificação, não quadros individuais.
Recorte ampliado só para checar um detalhe específico.
- **Testes:** filtre a saída (`pnpm test 2>&1 | grep -E "✖|^ℹ (pass|fail)|passaram|FALHA"`).
- **Código:** `Grep` com o nome da função antes de ler arquivos inteiros; leia por intervalo de linhas.
- **Renders:** um render de prévia por iteração; o perfil final só no fim. Não renderize para
testar algo que os testes headless ou `--validate-only` já cobrem.
- **Comandos longos de saída** (pnpm install, import da Godot): sempre com `| tail -n 5`.
- **Imagens, regra dura:** no máximo UMA por render, escolhida pelo `frame_check.py`. Nada de abrir quadros em
lote nem gerar imagens de QA próprias (ex.: `output/castaways-qa/`): cada imagem fica no histórico e é reenviada
a cada turno. Medido na execução #8 (Codex, cena Godot): ~100 imagens em resolução cheia → 26 milhões de caracteres
de saída de ferramenta, 6,83 milhões de tokens de entrada, 54 chamadas, 29 min.
- **Pesquisa na web (documental):** busque o termo dentro da página e use 3–5 fontes; página aberta inteira custa
30–40 mil caracteres (execução #6: 1,06 milhão de tokens de entrada).
- **Retomada (resume)** nas duas CLIs reenvia todo o histórico (vem do cache, mas conta): conversa longa fica cara a
cada mensagem. Com contexto já grande, abra nova execução com o resumo do que falta.
## Custo fixo dos agentes do painel (medido em 17/11/2026)
Código: `panel/src/lib/agents.ts`. Detalhes e correções de sintoma em [gotchas.md](gotchas.md) (itens 133–135).
| Provedor | O que o painel passa | Efeito medido |
|---|---|---|
| Claude CLI | `CLAUDE_LEAN_FLAGS`: `--setting-sources project,local --strict-mcp-config --tools Read,Edit,Write,Glob,Grep,Bash,Agent,Skill,TodoWrite` | prompt trivial no Haiku: 1º turno 62,4 mil → 14,9 mil tokens de entrada só com as flags (18,6 mil com o conjunto completo do painel, que inclui Agent); partida 8,0 s → 4,3 s. Sem as flags carregava plugins/MCP/hooks/skills do usuário (61 ferramentas, 5 MCPs, 310 skills, 78 agentes, 442 comandos). Subagentes do projeto (`.claude/agents`) e a skill `cenaforge` continuam visíveis |
| Claude CLI | `--max-budget-usd` por tarefa (`CLAUDE_BUDGET_USD`: story 1,5 · script 1,5 · branches 2,5 · scene 1 · godot 3 · free 3) | `error_max_budget_usd` vira "continue a conversa". A CLI não tem `--max-turns` |
| Codex | `codexLeanOverrides`: `-c model_reasoning_effort` por tarefa (story/script/branches/godot = medium, scene = low, free = o do `config.toml`), `mcp_servers.<nome>.enabled=false` para cada servidor do `config.toml`, plugins `computer-use@openai-bundled` e `unified-computer-use@openai-bundled` desligados (tira `cua_repl`, ~6,5 mil caracteres por turno) | fixo do Codex ~18–19 mil tokens no 1º turno; `base_instructions` ~21 mil caracteres |
Referência de peso: na execução #7 (cena Godot, Opus, US$ 3,09, 26 chamadas) o fixo era ~49 mil tokens por chamada e
somou 2,8 milhões de tokens lidos do cache — por isso o corte do fixo vale mais que qualquer ajuste de prompt.
### Juiz do Clipador (`clipper/app/judge.py`, medido em 17/11/2026)
Cada chamada é um processo novo de CLI: 2 por candidato (analista com 6–8 quadros 768×432 + editor só texto). Live de
3,7 h = 75 candidatos = ~150 chamadas; padrão Codex `gpt-6-luna`, esforço low.
| Provedor | O que o juiz passa | Efeito medido |
|---|---|---|
| Codex | `codex_lean_overrides(search)`: sem `--search`, `features.{plugins,apps,shell_tool,unified_exec,code_mode_host,sleep_tool,skill_search,tool_suggest,in_app_browser,browser_use}=false` + `computer_use,image_generation,goals,hooks=false`, `mcp_servers.<nome>.enabled=false`, plugins computer-use off, e o `system` num instructions.md temporário via `-c model_instructions_file='<caminho>'` (stdin só com o prompt). Com `--search` saem só os extras e o `system` fica no stdin. `view_image` fica ligado | antes: ~77 mil caracteres fixos (~19 mil tokens: instruções 18 mil, ferramentas 46,5 mil, skills/apps ~12 mil) ≈ 2,9 mi tokens naquela live, a mesma cota que bloqueou o agente do painel. Depois: instruções 105 caracteres, ferramentas 29 mil (sobram `exec` e `collaboration`, que `-c` não remove), fixo ≈ 35 mil caracteres (~9 mil tokens, −55%, estimativa). Imagem chega como `input_image`. **Resposta do modelo não validada** (cota esgotada até 16h27 de 17/11) |
| Claude | `--setting-sources project,local` (além de `--system-prompt`, `--tools`, `--strict-mcp-config`, `--no-session-persistence`) | Haiku: fixo 3,7 → 2,6 mil tokens (−31%), 5,5 → 2,8 s por chamada |
Propostas não implementadas (mudam recall; exigem decisão do usuário): na sessão 3, o juiz descartou 33 de 75
candidatos (44%) e, na origem `face`, 15 de 21 (heurística média 3,07). Opções: pré-filtro por pontuação antes do LLM
ou juntar analista+editor numa chamada.
Os prompts do painel (`panel/src/lib/prompts.ts`) já mandam: godot usa `frame_check.py` e uma imagem por render;
story/script/branches terminam com `check_script.py`; nenhum agente aciona `cenaforge-skill-updater` nem
`cenaforge-token-auditor`. `CLAUDE_ALLOWED_TOOLS` libera `frame_check.py` e `check_script.py` via Bash.
@@ -0,0 +1,190 @@
# Ferramentas do CenaForge
Inventário do que o pipeline usa, do que está planejado e de como avaliar uma ferramenta nova.
Versões abaixo foram **verificadas** na data indicada; ao trocar de versão, rode o render de
prévia e registre aqui (via `cenaforge-skill-updater`).
## Em uso
| Ferramenta | Versão testada | Papel | Como é localizada | Verificada em |
|---|---|---|---|---|
| Godot (edição padrão, GDScript) | 4.7.2.stable.official (ed1daf0bf) | monta e anima a cena (rua 3D `main.tscn`; documentário em `doc.tscn`: 2D por `doc2d_canvas.gd`, `_draw` + SystemFont Segoe UI/Arial/DejaVu; 3D pela biblioteca `godot/library/`: `island` com FastNoiseLite, MultiMesh, shader de mar e ProceduralSky; `castaways` sobre os kits `godot/kits/` com malha por SurfaceTool); Movie Maker grava PNG | `GODOT_BIN` → `PATH` (`godot`, `godot4`) → `.tools/godot-<versão>/Godot_v*-stable_win64.exe` | 16/11/2026 (reconferida 17/11/2026; `doc2d` e `doc3d` `island`/`castaways` com render ok em 17/11/2026) |
| Renderizador Godot | Mobile (Vulkan) | sombras direcionais, MSAA 4x, névoa, tonemap | método `mobile`, `msaa_3d=2` (4x) e sombra 4096 em `project.godot`; névoa e tonemap Filmic em `street_builder.gd`; ACES + névoa na ilha (`godot/library/island/template.gd`) | 16/11/2026 (ilha: 17/11/2026) |
| FFmpeg | 7.1.1 essentials (gyan.dev) | PNG → MP4; áudio AAC; quadros de inspeção; montagem documental do painel (`zoompan`, `boxblur` + `overlay` na foto horizontal, `drawtext`, concat `-c copy`; `panel/src/lib/montage-ffmpeg.ts`, fonte Segoe UI Bold/Arial Bold) | `FFMPEG_BIN` → `PATH` | 16/11/2026 (montagem: 17/11/2026) |
| FFprobe | 7.1.1 | verificação do MP4 e duração do áudio | `FFPROBE_BIN` → `PATH` | 16/11/2026 |
| Encoder de vídeo | `libx264` (preset medium, CRF 18) | H.264 yuv420p | ordem: libx264 → h264_nvenc → libopenh264 (`tools.ts`) | 16/11/2026 |
| Node.js | 24.19.0 (mínimo ≥ 20.10) | lançador | — | 16/11/2026 |
| pnpm | 11.22.0 | scripts e lockfile | — | 16/11/2026 |
| tsx | 4.23.15 | executa o TypeScript do lançador | devDependency | 16/11/2026 |
| TypeScript | 7.0.2 (compilador nativo) | `pnpm typecheck` | devDependency | 16/11/2026 |
| @types/node | 24.19.2 | tipos | devDependency | 16/11/2026 |
| Next.js / React / Tailwind | 16.4.6 / 19.3.0 / 4.3.3 | painel (`panel/`) | dependências do workspace | 16/11/2026 |
| @xyflow/react | 13.0.1 | árvore de vertentes na aba Fluxo (`panel/src/components/story-flow.tsx`) | dependência do painel | 16/11/2026 |
| SQLite | `node:sqlite` (Node 24) | banco do painel, sem dependência nativa | embutido | 16/11/2026 |
| Codex CLI | 0.169.0 (`@openai/codex`) | agente no painel (`codex exec --json -m <slug>`, sandbox `workspace-write`); modelos lidos de `~/.codex/models_cache.json` (panel.md, "Agentes e modelos") | `CODEX_BIN` → `.exe` no PATH → `codex.js` ao lado do `codex.cmd` do npm | 17/11/2026 |
| API do Wikimedia Commons (`commons.wikimedia.org/w/api.php`) | sem versão (HTTP público, sem chave; User-Agent genérico) | fotos reais por trecho na montagem documental (`panel/src/lib/image-search.ts`), com autor, licença e página de origem nos créditos | chamada direta do painel | 17/11/2026 (`ep01.montage.json`: 5 fotos do Commons com licença CC registrada; MP4 de 88,3 s; licença não conferida na página de cada foto) |
| Claude Code CLI | 2.1.314 | agente chamado pelo painel (`-p`, `stream-json`, `--resume`, `--model claude-*-5-5`/`claude-fable-5-2`) | `CLAUDE_BIN` → `PATH` (`claude.exe`) | 17/11/2026 |
Hardware do teste de referência: i9-13900K, 64 GB, RTX 2060 SUPER. Tempos: prévia 540×960
42–44 s; final 1080×1920 ~160 s. A etapa de render da Godot ocupa 94–96% do total, dominada
pela codificação PNG (105 ms/quadro na prévia, 404 ms no final; ~90–91% do total); GPU
1,9/4,5 ms por quadro. Cena 2D (`doc2d`, 17/11/2026, `report.json`): prévia 540×960 de 5 s em 2,7–4,3 s; final
1080×1920 de 4,4–14,3 s em 7,4–21,5 s por cena (9 cenas). Cena 3D `island` (`doc3d`, 17/11/2026, `report.json`): prévia
540×960 de 5 s em 9,4–14,3 s (Godot 9–13 s, 13 execuções); final 1080×1920 de 9,1 s em 42,9 s (Godot 39,1 s). Cena 3D
`castaways` (17/11/2026, `report.json`): prévia 540×960 de 4–5 s em 5,8–15,6 s (65 execuções `teste-cast-*`); final
1080×1920 de 2,8–12,3 s em 9,8–89,7 s por cena (11 cenas da montagem dos náufragos).
## Serviço de voz (`voice/`) — instalado, ainda fora do render
Serviço FastAPI local em `127.0.0.1:4510`, cópia adaptada do `dropsz_voice` (o original não é
alterado). Instalado por `setup.bat` → `scripts/setup.ps1`; fixações em `voice/requirements*.txt`
e `voice/models.lock.json`. Consumido pela página Vozes do painel (`panel/src/lib/voice.ts`).
Evidência (16/11/2026): `pnpm test:voice` → 133 passed (conferido nesta manutenção; inclui Kokoro/Google/Azure simulado/clone e flag `offline` por motor); legenda pelo painel na CPU: 6,5 s de fala
em 2,5 s, 14 palavras e `.srt`; fumaça
`voice/scripts/smoke.py` gerou os WAV das três vozes e a transcrição em `output/voice-smoke/`;
setup completo rodou 2x com saída 0 (repetível); `torch 2.11.0+cu128`, `cuda True`;
`VoiceConverter` do Applio importa no `voice/.venv` com device `cuda:0`; pré-requisitos em
`voice/vendor/applio/rvc/models/` (`predictors/rmvpe.pt`, `predictors/fcpe.pt`,
`embedders/contentvec/pytorch_model.bin`).
Catálogo com 76 vozes (16/11/2026): 12 Edge, 3 Piper, 45 Kokoro, 2 Google, 14 Azure (contagem
conferida no `catalog.json`; as Azure só aparecem com `VOICE_AZURE_KEY`). Antes, com 15 (informado): `fetch_models.py --group v1` conferiu sha256 de
cadu/jeff; `load_catalog(verify=True)` carregou 15; amostras transcritas com Whisper `small` —
Edge todas `pt` (prob ≥ 0,99), cadu correto, jeff erra palavras longas. `edresson` (Piper low,
16 kHz) fora de propósito. Piper não tem feminina pt-BR; a feminina offline agora é `kokoro-pf-dora`.
Kokoro (informado, 16/11/2026): as 54 vozes leram frase pt-BR, transcrição com Whisper `small` →
45 com 100% das palavras e idioma `pt` entraram; excluídas `af_bella`, `af_nicole`, `bf_alice`,
`bf_emma`, `bf_isabella`, `bm_fable`, `em_santa`, `ff_siwis`, `jf_alpha`.
**Nenhum render usou o serviço ainda** — o WAV entra no vídeo só via `audio.file`.
| Ferramenta | Versão verificada | Papel |
|---|---|---|
| uv | 0.11.26 | cria `voice/.venv` (o Python do sistema não é tocado) |
| Python | 3.12.13 | `voice/.venv` |
| FastAPI / uvicorn | 0.159.1 / 0.54.0 | HTTP (`uvicorn app.main:build --factory`, chamado por `scripts/dev.ts`) |
| edge-tts | 7.3.1 | 12 vozes online do catálogo (`pt-br-*`, `pt-pt-*`, `multi-*`) |
| piper-tts / onnxruntime | 1.8.0 / 1.31.0 | vozes `pt-br-faber`, `pt-br-cadu`, `pt-br-jeff` (offline, CPU, medium 22050 Hz) |
| kokoro-onnx / phonemizer / espeakng-loader | 0.6.1 / 3.6.0 / 0.2.4 | 45 vozes `kokoro-*` (offline, CPU; Kokoro-82M **fp16**, Apache-2.0; um modelo + `voices-v1.0.bin` do release `model-files-v1.1` de thewh1teagle/kokoro-onnx) |
| gTTS | 2.5.4 | `google-pt-br`, `google-pt-pt` (online; API não oficial do Google Tradutor; só normal/lenta) |
| faster-whisper / ctranslate2 / av | 1.2.1 / 4.8.3 / 19.0.2 | transcrição com tempos; modelos `base`, `small`, `medium`, `large-v3-turbo` |
| nvidia-cublas-cu12 / nvidia-cudnn-cu12 | 12.9.2.10 / 9.26.0.51 | DLLs CUDA 12 para o Whisper na GPU (só com GPU NVIDIA) |
| Applio | 3.7.0 (`voice/vendor/applio`) | RVC: vozes de personagem |
| torch / torchaudio | 2.11.0+cu128 (com GPU) ou 2.11.0+cpu (sem) | motor do Applio; o setup pede a variante explícita |
### Clonagem de voz (`voice/.venv-clone`, opcional: `setup.bat -Clone`)
Venv separado porque o Chatterbox conflita com o `voice/.venv` (gotchas, item 65). Worker
`voice/clone/worker.py` (stdlib, 127.0.0.1:4511, mesma `X-Service-Key`) chamado pelo `CloneEngine`.
Detalhes e formato da voz clonada: `voice/README.md`, "Clonagem de voz".
| Ferramenta | Versão verificada (16/11/2026) | Papel |
|---|---|---|
| Python | 3.12.13 | `voice/.venv-clone` |
| chatterbox-tts | 0.1.7 (Chatterbox Multilingual, Resemble AI, MIT; pt suportado) | clonagem a partir de 10–30 s de gravação; WAV 24 kHz; marca d'água PerTh; sem velocidade |
| torch / torchaudio | 2.6.0+cu124 (`torch.cuda.is_available()` = True) | fixado pelo Chatterbox |
| numpy / transformers | 1.26.4 / 5.2.0 | fixados pelo Chatterbox |
| Pesos | `ResembleAI/chatterbox`, revisão `main` (~3,3 GB em `data/voice/models/clone-hf/`) | **não fixados em commit nem sha256** (gotchas, item 64) |
Evidência informada (16/11/2026, RTX 2060 SUPER 8 GB, worker real na GPU; não registrada em
`doc/TEST_RESULT.md`): modelo carregou em 10 s (pesos já baixados); referência sintética de 10,7 s
(Kokoro `pm_alex`); fala 1: 6,0 s de áudio em 20,5 s (inclui condicionamento); fala 2: 7,1 s em
10,5 s; Whisper `small` transcreveu as duas exatamente (idioma `pt`, prob. 1,0). Não testado: CPU,
referência de voz humana real, fluxo completo pelo painel (upload → síntese).
Medições informadas (16/11/2026, i9-13900K, RTX 2060 SUPER 8 GB; não registradas em
`doc/TEST_RESULT.md`): Edge ~2,5–3 s por fala de ~6 s; Piper ~0,02 s (modelo já carregado);
Whisper `small` na CPU 2,7 s para 6,5 s de fala com palavras. Kokoro (CPU): `kokoro-pf-dora` 3,2 s
de áudio em 2,4 s (1ª síntese, carrega o modelo); depois `pm-alex` 0,6 s, `am-michael` 0,7 s.
Google: `google-pt-br` 4,8 s de áudio em 0,8 s. GPU disputada: ver `gotchas.md`.
Não verificado: conversão RVC com modelo real (`VOICE_ENABLE_RVC=1`, mas nenhum `.pth`
instalado), Whisper `large-v3-turbo` (só `small` baixado em `data/voice/models/whisper/`) e o
download de modelo de Whisper disparado pelo painel.
## Clipador (`clipper/`) — cortes de live, fora do render da Godot
Serviço FastAPI em `127.0.0.1:4520`. Instalado no passo 6b do `scripts/setup.ps1`, com as versões
fixadas em `clipper/requirements*.txt`. Detalhes e evidência em [clipper.md](clipper.md).
Evidência: `pnpm test:clipper` → 270 passed (17/11/2026, com apagar cortes e veto do rejeitado no juiz e na fila; sem dependência
Python nova nem ferramenta nova). Fase 1 (16/11/2026): uma live real da Twitch gerou 5 cortes H.264 1080×1920 + AAC. Horizontal 1920×1080: só
render de teste conferido no ffprobe (informado); nenhum corte horizontal de live ainda.
| Ferramenta | Versão verificada (16/11/2026) | Papel |
|---|---|---|
| Python | 3.12.13 | `clipper/.venv` (criado pelo uv) |
| FastAPI / uvicorn / httpx / websockets | 0.159.1 / 0.54.0 / 0.28.1 / 17.4 | HTTP do serviço; chamadas à voz; chat da Kick (Pusher) |
| Streamlink | 8.6.3 (reconferido em 17/11/2026) | captura de live/VOD (`clipper/.venv/Scripts/streamlink.exe`); qualidade por `--stream-sorting-excludes` e, na Twitch, `--twitch-supported-codecs h264,h265` (`clipper/app/capture.py`). HEVC real da Twitch não testado (nenhuma live 2K no ar) |
| pytest | 9.1.1 (fixado em `requirements-dev.txt`) | `pnpm test:clipper` |
| FFmpeg | 7.1.1 essentials, com filtro `ass` (libass) — reconferido em 17/11/2026 | blocos `-f segment`, render vertical e horizontal, legenda queimada com `fontsdir`, reenquadramento (`perspective` `eval=frame`), camadas (`alphamerge`/`overlay`); decodifica HEVC; sem libdav1d (AV1 não é pedido na captura); NVENC quando houver (`CLIPPER_ENCODER=auto`; horizontal com NVENC não testado) |
| Fontes empacotadas (`assets/fonts/`) | google/fonts no commit `7af0d90b4d532ffa4b041937b560c6df4e7b1e95`, sha256 em `fonts.lock.json` | ASS do Clipador e prévia do editor no painel. Licenças: Luckiest Guy Apache-2.0; Bangers, Anton, Bebas Neue, Poppins ExtraBold OFL-1.1 (texto ao lado de cada `.ttf`) |
| Codex CLI / Claude Code CLI | 0.169.0 (reconferida em 17/11/2026) / 2.1.314 (as mesmas da tabela "Em uso") | juízes analista + editor, varredura, câmera e pesquisa do jogo (`codex --search exec … -i <img> … -`), sem chave de API; padrão Codex `gpt-6-luna`. Claude: não testado |
| APIs públicas de emotes 7TV / BTTV / FFZ | sem versão (HTTP público, sem chave) | catálogo de emotes do canal e globais (`clipper/app/emotes.py`, cache 1 h; 7TV dá 404 em canal sem 7TV). Coberto só por teste sem rede; chamada real não registrada |
Rastreio de reação (`clipper/app/face.py` + `reaction.py`; detalhes em [clipper.md](clipper.md)). Versões conferidas
no `clipper/.venv` em 16/11/2026 (`importlib.metadata`). Evidência (`doc/FACE_BAKEOFF.md`): bancada e rastreio de
144 blocos numa cópia do banco; em 17/11/2026, serviço real ao vivo (instância 4521, 25/25 blocos, 1,71 s/bloco, p95
2,20 s, CPU média 16,8 % de um núcleo) e download real dos 4 pesos com sha256 conferido. Só CPU; GPU não testada.
| Ferramenta / peso | Versão verificada | Licença | Papel |
|---|---|---|---|
| mediapipe (Face Landmarker `face_landmarker.task` float16/1) | 1.2.3 | Apache-2.0 | 478 pontos + 52 blendshapes; 5–7 ms/quadro na bancada; bloco de 30 s em 1,71 s ao vivo (com gravação + transcrição juntas) |
| opencv-contrib-python (`cv2.FaceDetectorYN`) + YuNet `face_detection_yunet_2026may.onnx` | 5.0.0.93 (`cv2` 5.0.0) | Apache-2.0 / MIT (peso) | acha a câmera pelo rosto no quadro inteiro (piso de confiança 0,7: gotchas, item 92). Sem `opencv-python-headless` junto (gotchas, item 80) |
| numpy | 2.5.5 | BSD | séries e recorte |
| onnxruntime + OpenSeeFace `osf_lm_model3_opt.onnx` / `osf_mnv3_detection_opt.onnx` | 1.32.0 | MIT / BSD-2-Clause (pesos) | plano B (só posição, sem expressões; sem linha de rosto ao analista). Pesos reais no `face.py` em 17/11/2026: rosto 96,7–100 %, 12,3–13,9 ms/quadro (MediaPipe no mesmo trecho: 94,4–100 %, 9,8–13,2) |
Pesos fixados em `clipper/models.lock.json` (commit/caminho versionado + sha256), baixados em `data/clipper/models/`.
Descartados por licença (não integrar): SCRFD/InsightFace (pesos não comerciais), YOLO-Face (GPL/AGPL), LibreFace
(não comercial), OpenFace 3.0 (só pesquisa), Py-Feat (licença indefinida) — `doc/PLANO_RASTREIO_REACAO.md`.
## Publicador (`publisher/`) — instalado, sem envio real registrado
Serviço FastAPI em `127.0.0.1:4530` (detalhes em [publishing.md](publishing.md) e `publisher/README.md`). Instalado no
passo 6b2 do `scripts/setup.ps1`; versões fixadas em `publisher/requirements*.txt`. Evidência (17/11/2026):
`pnpm test:publisher` → 71 passed (rede e navegador simulados; reconferido pela skill depois das revisões de
segurança).
| Ferramenta | Versão verificada (17/11/2026, `publisher/.venv`) | Papel |
|---|---|---|
| Python | 3.12.13 | `publisher/.venv` (criado pelo uv) |
| FastAPI / uvicorn / pydantic / httpx | 0.159.1 / 0.54.0 / 2.14.1 / 0.28.1 | HTTP do serviço e chamadas às APIs das redes |
| playwright (Python) | 1.65.2 | **só o driver** para `connect_over_cdp` no Chrome/Edge do usuário (não rodar `playwright install`) |
| pytest | 9.1.1 | `pnpm test:publisher` |
| Chrome ou Edge instalado | versão da máquina (não registrada) | modo sessão: aberto como processo normal, CDP em 4540–4549 |
| DPAPI do Windows (`CryptProtectData`) | do sistema | cofre `data/publisher/vault.bin` |
## Planejadas ou candidatas — NÃO integradas
| Ferramenta | Para quê | Situação |
|---|---|---|
| Meshy | gerar modelos GLB (personagens, objetos) e rig | citada na especificação; não testada |
| Mixamo | animações para personagens com rig | citada como não obrigatória; não testada |
| `.glb` carregado por `GLTFDocument` em tempo de execução (Godot) | modelos prontos dentro de cenas da biblioteca (`library/<id>/assets/`) | **só documentado** em `doc/godot/cenas.md`; nenhum `.glb` no repositório nem render com ele (17/11/2026). Personagens e barcos atuais são procedurais (`godot/kits/`) |
| Serviço de voz no render | narração por fala e legenda automática a partir de `X-Detail: words` | próxima etapa; `scripts/lib/audio.ts` ainda não chama o serviço |
| Applio pessoal + projetos de narração do usuário | modelos RVC já treinados | existe no PC do usuário; **não instalar nem modificar**; possível origem de `.pth`/`.index` para `data/voice/models/rvc/<id>/` — não testado |
| Modelo RVC neutro pt-BR | primeira voz de personagem e teste RVC ponta a ponta | nenhum com licença clara: voice-models.com não tem pt-BR neutro; Adam (ElevenLabs), Jorge (Loquendo) e E-Girl têm licença não informada; no Hugging Face (16/11/2026) só imitações de personagem/dublador sem licença → **não usar**; `user-voices.json` segue sem voz |
| Azure Speech (motor `azure`, REST sem SDK, WAV `riff-24khz-16bit-mono-pcm`) | 14 vozes neurais pt-BR `azure-*` (chave do usuário; plano F0 0,5 M caracteres/mês, informado) | **código pronto** (`AzureEngine` em `voice/app/engine.py`, card no painel), mas **sem chave real**: testado só com `urlopen` simulado → não validado; nenhuma dependência nova |
| Vozes SAPI do Windows (Microsoft Maria Desktop pt-BR; Daniel/Maria OneCore) | TTS local sem download | existem na máquina; não integradas (robóticas) |
| Vozes "do TikTok/CapCut" famosas (Galvão Bueno, Ludmilla, narrador do CapCut Pro) | — | proprietárias ou imitação de pessoa real → **não copiar**. Equivalentes genéricos já no catálogo: Edge (Antonio/Francisca/Thalita) e Google |
| APIs oficiais: YouTube Data API v3, TikTok Content Posting API, Instagram API with Instagram Login | envio pelo Publicador (`publisher/app/platforms/*_api.py`) | **código pronto, testado só com chamadas simuladas**; nenhuma conta conectada nem envio real. Fatos e limites em `doc/publicacao/PESQUISA.md` (rupload do Instagram a testar) |
| Modo sessão logada (YouTube Studio, TikTok Studio, instagram.com) | envio pelo site com a sessão do usuário | **código pronto, seletores não validados com conta real**; viola os termos das redes |
| Chat do YouTube no Clipador | sinal de chat em lives do YouTube | exige a API do YouTube; não integrado (hoje só áudio + transcrição) |
| Saída AVI/MJPEG do Movie Maker | reduzir o tempo gasto em PNG | ideia; não medida |
Não afirme que uma candidata "funciona" ou "está integrada" até haver evidência registrada aqui.
## Como avaliar e adotar uma ferramenta nova
Antes de integrar, registre nesta tabela a resposta a cada item:
1. **Origem e licença** — fonte oficial, licença de uso dos arquivos gerados, custo.
2. **Interface** — CLI, API ou só interface gráfica; precisa de rede/conta? Funciona offline?
3. **Saída** — formato (GLB, FBX, WAV…), escala, orientação dos eixos, materiais, esqueleto,
animações incluídas. Lembre: rig corporal não garante lip sync nem atuação facial.
4. **Encaixe no pipeline** — onde entra (preparação de assets, nunca dentro do render), qual nó
adaptador corrige escala/orientação, como fica determinística.
5. **Teste mínimo** — um asset/arquivo real passando pelo render de prévia, com inspeção visual.
6. **Versão fixada** — versão exata testada, data, e onde o lançador a encontra.
Depois de adotada: mover para "Em uso", atualizar `scripts/lib/tools.ts` se o lançador a chama,
README e a tabela "Onde mexer" do `SKILL.md`. Dependência Python do serviço de voz: fixe a versão
em `voice/requirements*.txt`, peso novo em `voice/models.lock.json` com URL imutável (commit no
Hugging Face — nunca `resolve/main` — ou asset de release versionado no GitHub) e sha256, e rode `pnpm test:voice` + a fumaça.
@@ -0,0 +1,50 @@
"""Utilidades compartilhadas pelos scripts da skill cenaforge (só biblioteca padrão)."""
from __future__ import annotations
import json
import os
import shutil
import sys
from pathlib import Path
# .claude/skills/cenaforge/scripts/<arquivo> -> raiz do repositório
REPO_ROOT = Path(__file__).resolve().parents[4]
RUNS_DIR = REPO_ROOT / "output" / "runs"
LAST_SUCCESS = REPO_ROOT / "output" / "last-success.json"
def utf8_stdout() -> None:
"""Console do Windows pode vir em cp1252; acentos e '—' quebrariam."""
for stream in (sys.stdout, sys.stderr):
try:
stream.reconfigure(encoding="utf-8")
except (AttributeError, ValueError):
pass
def rel(path: Path) -> str:
try:
return path.resolve().relative_to(REPO_ROOT).as_posix()
except ValueError:
return str(path)
def load_json(path: Path) -> dict:
with open(path, encoding="utf-8") as f:
return json.load(f)
def find_tool(name: str) -> str | None:
"""Mesma ordem do lançador: variável de ambiente -> PATH -> .tools/ (só Godot)."""
env = {"godot": "GODOT_BIN", "ffmpeg": "FFMPEG_BIN", "ffprobe": "FFPROBE_BIN"}[name]
if os.environ.get(env):
return os.environ[env] if Path(os.environ[env]).is_file() else None
for candidate in ([name, "godot4"] if name == "godot" else [name]):
found = shutil.which(candidate)
if found:
return found
if name == "godot":
pattern = "Godot_v*-stable_win64.exe" if os.name == "nt" else "Godot_v*-stable_linux.x86_64"
for exe in sorted((REPO_ROOT / ".tools").glob(f"godot-*/{pattern}"), reverse=True):
return str(exe)
return None
@@ -0,0 +1,174 @@
#!/usr/bin/env python3
"""Confere um roteiro (.md) e os JSON da história sem LLM: duração, narração, trechos e campos.
Mesmas regras do leitor de roteiro do painel (panel/src/lib/script-doc.ts):
- duração alvo = linha de metadados "Duração: 60 s" (antes do primeiro "##");
- trechos = primeira tabela cuja 1ª coluna é o tempo ("t (s)" / "Tempo");
- narração lida a 2,5 palavras por segundo (doc/roteiro/comum.md).
Confere também, na pasta da história: meta.json (title ≤ 60, logline) e *.choices.json
(opções ≤ 60 caracteres, distintas).
Uso:
python .claude/skills/cenaforge/scripts/check_script.py stories/<história>/ep01.md
python .claude/skills/cenaforge/scripts/check_script.py stories/<história> (todos os ep*.md)
Saída: poucas linhas; código 0 = ok, 2 = há avisos, 1 = erro de leitura.
"""
from __future__ import annotations
import argparse
import json
import re
from pathlib import Path
from _common import rel, utf8_stdout
WORDS_PER_SECOND = 2.5
TOLERANCE = 0.15
MAX_LABEL = 60
WORD = re.compile(r"[^\W_][\w'’-]*", re.UNICODE)
def count_words(text: str) -> int:
return len(WORD.findall(re.sub(r"[*_`\"“”]", " ", text)))
def split_row(line: str) -> list[str]:
return [c.strip() for c in line.strip().strip("|").split("|")]
def is_separator(line: str) -> bool:
return bool(re.match(r"^\s*\|?\s*:?-{2,}:?\s*(\|\s*:?-{2,}:?\s*)*\|?\s*$", line))
def parse(markdown: str):
lines = markdown.replace("\r\n", "\n").split("\n")
meta, body, seen_h2 = [], [], False
for line in lines:
if line.startswith("## "):
seen_h2 = True
if not seen_h2 and line.strip() and not line.startswith("# "):
meta.append(line.strip())
if seen_h2:
body.append(line)
target = None
for part in (p for m in meta for p in re.split(r"\s+·\s+", m)):
m = re.match(r"^([^:]{2,40}):\s*(.+)$", part)
if m and re.search(r"dura[cç][aã]o", m.group(1), re.I):
num = re.search(r"\d+", m.group(2))
target = int(num.group()) if num else None
shots = []
for i, line in enumerate(body):
if line.strip().startswith("|") and i + 1 < len(body) and is_separator(body[i + 1]):
header = split_row(line)
if not re.match(r"^t\b|tempo", header[0] if header else "", re.I):
continue
col = lambda pattern: next((k for k, h in enumerate(header) if re.search(pattern, h, re.I)), -1)
narr, visual = col(r"narra|di[aá]logo|fala"), col(r"imagem|b-?roll|visual")
j = i + 2
while j < len(body) and body[j].strip().startswith("|"):
row = split_row(body[j])
nums = [float(n.replace(",", ".")) for n in re.findall(r"\d+(?:[.,]\d+)?", row[0] if row else "")]
shots.append({
"time": row[0] if row else "",
"start": nums[0] if nums else None,
"end": nums[1] if len(nums) > 1 else None,
"narration": row[narr] if 0 <= narr < len(row) else "",
"visual": row[visual] if 0 <= visual < len(row) else "",
"has_visual_col": visual >= 0,
})
j += 1
break
return target, shots
def check_episode(path: Path) -> list[str]:
target, shots = parse(path.read_text(encoding="utf-8"))
words = sum(count_words(s["narration"]) for s in shots)
spoken = words / WORDS_PER_SECOND
warnings: list[str] = []
head = f"{rel(path)}: {len(shots)} trechos · narração {words} palavras ≈ {spoken:.0f} s"
head += f" · alvo {target} s" if target else " · SEM duração alvo"
print(head)
if not target:
warnings.append("falta a linha 'Duração: <n> s' antes do primeiro '##'")
elif abs(spoken - target) > TOLERANCE * target:
warnings.append(f"narração ({spoken:.0f} s) foge mais de {TOLERANCE:.0%} do alvo ({target} s)")
if not shots:
warnings.append("sem tabela de trechos (1ª coluna 't (s)')")
previous_end = None
for n, shot in enumerate(shots, 1):
if shot["start"] is not None and previous_end is not None and abs(shot["start"] - previous_end) > 0.05:
warnings.append(f"trecho {n} ({shot['time']}): começa em {shot['start']:g}, o anterior terminou em {previous_end:g}")
if shot["start"] is not None and shot["end"] is not None:
length = shot["end"] - shot["start"]
need = count_words(shot["narration"]) / WORDS_PER_SECOND
if length <= 0:
warnings.append(f"trecho {n} ({shot['time']}): tempo inválido")
elif need > length + 0.5:
warnings.append(f"trecho {n} ({shot['time']}): narração pede {need:.1f} s em {length:g} s")
if shot["has_visual_col"] and not shot["visual"]:
warnings.append(f"trecho {n} ({shot['time']}): coluna Imagem vazia")
previous_end = shot["end"] if shot["end"] is not None else previous_end
if shots and target and previous_end is not None and abs(previous_end - target) > 1:
warnings.append(f"último trecho termina em {previous_end:g} s; alvo {target} s")
return warnings
def check_story_json(story_dir: Path) -> list[str]:
warnings: list[str] = []
meta = story_dir / "meta.json"
if meta.is_file():
try:
data = json.loads(meta.read_text(encoding="utf-8"))
title = str(data.get("title") or "")
if not title or len(title) > MAX_LABEL:
warnings.append(f"meta.json: title vazio ou com mais de {MAX_LABEL} caracteres ({len(title)})")
if not str(data.get("logline") or "").strip():
warnings.append("meta.json: logline vazia")
except json.JSONDecodeError as error:
warnings.append(f"meta.json inválido: {error}")
for choices in sorted(story_dir.glob("*.choices.json")):
try:
data = json.loads(choices.read_text(encoding="utf-8"))
except json.JSONDecodeError as error:
warnings.append(f"{choices.name} inválido: {error}")
continue
labels = [str(v).strip() for v in data.values()] if isinstance(data, dict) else []
if not labels:
warnings.append(f"{choices.name}: esperado objeto {{\"A\": \"...\", \"B\": \"...\"}}")
for letter, label in (data.items() if isinstance(data, dict) else []):
if not str(label).strip() or len(str(label)) > MAX_LABEL:
warnings.append(f"{choices.name}: opção {letter} vazia ou com mais de {MAX_LABEL} caracteres")
if len({l.lower() for l in labels}) < len(labels):
warnings.append(f"{choices.name}: opções repetidas")
return warnings
def main() -> int:
utf8_stdout()
ap = argparse.ArgumentParser(description="Confere roteiro e JSON da história, sem LLM.")
ap.add_argument("target", help="episódio .md ou pasta da história")
args = ap.parse_args()
target = Path(args.target).resolve()
if target.is_dir():
story_dir, episodes = target, sorted(target.glob("ep*.md"))
elif target.is_file():
story_dir, episodes = target.parent, [target]
else:
print("não encontrado:", args.target)
return 1
warnings: list[str] = []
for episode in episodes:
warnings += check_episode(episode)
warnings += check_story_json(story_dir)
for w in warnings[:20]:
print(" AVISO " + w)
if len(warnings) > 20:
print(f" ... e mais {len(warnings) - 20} avisos")
print("ok" if not warnings else f"{len(warnings)} aviso(s)")
return 2 if warnings else 0
if __name__ == "__main__":
raise SystemExit(main())
@@ -0,0 +1,53 @@
#!/usr/bin/env python3
"""Autoverificação da skill cenaforge: caminhos citados existem, comandos pnpm existem e a
versão do SKILL.md bate com o topo do CHANGELOG. Sai com 1 se houver problema.
Uso: python .claude/skills/cenaforge/scripts/check_skill.py
"""
from __future__ import annotations
import re
from _common import REPO_ROOT, load_json, utf8_stdout
SKILL = REPO_ROOT / ".claude" / "skills" / "cenaforge"
TEMPORARY = {"godot/override.cfg"}
ROOTS = ("godot/", "scripts/", "config/", "doc/", ".claude/")
def main() -> int:
utf8_stdout()
files = [*SKILL.rglob("*.md"), *(REPO_ROOT / ".claude" / "agents").glob("cenaforge-*.md"), REPO_ROOT / "CLAUDE.md"]
scripts = load_json(REPO_ROOT / "package.json")["scripts"]
problems: list[str] = []
for f in files:
name = f.relative_to(REPO_ROOT).as_posix()
text = f.read_text(encoding="utf-8")
for p in re.findall(r"`([^`\s]+)`", text):
if not p.startswith(ROOTS) or any(c in p for c in "<*{") or p in TEMPORARY:
continue
if not (REPO_ROOT / p.split(":")[0]).exists():
problems.append(f"{name}: caminho inexistente `{p}`")
for link in re.findall(r"\]\(([^)#\s]+)\)", text):
if not link.startswith("http") and not (f.parent / link).exists():
problems.append(f"{name}: link quebrado ({link})")
for cmd in re.findall(r"`pnpm (?:run )?([a-z][a-z:-]*)", text):
if cmd not in scripts and cmd not in {"install", "exec"}:
problems.append(f"{name}: comando inexistente `pnpm {cmd}`")
skill_text = (SKILL / "SKILL.md").read_text(encoding="utf-8")
version = re.search(r"Versão da skill: ([\d.]+)", skill_text)
top = re.search(r"^## ([\d.]+)", (SKILL / "CHANGELOG.md").read_text(encoding="utf-8"), re.M)
if not version or not top or version.group(1) != top.group(1):
problems.append(f"versão do SKILL.md ({version and version.group(1)}) diferente do topo do CHANGELOG ({top and top.group(1)})")
lines = len(skill_text.splitlines())
if lines > 220:
problems.append(f"SKILL.md com {lines} linhas (meta: até ~200)")
if problems:
print("\n".join(problems))
return 1
print(f"skill ok (versão {version.group(1)}, SKILL.md com {lines} linhas, {len(files)} arquivos conferidos)")
return 0
if __name__ == "__main__":
raise SystemExit(main())
@@ -0,0 +1,52 @@
#!/usr/bin/env python3
"""Limpa output/runs/: remove execuções com falha ou canceladas e sucessos antigos, mantendo os
N mais recentes por (configuração, perfil). Nunca remove a execução de last-success.json.
Por padrão só MOSTRA o que removeria. Use --apply para apagar.
Uso: python .claude/skills/cenaforge/scripts/clean_runs.py [--keep 2] [--apply]
"""
from __future__ import annotations
import argparse
import shutil
from collections import defaultdict
from _common import LAST_SUCCESS, RUNS_DIR, load_json, rel, utf8_stdout
def main() -> int:
utf8_stdout()
ap = argparse.ArgumentParser(description="Limpa execuções antigas de output/runs/.")
ap.add_argument("--keep", type=int, default=2, help="sucessos mantidos por configuração e perfil")
ap.add_argument("--apply", action="store_true", help="apaga de fato (sem isto, só simula)")
args = ap.parse_args()
protected = load_json(LAST_SUCCESS).get("runDir") if LAST_SUCCESS.is_file() else None
kept: dict[tuple, int] = defaultdict(int)
remove: list[tuple] = []
for run in sorted((p for p in RUNS_DIR.glob("*") if p.is_dir()), reverse=True):
if rel(run) == protected:
continue
report = run / "report.json"
r = load_json(report) if report.is_file() else {}
if r.get("status") != "success":
remove.append((run, r.get("status", "sem report.json")))
continue
key = (r.get("configSource"), r.get("profile"))
kept[key] += 1
if kept[key] > args.keep:
remove.append((run, "sucesso antigo"))
if not remove:
print("nada a remover")
return 0
for run, why in remove:
print(f"{'removido' if args.apply else 'removeria'}: {run.name} ({why})")
if args.apply:
shutil.rmtree(run)
if not args.apply:
print("(simulação; use --apply para apagar)")
return 0
if __name__ == "__main__":
raise SystemExit(main())
@@ -0,0 +1,178 @@
#!/usr/bin/env python3
"""Confere um render sem abrir imagens: resume o log e mede cada quadro de inspeção.
Economiza tokens: o agente lê ~10 linhas de texto e só abre UMA imagem (a folha de 480 px)
quando o veredito pede; um quadro solto só quando a linha dele vier marcada.
Mede em cada `inspect/t*.png`:
- luminância média (0–1): ESCURO < 0,08, ESTOURADO > 0,92;
- contraste (desvio padrão da luminância): CHAPADO < 0,04 (céu/chão liso, câmera no vazio);
- movimento em relação ao quadro anterior: PARADO quando nada muda entre os instantes;
- enquadramento: caixa e centro do "detalhe" (bordas). FORA quando o centro do detalhe foge
mais de 30% do centro, ou quando a caixa encosta numa borda e ocupa < 15% da altura.
Uso:
python .claude/skills/cenaforge/scripts/frame_check.py output/runs/<execução>
python .claude/skills/cenaforge/scripts/frame_check.py --config data/tmp/<id>-teste.json
(renderiza o perfil preview e confere em seguida; --profile para outro perfil)
python .claude/skills/cenaforge/scripts/frame_check.py --last (último render do disco)
"""
from __future__ import annotations
import argparse
import os
import re
import subprocess
from pathlib import Path
from _common import REPO_ROOT, RUNS_DIR, load_json, rel, utf8_stdout
DARK, BRIGHT, FLAT, STILL, OFF_CENTER = 0.08, 0.92, 0.04, 0.004, 0.30
LOG_TAIL = 15
def run_render(config: str, profile: str) -> tuple[Path | None, int]:
"""Roda o lançador e devolve a pasta da execução. Só imprime o fim do log se falhar."""
pnpm = "pnpm.cmd" if os.name == "nt" else "pnpm"
cmd = [pnpm, "render", "--", "--config", config, "--profile", profile]
proc = subprocess.run(cmd, cwd=REPO_ROOT, capture_output=True, text=True, encoding="utf-8", errors="replace")
output = (proc.stdout or "") + (proc.stderr or "")
match = re.search(r"->\s*(output[\\/]runs[\\/][^\s]+)", output)
run_dir = (REPO_ROOT / match.group(1)).resolve() if match else None
if proc.returncode != 0:
lines = [l for l in output.splitlines() if l.strip()]
print(f"render FALHOU (código {proc.returncode}). Últimas {LOG_TAIL} linhas do log:")
for line in lines[-LOG_TAIL:]:
print(" " + line[:220])
return run_dir, proc.returncode
def summarize_report(run_dir: Path) -> bool:
report_path = run_dir / "report.json"
if not report_path.is_file():
print("sem report.json em", rel(run_dir))
return False
report = load_json(report_path)
timings = report.get("timingsSeconds") or {}
video = report.get("video") or report.get("output") or {}
size = f"{video.get('width', '?')}x{video.get('height', '?')}" if isinstance(video, dict) else "?"
print(f"status {report.get('status')} · {rel(run_dir)} · {size} · total {timings.get('total', '?')} s"
f" (godot {timings.get('godotRender', '-')} s)")
failed = [c for c in report.get("checks") or [] if not c.get("ok")]
for check in failed[:8]:
print(f" FALHA {check.get('name')} — {check.get('detail')}")
for warning in (report.get("warnings") or [])[:5]:
print(f" AVISO {warning}")
if report.get("error"):
print(f" erro na etapa {report.get('failedStage')}: {str(report['error'])[:300]}")
return report.get("status") == "success"
def frame_stats(image, previous):
from PIL import ImageChops, ImageFilter, ImageStat
gray = image.convert("L")
stat = ImageStat.Stat(gray)
mean, std = stat.mean[0] / 255, stat.stddev[0] / 255
edges = gray.filter(ImageFilter.FIND_EDGES).point(lambda v: 255 if v > 40 else 0)
# Ignora 2 px da borda (o filtro marca a moldura).
w, h = edges.size
edges = edges.crop((2, 2, w - 2, h - 2))
box = edges.getbbox()
centroid = None
if box:
small = edges.resize((64, 64))
data = small.tobytes()
total = sum(data) or 1
cx = sum((i % 64) * v for i, v in enumerate(data)) / total / 63
cy = sum((i // 64) * v for i, v in enumerate(data)) / total / 63
centroid = (cx, cy)
motion = None
if previous is not None:
diff = ImageChops.difference(gray.resize((135, 240)), previous.resize((135, 240)))
motion = ImageStat.Stat(diff).mean[0] / 255
return gray, mean, std, box, (w - 4, h - 4), centroid, motion
def check_frames(run_dir: Path) -> int:
try:
from PIL import Image
except ImportError:
print("PIL não instalado: sem métricas de quadro. Abra só inspect/contact-sheet.png.")
return 0
frames = sorted((run_dir / "inspect").glob("t*.png"))
if not frames:
print("sem quadros em inspect/ (render falhou antes da etapa 6?)")
return 1
flagged: list[str] = []
previous = None
for frame in frames:
with Image.open(frame) as img:
gray, mean, std, box, (w, h), centroid, motion = frame_stats(img, previous)
previous = gray
tags = []
if mean < DARK:
tags.append("ESCURO")
if mean > BRIGHT:
tags.append("ESTOURADO")
if std < FLAT:
tags.append("CHAPADO")
if motion is not None and motion < STILL:
tags.append("PARADO")
framing = "sem detalhe"
if box and centroid:
x0, y0, x1, y1 = box
framing = (f"detalhe x {x0 / w:.0%}–{x1 / w:.0%} y {y0 / h:.0%}–{y1 / h:.0%}"
f" centro ({centroid[0]:.2f},{centroid[1]:.2f})")
touches = x0 <= 1 or y0 <= 1 or x1 >= w - 1 or y1 >= h - 1
if max(abs(centroid[0] - 0.5), abs(centroid[1] - 0.5)) > OFF_CENTER or (touches and (y1 - y0) / h < 0.15):
tags.append("FORA")
elif std >= FLAT:
tags.append("FORA")
move = f" mov {motion:.3f}" if motion is not None else ""
verdict = " ".join(tags) or "ok"
print(f" {frame.stem:>7}: luz {mean:.2f} contraste {std:.2f}{move} · {framing} · {verdict}")
if tags:
flagged.append(frame.name)
sheet = run_dir / "inspect" / "contact-sheet.png"
if flagged:
print(f"ATENÇÃO em {len(flagged)} quadro(s). Abra só: {rel(run_dir / 'inspect' / flagged[0])}"
+ (f" (e os demais marcados se precisar: {', '.join(flagged[1:])})" if len(flagged) > 1 else ""))
return 2
print(f"métricas ok. Para a revisão visual abra só UMA imagem: {rel(sheet) if sheet.is_file() else rel(frames[0])}")
return 0
def main() -> int:
utf8_stdout()
ap = argparse.ArgumentParser(description="Resumo do render e métricas dos quadros, sem LLM.")
ap.add_argument("run", nargs="?", help="pasta da execução (output/runs/<execução>)")
ap.add_argument("--config", help="renderiza esta cena antes de conferir")
ap.add_argument("--profile", default="preview")
ap.add_argument("--last", action="store_true", help="usa a execução mais recente de output/runs/")
args = ap.parse_args()
if args.config:
run_dir, code = run_render(args.config, args.profile)
if run_dir is None:
print("não achei a pasta da execução na saída do render")
return code or 1
elif args.last:
runs = sorted((p for p in RUNS_DIR.iterdir() if p.is_dir()), key=lambda p: p.name) if RUNS_DIR.is_dir() else []
if not runs:
print("nenhuma execução em", rel(RUNS_DIR))
return 1
run_dir = runs[-1]
elif args.run:
run_dir = Path(args.run).resolve()
else:
ap.error("informe a pasta da execução, --config ou --last")
return 1
ok = summarize_report(run_dir)
result = check_frames(run_dir)
return result if ok else 1
if __name__ == "__main__":
raise SystemExit(main())
@@ -0,0 +1,100 @@
#!/usr/bin/env python3
"""Gera doc/godot/api.md: o resumo das peças (godot/kits/) e das cenas da biblioteca (godot/library/).
Para o agente que constrói cenas ler ~100 linhas de assinaturas em vez de ~1.700 de GDScript.
Extrai de cada .gd o cabeçalho "##" do topo e as funções públicas (sem "_") com os "##" logo acima;
de cada manifest.json, o rótulo, a descrição e os parâmetros.
Uso (na raiz do repositório): python .claude/skills/cenaforge/scripts/godot_api.py
Rode de novo sempre que uma peça ou cena mudar (o agente da tarefa "Cena no Godot" também roda).
"""
from __future__ import annotations
import json
import re
import sys
from pathlib import Path
ROOT = Path(__file__).resolve().parents[4]
OUT = ROOT / "doc" / "godot" / "api.md"
FUNC = re.compile(r"^(static\s+)?func\s+([A-Za-z]\w*)\s*\((.*?)\)\s*(->\s*[\w\[\], ]+)?\s*:")
def summarize_gd(path: Path) -> list[str]:
lines = path.read_text(encoding="utf-8").splitlines()
out: list[str] = []
# Cabeçalho: os "##" do topo (depois de extends/class_name).
header: list[str] = []
for line in lines[:40]:
s = line.strip()
if s.startswith("##"):
header.append(s[2:].strip())
elif header and not s:
break
elif s and not s.startswith(("extends", "class_name", "@")):
if header:
break
if header:
out.append("> " + "\n> ".join(h for h in header if h))
funcs: list[str] = []
for i, line in enumerate(lines):
m = FUNC.match(line)
if not m or m.group(2).startswith("_"):
continue
doc: list[str] = []
j = i - 1
while j >= 0 and lines[j].strip().startswith("##"):
doc.insert(0, lines[j].strip()[2:].strip())
j -= 1
sig = f"{'static ' if m.group(1) else ''}{m.group(2)}({m.group(3)}){(' ' + m.group(4).strip()) if m.group(4) else ''}"
funcs.append(f"- `{sig}`" + (f": {' '.join(doc)}" if doc else ""))
if funcs:
out.append("")
out.extend(funcs)
return out
def summarize_manifest(path: Path) -> list[str]:
try:
m = json.loads(path.read_text(encoding="utf-8"))
except (OSError, json.JSONDecodeError) as e:
return [f"- manifest.json ilegível: {e}"]
out = [f"**{m.get('label', path.parent.name)}** ({m.get('kind', 'doc3d')}): {m.get('description', '')}"]
for p in m.get("params", []):
if p.get("type") == "select":
opts = ", ".join(str(o.get("value")) for o in p.get("options", []))
out.append(f"- param `{p.get('name')}` (select: {opts}; padrão {p.get('default')!r})")
else:
out.append(f"- param `{p.get('name')}` ({p.get('type')}; padrão {p.get('default')!r})")
return out
def main() -> int:
parts = [
"# API das peças e cenas do Godot (gerado)",
"",
"Gerado por `python .claude/skills/cenaforge/scripts/godot_api.py`. Não edite à mão: rode de novo",
"quando uma peça ou cena mudar. Use estas funções sem abrir os .gd inteiros.",
"",
"## Peças (`godot/kits/`, use com `preload(\"res://kits/<arquivo>.gd\")`)",
]
for gd in sorted((ROOT / "godot" / "kits").glob("*.gd")):
parts += ["", f"### `{gd.relative_to(ROOT).as_posix()}`", *summarize_gd(gd)]
parts += ["", "## Cenas da biblioteca (`godot/library/<id>/`)"]
for scene in sorted(p for p in (ROOT / "godot" / "library").iterdir() if p.is_dir()):
parts += ["", f"### `{scene.name}`"]
manifest = scene / "manifest.json"
if manifest.exists():
parts += summarize_manifest(manifest)
for gd in sorted(scene.glob("*.gd")):
summary = summarize_gd(gd)
if summary:
parts += ["", f"`{gd.relative_to(ROOT).as_posix()}`", *summary]
OUT.parent.mkdir(parents=True, exist_ok=True)
OUT.write_text("\n".join(parts) + "\n", encoding="utf-8")
print(f"{OUT.relative_to(ROOT).as_posix()}: {len(parts)} linhas")
return 0
if __name__ == "__main__":
sys.exit(main())
@@ -0,0 +1,72 @@
#!/usr/bin/env python3
"""Gera uma tira com 1 quadro por segundo de um MP4 (qualquer FPS e duração).
Economiza tokens: o agente lê UMA imagem em vez de vários quadros soltos.
Saída: <pasta da execução>/inspect/strip.png (ou ao lado do MP4).
Uso:
python .claude/skills/cenaforge/scripts/inspect_strip.py output/runs/<execução>
python .claude/skills/cenaforge/scripts/inspect_strip.py video.mp4 --width 160
"""
from __future__ import annotations
import argparse
import json
import math
import subprocess
from pathlib import Path
from _common import find_tool, rel, utf8_stdout
def main() -> int:
utf8_stdout()
ap = argparse.ArgumentParser(description="Tira de 1 quadro por segundo de um MP4.")
ap.add_argument("target", help="pasta de execução ou arquivo .mp4")
ap.add_argument("--width", type=int, default=180, help="largura de cada quadro na tira")
ap.add_argument("--cols", type=int, default=7)
args = ap.parse_args()
target = Path(args.target).resolve()
if target.is_dir():
mp4s = sorted(target.glob("*.mp4"))
if not mp4s:
print("nenhum .mp4 em", rel(target))
return 1
mp4, out_dir = mp4s[0], target / "inspect"
else:
mp4, out_dir = target, target.parent
ffmpeg, ffprobe = find_tool("ffmpeg"), find_tool("ffprobe")
if not ffmpeg or not ffprobe:
print("ffmpeg/ffprobe não encontrados (PATH ou FFMPEG_BIN/FFPROBE_BIN)")
return 1
probe = subprocess.run(
[ffprobe, "-v", "error", "-select_streams", "v:0", "-count_frames",
"-show_entries", "stream=r_frame_rate,nb_read_frames", "-of", "json", str(mp4)],
capture_output=True, text=True)
if probe.returncode != 0:
print("ffprobe falhou:", probe.stderr.strip()[-300:])
return 1
stream = json.loads(probe.stdout)["streams"][0]
num, den = (int(x) for x in stream["r_frame_rate"].split("/"))
fps = round(num / den)
count = math.ceil(int(stream["nb_read_frames"]) / fps)
cols = min(args.cols, count)
rows = math.ceil(count / cols)
out_dir.mkdir(parents=True, exist_ok=True)
out = out_dir / "strip.png"
vf = f"select='not(mod(n\\,{fps}))',scale={args.width}:-1,tile={cols}x{rows}"
r = subprocess.run([ffmpeg, "-hide_banner", "-loglevel", "error", "-y", "-i", str(mp4),
"-vf", vf, "-frames:v", "1", "-fps_mode", "vfr", str(out)],
capture_output=True, text=True)
if r.returncode != 0:
print("ffmpeg falhou:", r.stderr.strip()[-300:])
return 1
print(f"{rel(out)} ({count} quadros, 0..{count - 1} s, grade {cols}x{rows}, {fps} FPS)")
return 0
if __name__ == "__main__":
raise SystemExit(main())
@@ -0,0 +1,86 @@
#!/usr/bin/env python3
"""Cria config/<id>.json a partir de uma cena base, com alterações por caminho, e valida na Godot.
Economiza tokens: o agente não lê nem reescreve o JSON inteiro para mudar poucos campos.
Uso:
python .claude/skills/cenaforge/scripts/new_scene.py --id ep01-cena02 \\
--set overlay.title="Um pacote sem remetente." --set rider.travelMeters=36 \\
--set camera.offset=[1.2,2.8,5.6]
Opções: --base (padrão config/demo-street.json), --force (sobrescreve), --no-validate.
Valores são lidos como JSON quando possível (números, listas, true, null); senão, como texto.
"""
from __future__ import annotations
import argparse
import json
import re
import subprocess
from pathlib import Path
from _common import REPO_ROOT, find_tool, load_json, rel, utf8_stdout
def parse_value(raw: str):
try:
return json.loads(raw)
except json.JSONDecodeError:
return raw
def main() -> int:
utf8_stdout()
ap = argparse.ArgumentParser(description="Cria uma cena nova a partir de outra.")
ap.add_argument("--id", required=True)
ap.add_argument("--base", default="config/demo-street.json")
ap.add_argument("--set", action="append", default=[], metavar="caminho=valor")
ap.add_argument("--force", action="store_true")
ap.add_argument("--no-validate", action="store_true")
args = ap.parse_args()
if not re.fullmatch(r"[a-z0-9][a-z0-9_-]{0,63}", args.id):
print("id inválido: use minúsculas, números, '-' e '_'")
return 2
base = Path(args.base) if Path(args.base).is_absolute() else REPO_ROOT / args.base
scene = load_json(base)
scene["id"] = args.id
for item in args.set:
if "=" not in item:
print(f"--set sem '=': {item}")
return 2
path, raw = item.split("=", 1)
keys = path.split(".")
node = scene
for k in keys[:-1]:
if not isinstance(node.get(k), dict):
print(f"caminho inexistente na cena base: {path}")
return 2
node = node[k]
node[keys[-1]] = parse_value(raw)
out = REPO_ROOT / "config" / f"{args.id}.json"
if out.exists() and not args.force:
print(f"{rel(out)} já existe (use --force)")
return 2
text = json.dumps(scene, ensure_ascii=False, indent=2)
# Vetores [x, y, z] numa linha só, como nos exemplos do projeto.
text = re.sub(r"\[\s*([-\d.eE]+),\s*([-\d.eE]+),\s*([-\d.eE]+)\s*\]", r"[\1, \2, \3]", text)
out.write_text(text + "\n", encoding="utf-8", newline="\n")
print("criado", rel(out))
if args.no_validate:
return 0
godot = find_tool("godot")
if not godot:
print("Godot não encontrada; validação pulada (pnpm render valida antes de renderizar)")
return 0
r = subprocess.run([godot, "--headless", "--path", str(REPO_ROOT / "godot"), "--",
"--config", str(out), "--validate-only"],
capture_output=True, text=True, encoding="utf-8", errors="replace")
lines = [l for l in (r.stdout + r.stderr).splitlines() if l.startswith(("CONFIG_", " - "))]
print("\n".join(lines) or f"validação saiu com código {r.returncode}")
return 0 if r.returncode == 0 else 1
if __name__ == "__main__":
raise SystemExit(main())
@@ -0,0 +1,64 @@
#!/usr/bin/env python3
"""Resumo compacto das execuções em output/runs/.
Economiza tokens: em vez de ler report.json/render.log inteiros, imprime uma linha por
execução com status, perfil, verificações, tempos e digest.
Uso:
python .claude/skills/cenaforge/scripts/runs_summary.py # últimas 10
python .claude/skills/cenaforge/scripts/runs_summary.py --last 3 --details
python .claude/skills/cenaforge/scripts/runs_summary.py --run <pasta> --details
"""
from __future__ import annotations
import argparse
from pathlib import Path
from _common import LAST_SUCCESS, RUNS_DIR, load_json, rel, utf8_stdout
def main() -> int:
utf8_stdout()
ap = argparse.ArgumentParser(description="Resumo compacto das execuções de render.")
ap.add_argument("--last", type=int, default=10, help="quantas execuções mostrar (mais novas)")
ap.add_argument("--run", help="uma pasta de execução específica")
ap.add_argument("--details", action="store_true", help="falhas, avisos, MP4 e imagem de inspeção")
args = ap.parse_args()
if args.run:
runs = [Path(args.run).resolve()]
else:
runs = sorted((p for p in RUNS_DIR.glob("*") if (p / "report.json").is_file()), reverse=True)[: args.last]
if not runs:
print("nenhuma execução encontrada em", rel(RUNS_DIR))
return 1
last_ok = load_json(LAST_SUCCESS).get("runDir") if LAST_SUCCESS.is_file() else None
print("status perfil total_s godot_s checks digest execução")
for run in runs:
r = load_json(run / "report.json")
checks = r.get("checks", [])
failed = [c for c in checks if not c.get("ok")]
t = r.get("timingsSeconds", {})
digest = ((r.get("godot") or {}).get("stateDigest") or "-")[:8]
mark = " *" if last_ok and rel(run) == last_ok else ""
print(f"{r.get('status', '?'):9} {r.get('profile', '?'):8} {t.get('total', '-'):>8} {t.get('godotRender', '-'):>8}"
f" {len(checks) - len(failed):>2}/{len(checks):<3} {digest:9} {run.name}{mark}")
if args.details:
if r.get("error"):
print(f" erro ({r.get('failedStage')}): {r['error'].splitlines()[0]}")
for c in failed:
print(f" FALHA {c['name']}: {c['detail']}")
for w in r.get("warnings", []):
print(f" AVISO {w}")
if r.get("mp4"):
print(f" mp4: {r['mp4']}")
if r.get("inspection"):
print(f" inspeção: {r['inspection'][-1]}")
if last_ok:
print("* = output/last-success.json")
return 0
if __name__ == "__main__":
raise SystemExit(main())