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:
@@ -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.
|
||||
@@ -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())
|
||||
@@ -0,0 +1,68 @@
|
||||
---
|
||||
name: content-pipeline
|
||||
description: Metodologia de produção de vídeo curto do CenaForge em 8 etapas — 1 Pauta, 2 Roteiro, 3 Narração, 4 Cenas, 5 Montagem, 6 Shorts (formato e versões por rede), 7 Thumbnail (capa), 8 Agenda (aprovação, agendamento e publicação) — com portões de "pronto" entre as etapas. Vale para os dois trilhos: HISTÓRIA (episódios animados com votação) e CORTE DE LIVE (Clipador). Use sempre que o pedido envolver planejar, escrever, narrar, montar, empacotar, criar capa, aprovar, agendar ou publicar um vídeo, definir calendário/frequência, revisar gancho/retenção, ou "seguir a metodologia" — mesmo que o usuário cite só uma etapa.
|
||||
---
|
||||
|
||||
# Produção de conteúdo — 8 etapas
|
||||
|
||||
**Versão 1.0.0** (16/11/2026). Pesquisa de plataformas datada em [references/platforms.md](references/platforms.md):
|
||||
**reverifique a cada 3 meses** ou quando uma regra parecer não bater (as redes mudam rápido).
|
||||
|
||||
Esta skill diz **o que fazer e quando está pronto**. O **como** técnico do CenaForge (render, Godot, voz,
|
||||
Clipador) está na skill `cenaforge` — use as duas juntas.
|
||||
|
||||
## Os dois trilhos
|
||||
|
||||
| Etapa | HISTÓRIA (episódio animado) | CORTE DE LIVE (Clipador) |
|
||||
|---|---|---|
|
||||
| 1 Pauta | ideia/arco da série → `stories/<id>/pauta.md` | canais e critérios de momento → página Clipador (canais, juiz) |
|
||||
| 2 Roteiro | `stories/<id>/<file_key>.md` (subagente `cenaforge-story-writer`) | trecho escolhido + transcrição; gancho e contexto escritos pelo juiz/você |
|
||||
| 3 Narração | TTS/voz de personagem (serviço de voz) → WAV em `audio.file` | voz original do streamer; narração própria só como camada de contexto |
|
||||
| 4 Cenas | `config/<id>-<file_key>.json` + render Godot | não se aplica (o vídeo é a live) — escolher enquadramento |
|
||||
| 5 Montagem | MP4 do render + áudio + legenda | corte vertical, legenda palavra a palavra, crédito (Clipador) |
|
||||
| 6 Shorts | versões por rede (texto, hashtags, duração) | idem |
|
||||
| 7 Thumbnail | quadro-chave + título curto | quadro do pico + título curto |
|
||||
| 8 Agenda | aprovação → janela → publicação → métricas | idem (fila de aprovação do Clipador) |
|
||||
|
||||
Detalhe de cada etapa (objetivo, entradas, saída, regras, checklist "pronto quando", ferramenta, lacunas):
|
||||
[01 Pauta](references/01-pauta.md) · [02 Roteiro](references/02-roteiro.md) · [03 Narração](references/03-narracao.md) ·
|
||||
[04 Cenas](references/04-cenas.md) · [05 Montagem](references/05-montagem.md) · [06 Shorts](references/06-shorts.md) ·
|
||||
[07 Thumbnail](references/07-thumbnail.md) · [08 Agenda](references/08-agenda.md)
|
||||
|
||||
## Regras que valem em todas as etapas
|
||||
|
||||
1. **Portão entre etapas.** Só avance quando o checklist "pronto quando" da etapa atual passar. Se pular uma
|
||||
etapa (ex.: corte de live não tem Cenas), diga que pulou e por quê.
|
||||
2. **Ficha de produção.** Cada peça tem uma ficha ([templates/ficha.md](templates/ficha.md)) com o estado das 8
|
||||
etapas. História: `stories/<id>/<file_key>.ficha.md` e pauta em `stories/<id>/pauta.md` — **convenções desta
|
||||
skill**: crie a partir dos modelos quando faltarem; o painel ainda não lê esses arquivos. Corte: os campos do corte no Clipador já são a ficha
|
||||
(título, legenda, nota, status) — não duplique em arquivo.
|
||||
3. **Os 2 primeiros segundos decidem.** Toda decisão de roteiro, montagem e capa é julgada pela pergunta "isso
|
||||
segura quem está rolando o feed?". Gancho visual + texto na tela no 1º segundo.
|
||||
4. **Retenção > tamanho.** Corte tudo que não serve ao gancho ou ao pagamento. Duração é consequência.
|
||||
5. **Original e transformado.** Repost puro perde alcance (Instagram 2026) e pode perder monetização (YouTube,
|
||||
conteúdo reutilizado). Cortes de live precisam de transformação: contexto, gancho escrito, edição, legenda,
|
||||
crédito. Ver [platforms.md](references/platforms.md).
|
||||
6. **Nada vai ao ar sem aprovação humana** (decisão do usuário). A etapa 8 é aprovação primeiro, agenda depois.
|
||||
7. **Rótulo de IA** quando a peça tiver voz que imita pessoa real (RVC) ou imagem realista gerada por IA.
|
||||
8. **Medir e voltar.** Métrica de verdade vem do painel/analytics da rede; números de blog são ponto de partida,
|
||||
não meta. Depois de 2–4 semanas, troque as heurísticas pelos seus números.
|
||||
|
||||
## Como trabalhar com esta skill
|
||||
|
||||
- Pedido de uma etapa só ("faz a thumb", "agenda pra amanhã"): leia a referência daquela etapa e confira se as
|
||||
anteriores estão prontas na ficha; se não estiverem, avise antes de seguir.
|
||||
- Pedido de peça inteira ("faz o episódio 3", "solta os cortes de hoje"): percorra as 8 etapas em ordem,
|
||||
atualizando a ficha e parando nos portões que exigem o usuário (aprovação).
|
||||
- Texto (pauta, roteiro, títulos, legendas, A/B) vai para o subagente `cenaforge-story-writer` (modelo mais
|
||||
barato), passando a etapa e o checklist da referência.
|
||||
- Ao terminar, responda com: etapas feitas, artefatos (caminhos), o que ficou pendente e o próximo portão.
|
||||
|
||||
## Lacunas atuais do CenaForge (não finja que existem)
|
||||
|
||||
- **Thumbnail**: não há gerador; hoje é quadro extraído (FFmpeg) + título — ver [07](references/07-thumbnail.md).
|
||||
- **Agenda/publicação**: publicação automática existe (canais de publicação, API oficial ou sessão logada,
|
||||
página Publicações), mas **envio real ainda não validado com conta de verdade**; métricas continuam simuladas.
|
||||
Ver [08](references/08-agenda.md).
|
||||
- **Narração no render**: o render não chama o serviço de voz; o WAV é gerado à parte e apontado em `audio.file`.
|
||||
- **Legenda em episódio animado**: o Clipador queima legenda; o render da Godot ainda não.
|
||||
@@ -0,0 +1,38 @@
|
||||
# 1 — Pauta
|
||||
|
||||
**Objetivo:** decidir O QUE produzir e POR QUE alguém vai parar de rolar o feed por isso.
|
||||
**Saída:** item de pauta aprovado (modelo em [../templates/pauta.md](../templates/pauta.md)).
|
||||
|
||||
## Trilho HISTÓRIA
|
||||
|
||||
- Onde: `stories/<id>/pauta.md` (lista de ideias e arco da série) + `stories/<id>/biblia.md` (mundo, personagens).
|
||||
- Uma série é um **arco de 3–5 episódios** com escalada: cada parte acrescenta risco ou informação nova; a
|
||||
penúltima vira o jogo; a última paga. Cada episódio precisa funcionar **sozinho** para quem chegou agora.
|
||||
- Formato do painel (`STORY_FORMATS`): `interactive` (2–4 opções votadas nos comentários) ou `linear`.
|
||||
- Na interativa, a pauta já prevê as **duas escolhas** com custo e graça (nenhuma "certa" óbvia).
|
||||
|
||||
## Trilho CORTE DE LIVE
|
||||
|
||||
- A pauta é **quais canais** e **que tipo de momento**: canais no Clipador (monitorar, autorizado), nota mínima
|
||||
do juiz, nicho de cada conta (página Contas: conta ↔ canais).
|
||||
- Prefira canais com **permissão** (marca `authorized`). Sem permissão: risco de strike e, no Instagram/YouTube,
|
||||
de perder alcance/monetização por conteúdo reutilizado — ver [platforms.md](platforms.md).
|
||||
- Defina o **ângulo de transformação** da conta (ex.: "momentos de susto com contexto", "top reações da semana",
|
||||
"explicando o que aconteceu"). Conta só de repost puro deixa de ser recomendada no Instagram.
|
||||
|
||||
## Critérios de uma boa pauta (os dois trilhos)
|
||||
|
||||
1. Gancho em uma frase: "o que acontece nos 2 primeiros segundos?".
|
||||
2. Pagamento: o que o espectador ganha no fim (risada, susto, resposta, cliffhanger).
|
||||
3. Motivo de compartilhar: para quem a pessoa mandaria isso?
|
||||
4. Público e conta de destino definidos.
|
||||
5. Viável com o que o CenaForge faz hoje (senão, liste em "Necessidades de produção").
|
||||
|
||||
## Pronto quando
|
||||
|
||||
- [ ] gancho, pagamento e motivo de compartilhar escritos em uma linha cada;
|
||||
- [ ] conta(s) de destino definida(s);
|
||||
- [ ] (história) arco com nº de partes e escolha(s) do episódio; (corte) canal, permissão e ângulo definidos;
|
||||
- [ ] necessidades de produção listadas ou "nenhuma".
|
||||
|
||||
**Quem faz:** texto → `cenaforge-story-writer`; canais/juiz → página Clipador.
|
||||
@@ -0,0 +1,46 @@
|
||||
# 2 — Roteiro
|
||||
|
||||
**Objetivo:** transformar a pauta numa sequência de segundos em que nada sobra.
|
||||
**Saída:** história → `stories/<id>/<file_key>.md` (regras e formatos em `doc/roteiro/`: `comum.md` +
|
||||
`ficcao.md` ou `documental.md`, os mesmos para o Codex e para o `cenaforge-story-writer`); corte → trecho
|
||||
[início, fim] + título/legenda (campos do corte no Clipador).
|
||||
|
||||
## Estrutura de vídeo curto (os dois trilhos)
|
||||
|
||||
| Bloco | Tempo | Função |
|
||||
|---|---|---|
|
||||
| Gancho | 0–2 s | imagem forte + texto na tela; afirmação, pergunta ou ação já em andamento |
|
||||
| Contexto | até ~20% do vídeo | o mínimo para entender o que está em jogo |
|
||||
| Escalada | meio | cada beat aumenta a tensão/graça; troca visual a cada 2–4 s |
|
||||
| Pagamento | fim | a risada/susto/resposta — ou o cliffhanger/escolha (história interativa) |
|
||||
| Laço | último segundo | final que conversa com o começo ajuda a reassistir |
|
||||
|
||||
Fórmulas de gancho (escolha uma): curiosidade ("ele não sabia que…"), afirmação forte, começar no meio da ação,
|
||||
consequência antes da causa ("isso terminou com a moto no rio"), pergunta direta ao espectador.
|
||||
**Proibido:** prometer no gancho o que não acontece (gera "não tenho interesse" e derruba a distribuição).
|
||||
|
||||
## Trilho HISTÓRIA
|
||||
|
||||
- Siga o formato de `ep<NN>.md` de `doc/roteiro/ficcao.md` (cena a cena com `t (s)`, chamada final, campos de
|
||||
overlay, consequências, necessidades de produção). Limites: `overlay.title` ≤ 80 (ideal ≤ 30),
|
||||
`choiceA/B` ≤ 48 (ideal ≤ 24).
|
||||
- Episódio de série: abre com **recapitulação em 1 frase** (serve a quem chegou agora) e fecha em decisão ou
|
||||
gancho para a próxima parte.
|
||||
- Duração atual das cenas: ~12 s (render). Narração cabe em ~2,5 palavras/s.
|
||||
|
||||
## Trilho CORTE DE LIVE
|
||||
|
||||
- O roteiro é a **edição do trecho**: começar o mais perto possível do acontecimento (contexto mínimo), terminar
|
||||
logo depois da reação. O Clipador já propõe [início, fim] (chat + transcrição + juiz); revise na fila.
|
||||
- Escreva o **gancho em texto** para a tela/legenda do post (o juiz sugere o título). Isso é parte da
|
||||
transformação exigida em [platforms.md](platforms.md).
|
||||
- Duração: 15–59 s (padrão do Clipador). Shorts aceita até 3 min, mas mantenha cortes de terceiros ≤ 60 s.
|
||||
|
||||
## Pronto quando
|
||||
|
||||
- [ ] gancho cabe em 2 s e tem texto de tela;
|
||||
- [ ] cada beat tem motivo de existir (se tirar, a peça piora?);
|
||||
- [ ] fim paga o gancho (ou deixa escolha/cliffhanger claro);
|
||||
- [ ] (história) campos de overlay dentro dos limites e contados; (corte) início/fim revisados, título ≤ 70 chars.
|
||||
|
||||
**Quem faz:** `cenaforge-story-writer` (texto); ajuste de trecho → fila do Clipador.
|
||||
@@ -0,0 +1,36 @@
|
||||
# 3 — Narração
|
||||
|
||||
**Objetivo:** voz que carrega a história no ritmo do vídeo e casa com a legenda.
|
||||
**Saída:** história → WAV salvo no repositório e apontado em `audio.file` (`audio.enabled: true`) da cena;
|
||||
corte → normalmente nenhuma (a voz é a do streamer).
|
||||
|
||||
## Regras de ritmo (heurística — testar)
|
||||
|
||||
- Conversacional: **130–160 palavras/min** (~2,2–2,7 palavras/s). Acima de ~180/min cansa e a legenda não
|
||||
acompanha (leitura no celular ≈ 200–250 palavras/min). O roteiro do CenaForge usa ~2,5 palavras/s.
|
||||
- **Uma pausa estratégica** antes do ponto mais importante; corte silêncios mortos no resto.
|
||||
- Primeira palavra no **primeiro segundo** — narração que começa tarde perde o gancho.
|
||||
|
||||
## Trilho HISTÓRIA
|
||||
|
||||
- Serviço de voz (skill `cenaforge`, seção "Voz e legenda"): `POST /v1/synthesize` com `params.format: "wav"`;
|
||||
voz padrão `pt-br-antonio` (Edge); offline: Piper (`pt-br-faber`, `pt-br-cadu`). Página **Vozes** do painel
|
||||
para ouvir/testar (velocidade 0,5–2).
|
||||
- Personagem: voz de personagem (RVC) por personagem, registrada na bíblia. **Voz que imita pessoa real → rótulo
|
||||
de IA** na publicação (ver [platforms.md](platforms.md)).
|
||||
- Gere a legenda junto: `POST /v1/transcribe` com `X-Detail: words` sobre o WAV final (tempos por palavra).
|
||||
|
||||
## Trilho CORTE DE LIVE
|
||||
|
||||
- Voz original. Narração própria (TTS) só se for a **camada de transformação** (contexto de 1 frase no início:
|
||||
"o chat inteiro achou que ele ia morrer aqui…") — conta como comentário original para o YouTube.
|
||||
- Se usar, mixe a narração por cima com o áudio da live abaixado (ducking) — hoje isso é manual (FFmpeg).
|
||||
|
||||
## Pronto quando
|
||||
|
||||
- [ ] duração da fala ≤ duração da cena; ritmo dentro da faixa;
|
||||
- [ ] primeira palavra até 1 s; sem silêncio morto;
|
||||
- [ ] WAV final apontado na cena (história) e legenda com tempos gerada;
|
||||
- [ ] rótulo de IA decidido (sim/não) e anotado na ficha.
|
||||
|
||||
**Lacuna:** o render ainda não chama o serviço de voz sozinho.
|
||||
@@ -0,0 +1,29 @@
|
||||
# 4 — Cenas
|
||||
|
||||
**Objetivo:** imagem que mostra o roteiro, com algo mudando na tela a cada poucos segundos.
|
||||
**Saída:** história → `config/<id>-<file_key>.json` renderizado em prévia aprovada; corte → enquadramento decidido.
|
||||
|
||||
## Trilho HISTÓRIA
|
||||
|
||||
- Como fazer: skill `cenaforge` ("Receita: fazer ou ajustar um vídeo"): copiar a cena base, editar o JSON
|
||||
(textos, tempos, câmera, luz, seed), `pnpm render -- --config … --profile preview`, ler `report.json` e
|
||||
**olhar** `inspect/` (e a tira de 1 quadro/s se mexeu em câmera/movimento). Só depois `--profile final`.
|
||||
- Regras de linguagem visual para vídeo curto:
|
||||
- **0–2 s**: o quadro mais forte do episódio (ação já em andamento, personagem perto da câmera);
|
||||
- troca de plano/câmera/ação a cada **2–4 s** (o feed pune quadro parado);
|
||||
- assunto principal no **terço central** da tela vertical; nada importante nos ~15% de baixo nem na faixa direita;
|
||||
- texto/overlay legível no celular (contraste, ≤ 2 linhas).
|
||||
- Só pedir o que a cena atual faz (rua, entregador de moto); o resto vai para "Necessidades de produção".
|
||||
|
||||
## Trilho CORTE DE LIVE
|
||||
|
||||
- Não há cena a construir. Decisão: layout vertical. Hoje o Clipador usa **vídeo inteiro no meio + fundo
|
||||
desfocado**. Quando a webcam for o centro da reação, o ideal é webcam em cima + jogo embaixo (ainda não existe —
|
||||
lacuna do Clipador).
|
||||
|
||||
## Pronto quando
|
||||
|
||||
- [ ] (história) prévia com `status: success` e todas as `checks` ok; inspeção visual feita e descrita;
|
||||
- [ ] primeiro segundo é o quadro mais forte; não há trecho > 4 s sem mudança visual;
|
||||
- [ ] nada importante fora da zona segura;
|
||||
- [ ] (corte) layout escolhido.
|
||||
@@ -0,0 +1,39 @@
|
||||
# 5 — Montagem
|
||||
|
||||
**Objetivo:** juntar imagem, voz, legenda e marcas num MP4 final 1080×1920 que segura até o fim.
|
||||
**Saída:** MP4 final + legenda (`.srt` ou queimada) + registro na ficha.
|
||||
|
||||
## Regras (os dois trilhos)
|
||||
|
||||
- **Legenda queimada**, palavra a palavra ou em blocos de 1–3 palavras, grande, com contorno, palavra atual
|
||||
destacada (formato que mais rende em vídeo curto; a maioria assiste sem som). Nunca na zona dos botões.
|
||||
- **Cortes secos**: tirar respiração, "é…", silêncio morto. Ritmo > tamanho.
|
||||
- Áudio: fala sempre inteligível; música/efeito abaixo da voz.
|
||||
- Final: 1 s de pagamento + (história interativa) a tela de escolha com A/B legível.
|
||||
- Sem marca d'água de outra rede (Instagram rebaixa).
|
||||
|
||||
## Trilho HISTÓRIA
|
||||
|
||||
- Render final pela skill `cenaforge` (`--profile final`, ~2 min 40 s) com `audio.file` da etapa 3.
|
||||
- **Lacuna:** a Godot ainda não queima legenda. Até existir, opções: (a) só os textos de overlay da cena; (b)
|
||||
queimar a legenda do WAV com FFmpeg + ASS no MP4 final (mesma técnica de `clipper/app/subtitles.py` e
|
||||
`media.py`, com `-ss` antes do `-i` se houver corte).
|
||||
- Verificar: `pnpm verify -- --file <mp4>` vale para o MP4 **saído do render** (lê o `scene.json` da mesma
|
||||
pasta). Depois de queimar legenda à parte, grave o resultado com outro nome e confira com `ffprobe`
|
||||
(1080×1920, H.264, AAC, duração) — o `verify` não se aplica a esse arquivo (não testado).
|
||||
|
||||
## Trilho CORTE DE LIVE
|
||||
|
||||
- O Clipador já monta: vertical, legenda ASS palavra a palavra (amarelo na palavra falada), **crédito do canal
|
||||
no topo**, NVENC/libx264. Ajuste fino de início/fim na fila reenfileira o render.
|
||||
- **Transformação mínima obrigatória** (ver [platforms.md](platforms.md)): gancho em texto (título), crédito,
|
||||
legenda, corte justo. Para monetizar no YouTube, acrescente camada própria (contexto narrado/escrito, edição que
|
||||
conta uma história, compilação temática com comentário).
|
||||
|
||||
## Pronto quando
|
||||
|
||||
- [ ] MP4 1080×1920, H.264, áudio AAC, duração dentro da faixa da etapa 6;
|
||||
- [ ] legenda sincronizada (conferir quadros em 3 pontos) e dentro da zona segura;
|
||||
- [ ] primeiro segundo tem imagem + texto; último segundo paga o gancho;
|
||||
- [ ] (corte) crédito visível; (história) A/B legível no fim;
|
||||
- [ ] visto por inteiro com som pelo menos uma vez (diga se não foi).
|
||||
@@ -0,0 +1,34 @@
|
||||
# 6 — Shorts (empacotamento por rede)
|
||||
|
||||
**Objetivo:** a mesma peça vira uma versão certa para cada rede: duração, título, descrição, hashtags, rótulos.
|
||||
**Saída:** por rede de destino: título, descrição/legenda, hashtags, rótulo de IA (sim/não), crédito (corte).
|
||||
|
||||
## Formato
|
||||
|
||||
| | YouTube Shorts | TikTok | Instagram Reels |
|
||||
|---|---|---|---|
|
||||
| Vídeo | 9:16, 1080×1920, até 3 min | 9:16, até 10 min | 9:16 |
|
||||
| Duração do CenaForge | história: duração da cena; corte: 15–59 s (≤ 60 s para terceiros) | idem | idem |
|
||||
| Título | ≤ 70 chars, gancho + palavra de busca | texto curto no post | 1ª linha da legenda é o gancho |
|
||||
| Hashtags | 3–5 relevantes (#shorts opcional) | 3–5 de nicho | 3–5 de nicho |
|
||||
| Rótulo de IA | "alterado ou sintético" se realista | botão de rótulo IA se realista | "Informações de IA" |
|
||||
|
||||
## Regras
|
||||
|
||||
- **Título ≠ descrição do vídeo**: título é gancho ("Ele não viu o caminhão"), não resumo.
|
||||
- **Legenda do post**: 1ª linha = gancho; depois contexto curto; CTA de compartilhar/comentar.
|
||||
- História interativa: **CTA de voto** ("Comenta A ou B — o mais votado vira o próximo episódio").
|
||||
- Corte: **crédito** obrigatório ("🎥 Créditos: <link do canal>") — o Clipador já acrescenta.
|
||||
- Hashtags só do que está no vídeo (jogo do título da live, canal, assunto) — nunca inventar.
|
||||
- **Mesma peça em várias redes:** suba o arquivo original em cada uma (nunca baixe de uma rede para postar em
|
||||
outra — marca d'água rebaixa no Instagram).
|
||||
- Série: título com "Parte N" ou "Ep. N" e a mesma identidade visual entre partes.
|
||||
|
||||
## Pronto quando
|
||||
|
||||
- [ ] para cada rede de destino: título, legenda, hashtags e rótulo de IA definidos;
|
||||
- [ ] (história) CTA de voto com as opções exatas do overlay; (corte) crédito presente;
|
||||
- [ ] nenhum texto promete o que o vídeo não mostra.
|
||||
|
||||
**Quem faz:** `cenaforge-story-writer` (títulos e legendas, inclusive A/B de título); corte: o juiz do Clipador
|
||||
sugere título e legenda — revise na fila.
|
||||
@@ -0,0 +1,38 @@
|
||||
# 7 — Thumbnail (capa)
|
||||
|
||||
**Objetivo:** a capa que faz clicar no perfil/grade/busca — e que não mente.
|
||||
**Saída:** imagem da capa (e o quadro escolhido) por rede; registrada na ficha.
|
||||
|
||||
## Onde a capa importa
|
||||
|
||||
- **YouTube Shorts:** capa personalizada existe desde 25/07/2026 (primeiro para canais do YPP; também dá para
|
||||
escolher entre 3 quadros sugeridos). Aparece **cortada em ~3:2** → o assunto tem que estar no **centro**.
|
||||
Shorts **não tem teste A/B** de capa. Vídeo longo tem "Testar e comparar" (até 3 capas).
|
||||
- **TikTok/Reels:** capa = quadro escolhido ou imagem enviada; aparece na grade do perfil (recorte vertical).
|
||||
- No feed, quem decide é o 1º segundo do vídeo, não a capa — a capa pesa em perfil, busca e sugestões.
|
||||
|
||||
## Regras (heurística consistente nas fontes)
|
||||
|
||||
1. **Rosto com expressão forte** (susto, riso) costuma ganhar de capa só com texto — teste no seu nicho.
|
||||
2. **Texto ≤ 3–5 palavras**, grande, que complementa (não repete) o título.
|
||||
3. Um assunto só, alto contraste, legível em miniatura (teste reduzindo para ~10% do tamanho).
|
||||
4. Assunto no centro (sobrevive aos recortes 3:2 e da grade).
|
||||
5. Série: mesma identidade (posição do texto, cor, "Ep. N").
|
||||
6. Honesta: a cena da capa está no vídeo.
|
||||
|
||||
## Como fazer hoje no CenaForge
|
||||
|
||||
- **Lacuna:** não há gerador de capa. Caminho atual:
|
||||
1. escolher o quadro (corte: o pico — o Clipador já salva `clip-<id>.jpg`; história: um quadro de
|
||||
`inspect/` ou extraído do MP4);
|
||||
2. extrair em alta: `ffmpeg -ss <t> -i <mp4> -frames:v 1 -q:v 2 capa.jpg` (`-ss` antes do `-i`);
|
||||
3. texto por cima: FFmpeg `drawtext`/ASS ou editor externo.
|
||||
- Teste: em vídeo longo use "Testar e comparar"; em Shorts compare capas **entre episódios** (uma variável por vez)
|
||||
e leia o resultado em 2–3 semanas.
|
||||
|
||||
## Pronto quando
|
||||
|
||||
- [ ] quadro escolhido com o assunto no centro e expressão/ação forte;
|
||||
- [ ] texto ≤ 5 palavras, legível em miniatura;
|
||||
- [ ] capa corresponde a algo que acontece no vídeo;
|
||||
- [ ] arquivo salvo e caminho na ficha.
|
||||
@@ -0,0 +1,48 @@
|
||||
# 8 — Agenda (aprovação → agendamento → publicação → métricas)
|
||||
|
||||
**Objetivo:** nada sai sem aprovação; o que é aprovado sai no melhor horário da conta certa; o resultado volta
|
||||
para a pauta.
|
||||
**Saída:** peça aprovada, com data/hora e conta(s) por rede, publicada e acompanhada.
|
||||
|
||||
## Fluxo
|
||||
|
||||
1. **Aprovação humana (obrigatória, decisão do usuário).**
|
||||
- Corte: fila do Clipador (`ready` → `approved`/`rejected`). Aprovar cria as publicações nas redes dos canais
|
||||
ligados à fonte; com **aprovação automática** ligada no canal, cortes novos são aprovados sozinhos. O painel marca
|
||||
`published` no Clipador quando todas as redes confirmarem.
|
||||
- História: o episódio é aprovado pelo usuário depois do render final (prévia + final conferidos).
|
||||
2. **Destino:** conta(s) pela página **Contas** (conta ↔ histórias, conta ↔ canais do Clipador).
|
||||
3. **Janela:** horários sugeridos para o Brasil em [platforms.md](platforms.md) até haver dados próprios; depois,
|
||||
o horário em que o público da conta está online (analytics da rede).
|
||||
4. **Frequência (ponto de partida):** Shorts 3–5/semana com constância; Reels 1 bom/dia > 3 medianos; espalhar
|
||||
cortes do mesmo canal ao longo do dia/semana em vez de despejar tudo junto; misturar conteúdo próprio
|
||||
(histórias) com cortes.
|
||||
5. **Publicação:** automática pelo painel (desde 17/11/2026). O canal de publicação define a **aprovação**
|
||||
(manual ou automática para cortes; episódio sempre pelo botão "Aprovar para publicar") e **quando sai** (na hora
|
||||
ou no próximo horário bom, com limite por dia por rede). Cada rede conecta por **API oficial** ou **sessão logada**,
|
||||
à escolha do usuário. Acompanhe em **Publicações** (`/publishing`); só conta como publicado com link/ID da rede.
|
||||
O painel precisa estar aberto e o Publicador rodando (`pnpm dev`). Limites por rede em [platforms.md](platforms.md);
|
||||
plano técnico em `doc/publicacao/PLANO.md`.
|
||||
6. **Interativa:** ao publicar, registrar a votação; ao fechar (`closeDecision` no painel) a vencedora vira
|
||||
principal e o próximo nível é preparado — a agenda do próximo episódio nasce aqui.
|
||||
7. **Métricas (24 h, 72 h, 7 dias):** retenção aos 3 s, % que assistiu até o fim, compartilhamentos/salvamentos
|
||||
por alcance, comentários (votos), seguidores ganhos; série: % da parte 1 que viu a parte 2. O dashboard do
|
||||
painel ainda usa **métricas simuladas** — não trate como reais.
|
||||
8. **Volta para a pauta:** o que funcionou vira regra da conta; o que falhou vira hipótese para testar (uma
|
||||
variável por vez: gancho, duração, capa, horário).
|
||||
|
||||
## Calendário
|
||||
|
||||
Use a tabela da ficha ([../templates/ficha.md](../templates/ficha.md)) ou, para uma semana, uma linha por peça:
|
||||
`data | hora | rede | conta | peça | status (aprovado/agendado/publicado) | link`.
|
||||
|
||||
## Pronto quando
|
||||
|
||||
- [ ] aprovado pelo usuário (registro de quem/quando);
|
||||
- [ ] conta e rede de destino; data/hora definidas;
|
||||
- [ ] título, legenda, capa e rótulo de IA da etapa 6–7 anexados;
|
||||
- [ ] (após publicar) link registrado e lembrete de leitura de métricas em 24 h / 7 dias.
|
||||
|
||||
**Lacunas:** sem métricas reais (o dashboard ainda usa simuladas); envio real ainda não validado com conta de
|
||||
verdade em todas as redes. Não diga que algo foi "agendado" ou "publicado" se só foi aprovado — confira o estado em
|
||||
**Publicações**.
|
||||
@@ -0,0 +1,112 @@
|
||||
# Regras e sinais das plataformas (pesquisa de 16/11/2026)
|
||||
|
||||
**Como ler:** "confirmado" = anúncio da própria plataforma ou imprensa citando a plataforma. "Heurística" = blog
|
||||
de ferramenta/agência, sem dado primário — use como ponto de partida e troque pelos seus números.
|
||||
Reverifique a cada 3 meses. Nunca apresente heurística como regra oficial.
|
||||
|
||||
## Sinais de distribuição
|
||||
|
||||
| O quê | Status | Resumo |
|
||||
|---|---|---|
|
||||
| Tempo assistido e taxa de conclusão pesam mais que curtidas (TikTok, Reels, Shorts) | consenso de mercado; TikTok não publica pesos | gancho + vídeo que se assiste até o fim / reassiste |
|
||||
| Compartilhamentos/envios e salvamentos > curtidas | heurística consistente | escreva para ser enviado ("manda pro amigo que…") |
|
||||
| Sinais negativos ("Não tenho interesse", pular cedo) derrubam | consenso | não prometa no gancho o que o vídeo não entrega |
|
||||
| Retenção aos 3 s ≈ 70–80% como alvo; queda > 50% nos 3 s = vídeo morto | heurística (números variam) | a referência real é o gráfico de retenção do YouTube Studio |
|
||||
| Série: medir quantos que terminaram a parte 1 viram a parte 2 | heurística | métrica-chave das histórias por episódio |
|
||||
|
||||
## Originalidade e conteúdo reutilizado (crítico para o Clipador)
|
||||
|
||||
- **Instagram (abr–mai/2026, Mosseri):** conta cujo conteúdo é majoritariamente de outras pessoas deixa de ser
|
||||
recomendável; ao detectar conteúdo idêntico, o Instagram recomenda o original no lugar do repost e rotula o repost
|
||||
com link para o original. Marca d'água de outra rede, corte mínimo ou repost simples não contam como original.
|
||||
— confirmado pela imprensa citando Mosseri (detalhes de limiar não confirmados).
|
||||
- **YouTube (política de conteúdo reutilizado):** compilação/reação/corte só monetiza com **comentário original
|
||||
significativo, modificação ou valor educativo/de entretenimento**; vale para o canal inteiro; **permissão do
|
||||
criador não resolve** (resolve copyright/Content ID, não a "originalidade"). — fontes secundárias; conferir a
|
||||
página oficial antes de pedir monetização.
|
||||
- **Permissão de clipar:** crédito não é permissão. Permissão boa diz: quais clipes, quais redes, se pode editar,
|
||||
se pode monetizar, por quanto tempo. Música do jogo/fundo é direito separado (Content ID).
|
||||
- **Consequência para o trilho Corte:** sempre transformar (gancho escrito, contexto em texto ou narração própria,
|
||||
edição/zoom, legenda, crédito no vídeo e na descrição) e misturar com conteúdo próprio (as histórias) nas contas.
|
||||
|
||||
## Formato
|
||||
|
||||
| Rede | Fato | Status |
|
||||
|---|---|---|
|
||||
| YouTube Shorts | vertical/quadrado até **3 min** (desde out/2024) | confirmado |
|
||||
| YouTube Shorts | **capa personalizada** desde 24–25/07/2026 (Neal Mohan), primeiro para canais do YPP; aparece cortada em ~3:2; **sem teste A/B** em Shorts | confirmado (recorte e YPP via imprensa) |
|
||||
| YouTube Shorts | uma fonte diz que regra de copyright para Shorts > 60 s muda em 24/09/2026 | **não confirmado** — manter cortes de terceiros ≤ 60 s por precaução |
|
||||
| YouTube (vídeo longo) | "Testar e comparar": até 3 capas por vídeo | confirmado; critério do vencedor varia nas fontes |
|
||||
| TikTok | vídeos longos permitidos (até 10 min no app) | confirmado |
|
||||
| Todas | 1080×1920, 9:16, legenda queimada (a maioria assiste sem som) | prática consolidada |
|
||||
|
||||
Zona segura (heurística): texto importante fora dos ~15% de baixo (legenda/@ da rede) e da faixa direita
|
||||
(botões do TikTok/Reels). No Clipador a legenda fica centrada em y≈1420 de 1920 — dentro da zona segura.
|
||||
|
||||
## Rótulo de conteúdo feito com IA
|
||||
|
||||
| Rede | Regra (fontes secundárias, conferir) |
|
||||
|---|---|
|
||||
| YouTube | pergunta "alterado ou sintético" no upload para conteúdo **realista**; detecção automática e rótulo para conteúdo fotorrealista gerado por IA; edição menor não precisa |
|
||||
| TikTok | rótulo obrigatório para conteúdo realista gerado por IA (botão no post); pode rotular sozinho via metadados C2PA; rótulo não reduz distribuição |
|
||||
| Instagram/Meta | rótulo "Informações de IA", aplicado também por sinais C2PA |
|
||||
| UE (AI Act, art. 50) | regras de transparência a partir de ago/2026 |
|
||||
|
||||
**Regra do CenaForge:** episódio animado (3D estilizado + TTS genérico) não é "realista" — rótulo opcional.
|
||||
**Marque IA** quando houver voz que imita pessoa real (RVC de personagem baseado em alguém) ou imagem realista.
|
||||
|
||||
## Horários e frequência (Brasil — heurística, testar)
|
||||
|
||||
| Rede | Janelas sugeridas (horário de Brasília) | Frequência sugerida |
|
||||
|---|---|---|
|
||||
| TikTok | 7–9h e 18–22h; fim de semana mais amplo (sáb 10–18h, dom 11–19h) | sem número confiável para BR |
|
||||
| Reels | 11–13h e 19–21h (seg–qui); domingo à tarde forte | 1 Reel bom/dia > 3 medianos |
|
||||
| Shorts | uma fonte aponta 14–16h | constância: 3–5/semana |
|
||||
|
||||
As fontes discordam entre si: depois de 2–4 semanas, use os horários do seu próprio público (analytics).
|
||||
|
||||
## Publicação por API (limites que afetam a etapa 8) — atualizado em 17/11/2026
|
||||
|
||||
Detalhe completo e fontes: [doc/publicacao/PESQUISA.md](../../../../doc/publicacao/PESQUISA.md).
|
||||
|
||||
- YouTube Data API: desde 02/11/2026 app **não verificado já publica público**; cota de `videos.insert` = **100/dia**.
|
||||
Deixe o app do Google "In production" (em "Testing" a autorização vence em 7 dias).
|
||||
- TikTok Content Posting API: sem auditoria, só **SELF_ONLY** (privado) ou **rascunho** na caixa de entrada do app;
|
||||
a auditoria provavelmente é negada para ferramenta de uso próprio. Público só pelo modo **sessão logada**.
|
||||
- Instagram: conta **Profissional**; "Instagram API with Instagram Login" dispensa Página do Facebook e, para conta
|
||||
própria, dispensa App Review. Token longo de 60 dias.
|
||||
- Modo **sessão logada** (sem API) existe nas três redes, mas **viola os termos** delas (risco de bloqueio da conta).
|
||||
|
||||
## Fontes
|
||||
|
||||
- Ganchos e retenção: [vidIQ — views em Shorts](https://vidiq.com/blog/post/get-more-views-youtube-shorts/),
|
||||
[Opus — fórmulas de gancho](https://www.opus.pro/blog/youtube-shorts-hook-formulas),
|
||||
[dev.to — Hook Engineering 2026](https://dev.to/bulkdl/hook-engineering-the-science-of-the-first-3-seconds-in-short-form-video-2026-2jp9)
|
||||
- TikTok: [Hootsuite — algoritmo](https://blog.hootsuite.com/tiktok-algorithm/),
|
||||
[Darkroom — guia 2026](https://www.darkroomagency.com/observatory/tiktok-algorithm-guide-2026-everything-we-know-about-how-videos-are-ranked)
|
||||
- Instagram originalidade: [PetaPixel 30/04/2026](https://petapixel.com/2026/04/30/new-instagram-policies-target-reposted-content/),
|
||||
[Tecnoblog](https://tecnoblog.net/noticias/instagram-reforca-combate-a-reposts-do-tiktok-e-de-outros-videos-no-reels/),
|
||||
[Engadget](https://www.engadget.com/instagrams-algorithm-overhaul-will-reward-original-content-and-penalize-aggregators-130018977.html),
|
||||
[SocialPilot — Reels 2026](https://www.socialpilot.co/?p=563048)
|
||||
- YouTube reutilizado: [vidIQ — política](https://vidiq.com/blog/post/youtube-reused-content-policy-guide/),
|
||||
[Search Engine Journal](https://www.searchenginejournal.com/youtube-clarifies-monetization-update-targeting-spam-not-reaction-channels/550123/),
|
||||
[AIR — linha do tempo 2026](https://air.io/en/monetization/youtube-monetization-policy-changes-2026-a-complete-dated-timeline)
|
||||
- Shorts formato/capa: [Tubefilter 24/07/2026](https://www.tubefilter.com/2026/07/24/youtube-shorts-custom-thumbnails-neal-mohan-feature-update/),
|
||||
[Relevant Audience — sem A/B](https://www.relevantaudience.com/social-media-marketing/youtube-shorts-custom-thumbnails-no-ab-testing/),
|
||||
[Descript — duração](https://www.descript.com/blog/article/how-long-can-youtube-shorts-be)
|
||||
- Thumbnail: [vidIQ — dicas 2026](https://vidiq.com/blog/post/youtube-thumbnail-tips/),
|
||||
[ThumbnailTest](https://thumbnailtest.com/guides/best-practices-youtube-thumbnail/),
|
||||
[PostIgniter — testes](https://postigniter.com/blog/youtube-thumbnails-as-performance-assets-design-testing-and-iteration-strategies-for-2026)
|
||||
- Rótulo de IA: [The Next Web — YouTube auto-rótulo](https://thenextweb.com/news/youtube-will-now-automatically-label-ai-generated-videos-whether-creators-disclose-them-or-not),
|
||||
[Billo — rótulos 2026](https://billo.app/blog/ai-labeling/),
|
||||
[Fanpage Karma — AI Act](https://www.fanpagekarma.com/insights/?p=16910)
|
||||
- Horários BR: [Cut.pro — Reels Brasil 2026](https://cut.pro/pt-BR/blog/best-time-to-post-reels-brazil),
|
||||
[TimeToPost — TikTok Brasil](https://timetopost.co/best-time-to-post/tiktok/brazil/),
|
||||
[Hopper HQ — TikTok 2026](https://hopperhq.com/blog/best-time-to-post-on-tiktok/)
|
||||
- Séries curtas: [Influencers-Time — séries com cliffhanger](https://www.influencers-time.com/how-to-build-a-tiktok-series-with-cliffhangers-that-retain-v/),
|
||||
[NoGood — micro-dramas](https://nogood.io/blog/micro-drama/)
|
||||
- Narração e legenda: [Syllaby — ritmo de locução](https://syllaby.io/blog/voiceover-pacing-silence-trimming-retention-editing/),
|
||||
[Opus — legendas TikTok 2026](https://www.opus.pro/blog/tiktok-caption-subtitle-best-practices)
|
||||
- Clipes de terceiros: [ClipSpeed — copyright](https://clipspeed.ai/blog/can-you-clip-someone-elses-stream.html),
|
||||
[Twitch Creator Camp — copyright](https://twitch.tv/creatorcamp/paths/getting-started-on-twitch/copyrights-and-your-channel),
|
||||
[ABA — DMCA para streamers (set/2026)](https://www.americanbar.org/groups/business_law/resources/business-law-today/2026-september/dmca-lessons-for-live-streamers-their-counsel/)
|
||||
@@ -0,0 +1,29 @@
|
||||
# Ficha de produção — <história/file_key ou corte #id>
|
||||
|
||||
Trilho: HISTÓRIA | CORTE DE LIVE · Responsável: <...> · Criada em: <AAAA-MM-DD>
|
||||
|
||||
| # | Etapa | Status | Artefato (caminho / id) | Observação |
|
||||
|---|---|---|---|---|
|
||||
| 1 | Pauta | ⬜ | `stories/<id>/pauta.md` item # | gancho: |
|
||||
| 2 | Roteiro | ⬜ | `stories/<id>/<file_key>.md` | |
|
||||
| 3 | Narração | ⬜ | `<wav>` · rótulo IA: sim/não | ritmo: palavras/min |
|
||||
| 4 | Cenas | ⬜ | `config/<id>-<file_key>.json` · run da prévia | inspeção visual: |
|
||||
| 5 | Montagem | ⬜ | `<mp4 final>` | visto com som: sim/não |
|
||||
| 6 | Shorts | ⬜ | títulos/legendas por rede (abaixo) | |
|
||||
| 7 | Thumbnail | ⬜ | `<capa.jpg>` | |
|
||||
| 8 | Agenda | ⬜ | aprovado por/quando · data/hora/rede/conta | link após publicar |
|
||||
|
||||
Status: ⬜ pendente · 🟨 em andamento · ✅ pronto (checklist da etapa passou) · ⏭️ não se aplica (diga por quê)
|
||||
|
||||
## Por rede (etapa 6)
|
||||
|
||||
| Rede | Conta | Título | Legenda (1ª linha = gancho) | Hashtags | Rótulo IA |
|
||||
|---|---|---|---|---|---|
|
||||
| YouTube Shorts | | | | | |
|
||||
| TikTok | | | | | |
|
||||
| Instagram Reels | | | | | |
|
||||
|
||||
## Agenda e métricas (etapa 8)
|
||||
|
||||
| Rede | Data/hora | Status | Link | 24 h (views · ret. 3 s · % até o fim · shares) | 7 dias |
|
||||
|---|---|---|---|---|---|
|
||||
@@ -0,0 +1,28 @@
|
||||
# Pauta — <série ou conta>
|
||||
|
||||
Trilho: HISTÓRIA | CORTE DE LIVE · Conta(s) de destino: <...> · Atualizada em: <AAAA-MM-DD>
|
||||
|
||||
## Ideias
|
||||
|
||||
| # | Ideia (1 linha) | Gancho (0–2 s) | Pagamento | Por que compartilhar | Status |
|
||||
|---|---|---|---|---|---|
|
||||
| 1 | | | | | ideia / aprovada / em produção / publicada / descartada |
|
||||
|
||||
## Arco (história) — 3 a 5 partes
|
||||
|
||||
| Parte | O que muda | Risco/informação nova | Termina em |
|
||||
|---|---|---|---|
|
||||
| 1 | | | escolha A/B ou cliffhanger |
|
||||
|
||||
## Canais e ângulo (corte de live)
|
||||
|
||||
| Canal (id do Clipador) | Permissão (o quê, onde, monetiza?, até quando) | Ângulo de transformação | Nota mínima do juiz |
|
||||
|---|---|---|---|
|
||||
|
||||
## Necessidades de produção
|
||||
|
||||
- <o que o CenaForge ainda não faz e esta pauta pede — ou "nenhuma">
|
||||
|
||||
## Aprendizados (da etapa 8)
|
||||
|
||||
- <o que funcionou / falhou e a hipótese para o próximo teste>
|
||||
Reference in New Issue
Block a user