diff --git a/.claude/skills/cenaforge/CHANGELOG.md b/.claude/skills/cenaforge/CHANGELOG.md
index d75235c..178ea1d 100644
--- a/.claude/skills/cenaforge/CHANGELOG.md
+++ b/.claude/skills/cenaforge/CHANGELOG.md
@@ -7,20 +7,38 @@ Versão semântica da **skill** (não do projeto):
Mantido pelo subagente `cenaforge-skill-updater`. Entradas mais novas no topo.
-## 1.54.0 — 18/11/2026
+## 1.55.0 — 18/11/2026
Clipador: detecção automática do jogo da live.
-- `references/clipper.md`: banco em v16 (inclui v14 revisão × final e v15 `voice_chunks`, que a skill ainda não cobria, só
- com ponteiro para `doc/clipador/REVISAO.md` e `FALANTES.md`); seção nova "Detecção do jogo da live" (pistas e pesos,
+- `references/clipper.md`: banco em v17 (v16 = detecção do jogo); seção nova "Detecção do jogo da live" (pistas e pesos,
estados `user|agreed|probable|conflict|unknown`, regras de troca e de sugestão, "Detectar agora", API, painel);
`GAME_CHECK_S` 600 → 180; juiz com `screen_game_confidence`/`screen_evidence` e `Judge.detect_game`; "Testes e evidência".
-- `references/gotchas.md`: 180 (jogo não detectado: serviço sem reiniciar, jogo não cadastrado, sem IA/visão, `game_id` ×
+- `references/gotchas.md`: 186 (jogo não detectado: serviço sem reiniciar, jogo não cadastrado, sem IA/visão, `game_id` ×
`slug`, e proxy do painel sem `game/detect`).
- `SKILL.md`: versão, `description`, linha do Clipador em "Onde mexer", faixa de itens.
- Evidência (reexecutada): suíte do Clipador exit 0 com 440 testes (15 em `test_game_detect.py`); `npx tsc --noEmit -p panel`
exit 0. Conferidos no código: `db.py` v16, rotas `PUT …/game` e `POST …/game/detect`, `session_view`, constantes de `intel.py`.
Não verificado: IA real, painel no navegador, banco real em v16. Corrigido depois: `ALLOWED` de
`panel/src/lib/clipper.ts` agora libera `sessions//game/detect` (`game(\/detect)?`).
+- Sincronização com a 1.54.0 (outra sessão): versão renumerada, item de gotchas 180 → 186, banco descrito em v17.
+
+## 1.54.0 — 18/11/2026
+
+Clipador: vídeo de revisão × final, dublagem, falantes, expressões e Equipe de IA.
+- `references/clipper-video.md` (novo): revisão × final (grupo `dev`, `dev_flags`, migração v14, `publishFile`, `POST /v1/clips/{id}/final`,
+ quando o final some), dublagem (`dev.dub*`, `dub.py`, cache, encaixe sem sincronia labial, tempos medidos) e falantes (WeSpeaker
+ ResNet34-LM CC-BY-4.0 + boca/volume, migração v15, legenda em duas linhas, `GET /v1/sessions/{id}/speakers`).
+- `references/clipper-ai-team.md` (novo): papéis (`judge.roles`), juiz de contexto (7 checagens, o código decide), linha do tempo JSON +
+ mosaico 4×2 (`timelineJson`), medição F0 (`ai_calls`, `scene_notes`, v17, `GET /v1/judge/report`, rótulo "sem contexto"), tokens medidos.
+- `references/clipper.md`: banco em v17 (v16 só citada: detecção do jogo, doc ainda fora desta branch); 4 linhas novas em "Onde mexer";
+ seção de expressões/pose/corpo em "Rastreio de reação" (calibração, canais novos só rotulam); `dev.translation` no lugar de
+ `caption.translation`; fontes em teste; bloco de evidência.
+- `references/gotchas.md`: 180 (publicar só o final), 181 (proxy 404), 182 (falantes), 183 (dublagem), 184 (worktree no Windows), 185 (serviços do usuário).
+- `references/panel.md`, `publishing.md`, `ai.md`, `tools.md`: ponteiros e linha do peso WeSpeaker. `SKILL.md`: versão, `description`, invariante de publicação, faixa de itens.
+- Evidência: conferido no código (`db.py` v14–v17, `layout.py` `dev`/`DEFAULTS`, rotas em `main.py`, regex `ALLOWED`, `models.lock.json`,
+ `OPTION_DEFAULTS.timelineJson`); `onnxruntime` 1.32.0 e `mediapipe` 1.2.3 no `clipper/.venv`. Suíte do Clipador (inteira) e painel
+ (`tsc` + 119 testes) **informados pelo coordenador, não reexecutados**. Medidas de tempo/tokens/estabilidade vêm de `doc/clipador/`.
+ Não verificado: serviços reais com o código novo, UI no navegador, IA/TTS reais além dos cortes citados.
## 1.53.0 — 18/11/2026
diff --git a/.claude/skills/cenaforge/SKILL.md b/.claude/skills/cenaforge/SKILL.md
index 043a335..b6eda31 100644
--- a/.claude/skills/cenaforge/SKILL.md
+++ b/.claude/skills/cenaforge/SKILL.md
@@ -1,11 +1,11 @@
---
name: cenaforge
-description: Produz e altera vídeos narrativos do projeto CenaForge — cena 3D (rua) ou do documentário (2D: título, contador, mapa do litoral de SP, `kind: "doc2d"`; 3D da biblioteca de cenas `godot/library/`, ex.: ilha com farol de dia/entardecer/noite, náufragos no costão, `kind: "doc3d"`; peças `godot/kits/`: pessoa articulada com poses e barco; cena dentro de outra) descrita por JSON, animada por tempo de cena na Godot, gravada pelo Movie Maker e convertida em MP4 pelo FFmpeg. Use sempre que o pedido envolver criar, renderizar ou ajustar um vídeo, episódio ou cena (câmera, movimento, cenário, personagem, moto, luz, texto e opções A/B, áudio, resolução), validar um MP4, gerar narração (TTS: Edge, Piper, Kokoro, Google, Azure Speech) ou escolher/filtrar voz, clonar voz a partir de uma gravação (Chatterbox, com consentimento), vozes de personagem (RVC/Applio) ou transcrição com tempos para legenda (.srt) pelo serviço de voz local ou pela página Vozes do painel, histórias interativas com vertentes e votação A–D, lineares ou documentais (vídeo único sobre fatos reais, com fontes) e onde ficam as regras de roteiro (doc/roteiro/), leitor de roteiro do painel (trechos, narração × duração alvo, fontes), criar cena 3D nova na biblioteca (`template.gd` + `manifest.json`, guia `doc/godot/cenas.md`, tarefa "Cena no Godot" do agente), montagem do vídeo documental em MP4 no painel ("Gerar vídeo automático" num clique: plano por regras, fotos reais do Wikimedia Commons, narração e cenas 2D/3D da Godot; "Gerar de novo" por trecho e "Refazer tudo do zero"; estilo "Tudo em 3D" com cartão de foto real por cima e cartões de informação em sequência; estilo "Cartoon" (desenho 2D em Remotion, pacote `cartoon/`: lugares montados por peças a partir do texto, sem cenário pronto; biblioteca de personagens criados uma vez e reaproveitados entre histórias — aba "Personagens", elenco por história, agente "character" —; paleta da série, etiquetas, onomatopeias e legenda palavra por palavra; personagem com rig de expressões e ações de movimento combináveis, fala sincronizada com a narração, acabamento de ilustração: formato de cabeça, nariz, pálpebra, rugas, acessórios de profissão, enquadramento close/medium e textura de papel); ou manual: áudio por trecho com números por extenso, visual por trecho — foto com fundo desfocado, animação 2D, cena 3D da biblioteca, clipe ou cartela —, texto na tela, legenda e créditos, pelo FFmpeg), excluir história no painel (vai para data/trash/), escolha de agente e modelo (Claude Code, Codex, Gemini CLI ou Antigravity) no painel, IA (provedores Claude, Codex, Gemini e Antigravity, entrar com a conta ou chave de API no cofre, ordem e IA reserva quando uma cai por cota/login/rede, monitor de uso do limite e troca antes de bater, Configurações em subpáginas), mensagem ou correção ao agente durante a execução (Corrigir agora / Enviar ao terminar), termos episódio × vídeo na interface, contas e dashboard (métricas simuladas) do painel, Clipador (cortes automáticos de live da Twitch/Kick/YouTube, verticais 9:16 ou horizontais 16:9 para YouTube, com duração configurável e mínimo garantido, qualidade de gravação configurável até 2K: chat e emotes, heurística, varredura da IA, juízes analista e editor pela CLI, detecção automática do jogo da live (categoria, título, tela, chat e fala; estados confirmado/concordam/provável/conflito; "Detectar agora"), contexto do jogo e perfil do jogo bilíngue (português para ler, inglês para a IA) editável/refinável pela IA, com missões, gatilhos de fim de missão e outros nomes (aliases), cadastro e apagar jogo pelo painel, tradução do perfil e semente do GTA VI, webcam achada sem IA e layout do corte, rastreio de reação do rosto do streamer (YuNet, MediaPipe, expressões que reforçam o corte), legenda com hashtags do canal, do jogo e do momento, editor de cortes em tela cheia no padrão de editor de vídeo, com timeline de uma trilha por camada e projeto de edição feito pela IA (trechos com layout próprio e trecho mudo, câmera inteira e editável na Fonte, legenda animada editável arrastando, gancho em tarja animada, fontes empacotadas, textos, zoom, reenquadramento do jogo com keyframes, camadas inseridas (recorte da tela em destaque), chat da live na tela, narração, música, capa também no início, export pelo FFmpeg), interface em subpáginas (Cortes com modal, Sessões, Fontes, Jogos, Ajustes), parar a sessão à mão (pausa o monitor da fonte, "Religar"), idioma da fonte, da sessão e do canal de publicação (en-US, es-419), fonte de live em inglês (juízes em inglês, vídeo em inglês, painel em português, fala traduzida frase a frase, legenda em português embaixo para teste), retomada de live que caiu, cortes duplicados descartados (o rejeitado ou apagado não volta), render que falha, fila de aprovação com apagar corte (um, selecionados ou a aba inteira), relógio da gravação e cadência do resumo no cartão da sessão, prévia do editor igual ao render (legenda e recorte), "não sai corte" (live fria × regras) e fontes ligadas aos canais de publicação), publicação automática em YouTube, TikTok e Instagram (serviço Publicador, canais de publicação, conectar rede pela API oficial ou sessão logada, aprovação manual ou automática, horários bons e limite por dia, botão "Publicar" no corte aprovado, inclusive sem fonte ligada e com "Horário específico" por rede, ordenar a fila de cortes, capa que sumiu do dashboard, fila "Publicações", Configurações, job que falhou, pede login ou pede "Confira na rede", "Já saiu: informar o link" quando o vídeo foi ao ar mas o job falhou, YouTube Studio que "não confirmou" a publicação, hashtag do TikTok que não vira hashtag (legenda colada), botão "Publicar no " nos cartões de Publicações), números dos posts (views, curtidas, comentários) lidos das redes e mostrados no Dashboard (leitura automática a cada N horas, "Atualizar números agora"), chamar a API do painel por script (cabeçalhos `Origin` e JSON; criar história com agente por `POST /api/stories`), agente que parou no limite de uso ou morreu ao reiniciar o painel, instalar/subir o projeto (setup.bat, start.bat, pnpm dev), ou trocar/adicionar ferramentas de 3D, voz ou render neste repositório — mesmo que o usuário não diga "skill" nem "CenaForge".
+description: Produz e altera vídeos narrativos do projeto CenaForge — cena 3D (rua) ou do documentário (2D: título, contador, mapa do litoral de SP, `kind: "doc2d"`; 3D da biblioteca de cenas `godot/library/`, ex.: ilha com farol de dia/entardecer/noite, náufragos no costão, `kind: "doc3d"`; peças `godot/kits/`: pessoa articulada com poses e barco; cena dentro de outra) descrita por JSON, animada por tempo de cena na Godot, gravada pelo Movie Maker e convertida em MP4 pelo FFmpeg. Use sempre que o pedido envolver criar, renderizar ou ajustar um vídeo, episódio ou cena (câmera, movimento, cenário, personagem, moto, luz, texto e opções A/B, áudio, resolução), validar um MP4, gerar narração (TTS: Edge, Piper, Kokoro, Google, Azure Speech) ou escolher/filtrar voz, clonar voz a partir de uma gravação (Chatterbox, com consentimento), vozes de personagem (RVC/Applio) ou transcrição com tempos para legenda (.srt) pelo serviço de voz local ou pela página Vozes do painel, histórias interativas com vertentes e votação A–D, lineares ou documentais (vídeo único sobre fatos reais, com fontes) e onde ficam as regras de roteiro (doc/roteiro/), leitor de roteiro do painel (trechos, narração × duração alvo, fontes), criar cena 3D nova na biblioteca (`template.gd` + `manifest.json`, guia `doc/godot/cenas.md`, tarefa "Cena no Godot" do agente), montagem do vídeo documental em MP4 no painel ("Gerar vídeo automático" num clique: plano por regras, fotos reais do Wikimedia Commons, narração e cenas 2D/3D da Godot; "Gerar de novo" por trecho e "Refazer tudo do zero"; estilo "Tudo em 3D" com cartão de foto real por cima e cartões de informação em sequência; estilo "Cartoon" (desenho 2D em Remotion, pacote `cartoon/`: lugares montados por peças a partir do texto, sem cenário pronto; biblioteca de personagens criados uma vez e reaproveitados entre histórias — aba "Personagens", elenco por história, agente "character" —; paleta da série, etiquetas, onomatopeias e legenda palavra por palavra; personagem com rig de expressões e ações de movimento combináveis, fala sincronizada com a narração, acabamento de ilustração: formato de cabeça, nariz, pálpebra, rugas, acessórios de profissão, enquadramento close/medium e textura de papel); ou manual: áudio por trecho com números por extenso, visual por trecho — foto com fundo desfocado, animação 2D, cena 3D da biblioteca, clipe ou cartela —, texto na tela, legenda e créditos, pelo FFmpeg), excluir história no painel (vai para data/trash/), escolha de agente e modelo (Claude Code, Codex, Gemini CLI ou Antigravity) no painel, IA (provedores Claude, Codex, Gemini e Antigravity, entrar com a conta ou chave de API no cofre, ordem e IA reserva quando uma cai por cota/login/rede, monitor de uso do limite e troca antes de bater, Configurações em subpáginas), mensagem ou correção ao agente durante a execução (Corrigir agora / Enviar ao terminar), termos episódio × vídeo na interface, contas e dashboard (métricas simuladas) do painel, Clipador (cortes automáticos de live da Twitch/Kick/YouTube, verticais 9:16 ou horizontais 16:9 para YouTube, com duração configurável e mínimo garantido, qualidade de gravação configurável até 2K: chat e emotes, heurística, varredura da IA, juízes analista e editor pela CLI, contexto do jogo e perfil do jogo bilíngue (português para ler, inglês para a IA) editável/refinável pela IA, com missões, gatilhos de fim de missão e outros nomes (aliases), cadastro e apagar jogo pelo painel, tradução do perfil e semente do GTA VI, webcam achada sem IA e layout do corte, rastreio de reação do rosto do streamer (YuNet, MediaPipe, expressões que reforçam o corte), legenda com hashtags do canal, do jogo e do momento, editor de cortes em tela cheia no padrão de editor de vídeo, com timeline de uma trilha por camada e projeto de edição feito pela IA (trechos com layout próprio e trecho mudo, câmera inteira e editável na Fonte, legenda animada editável arrastando, gancho em tarja animada, fontes empacotadas, textos, zoom, reenquadramento do jogo com keyframes, camadas inseridas (recorte da tela em destaque), chat da live na tela, narração, música, capa também no início, export pelo FFmpeg), interface em subpáginas (Cortes com modal, Sessões, Fontes, Jogos, Ajustes), parar a sessão à mão (pausa o monitor da fonte, "Religar"), idioma da fonte, da sessão e do canal de publicação (en-US, es-419), fonte de live em inglês (juízes em inglês, vídeo em inglês, painel em português, fala traduzida frase a frase, legenda em português embaixo para teste), 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), vídeo de revisão × vídeo final (camadas de teste só na revisão; ao aprovar sai o final, e só ele é publicado), dublagem em português por TTS (teste), quem fala cada trecho (streamer × outra pessoa, legenda em duas linhas), mapa de expressões e movimento do corpo do streamer, Equipe de IA do Clipador (papéis varredura/analista/editor/juiz de contexto com provedor, modelo e instruções do administrador; linha do tempo JSON e mosaico; medição de tokens e "sem contexto"), "não sai corte" (live fria × regras) e fontes ligadas aos canais de publicação), publicação automática em YouTube, TikTok e Instagram (serviço Publicador, canais de publicação, conectar rede pela API oficial ou sessão logada, aprovação manual ou automática, horários bons e limite por dia, botão "Publicar" no corte aprovado, inclusive sem fonte ligada e com "Horário específico" por rede, ordenar a fila de cortes, capa que sumiu do dashboard, fila "Publicações", Configurações, job que falhou, pede login ou pede "Confira na rede", "Já saiu: informar o link" quando o vídeo foi ao ar mas o job falhou, YouTube Studio que "não confirmou" a publicação, hashtag do TikTok que não vira hashtag (legenda colada), botão "Publicar no " nos cartões de Publicações), números dos posts (views, curtidas, comentários) lidos das redes e mostrados no Dashboard (leitura automática a cada N horas, "Atualizar números agora"), chamar a API do painel por script (cabeçalhos `Origin` e JSON; criar história com agente por `POST /api/stories`), agente que parou no limite de uso ou morreu ao reiniciar o painel, instalar/subir o projeto (setup.bat, start.bat, pnpm dev), ou trocar/adicionar ferramentas de 3D, voz ou render neste repositório — mesmo que o usuário não diga "skill" nem "CenaForge".
---
# CenaForge — vídeo a partir de cena descrita por JSON
-**Versão da skill: 1.54.0** (18/11/2026) — histórico em [CHANGELOG.md](CHANGELOG.md).
+**Versão da skill: 1.55.0** (18/11/2026) — histórico em [CHANGELOG.md](CHANGELOG.md).
Mantida pelo subagente `cenaforge-skill-updater` (ver "Manutenção" no fim).
## Regra zero
@@ -61,7 +61,7 @@ outra, teste olhando o `inspect/`); detalhes em [references/panel.md](references
| Assets da história / biblioteca | `stories//assets///` · `assets/library///` (cada um com `asset.json`) |
| Estado (episódios, vertentes, votos, canais de publicação, fila de publicação, métricas, execuções) | `data/cenaforge.db` (esquema v10; backup antes de migrar em `data/backups/`), gerido pelo painel (`panel/`, http://127.0.0.1:4500) — detalhes em [references/panel.md](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//` — ver [references/clipper.md](references/clipper.md) |
+| Clipador (cortes de live) | `clipper/` (http://127.0.0.1:4520); banco e blocos em `data/clipper/`, cortes em `output/clipper//` — ver [references/clipper.md](references/clipper.md) (revisão × final, dublagem e falantes: [clipper-video.md](references/clipper-video.md); Equipe de IA: [clipper-ai-team.md](references/clipper-ai-team.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) |
@@ -117,7 +117,7 @@ Interativa = 2–4 vertentes, mas o overlay só desenha `choiceA`/`choiceB`. Tab
| 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 e sua detecção automática (`game_detect.py`), formato (vertical/horizontal), duração mínima (`fit_window`), layout/webcam, rastreio de reação (rosto), legenda, gancho/tarja e fontes (`assets/fonts/`), reenquadramento e camadas inseridas (`reframe.py`), render, apagar cortes (`clip_delete.py`, tabela `deleted_clips`), editor de cortes, páginas `/clipper/*` (grupo `(studio)`), pausa do monitor e idioma, fonte em inglês (`*_EN`, `translate_clip`, `voice_language`), canais nas contas | `clipper/app/` · `panel/src/lib/clipper.ts` (regex `ALLOWED`, métodos `METHODS` + timeout por rota) · `panel/src/components/clipper-*.tsx` (moldura `clipper-shell.tsx`, páginas em `panel/src/app/clipper/(studio)/`) e `clip-editor*.ts(x)` — tabela em [references/clipper.md](references/clipper.md) | `clipper/tests/`, `clipper/README.md`; peso novo em `clipper/models.lock.json` (URL imutável + sha256) |
+| Clipador: captura e qualidade de gravação (`capture.py`), retomada de live, chat/emotes, heurística, duplicados, varredura, juízes, jogo e sua detecção automática (`game_detect.py`), formato (vertical/horizontal), duração mínima (`fit_window`), layout/webcam, rastreio de reação (rosto), legenda, gancho/tarja e fontes (`assets/fonts/`), reenquadramento e camadas inseridas (`reframe.py`), render, apagar cortes (`clip_delete.py`, tabela `deleted_clips`), editor de cortes, páginas `/clipper/*` (grupo `(studio)`), pausa do monitor e idioma, fonte em inglês (`*_EN`, `translate_clip`, `voice_language`), canais nas contas | `clipper/app/` · `panel/src/lib/clipper.ts` (regex `ALLOWED`, métodos `METHODS` + timeout por rota) · `panel/src/components/clipper-*.tsx` (moldura `clipper-shell.tsx`, páginas em `panel/src/app/clipper/(studio)/`) e `clip-editor*.ts(x)` — tabela em [references/clipper.md](references/clipper.md); vídeo final, dublagem e falantes em [clipper-video.md](references/clipper-video.md); papéis, juiz de contexto e linha do tempo em [clipper-ai-team.md](references/clipper-ai-team.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`/`cartoon`; áudio, visual e cartão de foto por trecho → MP4) | estado/banco/modo automático/"Gerar de novo" `panel/src/lib/montage.ts`; FFmpeg **sem banco** `montage-ffmpeg.ts` (cartão, textos em sequência); plano do trecho (`planShot`, `planShot3d`) e render Godot **sem banco** `montage-godot.ts`; biblioteca `scene-library.ts`; fotos `image-search.ts`; fala por extenso `speech-text.ts`; UI `components/montage-editor.tsx`; rotas `app/api/episodes/[id]/montage/` — ver [references/panel.md](references/panel.md#montagem-documental) | `doc/roteiro/comum.md` e `documental.md` se mudar regra de narração/trecho |
@@ -147,7 +147,7 @@ Interativa = 2–4 vertentes, mas o overlay só desenha `choiceA`/`choiceB`. Tab
- **Identificadores em inglês; comentários, mensagens e textos de UI em português.**
- **Chave de API das IAs** só pelo cofre do painel (`data/ai/vault.bin`, DPAPI) e só no ambiente da chamada; nunca em
arquivo, log, prompt ou nesta skill; não troque o login global das CLIs (sem `codex login --with-api-key`).
-- **Publicação:** nunca marque `published` sem ID/URL remota; nada sai sem aprovação (humana ou automática ligada
+- **Publicação:** nunca marque `published` sem ID/URL remota; corte de fonte só sai pelo vídeo **final** (`publishFile`), nunca pelo de revisão; 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
@@ -225,7 +225,7 @@ serviço de voz, Clipador, publicação ou Cartoon. As que mais custam caro:
continue à mão no outro provedor (131–135, 168–172, 175–179; [references/ai.md](references/ai.md)).
- **Correção que "não pegou" = serviço Python rodando código antigo (sem `--reload`): compare o início do processo com o
`LastWriteTime` do arquivo antes de validar (143).**
-- IA, login, chave, limites e Antigravity (168–172, 175–179). Publicação/modo sessão (137–155, 158–159), Cartoon (156, 157, 160–165) e Clipador (144, 166, 167, 173, 174, 180): ver o item citado em gotchas.
+- IA, login, chave, limites e Antigravity (168–172, 175–179). Publicação/modo sessão (137–155, 158–159), Cartoon (156, 157, 160–165) e Clipador (144, 166, 167, 173, 174, 180–186: publicar só o final, proxy 404, falantes, dublagem, worktree no Windows, serviços do usuário; 186 detecção do jogo): ver o item citado em gotchas.
## Manutenção desta skill
diff --git a/.claude/skills/cenaforge/references/ai.md b/.claude/skills/cenaforge/references/ai.md
index 3bfaf74..60366da 100644
--- a/.claude/skills/cenaforge/references/ai.md
+++ b/.claude/skills/cenaforge/references/ai.md
@@ -15,6 +15,7 @@ headless). Não duplique aqui; este arquivo diz onde mexer e o que não quebrar.
| API | `panel/src/app/api/ai/route.ts` (`GET/PUT /api/ai`), `.../ai/[provider]/route.ts` (`POST {action: install\|login\|verify\|test\|resume\|usage}`, `PUT/DELETE` = chave) | guarda `Origin`/JSON (gotchas, item 125) |
| Tela | `panel/src/components/ai-settings.tsx` em `panel/src/app/settings/ai/page.tsx`; seletor de provedor em `agent-console.tsx` e `story-composer.tsx` | — |
| Subpáginas de Configurações | `panel/src/app/settings/{ai,publishing,apps,browser,modes}/page.tsx` + `layout.tsx`; seções em `SETTINGS_SECTIONS` de `components/settings-shell.tsx` (o menu lateral `sidebar-nav.tsx` as lê como `children`); `/settings` redireciona para `/settings/ai` | seção nova = entrada em `SETTINGS_SECTIONS` + pasta |
+| Papéis do juiz (varredura/analista/editor/juiz de contexto, cada um com provedor+modelo+raciocínio+instruções; reserva por papel) | `clipper/app/roles.py`, `judge.py` (`Judge.ask(role=…)`), `panel/src/components/clipper-ai-team.tsx` — [clipper-ai-team.md](clipper-ai-team.md) | `clipper/tests/test_roles.py` |
| Juiz do Clipador (3 provedores, reserva por chamada) | `clipper/app/judge.py` (`_gemini`, `find_gemini`, `parse_gemini_output`), leitura de settings e cofre `clipper/app/ai_settings.py` (DPAPI por `ctypes`), `main.py`, `config.py`, `intel.py` | `clipper/tests/test_ai_fallback.py`, `conftest.py`, `clipper/README.md` |
## Regras
diff --git a/.claude/skills/cenaforge/references/clipper-ai-team.md b/.claude/skills/cenaforge/references/clipper-ai-team.md
new file mode 100644
index 0000000..06feacf
--- /dev/null
+++ b/.claude/skills/cenaforge/references/clipper-ai-team.md
@@ -0,0 +1,74 @@
+# Clipador — Equipe de IA: papéis, juiz de contexto, linha do tempo JSON e medição (18/11/2026)
+
+Fontes do contrato: `doc/clipador/EQUIPE-IA.md` (o que foi feito, F0 + F1) e `doc/clipador/PESQUISA-JUIZ.md` (pesquisa; F2
+OCR do HUD/YAMNet e F3 VLM local **não** entraram — são só candidatas). Visão geral: [clipper.md](clipper.md); provedores e
+reserva: [ai.md](ai.md). Migração v17 (`ai_calls`, `scene_notes`, `clips.owner_label/owner_note`).
+
+## Papéis (`clipper/app/roles.py`, `settings` chave `judge.roles`)
+
+| `id` | Faz | Imagem | Desligável |
+|---|---|---|---|
+| `scan` (varredura) | assiste por janelas, propõe momentos, descreve os quadros (`lines`) | mosaico 4×2 (padrão), soltos ou nenhuma | sim (`scanEnabled`) |
+| `analyst` | diz O QUE aconteceu no candidato | idem | sim (o editor passa a receber imagens) |
+| `editor` | decide corte, trecho, título, legenda, hashtags | só se o analista falhou/está off | **não** |
+| `judge` | só texto: o corte faz sentido para quem nunca viu a live? | nunca | sim |
+
+- Cada papel: `enabled`, `provider`, `model` (`""` = padrão do provedor), `effort` (só Codex; `""` = low; juiz começa em
+ `medium`), `extra` = **instruções do administrador** (≤ 2.000 caracteres, entram DEPOIS das padrão, que ficam no código e o
+ painel mostra só para leitura: `GET /v1/judge` → `roleDefaults..pt|en`). Juiz também: `critical`
+ (`setup`,`payoff`,`standalone`), `allowFix`, `allowContextLine`, `penalty` (0,5). Validação: `roles.normalize_roles`.
+- Banco sem `judge.roles` migra sozinho (o provedor/modelo único vira o de todos; `judge_analyst_model` fica no analista).
+ `judge_provider = "off"` continua = equipe inteira desligada. `PUT /v1/judge` sem `roles` (painel antigo) vale para todos.
+ Reserva por papel: `fallback_chain(primary)` começa na IA do papel. Tradução, perfil do jogo e câmera usam a IA do **editor**.
+
+## Juiz de contexto (`context_judge.py`, `judge.check_context`)
+
+Roda depois que o editor MANTEVE (nota ≥ mínima). Vê só o que vai no corte + 20 s antes/15 s depois marcados `out=1`, título,
+legenda, abertura, `what_happened` e linha do jogo. Escreve `viewer_summary` e responde 7 checagens: `setup`, `payoff`,
+`standalone` (críticas) · `who_what`, `intelligible`, `faithful`, `strong_open`. **O código decide** (`context_judge.decide`):
+
+1. crítica falha + `fix` (e `allowFix`) → recalcula com `fit_window`; mudou ≥ 1 s = **ajusta** e confere **uma** vez; falhou = descarta;
+2. crítica falha sem ajuste → **descarta** com motivo em português;
+3. `standalone`/`who_what` falhos + `context_line` curta (≤ 10 palavras, ≤ 60 caracteres) → aprova e a frase vira o texto de abertura;
+4. não críticas falhas tiram `penalty` da nota; abaixo da mínima → descarta;
+5. corte manual: só **avisa** (`decision: "warn"`); falha da IA do juiz: vale o editor (`context: {error}`).
+
+Gravado em `judge_json.context`; descartado pelo juiz = `status = discarded` + `judge_json.discardedBy = "context"` (aparece em
+"Descartados"; **Forçar render** funciona). Fonte em inglês: `CONTEXT_SCHEMA_EN` com bloco `pt`. Fora do F1: 2ª opinião
+com outro provedor, few-shot do dono, "testar nos últimos 10 cortes".
+
+## Linha do tempo JSON e mosaico (`timeline.py`, `media.mosaic`)
+
+- JSON Lines com chaves curtas: `t,d` · `v` (o que está na tela, ≤ 12 palavras; vem de `lines` da varredura/analista e fica em
+ `scene_notes`) · `sp` (fala literal ≤ 25 palavras; `[other1]` = outra pessoa) · `face` (rótulo de `reaction.label` com
+ intensidade ≥ 3) · `lvl` (só se ≥ 6 ou ≤ 1) · `chat`. Entrada nova a cada pausa > 1,2 s (se a atual tem ≥ 4 s), troca de
+ falante ou 8 s. Orçamento de caracteres por papel (analista 9.000, editor 7.000, juiz 6.000, varredura 9.000): passou, a
+ fala encurta (25 → 12 → 6 palavras). Perfil do jogo enxuto (`judge.lean_profile`).
+- Imagens: 8 quadros de 384×216 numa grade 4×2 = 1 imagem 1536×432; falhou = quadros soltos.
+- Opção **`timelineJson`** (`PUT /v1/judge`, padrão ligada): desligada = formato antigo (transcrição + chat + quadros de
+ 768 px). Cada chamada grava o modo em `ai_calls.mode` (`timeline+mosaic`, `legacy+frames`…) — é como se compara.
+- **Medido** (corte 291, sessão 15, tfue, IA falsa que guarda o prompt; fórmulas de imagem da pesquisa): analista 5.638 →
+ 3.104 tokens (−45 %), editor 2.795 → 2.250 (−20 %), varredura 5.330 → 3.311 (−38 %), juiz novo ≈ 1.420. Por hora (tfue):
+ ≈ 317 mil → ≈ 224 mil **com** o juiz (−29 %). **Uma** chamada real do juiz (Codex `gpt-6-luna`, esforço médio): 9.624 de
+ entrada, 1.400 de saída, 27 s ⇒ o **fixo da CLI do Codex ≈ 8 mil tokens por chamada** é o maior item e o próximo alvo
+ (gotchas, item 136; [token-economy.md](token-economy.md)).
+
+## Medição (F0)
+
+- `ai_calls` (v17): por tentativa — `role`, `purpose`, `provider`, `model`, `ok/error`, `ms`, tamanhos de prompt/imagem,
+ `tokens_in/out/cached` (quando a CLI informa: `codex exec --json`, `claude --output-format json`, `gemini -o json`),
+ `session_id`, `clip_id`, `mode`. O `codex exec` agora roda com `--json` (a resposta continua em `-o`).
+- Avaliação do dono: `clips.owner_label` (`good|bad|no_context`) + `owner_note`. `PATCH /v1/clips/{id}` com
+ `{"label": "no_context"}` (vale para qualquer corte, não muda o estado) ou `{"status": "rejected", "label": "no_context"}`
+ (botão **Sem contexto** no modal). Sem rótulo: aprovado/publicado = bom, rejeitado = ruim.
+- `GET /v1/judge/report?days=7` (ou `?session=N`): chamadas por papel × IA × modo, tokens por hora, cortes, juiz
+ (aprovou/ajustou/descartou/avisou/erro), concordância e κ de Cohen. Painel: Ajustes → Juiz → Medição. Rota na regex
+ `ALLOWED` do painel (`judge(\/report)?`).
+
+## Onde está cada coisa
+
+`roles.py` (papéis, validação, migração) · `judge.py` (`Judge.ask(role=…)`, `check_context`, `build_*_prompt`, `lean_profile`,
+`codex_usage`/`claude_usage`/`gemini_usage`, `scope`) · `context_judge.py` · `timeline.py` · `worker.py` (`judge_clip`:
+analista → editor → juiz; `_context_check`; `record_ai_call`) · `intel.py` (`visual`, varredura, `timelineJson`) · `report.py`.
+Painel: `clipper-ai-team.tsx` (cartões e medição), `clipper-judge.tsx`, `clipper-clip-parts.tsx` (`ContextVerdict`,
+`OwnerLabelControl`). Testes: `test_roles.py`, `test_context_judge.py`; `conftest._no_real_ai_cli` bloqueia qualquer CLI real.
diff --git a/.claude/skills/cenaforge/references/clipper-video.md b/.claude/skills/cenaforge/references/clipper-video.md
new file mode 100644
index 0000000..1afa9af
--- /dev/null
+++ b/.claude/skills/cenaforge/references/clipper-video.md
@@ -0,0 +1,92 @@
+# Clipador — vídeo de revisão × final, dublagem e falantes (18/11/2026)
+
+Fontes do contrato (leia antes de mexer, não duplique aqui): `doc/clipador/REVISAO.md`, `DUBLAGEM.md`, `FALANTES.md`.
+Visão geral do serviço: [clipper.md](clipper.md). Só vale depois de reiniciar o Clipador (gotchas, item 144).
+
+## Revisão × final (`doc/clipador/REVISAO.md`, migração v14)
+
+Regra do dono: o vídeo que a equipe aprova tem camadas **só de desenvolvimento**; ao aprovar, o Clipador renderiza de novo
+**sem elas** e só esse vai para as redes.
+
+```
+fila de render ─► clip-.mp4 REVISÃO (dev=True) ─► Aprovar ─► clip--final.mp4 (+ -final.jpg, -final-cover.jpg) (dev=False)
+ review_dev_json = [] ? ─► o de revisão JÁ É o final (sem render novo; final.reused = true)
+```
+
+- **Camadas `dev`** (grupo `dev` da configuração do corte, `layout.py`): `translation` (português embaixo da legenda) e
+ `dub` (dublagem). `layout.dev_flags(cfg, dev=False)` desliga todas. `caption.translation` é legado: conta como
+ `dev.translation`.
+- Render da fila = `worker._render_clip` → `editor_api.render_clip_edit(..., dev=True)`; grava `clips.review_dev_json`
+ (camadas que entraram de fato, `editor_api.review_layers`). Final: `Engine.render_pending` (finais primeiro, até 3 por
+ volta), mesmo projeto de edição, `dev=False`, não grava `review_dev_json`.
+- Banco v14: `clips.review_dev_json` (`[]` = nenhuma; NULL = desconhecido), `final_status` (`pending|rendering|ready|error`;
+ NULL = sem final), `final_file/thumb/cover/error/at`. Falha no final = `error` + `final_error`; o corte segue aprovado e
+ nada é publicado. Serviço caído no meio: `rendering` volta a `pending` na subida.
+- **O final some** (`drop_final`) ao: desfazer aprovação/rejeitar; mudar `startS/endS` de aprovado; `POST /export`,
+ `/render`, `/rejudge`; qualquer render de revisão novo. Desaprovar durante o render do final descarta o resultado.
+ `clip_delete` apaga `clip--*` e recusa enquanto o final renderiza.
+- API: cada corte traz `review: {devLayers}`, `final: {status,file,thumb,cover,error,at,reused} | null` e `publishFile`
+ (= `final.file` se `approved|published` com final `ready`; senão `null`). `file`/`thumb` continuam os de revisão.
+ `POST /v1/clips/{id}/final` (re)gera ("Tentar de novo"; 409 se não aprovado). Rota na regex `ALLOWED` e em `METHODS`
+ (`panel/src/lib/clipper.ts`).
+- **Publicação (painel):** `clipPublishFile(clip)` em `panel/src/lib/publishing-rules.ts` devolve `publishFile` ou o motivo
+ de esperar; **nunca** `file` quando o Clipador manda o campo (Clipador antigo, sem `publishFile`, segue com `file`).
+ `sendDue` (`publishing.ts`) relê o corte (`clipFinalForJob`): sem final pronto o job espera ("Esperando o vídeo final…");
+ com final, troca `file` (e a capa) e envia. Capa: a do final primeiro. Regras gerais: [publishing.md](publishing.md).
+- `prune` (`CLIPPER_KEEP_HOURS`) guarda o trecho de quem ainda vai precisar do final (aprovado com final pendente/erro;
+ pronto com camada de teste ou desconhecida). Corte sem camada de teste não segura blocos.
+- Painel: etiqueta `revisão · teste` / `gerando final` / `final` / `final com erro` na lista; modal com player
+ **Final / Revisão**, "Tentar de novo" e "Gerar vídeo final"; aviso no diálogo Publicar. Teste:
+ `clipper/tests/test_final_render.py`, `publishing-rules.test.ts`, `publishing-db.test.ts`.
+- Sem tradução (fonte em português) não há dublagem nem tradução: o de revisão já é o final.
+
+## Dublagem em português (`dub.py`, `doc/clipador/DUBLAGEM.md`)
+
+Para fonte em inglês, só no vídeo de revisão, para a equipe entender o contexto. **Sem sincronia labial** (pedido do dono).
+
+| Chave (`dev.*`) | Padrão | O quê |
+|---|---|---|
+| `dub` | `false` | liga a dublagem no vídeo de revisão (aba Legenda → "Dublagem em português (teste)") |
+| `dubVoice` | `pt-br-antonio` | voz do streamer (Edge, online) |
+| `dubVoiceOther` | `kokoro-pm-alex` | voz das falas `speaker: "other…"` (Kokoro, offline) |
+| `dubDuck` | `0.25` | volume do áudio original enquanto a dublagem toca (0–1) |
+
+- **Só vozes TTS prontas**; nunca clonar a voz do streamer (terceiro sem consentimento); o painel não lista clonadas.
+- Frases de `clips.translation_json` → tempo de saída → `POST /v1/synthesize` do serviço de voz (`format: "wav"`,
+ `speed: 1.05`; voz que falha cai em `pt-br-faber`). Cache `data/clipper/dub/` por (voz, velocidade, texto), −16 LUFS,
+ 48 kHz mono, 30 dias sem uso apaga. Encaixe `fit`: fala em velocidade natural, pode escorrer até 1,5 s sobre a próxima
+ frase (sem acumular); só então acelera até 1,2× e, se ainda não couber, corta com fade. Original abaixa para `dubDuck`
+ (rampa 0,15 s) só onde há dublagem; dublagem 6 dB acima do volume médio do corte (−20…+3 dB).
+- Prévia do editor e render da fila usam o mesmo caminho (`dub.for_engine`). Serviço de voz fora = sai sem dublagem.
+- **Medido** (corte 259 do tfue, 54,5 s, 25 frases, NVENC, informado em `DUBLAGEM.md`): sem dublagem 5,8 s; 1ª vez
+ +29 a +41 s (~1,6 s/frase, 3 em paralelo; 6 não ajudam); cache pronto +0,3 s; prévia de 5 s com cache 1,2 s. Conversa
+ densa: o português fica bem mais longo (9 das 25 falas terminaram cortadas com fade). Teste: `test_dub.py` (TTS falso).
+
+## Quem fala (`speakers.py`, `voiceprint.py`, `doc/clipador/FALANTES.md`, migração v15)
+
+O áudio da live é um canal só: streamer, colegas no Discord e voz do jogo misturados. **As outras vozes NÃO estão na
+câmera**; a webcam só ajuda a confirmar qual voz é o streamer.
+
+- **Impressão de voz:** WeSpeaker ResNet34-LM (`models.lock.json` id `wespeaker_r34`, pesos **CC-BY-4.0**, atribuição
+ "WeSpeaker, wenet-e2e", 26,5 MB, sha256 no lock) no `onnxruntime` (sem PyTorch; fbank reimplementado em numpy). Nada de
+ pyannote/SpeechBrain/NeMo/Resemblyzer (pedem PyTorch). 3D-Speaker CAM++ ficou fora: licença dos pesos não conferida.
+- Etapas: `speakers.index_block` (logo após o Whisper, 0,19 s de CPU por bloco de 30 s) → `face.MouthMeter` (YuNet, boca na
+ webcam, +0,5 s por bloco) → `speakers.build_model` sob demanda (0,05 s em 72 min; refeito na leitura, o rótulo melhora
+ sozinho com a live). Tabela `voice_chunks (session_id, idx, data_json, updated_at)` = **migração v15** (~0,6 MB/h).
+- Regras: trechos ≤ 3 s, fecham em `. ? !`; voz = grupo com ≥ 15 s de fala (cosseno ≥ 0,5). Streamer = a voz que bate com a
+ boca (t de Welch ≥ 3) **e/ou** a mais forte (≥ 3 dB acima da 2ª). **Discordam ou nenhuma decide → ninguém vira
+ "outro"** (tudo do streamer, como antes). Trecho só vira `otherN` com folga (cosseno ≥ 0,30 e ≥ 0,10 acima do streamer).
+- Dados: `scoring.Word.speaker` (`""`/`"streamer"` ou `"other1"…`); `segments.words_json` aceita o 4º elemento; o projeto do
+ editor ganha `sp` por palavra (projeto antigo sem `sp` sai igual); `translation_json` por linha tem `speaker` e frases
+ nunca misturam falantes (tradução antiga sem `speaker` é refeita). `GET /v1/sessions/{id}/speakers` mostra as vozes e
+ o porquê. Opção `speakers` (`intel.opts`, padrão ligada) desliga tudo.
+- **Legenda em duas linhas:** streamer na posição normal; outra pessoa logo abaixo (`caption.otherColor` `#5CE1FF`,
+ `caption.otherSize` vazio = 85 % de `size`); no horizontal a linha do streamer sobe. Estilos `CaptionOther`/`KaraokeOther`
+ só entram no ASS quando há outra pessoa: corte só com o streamer sai byte a byte igual (teste dourado do vertical).
+ Editor: botão **Outra pessoa / É o streamer** corrige palavras selecionadas.
+- **Juízes:** `judge._transcript` marca `[Tfue]`/`[other1]` e manda "Never attribute to Tfue what someone else said".
+- **Medido** (sessão 15, tfue, 144 blocos, só leitura; em `FALANTES.md`): 3 vozes; volume do streamer +7,5 dB sobre os
+ colegas; boca sozinha **não** resolve (webcam de perfil, AUC 0,55–0,64), quem decide é o volume; estabilidade 84 % aos
+ 5 min, 98 % aos 10, 99 % aos 40. Conferência visual às cegas fraca (rosto de 45 px). Sem gabarito de áudio.
+- Limites: troca de falante sem pausa nem pontuação fica com um rótulo; primeiros minutos (< 15 s de fala por voz) sem
+ atribuição; vozes de NPC também viram "outra pessoa"; modelo indisponível = blocos sem impressão (não refeitos).
diff --git a/.claude/skills/cenaforge/references/clipper.md b/.claude/skills/cenaforge/references/clipper.md
index 2c16b5d..f2c1543 100644
--- a/.claude/skills/cenaforge/references/clipper.md
+++ b/.claude/skills/cenaforge/references/clipper.md
@@ -12,7 +12,7 @@ renderiza cortes verticais (1080×1920, padrão) ou horizontais (1920×1080, You
| O quê | Onde |
|---|---|
-| Banco do Clipador | `data/clipper/clipper.db` (`PRAGMA user_version` 16, `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); v11 `channels.monitor_paused_at`/`monitor_paused_session`/`language` e `sessions.language`, padrão `''` = `CLIPPER_LANGUAGE`; v12 `games.profile_ai_json` (perfil em inglês), `translated_at`, `aliases_json`; v13 `clips.translation_json`, fala do corte em frases + português; v14 vídeo de revisão × final em `clips` (`review_dev_json`, `final_*`; `doc/clipador/REVISAO.md`); v15 tabela `voice_chunks` (falantes; `doc/clipador/FALANTES.md`); v16 `sessions.game_status` + `sessions.game_detect_json`, seção "Detecção do jogo da live"). 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 |
+| Banco do Clipador | `data/clipper/clipper.db` (`PRAGMA user_version` 17, `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); v11 `channels.monitor_paused_at`/`monitor_paused_session`/`language` e `sessions.language`, padrão `''` = `CLIPPER_LANGUAGE`; v12 `games.profile_ai_json` (perfil em inglês), `translated_at`, `aliases_json`; v13 `clips.translation_json`, fala do corte em frases + português; v14 vídeo de revisão × final (`clips.review_dev_json`, `final_status/file/thumb/cover/error/at`); v15 `voice_chunks` (impressão de voz); v16 detecção do jogo (`sessions.game_status`, `game_detect_json`; vem de outra frente, o doc `DETECCAO-JOGO.md` ainda não está nesta branch); v17 `ai_calls`, `scene_notes`, `clips.owner_label/owner_note`). Detalhes de v14–v15 em [clipper-video.md](clipper-video.md), de v17 em [clipper-ai-team.md](clipper-ai-team.md). 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//` (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//clip-.mp4` + `clip-.jpg` |
@@ -31,6 +31,11 @@ renderiza cortes verticais (1080×1920, padrão) ou horizontais (1920×1080, You
| 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 |
| Parar à mão e pausa do monitor (`Engine.stop_session(id, pause_monitor=True)`, `StopIn.pauseMonitor`), idioma por fonte/sessão (`check_language`, visões de fonte/sessão/corte com `language` resolvido; Whisper e `judge.output_language_note`) | `clipper/app/worker.py`, `main.py`, `db.py` (v11), `judge.py`; painel `ACCOUNT_LANGUAGES` em `panel/src/lib/languages.ts` | `clipper/tests/test_monitor_pause_and_language.py` (9); seção "Parar é parar e idioma" abaixo |
| Fonte em outro idioma (inglês): prompts `*_EN`, schemas com bloco `pt`, `lang_key`, `translate_lines`, `translate_clip`, `voice_language`, `phrases`, legenda `Trans` | `clipper/app/judge.py`, `intel.py` (`Intel.lang`), `worker.py`, `subtitles.py`, `scoring.py`, `layout.py`, `editor_render.py`, `editor_api.py` (`translation_for`), `main.py`; painel `clipper-client.ts`, `clipper-clip-dialog.tsx`, `clipper-clip-parts.tsx`, `clipper-clip-table.tsx`, `clipper-session-detail.tsx`, `clipper-cut-settings.tsx` | `clipper/tests/test_english_source.py` (9); seção "Fonte em inglês" abaixo |
+| Vídeo de revisão × final (`dev_flags`, `render_clip_edit(dev=…)`, `review_layers`, `render_final`, `drop_final`, rota `POST /v1/clips/{id}/final`, `publishFile`) | `clipper/app/layout.py`, `editor_api.py`, `worker.py`, `main.py`; painel `panel/src/lib/publishing-rules.ts` (`clipPublishFile`), `publishing.ts` (`sendDue`), `clipper-clip-dialog.tsx`, `clipper-clip-table.tsx` | `clipper/tests/test_final_render.py`, `publishing-rules.test.ts`, `publishing-db.test.ts`; seção em [clipper-video.md](clipper-video.md) |
+| Dublagem em português (`dev.dub*`, TTS, cache, encaixe, `duck`) | `clipper/app/dub.py` + `editor_render.py` (mistura) + serviço de voz `POST /v1/synthesize` | `clipper/tests/test_dub.py`; [clipper-video.md](clipper-video.md) |
+| Falantes (streamer × `otherN`): impressão de voz, boca, legenda em duas linhas, `GET /v1/sessions/{id}/speakers` | `clipper/app/speakers.py`, `voiceprint.py`, `face.py` (`MouthMeter`), `subtitles.py`, `judge.py` (`_transcript`); peso `wespeaker_r34` em `clipper/models.lock.json` | `clipper/tests/test_speakers.py`; [clipper-video.md](clipper-video.md) |
+| Expressões, pose da cabeça e corpo do streamer; mapa de expressões | lógica `clipper/app/reaction.py` (`label`, `body_moments`, `expression_map`, `extra_weights`), E/S `face.py` (`pose_from_matrix`, reserva do YuNet); painel `clipper-face-map.tsx` | `clipper/tests/test_expressions.py`; seção "Expressões" em "Rastreio de reação" abaixo |
+| Equipe de IA: papéis (`judge.roles`), juiz de contexto, linha do tempo JSON + mosaico (`timelineJson`), medição (`ai_calls`, `GET /v1/judge/report`), rótulo do dono | `clipper/app/roles.py`, `context_judge.py`, `timeline.py`, `report.py`, `judge.py`, `worker.py`, `intel.py`; painel `clipper-ai-team.tsx`, `clipper-judge.tsx`, `clipper-clip-parts.tsx` | `clipper/tests/test_roles.py`, `test_context_judge.py`; [clipper-ai-team.md](clipper-ai-team.md) |
| 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` |
@@ -82,7 +87,10 @@ renderiza cortes verticais (1080×1920, padrão) ou horizontais (1920×1080, You
`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.
+ `scanIntervalS`, `vision`, `camDetect`, `faceTrack`, `timelineJson`, `roles`. Fica na tabela `settings`, sem reiniciar; o `.env` só dá o valor inicial.
+- **Equipe de IA (18/11/2026):** hoje são quatro papéis (varredura, analista, editor e o **juiz de contexto**), cada um com
+ provedor + modelo + raciocínio + instruções do administrador (`judge.roles`), e a IA lê a live como linha do tempo JSON
+ (`timelineJson`). Tudo em [clipper-ai-team.md](clipper-ai-team.md); o texto acima descreve o fluxo base analista → editor.
- 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
@@ -236,6 +244,26 @@ medições em `doc/FACE_BAKEOFF.md`. Roda no PC, sem IA. Opção `faceTrack` (pa
(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).
+- **Expressões, cabeça e corpo** (18/11/2026; `doc/clipador/EXPRESSOES.md`, sem migração: os campos novos vão no
+ `data_json` de `face_track`, séries antigas continuam valendo):
+ - Rótulos novos só a partir de blendshapes que já vinham: `gargalhada` (risada + cabeça ≥ 20° para trás), `alegria` (só no
+ mapa), `medo`, `nojo`, `tristeza`, `espanto`, `tenso`, `bocejo`. Além dos antigos (`risada`, `grito`, `susto`, `choque`,
+ `raiva`, `confuso`). Pose (yaw/pitch/roll) vem da matriz de transformação facial do MediaPipe
+ (`output_facial_transformation_matrixes=True`, `face.pose_from_matrix`).
+ - **Reserva do YuNet:** quando o MediaPipe perde o rosto (streamer de perfil), o YuNet roda **só nesse quadro** (5,3 ms) e dá a
+ caixa da cabeça → corpo: `balançando`, `acenando`, `agitado`, `chegou perto`, `saiu do quadro` (`reaction.body_moments`;
+ "saiu" só com o campo `head`). Rastreio perdido nunca vira movimento.
+ - **Canais novos só dão nome, não criam picos:** `ReactionParams.extra_weights` = 0 (a intensidade alimenta nota e fonte
+ `face`; mexer sem conjunto aprovado/rejeitado maior seria chute). Ligar um canal = dar peso lá e medir de novo. Única mudança
+ nos picos: bocejo deixou de contar como grito.
+ - **Calibração (dados reais, 4 sessões):** bocejos eram os maiores "gritos" (jawOpen ≥ 0,6 por 3 s); `noseSneerLeft/Right`,
+ `cheekSquintLeft/Right`, `cheekPuff` são sempre ~0 no MediaPipe (nojo usa o lábio de cima); mão no rosto ainda engana a
+ boca (tristeza/espanto/medo/raiva no mapa); cadeira vazia pode gerar "rosto fantasma"; balançar a 6 qps é movimento, não
+ "não" literal. Série de 1,7 h: ~1,4 MB/h no banco; análise ~1 s.
+ - API: `GET /v1/sessions/{id}/face` ganha `expr`/`body` por segundo e `body: [{startS,endS,peakS,label,value}]`; a linha
+ "Rosto do streamer" do analista leva até 2 movimentos do corpo (com rosto de perfil: "sem expressão legível… saiu do quadro").
+ Painel: **Mapa de expressões** no modal do corte (`clipper-face-map.tsx`), chip `FaceSignal` com os rótulos novos.
+ - **Não verificado:** serviço real rodando o código novo; painel no navegador (só `tsc`); câmera escura/minúscula além da do tfue.
- **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
@@ -367,16 +395,18 @@ Fonte do contrato: `doc/clipador/IDIOMAS.md`; README do Clipador, "Idioma por fo
`clips.translation_json` `{language, startS, endS, model, lines: [{s, e, text, pt}]}`; frases de `subtitles.phrases`
(pausa > 0,7 s, fim de frase com 4+ palavras, 16 palavras ou 6 s) traduzidas por `Judge.translate_lines`.
`POST /v1/clips/{id}/translate` refaz (409 em fonte PT); `clip_view.translation`.
-- **Legenda em português no vídeo (só para desenvolver):** `caption.translation` (padrão `false`) → estilo ASS `Trans`
- (metade do tamanho, `&H00FFE79B`, `n8` + `\q0`) sob a legenda, seguindo o desvio do gancho; só entra no ASS quando
- ligado **e** há tradução (sem isso o ASS é idêntico ao de antes). `editor_api.translation_for` alimenta render e prévia.
- **Nunca publicar com isto ligado.**
+- **Legenda em português no vídeo (só para desenvolver):** `dev.translation` (padrão `false`; `caption.translation` é o legado, ainda lido) → estilo ASS `Trans`
+ (metade do tamanho, `&H00FFE79B`) sob a legenda, seguindo o desvio do gancho; só entra no ASS quando ligado **e** há
+ tradução (sem isso o ASS é idêntico ao de antes). `editor_api.translation_for` alimenta render e prévia. Entra só no
+ **vídeo de revisão**: o final, gerado ao aprovar, sai sem ela ([clipper-video.md](clipper-video.md); dublagem: mesma seção).
- **Heurística:** `scoring.py` (`REACTION_PATTERNS`, `SPOKEN_REACTION`) reconhece reação em inglês (lmao, lol, 💀, 😭, no
way, bruh, holy, clutch, goated, clip that…). `judge.output_language_note` agora é vazio também para inglês.
- **Voz:** `worker.VOICE_LANGUAGES`/`voice_language()` converte `en-US` → `en` e `es-419` → `es` antes do Whisper (gotchas, item 173).
- **Começar uma fonte gringa:** Fontes → idioma English (US); jogo com perfil em inglês e gírias do público gringo
(Jogos → "acrescente as gírias…", ou `POST /v1/games/{id}/translate` se o perfil só existe em português); ligar
- "Tradução em português embaixo (teste)" na configuração do corte do canal enquanto estiver testando.
+ "Tradução em português embaixo (teste)" (e, se quiser, "Dublagem em português (teste)") na configuração do corte do
+ canal enquanto estiver testando. Fontes em teste (18/11/2026): twitch-tfue (ROB RUN) e twitch-maxylobes (GTA V Chaos
+ Mod, en-US, `dev.translation` + `dev.dub` ligados).
- **Painel:** modal do corte com bloco "Em português" (título, legenda, "O que ele fala" frase a frase, botão "Traduzir a
fala"); lista com título traduzido (🇧🇷); resumo da sessão em português; switch em `clipper-cut-settings.tsx`; Fontes: a
coluna "Ao vivo" mostra "gravando #N" da sessão ativa e checagem do monitor com mais de 10 min vira "ao vivo há X"
@@ -495,7 +525,16 @@ exit 0, 440 testes (pontos contados na saída; o `pytest.ini` usa `-q` e não im
manutenção); `tests/test_game_detect.py` tem 15 testes (o lote informou 14); `npx tsc --noEmit -p panel` → exit 0
(reexecutado). Não verificado: IA real em `Judge.detect_game` e nos prompts com os campos novos; o painel no navegador;
banco real em v16 (o serviço precisa reiniciar); o botão "Detectar agora" contra o serviço — o proxy do painel não tem
-`game/detect` no `ALLOWED` (gotchas, item 180).
+`game/detect` no `ALLOWED` (gotchas, item 186; já corrigido).
+
+Bloco de 18/11/2026 (revisão × final, dublagem, falantes, expressões, Equipe de IA e proxy): **informado pelo coordenador**
+(não reexecutado por mim): suíte inteira do Clipador passa; painel `tsc` + 119 testes. Testes novos: `test_final_render.py`,
+`test_dub.py`, `test_speakers.py`, `test_expressions.py`, `test_roles.py`, `test_context_judge.py`. Medidas citadas (tempo da
+dublagem, custo da voz, estabilidade dos falantes, tokens por hora) vêm dos docs de `doc/clipador/` e estão nas seções
+próprias. Não verificado: serviços reais com o código novo (precisam reiniciar), UI no navegador, juiz/dublagem/voz com IA e
+TTS reais além dos cortes citados, banco real em v17. `onnxruntime` 1.32.0 e `mediapipe` 1.2.3 reconferidos no `clipper/.venv`.
+O proxy do painel liberou `POST clips/{id}/translate` e `GET sessions/{id}/speakers` (sem isso o botão "Traduzir a fala"
+dava 404; regex `ALLOWED` + `METHODS` em `panel/src/lib/clipper.ts`).
Fonte em inglês (18/11/2026): `pnpm test:clipper` → **346 passed** (reexecutado nesta manutenção, 101 s); `test_english_source.py`
novo (9 testes) e ajustes em `test_monitor_pause_and_language.py`, `test_render_and_duplicates.py`, `test_intel.py`. Não
diff --git a/.claude/skills/cenaforge/references/gotchas.md b/.claude/skills/cenaforge/references/gotchas.md
index 9bceb91..f7a6abc 100644
--- a/.claude/skills/cenaforge/references/gotchas.md
+++ b/.claude/skills/cenaforge/references/gotchas.md
@@ -508,6 +508,35 @@ Observadas em 17/11/2026 (diagnóstico da sessão 3, cartão da sessão, apagar
**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`.
+Observadas em 18/11/2026 (revisão × final, falantes, dublagem, trabalho em worktree):
+
+180. **Corte aprovado "não publica" e o job fica parado.** Causa: a publicação só usa o vídeo FINAL (`publishFile`); enquanto
+ `final_status` não é `ready` o job mostra "Esperando o vídeo final…" (final `pending`/`rendering`, ou `error`).
+ Correção: olhe `final` no corte (`GET /v1/clips`, campos `final` e `publishFile`); `error` → "Tentar de novo" = `POST /v1/clips/{id}/final`.
+ Nunca troque para `file` (é o de revisão, com camadas de teste). Corte antigo publicado com tradução e sem final: gere
+ com `POST /final` antes de mandar a outra rede. Onde: `clipPublishFile` (`panel/src/lib/publishing-rules.ts`),
+ `sendDue` (`publishing.ts`); doc `doc/clipador/REVISAO.md`.
+181. **Botão "Traduzir a fala" (e a lista de vozes) dava 404.** Causa: a rota existia no Clipador, mas a regex `ALLOWED` do
+ proxy do painel não liberava `clips/{id}/translate` nem `sessions/{id}/speakers`. Correção: liberadas em `ALLOWED` +
+ `METHODS`. Rota nova do Clipador = regex, método e timeout em `panel/src/lib/clipper.ts` no mesmo commit.
+182. **Fala do colega aparece como do streamer (ou tudo em uma linha só).** Causa esperada, não bug: sem atribuição nos
+ primeiros minutos (< 15 s de fala por voz); volume e boca **discordam** ou nenhum decide → ninguém vira "outro"; webcam
+ de perfil não separa pela boca; o código novo só roda depois de reiniciar o Clipador. Correção: confira
+ `GET /v1/sessions/{id}/speakers` (vozes e por quê); corrija à mão no editor (**Outra pessoa / É o streamer**).
+ Onde: `clipper/app/speakers.py`; `doc/clipador/FALANTES.md`.
+183. **Dublagem soa corrida, emendada ou cortada no fim.** Causa: o português sai bem mais longo que o inglês; o encaixe
+ deixa a fala escorrer até 1,5 s sobre a próxima frase, acelera até 1,2× e por fim corta com fade (medido: 9 de 25 falas
+ cortadas no corte 259). Não é falha; **não** acelere além disso nem clone a voz do streamer. A 1ª renderização sintetiza
+ (~1,6 s por frase); depois o cache (`data/clipper/dub/`) deixa +0,3 s. Onde: `clipper/app/dub.py` (`fit`).
+184. **Worktree de isolamento do harness falha no Windows.** Causa: diferença de caixa da letra do drive (`f:` × `F:`).
+ Correção: criar a worktree à mão em `F:/Projects/cf-wt/` (`git worktree add`). Para rodar testes nela: copiar
+ `clipper/tests/data/vertical_golden_sha256.json` (ignorado no git, o teste dourado do vertical precisa dele) e criar
+ um junction `panel/node_modules` apontando para o da pasta principal (sem isso `tsc` e os testes do painel não rodam).
+185. **Serviço "não pegou" ou "caiu e não voltou".** Os serviços (painel, voz, Clipador, Publicador) são do usuário, subidos
+ por `pnpm dev`: agente **não** sobe nem encerra. O `scripts/dev.ts` pula um serviço se a porta já está ocupada e só
+ reinicia sozinho a voz (quando `voice/.env` muda); serviço que cai não volta. Peça ao usuário para reiniciar o `pnpm
+ dev` (com a suíte verde: item 87) e compare o início do processo com o arquivo (item 143).
+
## 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
@@ -798,7 +827,7 @@ observada num envio real ainda. Contexto em [publishing.md](publishing.md).
sessão gravando era a do Tfue. Correção: a coluna mostra "gravando #N" da sessão ativa e trata checagem com mais de
10 min como "ao vivo há X" apagado. Onde: `panel/src/components/clipper-channels.tsx`.
-180. **Clipador: o jogo da sessão não é detectado, fica `unknown`, ou "Detectar agora" falha.** Conferido no código em
+186. **Clipador: o jogo da sessão não é detectado, fica `unknown`, ou "Detectar agora" falha.** Conferido no código em
18/11/2026. Causas, por ordem: (a) serviço sem reiniciar (item 144): a migração v16 não roda, `game_status` e
`gameDetect` não existem e `POST …/game/detect` dá 404; reinicie (é do usuário) e confira `PRAGMA user_version` = 16.
(b) Chat e fala só reconhecem jogos **já cadastrados** em Jogos (nome, id ou alias): jogo novo só aparece por
diff --git a/.claude/skills/cenaforge/references/panel.md b/.claude/skills/cenaforge/references/panel.md
index d86ea34..aab6254 100644
--- a/.claude/skills/cenaforge/references/panel.md
+++ b/.claude/skills/cenaforge/references/panel.md
@@ -355,12 +355,12 @@ sidebar (`sidebar-nav.tsx`) mostra os mesmos subitens quando o Clipador está at
| Rota | Conteúdo | Arquivos |
|---|---|---|
-| `/clipper` Cortes | lista `ClipTable` (uma linha por corte; ações rápidas Aprovar/Rejeitar/Publicar), filtros na URL (`?stage ?source ?session ?lang`), modal `ClipDialog` por `?clip=ID` com anterior/próximo; em fonte inglesa, bloco "Em português" e título traduzido na lista ([clipper.md](clipper.md#fonte-em-inglês-18112026)) | `clipper-clips-page.tsx`, `clipper-clip-table.tsx`, `clipper-clip-dialog.tsx`, `clipper-clip-parts.tsx`; ordenar/apagar/selecionar em utilitários de `clipper-queue.tsx` |
+| `/clipper` Cortes | lista `ClipTable` (uma linha por corte; ações rápidas Aprovar/Rejeitar/Publicar), filtros na URL (`?stage ?source ?session ?lang`), modal `ClipDialog` por `?clip=ID` com anterior/próximo; em fonte inglesa, bloco "Em português" e título traduzido na lista ([clipper.md](clipper.md#fonte-em-inglês-18112026)); etiquetas e player **Final / Revisão** do vídeo final, **Mapa de expressões**, "O que falam" por falante, botão **Sem contexto** e veredito do juiz de contexto ([clipper-video.md](clipper-video.md), [clipper-ai-team.md](clipper-ai-team.md)) | `clipper-clips-page.tsx`, `clipper-clip-table.tsx`, `clipper-clip-dialog.tsx`, `clipper-clip-parts.tsx`; ordenar/apagar/selecionar em utilitários de `clipper-queue.tsx` |
| `/clipper/sessions` | lista de sessões; "Gravar pelo link" em diálogo (`RecordForm`) | `clipper-sessions-page.tsx` |
| `/clipper/sessions/[id]` | saúde, resumo da IA, tiles, gráfico do chat, emotes, configuração do corte | `clipper-session-detail.tsx` |
| `/clipper/sources` | fontes em tabela, "Adicionar fonte" em diálogo, monitor ligado/**pausado** + Religar, idioma da live, canais de publicação; coluna "Ao vivo" = "gravando #N" (sessão ativa) ou "ao vivo há X" apagado se a checagem tem > 10 min (gotchas, item 174) | `clipper-channels.tsx` |
| `/clipper/games` | jogos em tabela (nome, gênero, estado, missões, última pesquisa/edição), "Adicionar jogo" em diálogo, `?game=ID` abre o modal do jogo e emotes do canal | `clipper-games-page.tsx`, `clipper-game-dialog.tsx` (modal), `clipper-game-parts.tsx` (seções, `AiChat`, editor à mão), `clipper-games.tsx` |
-| `/clipper/settings` | abas Juiz (IA) / Serviço / Idiomas e públicos | `clipper-settings-page.tsx`, `clipper-judge.tsx` |
+| `/clipper/settings` | abas Juiz (IA) / Serviço / Idiomas e públicos; em Juiz, a **Equipe de IA** (um cartão por papel: provedor, modelo, raciocínio, instruções do administrador, mosaico/`timelineJson`) e a **Medição** ([clipper-ai-team.md](clipper-ai-team.md)) | `clipper-settings-page.tsx`, `clipper-judge.tsx`, `clipper-ai-team.tsx` |
| `/clipper/edit/[clipId]` | editor em tela cheia, **fora** do grupo `(studio)` | ver "Editor de cortes" |
`clipper-studio.tsx` foi **apagado**; `clipper-queue.tsx` virou só utilitários da lista (a lista é `ClipTable`);
diff --git a/.claude/skills/cenaforge/references/publishing.md b/.claude/skills/cenaforge/references/publishing.md
index 3b11c41..4c1c01f 100644
--- a/.claude/skills/cenaforge/references/publishing.md
+++ b/.claude/skills/cenaforge/references/publishing.md
@@ -74,6 +74,9 @@ No texto visível do Clipador "Canais" virou **"Fontes"**; código, tabelas e ro
- 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.
+- **Só o vídeo FINAL sai** (18/11/2026): corte de fonte com camadas de teste (tradução, dublagem) tem um vídeo de revisão e, ao
+ aprovar, um final sem elas. `clipPublishFile` (`publishing-rules.ts`) devolve `publishFile` ou o motivo de esperar; `sendDue`
+ relê o corte e deixa o job em "Esperando o vídeo final…" até estar pronto; nunca use `file`. Detalhes: [clipper-video.md](clipper-video.md), gotchas 180.
- **Botão "Publicar" do corte** (`POST /api/publishing/clips/`, corpo `{accountId, platforms[], timing?: "now"|"best_slot"}`,
resposta `{jobs, skipped[{platform, reason}], placed}`; `publishClip`; `timing` também aceita `"at"`, ver abaixo): 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.
diff --git a/.claude/skills/cenaforge/references/tools.md b/.claude/skills/cenaforge/references/tools.md
index d0d8c1e..b5c2b11 100644
--- a/.claude/skills/cenaforge/references/tools.md
+++ b/.claude/skills/cenaforge/references/tools.md
@@ -142,6 +142,7 @@ no `clipper/.venv` em 16/11/2026 (`importlib.metadata`). Evidência (`doc/FACE_B
| 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 + WeSpeaker ResNet34-LM `wespeaker_voxceleb_resnet34_LM.onnx` (`wespeaker_r34` no lock, commit `f0c48c2…`) | 1.32.0 (onnxruntime reconferido em 18/11/2026) | CC-BY-4.0 (pesos; atribuição "WeSpeaker, wenet-e2e") | impressão de voz: quem fala cada palavra (streamer × `otherN`); 0,19 s de CPU por bloco de 30 s. Medido em `doc/clipador/FALANTES.md` (sessão 15, informado; **não reexecutado** aqui). Quadro: [clipper-video.md](clipper-video.md) |
| 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/`.
diff --git a/clipper/README.md b/clipper/README.md
index 9054f48..544dd25 100644
--- a/clipper/README.md
+++ b/clipper/README.md
@@ -444,7 +444,8 @@ chave `clipper--`; num banco novo as sessões recomeçam do 1 e
|---|---|
| `GET /health` | sem chave |
| `GET /v1/status` | ferramentas, voz, juiz, gravações ativas |
-| `GET/PUT /v1/judge` | provedor, modelos (editor/analista), nota mínima, varredura, visão, câmera (+ lista de modelos) |
+| `GET/PUT /v1/judge` | Equipe de IA (`roles`: varredura, analista, editor, juiz — provedor, modelo, esforço, liga/desliga, instruções do administrador; `roleDefaults` = instruções padrão), nota mínima, varredura, visão, câmera, `timelineJson` (+ lista de modelos) — doc/clipador/EQUIPE-IA.md |
+| `GET /v1/judge/report?days=&session=` | medição: chamadas e tokens por papel/IA por hora de live, aprovação, decisões do juiz de contexto, concordância juiz × dono |
| `GET/PUT /v1/channels/{id}/settings` · `GET/PUT /v1/sessions/{id}/settings` | configuração do corte: `own`, `effective`, `defaults` (com `format`, `duration` e `hook`), `modes`, `fonts`, `fontFiles` (`{família: "assets/fonts/…ttf"}` das empacotadas, relativo à raiz do repositório), `hookStyles`, `hookAnims`, `aspects`, `frames` (`{vertical, horizontal: {width, height, canvasWidth, canvasHeight}}`, para o painel desenhar a prévia) e `captureQualities` (`[{id, label, maxHeight, gbPerHour, gbPerHourMax, hint}]`) |
| `GET /v1/sessions/{id}/frame?t=` · `POST …/preview` · `POST …/detect-cam[?ai=true]` | quadro para o editor, prévia do layout, achar webcam (local primeiro) |
| `GET /v1/sessions/{id}/face?from=&to=` · `POST …/face/reset` | série por segundo do rosto (cx/cy/size no quadro inteiro, expressões, `signal`) e picos; refazer o rastreio |
diff --git a/clipper/app/context_judge.py b/clipper/app/context_judge.py
new file mode 100644
index 0000000..b492858
--- /dev/null
+++ b/clipper/app/context_judge.py
@@ -0,0 +1,116 @@
+"""Decisão do JUIZ de contexto pelo código (doc/clipador/EQUIPE-IA.md).
+
+O juiz (IA, só texto) responde perguntas sim/não sobre o corte; quem decide é esta função, com regras fixas e
+calibráveis no painel (papel `judge` em `judge.roles`):
+
+- checagem **crítica** que falhou (padrão: começo, desfecho, funciona sozinho) + ajuste de trecho dentro dos limites
+ → **ajusta** (o trecho é recalculado com `fit_window`) e o juiz confere UMA vez de novo; falhou de novo → descarta;
+- crítica que falhou sem ajuste possível → **descarta** com o motivo em português;
+- "funciona sozinho" (e "quem/o quê") falho + frase de contexto → a frase resolve: vai na tela no começo do corte;
+- checagem não crítica que falhou só **baixa a nota** (`penalty` por checagem); abaixo da nota mínima → descarta;
+- corte manual ("cortar agora"): o juiz só **avisa**, nunca descarta nem mexe no trecho.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from .roles import CHECK_NAMES, CHECKS, DEFAULT_CRITICAL, DEFAULT_PENALTY
+from .scoring import fit_window
+
+MIN_SHIFT_S = 1.0 # ajuste menor que isso não muda nada: conta como "sem ajuste"
+CONTEXT_LINE_MAX_WORDS = 10
+CONTEXT_LINE_MAX_CHARS = 60
+OUT_BEFORE_S = 20.0 # o juiz vê 20 s antes do corte, marcados out=1 (o espectador não vê)…
+OUT_AFTER_S = 15.0 # …e 15 s depois (para notar o desfecho que ficou de fora)
+# O que a frase de contexto resolve (ela dá ao espectador frio quem/o quê e o pano de fundo).
+SOLVED_BY_LINE = ("standalone", "who_what")
+
+
+@dataclass
+class Decision:
+ action: str # approve | adjust | discard | warn
+ failed: list[str] = field(default_factory=list) # todas as checagens que falharam
+ failed_critical: list[str] = field(default_factory=list) # críticas que falharam e a frase não resolveu
+ solved_by_line: list[str] = field(default_factory=list)
+ window: tuple[float, float] | None = None # trecho novo (só em adjust)
+ context_line: str = ""
+ score_after: float | None = None
+ reason_pt: str = ""
+
+
+def usable_line(text: str) -> str:
+ """Frase de contexto que cabe na tela no começo do corte (curta); senão vazia."""
+ text = " ".join((text or "").split())
+ if not text or len(text) > CONTEXT_LINE_MAX_CHARS or len(text.split()) > CONTEXT_LINE_MAX_WORDS:
+ return ""
+ return text
+
+
+def _names(checks: list[str]) -> str:
+ names = [CHECK_NAMES.get(c, c) for c in checks]
+ return names[0] if len(names) == 1 else ", ".join(names[:-1]) + " e " + names[-1]
+
+
+def decide(result: dict, *, start_s: float, end_s: float, lo: float, hi: float, min_s: float, max_s: float,
+ conf: dict | None = None, score: float | None = None, min_score: float | None = None,
+ manual: bool = False, allow_fix: bool | None = None) -> Decision:
+ """Ação pelo resultado do juiz (`judge.clean_context`). `conf` = papel `judge` da Equipe de IA.
+ `allow_fix=False` força a 2ª rodada (sem novo ajuste)."""
+ conf = conf or {}
+ critical = [c for c in conf.get("critical", DEFAULT_CRITICAL) if c in CHECKS]
+ penalty = float(conf.get("penalty", DEFAULT_PENALTY))
+ can_fix = conf.get("allowFix", True) if allow_fix is None else (allow_fix and conf.get("allowFix", True))
+ checks = result.get("checks") or {}
+ failed = [c for c in CHECKS if not (checks.get(c) or {}).get("ok", True)]
+ fix = result.get("fix") or {}
+ line = usable_line(fix.get("context_line", "")) if conf.get("allowContextLine", True) else ""
+ solved = [c for c in failed if c in SOLVED_BY_LINE] if line else []
+ failed_critical = [c for c in failed if c in critical and c not in solved]
+ others = [c for c in failed if c not in critical and c not in solved]
+ score_after = None if score is None else round(max(0.0, score - penalty * len(others)), 2)
+ why_pt = (result.get("pt") or {}).get("reason") or result.get("reason") or ""
+ d = Decision("approve", failed, failed_critical, solved, None, line, score_after)
+
+ if manual:
+ d.action = "warn" if failed else "approve"
+ d.reason_pt = (f"Aviso do juiz: falhou em {_names(failed)}. {why_pt}".strip() if failed else "")
+ return d
+ if failed_critical:
+ new = None
+ if can_fix and (fix.get("start_s") is not None or fix.get("end_s") is not None):
+ ns = fix["start_s"] if fix.get("start_s") is not None else start_s
+ ne = fix["end_s"] if fix.get("end_s") is not None else end_s
+ # Recuar o início (faltou o começo) mantém o início; estender o fim (faltou o desfecho) mantém o fim.
+ keep = "start" if "setup" in failed_critical or ns < start_s - MIN_SHIFT_S else "end"
+ ns, ne = fit_window(ns, ne, lo, hi, min_s, max_s, keep=keep)
+ if ne - ns >= min(min_s, 10.0) and (abs(ns - start_s) >= MIN_SHIFT_S or abs(ne - end_s) >= MIN_SHIFT_S):
+ new = (ns, ne)
+ if new:
+ d.action, d.window = "adjust", new
+ d.reason_pt = (f"Juiz ajustou o trecho para {new[0]:.0f}–{new[1]:.0f}s: faltava {_names(failed_critical)}. "
+ f"{why_pt}").strip()
+ else:
+ d.action = "discard"
+ d.reason_pt = f"Descartado pelo juiz: sem {_names(failed_critical)}. {why_pt}".strip()
+ return d
+ if score_after is not None and min_score is not None and others and score_after < min_score:
+ d.action = "discard"
+ d.reason_pt = (f"Descartado pelo juiz: a nota caiu para {score_after:.1f} (falhou em {_names(others)}). "
+ f"{why_pt}").strip()
+ return d
+ d.reason_pt = (f"Juiz aprovou{' com frase de contexto' if line and solved else ''}"
+ + (f" (falhou em {_names(others)}, nota {score_after:.1f})" if others and score_after is not None else "")
+ + (f". {why_pt}" if why_pt else "."))
+ return d
+
+
+def view(result: dict, decision: Decision, model: str) -> dict:
+ """O que vai em `judge_json.context` (o painel mostra em português)."""
+ return {"model": model, "viewerSummary": result.get("viewer_summary", ""), "checks": result.get("checks", {}),
+ "fix": result.get("fix", {}), "confidence": result.get("confidence"), "reason": result.get("reason", ""),
+ "pt": result.get("pt") or {}, "decision": decision.action, "failed": decision.failed,
+ "failedCritical": decision.failed_critical, "solvedByLine": decision.solved_by_line,
+ "contextLine": decision.context_line if decision.action in ("approve", "adjust", "warn") else "",
+ "scoreAfter": decision.score_after, "reasonPt": decision.reason_pt,
+ **({"window": [round(decision.window[0], 2), round(decision.window[1], 2)]} if decision.window else {})}
diff --git a/clipper/app/db.py b/clipper/app/db.py
index b6d74ba..2b66b41 100644
--- a/clipper/app/db.py
+++ b/clipper/app/db.py
@@ -250,6 +250,46 @@ SCHEMA = [
ALTER TABLE sessions ADD COLUMN game_status TEXT NOT NULL DEFAULT '';
ALTER TABLE sessions ADD COLUMN game_detect_json TEXT;
""",
+ # v17: Equipe de IA (doc/clipador/EQUIPE-IA.md).
+ # - `ai_calls`: cada chamada de IA (papel, IA, tamanho do prompt e das imagens, tokens quando a CLI informa, tempo)
+ # para comparar custo por hora (F0). Sem FK para a sessão: a medição fica depois de apagar a sessão.
+ # - `scene_notes`: frase curta do que está na tela num instante (escrita pela varredura/analista ao ver os quadros);
+ # vira o campo `v` da linha do tempo JSON.
+ # - `clips.owner_label`/`owner_note`: avaliação do dono (bom / ruim / sem contexto) para o conjunto de avaliação.
+ """
+ CREATE TABLE IF NOT EXISTS ai_calls (
+ id INTEGER PRIMARY KEY AUTOINCREMENT,
+ at TEXT NOT NULL,
+ role TEXT NOT NULL,
+ purpose TEXT NOT NULL,
+ provider TEXT NOT NULL,
+ model TEXT NOT NULL,
+ ok INTEGER NOT NULL,
+ error TEXT,
+ ms INTEGER,
+ system_chars INTEGER,
+ prompt_chars INTEGER,
+ images INTEGER,
+ image_bytes INTEGER,
+ tokens_in INTEGER,
+ tokens_out INTEGER,
+ tokens_cached INTEGER,
+ session_id INTEGER,
+ clip_id INTEGER,
+ mode TEXT
+ );
+ CREATE INDEX IF NOT EXISTS ai_calls_at ON ai_calls (at);
+ CREATE TABLE IF NOT EXISTS scene_notes (
+ session_id INTEGER NOT NULL REFERENCES sessions(id) ON DELETE CASCADE,
+ t REAL NOT NULL,
+ source TEXT NOT NULL,
+ text TEXT NOT NULL,
+ created_at TEXT NOT NULL,
+ PRIMARY KEY (session_id, t, source)
+ );
+ ALTER TABLE clips ADD COLUMN owner_label TEXT CHECK (owner_label IN ('good', 'bad', 'no_context'));
+ ALTER TABLE clips ADD COLUMN owner_note TEXT;
+ """,
]
diff --git a/clipper/app/editor_api.py b/clipper/app/editor_api.py
index fcaae0a..42fcb4b 100644
--- a/clipper/app/editor_api.py
+++ b/clipper/app/editor_api.py
@@ -172,7 +172,18 @@ def auto_for(engine, clip: dict, session: dict) -> dict:
lo, hi = editor.default_window(clip, session["duration_s"])
words = engine.words_between(clip["session_id"], lo, hi) # já com quem fala cada palavra (FALANTES.md)
loudness = engine.load_timeline(clip["session_id"], max(0.0, lo - 5))["loudness"]
- return editor.auto_project(clip, judge.get("analysis"), words, loudness, session["duration_s"],
+ analysis = judge.get("analysis")
+ context = judge.get("context") if isinstance(judge.get("context"), dict) else {}
+ if context.get("decision") in ("approve", "adjust", "warn") and (context.get("contextLine") or context.get("window")):
+ analysis = dict(analysis or {})
+ # Juiz de contexto (EQUIPE-IA.md): a frase de contexto vira o texto do começo do corte (no lugar do gancho)…
+ if context.get("contextLine"):
+ analysis["hook"] = context["contextLine"]
+ # …e, se ele ajustou o trecho, o início/fim do analista não desfaz o ajuste (ex.: recuou para pegar o começo).
+ if context.get("window"):
+ analysis.pop("action_start_s", None)
+ analysis.pop("reaction_end_s", None)
+ return editor.auto_project(clip, analysis, words, loudness, session["duration_s"],
engine.intel.settings_for(session), model=judge.get("model") or "", generated_at=now())
diff --git a/clipper/app/intel.py b/clipper/app/intel.py
index d31e5d1..4c944a8 100644
--- a/clipper/app/intel.py
+++ b/clipper/app/intel.py
@@ -18,7 +18,7 @@ import time
from pathlib import Path
from typing import TYPE_CHECKING
-from . import clip_delete, layout
+from . import clip_delete, layout, media, timeline
from .db import loads, now
from .emotes import EmoteCatalog, extract, learn_delta, message_bonus
from .face import FaceError, FaceUnavailable
@@ -27,7 +27,8 @@ from .game_detect import (
slug_all,
)
from .hashtags import fold, to_tag
-from .judge import JudgeError, build_scan_prompt, game_context, lang_key, output_language_note
+from .judge import (JudgeError, build_scan_prompt, build_scan_timeline_prompt, game_context, lang_key, lean_profile,
+ output_language_note)
from .scoring import fit_window
from .sources import parse_source
@@ -37,7 +38,10 @@ if TYPE_CHECKING: # pragma: no cover
log = logging.getLogger("cenaforge_clipper.intel")
# faceTrack: rastreio do rosto do streamer (face.py) — reforça/cria cortes e vai em texto para o analista.
-OPTION_DEFAULTS = {"scanEnabled": True, "scanIntervalS": 180, "vision": True, "camDetect": True, "faceTrack": True}
+# timelineJson: a IA lê o vídeo como linha do tempo JSON curta (timeline.py); desligado = transcrição + chat + frames
+# soltos como antes (para comparar custo e qualidade — doc/clipador/EQUIPE-IA.md).
+OPTION_DEFAULTS = {"scanEnabled": True, "scanIntervalS": 180, "vision": True, "camDetect": True, "faceTrack": True,
+ "timelineJson": True}
CAM_RETRY_S = 300 # câmera não achada enquanto grava: nova tentativa depois de mais 5 min de gravação
CAM_MAX_ATTEMPTS = 6 # falha sem rosto decidido (poucos quadros legíveis): no máximo isto de tentativas
GAME_CHECK_S = 180 # rechecar a categoria da live (e cruzar com tela, chat e fala) a cada 3 min: o streamer troca de jogo
@@ -47,6 +51,8 @@ CHAT_WINDOW_S = 360 # chat e fala dos últimos 6 min entram na detecção do jo
SPEECH_SEGMENTS = 12 # = 6 min de blocos de 30 s
SCAN_FRAME_EVERY_S = 30
SCAN_MAX_FRAMES = 7
+SCAN_MOSAIC_TILES = 8 # mosaico 4×2: 1 imagem por janela de varredura
+SCAN_TIMELINE_CHARS = 9000
MEMORY_KEEP = 6
SCAN_MAX_MOMENTS = 2
SCAN_MIN_PROPOSAL = 4 # proposta da varredura abaixo disso nem vai aos juízes (economia)
@@ -628,10 +634,13 @@ class Intel:
"""'en' = fonte em inglês (juízes em inglês, tradução para o painel); 'pt' = o resto."""
return lang_key(session.get("language") or self.e.settings.language)
- def context(self, session: dict) -> str:
+ def context(self, session: dict, lean: bool = False) -> str:
+ """Contexto do jogo para os prompts. `lean` (linha do tempo JSON): perfil enxuto (judge.lean_profile)."""
memory = loads(session.get("memory_json"), [])
confirmed = session.get("game_source") == "user" and bool(session.get("game"))
profile = self.profile(session.get("game", "")) or (None if confirmed else self.profile(session.get("screen_game", "")))
+ if lean:
+ profile = lean_profile(profile)
text = game_context(session.get("game", ""), session.get("screen_game", ""), profile, session.get("title", ""),
" | ".join(m["summary"] for m in memory[-3:] if m.get("summary")), confirmed=confirmed,
lang=self.lang(session))
@@ -640,7 +649,7 @@ class Intel:
return f"{text}\n{note}" if note else text
# ---------------------------------------------------------------- frames
- def frames(self, session: dict, times: list[float], tag: str) -> list[tuple[float, Path]]:
+ def frames(self, session: dict, times: list[float], tag: str, width: int = 768) -> list[tuple[float, Path]]:
if not self.opts["vision"]:
return []
segments = [(self.e.repo_path(s["file"]), s["start_s"], s["end_s"])
@@ -649,11 +658,31 @@ class Intel:
frames = []
for t in times:
try:
- frames.append((t, self.e.grab_frame(segments, t, out_dir / f"{tag}-{int(t)}.jpg")))
+ frames.append((t, self.e.grab_frame(segments, t, out_dir / f"{tag}-{int(t)}.jpg", width)))
except Exception as exc: # noqa: BLE001 - sem frame a IA decide só pelo texto
log.info("frame %.0fs indisponível: %s", t, exc)
return frames
+ def visual(self, session: dict, times: list[float], tag: str, mode: str) -> tuple[list[Path], list[float], bool]:
+ """Imagens para a IA: (arquivos, instante de cada quadro, é mosaico?). `mode`: "mosaic" = os quadros numa
+ grade 4×2 numa imagem só (384×216 cada); "frames" = soltos em 768 px (o antigo); "none" = nenhuma.
+ Mosaico que falha cai para os quadros soltos (a IA não fica sem ver a tela)."""
+ if mode == "none" or not self.opts["vision"] or not times:
+ return [], [], False
+ if mode != "mosaic":
+ frames = self.frames(session, times, tag)
+ return [p for _, p in frames], [t for t, _ in frames], False
+ frames = self.frames(session, times, f"{tag}m", width=media.MOSAIC_TILE_W)
+ if not frames:
+ return [], [], False
+ out = self.e.repo_path(session["dir"]) / "frames" / f"{tag}-mosaic-{int(frames[0][0])}.jpg"
+ try:
+ media.mosaic(self.e.settings.ffmpeg or "ffmpeg", [p for _, p in frames], out)
+ except Exception as exc: # noqa: BLE001 - sem mosaico, vão os quadros (pequenos) soltos
+ log.info("mosaico %s indisponível: %s", tag, exc)
+ return [p for _, p in frames], [t for t, _ in frames], False
+ return [out], [t for t, _ in frames], True
+
# ---------------------------------------------------------------- webcam
def maybe_detect_cam(self, session: dict) -> None:
"""Acha a câmera no início da sessão. A detecção local (YuNet) não precisa de IA, visão nem juiz ligados."""
@@ -787,19 +816,39 @@ class Intel:
cfg = self.settings_for(session)
dur = cfg["duration"]
back_lo = max(0.0, lo - dur["backtrackS"])
- step = max(SCAN_FRAME_EVERY_S, (hi - lo) / SCAN_MAX_FRAMES)
- times = [lo + step / 2 + i * step for i in range(int((hi - lo) // step) or 1)][:SCAN_MAX_FRAMES]
- frames = self.frames(session, times, "scan")
+ use_timeline = bool(self.opts.get("timelineJson", True))
+ mode = self.e.judge.roles["scan"].get("images", "mosaic") if use_timeline else "frames"
+ if mode == "mosaic": # 8 quadros por igual na janela, numa imagem só
+ step = (hi - lo) / SCAN_MOSAIC_TILES
+ times = [lo + step / 2 + i * step for i in range(SCAN_MOSAIC_TILES)]
+ else:
+ step = max(SCAN_FRAME_EVERY_S, (hi - lo) / SCAN_MAX_FRAMES)
+ times = [lo + step / 2 + i * step for i in range(int((hi - lo) // step) or 1)][:SCAN_MAX_FRAMES]
+ images, tiles, mosaic = self.visual(session, times, "scan", mode)
existing = [(c["start_s"], c["end_s"], c["title"]) for c in self.e.db.all(
"SELECT start_s, end_s, title FROM clips WHERE session_id = ? AND end_s > ? AND start_s < ?", session["id"], back_lo, hi)]
existing += clip_delete.mark_spans(self.e.db, session["id"], back_lo, hi) # apagados não voltam pela varredura
- prompt = build_scan_prompt(self.e.streamer_name(session), session["platform"], lo, hi, back_lo, tl["words"],
- tl["chat"], self.context(session), frames, existing, dur["minS"], dur["maxS"],
- lang=self.lang(session))
+ lang = self.lang(session)
+ if use_timeline:
+ # A "volta" (antes da janela) vai resumida: já foi vista na janela anterior.
+ ev = timeline.collect(self.e, session, tl, back_lo, hi)
+ text = timeline.build(ev, back_lo, hi, {"win": [int(lo), int(hi)], "back": int(back_lo), "src": lang},
+ budget_chars=SCAN_TIMELINE_CHARS, coarse_until=lo)
+ prompt = build_scan_timeline_prompt(self.e.streamer_name(session), session["platform"], lo, hi, back_lo,
+ self.context(session, lean=True), text, tiles, mosaic, existing, dur["minS"],
+ dur["maxS"], lang=lang)
+ else:
+ prompt = build_scan_prompt(self.e.streamer_name(session), session["platform"], lo, hi, back_lo, tl["words"],
+ tl["chat"], self.context(session), list(zip(tiles, images)), existing,
+ dur["minS"], dur["maxS"], lang=lang)
created = 0
try:
- data = self.e.judge.scan(prompt, [p for _, p in frames], lang=self.lang(session))
+ run_mode = ("timeline" if use_timeline else "legacy") + f"+{'mosaic' if mosaic else mode}"
+ with self.e.judge.scope(session_id=session["id"], mode=run_mode):
+ data = self.e.judge.scan(prompt, images, lang=lang)
self.last_scan_error = None
+ # O que a varredura viu em cada quadro vira o `v` da linha do tempo (analista, editor e juiz reaproveitam).
+ timeline.save_scene_lines(self.e, session["id"], "scan", data.get("lines"), tiles)
except (JudgeError, json.JSONDecodeError) as exc:
# Avança mesmo assim: repetir a mesma janela com a CLI quebrada só gastaria cota.
self.last_scan_error = str(exc)[:300]
diff --git a/clipper/app/judge.py b/clipper/app/judge.py
index a4c82af..6929266 100644
--- a/clipper/app/judge.py
+++ b/clipper/app/judge.py
@@ -30,11 +30,13 @@ import sys
import tempfile
import threading
import time
+from contextlib import contextmanager
from dataclasses import dataclass, field
from datetime import datetime, timezone
from pathlib import Path
from . import layout
+from . import roles as roles_module
from .ai_settings import AiConfig
from .scoring import ChatMessage, Word, fit_window
@@ -111,6 +113,14 @@ CHAT_GLOSSARY = """Gírias comuns do chat (interprete pelo contexto):
"clipa/clip it" → pedido de corte; "hack/hackudo" → suspeita de trapaça; "gg" → fim de partida.
- Emotes próprios do canal (prefixo do streamer, ex.: skpPog) carregam a mesma reação do emote original."""
+# Frase curta do que está na tela em cada quadro/ladrilho do mosaico (`n` = nº do quadro, 1 = primeiro). Vira o
+# campo `v` da linha do tempo (app/timeline.py), guardado em `scene_notes` e reaproveitado por editor e juiz.
+SCENE_LINES = {
+ "type": "array",
+ "items": {"type": "object", "properties": {"n": {"type": "integer"}, "v": {"type": "string"}},
+ "required": ["n", "v"], "additionalProperties": False},
+}
+
SITUATIONS = ("lag_ou_bug", "jogada", "falha_engracada", "morte", "susto", "treta", "conversa_engracada",
"historia", "informacao_do_jogo", "reacao", "outro")
@@ -126,11 +136,14 @@ ANALYSIS_SCHEMA = {
"action_start_s": {"type": "number"},
"reaction_end_s": {"type": "number"},
"hook": {"type": "string"},
+ "lines": SCENE_LINES,
},
"required": ["situation", "what_happened", "screen", "speech", "chat_meaning", "confidence",
- "action_start_s", "reaction_end_s", "hook"],
+ "action_start_s", "reaction_end_s", "hook", "lines"],
"additionalProperties": False,
}
+# Campos que a resposta pode não trazer (modelo antigo/cache): a análise segue sem eles.
+ANALYSIS_OPTIONAL = ("lines",)
ANALYST_SYSTEM = """Você é o ANALISTA de uma equipe de cortes de live. Não escreve título: descreve com fidelidade
O QUE ACONTECEU no trecho, para o editor decidir. Recebe contexto do jogo, transcrição com tempos, FRAMES da tela
@@ -152,6 +165,8 @@ Campos:
- action_start_s: instante (s da gravação) em que começa a AÇÃO que gerou a reação (pode ser antes da fala).
- reaction_end_s: instante em que a reação/pagamento termina.
- hook: o que prenderia alguém nos 2 primeiros segundos do corte.
+- lines: para cada frame/quadro do mosaico anexado (n = o número dele), v = o que está na tela em até 12 palavras,
+ factual (ação, lugar, texto grande do jogo). Sem imagem anexada: lista vazia.
Não use ferramentas além do que foi entregue. Responda só com o JSON pedido."""
VERDICT_SCHEMA = {
@@ -186,8 +201,9 @@ SCAN_SCHEMA = {
"has_webcam": {"type": "boolean"},
"summary": {"type": "string"},
"moments": {"type": "array", "items": _MOMENT},
+ "lines": SCENE_LINES,
},
- "required": ["screen_game", "screen_game_confidence", "screen_evidence", "has_webcam", "summary", "moments"],
+ "required": ["screen_game", "screen_game_confidence", "screen_evidence", "has_webcam", "summary", "moments", "lines"],
"additionalProperties": False,
}
_MISSION = {
@@ -276,6 +292,8 @@ moments=[] (é o normal na maior parte do tempo — não force). Não repita um
has_webcam: há câmera do streamer no quadro?
- summary: 1 frase do que está acontecendo na janela (vira memória para as próximas janelas).
- title/caption/reason como um editor faria (título ≤ 70 caracteres, verdadeiro; hashtags só do que há aqui).
+- lines: para cada frame/quadro do mosaico (n = o número dele), v = o que está na tela em até 12 palavras, factual.
+ Sem imagem anexada: lista vazia.
Não use ferramentas além do que foi entregue. Responda só com o JSON pedido."""
# Perfil do jogo em INGLÊS (doc/clipador/JOGOS.md): é o que vai nos prompts; a tradução para português é só para o
@@ -477,6 +495,8 @@ Fields (in English):
- action_start_s: second of the recording where the ACTION that caused the reaction starts (may be before the speech).
- reaction_end_s: second where the reaction/payoff ends.
- hook: what would hook someone in the first 2 seconds of the clip (English, it goes on screen).
+- lines: for each attached frame/mosaic tile (n = its number), v = what is on screen in up to 12 words, factual
+ (action, place, big on-screen game text), in English. No image attached: empty list.
- pt: what_happened, screen, speech, chat_meaning and hook translated. """ + PT_NOTE + """
Do not use tools beyond what was given. Answer only with the requested JSON."""
@@ -526,6 +546,8 @@ moments=[] (that's normal most of the time — don't force it). Don't repeat a c
has_webcam: is there a streamer camera in the frame?
- summary: 1 sentence of what's going on in the window (becomes memory for the next windows).
- title/caption/reason in English like an editor would write (title ≤ 70 characters, true).
+- lines: for each frame/mosaic tile (n = its number), v = what is on screen in up to 12 words, factual, in English.
+ No image attached: empty list.
- summary_pt and each moment's pt (title, reason): translated. """ + PT_NOTE + """
Do not use tools beyond what was given. Answer only with the requested JSON."""
@@ -561,6 +583,213 @@ names; translate the slang's meaning, e.g. "he's cooked" -> "ele tá ferrado").
as is. Answer only with the requested JSON."""
+# ---------------------------------------------------------------- JUIZ de contexto (doc/clipador/EQUIPE-IA.md)
+# Pedido do dono (18/11/2026): "não trazer corte sem sentido, principalmente em inglês". O juiz vê SÓ o que vai no
+# corte final (linha do tempo do trecho + 20 s antes marcados out=1), escreve primeiro o que um espectador frio
+# entenderia e depois responde sim/não. Quem decide pelas respostas é o código (context_judge.decide), não uma nota.
+CONTEXT_CHECKS = roles_module.CHECKS
+_CHECK = {"type": "object",
+ "properties": {"ok": {"type": "boolean"}, "t": {"type": ["number", "null"]}, "why": {"type": "string"}},
+ "required": ["ok", "t", "why"], "additionalProperties": False}
+CONTEXT_SCHEMA = {
+ "type": "object",
+ "properties": {
+ "viewer_summary": {"type": "string"},
+ "checks": {"type": "object", "properties": {c: _CHECK for c in CONTEXT_CHECKS}, "required": list(CONTEXT_CHECKS),
+ "additionalProperties": False},
+ "fix": {"type": "object",
+ "properties": {"start_s": {"type": ["number", "null"]}, "end_s": {"type": ["number", "null"]},
+ "context_line": {"type": "string"}},
+ "required": ["start_s", "end_s", "context_line"], "additionalProperties": False},
+ "confidence": {"type": "number"},
+ "reason": {"type": "string"},
+ },
+ "required": ["viewer_summary", "checks", "fix", "confidence", "reason"],
+ "additionalProperties": False,
+}
+CONTEXT_SCHEMA_EN = _with(CONTEXT_SCHEMA, pt={
+ "type": "object",
+ "properties": {"viewer_summary": {"type": "string"}, "reason": {"type": "string"}, "context_line": {"type": "string"},
+ "checks": _pt_block(*CONTEXT_CHECKS)},
+ "required": ["viewer_summary", "reason", "context_line", "checks"], "additionalProperties": False})
+
+CONTEXT_SYSTEM_EN = """You are the CONTEXT JUDGE of a live-stream clipping team. The editor already picked the segment and
+wrote the title. You check ONE thing: will someone who has NEVER seen this stream understand the clip and feel it makes
+sense on its own? You only get what the viewer will see: the clip's timeline (entries with out=1 are just BEFORE or AFTER
+the clip — the viewer does NOT see them; use them only to notice a missing setup or payoff), the title, caption and opening on-screen text, the
+intended story (from the analyst) and one line about the game.
+
+First write viewer_summary: what a cold viewer understands from the clip alone (1–2 sentences) — BEFORE the checks.
+Then answer every check with ok (true/false), t (second of the recording that is the evidence, or null) and why
+(up to 15 words):
+- setup: the clip includes the start of the situation the moment depends on. Fails if the key setup is only in the
+ out=1 entries before the clip (or earlier).
+- payoff: the clip includes the outcome/punchline/result (of the fight, escape, mission, joke). Fails if it ends before
+ (e.g. the result is only in the out=1 entries after the clip).
+- who_what: it is clear who is involved and what is happening.
+- standalone: it works without knowing earlier events of the stream, the channel's lore or inside jokes.
+- intelligible: the key line is in the transcript; fails if the important line is a teammate's/other player's that is
+ missing, or the streamer only reacts to something we never hear.
+- faithful: title/caption only claim what the clip shows ("caught a hacker" when he only accuses him = false).
+- strong_open: the first ~3 s already hook (not calm chatter).
+Red flags in English streams: references to things outside the clip ("that guy", "again", "like I said", "remember
+when", names never introduced), callbacks to donations/raids/subs, chat or channel inside jokes. Irony/slang ("he's
+cooked", "Clueless", "W") only counts if the screen confirms it.
+fix — only when a check fails and the timeline shows the answer: start_s (earlier, to include the setup) and/or end_s
+(later, to include the payoff; or earlier, to drop a tail that depends on other context), seconds of the recording,
+within the limits given; null when not needed. context_line: on-screen text for the first seconds (up to 8 words, in
+English) that gives a cold viewer the missing context (e.g. "Tfue tries to talk his way out of a robbery"); "" when not
+needed. Never invent facts.
+confidence: 0–1. reason: one sentence.
+pt: viewer_summary, reason, context_line and every check's why, translated. """ + PT_NOTE + """
+Do not use tools. Answer only with the requested JSON."""
+
+CONTEXT_SYSTEM = """Você é o JUIZ DE CONTEXTO de uma equipe de cortes de live. O editor já escolheu o trecho e escreveu o
+título. Você confere UMA coisa: alguém que NUNCA viu esta live entende o corte e sente que ele faz sentido sozinho?
+Você recebe só o que o espectador vai ver: a linha do tempo do corte (entradas com out=1 vêm logo ANTES ou DEPOIS do
+corte — o espectador NÃO as vê; use só para notar o começo ou o desfecho que faltam), título, legenda e texto de abertura na tela, a história
+pretendida (do analista) e uma linha sobre o jogo.
+
+Escreva primeiro viewer_summary: o que um espectador frio entende só com o corte (1–2 frases) — ANTES das checagens.
+Depois responda cada checagem com ok (true/false), t (segundo da gravação que é a evidência, ou null) e why (até 15
+palavras):
+- setup: o corte inclui o começo da situação de que o momento depende. Falha se o começo importante só está nas
+ entradas out=1 (ou antes).
+- payoff: o corte inclui o desfecho/resultado/piada (da treta, da fuga, da missão). Falha se termina antes (ex.: o
+ resultado só aparece nas entradas out=1 depois do corte).
+- who_what: dá para entender quem está envolvido e o que está acontecendo.
+- standalone: funciona sem saber o que aconteceu antes na live, a história do canal ou piadas internas.
+- intelligible: a fala principal está na transcrição; falha se ela é de um colega/outro jogador que não aparece, ou se
+ o streamer só reage a algo que não se ouve.
+- faithful: título/legenda só afirmam o que o corte mostra ("pegou um hacker" quando ele só acusa = falso).
+- strong_open: os ~3 primeiros segundos já prendem (não é conversa morna).
+Sinais de alerta: referência a algo fora do corte ("aquele cara", "de novo", "como eu falei", "lembra quando", nome
+nunca apresentado), menção a doação/raid/sub, piada interna do chat ou do canal. Ironia/gíria só vale se a tela
+confirma.
+fix — só quando uma checagem falha e a linha do tempo mostra a resposta: start_s (mais cedo, para incluir o começo) e/ou
+end_s (mais tarde, para incluir o desfecho; ou mais cedo, para tirar uma cauda que depende de outro contexto), em
+segundos da gravação, dentro dos limites informados; null quando não precisa. context_line: texto na tela para os
+primeiros segundos (até 8 palavras, no idioma do corte) que dá ao espectador frio o contexto que falta; "" se não
+precisa. Nunca invente fatos.
+confidence: 0–1. reason: uma frase.
+Não use ferramentas. Responda só com o JSON pedido."""
+
+
+def clean_context(data: dict) -> dict:
+ """Resposta do juiz normalizada: checagem ausente/inválida conta como "não respondida" (ok=True, sem motivo) —
+ o código não descarta por falta de resposta. Sem `checks` nem `viewer_summary` é erro de conteúdo."""
+ if not isinstance(data, dict) or not isinstance(data.get("checks"), dict) or "viewer_summary" not in data:
+ raise JudgeError("juiz sem viewer_summary/checks", unavailable=False)
+ checks = {}
+ for name in CONTEXT_CHECKS:
+ raw = data["checks"].get(name)
+ raw = raw if isinstance(raw, dict) else {}
+ t = raw.get("t")
+ checks[name] = {"ok": raw.get("ok") is not False,
+ "t": float(t) if isinstance(t, (int, float)) and not isinstance(t, bool) else None,
+ "why": str(raw.get("why") or "").strip()[:200]}
+ fix = data.get("fix") if isinstance(data.get("fix"), dict) else {}
+
+ def num(value):
+ return float(value) if isinstance(value, (int, float)) and not isinstance(value, bool) else None
+
+ pt = data.get("pt") if isinstance(data.get("pt"), dict) else {}
+ pt_checks = pt.get("checks") if isinstance(pt.get("checks"), dict) else {}
+ try:
+ confidence = max(0.0, min(1.0, float(data.get("confidence", 0.5))))
+ except (TypeError, ValueError):
+ confidence = 0.5
+ out_pt = {k: str(pt.get(k) or "").strip()[:600] for k in ("viewer_summary", "reason", "context_line") if pt.get(k)}
+ if pt_checks:
+ out_pt["checks"] = {c: str(pt_checks.get(c) or "").strip()[:200] for c in CONTEXT_CHECKS if pt_checks.get(c)}
+ return {
+ "viewer_summary": str(data.get("viewer_summary") or "").strip()[:600],
+ "checks": checks,
+ "fix": {"start_s": num(fix.get("start_s")), "end_s": num(fix.get("end_s")),
+ "context_line": " ".join(str(fix.get("context_line") or "").split())[:80]},
+ "confidence": confidence,
+ "reason": str(data.get("reason") or "").strip()[:300],
+ "pt": out_pt,
+ }
+
+
+# ---------------------------------------------------------------- prompts com a linha do tempo (v1)
+def images_block(tiles: list[float], mosaic: bool, lang: str = "pt") -> str:
+ """O que vai anexado. `tiles` = instante de cada quadro (no mosaico, da esquerda para a direita, de cima para
+ baixo). As frases `lines[].n` da resposta se referem a esses números."""
+ if not tiles:
+ return "Images: none." if lang == "en" else "Imagens: nenhuma."
+ numbered = ", ".join(f"#{i + 1}={t:.0f}s" for i, t in enumerate(tiles))
+ if mosaic:
+ return (f"Attached: ONE mosaic image with {len(tiles)} frames in a grid (left→right, top→bottom): {numbered}."
+ if lang == "en" else
+ f"Anexo: UMA imagem em mosaico com {len(tiles)} quadros em grade (esquerda→direita, cima→baixo): {numbered}.")
+ return (f"Attached frames, in order: {numbered}." if lang == "en" else f"Frames anexados, em ordem: {numbered}.")
+
+
+def timeline_section(timeline_text: str, lang: str, streamer: str) -> str:
+ """Legenda das chaves + (se há fala de outra pessoa) a nota de quem fala + a linha do tempo."""
+ from .timeline import legend
+
+ me = (streamer or "streamer").replace("[", "(").replace("]", ")")
+ note = ""
+ if "[other" in timeline_text: # fala de outra pessoa no trecho (FALANTES.md): sem marca = o streamer
+ note = "\n" + SPEAKER_NOTE["en" if lang == "en" else "pt"].format(s=me).replace(f"[{me}]", "no tag")
+ return f"{legend(lang)}{note}\n{timeline_text}"
+
+
+def build_timeline_prompt(streamer: str, platform: str, start_s: float, end_s: float, peak_s: float,
+ heuristic: dict, *, context: str, timeline_text: str, tiles: list[float], mosaic: bool,
+ lo: float, hi: float, min_s: float, max_s: float, lang: str = "pt",
+ analysis: dict | None = None) -> str:
+ """Prompt do ANALISTA e do EDITOR no formato novo: cabeçalho + imagens + linha do tempo JSON (no lugar da
+ transcrição, do chat e da linha do rosto, que já estão dentro dela)."""
+ L, to = LABELS[lang], ("to" if lang == "en" else "a")
+ signals = {k: v for k, v in heuristic.items() if k not in ("topMessages", "face", "emotes")}
+ text = (f"{L['channel']}: {streamer} ({platform})\n{context}\n\n"
+ f"{L['window']}: {lo:.0f}s {to} {hi:.0f}s. {L['candidate']}: {start_s:.0f}s {to} {end_s:.0f}s; "
+ f"{L['peak']} {peak_s:.0f}s. {L['duration']}: {min_s:.0f} {to} {max_s:.0f} s.\n"
+ f"{L['signals']}: {json.dumps(signals, ensure_ascii=False, separators=(',', ':'))}\n"
+ f"{images_block(tiles, mosaic, lang)}\n\n{timeline_section(timeline_text, lang, streamer)}")
+ if analysis:
+ text += "\n\n" + analysis_block(analysis, lang)
+ return text
+
+
+def build_scan_timeline_prompt(streamer: str, platform: str, lo: float, hi: float, back_lo: float, context: str,
+ timeline_text: str, tiles: list[float], mosaic: bool,
+ existing: list[tuple[float, float, str]], min_s: float, max_s: float,
+ lang: str = "pt") -> str:
+ L, to = LABELS[lang], ("to" if lang == "en" else "a")
+ done = "; ".join(f"{a:.0f}–{b:.0f}s ({t[:40]})" for a, b, t in existing) or L["none"]
+ return (f"{L['channel']}: {streamer} ({platform})\n{context}\n\n"
+ f"{L['new_window']}: {lo:.0f}s {to} {hi:.0f}s ({L['back_to'].format(s=f'{back_lo:.0f}')}).\n"
+ f"{L['duration']}: {min_s:.0f} {to} {max_s:.0f} s. {L['done']}: {done}\n"
+ f"{images_block(tiles, mosaic, lang)}\n\n{timeline_section(timeline_text, lang, streamer)}")
+
+
+def build_context_prompt(*, streamer: str, game: str, game_line: str, start_s: float, end_s: float, title: str,
+ caption: str, opening: str, story: str, timeline_text: str, lo: float, hi: float,
+ min_s: float, max_s: float, lang: str = "pt") -> str:
+ """Prompt do JUIZ: só o que o espectador verá (e 20 s antes / 15 s depois, marcados out=1) + limites do ajuste."""
+ if lang == "en":
+ lines = [f"Game: {game or 'unknown'}" + (f" — {game_line}" if game_line else ""),
+ f"Streamer: {streamer}",
+ f"Clip the viewer will see: {start_s:.0f}s to {end_s:.0f}s ({end_s - start_s:.0f} s).",
+ f"Title: {title}", f"Caption: {caption or '(none)'}", f"Opening on-screen text: {opening or '(none)'}",
+ f"Intended story (analyst): {story or '(not available)'}",
+ f"Limits for a fix: start back to {lo:.0f}s at most, end up to {hi:.0f}s; duration {min_s:.0f} to {max_s:.0f} s."]
+ else:
+ lines = [f"Jogo: {game or 'desconhecido'}" + (f" — {game_line}" if game_line else ""),
+ f"Streamer: {streamer}",
+ f"Corte que o espectador verá: {start_s:.0f}s a {end_s:.0f}s ({end_s - start_s:.0f} s).",
+ f"Título: {title}", f"Legenda: {caption or '(nenhuma)'}", f"Texto de abertura na tela: {opening or '(nenhum)'}",
+ f"História pretendida (analista): {story or '(não disponível)'}",
+ f"Limites para o ajuste: início até {lo:.0f}s no máximo para trás, fim até {hi:.0f}s; duração de "
+ f"{min_s:.0f} a {max_s:.0f} s."]
+ return "\n".join(lines) + f"\n\n{timeline_section(timeline_text, lang, streamer)}"
+
+
def lang_key(language: str | None) -> str:
"""'en' para fonte em inglês (juízes em inglês); 'pt' para o resto (prompts em português + nota de saída)."""
return "en" if (language or "").strip().lower().startswith("en") else "pt"
@@ -637,6 +866,23 @@ def mission_lines(profile: dict, lang: str = "pt") -> list[str]:
return lines
+LEAN_LIMITS = {"clip_worthy": 6, "avoid": 4, "mechanics": 6, "jargon": 10, "news": 2}
+LEAN_ITEM_CHARS = 100
+
+
+def lean_profile(profile: dict | None) -> dict | None:
+ """Perfil enxuto para os prompts da linha do tempo (o perfil completo ia inteiro em TODA chamada: ~1.000
+ tokens no ROB RUN). Resumo em 2 frases, listas menores e itens curtos; missões seguem com o teto de sempre."""
+ if not profile:
+ return profile
+ out = dict(profile)
+ summary = str(profile.get("summary") or "")
+ out["summary"] = ". ".join(summary.split(". ")[:2]).strip()
+ for key, limit in LEAN_LIMITS.items():
+ out[key] = [str(item)[:LEAN_ITEM_CHARS] for item in (profile.get(key) or [])[:limit]]
+ return out
+
+
def game_context(game: str, screen_game: str, profile: dict | None, live_title: str, history: str = "",
confirmed: bool = False, lang: str = "pt") -> str:
if lang == "en":
@@ -878,14 +1124,70 @@ def codex_models(cache: Path | None = None) -> list[dict]:
return out or [{"id": DEFAULT_MODELS["codex"], "label": DEFAULT_MODELS["codex"]}]
+# ---------------------------------------------------------------- uso de tokens (F0: medir antes de otimizar)
+def _int(value) -> int | None:
+ try:
+ return int(value) if value is not None else None
+ except (TypeError, ValueError):
+ return None
+
+
+def codex_usage(stdout: str) -> dict | None:
+ """Uso do `codex exec --json` (eventos JSONL): o último evento com `usage` (`turn.completed`). None = não veio."""
+ found = None
+ for line in (stdout or "").splitlines():
+ line = line.strip()
+ if not line.startswith("{") or "input_tokens" not in line:
+ continue
+ try:
+ event = json.loads(line)
+ except json.JSONDecodeError:
+ continue
+ usage = event.get("usage") if isinstance(event, dict) else None
+ if not isinstance(usage, dict): # formato antigo: {"msg": {"type": "token_count", "info": {...}}}
+ info = ((event.get("msg") or {}).get("info") or {}) if isinstance(event, dict) else {}
+ usage = info.get("total_token_usage") or info.get("last_token_usage")
+ if isinstance(usage, dict) and "input_tokens" in usage:
+ found = {"in": _int(usage.get("input_tokens")), "out": _int(usage.get("output_tokens")),
+ "cached": _int(usage.get("cached_input_tokens"))}
+ return found
+
+
+def claude_usage(envelope: dict) -> dict | None:
+ """Uso do envelope `claude -p --output-format json`: entrada = nova + criação de cache + leitura de cache."""
+ usage = envelope.get("usage") if isinstance(envelope, dict) else None
+ if not isinstance(usage, dict):
+ return None
+ parts = [_int(usage.get(k)) or 0 for k in ("input_tokens", "cache_creation_input_tokens", "cache_read_input_tokens")]
+ return {"in": sum(parts), "out": _int(usage.get("output_tokens")), "cached": _int(usage.get("cache_read_input_tokens"))}
+
+
+def gemini_usage(envelope: dict) -> dict | None:
+ """Uso do `gemini -o json` (`stats.models..tokens`), somado entre os modelos que a CLI usou."""
+ models = ((envelope or {}).get("stats") or {}).get("models") if isinstance(envelope, dict) else None
+ if not isinstance(models, dict) or not models:
+ return None
+ total = {"in": 0, "out": 0, "cached": 0}
+ for data in models.values():
+ tokens = (data or {}).get("tokens") or {}
+ total["in"] += _int(tokens.get("prompt")) or 0
+ total["out"] += (_int(tokens.get("candidates")) or 0) + (_int(tokens.get("thoughts")) or 0)
+ total["cached"] += _int(tokens.get("cached")) or 0
+ return total
+
+
# ---------------------------------------------------------------- IA
class Judge:
+ """As IAs da equipe (doc/clipador/EQUIPE-IA.md). Cada papel (varredura, analista, editor, juiz) tem provedor e
+ modelo próprios (`roles`); `provider`/`model` continuam existindo como a IA do EDITOR — a "principal", que também
+ faz os serviços gerais (pesquisa de jogo, tradução, câmera). `provider == "off"` desliga a equipe inteira."""
+
def __init__(self, provider: str, model: str, workdir: Path, analyst_model: str = "",
- ai: AiConfig | None = None, clock=time.time):
- self.provider = provider if provider in PROVIDERS else "codex"
- self.model = model or DEFAULT_MODELS.get(self.provider, "")
- # Modelo do ANALISTA (1º juiz, vê os frames). Vazio = o mesmo do editor.
- self.analyst_model = analyst_model
+ ai: AiConfig | None = None, clock=time.time, roles: dict | None = None):
+ legacy = provider if provider in PROVIDERS else "codex"
+ self._master = "off" if legacy == "off" else "on"
+ base = roles_module.default_roles(legacy if legacy != "off" else "codex", model, analyst_model)
+ self.roles = roles_module.normalize_roles(roles, base)
self.workdir = workdir
# Configurações → IA do painel (data/ai): login/chave por provedor e ordem da reserva.
self.ai = ai or AiConfig()
@@ -895,14 +1197,85 @@ class Judge:
self._pause_lock = threading.Lock()
# Quem respondeu a última chamada DESTA thread ("provedor:modelo"): o juiz roda em várias threads.
self._local = threading.local()
+ # Medição (F0): o motor liga isto para gravar cada chamada em `ai_calls`. None = não mede.
+ self.meter = None
- def configure(self, provider: str, model: str, analyst_model: str | None = None) -> None:
+ # ---------- papéis
+ @property
+ def provider(self) -> str:
+ return "off" if self._master == "off" else self.roles["editor"]["provider"]
+
+ @provider.setter
+ def provider(self, value: str) -> None:
+ """Compatível com o jeito antigo (um provedor só): "off" desliga a equipe; outro vale para todos os papéis."""
+ if value == "off":
+ self._master = "off"
+ return
+ if value not in AI_ENABLED:
+ raise JudgeError(f"provedor precisa ser um de {', '.join(PROVIDERS)}")
+ self._master = "on"
+ for role in self.roles.values():
+ if role["provider"] != value:
+ role["provider"], role["model"] = value, ""
+
+ @property
+ def model(self) -> str:
+ return self.role_model("editor")
+
+ @property
+ def analyst_model(self) -> str:
+ return self.roles["analyst"]["model"]
+
+ def role_model(self, role: str) -> str:
+ conf = self.roles[role]
+ return conf["model"] or DEFAULT_MODELS.get(conf["provider"], "")
+
+ def role_enabled(self, role: str) -> bool:
+ return self.enabled and bool(self.roles[role]["enabled"])
+
+ def system_for(self, role: str, base: str, lang: str = "pt") -> str:
+ """Instruções padrão do papel + as do administrador (somadas, nunca no lugar)."""
+ return base + roles_module.admin_notes(self.roles.get(role) or {}, lang)
+
+ def configure(self, provider: str, model: str, analyst_model: str | None = None, roles: dict | None = None) -> None:
+ """`roles` = configuração por papel (painel novo). Sem ela (painel antigo): `provider`/`model` valem para
+ todos os papéis e `analyst_model` para o analista. `provider == "off"` desliga a equipe."""
if provider not in PROVIDERS:
raise JudgeError(f"provedor precisa ser um de {', '.join(PROVIDERS)}")
- self.provider = provider
- self.model = model.strip() or DEFAULT_MODELS.get(provider, "")
+ if roles is not None:
+ self.roles = roles_module.normalize_roles(roles, self.roles)
+ self._master = "off" if provider == "off" else "on"
+ return
+ if provider == "off":
+ self._master = "off"
+ return
+ self._master = "on"
+ model = model.strip()
+ for name, role in self.roles.items():
+ role["provider"] = provider
+ role["model"] = "" if model == DEFAULT_MODELS.get(provider) else model
if analyst_model is not None:
- self.analyst_model = analyst_model.strip()
+ self.roles["analyst"]["model"] = analyst_model.strip()
+ elif self.roles["analyst"]["model"] and provider != self.roles["analyst"]["provider"]:
+ self.roles["analyst"]["model"] = ""
+
+ def roles_view(self, skip: dict[str, str | None] | None = None) -> dict:
+ """Papéis para o painel: a configuração + o modelo efetivo e a cadeia de reserva de cada um."""
+ out = {}
+ for name in roles_module.ROLES:
+ conf = dict(self.roles[name])
+ conf["resolvedModel"] = self.role_model(name)
+ conf["chain"] = self.fallback_chain(conf["provider"], skip) if self.enabled else []
+ out[name] = conf
+ return out
+
+ @staticmethod
+ def default_instructions() -> dict:
+ """Texto padrão de cada papel nos dois idiomas (o painel mostra só para leitura)."""
+ return {"scan": {"pt": SCAN_SYSTEM, "en": SCAN_SYSTEM_EN},
+ "analyst": {"pt": ANALYST_SYSTEM, "en": ANALYST_SYSTEM_EN},
+ "editor": {"pt": JUDGE_SYSTEM, "en": JUDGE_SYSTEM_EN},
+ "judge": {"pt": CONTEXT_SYSTEM, "en": CONTEXT_SYSTEM_EN}}
@property
def enabled(self) -> bool:
@@ -915,6 +1288,16 @@ class Judge:
""""provedor:modelo" de quem respondeu a última chamada desta thread (a reserva pode ter respondido)."""
return getattr(self._local, "responder", None) or f"{self.provider}:{self.model}"
+ @contextmanager
+ def scope(self, **context):
+ """Contexto das chamadas desta thread para a medição (`session_id`, `clip_id`, `mode`)."""
+ previous = getattr(self._local, "scope", None) or {}
+ self._local.scope = {**previous, **context}
+ try:
+ yield
+ finally:
+ self._local.scope = previous
+
# ---------- reserva
def pauses(self) -> dict[str, tuple[float, str]]:
"""Pausas ainda valendo (as vencidas saem)."""
@@ -942,18 +1325,21 @@ class Judge:
return "modo chave de API sem chave no cofre"
return None
- def fallback_chain(self) -> list[str]:
- """Ordem em que `ask` tenta as IAs: a escolhida no juiz primeiro, depois a `order` do painel, só as ligadas,
- com CLI e (no modo chave) com chave; as em pausa são puladas e as perto do limite de uso vão para o fim.
- Reserva desligada: só a escolhida.
- Se TODAS as prontas estiverem em pausa, elas voltam como último recurso (melhor tentar do que parar)."""
+ def fallback_chain(self, primary: str | None = None, skip: dict[str, str | None] | None = None) -> list[str]:
+ """Ordem em que `ask` tenta as IAs: a do papel (`primary`; padrão = a do editor) primeiro, depois a `order`
+ do painel, só as ligadas, com CLI e (no modo chave) com chave; as em pausa são puladas e as perto do limite
+ de uso vão para o fim. Reserva desligada: só a escolhida.
+ Se TODAS as prontas estiverem em pausa, elas voltam como último recurso (melhor tentar do que parar).
+ `skip` = `_skip_reason` já calculado por provedor (o `describe` monta a cadeia de cada papel de uma vez)."""
if not self.enabled:
return []
+ primary = primary if primary in AI_ENABLED else self.provider
settings = self.ai.settings()
- candidates = [self.provider]
+ candidates = [primary]
if settings["fallback"]["enabled"]:
- candidates += [p for p in settings["order"] if p != self.provider and p in AI_ENABLED]
- ready = [p for p in candidates if self._skip_reason(p, settings) is None]
+ candidates += [p for p in settings["order"] if p != primary and p in AI_ENABLED]
+ ready = [p for p in candidates
+ if (skip[p] if skip is not None and p in skip else self._skip_reason(p, settings)) is None]
if not settings["fallback"]["enabled"]:
return ready
paused = self.pauses()
@@ -965,29 +1351,36 @@ class Judge:
def describe(self) -> dict:
cmd = self.command() if self.enabled else None
settings = self.ai.settings()
- primary_skip = self._skip_reason(self.provider, settings) if self.enabled else None
+ # Uma checagem por provedor (CLI no PATH, ligada, chave) para todas as cadeias: o painel lê isto a cada poucos s.
+ skip = {p: self._skip_reason(p, settings) for p in AI_ENABLED}
+ primary_skip = skip.get(self.provider) if self.enabled else None
return {"provider": self.provider, "model": self.model if self.enabled else None,
- "analystModel": (self.analyst_model or self.model) if self.enabled else None,
+ "analystModel": self.role_model("analyst") if self.enabled else None,
"available": bool(cmd) if self.enabled else None, "path": cmd[-1] if cmd else None,
# Por que a escolhida não roda (desligada no painel, sem CLI, sem chave); None = pronta.
"unavailableReason": primary_skip,
"authMode": settings["providers"].get(self.provider, {}).get("authMode") if self.enabled else None,
"fallback": {"enabled": settings["fallback"]["enabled"],
"cooldownMin": settings["fallback"]["cooldownMin"],
- "chain": self.fallback_chain()},
+ "chain": self.fallback_chain(skip=skip)},
"pauses": [{"provider": p, "until": datetime.fromtimestamp(until, timezone.utc).isoformat(timespec="seconds"),
- "reason": reason} for p, (until, reason) in sorted(self.pauses().items())]}
+ "reason": reason} for p, (until, reason) in sorted(self.pauses().items())],
+ # Equipe de IA: cada papel com a sua IA (doc/clipador/EQUIPE-IA.md).
+ "roles": self.roles_view(skip),
+ "providers": {p: {"ready": skip[p] is None, "reason": skip[p],
+ "enabled": bool((settings["providers"].get(p) or {}).get("enabled"))}
+ for p in AI_ENABLED}}
def models(self) -> dict:
return {"codex": codex_models(), "claude": CLAUDE_MODELS, "gemini": GEMINI_MODELS, "defaults": DEFAULT_MODELS}
# ---------- usos
def analyze(self, prompt: str, images: list[Path], lang: str = "pt") -> dict:
- """1º juiz (ANALISTA): o que aconteceu, cruzando tela + fala + chat. Não decide nem escreve título.
+ """ANALISTA: o que aconteceu, cruzando tela + fala + chat. Não decide nem escreve título.
`lang="en"`: prompt em inglês e bloco `pt` (tradução para o painel) na mesma resposta."""
system, schema = (ANALYST_SYSTEM_EN, ANALYSIS_SCHEMA_EN) if lang == "en" else (ANALYST_SYSTEM, ANALYSIS_SCHEMA)
- data = self.ask(system, prompt, schema, images, model=self.analyst_model or self.model)
- missing = [k for k in ANALYSIS_SCHEMA["required"] if k not in data]
+ data = self.ask(self.system_for("analyst", system, lang), prompt, schema, images, role="analyst")
+ missing = [k for k in ANALYSIS_SCHEMA["required"] if k not in data and k not in ANALYSIS_OPTIONAL]
if missing:
raise JudgeError(f"análise sem os campos {missing}")
data["confidence"] = max(0.0, min(1.0, float(data["confidence"])))
@@ -996,18 +1389,26 @@ class Judge:
def judge(self, prompt: str, start_s: float, end_s: float, images: list[Path] | None = None, *,
lo: float | None = None, hi: float | None = None, min_s: float = DEFAULT_MIN_S,
max_s: float = DEFAULT_MAX_S, lang: str = "pt") -> Verdict:
+ """EDITOR: decide se vira corte, o trecho, título, legenda e hashtags."""
system, schema = (JUDGE_SYSTEM_EN, VERDICT_SCHEMA_EN) if lang == "en" else (JUDGE_SYSTEM, VERDICT_SCHEMA)
- data = self.ask(system, prompt, schema, images or [])
+ data = self.ask(self.system_for("editor", system, lang), prompt, schema, images or [], role="editor")
# Modelo de quem DE FATO respondeu (a reserva pode ter entrado no lugar da escolhida).
return _clean(data, start_s, end_s, self.responder(), lo, hi, min_s, max_s)
+ def check_context(self, prompt: str, lang: str = "pt") -> dict:
+ """JUIZ de contexto (só texto): o que um espectador frio entende + as checagens sim/não. Quem decide pelas
+ respostas é o código (`context_judge.decide`)."""
+ system, schema = (CONTEXT_SYSTEM_EN, CONTEXT_SCHEMA_EN) if lang == "en" else (CONTEXT_SYSTEM, CONTEXT_SCHEMA)
+ data = self.ask(self.system_for("judge", system, lang), prompt, schema, [], role="judge")
+ return clean_context(data)
+
def translate_lines(self, lines: list[str]) -> list[str]:
"""Fala de um corte (frases em ordem) → português, mesma quantidade. Para o painel e a legenda de
desenvolvimento; o vídeo publicado continua no idioma da fonte."""
if not lines:
return []
prompt = "\n".join(f"{i + 1}. {text}" for i, text in enumerate(lines))
- data = self.ask(LINES_SYSTEM, prompt, LINES_SCHEMA, [])
+ data = self.ask(LINES_SYSTEM, prompt, LINES_SCHEMA, [], purpose="translate")
out = [str(x).strip() for x in (data.get("lines") or [])]
if len(out) != len(lines):
raise JudgeError(f"tradução com {len(out)} linhas para {len(lines)} frases", unavailable=False)
@@ -1015,7 +1416,7 @@ class Judge:
def scan(self, prompt: str, images: list[Path], lang: str = "pt") -> dict:
system, schema = (SCAN_SYSTEM_EN, SCAN_SCHEMA_EN) if lang == "en" else (SCAN_SYSTEM, SCAN_SCHEMA)
- data = self.ask(system, prompt, schema, images)
+ data = self.ask(self.system_for("scan", system, lang), prompt, schema, images, role="scan")
if not isinstance(data.get("moments"), list):
raise JudgeError("varredura sem a lista de momentos")
return data
@@ -1025,7 +1426,8 @@ class Judge:
if notes:
prompt += "User requests (respect them; may be in Portuguese):\n" + "\n".join(f"- {n}" for n in notes) + "\n"
prompt += "Research and return the game profile in English."
- return self.ask(PROFILE_SYSTEM, prompt, PROFILE_SCHEMA, [], search=True, timeout=RESEARCH_TIMEOUT_S)
+ return self.ask(PROFILE_SYSTEM, prompt, PROFILE_SCHEMA, [], search=True, timeout=RESEARCH_TIMEOUT_S,
+ purpose="research")
def refine_game(self, name: str, profile: dict, instruction: str, search: bool = True, section: str = "",
history: list[dict] | None = None) -> dict:
@@ -1039,14 +1441,14 @@ class Judge:
f"{'User' if h.get('role') == 'user' else 'AI'}: {str(h.get('text', ''))[:400]}" for h in history[-8:]) + "\n"
prompt += f"User REQUEST:\n{instruction}\n\nReturn the complete updated profile (English) and the reply (Portuguese)."
return self.ask(REFINE_SYSTEM, prompt, REFINE_SCHEMA, [], search=search,
- timeout=RESEARCH_TIMEOUT_S if search else TIMEOUT_S)
+ timeout=RESEARCH_TIMEOUT_S if search else TIMEOUT_S, purpose="research")
def translate_game(self, profile: dict, target: str) -> dict:
"""Traduz o perfil inteiro (pt-BR <-> en-US), mesmo formato, sem busca. Nomes oficiais e hashtags ficam."""
language = TRANSLATE_TARGETS.get(target, target)
prompt = (f"Target language: {language}\nProfile JSON:\n{json.dumps(profile, ensure_ascii=False, indent=1)}\n\n"
"Return the translated profile.")
- return self.ask(TRANSLATE_SYSTEM, prompt, PROFILE_SCHEMA, [], timeout=RESEARCH_TIMEOUT_S)
+ return self.ask(TRANSLATE_SYSTEM, prompt, PROFILE_SCHEMA, [], timeout=RESEARCH_TIMEOUT_S, purpose="translate")
def detect_game(self, images: list[Path], live_title: str = "") -> dict:
prompt = (f"Título da live (só uma dica): {live_title or '(sem título)'}\n"
@@ -1054,29 +1456,38 @@ class Judge:
return self.ask(GAME_SYSTEM, prompt, GAME_SCHEMA, images)
def detect_cam(self, images: list[Path]) -> dict:
- return self.ask(CAM_SYSTEM, "Analise os frames anexados (mesma live, instantes diferentes).", CAM_SCHEMA, images)
+ return self.ask(CAM_SYSTEM, "Analise os frames anexados (mesma live, instantes diferentes).", CAM_SCHEMA, images,
+ purpose="cam")
# ---------- execução
def ask(self, system: str, prompt: str, schema: dict, images: list[Path], *, search: bool = False,
- timeout: int = TIMEOUT_S, model: str | None = None) -> dict:
- """Chama a IA escolhida; se ela falhar por indisponibilidade, a próxima da cadeia de reserva (com o modelo
- padrão DELA) e a que falhou fica em pausa. Erro de conteúdo (JSON inválido, campos faltando) não troca."""
+ timeout: int = TIMEOUT_S, model: str | None = None, role: str = "editor", purpose: str | None = None) -> dict:
+ """Chama a IA do papel `role`; se ela falhar por indisponibilidade, a próxima da cadeia de reserva (com o
+ modelo padrão DELA) e a que falhou fica em pausa. Erro de conteúdo (JSON inválido, campos faltando) não troca.
+ Cada tentativa é medida (`meter`), com o papel, a IA, o tamanho do prompt e das imagens e os tokens."""
if not self.enabled:
raise JudgeError("IA desligada", unavailable=False)
- chain = self.fallback_chain()
+ conf = self.roles.get(role) or self.roles["editor"]
+ primary = conf["provider"]
+ chain = self.fallback_chain(primary)
if not chain:
- why = self._skip_reason(self.provider, self.ai.settings()) or "nenhuma IA pronta"
- raise JudgeError(f"{PROVIDER_NAMES[self.provider]} indisponível: {why} (veja Configurações → IA)",
+ why = self._skip_reason(primary, self.ai.settings()) or "nenhuma IA pronta"
+ raise JudgeError(f"{PROVIDER_NAMES.get(primary, primary)} indisponível: {why} (veja Configurações → IA)",
unavailable=True)
fallback_on = self.ai.settings()["fallback"]["enabled"]
attempts: list[str] = []
for provider in chain:
- use_model = (model or self.model) if provider == self.provider else DEFAULT_MODELS[provider]
+ use_model = (model or self.role_model(role if role in self.roles else "editor")) if provider == primary \
+ else DEFAULT_MODELS[provider]
+ effort = conf.get("effort", "") if provider == primary else ""
+ self._local.usage = None
+ started = time.monotonic()
try:
- data = self._call(provider, system, prompt, schema, images, search, timeout, use_model)
+ data = self._call(provider, system, prompt, schema, images, search, timeout, use_model, effort)
except JudgeError as exc:
text = str(exc)
unavailable = exc.unavailable if exc.unavailable is not None else is_availability_error(text)
+ self._measure(role, purpose, provider, use_model, system, prompt, images, started, text)
attempts.append(f"{provider}:{use_model}: {text}")
if not unavailable:
# Erro de conteúdo: a IA respondeu, o pedido é que não deu certo. Não troca de IA.
@@ -1086,16 +1497,38 @@ class Judge:
log.warning("IA %s indisponível (%s); tentando a reserva", provider, text[:160])
continue
raise JudgeError(text, unavailable=True) from exc
+ self._measure(role, purpose, provider, use_model, system, prompt, images, started, None)
self._local.responder = f"{provider}:{use_model}"
- if provider != self.provider:
+ if provider != primary:
log.info("respondido pela reserva %s:%s", provider, use_model)
return data
raise JudgeError("nenhuma IA respondeu — " + " · ".join(attempts)[:900], unavailable=True)
+ def _measure(self, role: str, purpose: str | None, provider: str, model: str, system: str, prompt: str,
+ images: list[Path], started: float, error: str | None) -> None:
+ if self.meter is None:
+ return
+ image_bytes = 0
+ for img in images:
+ try:
+ image_bytes += Path(img).stat().st_size
+ except OSError:
+ pass
+ usage = getattr(self._local, "usage", None) or {}
+ record = {"role": role, "purpose": purpose or role, "provider": provider, "model": model, "ok": error is None,
+ "error": (error or "")[:300] or None, "ms": int((time.monotonic() - started) * 1000),
+ "systemChars": len(system), "promptChars": len(prompt), "images": len(images),
+ "imageBytes": image_bytes, "tokensIn": usage.get("in"), "tokensOut": usage.get("out"),
+ "tokensCached": usage.get("cached"), **(getattr(self._local, "scope", None) or {})}
+ try:
+ self.meter(record)
+ except Exception as exc: # noqa: BLE001 - medir nunca derruba a chamada
+ log.debug("medição da chamada falhou: %s", exc)
+
def _call(self, provider: str, system: str, prompt: str, schema: dict, images: list[Path], search: bool,
- timeout: int, model: str) -> dict:
+ timeout: int, model: str, effort: str = "") -> dict:
if provider == "codex":
- return self._codex(system, prompt, schema, images, search, timeout, model)
+ return self._codex(system, prompt, schema, images, search, timeout, model, effort)
if provider == "claude":
return self._claude(system, prompt, schema, images, search, timeout, model)
if provider == "gemini":
@@ -1121,7 +1554,7 @@ class Judge:
return result
def _codex(self, system: str, prompt: str, schema: dict, images: list[Path], search: bool, timeout: int,
- model: str) -> dict:
+ model: str, effort: str = "") -> dict:
cmd = find_codex()
if not cmd:
raise JudgeError("Codex CLI não encontrado (npm install -g @openai/codex; codex login)", unavailable=True)
@@ -1140,12 +1573,16 @@ class Judge:
instructions.write_text(system, encoding="utf-8")
lean += ["-c", f"model_instructions_file='{instructions}'"]
stdin = prompt
+ # Esforço de raciocínio por papel (Equipe de IA); padrão = low, o de sempre.
+ reasoning = effort if effort in ("low", "medium", "high") else "low"
# `--search` é opção global (antes de `exec`). Cada imagem com seu `-i`; o "-" (prompt pela entrada
# padrão) vem depois de uma opção de valor único para não ser lido como mais uma imagem.
+ # `--json`: eventos JSONL na saída padrão — o `turn.completed` traz o uso de tokens (medição F0).
args = [*cmd, *(["--search"] if search else []), "exec", "--skip-git-repo-check", "--ephemeral",
- "--sandbox", "read-only", "-c", 'model_reasoning_effort="low"', *lean, "-m", model, *image_args,
- "--output-schema", str(schema_file), "-o", str(out), "-C", tmp, "-"]
- self._run(args, stdin, Path(tmp), timeout, "codex")
+ "--sandbox", "read-only", "--json", "-c", f'model_reasoning_effort="{reasoning}"', *lean,
+ "-m", model, *image_args, "--output-schema", str(schema_file), "-o", str(out), "-C", tmp, "-"]
+ result = self._run(args, stdin, Path(tmp), timeout, "codex")
+ self._local.usage = codex_usage(result.stdout.decode("utf-8", errors="replace"))
try:
return json.loads(out.read_text(encoding="utf-8"))
except (OSError, json.JSONDecodeError) as exc:
@@ -1175,6 +1612,7 @@ class Judge:
envelope = json.loads(result.stdout.decode("utf-8", errors="replace"))
except json.JSONDecodeError as exc:
raise JudgeError("o Claude não devolveu JSON", unavailable=False) from exc
+ self._local.usage = claude_usage(envelope)
if envelope.get("is_error"):
# Pode ser cota/login ("Credit balance is too low", "Not logged in"): o texto decide (unavailable=None).
raise JudgeError(f"o Claude terminou com erro: {str(envelope.get('result'))[:200]}")
@@ -1221,7 +1659,9 @@ class Judge:
short += " Frames anexados, na ordem: " + " ".join(refs)
args = [*cmd, "-p", short, "-o", "json", "--approval-mode", "plan", "--skip-trust", "-m", model]
result = self._run(args, stdin, Path(tmp), timeout, "gemini")
- return parse_gemini_output(result.stdout.decode("utf-8", errors="replace"))
+ stdout = result.stdout.decode("utf-8", errors="replace")
+ self._local.usage = gemini_usage(extract_json_object(stdout, fences=False) or {})
+ return parse_gemini_output(stdout)
def parse_gemini_output(stdout: str) -> dict:
diff --git a/clipper/app/main.py b/clipper/app/main.py
index a07092f..61fa035 100644
--- a/clipper/app/main.py
+++ b/clipper/app/main.py
@@ -25,7 +25,7 @@ from .scoring import Word
from .sources import SourceError, parse_source
from .subtitles import build_ass
from .worker import Engine
-from . import clip_delete, editor_api
+from . import clip_delete, editor_api, report
VERSION = "1.0.0"
logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(name)s %(message)s")
@@ -96,6 +96,12 @@ class JudgeIn(BaseModel):
camDetect: bool | None = None
# Rastreio do rosto do streamer (face.py): reforça/cria cortes e vai em texto para o analista.
faceTrack: bool | None = None
+ # A IA lê o vídeo como linha do tempo JSON curta (novo); False = transcrição + chat + frames soltos (antigo).
+ timelineJson: bool | None = None
+ # Equipe de IA (doc/clipador/EQUIPE-IA.md): {scan|analyst|editor|judge: {enabled, provider, model, effort, extra,
+ # images, critical, allowFix, allowContextLine, penalty}}. None = não mexer (painel antigo: provider/model valem
+ # para todos os papéis). Validado campo a campo em roles.normalize_roles.
+ roles: dict | None = None
class GameIn(BaseModel):
@@ -152,6 +158,10 @@ class PreviewIn(BaseModel):
class ClipPatch(BaseModel):
status: Literal["approved", "rejected", "ready", "published"] | None = None
+ # Avaliação do dono (conjunto de avaliação do juiz): bom / ruim / sem contexto; "" limpa. Rejeitar com
+ # label "no_context" = "rejeitado: sem contexto".
+ label: Literal["good", "bad", "no_context", ""] | None = None
+ labelNote: str | None = Field(default=None, max_length=300)
title: str | None = Field(default=None, max_length=100)
caption: str | None = Field(default=None, max_length=2200)
startS: float | None = Field(default=None, ge=0)
@@ -194,6 +204,8 @@ def clip_view(row: dict) -> dict:
# e nos cortes de antes da migração v8, vale o padrão `vertical`.
"aspect": row.get("aspect") or "vertical",
"createdAt": row["created_at"], "updatedAt": row["updated_at"],
+ # Avaliação do dono (bom / ruim / sem contexto) para medir o juiz; None = não marcou.
+ "ownerLabel": row.get("owner_label"), "ownerNote": row.get("owner_note"),
"channelId": row.get("channel_id"), "platform": row.get("platform"), "sessionUrl": row.get("url"),
# Idioma da sessão (resolvido no SELECT: o da sessão ou o padrão do serviço). Ausente só em consultas antigas.
"language": row.get("language"),
@@ -321,18 +333,25 @@ def create_app(settings: Settings | None = None, engine: Engine | None = None, s
# ---------- juiz (IA pela CLI: Codex/GPT ou Claude)
@app.get("/v1/judge")
def get_judge():
- return engine.judge_config() | {"models": engine.judge.models()}
+ return engine.judge_config(full=True) | {"models": engine.judge.models()}
@app.put("/v1/judge")
def put_judge(body: JudgeIn):
try:
engine.intel.set_options({"scanEnabled": body.scanEnabled, "scanIntervalS": body.scanIntervalS,
- "vision": body.vision, "camDetect": body.camDetect, "faceTrack": body.faceTrack})
- return engine.set_judge_config(body.provider, body.model, body.minScore, body.analystModel) | {
+ "vision": body.vision, "camDetect": body.camDetect, "faceTrack": body.faceTrack,
+ "timelineJson": body.timelineJson})
+ return engine.set_judge_config(body.provider, body.model, body.minScore, body.analystModel, body.roles) | {
"models": engine.judge.models()}
except JudgeError as exc:
raise UserError(str(exc)) from exc
+ @app.get("/v1/judge/report")
+ def judge_report(days: float = Query(default=7, gt=0, le=365), session: int | None = None):
+ """Medição da Equipe de IA (F0): chamadas e tokens por papel/IA, por hora de live; taxa de aprovação; o que o
+ juiz de contexto decidiu; e a concordância juiz × dono nos cortes que você avaliou."""
+ return report.build(db, days=days, session_id=session)
+
# ---------- configuração do corte (layout, câmera, legenda, crédito, duração)
def _settings_payload(own: dict, channel_layer: dict | None, session_layer: dict | None) -> dict:
return {"own": own, "effective": layout.merge(channel_layer, session_layer), "defaults": layout.DEFAULTS,
@@ -790,6 +809,11 @@ def create_app(settings: Settings | None = None, engine: Engine | None = None, s
status = body.status or row["status"]
if body.status in ("approved", "published") and row["status"] not in ("ready", "approved", "published"):
raise UserError("Só dá para aprovar um corte já renderizado.")
+ if body.label is not None or body.labelNote is not None:
+ # Avaliação do dono: vale para qualquer corte (inclusive antigos e descartados), sem mexer no estado.
+ label = row.get("owner_label") if body.label is None else (body.label or None)
+ note = row.get("owner_note") if body.labelNote is None else (body.labelNote.strip() or None)
+ db.run("UPDATE clips SET owner_label = ?, owner_note = ? WHERE id = ?", label, note, clip_id)
if retime:
status = "pending" # novo trecho → renderiza de novo
db.run("UPDATE clips SET title = ?, caption = ?, start_s = ?, end_s = ?, status = ?, updated_at = ? WHERE id = ?",
diff --git a/clipper/app/media.py b/clipper/app/media.py
index 26e0d87..ba6b3db 100644
--- a/clipper/app/media.py
+++ b/clipper/app/media.py
@@ -153,6 +153,43 @@ def grab_frame(ffmpeg: str, segments: list[tuple[Path, float, float]], t: float,
return out_file
+MOSAIC_TILE_W, MOSAIC_TILE_H = 384, 216
+MOSAIC_COLS, MOSAIC_ROWS = 4, 2
+
+
+def mosaic(ffmpeg: str, images: list[Path], out_file: Path, cols: int = MOSAIC_COLS, rows: int = MOSAIC_ROWS,
+ tile_w: int = MOSAIC_TILE_W, tile_h: int = MOSAIC_TILE_H) -> Path:
+ """Vários quadros numa imagem só (grade `cols`×`rows`, da esquerda para a direita e de cima para baixo), cada um
+ em `tile_w`×`tile_h` (barras pretas se o quadro não for 16:9). Com menos quadros que a grade, a grade encolhe
+ (até 4 → uma linha só). Para a IA: 1 imagem no lugar de 8 (Claude = 1 leitura; Gemini cobra por imagem)."""
+ images = [Path(p) for p in images][: cols * rows]
+ if not images:
+ raise MediaError("mosaico sem quadros")
+ n = len(images)
+ if n <= cols:
+ cols, rows = n, 1
+ else:
+ rows = math.ceil(n / cols)
+ out_file.parent.mkdir(parents=True, exist_ok=True)
+ inputs = [arg for img in images for arg in ("-i", str(img))]
+ fit = (f"scale={tile_w}:{tile_h}:force_original_aspect_ratio=decrease,"
+ f"pad={tile_w}:{tile_h}:(ow-iw)/2:(oh-ih)/2,setsar=1")
+ chains = [f"[{i}:v]{fit}[t{i}]" for i in range(n)]
+ # Grade incompleta (ex.: 6 quadros em 4×2): completa com quadro preto do mesmo tamanho.
+ pads = cols * rows - n
+ for k in range(pads):
+ chains.append(f"color=c=black:s={tile_w}x{tile_h}:d=1[p{k}]")
+ labels = [f"[t{i}]" for i in range(n)] + [f"[p{k}]" for k in range(pads)]
+ layout_cells = "|".join(f"{(i % cols) * tile_w}_{(i // cols) * tile_h}" for i in range(cols * rows))
+ if cols * rows == 1:
+ graph = chains[0].replace("[t0]", "[out]")
+ else:
+ graph = ";".join(chains) + ";" + "".join(labels) + f"xstack=inputs={cols * rows}:layout={layout_cells}[out]"
+ run([ffmpeg, "-y", "-v", "error", *inputs, "-filter_complex", graph, "-map", "[out]", "-frames:v", "1",
+ "-q:v", "4", str(out_file)], 60)
+ return out_file
+
+
def preview_still(ffmpeg: str, frame_file: Path, settings: dict, ass_text: str, out_file: Path, reframe=None) -> Path:
"""Prévia do layout num quadro só (imagem no formato do corte com câmera, jogo, legenda e crédito de exemplo).
`reframe` = reenquadramento parado do jogo (capa de um corte com keyframes; ver `reframe.static_reframe`)."""
diff --git a/clipper/app/report.py b/clipper/app/report.py
new file mode 100644
index 0000000..d231aae
--- /dev/null
+++ b/clipper/app/report.py
@@ -0,0 +1,145 @@
+"""Relatório da Equipe de IA (F0 — medir antes de otimizar; doc/clipador/EQUIPE-IA.md).
+
+`GET /v1/judge/report?days=7[&session=N]`:
+- `calls`: por papel × IA × modelo × modo (linha do tempo/antigo, mosaico/frames): chamadas, falhas, tamanho médio do
+ prompt, imagens, tokens (quando a CLI informa) e tempo médio;
+- `perHour`: chamadas e tokens por hora de live gravada no período (por papel);
+- `clips`: cortes do período por estado e a taxa de aprovação do dono;
+- `judge`: o que o juiz de contexto decidiu (aprovou, ajustou, descartou, avisou, erro, frase de contexto);
+- `agreement`: concordância juiz × dono (e editor × dono) nos cortes que o dono avaliou.
+
+Veredito do dono: `owner_label` (bom / ruim / sem contexto) quando marcado; senão aprovado/publicado = bom e
+rejeitado = ruim. Veredito do juiz: aprovou/ajustou/avisou = mantém; descartou = descarta.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timedelta, timezone
+
+from .db import Database, loads
+
+KEEP_DECISIONS = ("approve", "adjust", "warn")
+
+
+def _since(days: float) -> str:
+ return (datetime.now(timezone.utc) - timedelta(days=days)).isoformat(timespec="seconds")
+
+
+def owner_verdict(row: dict) -> str | None:
+ """good | bad | no_context | None (o dono ainda não disse)."""
+ if row.get("owner_label"):
+ return row["owner_label"]
+ if row["status"] in ("approved", "published"):
+ return "good"
+ if row["status"] == "rejected":
+ return "bad"
+ return None
+
+
+def judge_verdict(judge: dict) -> str | None:
+ """keep | discard | None (juiz não rodou ou falhou)."""
+ context = (judge or {}).get("context") if isinstance(judge, dict) else None
+ if not isinstance(context, dict) or context.get("error"):
+ return None
+ decision = context.get("decision")
+ if decision in KEEP_DECISIONS:
+ return "keep"
+ return "discard" if decision == "discard" else None
+
+
+def editor_verdict(judge: dict) -> str | None:
+ if not isinstance(judge, dict) or "keep" not in judge:
+ return None
+ return "keep" if judge.get("keep") else "discard"
+
+
+def agreement(pairs: list[tuple[str, str]]) -> dict:
+ """Concordância (e kappa de Cohen) entre "mantém/descarta" da IA e "bom/ruim" do dono ("sem contexto" = ruim)."""
+ matrix = {"keep": {"good": 0, "bad": 0, "no_context": 0}, "discard": {"good": 0, "bad": 0, "no_context": 0}}
+ for ai, owner in pairs:
+ matrix[ai][owner] += 1
+ n = len(pairs)
+ if not n:
+ return {"pairs": 0, "agree": 0, "rate": None, "kappa": None, "matrix": matrix}
+ agree = matrix["keep"]["good"] + matrix["discard"]["bad"] + matrix["discard"]["no_context"]
+ p_keep = (sum(matrix["keep"].values())) / n
+ p_good = (matrix["keep"]["good"] + matrix["discard"]["good"]) / n
+ pe = p_keep * p_good + (1 - p_keep) * (1 - p_good)
+ po = agree / n
+ kappa = None if pe >= 1 else round((po - pe) / (1 - pe), 3)
+ return {"pairs": n, "agree": agree, "rate": round(po, 3), "kappa": kappa, "matrix": matrix}
+
+
+def build(db: Database, days: float = 7, session_id: int | None = None) -> dict:
+ since = _since(days)
+ call_where, call_args = ("session_id = ?", [session_id]) if session_id else ("at >= ?", [since])
+ rows = db.all(
+ "SELECT role, purpose, provider, model, COALESCE(mode, '') AS mode, COUNT(*) AS calls, SUM(ok) AS ok,"
+ " AVG(COALESCE(system_chars, 0) + COALESCE(prompt_chars, 0)) AS avg_chars, AVG(images) AS avg_images,"
+ " SUM(COALESCE(image_bytes, 0)) AS image_bytes, SUM(tokens_in) AS tokens_in, SUM(tokens_out) AS tokens_out,"
+ " SUM(tokens_cached) AS tokens_cached, SUM(CASE WHEN tokens_in IS NOT NULL THEN 1 ELSE 0 END) AS with_usage,"
+ " AVG(ms) AS avg_ms FROM ai_calls WHERE " + call_where +
+ " GROUP BY role, purpose, provider, model, mode ORDER BY role, calls DESC", *call_args)
+ calls = [{"role": r["role"], "purpose": r["purpose"], "provider": r["provider"], "model": r["model"],
+ "mode": r["mode"], "calls": r["calls"], "failures": r["calls"] - (r["ok"] or 0),
+ "avgChars": round(r["avg_chars"] or 0), "avgImages": round(r["avg_images"] or 0, 2),
+ "imageKB": round((r["image_bytes"] or 0) / 1024), "tokensIn": r["tokens_in"], "tokensOut": r["tokens_out"],
+ "tokensCached": r["tokens_cached"], "withUsage": r["with_usage"], "avgMs": round(r["avg_ms"] or 0)}
+ for r in rows]
+
+ session_where, session_args = ("id = ?", [session_id]) if session_id else ("started_at >= ?", [since])
+ live_s = db.get(f"SELECT COALESCE(SUM(duration_s), 0) AS s FROM sessions WHERE {session_where}", *session_args)["s"]
+ hours = live_s / 3600
+ per_role: dict[str, dict] = {}
+ for c in calls:
+ item = per_role.setdefault(c["role"], {"calls": 0, "tokensIn": 0, "tokensOut": 0, "withUsage": 0, "chars": 0})
+ item["calls"] += c["calls"]
+ item["tokensIn"] += c["tokensIn"] or 0
+ item["tokensOut"] += c["tokensOut"] or 0
+ item["withUsage"] += c["withUsage"]
+ item["chars"] += c["avgChars"] * c["calls"]
+ per_hour = {role: {"calls": round(v["calls"] / hours, 1) if hours else None,
+ "tokensIn": round(v["tokensIn"] / hours) if hours and v["withUsage"] else None,
+ "tokensOut": round(v["tokensOut"] / hours) if hours and v["withUsage"] else None,
+ # Estimativa pelo tamanho do texto (~4 caracteres por token), para quando a CLI não informa.
+ "estTokensIn": round(v["chars"] / 4 / hours) if hours else None}
+ for role, v in per_role.items()}
+
+ clip_where, clip_args = ("session_id = ?", [session_id]) if session_id else ("created_at >= ?", [since])
+ clips = db.all(f"SELECT id, status, judge_json, owner_label FROM clips WHERE {clip_where}", *clip_args)
+ by_status: dict[str, int] = {}
+ decisions = {"approve": 0, "adjust": 0, "discard": 0, "warn": 0, "error": 0, "contextLine": 0}
+ judge_pairs: list[tuple[str, str]] = []
+ editor_pairs: list[tuple[str, str]] = []
+ labeled = 0
+ for row in clips:
+ by_status[row["status"]] = by_status.get(row["status"], 0) + 1
+ judge = loads(row["judge_json"], None)
+ context = judge.get("context") if isinstance(judge, dict) else None
+ if isinstance(context, dict):
+ if context.get("error"):
+ decisions["error"] += 1
+ elif context.get("decision") in decisions:
+ decisions[context["decision"]] += 1
+ if context.get("contextLine"):
+ decisions["contextLine"] += 1
+ owner = owner_verdict(row)
+ labeled += owner is not None
+ if owner:
+ if (jv := judge_verdict(judge)) is not None:
+ judge_pairs.append((jv, owner))
+ if (ev := editor_verdict(judge)) is not None:
+ editor_pairs.append((ev, owner))
+ approved = by_status.get("approved", 0) + by_status.get("published", 0)
+ decided = approved + by_status.get("rejected", 0)
+ no_context = sum(1 for r in clips if r.get("owner_label") == "no_context")
+ return {
+ "window": {"days": days, "since": since if not session_id else None, "sessionId": session_id,
+ "liveHours": round(hours, 2)},
+ "calls": calls,
+ "perHour": per_hour,
+ "clips": {"total": len(clips), "byStatus": by_status, "approvalRate": round(approved / decided, 3) if decided else None,
+ "labeled": labeled, "noContext": no_context},
+ "judge": decisions,
+ "agreement": {"judge": agreement(judge_pairs), "editor": agreement(editor_pairs)},
+ }
diff --git a/clipper/app/roles.py b/clipper/app/roles.py
new file mode 100644
index 0000000..1972eed
--- /dev/null
+++ b/clipper/app/roles.py
@@ -0,0 +1,127 @@
+"""Equipe de IA do Clipador (doc/clipador/EQUIPE-IA.md): quatro papéis, cada um com a sua IA.
+
+- **varredura** (`scan`): assiste a live por janelas e propõe momentos (e descreve a tela para a linha do tempo);
+- **analista** (`analyst`): diz O QUE aconteceu no trecho candidato (cruza tela, fala e chat);
+- **editor** (`editor`): decide se vira corte, escolhe o trecho e escreve título/legenda — não pode ser desligado;
+- **juiz** (`judge`): só texto, vê só o que vai no corte final e confere se ele tem CONTEXTO (começo, desfecho,
+ funciona sozinho). Quem decide pelas respostas é o código (`context_judge.decide`).
+
+Cada papel tem provedor + modelo (+ esforço de raciocínio no Codex), liga/desliga e as **instruções do
+administrador** (texto extra somado às instruções padrão, que continuam no código). Gravado na tabela `settings`
+com a chave `judge.roles` (JSON). Sem essa chave (banco de antes), a configuração antiga vira a de todos os papéis:
+o provedor/modelo único de hoje vale para todos e o "modelo do analista" que já existia é respeitado.
+"""
+
+from __future__ import annotations
+
+import copy
+import json
+
+SETTINGS_KEY = "judge.roles"
+ROLES = ("scan", "analyst", "editor", "judge")
+ROLE_NAMES = {"scan": "Varredura", "analyst": "Analista", "editor": "Editor", "judge": "Juiz"}
+ROLE_PROVIDERS = ("codex", "claude", "gemini")
+# Esforço de raciocínio: só o Codex aceita (`model_reasoning_effort`). "" = padrão (low, o de sempre).
+EFFORTS = ("", "low", "medium", "high")
+# Imagens da varredura e do analista: mosaico 4×2 numa imagem só (novo), frames soltos (antigo) ou nenhuma.
+IMAGE_MODES = ("mosaic", "frames", "none")
+IMAGE_ROLES = ("scan", "analyst")
+EXTRA_MAX = 2000
+# Perguntas sim/não do juiz (doc/clipador/PESQUISA-JUIZ.md §6). As críticas decidem; as outras só baixam a nota.
+CHECKS = ("setup", "payoff", "who_what", "standalone", "intelligible", "faithful", "strong_open")
+CHECK_NAMES = {"setup": "começo (setup)", "payoff": "desfecho", "who_what": "quem/o quê", "standalone": "funciona sozinho",
+ "intelligible": "fala clara", "faithful": "título fiel", "strong_open": "abertura forte"}
+DEFAULT_CRITICAL = ("setup", "payoff", "standalone")
+DEFAULT_PENALTY = 0.5
+
+
+def _role(provider: str, model: str = "", effort: str = "", enabled: bool = True) -> dict:
+ return {"enabled": enabled, "provider": provider, "model": model, "effort": effort, "extra": ""}
+
+
+def default_roles(provider: str = "codex", model: str = "", analyst_model: str = "") -> dict:
+ """Configuração de partida: todos os papéis na mesma IA (como era antes). O juiz pensa um pouco mais
+ (esforço médio no Codex), como a pesquisa recomenda; os outros continuam no esforço baixo de sempre."""
+ provider = provider if provider in ROLE_PROVIDERS else "codex"
+ roles = {
+ "scan": _role(provider, model),
+ "analyst": _role(provider, analyst_model or model),
+ "editor": _role(provider, model),
+ "judge": _role(provider, model, "medium" if provider == "codex" else ""),
+ }
+ roles["scan"]["images"] = "mosaic"
+ roles["analyst"]["images"] = "mosaic"
+ roles["judge"] |= {"critical": list(DEFAULT_CRITICAL), "allowFix": True, "allowContextLine": True,
+ "penalty": DEFAULT_PENALTY}
+ return roles
+
+
+def _text(value: object, limit: int) -> str:
+ return str(value or "").replace("\r\n", "\n").strip()[:limit]
+
+
+def normalize_roles(raw: object, base: dict | None = None) -> dict:
+ """Valida campo a campo sobre `base` (padrão: `default_roles()`). O que vier errado fica como estava.
+ O editor nunca desliga (é quem decide se vira corte)."""
+ roles = copy.deepcopy(base or default_roles())
+ if not isinstance(raw, dict):
+ return roles
+ for name in ROLES:
+ item = raw.get(name)
+ if not isinstance(item, dict):
+ continue
+ role = roles[name]
+ if isinstance(item.get("enabled"), bool):
+ role["enabled"] = item["enabled"]
+ if item.get("provider") in ROLE_PROVIDERS:
+ if item["provider"] != role["provider"] and "model" not in item:
+ role["model"] = "" # trocou de provedor sem dizer o modelo: o padrão do provedor novo
+ role["provider"] = item["provider"]
+ if isinstance(item.get("model"), str):
+ model = item["model"].strip()[:80]
+ if all(c.isalnum() or c in "._:-" for c in model):
+ role["model"] = model
+ if item.get("effort") in EFFORTS:
+ role["effort"] = item["effort"]
+ if "extra" in item:
+ role["extra"] = _text(item.get("extra"), EXTRA_MAX)
+ if name in IMAGE_ROLES and item.get("images") in IMAGE_MODES:
+ role["images"] = item["images"]
+ if name == "judge":
+ critical = item.get("critical")
+ if isinstance(critical, list):
+ role["critical"] = [c for c in CHECKS if c in critical]
+ for key in ("allowFix", "allowContextLine"):
+ if isinstance(item.get(key), bool):
+ role[key] = item[key]
+ penalty = item.get("penalty")
+ if isinstance(penalty, (int, float)) and not isinstance(penalty, bool) and 0 <= penalty <= 3:
+ role["penalty"] = float(penalty)
+ roles["editor"]["enabled"] = True
+ return roles
+
+
+def from_settings(saved: dict[str, str], provider: str, model: str) -> dict:
+ """Papéis gravados (`judge.roles`) ou, sem eles, a MIGRAÇÃO da configuração antiga: `judge_provider`/
+ `judge_model` viram os de todos os papéis e `judge_analyst_model` (se havia) fica com o analista.
+ `provider`/`model` = os valores iniciais do .env, para quando nem a antiga existe."""
+ legacy_provider = saved.get("judge_provider", provider)
+ legacy_model = saved.get("judge_model", model) or ""
+ base = default_roles(legacy_provider, legacy_model, saved.get("judge_analyst_model", "") or "")
+ raw = saved.get(SETTINGS_KEY)
+ if not raw:
+ return base
+ try:
+ return normalize_roles(json.loads(raw), base)
+ except ValueError:
+ return base
+
+
+def admin_notes(role: dict, lang: str = "pt") -> str:
+ """Bloco que vai DEPOIS das instruções padrão. Os juízes em inglês entendem português: o dono escreve como quiser."""
+ extra = (role or {}).get("extra", "").strip()
+ if not extra:
+ return ""
+ title = ("Admin notes (may be written in Portuguese; when they conflict with the rules above, they win):"
+ if lang == "en" else "Instruções do administrador (quando conflitarem com as regras acima, valem estas):")
+ return f"\n\n{title}\n{extra}"
diff --git a/clipper/app/timeline.py b/clipper/app/timeline.py
new file mode 100644
index 0000000..57cec8b
--- /dev/null
+++ b/clipper/app/timeline.py
@@ -0,0 +1,298 @@
+"""Linha do tempo em JSON curto (v1): o vídeo "lido" como texto barato para a IA (doc/clipador/EQUIPE-IA.md).
+
+Uma linha JSON por instante (JSON Lines), chaves curtas — a legenda das chaves vai uma vez no prompt —, segundos
+inteiros da gravação e campos vazios omitidos. Só com o que já existe (nenhum modelo novo):
+
+| chave | conteúdo | de onde vem |
+| --- | --- | --- |
+| `t`, `d` | início e duração da entrada | pausas da fala, troca de falante ou no máximo 8 s |
+| `v` | o que está na tela (frase curta) | a IA que já vê os frames (varredura/analista), guardada em `scene_notes` |
+| `sp` | fala literal (até ~25 palavras); `[other1] …` = outra pessoa | Whisper + falantes |
+| `face` | expressão do streamer + intensidade 0–9 (`laugh.7`) | série do rosto (face.FaceService.dense + reaction) |
+| `lvl` | volume relativo ao normal da live, 0–9 (3 = normal) | dBFS por segundo já medido |
+| `chat` | `"mensagens\\|emote×n\\|frase mais repetida"` | chat da sessão |
+| `out` | 1 = fora do corte (o espectador NÃO vê) — só no prompt do juiz | — |
+
+Comportamento antigo (transcrição + chat + frames soltos) continua atrás da opção `timelineJson` (intel.opts).
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import re
+import statistics
+from collections import Counter
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+from .scoring import ChatMessage, Word
+
+if TYPE_CHECKING: # pragma: no cover
+ from .worker import Engine
+
+log = logging.getLogger("cenaforge_clipper.timeline")
+
+STEP_MAX_S = 8.0 # uma entrada nunca passa disso (gameplay contínuo quase não tem corte de plano)
+COARSE_STEP_S = 20.0 # trecho de "volta" da varredura: resumido
+PAUSE_S = 1.2 # pausa na fala que fecha a entrada (se ela já tem MIN_ENTRY_S)
+MIN_ENTRY_S = 4.0
+FACE_MIN = 3 # expressão abaixo disso (z do rosto) é ruído: fica de fora
+LOUD_LVL, QUIET_LVL = 6, 1 # volume só aparece quando foge do normal (alto ou silêncio)
+PHRASE_CHARS = 32
+SP_WORDS = 25
+COARSE_SP_WORDS = 12
+NORMAL_LVL = 3
+# Rótulos do rosto (reaction.label) → token curto em inglês (as chaves e valores da linha do tempo são em inglês).
+FACE_TOKENS = {"risada": "laugh", "grito": "shout", "susto": "scare", "choque": "shock", "confuso": "confused",
+ "raiva": "anger"}
+
+LEGEND = {
+ "en": ("Timeline (JSON Lines; one entry per moment; seconds of the recording). Keys: t=start, d=duration, "
+ "v=what is on screen (short), sp=speech, literal ([other1] = someone else talking, not the streamer), "
+ "face=streamer expression.intensity 0-9, lvl=loudness vs. the stream's normal 0-9 (3=normal), "
+ "chat=messages|top emote×count|most repeated message, out=1 → OUTSIDE the clip (the viewer does NOT see it). "
+ "Missing key = nothing notable."),
+ "pt": ("Linha do tempo (JSON Lines; uma entrada por instante; segundos da gravação). Chaves: t=início, d=duração, "
+ "v=o que está na tela (curto), sp=fala literal ([other1] = outra pessoa falando, não o streamer), "
+ "face=expressão do streamer.intensidade 0-9, lvl=volume em relação ao normal da live 0-9 (3=normal), "
+ "chat=mensagens|emote mais usado×vezes|mensagem mais repetida, out=1 → FORA do corte (o espectador NÃO vê). "
+ "Chave ausente = nada a notar."),
+}
+
+
+@dataclass
+class Evidence:
+ """Tudo que a linha do tempo de uma janela usa. `face` = (segundo, token, intensidade z); `scenes` = (t, texto)."""
+ words: list[Word]
+ chat: list[ChatMessage]
+ loudness: list[float | None]
+ face: list[tuple[int, str, float]] = field(default_factory=list)
+ scenes: list[tuple[float, str]] = field(default_factory=list)
+
+
+# ---------------------------------------------------------------- coleta (motor → Evidence)
+def face_marks(engine: "Engine", session: dict, lo: float, hi: float) -> list[tuple[int, str, float]]:
+ """Expressões do streamer por segundo em [lo, hi], pelo que o rastreio já gravou (sem rodar nada novo).
+ Sem câmera, rastreio desligado ou plano B sem expressões: lista vazia."""
+ try:
+ from . import reaction
+ from .face import OpenSeeFaceTracker
+
+ face = engine.face
+ if not face.enabled or not face.has_cam(session):
+ return []
+ if face.session_backend(session["id"]) == OpenSeeFaceTracker.name:
+ return []
+ seconds = face.dense(session["id"], max(0.0, lo - 240), hi)
+ if not any(s.smile is not None for s in seconds if lo <= s.t <= hi):
+ return []
+ zs = reaction.channel_z(seconds, face.params)
+ signal = reaction.reaction_signal(seconds, params=face.params)
+ marks = []
+ for second, z, value in zip(seconds, zs, signal):
+ if not lo <= second.t <= hi or z is None:
+ continue
+ label = reaction.label(second, z, face.params)
+ if label and label != "neutro":
+ marks.append((int(second.t), FACE_TOKENS.get(label, label), float(value or 0.0)))
+ return marks
+ except Exception as exc: # noqa: BLE001 - sem rosto a linha do tempo segue sem `face`
+ log.info("rosto para a linha do tempo indisponível: %s", exc)
+ return []
+
+
+def scene_lines(engine: "Engine", session_id: int, lo: float, hi: float) -> list[tuple[float, str]]:
+ """Frases de tela guardadas (varredura e analista). Do analista primeiro quando os dois descreveram o mesmo t."""
+ rows = engine.db.all("SELECT t, source, text FROM scene_notes WHERE session_id = ? AND t >= ? AND t <= ? ORDER BY t",
+ session_id, lo, hi)
+ rows.sort(key=lambda r: (r["t"], r["source"] != "analyst"))
+ return [(float(r["t"]), r["text"]) for r in rows]
+
+
+def save_scene_lines(engine: "Engine", session_id: int, source: str, lines: object,
+ tiles: list[float]) -> int:
+ """Grava as frases `v` que a IA escreveu para cada quadro (`n` = nº do quadro, 1 = primeiro). Devolve quantas."""
+ if not isinstance(lines, list) or not tiles:
+ return 0
+ rows = []
+ for item in lines:
+ if not isinstance(item, dict):
+ continue
+ try:
+ n = int(item.get("n"))
+ except (TypeError, ValueError):
+ continue
+ text = " ".join(str(item.get("v") or "").split())[:120]
+ if 1 <= n <= len(tiles) and text:
+ rows.append((session_id, round(tiles[n - 1], 1), source, text, _now()))
+ if rows:
+ engine.db.many("INSERT INTO scene_notes (session_id, t, source, text, created_at) VALUES (?, ?, ?, ?, ?)"
+ " ON CONFLICT (session_id, t, source) DO UPDATE SET text = excluded.text", rows)
+ return len(rows)
+
+
+def _now() -> str:
+ from .db import now
+
+ return now()
+
+
+def collect(engine: "Engine", session: dict, tl: dict, lo: float, hi: float) -> Evidence:
+ """Evidência da janela [lo, hi] a partir da linha do tempo já carregada (`Engine.load_timeline`)."""
+ return Evidence(words=[w for w in tl["words"] if lo - 1 <= w.start <= hi + 1],
+ chat=[m for m in tl["chat"] if lo - 1 <= m.t <= hi + 1],
+ loudness=tl["loudness"], face=face_marks(engine, session, lo, hi),
+ scenes=scene_lines(engine, session["id"], lo, hi))
+
+
+# ---------------------------------------------------------------- entradas
+def boundaries(words: list[Word], lo: float, hi: float, step: float = STEP_MAX_S, split_speech: bool = True) -> list[float]:
+ """Onde cada entrada começa: pausa na fala, troca de quem fala ou no máximo `step` segundos.
+ `split_speech=False` (resumo): só pelo passo."""
+ cuts = [lo]
+ last_end: float | None = None
+ last_sp: str | None = None
+ for w in sorted((w for w in words if lo <= w.start < hi), key=lambda w: w.start):
+ while w.start - cuts[-1] > step:
+ cuts.append(cuts[-1] + step)
+ cur = cuts[-1]
+ speaker = w.speaker or "streamer"
+ new_speaker = last_sp is not None and speaker != last_sp
+ pause = last_end is not None and w.start - last_end > PAUSE_S and w.start - cur >= MIN_ENTRY_S
+ if ((split_speech and (new_speaker or pause)) or w.start - cur >= step) and w.start > cur + 0.5:
+ cuts.append(w.start)
+ last_end, last_sp = w.end, speaker
+ while hi - cuts[-1] > step:
+ cuts.append(cuts[-1] + step)
+ if hi - cuts[-1] < 0.5 and len(cuts) > 1:
+ cuts.pop()
+ return cuts + [hi]
+
+
+def _speech(words: list[Word], limit: int) -> str:
+ parts: list[str] = []
+ current = None
+ count = 0
+ for w in words:
+ speaker = w.speaker or "streamer"
+ if speaker != current:
+ if speaker != "streamer":
+ parts.append(f"[{speaker}]")
+ elif current is not None:
+ parts.append("[streamer]")
+ current = speaker
+ parts.append(w.word.strip())
+ count += 1
+ if count >= limit:
+ parts.append("…")
+ break
+ return " ".join(p for p in parts if p)
+
+
+def _chat(messages: list[ChatMessage], coarse: bool) -> str:
+ if not messages:
+ return ""
+ emotes = Counter(e for m in messages for e in set(m.emotes))
+ top = ""
+ if emotes:
+ name, n = emotes.most_common(1)[0]
+ top = f"{name}×{n}"
+ phrase = ""
+ if not coarse:
+ # Só o que o chat REPETE (reação coletiva); resposta a alguém (@) e comando (!) não contam.
+ texts = Counter(re.sub(r"\s+", " ", m.text.strip().lower())[:PHRASE_CHARS] for m in messages
+ if m.text.strip() and not m.text.lstrip().startswith(("@", "!")))
+ if texts:
+ text, n = texts.most_common(1)[0]
+ if n >= 2:
+ phrase = text
+ return "|".join((str(len(messages)), top, phrase)).rstrip("|")
+
+
+def _level(loudness: list[float | None], a: float, b: float, normal: float | None) -> int | None:
+ values = [v for v in loudness[max(0, int(a)): max(int(a) + 1, int(b))] if v is not None]
+ if not values or normal is None:
+ return None
+ return max(0, min(9, round(NORMAL_LVL + (max(values) - normal) / 4)))
+
+
+def normal_level(loudness: list[float | None], lo: float, hi: float) -> float | None:
+ """Volume "normal" da live em volta da janela (mediana dos segundos com som)."""
+ values = [v for v in loudness[max(0, int(lo) - 120): int(hi) + 1] if v is not None and v > -60]
+ return statistics.median(values) if values else None
+
+
+def entries(ev: Evidence, lo: float, hi: float, *, coarse: bool = False, clip: tuple[float, float] | None = None,
+ sp_words: int | None = None) -> list[dict]:
+ """Entradas da janela. `coarse` = resumo (passo maior, fala curta, sem rosto/volume baixos). `clip` = (início,
+ fim) do corte: as entradas fora dele saem marcadas `out: 1` (prompt do juiz: o espectador não vê) e nenhuma
+ entrada atravessa o início ou o fim do corte."""
+ if clip is not None:
+ start, end = clip
+ out_items: list[dict] = []
+ for a, b, outside in ((lo, min(start, hi), True), (max(lo, start), min(end, hi), False), (max(lo, end), hi, True)):
+ if b - a < 0.3:
+ continue
+ for item in entries(ev, a, b, coarse=coarse, sp_words=sp_words):
+ out_items.append({"t": item.pop("t"), "d": item.pop("d"), **({"out": 1} if outside else {}), **item})
+ return out_items
+ step = COARSE_STEP_S if coarse else STEP_MAX_S
+ limit = sp_words or (COARSE_SP_WORDS if coarse else SP_WORDS)
+ cuts = boundaries(ev.words, lo, hi, step, split_speech=not coarse)
+ normal = normal_level(ev.loudness, lo, hi)
+ out: list[dict] = []
+ used_scenes: set[int] = set()
+ for a, b in zip(cuts, cuts[1:]):
+ if b - a < 0.3:
+ continue
+ item: dict = {"t": int(round(a)), "d": max(1, int(round(b - a)))}
+ scenes = [(i, text) for i, (t, text) in enumerate(ev.scenes) if a <= t < b and i not in used_scenes]
+ if scenes:
+ used_scenes.update(i for i, _ in scenes[:2])
+ item["v"] = " / ".join(dict.fromkeys(text for _, text in scenes[:2]))
+ words = [w for w in ev.words if a <= w.start < b]
+ if words:
+ item["sp"] = _speech(words, limit)
+ marks = [m for m in ev.face if a <= m[0] < b]
+ if marks:
+ _t, token, value = max(marks, key=lambda m: m[2])
+ intensity = max(0, min(9, round(value)))
+ if intensity >= (FACE_MIN + 1 if coarse else FACE_MIN):
+ item["face"] = f"{token}.{intensity}"
+ level = _level(ev.loudness, a, b, normal)
+ if level is not None and (level >= LOUD_LVL or level <= QUIET_LVL):
+ item["lvl"] = level
+ chat = _chat([m for m in ev.chat if a <= m.t < b], coarse)
+ if chat:
+ item["chat"] = chat
+ out.append(item)
+ return out
+
+
+def render(header: dict, items: list[dict]) -> str:
+ dump = lambda obj: json.dumps(obj, ensure_ascii=False, separators=(",", ":")) # noqa: E731
+ return "\n".join([dump(header), *(dump(i) for i in items)])
+
+
+def build(ev: Evidence, lo: float, hi: float, header: dict, *, budget_chars: int = 9000,
+ coarse_until: float | None = None, clip: tuple[float, float] | None = None) -> str:
+ """JSONL da janela dentro do orçamento de caracteres: se passar, a fala de cada entrada encurta (25 → 12 → 6
+ palavras) e, por último, o trecho mais antigo vira resumo. `coarse_until` = a parte [lo, coarse_until) já sai
+ resumida (a "volta" da varredura)."""
+ for sp_words in (SP_WORDS, COARSE_SP_WORDS, 6):
+ items: list[dict] = []
+ split = coarse_until if coarse_until is not None and lo < coarse_until < hi else None
+ if split is not None:
+ items += entries(ev, lo, split, coarse=True, clip=clip)
+ items += entries(ev, split, hi, clip=clip, sp_words=sp_words)
+ else:
+ items += entries(ev, lo, hi, clip=clip, sp_words=sp_words)
+ text = render(header, items)
+ if len(text) <= budget_chars:
+ return text
+ return text[:budget_chars].rsplit("\n", 1)[0]
+
+
+def legend(lang: str) -> str:
+ return LEGEND["en" if lang == "en" else "pt"]
diff --git a/clipper/app/worker.py b/clipper/app/worker.py
index d620ac0..c0a5770 100644
--- a/clipper/app/worker.py
+++ b/clipper/app/worker.py
@@ -29,7 +29,8 @@ from pathlib import Path
import httpx
from . import capture as capture_quality
-from . import clip_delete, layout, media
+from . import clip_delete, context_judge, layout, media, timeline
+from . import roles as roles_module
from .chat import ChatReader
from .config import REPO_ROOT, Settings
from .db import Database, loads, now
@@ -37,7 +38,7 @@ from .face import FaceService
from .hashtags import build_caption, split_hashtags
from .hashtags import compose as compose_hashtags
from .intel import Intel
-from .judge import Judge, JudgeError, analysis_block, build_prompt
+from .judge import (Judge, JudgeError, analysis_block, build_context_prompt, build_prompt, build_timeline_prompt)
from .scoring import ChatMessage, Params, Word, find_moments, overlaps
from .sources import Source, parse_source
from .speakers import SpeakerService, dump_words, parse_words
@@ -45,6 +46,10 @@ from .subtitles import build_ass, phrases
log = logging.getLogger("cenaforge_clipper")
LIVE_WINDOW_S = 900 # ao vivo, pontua só os últimos 15 min (o que veio antes já foi decidido)
+# Orçamento de caracteres da linha do tempo JSON por papel (~4 caracteres por token).
+ANALYST_TIMELINE_CHARS = 9000
+EDITOR_TIMELINE_CHARS = 7000
+JUDGE_TIMELINE_CHARS = 6000
def rel(path: Path) -> str:
@@ -339,9 +344,18 @@ class Engine:
def __init__(self, settings: Settings, db: Database, judge: Judge | None = None, voice: VoiceClient | None = None):
self.settings, self.db = settings, db
saved = {r["key"]: r["value"] for r in db.all("SELECT key, value FROM settings")}
- self.judge = judge or Judge(saved.get("judge_provider", settings.judge_provider),
- saved.get("judge_model", settings.judge_model), settings.data_dir / "judge",
- saved.get("judge_analyst_model", ""))
+ if judge is None:
+ # Equipe de IA: papéis gravados em `judge.roles`; sem eles, a configuração antiga vira a de todos os papéis
+ # (migração automática, gravada já na subida para ficar explícita no banco).
+ roles = roles_module.from_settings(saved, settings.judge_provider, settings.judge_model)
+ judge = Judge(saved.get("judge_provider", settings.judge_provider),
+ saved.get("judge_model", settings.judge_model), settings.data_dir / "judge",
+ saved.get("judge_analyst_model", ""), roles=roles)
+ if roles_module.SETTINGS_KEY not in saved:
+ db.run("INSERT INTO settings (key, value) VALUES (?, ?) ON CONFLICT (key) DO UPDATE SET value = excluded.value",
+ roles_module.SETTINGS_KEY, json.dumps(judge.roles, ensure_ascii=False))
+ self.judge = judge
+ self.judge.meter = self.record_ai_call # medição por chamada (F0): tabela ai_calls
self.min_score = float(saved.get("judge_min_score", settings.judge_min_score))
self.voice = voice or VoiceClient(settings.voice_url, settings.voice_key, settings.language)
self.params = Params()
@@ -513,19 +527,44 @@ class Engine:
self.stop_event.wait(10)
# ---------- juiz (configurável pelo painel, sem reiniciar)
- def judge_config(self) -> dict:
- return self.judge.describe() | {"minScore": self.min_score, "options": dict(self.intel.opts),
- "lastScanError": self.intel.last_scan_error}
+ def judge_config(self, full: bool = False) -> dict:
+ """Configuração da Equipe de IA. `full` (GET /v1/judge) acrescenta as instruções padrão de cada papel (texto
+ grande, só leitura no painel) e os nomes das checagens do juiz."""
+ out = self.judge.describe() | {"minScore": self.min_score, "options": dict(self.intel.opts),
+ "lastScanError": self.intel.last_scan_error}
+ if isinstance(out.get("roles"), dict) and "scan" in out["roles"]:
+ out["roles"]["scan"]["enabled"] = bool(self.intel.opts.get("scanEnabled", True)) # liga/desliga = varredura
+ if full:
+ out["roleDefaults"] = self.judge.default_instructions()
+ out["checks"] = [{"id": c, "label": roles_module.CHECK_NAMES[c]} for c in roles_module.CHECKS]
+ return out
- def set_judge_config(self, provider: str, model: str, min_score: float, analyst_model: str | None = None) -> dict:
+ def set_judge_config(self, provider: str, model: str, min_score: float, analyst_model: str | None = None,
+ roles: dict | None = None) -> dict:
if not 0 <= min_score <= 10:
raise JudgeError("a nota mínima vai de 0 a 10")
- self.judge.configure(provider, model, analyst_model)
+ self.judge.configure(provider, model, analyst_model, roles)
+ scan = (roles or {}).get("scan") if isinstance(roles, dict) else None
+ if isinstance(scan, dict) and isinstance(scan.get("enabled"), bool):
+ self.intel.set_options({"scanEnabled": scan["enabled"]}) # o cartão da varredura liga/desliga a varredura
self.min_score = float(min_score)
rows = [("judge_provider", self.judge.provider), ("judge_model", self.judge.model), ("judge_min_score", str(self.min_score)),
- ("judge_analyst_model", self.judge.analyst_model)]
+ ("judge_analyst_model", self.judge.analyst_model),
+ (roles_module.SETTINGS_KEY, json.dumps(self.judge.roles, ensure_ascii=False))]
self.db.many("INSERT INTO settings (key, value) VALUES (?, ?) ON CONFLICT (key) DO UPDATE SET value = excluded.value", rows)
- return self.judge_config()
+ return self.judge_config(full=True)
+
+ def record_ai_call(self, record: dict) -> None:
+ """Uma linha em `ai_calls` por tentativa de chamada de IA (medição F0; relatório em GET /v1/judge/report)."""
+ self.db.run(
+ "INSERT INTO ai_calls (at, role, purpose, provider, model, ok, error, ms, system_chars, prompt_chars, images,"
+ " image_bytes, tokens_in, tokens_out, tokens_cached, session_id, clip_id, mode)"
+ " VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)",
+ now(), record.get("role", ""), record.get("purpose", ""), record.get("provider", ""), record.get("model", ""),
+ int(bool(record.get("ok"))), record.get("error"), record.get("ms"), record.get("systemChars"),
+ record.get("promptChars"), record.get("images"), record.get("imageBytes"), record.get("tokensIn"),
+ record.get("tokensOut"), record.get("tokensCached"), record.get("session_id"), record.get("clip_id"),
+ record.get("mode"))
# ---------- sessões
def start_session(self, url: str, channel_id: str | None = None, language: str | None = None) -> int:
@@ -723,8 +762,8 @@ class Engine:
def rel(path: Path) -> str:
return rel(path)
- def grab_frame(self, segments: list[tuple[Path, float, float]], t: float, out_file: Path) -> Path:
- return media.grab_frame(self.settings.ffmpeg or "ffmpeg", segments, t, out_file)
+ def grab_frame(self, segments: list[tuple[Path, float, float]], t: float, out_file: Path, width: int = 768) -> Path:
+ return media.grab_frame(self.settings.ffmpeg or "ffmpeg", segments, t, out_file, width)
# ---------- análise dos blocos (volume + transcrição)
def _analysis_loop(self) -> None:
@@ -896,48 +935,83 @@ class Engine:
# A ação vem antes do comentário: a IA vê `backtrackS` para trás (transcrição + frames) e pode recuar.
lo = max(0.0, clip["start_s"] - dur["backtrackS"])
hi = min(tl["duration"], clip["end_s"] + 15)
+ # Fonte em inglês: os juízes trabalham em inglês e devolvem também o português do painel (IDIOMAS.md).
+ lang = self.intel.lang(session)
+ # Linha do tempo JSON (novo) ou transcrição + chat + frames soltos (antigo, `timelineJson` desligado).
+ use_timeline = bool(self.intel.opts.get("timelineJson", True))
+ analyst_on = self.judge.role_enabled("analyst")
+ # Imagens como escolhido no analista (sem analista, o editor recebe as mesmas); formato antigo = soltos.
+ image_mode = self.judge.roles["analyst"].get("images", "mosaic") if use_timeline else "frames"
# Quadros espalhados de um pouco antes do candidato até o fim da reação: o analista vê a sequência.
# 6 quadros; 8 quando o trecho passa de 80 s (cortes de 60–90 s), para não ficar > 20 s entre quadros.
f_lo = max(lo, clip["start_s"] - 20)
- n_frames = 8 if hi - f_lo > 80 else 6
+ n_frames = 8 if hi - f_lo > 80 or image_mode == "mosaic" else 6
times = [f_lo + (hi - f_lo) * k / (n_frames - 1) for k in range(n_frames)]
- frames = self.intel.frames(session, times, f"clip{clip['id']}")
- # Fonte em inglês: os juízes trabalham em inglês e devolvem também o português do painel (IDIOMAS.md).
- lang = self.intel.lang(session)
- prompt = build_prompt(streamer, session["platform"], clip["start_s"], clip["end_s"], clip["peak_s"],
- tl["words"], tl["chat"], heuristic, session["title"], context=self.intel.context(session),
- frames=frames, backtrack_s=dur["backtrackS"], min_s=dur["minS"], max_s=dur["maxS"],
- face=self.face.summary(session, lo, hi), lang=lang)
- analysis = None
- try:
- # Dois juízes: o ANALISTA (vê os frames) diz o que aconteceu; o EDITOR decide e escreve a partir disso.
+ images, tiles, mosaic = self.intel.visual(session, times, f"clip{clip['id']}", image_mode)
+ mode = ("timeline" if use_timeline else "legacy") + f"+{'mosaic' if mosaic else image_mode}"
+ min_len = layout.min_target({"duration": dur})
+ with self.judge.scope(session_id=session["id"], clip_id=clip["id"], mode=mode):
+ if use_timeline:
+ prompt = build_timeline_prompt(
+ streamer, session["platform"], clip["start_s"], clip["end_s"], clip["peak_s"], heuristic,
+ context=self.intel.context(session, lean=True), timeline_text=self._timeline_text(session, tl, lo, hi),
+ tiles=tiles, mosaic=mosaic, lo=lo, hi=hi, min_s=dur["minS"], max_s=dur["maxS"], lang=lang)
+ else:
+ prompt = build_prompt(streamer, session["platform"], clip["start_s"], clip["end_s"], clip["peak_s"],
+ tl["words"], tl["chat"], heuristic, session["title"],
+ context=self.intel.context(session), frames=list(zip(tiles, images)),
+ backtrack_s=dur["backtrackS"], min_s=dur["minS"], max_s=dur["maxS"],
+ face=self.face.summary(session, lo, hi), lang=lang)
+ analysis = None
try:
- analysis = self.judge.analyze(prompt, [p for _, p in frames], lang=lang)
+ # ANALISTA (vê a tela) diz o que aconteceu; o EDITOR decide e escreve a partir disso.
+ if analyst_on:
+ try:
+ analysis = self.judge.analyze(prompt, images, lang=lang)
+ except (JudgeError, json.JSONDecodeError, KeyError, ValueError) as exc:
+ log.warning("analista falhou no corte %s: %s (editor segue sozinho)", clip["id"], exc)
+ if analysis:
+ # O que o analista viu em cada quadro vira o `v` da linha do tempo (editor e juiz reaproveitam).
+ timeline.save_scene_lines(self, session["id"], "analyst", analysis.pop("lines", None), tiles)
+ if use_timeline and analysis:
+ # Editor: só texto, linha do tempo do trecho (da ação, se o analista a viu antes) até o fim.
+ try:
+ act = float(analysis.get("action_start_s"))
+ except (TypeError, ValueError):
+ act = clip["start_s"]
+ e_lo = max(lo, min(clip["start_s"], act if lo <= act <= hi else clip["start_s"]) - 15)
+ editor_prompt = build_timeline_prompt(
+ streamer, session["platform"], clip["start_s"], clip["end_s"], clip["peak_s"], heuristic,
+ context=self.intel.context(session, lean=True),
+ timeline_text=self._timeline_text(session, tl, e_lo, hi, EDITOR_TIMELINE_CHARS),
+ tiles=[], mosaic=False, lo=lo, hi=hi, min_s=dur["minS"], max_s=dur["maxS"], lang=lang,
+ analysis=analysis)
+ else:
+ editor_prompt = prompt + ("\n\n" + analysis_block(analysis, lang) if analysis else "")
+ # Sem análise, o editor recebe as imagens; com análise, só texto (mais barato, a tela já foi lida).
+ verdict = self.judge.judge(editor_prompt, clip["start_s"], clip["end_s"], [] if analysis else images,
+ lo=lo, hi=hi, min_s=min_len, max_s=dur["maxS"], lang=lang)
+ # Corte manual: quem decidiu foi você; o juiz só escreve título e legenda (e não mexe no trecho).
+ manual = clip["source"] == "manual"
+ keep = manual or (verdict.keep and verdict.score >= self.min_score)
+ if manual:
+ verdict = verdict.__class__(**{**verdict.__dict__, "start_s": clip["start_s"], "end_s": clip["end_s"]})
+ update |= {"title": verdict.title or update["title"], "caption": verdict.caption,
+ "hashtags": list(verdict.hashtags),
+ "status": "pending" if keep else "discarded",
+ "start_s": verdict.start_s, "end_s": verdict.end_s,
+ "judge": {"model": verdict.model, "keep": verdict.keep, "score": verdict.score,
+ "reason": verdict.reason, "analysis": analysis,
+ # Fonte em inglês: título/legenda/motivo em português (só o painel lê).
+ **({"pt": verdict.pt} if verdict.pt else {}),
+ "analystModel": self.judge.role_model("analyst") if analysis else None}}
+ if keep and self.judge.role_enabled("judge"):
+ # JUIZ de contexto: o corte faz sentido sozinho? (só texto, só o que vai no corte final)
+ self._context_check(session, clip, tl, update, verdict.score, analysis, lo, hi, min_len,
+ float(dur["maxS"]), lang, manual)
except (JudgeError, json.JSONDecodeError, KeyError, ValueError) as exc:
- log.warning("analista falhou no corte %s: %s (editor segue sozinho)", clip["id"], exc)
- editor_prompt = prompt + ("\n\n" + analysis_block(analysis, lang) if analysis else "")
- # Sem análise, o editor recebe os frames; com análise, só texto (mais barato, a tela já foi lida).
- verdict = self.judge.judge(editor_prompt, clip["start_s"], clip["end_s"],
- [] if analysis else [p for _, p in frames],
- lo=lo, hi=hi, min_s=layout.min_target({"duration": dur}), max_s=dur["maxS"],
- lang=lang)
- # Corte manual: quem decidiu foi você; o juiz só escreve título e legenda (e não mexe no trecho).
- manual = clip["source"] == "manual"
- keep = manual or (verdict.keep and verdict.score >= self.min_score)
- if manual:
- verdict = verdict.__class__(**{**verdict.__dict__, "start_s": clip["start_s"], "end_s": clip["end_s"]})
- update |= {"title": verdict.title or update["title"], "caption": verdict.caption,
- "hashtags": list(verdict.hashtags),
- "status": "pending" if keep else "discarded",
- "start_s": verdict.start_s, "end_s": verdict.end_s,
- "judge": {"model": verdict.model, "keep": verdict.keep, "score": verdict.score,
- "reason": verdict.reason, "analysis": analysis,
- # Fonte em inglês: título/legenda/motivo em português (só o painel lê).
- **({"pt": verdict.pt} if verdict.pt else {}),
- "analystModel": (self.judge.analyst_model or self.judge.model) if analysis else None}}
- except (JudgeError, json.JSONDecodeError, KeyError, ValueError) as exc:
- # Falha do juiz não perde o momento: segue com a heurística e registra o motivo.
- update["judge"] = {"error": str(exc)[:300]}
+ # Falha do juiz não perde o momento: segue com a heurística e registra o motivo.
+ update["judge"] = {"error": str(exc)[:300]}
if update["status"] == "pending":
# O juiz pode ter recuado o trecho para cima de um corte já mantido: confere de novo (todas as origens).
kept = self.db.all(f"SELECT id, session_id, status, peak_s, start_s, end_s FROM clips WHERE session_id = ? "
@@ -973,7 +1047,8 @@ class Engine:
# Novo veredito: o projeto que a IA tinha gerado é refeito no render (o que você editou fica).
self.db.run("DELETE FROM edits WHERE clip_id = ? AND origin = 'ai'", clip["id"])
# Fonte em inglês: a fala do corte em português para o painel (falha não segura o corte).
- self.translate_clip(clip["id"], update["start_s"], update["end_s"])
+ with self.judge.scope(session_id=session["id"], clip_id=clip["id"]):
+ self.translate_clip(clip["id"], update["start_s"], update["end_s"])
verdict_info = update["judge"] or {}
if clip["source"] != "manual" and "score" in verdict_info:
# Aprendizado fraco pela IA (o forte vem da sua aprovação/rejeição no painel).
@@ -982,6 +1057,77 @@ class Engine:
elif verdict_info["score"] >= 7:
self.intel.learn_from_clip(clip, positive=True, factor=0.5)
+ def _timeline_text(self, session: dict, tl: dict, lo: float, hi: float, budget: int = ANALYST_TIMELINE_CHARS,
+ clip: tuple[float, float] | None = None, header: dict | None = None) -> str:
+ """Linha do tempo JSON de [lo, hi] (app/timeline.py) com o que já existe: fala+falante, chat, rosto, volume
+ e as frases de tela guardadas."""
+ ev = timeline.collect(self, session, tl, lo, hi)
+ head = header or {"win": [int(lo), int(hi)], "src": self.intel.lang(session)}
+ return timeline.build(ev, lo, hi, head, budget_chars=budget, clip=clip)
+
+ def _context_check(self, session: dict, clip: dict, tl: dict, update: dict, score: float, analysis: dict | None,
+ lo: float, hi: float, min_len: float, max_len: float, lang: str, manual: bool) -> None:
+ """JUIZ de contexto sobre o corte que o editor manteve. O código decide pelas respostas (context_judge.decide):
+ aprova (talvez com frase de contexto na tela), ajusta o trecho e confere UMA vez de novo, ou descarta com o
+ motivo em português. Falha da IA aqui não muda a decisão do editor (só registra o erro)."""
+ from .editor import pick_hook
+
+ conf = self.judge.roles["judge"]
+ game, profile = self.intel.session_game(session)
+ summary = str((profile or {}).get("summary") or "")
+ game_line = (summary.split(". ")[0] if summary else "")[:160]
+ story = str((analysis or {}).get("what_happened") or "")
+ opening, _ = pick_hook((analysis or {}).get("hook"), update["title"])
+ streamer = self.streamer_name(session)
+
+ def ask(start: float, end: float) -> tuple[dict, str]:
+ # O corte + 20 s antes e 15 s depois (marcados out=1): o juiz nota o começo ou o desfecho que ficaram de fora.
+ t_lo = max(0.0, start - context_judge.OUT_BEFORE_S)
+ t_hi = min(tl["duration"], end + context_judge.OUT_AFTER_S)
+ text = self._timeline_text(session, tl, t_lo, t_hi, JUDGE_TIMELINE_CHARS, clip=(start, end),
+ header={"clip": [int(start), int(end)], "src": lang})
+ prompt = build_context_prompt(streamer=streamer, game=game, game_line=game_line, start_s=start, end_s=end,
+ title=update["title"], caption=update["caption"], opening=opening, story=story,
+ timeline_text=text, lo=lo, hi=hi, min_s=min_len, max_s=max_len, lang=lang)
+ result = self.judge.check_context(prompt, lang=lang)
+ return result, self.judge.responder()
+
+ judge_info = update["judge"]
+ start, end = update["start_s"], update["end_s"]
+ limits = {"lo": lo, "hi": hi, "min_s": min_len, "max_s": max_len, "conf": conf, "score": score,
+ "min_score": self.min_score, "manual": manual}
+ try:
+ result, model = ask(start, end)
+ decision = context_judge.decide(result, start_s=start, end_s=end, **limits)
+ info = context_judge.view(result, decision, model)
+ if decision.action == "adjust" and decision.window:
+ # Trecho novo dentro dos limites: o juiz confere UMA vez de novo (sem novo ajuste).
+ ns, ne = decision.window
+ result2, model2 = ask(ns, ne)
+ second = context_judge.decide(result2, start_s=ns, end_s=ne, allow_fix=False, **limits)
+ first = info
+ info = context_judge.view(result2, second, model2)
+ info["first"] = {k: first[k] for k in ("viewerSummary", "checks", "failedCritical", "reasonPt", "pt")}
+ info["window"] = [round(ns, 2), round(ne, 2)]
+ if second.action == "approve":
+ info["decision"] = "adjust"
+ info["contextLine"] = second.context_line or decision.context_line
+ info["reasonPt"] = f"{decision.reason_pt} Conferido de novo: aprovado."
+ update["start_s"], update["end_s"] = round(ns, 2), round(ne, 2)
+ else:
+ info["decision"] = "discard"
+ info["contextLine"] = ""
+ info["reasonPt"] = (f"Descartado pelo juiz depois do ajuste para {ns:.0f}–{ne:.0f}s: "
+ f"{second.reason_pt.removeprefix('Descartado pelo juiz: ')}")
+ if info["decision"] == "discard":
+ update["status"] = "discarded"
+ judge_info["discardedBy"] = "context"
+ judge_info["context"] = info
+ log.info("juiz de contexto no corte %s: %s (%s)", clip["id"], info["decision"], info["reasonPt"][:160])
+ except (JudgeError, json.JSONDecodeError, KeyError, ValueError, TypeError) as exc:
+ judge_info["context"] = {"error": str(exc)[:300]}
+ log.warning("juiz de contexto falhou no corte %s: %s (fica a decisão do editor)", clip["id"], exc)
+
def translate_clip(self, clip_id: int, lo: float | None = None, hi: float | None = None,
force: bool = False) -> dict | None:
"""Fonte em inglês (doc/clipador/IDIOMAS.md): a fala de [lo, hi] (padrão: o trecho do corte) em frases com
diff --git a/clipper/tests/conftest.py b/clipper/tests/conftest.py
index db5b1cb..97df794 100644
--- a/clipper/tests/conftest.py
+++ b/clipper/tests/conftest.py
@@ -1,8 +1,29 @@
"""Configuração comum dos testes do Clipador."""
+import subprocess
+
import pytest
import app.ai_settings as ai_settings_module
import app.intel as intel_module
+import app.judge as judge_module
+
+
+class _NoRealCli:
+ """`subprocess` do juiz nos testes: igual ao de verdade, mas `run` recusa (nenhuma CLI de IA roda e gasta a cota
+ do dono — juízes falsos que não cobrem um papel, como o juiz de contexto, caem no caminho de falha da IA).
+ Quem testa as CLIs (test_ai_fallback) troca `run` por um falso."""
+
+ def __getattr__(self, name):
+ return getattr(subprocess, name)
+
+ @staticmethod
+ def run(*_args, **_kwargs):
+ raise OSError("CLI de IA bloqueada nos testes")
+
+
+@pytest.fixture(autouse=True)
+def _no_real_ai_cli(monkeypatch):
+ monkeypatch.setattr(judge_module, "subprocess", _NoRealCli())
@pytest.fixture(autouse=True)
diff --git a/clipper/tests/test_context_judge.py b/clipper/tests/test_context_judge.py
new file mode 100644
index 0000000..e227589
--- /dev/null
+++ b/clipper/tests/test_context_judge.py
@@ -0,0 +1,257 @@
+"""JUIZ de contexto (doc/clipador/EQUIPE-IA.md): decisão pelo código (aprovar / ajustar e conferir uma vez / frase de
+contexto / descartar), o fluxo no motor, a linha do tempo JSON dentro do orçamento e o mosaico de quadros."""
+import json
+import shutil
+import subprocess
+from pathlib import Path
+
+import pytest
+
+from app import context_judge, editor_api, media, timeline
+from app import roles as roles_module
+from app.judge import Judge, Verdict
+from app.scoring import ChatMessage, Word
+
+from .test_render_and_duplicates import add_clip
+from .test_sources_and_api import auth, env, seed_session # noqa: F401 - fixture reaproveitada
+
+FFMPEG = shutil.which("ffmpeg")
+FFPROBE = shutil.which("ffprobe")
+
+
+def result(failed=(), fix=None, line="", reason="motivo"):
+ return {"viewer_summary": "resumo", "confidence": 0.8, "reason": reason, "pt": {"reason": reason},
+ "checks": {c: {"ok": c not in failed, "t": None, "why": ""} for c in roles_module.CHECKS},
+ "fix": {"start_s": None, "end_s": None, "context_line": line, **(fix or {})}}
+
+
+LIMITS = {"start_s": 200.0, "end_s": 265.0, "lo": 80.0, "hi": 280.0, "min_s": 61.0, "max_s": 90.0}
+CONF = roles_module.default_roles()["judge"]
+
+
+# ---------------------------------------------------------------- decisão pelo código
+def test_all_checks_ok_approves():
+ d = context_judge.decide(result(), conf=CONF, score=8, min_score=6, **LIMITS)
+ assert d.action == "approve" and d.failed == [] and d.window is None and d.score_after == 8
+
+
+def test_missing_setup_with_fix_adjusts_inside_the_limits():
+ d = context_judge.decide(result(["setup"], {"start_s": 150}), conf=CONF, score=8, **LIMITS)
+ assert d.action == "adjust" and d.failed_critical == ["setup"]
+ # Recuou o início para pegar o começo; com máximo de 90 s o fim encolhe (fit_window mantém o início).
+ assert d.window == (150.0, 240.0) and "começo (setup)" in d.reason_pt
+
+
+def test_fix_outside_the_window_is_clamped_and_no_change_means_discard():
+ d = context_judge.decide(result(["payoff"], {"end_s": 999}), conf=CONF, **LIMITS)
+ assert d.action == "adjust" and d.window[1] == 280.0 # nunca passa do limite
+ same = context_judge.decide(result(["payoff"], {"end_s": 265.2}), conf=CONF, **LIMITS)
+ assert same.action == "discard" # "ajuste" que não muda nada
+
+
+def test_critical_failure_without_fix_discards_with_portuguese_reason():
+ d = context_judge.decide(result(["payoff"], reason="ends before the fight is resolved"), conf=CONF, **LIMITS)
+ assert d.action == "discard" and d.reason_pt.startswith("Descartado pelo juiz: sem desfecho.")
+ no_fix = context_judge.decide(result(["setup"], {"start_s": 150}), conf={**CONF, "allowFix": False}, **LIMITS)
+ assert no_fix.action == "discard"
+
+
+def test_context_line_solves_standalone():
+ d = context_judge.decide(result(["standalone"], line="Tfue tries to talk his way out of a robbery"), conf=CONF,
+ score=8, min_score=6, **LIMITS)
+ assert d.action == "approve" and d.solved_by_line == ["standalone"] and d.context_line.startswith("Tfue")
+ off = context_judge.decide(result(["standalone"], line="Tfue tries"), conf={**CONF, "allowContextLine": False},
+ **LIMITS)
+ assert off.action == "discard"
+ too_long = context_judge.decide(result(["standalone"], line=" ".join(["word"] * 14)), conf=CONF, **LIMITS)
+ assert too_long.action == "discard"
+
+
+def test_non_critical_failures_only_lower_the_score():
+ d = context_judge.decide(result(["strong_open"]), conf=CONF, score=7, min_score=6, **LIMITS)
+ assert d.action == "approve" and d.score_after == 6.5
+ low = context_judge.decide(result(["strong_open", "faithful", "intelligible"]), conf=CONF, score=7, min_score=6,
+ **LIMITS)
+ assert low.action == "discard" and low.score_after == 5.5 and "nota caiu" in low.reason_pt
+ custom = context_judge.decide(result(["strong_open"]), conf={**CONF, "critical": ["strong_open"]}, **LIMITS)
+ assert custom.action == "discard" # as críticas são calibráveis no painel
+
+
+def test_manual_clip_only_warns():
+ d = context_judge.decide(result(["payoff"], {"end_s": 280}), conf=CONF, manual=True, **LIMITS)
+ assert d.action == "warn" and d.window is None and d.reason_pt.startswith("Aviso do juiz")
+
+
+# ---------------------------------------------------------------- fluxo no motor
+class ContextFakeJudge(Judge):
+ """Analista, editor e juiz falsos (nunca chama CLI). `answers` = respostas do juiz, em ordem."""
+
+ def __init__(self, answers, keep=True, score=8.0):
+ super().__init__("codex", "fake", Path("."))
+ self.answers = list(answers)
+ self.keep, self.score_value = keep, score
+ self.context_prompts: list[str] = []
+ self.editor_prompt = ""
+
+ def analyze(self, prompt, images, lang="pt"):
+ return {"situation": "treta", "what_happened": "Ele tenta negociar e leva um tiro.", "screen": "", "speech": "",
+ "chat_meaning": "", "confidence": 0.9, "action_start_s": 270, "reaction_end_s": 330, "hook": "",
+ "lines": [{"n": 1, "v": "streamer aponta rifle para mascarado"}]}
+
+ def judge(self, prompt, start_s, end_s, images=None, lang="pt", **_limits):
+ self.editor_prompt = prompt
+ return Verdict(self.keep, self.score_value, 270.0, 340.0, "Tentou negociar e levou tiro", "c", "r", "fake")
+
+ def check_context(self, prompt, lang="pt"):
+ self.context_prompts.append(prompt)
+ answer = self.answers.pop(0)
+ if isinstance(answer, Exception):
+ raise answer
+ return answer
+
+
+def run_clip(engine, judge, source="chat"):
+ engine.judge = judge
+ # Sem ffmpeg nos blocos falsos: um "mosaico" de um quadro só (em 275 s), que o analista descreve.
+ engine.intel.visual = lambda *_a, **_k: ([Path("mosaico-falso.jpg")], [275.0], True)
+ sid = seed_session(engine)
+ cid = (engine.db.get("SELECT MAX(id) AS n FROM clips")["n"] or 0) + 1
+ add_clip(engine, sid, cid, "candidate", 300, 280, 345, source=source)
+ engine.judge_clip(engine.db.get("SELECT * FROM clips WHERE id = ?", cid))
+ row = engine.db.get("SELECT * FROM clips WHERE id = ?", cid)
+ return row, json.loads(row["judge_json"])
+
+
+def test_engine_approves_and_records_the_context(env): # noqa: F811
+ _client, engine = env
+ row, info = run_clip(engine, ContextFakeJudge([result(line="Tenta negociar com o assaltante")]))
+ assert row["status"] == "pending" and info["context"]["decision"] == "approve"
+ assert info["context"]["contextLine"] == "Tenta negociar com o assaltante"
+ prompt = engine.judge.context_prompts[0]
+ # O juiz vê só o que vai no corte: o trecho e os 20 s antes marcados out=1.
+ assert "Corte que o espectador verá: 270s a 340s" in prompt and '"out":1' in prompt
+ assert "História pretendida (analista): Ele tenta negociar e leva um tiro." in prompt
+ # O que o analista viu no quadro virou o `v` da linha do tempo do editor.
+ assert '"v":"streamer aponta rifle para mascarado"' in engine.judge.editor_prompt
+
+
+def test_engine_adjusts_once_then_approves(env): # noqa: F811
+ _client, engine = env
+ row, info = run_clip(engine, ContextFakeJudge([result(["setup"], {"start_s": 250}), result()]))
+ assert row["status"] == "pending" and (row["start_s"], row["end_s"]) == (250.0, 340.0)
+ ctx = info["context"]
+ assert ctx["decision"] == "adjust" and ctx["window"] == [250.0, 340.0] and ctx["first"]["failedCritical"] == ["setup"]
+ assert len(engine.judge.context_prompts) == 2 and "250s a 340s" in engine.judge.context_prompts[1]
+
+
+def test_engine_adjusts_then_discards_when_still_failing(env): # noqa: F811
+ client, engine = env
+ row, info = run_clip(engine, ContextFakeJudge([result(["payoff"], {"end_s": 355}),
+ result(["payoff"], {"end_s": 360})]))
+ assert row["status"] == "discarded" and info["discardedBy"] == "context"
+ assert info["context"]["decision"] == "discard" and "depois do ajuste" in info["context"]["reasonPt"]
+ assert len(engine.judge.context_prompts) == 2 # confere UMA vez de novo, nunca mais
+ # Descartado pelo juiz fica visível e dá para forçar o render, como o descarte de hoje.
+ forced = client.post("/v1/clips/1/render", headers=auth()).json()
+ assert forced["status"] == "pending" and forced["judge"]["context"]["decision"] == "discard"
+
+
+def test_engine_discard_without_fix_and_judge_failure_keeps_editor(env): # noqa: F811
+ _client, engine = env
+ row, info = run_clip(engine, ContextFakeJudge([result(["standalone"])]))
+ assert row["status"] == "discarded" and info["context"]["failedCritical"] == ["standalone"]
+ from app.judge import JudgeError
+
+ row, info = run_clip(engine, ContextFakeJudge([JudgeError("cota")]))
+ assert row["status"] == "pending" and info["context"] == {"error": "cota"}
+
+
+def test_judge_role_off_and_editor_discard_skip_the_judge(env): # noqa: F811
+ _client, engine = env
+ judge = ContextFakeJudge([result(["payoff"])])
+ judge.roles["judge"]["enabled"] = False
+ row, info = run_clip(engine, judge)
+ assert row["status"] == "pending" and "context" not in info and judge.context_prompts == []
+ kept_out = ContextFakeJudge([result()], keep=False)
+ row, info = run_clip(engine, kept_out)
+ assert row["status"] == "discarded" and kept_out.context_prompts == [] # o editor já descartou
+
+
+def test_manual_clip_is_never_discarded_by_the_judge(env): # noqa: F811
+ _client, engine = env
+ row, info = run_clip(engine, ContextFakeJudge([result(["payoff"], {"end_s": 360})]), source="manual")
+ assert row["status"] == "pending" and info["context"]["decision"] == "warn"
+ assert (row["start_s"], row["end_s"]) == (280.0, 345.0)
+
+
+def test_context_line_becomes_the_opening_text_of_the_edit(env): # noqa: F811
+ _client, engine = env
+ row, _info = run_clip(engine, ContextFakeJudge([result(["setup"], {"start_s": 250}),
+ result(line="Ele tenta negociar com o assaltante")]))
+ session = engine.db.get("SELECT * FROM sessions WHERE id = ?", row["session_id"])
+ project = editor_api.auto_for(engine, row, session)
+ hook = next(o for o in project["overlays"] if o["kind"] == "hook")
+ assert hook["text"] == "Ele tenta negociar com o assaltante"
+ # O ajuste do juiz não é desfeito pelo início da ação do analista (270 s).
+ assert project["cuts"][0]["start"] <= 250.5
+
+
+# ---------------------------------------------------------------- linha do tempo JSON
+def _evidence(seconds=240):
+ words, chat = [], []
+ for t in range(0, seconds, 2):
+ words.append(Word(float(t), t + 1.5, f"palavra{t}", "other1" if 60 <= t < 64 else ""))
+ for t in range(0, seconds, 3):
+ chat.append(ChatMessage(float(t), "KEKW que isso" if t % 2 else "lol", emotes=("KEKW",) if t % 2 else ()))
+ loudness = [-30.0] * seconds
+ loudness[100] = -10.0
+ return timeline.Evidence(words=words, chat=chat, loudness=loudness, face=[(101, "laugh", 6.4)],
+ scenes=[(100.0, "explosão na garagem")])
+
+
+def test_timeline_entries_are_short_split_by_speaker_and_marked():
+ ev = _evidence()
+ items = timeline.entries(ev, 40, 130, clip=(60, 120))
+ assert all(i["d"] <= 8 for i in items) and items[0]["t"] == 40
+ assert any(i.get("sp", "").startswith("[other1]") for i in items) # troca de falante abre entrada nova
+ # Fora do corte (antes e depois) sai marcado; nenhuma entrada atravessa o início ou o fim do corte.
+ assert all(i.get("out") == 1 for i in items if i["t"] < 60 or i["t"] >= 120)
+ assert not any("out" in i for i in items if 60 <= i["t"] < 120)
+ assert {60, 120} <= {i["t"] for i in items} and all(i["t"] + i["d"] <= 60 for i in items if i["t"] < 60)
+ hit = next(i for i in items if i["t"] <= 100 < i["t"] + i["d"])
+ assert hit["v"] == "explosão na garagem" and hit["face"] == "laugh.6" and hit["lvl"] > 3
+ assert hit["chat"].split("|")[0].isdigit() and "KEKW×" in hit["chat"]
+
+
+def test_timeline_fits_the_budget():
+ ev = _evidence(600)
+ full = timeline.build(ev, 0, 600, {"win": [0, 600]}, budget_chars=100_000)
+ small = timeline.build(ev, 0, 600, {"win": [0, 600]}, budget_chars=6000)
+ assert len(small) <= 6000 < len(full)
+ assert all(json.loads(line) for line in small.splitlines()) # cada linha continua JSON válido
+ coarse = timeline.build(ev, 0, 600, {"win": [480, 600]}, budget_chars=100_000, coarse_until=480)
+ first = json.loads(coarse.splitlines()[1])
+ assert first["d"] == 20 and "face" not in first # a "volta" da varredura vai resumida
+
+
+def test_scene_lines_are_saved_by_tile_number(env): # noqa: F811
+ _client, engine = env
+ sid = seed_session(engine)
+ n = timeline.save_scene_lines(engine, sid, "scan", [{"n": 2, "v": " carro capotando "}, {"n": 9, "v": "x"},
+ {"n": "a"}], [10.0, 40.0, 70.0])
+ assert n == 1 and timeline.scene_lines(engine, sid, 0, 100) == [(40.0, "carro capotando")]
+
+
+@pytest.mark.skipif(not (FFMPEG and FFPROBE), reason="FFmpeg não instalado")
+@pytest.mark.parametrize("count,size", [(8, "1536x432"), (6, "1536x432"), (3, "1152x216")])
+def test_mosaic_puts_frames_in_one_image(tmp_path, count, size):
+ frames = []
+ for i in range(count):
+ out = tmp_path / f"f{i}.jpg"
+ subprocess.run([FFMPEG, "-y", "-v", "error", "-f", "lavfi", "-i", f"color=c=0x{i * 30:02x}4080:s=768x432",
+ "-frames:v", "1", str(out)], check=True)
+ frames.append(out)
+ target = media.mosaic(FFMPEG, frames, tmp_path / "m.jpg")
+ probe = subprocess.run([FFPROBE, "-v", "error", "-select_streams", "v:0", "-show_entries", "stream=width,height",
+ "-of", "csv=s=x:p=0", str(target)], capture_output=True, text=True, check=True)
+ assert probe.stdout.strip() == size
diff --git a/clipper/tests/test_english_source.py b/clipper/tests/test_english_source.py
index 3d6a8e7..05a8ebf 100644
--- a/clipper/tests/test_english_source.py
+++ b/clipper/tests/test_english_source.py
@@ -97,7 +97,10 @@ def test_english_session_judges_in_english_and_stores_portuguese(env): # noqa:
add_clip(engine, sid, 1, "candidate", 285, 270, 340)
engine.judge_clip(engine.db.get("SELECT * FROM clips WHERE id = 1"))
assert engine.judge.seen["analyze"][0] == "en" and engine.judge.seen["judge"][0] == "en"
- assert "Transcript:" in engine.judge.seen["judge"][1] and "ANALYST's analysis" in engine.judge.seen["judge"][1]
+ # Linha do tempo JSON (padrão desde a Equipe de IA, EQUIPE-IA.md): legenda das chaves e a fala dentro dela.
+ editor_prompt = engine.judge.seen["judge"][1]
+ assert "Timeline (JSON Lines" in editor_prompt and "ANALYST's analysis" in editor_prompt
+ assert '"sp":"No way bro.' in editor_prompt
clip = client.get("/v1/clips/1", headers=_auth()).json()
assert clip["title"] == "He robbed the bank solo" # o vídeo/publicação: inglês
assert clip["judge"]["pt"]["title"] == "Ele roubou o banco sozinho" # o painel: português
@@ -115,6 +118,7 @@ def test_portuguese_session_has_no_translation(env): # noqa: F811
engine.judge = EnglishJudge()
sid = seed_session(engine)
add_clip(engine, sid, 1, "candidate", 300, 280, 350)
+ engine.intel.opts["timelineJson"] = False # formato antigo (transcrição + chat) continua atrás da opção
engine.judge_clip(engine.db.get("SELECT * FROM clips WHERE id = 1"))
assert engine.judge.seen["judge"][0] == "pt" and "Transcrição:" in engine.judge.seen["judge"][1]
assert client.get("/v1/clips/1", headers=_auth()).json()["translation"] is None
diff --git a/clipper/tests/test_roles.py b/clipper/tests/test_roles.py
new file mode 100644
index 0000000..f1e4647
--- /dev/null
+++ b/clipper/tests/test_roles.py
@@ -0,0 +1,244 @@
+"""Equipe de IA (doc/clipador/EQUIPE-IA.md): papéis com IA própria, migração da configuração antiga, instruções do
+administrador, esforço por papel, medição por chamada (F0) e o relatório. Nenhuma CLI de verdade roda aqui."""
+import json
+import subprocess
+from pathlib import Path
+
+import pytest
+
+from app import judge as judge_module
+from app import roles as roles_module
+from app.ai_settings import AiConfig
+from app.config import Settings
+from app.db import Database
+from app.judge import Judge, claude_usage, codex_usage, gemini_usage
+from app.worker import Engine
+
+from .test_sources_and_api import KEY, auth, env, seed_session # noqa: F401 - fixture reaproveitada
+
+ANALYSIS = {"situation": "jogada", "what_happened": "Ele roubou o banco.", "screen": "", "speech": "", "chat_meaning": "",
+ "confidence": 0.9, "action_start_s": 100, "reaction_end_s": 160, "hook": "Assalto solo", "lines": []}
+VERDICT = {"keep": True, "score": 8, "start_s": 100, "end_s": 170, "title": "Virada", "caption": "c", "hashtags": [],
+ "reason": "r"}
+CONTEXT_OK = {"viewer_summary": "Ele rouba o banco sozinho.", "fix": {"start_s": None, "end_s": None, "context_line": ""},
+ "checks": {c: {"ok": True, "t": None, "why": ""} for c in roles_module.CHECKS}, "confidence": 0.9,
+ "reason": "ok"}
+SCAN = {"screen_game": "GTA", "has_webcam": False, "summary": "s", "moments": [], "lines": []}
+
+
+def answer_for(schema: dict) -> dict:
+ props = schema["properties"]
+ if "viewer_summary" in props:
+ return CONTEXT_OK
+ if "situation" in props:
+ return ANALYSIS
+ if "moments" in props:
+ return SCAN
+ if list(props) == ["lines"]:
+ return {"lines": ["oi"]}
+ return VERDICT
+
+
+@pytest.fixture
+def team(tmp_path, monkeypatch):
+ """Juiz de verdade com as CLIs trocadas por um registro: cada chamada guarda provedor, modelo, esforço e sistema."""
+ calls: list[dict] = []
+
+ def fake_call(self, provider, system, prompt, schema, images, search, timeout, model, effort=""):
+ calls.append({"provider": provider, "model": model, "effort": effort, "system": system, "prompt": prompt})
+ return answer_for(schema)
+
+ monkeypatch.setattr(Judge, "_call", fake_call)
+ for name in ("codex", "claude", "gemini"):
+ monkeypatch.setattr(judge_module, f"find_{name}", (lambda n=name: [n]))
+ return calls
+
+
+def make_engine(tmp_path, saved: dict[str, str] | None = None) -> Engine:
+ settings = Settings.load(env_file=tmp_path / "none.env", service_key=KEY, data_dir=tmp_path / "data",
+ clips_dir=tmp_path / "clips", judge_provider="codex", voice_url=None, voice_key=None)
+ db = Database(settings.data_dir / "clipper.db")
+ if saved:
+ db.many("INSERT INTO settings (key, value) VALUES (?, ?)", list(saved.items()))
+ return Engine(settings, db)
+
+
+# ---------------------------------------------------------------- migração
+def test_old_single_provider_becomes_every_role_and_analyst_model_is_kept(tmp_path):
+ engine = make_engine(tmp_path, {"judge_provider": "claude", "judge_model": "sonnet", "judge_analyst_model": "haiku"})
+ roles = engine.judge.roles
+ assert {r["provider"] for r in roles.values()} == {"claude"}
+ assert roles["editor"]["model"] == "sonnet" and roles["scan"]["model"] == "sonnet" and roles["judge"]["model"] == "sonnet"
+ assert roles["analyst"]["model"] == "haiku" # o "modelo do analista" que já existia é respeitado
+ assert roles["judge"]["enabled"] and roles["judge"]["critical"] == ["setup", "payoff", "standalone"]
+ # A migração fica gravada (explícita no banco); a próxima subida lê `judge.roles`.
+ saved = json.loads(engine.db.get("SELECT value FROM settings WHERE key = 'judge.roles'")["value"])
+ assert saved["analyst"]["model"] == "haiku"
+ again = Engine(engine.settings, engine.db)
+ assert again.judge.roles == roles
+
+
+def test_off_master_switch_is_kept_and_roles_still_migrate(tmp_path):
+ engine = make_engine(tmp_path, {"judge_provider": "off", "judge_model": ""})
+ assert not engine.judge.enabled and engine.judge.provider == "off"
+ assert {r["provider"] for r in engine.judge.roles.values()} == {"codex"}
+
+
+def test_normalize_roles_field_by_field():
+ base = roles_module.default_roles("codex", "gpt-6-luna")
+ out = roles_module.normalize_roles({
+ "editor": {"enabled": False, "provider": "claude"}, # editor nunca desliga; trocou de provedor → modelo padrão
+ "judge": {"effort": "turbo", "critical": ["payoff", "inventado"], "penalty": 9, "extra": " x "},
+ "scan": {"images": "frames", "model": "bad model;"},
+ }, base)
+ assert out["editor"]["enabled"] is True and out["editor"]["provider"] == "claude" and out["editor"]["model"] == ""
+ assert out["judge"]["effort"] == "medium" and out["judge"]["critical"] == ["payoff"]
+ assert out["judge"]["penalty"] == 0.5 and out["judge"]["extra"] == "x"
+ assert out["scan"]["images"] == "frames" and out["scan"]["model"] == "gpt-6-luna"
+
+
+# ---------------------------------------------------------------- cada papel chama a sua IA
+def test_each_role_calls_its_own_provider_model_and_effort(tmp_path, team):
+ roles = roles_module.default_roles("codex")
+ roles["scan"] |= {"provider": "codex", "model": "gpt-6-luna", "effort": "low"}
+ roles["analyst"] |= {"provider": "claude", "model": "haiku"}
+ roles["editor"] |= {"provider": "codex", "model": ""}
+ roles["judge"] |= {"provider": "claude", "model": "sonnet", "effort": ""}
+ judge = Judge("codex", "", tmp_path / "j", ai=AiConfig(tmp_path / "ai"), roles=roles)
+ judge.scan("p", [], lang="en")
+ judge.analyze("p", [], lang="en")
+ judge.judge("p", 100, 170, [], lang="en")
+ judge.check_context("p", lang="en")
+ got = [(c["provider"], c["model"], c["effort"]) for c in team]
+ assert got == [("codex", "gpt-6-luna", "low"), ("claude", "haiku", ""), ("codex", "gpt-6-luna", ""),
+ ("claude", "sonnet", "")]
+ # O que não é dos quatro papéis (tradução, pesquisa) usa a IA do editor.
+ judge.translate_lines(["oi"])
+ assert team[-1]["provider"] == "codex"
+ assert judge.fallback_chain("claude")[0] == "claude" and judge.fallback_chain()[0] == "codex"
+
+
+def test_admin_instructions_are_added_after_the_default_text(tmp_path, team):
+ roles = roles_module.default_roles("codex")
+ roles["judge"]["extra"] = "Não aprove corte que termina antes do resultado da treta."
+ roles["analyst"]["extra"] = "Lag conta como jogada."
+ judge = Judge("codex", "", tmp_path / "j", ai=AiConfig(tmp_path / "ai"), roles=roles)
+ judge.check_context("p", lang="en")
+ judge.analyze("p", [], lang="pt")
+ judge.judge("p", 100, 170, [], lang="pt")
+ context_system, analyst_system, editor_system = (c["system"] for c in team)
+ assert context_system.startswith(judge_module.CONTEXT_SYSTEM_EN) # o padrão continua inteiro, no começo
+ assert context_system.endswith("Admin notes (may be written in Portuguese; when they conflict with the rules above, "
+ "they win):\nNão aprove corte que termina antes do resultado da treta.")
+ assert analyst_system.endswith("valem estas):\nLag conta como jogada.")
+ assert "Instruções do administrador" not in editor_system # o editor não tem extra
+
+
+def test_codex_effort_goes_to_the_command_line(tmp_path, monkeypatch):
+ seen: list[list[str]] = []
+
+ def run(args, input=None, capture_output=True, timeout=None, cwd=None, creationflags=0, env=None):
+ seen.append(list(args))
+ Path(args[args.index("-o") + 1]).write_text(json.dumps(CONTEXT_OK), encoding="utf-8")
+ events = '{"type":"thread.started"}\n{"type":"turn.completed","usage":{"input_tokens":1234,"cached_input_tokens":200,"output_tokens":56}}\n'
+ return subprocess.CompletedProcess(args, 0, events.encode(), b"")
+
+ monkeypatch.setattr(judge_module.subprocess, "run", run)
+ monkeypatch.setattr(judge_module, "find_codex", lambda: ["codex"])
+ monkeypatch.setattr(judge_module, "find_claude", lambda: None)
+ records = []
+ judge = Judge("codex", "", tmp_path / "j", ai=AiConfig(tmp_path / "ai"))
+ judge.meter = records.append
+ with judge.scope(clip_id=7, session_id=3, mode="timeline+mosaic"):
+ judge.check_context("prompt de teste", lang="pt")
+ assert 'model_reasoning_effort="medium"' in seen[0] and "--json" in seen[0] # juiz: esforço médio por padrão
+ rec = records[0]
+ assert rec["role"] == "judge" and rec["provider"] == "codex" and rec["ok"] is True
+ assert (rec["tokensIn"], rec["tokensOut"], rec["tokensCached"]) == (1234, 56, 200)
+ assert rec["clip_id"] == 7 and rec["mode"] == "timeline+mosaic" and rec["promptChars"] == len("prompt de teste")
+
+
+def test_usage_parsers():
+ assert codex_usage("lixo\n{\"type\":\"turn.completed\",\"usage\":{\"input_tokens\":10,\"output_tokens\":2}}") == \
+ {"in": 10, "out": 2, "cached": None}
+ assert codex_usage("") is None
+ assert claude_usage({"usage": {"input_tokens": 5, "cache_creation_input_tokens": 100, "cache_read_input_tokens": 2000,
+ "output_tokens": 40}}) == {"in": 2105, "out": 40, "cached": 2000}
+ assert gemini_usage({"stats": {"models": {"gemini-3.5-flash": {"tokens": {"prompt": 900, "candidates": 50,
+ "thoughts": 10, "cached": 0}}}}}) == \
+ {"in": 900, "out": 60, "cached": 0}
+ assert gemini_usage({"response": "x"}) is None
+
+
+# ---------------------------------------------------------------- API e medição
+def test_put_roles_and_read_defaults(env): # noqa: F811
+ client, engine = env
+ roles = {"scan": {"enabled": False, "provider": "codex", "images": "frames"},
+ "analyst": {"provider": "claude", "model": "haiku", "extra": "Olhe o HUD."},
+ "editor": {"enabled": False, "provider": "codex"},
+ "judge": {"enabled": True, "provider": "claude", "model": "sonnet", "critical": ["setup", "payoff"],
+ "allowContextLine": False}}
+ r = client.put("/v1/judge", json={"provider": "codex", "model": "", "minScore": 6, "roles": roles}, headers=auth())
+ assert r.status_code == 200
+ data = r.json()
+ assert data["roles"]["analyst"]["provider"] == "claude" and data["roles"]["analyst"]["extra"] == "Olhe o HUD."
+ assert data["roles"]["editor"]["enabled"] is True # o editor não desliga
+ assert data["roles"]["judge"]["critical"] == ["setup", "payoff"] and data["roles"]["judge"]["allowContextLine"] is False
+ # O cartão da varredura liga/desliga a varredura de verdade.
+ assert data["roles"]["scan"]["enabled"] is False and engine.intel.opts["scanEnabled"] is False
+ got = client.get("/v1/judge", headers=auth()).json()
+ assert set(got["roleDefaults"]) == {"scan", "analyst", "editor", "judge"}
+ assert got["roleDefaults"]["judge"]["en"].startswith("You are the CONTEXT JUDGE")
+ assert [c["id"] for c in got["checks"]][:3] == ["setup", "payoff", "who_what"]
+ assert "roleDefaults" not in client.get("/v1/status", headers=auth()).json()["judge"] # status fica leve
+ # A opção da linha do tempo (comparar com o formato antigo) também se troca pela mesma rota.
+ client.put("/v1/judge", json={"provider": "codex", "model": "", "minScore": 6, "timelineJson": False}, headers=auth())
+ assert engine.intel.opts["timelineJson"] is False
+
+
+def test_owner_label_and_report(env): # noqa: F811
+ client, engine = env
+ sid = seed_session(engine)
+ db = engine.db
+
+ def clip(cid, status, decision, keep=True, label=None):
+ judge = {"keep": keep, "score": 7}
+ if decision:
+ judge["context"] = {"decision": decision, "contextLine": "x" if decision == "approve" else ""}
+ db.run("INSERT INTO clips (id, session_id, peak_s, start_s, end_s, score, source, status, judge_json, created_at,"
+ " updated_at, owner_label) VALUES (?, ?, 1, 0, 60, 5, 'chat', ?, ?, ?, ?, ?)",
+ cid, sid, status, json.dumps(judge), engine_now(), engine_now(), label)
+
+ clip(1, "approved", "approve") # juiz mantém, dono bom → concorda
+ clip(2, "rejected", "approve") # juiz mantém, dono ruim → discorda
+ clip(3, "discarded", "discard", label="no_context") # juiz descarta, dono "sem contexto" → concorda
+ clip(4, "ready", "adjust") # dono não avaliou
+ clip(5, "approved", "discard") # juiz descartou, dono forçou e aprovou → falso negativo
+ # Rejeitar com "sem contexto" pela rota (o rótulo vale também para corte antigo/descartado).
+ r = client.patch("/v1/clips/4", json={"label": "no_context", "labelNote": "não dá pra entender"}, headers=auth())
+ assert r.json()["ownerLabel"] == "no_context" and r.json()["ownerNote"] == "não dá pra entender"
+ assert r.json()["status"] == "ready" # avaliar não muda o estado
+ engine.record_ai_call({"role": "judge", "purpose": "judge", "provider": "codex", "model": "gpt-6-luna", "ok": True,
+ "ms": 1200, "systemChars": 2700, "promptChars": 3000, "images": 0, "imageBytes": 0,
+ "tokensIn": 1500, "tokensOut": 200, "session_id": sid, "mode": "timeline+mosaic"})
+ engine.record_ai_call({"role": "analyst", "purpose": "analyst", "provider": "codex", "model": "gpt-6-luna",
+ "ok": False, "error": "cota", "systemChars": 3000, "promptChars": 5000, "images": 1,
+ "imageBytes": 60_000, "session_id": sid})
+ rep = client.get(f"/v1/judge/report?session={sid}", headers=auth()).json()
+ assert rep["window"]["liveHours"] == round(600 / 3600, 2)
+ judge_row = next(c for c in rep["calls"] if c["role"] == "judge")
+ assert judge_row["tokensIn"] == 1500 and judge_row["withUsage"] == 1 and judge_row["mode"] == "timeline+mosaic"
+ assert next(c for c in rep["calls"] if c["role"] == "analyst")["failures"] == 1
+ assert rep["perHour"]["judge"]["calls"] == pytest.approx(6.0)
+ assert rep["judge"]["approve"] == 2 and rep["judge"]["discard"] == 2 and rep["judge"]["adjust"] == 1
+ assert rep["clips"]["approvalRate"] == round(2 / 3, 3) and rep["clips"]["noContext"] == 2
+ agreement = rep["agreement"]["judge"]
+ # pares: (keep, good) (keep, bad) (discard, no_context) (keep, no_context) (discard, good) → concordam 2 de 5
+ assert agreement["pairs"] == 5 and agreement["agree"] == 2
+ assert agreement["matrix"]["discard"]["good"] == 1 and agreement["matrix"]["keep"]["no_context"] == 1
+
+
+def engine_now() -> str:
+ from app.db import now
+
+ return now()
diff --git a/clipper/tests/test_sources_and_api.py b/clipper/tests/test_sources_and_api.py
index cce0e17..81f1b83 100644
--- a/clipper/tests/test_sources_and_api.py
+++ b/clipper/tests/test_sources_and_api.py
@@ -165,6 +165,9 @@ def test_judge_config_persists(env, tmp_path):
assert client.put("/v1/judge", json={"provider": "gpt", "model": ""}, headers=auth()).status_code == 422
assert client.put("/v1/judge", json={"provider": "codex", "model": "x; rm -rf"}, headers=auth()).status_code == 422
saved = {r["key"]: r["value"] for r in engine.db.all("SELECT * FROM settings")}
+ # Equipe de IA (EQUIPE-IA.md): o painel antigo (um provedor só) troca a IA de todos os papéis.
+ roles = json.loads(saved.pop("judge.roles"))
+ assert {r["provider"] for r in roles.values()} == {"claude"}
assert saved == {"judge_provider": "claude", "judge_model": "haiku", "judge_min_score": "7.0", "judge_analyst_model": ""}
diff --git a/clipper/tests/test_speakers.py b/clipper/tests/test_speakers.py
index 7c00f8b..f6d89d2 100644
--- a/clipper/tests/test_speakers.py
+++ b/clipper/tests/test_speakers.py
@@ -352,7 +352,8 @@ def test_translation_lines_get_speaker(env): # noqa: F811
assert [(x["text"], x["speaker"]) for x in lines] == [("No way bro.", "streamer"), ("Told you.", "other1")]
# O juiz viu quem fala.
prompt = engine.judge.seen["judge"][1]
- assert "] No way bro." in prompt and "[other1] Told you." in prompt and "Never attribute to" in prompt
+ # Linha do tempo JSON (EQUIPE-IA.md): cada entrada é de um falante só; a de outra pessoa vem marcada.
+ assert '"sp":"No way bro."' in prompt and '"sp":"[other1] Told you."' in prompt and "Never attribute to" in prompt
# Tradução antiga (sem `speaker`) é refeita na próxima vez.
engine.db.run("UPDATE clips SET translation_json = ? WHERE id = 1",
json.dumps({"startS": 0, "endS": 1e6, "lines": [{"s": 1, "e": 2, "text": "x", "pt": "y"}]}))
diff --git a/doc/clipador/EQUIPE-IA.md b/doc/clipador/EQUIPE-IA.md
new file mode 100644
index 0000000..0905ae0
--- /dev/null
+++ b/doc/clipador/EQUIPE-IA.md
@@ -0,0 +1,178 @@
+# Clipador — Equipe de IA: papéis, juiz de contexto, linha do tempo JSON e medição (18/11/2026)
+
+Implementa as fases **F0** (medir) e **F1** (três papéis + linha do tempo v1) de
+[`PESQUISA-JUIZ.md`](PESQUISA-JUIZ.md). F2 (OCR do HUD, eventos de áudio) e F3 (modelo local de cena) **não** entraram.
+
+Pedido do dono: "temos o analista, o editor e vamos criar o JUIZ — três partes, cada uma com a sua IA (provedor e
+modelo); nós, como administrador, editamos o que cada um faz. O editor decide se vira corte. O juiz verifica se tem
+contexto. A IA lê o vídeo em JSON curto para não gastar token de entrada. Para não trazer corte sem sentido,
+principalmente em inglês."
+
+## 1. Papéis
+
+| Papel (`id`) | O que faz | Vê imagem? | Pode desligar? |
+| --- | --- | --- | --- |
+| Varredura (`scan`) | assiste a live por janelas e propõe momentos; descreve cada quadro do mosaico (`lines`) | mosaico 4×2 (padrão), quadros soltos ou nenhuma | sim (é a opção `scanEnabled`) |
+| Analista (`analyst`) | diz O QUE aconteceu no trecho candidato; também descreve os quadros (`lines`) | mosaico (padrão), quadros soltos ou nenhuma | sim (o editor passa a receber as imagens) |
+| Editor (`editor`) | decide se vira corte, trecho, título, legenda, hashtags | só quando o analista falhou/está desligado | **não** |
+| Juiz (`judge`) | só texto: o corte faz sentido para quem nunca viu a live? | nunca | sim |
+
+Tradução da fala, pesquisa/edição de perfil de jogo e câmera pela IA usam a IA do **editor** (é a "principal"; o
+`provider`/`model` de `GET /v1/judge` continuam sendo os dele).
+
+### Configuração (`settings`, chave `judge.roles`)
+
+```jsonc
+{
+ "scan": {"enabled": true, "provider": "codex", "model": "", "effort": "", "extra": "", "images": "mosaic"},
+ "analyst": {"enabled": true, "provider": "codex", "model": "", "effort": "", "extra": "", "images": "mosaic"},
+ "editor": {"enabled": true, "provider": "codex", "model": "", "effort": "", "extra": ""},
+ "judge": {"enabled": true, "provider": "codex", "model": "", "effort": "medium", "extra": "",
+ "critical": ["setup", "payoff", "standalone"], "allowFix": true, "allowContextLine": true, "penalty": 0.5}
+}
+```
+
+- `model: ""` = padrão do provedor (`DEFAULT_MODELS`). `effort` só vale no Codex (`model_reasoning_effort`; "" = low,
+ como sempre foi). O juiz começa em `medium` (recomendação da pesquisa).
+- `extra` = **instruções do administrador** (até 2.000 caracteres). Vão DEPOIS das instruções padrão, que continuam no
+ código, com o rótulo "Admin notes (may be written in Portuguese; when they conflict with the rules above, they win)"
+ (fonte em inglês) ou "Instruções do administrador…" (fonte em português). O painel mostra as padrão só para leitura
+ (`GET /v1/judge` → `roleDefaults..pt|en`).
+- Validação campo a campo em `roles.normalize_roles`; o editor é sempre `enabled: true`.
+- **Migração automática**: banco sem `judge.roles` → o provedor/modelo único de hoje (`judge_provider`/`judge_model`)
+ vira o de todos os papéis e o `judge_analyst_model` que existia fica com o analista. A migração é gravada na subida.
+ `judge_provider = "off"` continua sendo o "IA desligada" (só heurística) — a equipe inteira.
+- Painel antigo (sem `roles` no `PUT`): `provider`/`model` valem para todos os papéis (como antes).
+- **Reserva por papel**: a cadeia (`fallback_chain(primary)`) começa na IA do papel e segue a ordem de Configurações →
+ IA; cada papel mostra a sua (`roles..chain`).
+
+## 2. Juiz de contexto
+
+Roda depois que o editor MANTEVE o corte (nota ≥ mínima). Vê só o que vai no corte final: a linha do tempo do trecho
+mais 20 s antes e 15 s depois marcados `out=1` (o espectador não vê), título, legenda, texto de abertura, a "história
+pretendida" (`what_happened` do analista) e uma linha do jogo. Escreve primeiro `viewer_summary` (o que um espectador
+frio entende) e depois responde sim/não a 7 checagens:
+
+| Checagem | Pergunta | Crítica por padrão |
+| --- | --- | --- |
+| `setup` | o corte tem o começo da situação? | sim |
+| `payoff` | tem o desfecho/resultado/piada? | sim |
+| `standalone` | funciona sem saber o que veio antes na live / lore do canal? | sim |
+| `who_what` | dá para entender quem e o quê? | — |
+| `intelligible` | a fala-chave está na transcrição (não é de um colega que não se ouve)? | — |
+| `faithful` | título/legenda só dizem o que o corte mostra? | — |
+| `strong_open` | os 3 primeiros segundos prendem? | — |
+
+Schema: `CONTEXT_SCHEMA` (`viewer_summary`, `checks.{c}.{ok,t,why}`, `fix.{start_s,end_s,context_line}`, `confidence`,
+`reason`); fonte em inglês: `CONTEXT_SCHEMA_EN` com o bloco `pt` (`viewer_summary`, `reason`, `context_line`,
+`checks.{c}`), como em [`IDIOMAS.md`](IDIOMAS.md).
+
+### Quem decide é o código (`context_judge.decide`)
+
+1. Crítica que falhou **e** o juiz propôs `fix` (e `allowFix`) → o trecho é recalculado com `fit_window` dentro dos
+ limites (volta até `backtrackS`, duração mínima+1 s e máxima). Mudou ≥ 1 s → **ajusta** e o juiz confere **uma** vez
+ de novo, sem novo ajuste: passou → fica o trecho novo; falhou → **descarta** ("Descartado pelo juiz depois do
+ ajuste…").
+2. Crítica que falhou sem ajuste possível → **descarta** com o motivo em português ("Descartado pelo juiz: sem
+ desfecho. …").
+3. `standalone`/`who_what` falhos + `context_line` curta (≤ 10 palavras, ≤ 60 caracteres, `allowContextLine`) → a frase
+ resolve: o corte é aprovado e a frase vira o **texto de abertura** do projeto de edição (no lugar do gancho do
+ analista, `editor_api.auto_for`). Com ajuste de trecho, o início/fim do analista não desfaz o ajuste.
+4. Não críticas falhas só tiram `penalty` (0,5) cada da nota do editor (`scoreAfter`); abaixo da nota mínima →
+ descarta.
+5. Corte manual ("cortar agora"): só **avisa** (`decision: "warn"`), nunca descarta nem mexe no trecho.
+6. Falha da IA do juiz → fica a decisão do editor (`context: {error}`).
+
+Gravado em `judge_json.context` (`decision`: approve | adjust | discard | warn, `checks`, `failed`, `failedCritical`,
+`solvedByLine`, `contextLine`, `scoreAfter`, `reasonPt`, `window`, `first` = 1ª rodada quando ajustou). Descartado pelo
+juiz: `status = discarded` + `judge_json.discardedBy = "context"`; aparece em "Descartados" e **Forçar render** funciona
+como sempre. O modal do corte mostra tudo em português.
+
+Fora do F1 (da pesquisa): 2ª opinião com outro provedor quando a confiança é baixa, exemplos do dono como few-shot e
+"testar nos últimos 10 cortes".
+
+## 3. Linha do tempo JSON (v1) e mosaico
+
+`app/timeline.py` monta, só com o que já existe, uma linha JSON por instante (chaves curtas; a legenda vai uma vez no
+prompt):
+
+```jsonl
+{"win":[4401,4626],"src":"en"}
+{"t":4529,"d":8,"v":"Tfue on foot near beach house, aims rifle at masked player","sp":"That's my friend… Can be friends?"}
+{"t":4417,"d":5,"sp":"is that tech","face":"laugh.8","lvl":7,"chat":"9|freckPepeLaff×1"}
+```
+
+- Entradas: nova a cada pausa > 1,2 s (se a atual já tem 4 s), troca de falante ou no máximo 8 s; nenhuma atravessa o
+ início/fim do corte.
+- `sp` = fala literal (até 25 palavras; `[other1]` = outra pessoa, FALANTES.md); `face` = expressão do streamer
+ (`reaction.label` sobre a série do rosto já gravada) com intensidade ≥ 3; `lvl` só quando foge do normal (≥ 6 ou ≤ 1);
+ `chat` = `mensagens|emote×n|frase repetida` (só o que o chat repete; @resposta e !comando não contam).
+- `v` = o que está na tela: a varredura e o analista já veem os quadros e agora devolvem `lines: [{n, v}]` (até 12
+ palavras por quadro); fica em `scene_notes` e é reaproveitado por analista, editor e juiz.
+- Orçamento de caracteres por papel (analista 9.000, editor 7.000, juiz 6.000, varredura 9.000): passou, a fala encurta
+ (25 → 12 → 6 palavras). A "volta" da varredura vai resumida (passo de 20 s).
+- Perfil do jogo **enxuto** nos prompts da linha do tempo (`judge.lean_profile`: resumo em 2 frases, listas menores).
+- Imagens: `media.mosaic` junta os quadros (384×216 cada) numa grade 4×2 = 1 imagem 1536×432; a varredura usa 8
+ quadros por janela. Falhou o mosaico → quadros pequenos soltos.
+- **Comparar com o antigo**: opção `timelineJson` (`PUT /v1/judge`, interruptor no painel). Desligada = exatamente o
+ formato anterior (transcrição + chat + quadros soltos de 768 px). Cada chamada grava o modo em `ai_calls.mode`
+ (`timeline+mosaic`, `legacy+frames`…).
+
+### Medido no corte 291 (sessão 15, tfue/ROB RUN, fonte em inglês), 18/11/2026
+
+Cópia do banco (`?mode=ro` + backup) e dos blocos numa pasta temporária; IA falsa que só guarda o prompt. Texto ≈
+caracteres/4; imagens pelas fórmulas da pesquisa (Codex 1,2 × patches de 32 px; Claude patches de 28 px; Gemini 1.120
+por imagem).
+
+| Chamada | Antes (texto + imagens, Codex) | Depois | Gemini antes → depois |
+| --- | --- | --- | --- |
+| Analista (8 quadros → 1 mosaico) | 2.414 + 3.224 = **5.638** | 2.298 + 806 = **3.104** (−45%) | 11.374 → 3.418 (−70%) |
+| Editor (só texto) | **2.795** | **2.250** (−20%) | igual |
+| Varredura (6 quadros → mosaico de 8) | 2.912 + 2.418 = **5.330** | 2.505 + 806 = **3.311** (−38%) | 9.632 → 3.625 (−62%) |
+| Juiz (novo, só nos mantidos) | — | **≈ 1.420** | — |
+
+Por hora (tfue: ~20 varreduras, ~25 candidatos, ~13 mantidos): antes ≈ 317 mil tokens de conteúdo; depois ≈ 224 mil
+**com** o juiz (−29%). Em bytes de imagem: analista 361 KB → 121 KB por corte.
+
+Chamada real (UMA, Codex `gpt-6-luna`, papel juiz, esforço médio, 18/11/2026): schema com `null` aceito, bloco `pt`
+completo, **9.624 tokens de entrada / 1.400 de saída, 27 s**. Como o conteúdo era ≈ 1.450 tokens, o **fixo do Codex
+pela CLI ≈ 8 mil tokens por chamada** — hoje é o maior item; o próximo passo de economia é ele (medir pelo relatório).
+
+## 4. Medição (F0)
+
+- `ai_calls` (banco v17): uma linha por tentativa de chamada — `role`, `purpose` (translate, research, cam…),
+ `provider`, `model`, `ok`/`error`, `ms`, `system_chars`, `prompt_chars`, `images`, `image_bytes`, `tokens_in`,
+ `tokens_out`, `tokens_cached` (quando a CLI informa: `codex exec --json` → `turn.completed.usage`; `claude
+ --output-format json` → `usage`; `gemini -o json` → `stats.models.*.tokens`), `session_id`, `clip_id`, `mode`.
+- Avaliação do dono: `clips.owner_label` (`good` | `bad` | `no_context`) + `owner_note`. `PATCH /v1/clips/{id}` com
+ `{"label": "no_context"}` (vale para qualquer corte, inclusive antigos e descartados; não muda o estado) ou
+ `{"status": "rejected", "label": "no_context"}` (botão **Sem contexto** no modal). Sem rótulo: aprovado/publicado =
+ bom, rejeitado = ruim.
+- `GET /v1/judge/report?days=7` (ou `?session=N`): `calls` por papel × IA × modo, `perHour` (chamadas e tokens por hora
+ de live; `estTokensIn` = caracteres/4 quando a CLI não informou), `clips` (por estado, taxa de aprovação, "sem
+ contexto"), `judge` (aprovou/ajustou/descartou/avisou/erro/com frase) e `agreement.judge|editor` (pares, concordância,
+ κ de Cohen, matriz mantém/descarta × bom/ruim/sem contexto). O painel mostra em Ajustes → Juiz → Medição.
+
+## 5. Onde está cada coisa
+
+- `clipper/app/roles.py` — papéis, padrão, validação, migração, instruções do administrador.
+- `clipper/app/judge.py` — `Judge.ask(role=…)`, `check_context`, `CONTEXT_*`, `build_timeline_prompt`,
+ `build_scan_timeline_prompt`, `build_context_prompt`, `lean_profile`, leitura de uso (`codex_usage`, `claude_usage`,
+ `gemini_usage`), `scope(...)` para a medição.
+- `clipper/app/context_judge.py` — `decide` e `view`.
+- `clipper/app/timeline.py` — evidência, entradas, orçamento, `scene_notes`.
+- `clipper/app/worker.py` — `judge_clip` (analista → editor → juiz), `_context_check`, `record_ai_call`.
+- `clipper/app/intel.py` — `visual` (mosaico/quadros), varredura com a linha do tempo, opção `timelineJson`.
+- `clipper/app/report.py` — relatório.
+- Painel: `clipper-ai-team.tsx` (cartões e medição), `clipper-judge.tsx`, `clipper-clip-parts.tsx`
+ (`ContextVerdict`, `OwnerLabelControl`, botão "Sem contexto").
+- Testes: `clipper/tests/test_roles.py`, `clipper/tests/test_context_judge.py`. Os testes bloqueiam qualquer CLI de IA
+ de verdade (`conftest._no_real_ai_cli`).
+
+## 6. Pontos de integração
+
+- Banco: **v17** (`ai_calls`, `scene_notes`). A v16 é a detecção do jogo (`game_status`, `game_detect_json`); as
+ expressões do rosto não precisaram de migração.
+- O rosto é lido por `face.FaceService.dense` + `reaction.channel_z/reaction_signal/label` (sem mudar `face.py` nem
+ `reaction.py`); rótulos novos de expressão passam como vierem (o mapa para inglês está em `timeline.FACE_TOKENS`).
+- `codex exec` agora roda com `--json` (os eventos vão para a saída padrão; a resposta continua em `-o`).
diff --git a/doc/clipador/FALANTES.md b/doc/clipador/FALANTES.md
index 384ee1d..d8e6a0e 100644
--- a/doc/clipador/FALANTES.md
+++ b/doc/clipador/FALANTES.md
@@ -45,9 +45,7 @@ padrão ligada) desliga tudo.
- `segments.words_json` aceita o 4º elemento `[início, fim, texto, falante]`; o formato antigo (3) continua valendo e é
o que se grava hoje (`speakers.dump_words`). Falante gravado no 4º elemento tem prioridade sobre a atribuição.
- Tabela `voice_chunks (session_id, idx, data_json, updated_at)` — `{model, chunks: [{s, e, db, v}]}`, `v` = vetor em
- float16/base64 (~5 KB por bloco, ~0,6 MB por hora). Criada com `CREATE TABLE IF NOT EXISTS` ao subir o serviço,
- **fora** da lista de migrações: a v14 é de outra frente e ainda não está nesta branch; numa posição fixa da lista ela
- viraria a v14 aqui. Quem integrar pode movê-la para a v15.
+ float16/base64 (~5 KB por bloco, ~0,6 MB por hora). Criada pela migração **v15** (`db.py`).
- `face_track.data_json.mouth`: série por quadro (6 qps) do movimento da boca; blocos antigos não têm (a prova da boca
só vale para blocos rastreados depois desta versão).
- Projeto do editor: cada palavra ganha `sp` (só quando atribuída). Projetos antigos, sem `sp`, saem iguais.
diff --git a/doc/ia.md b/doc/ia.md
index 44768b2..a44a397 100644
--- a/doc/ia.md
+++ b/doc/ia.md
@@ -19,8 +19,10 @@ Três IAs, sempre pela **CLI oficial** instalada no PC (nunca SDK/HTTP direto):
> OAuth só funciona com plano elegível (Code Assist Standard/Enterprise, Workspace). Para conta pessoal, use a
> **chave de API** do Google AI Studio.
-Quem usa: os **agentes do painel** (`panel/src/lib/agents.ts`) e o **juiz do Clipador** (`clipper/app/judge.py`).
-A configuração fica no painel em **Configurações → IA** (`/settings/ai`).
+Quem usa: os **agentes do painel** (`panel/src/lib/agents.ts`) e a **Equipe de IA do Clipador**
+(`clipper/app/judge.py`: varredura, analista, editor e juiz, cada papel com o seu provedor/modelo —
+[`clipador/EQUIPE-IA.md`](clipador/EQUIPE-IA.md)). A configuração das IAs (login, chave, reserva) fica no painel em
+**Configurações → IA** (`/settings/ai`); qual IA cada papel usa, em Clipador → Ajustes → Juiz.
## Arquivos compartilhados (contrato painel ↔ Clipador)
@@ -68,6 +70,19 @@ Montado a partir do ambiente do processo, por provedor:
Assim o login global de cada CLI não é tocado: o modo chave só vale para a chamada.
+## Clipador: uma IA por papel (18/11/2026)
+
+- Cada papel do Clipador (`scan`, `analyst`, `editor`, `judge`) tem `provider` + `model` (+ `effort` no Codex) em
+ `judge.roles` (banco do Clipador). A **reserva vale por papel**: a cadeia começa na IA do papel e segue a `order`
+ deste arquivo, com as mesmas regras (ligada, CLI, chave, pausa, perto do limite). Serviços gerais (tradução da fala,
+ pesquisa de jogo, câmera) usam a IA do editor.
+- `codex exec` do Clipador roda com `--json` (eventos JSONL na saída padrão; a resposta continua em `-o`) e
+ `model_reasoning_effort` do papel (padrão `low`; o juiz começa em `medium`).
+- Uso de tokens por chamada vai para `ai_calls` (Clipador): Codex = `turn.completed.usage` do `--json`; Claude =
+ `usage` do envelope `--output-format json` (entrada = nova + criação + leitura de cache); Gemini =
+ `stats.models.*.tokens`. Medido 18/11/2026: o Codex cobra ≈ 8 mil tokens fixos por chamada pela CLI (juiz com
+ ≈ 1.450 de conteúdo → 9.624 de entrada).
+
## O que conta como "indisponível" (dispara a reserva)
Falha que não é culpa do pedido: limite de uso ou cota (`rate limit`, `429`, `quota`, `usage limit`,
diff --git a/panel/src/components/clipper-ai-team.tsx b/panel/src/components/clipper-ai-team.tsx
new file mode 100644
index 0000000..dba5e78
--- /dev/null
+++ b/panel/src/components/clipper-ai-team.tsx
@@ -0,0 +1,285 @@
+"use client";
+// Equipe de IA do Clipador (doc/clipador/EQUIPE-IA.md): um cartão por papel — varredura, analista, editor e juiz —
+// com provedor, modelo (lista do provedor escolhido), raciocínio (só Codex), imagens, liga/desliga (o editor não
+// desliga), as instruções padrão (só leitura) e as instruções do administrador (somadas às padrão). E o relatório
+// de medição: chamadas e tokens por papel, decisões do juiz e a concordância dele com você.
+import { useCallback, useEffect, useState } from "react";
+import {
+ CHECK_LABEL, PROVIDER_LABEL, ROLE_INFO, ROLE_ORDER, clipperCall, formatScore,
+ type AiEffort, type AiImages, type AiReport, type AiRole, type AiRoleId, type AiRoleProvider, type AiRoles,
+ type ContextCheckId, type JudgeConfig,
+} from "./clipper-client";
+import { DescribedSelect } from "./forms";
+import { AlertIcon, RefreshIcon, SparkIcon } from "./icons";
+import { Badge, Button, Card, Select, Spinner, Switch, Textarea, cx } from "./ui";
+
+const EXTRA_MAX = 2000;
+const EFFORT_LABEL: Record = { "": "padrão (baixo)", low: "baixo", medium: "médio", high: "alto" };
+const IMAGES_LABEL: Record = {
+ mosaic: { label: "Mosaico (1 imagem com 8 quadros)", description: "Os quadros numa grade 4×2: a IA vê a sequência pagando por 1 imagem (4–8× menos que quadros soltos)." },
+ frames: { label: "Quadros soltos (antigo)", description: "Cada quadro em uma imagem, em 768 px. Mais detalhe, bem mais caro." },
+ none: { label: "Nenhuma", description: "Só texto (fala, chat, rosto e o que a varredura já descreveu da tela)." },
+};
+const ALL_CHECKS = Object.keys(CHECK_LABEL) as ContextCheckId[];
+
+/** Provedores que dá para escolher: Codex e Claude sempre; Gemini só se estiver ligado em Configurações → IA. */
+function providerOptions(judge: JudgeConfig, current: AiRoleProvider): AiRoleProvider[] {
+ const list: AiRoleProvider[] = ["codex", "claude"];
+ if (judge.providers?.gemini?.enabled || current === "gemini") list.push("gemini");
+ return list;
+}
+
+export function AiTeam({ judge, roles, onChange, disabled }: {
+ judge: JudgeConfig; roles: AiRoles; onChange: (next: AiRoles) => void; disabled: boolean;
+}) {
+ const set = (id: AiRoleId, values: Partial) => onChange({ ...roles, [id]: { ...roles[id], ...values } });
+ return (
+
+
+
Equipe de IA
+
+ Cada papel roda na IA que você escolher. A varredura e o analista veem a tela;
+ o editor decide se vira corte; o juiz confere se o corte faz sentido para quem nunca viu a live.
+ Se a IA de um papel cair, a reserva de Configurações → IA assume para aquele papel.
+
+ );
+}
diff --git a/panel/src/components/clipper-client.ts b/panel/src/components/clipper-client.ts
index cbada78..7b83543 100644
--- a/panel/src/components/clipper-client.ts
+++ b/panel/src/components/clipper-client.ts
@@ -18,8 +18,40 @@ export type ClipperStatus = {
};
export type JudgeModel = { id: string; label: string; description?: string };
-/** `faceTrack` é opcional: o serviço antigo (antes do rastreio de reação) não manda. */
-export type JudgeOptions = { scanEnabled: boolean; scanIntervalS: number; vision: boolean; camDetect: boolean; faceTrack?: boolean };
+/** `faceTrack` e `timelineJson` são opcionais: o serviço antigo não manda. `timelineJson` = a IA lê o vídeo como
+ * linha do tempo JSON curta (novo); false = transcrição + chat + frames soltos (antigo, para comparar). */
+export type JudgeOptions = {
+ scanEnabled: boolean; scanIntervalS: number; vision: boolean; camDetect: boolean; faceTrack?: boolean; timelineJson?: boolean;
+};
+
+/** Equipe de IA (doc/clipador/EQUIPE-IA.md): quatro papéis, cada um com a sua IA. */
+export type AiRoleId = "scan" | "analyst" | "editor" | "judge";
+export type AiRoleProvider = Exclude;
+export type AiEffort = "" | "low" | "medium" | "high";
+export type AiImages = "mosaic" | "frames" | "none";
+export type ContextCheckId = "setup" | "payoff" | "who_what" | "standalone" | "intelligible" | "faithful" | "strong_open";
+export type AiRole = {
+ enabled: boolean;
+ provider: AiRoleProvider;
+ /** "" = padrão do provedor. */
+ model: string;
+ /** Raciocínio (só Codex); "" = padrão (baixo). */
+ effort: AiEffort;
+ /** Instruções do administrador, somadas às padrão (podem ser em português). */
+ extra: string;
+ /** Só varredura e analista. */
+ images?: AiImages;
+ // Só o juiz: checagens críticas, se pode ajustar o trecho e pôr frase de contexto, e quanto cada checagem
+ // não crítica tira da nota.
+ critical?: ContextCheckId[];
+ allowFix?: boolean;
+ allowContextLine?: boolean;
+ penalty?: number;
+ /** Só leitura (o serviço calcula): modelo efetivo e a ordem de tentativa (reserva) deste papel. */
+ resolvedModel?: string;
+ chain?: AiRoleProvider[];
+};
+export type AiRoles = Record;
export type JudgeConfig = {
provider: JudgeProvider;
/** Modelo do EDITOR (2º juiz). null com o juiz desligado. */
@@ -41,8 +73,37 @@ export type JudgeConfig = {
fallback?: { enabled: boolean; cooldownMin: number; chain: Exclude[] };
/** IAs em pausa depois de falha de indisponibilidade (`until` em ISO, UTC). */
pauses?: JudgePause[];
+ /** Equipe de IA (serviço novo): cada papel com a sua IA. Ausente = serviço antigo (um provedor só). */
+ roles?: AiRoles;
+ /** Instruções padrão de cada papel nos dois idiomas (só leitura). Só em GET/PUT /judge. */
+ roleDefaults?: Record;
+ /** Checagens do juiz de contexto (id + nome em português). */
+ checks?: { id: ContextCheckId; label: string }[];
+ /** Situação de cada IA (Configurações → IA): ligada, pronta e por que não. */
+ providers?: Partial>;
};
+/** GET /judge/report: medição da Equipe de IA (F0) — chamadas e tokens por papel, decisões do juiz e concordância com você. */
+export type AiReport = {
+ window: { days: number; since: string | null; sessionId: number | null; liveHours: number };
+ calls: {
+ role: string; purpose: string; provider: string; model: string; mode: string; calls: number; failures: number;
+ avgChars: number; avgImages: number; imageKB: number; tokensIn: number | null; tokensOut: number | null;
+ tokensCached: number | null; withUsage: number; avgMs: number;
+ }[];
+ perHour: Record;
+ clips: { total: number; byStatus: Partial>; approvalRate: number | null; labeled: number; noContext: number };
+ judge: { approve: number; adjust: number; discard: number; warn: number; error: number; contextLine: number };
+ agreement: Record<"judge" | "editor", AiAgreement>;
+};
+export type AiAgreement = {
+ pairs: number; agree: number; rate: number | null; kappa: number | null;
+ matrix: Record<"keep" | "discard", Record>;
+};
+
+/** Sua avaliação do corte (conjunto de avaliação do juiz). */
+export type OwnerLabel = "good" | "bad" | "no_context";
+
export type JudgePause = { provider: Exclude; until: string; reason: string };
export type ClipperChannel = {
@@ -188,9 +249,42 @@ export type ClipJudge = null
model: string; keep: boolean; score: number; reason: string; analysis?: ClipAnalysis | null; analystModel?: string;
/** Fonte em inglês: título, legenda e motivo em português (só para ler; o post sai em inglês). */
pt?: { title?: string; caption?: string; reason?: string };
+ /** Juiz de contexto (EQUIPE-IA.md). Ausente = juiz desligado, editor descartou ou corte de antes. */
+ context?: ClipContext;
+ /** "context" = quem descartou foi o juiz de contexto (dá para forçar o render). */
+ discardedBy?: "context";
}
| { error: string };
+export type ContextCheck = { ok: boolean; t: number | null; why: string };
+export type ClipContext =
+ | { error: string }
+ | {
+ model: string;
+ /** O que um espectador que nunca viu a live entende (escrito antes das checagens). */
+ viewerSummary: string;
+ checks: Partial>;
+ fix: { start_s: number | null; end_s: number | null; context_line: string };
+ confidence: number;
+ reason: string;
+ /** Fonte em inglês: resumo, motivo, frase e o porquê de cada checagem em português. */
+ pt?: { viewer_summary?: string; reason?: string; context_line?: string; checks?: Partial> };
+ /** O que o código decidiu pelas respostas. */
+ decision: "approve" | "adjust" | "discard" | "warn";
+ failed: ContextCheckId[];
+ failedCritical: ContextCheckId[];
+ solvedByLine: ContextCheckId[];
+ /** Frase de contexto que vai na tela no começo do corte ("" = nenhuma). */
+ contextLine: string;
+ scoreAfter: number | null;
+ /** Motivo da decisão, em português (montado pelo código). */
+ reasonPt: string;
+ /** Trecho novo quando o juiz ajustou. */
+ window?: [number, number];
+ /** 1ª rodada, quando houve ajuste (o juiz conferiu de novo). */
+ first?: { viewerSummary: string; checks: Partial>; failedCritical: ContextCheckId[]; reasonPt: string };
+ };
+
export type ClipTags = { risada?: number; susto?: number; hype?: number; clip?: number };
export type Clip = {
@@ -242,6 +336,9 @@ export type Clip = {
final?: ClipFinal | null;
/** O único arquivo que vai para as redes: o final pronto. null = ainda não (a publicação espera). */
publishFile?: string | null;
+ /** Sua avaliação (bom / ruim / sem contexto) para medir o juiz. Opcional: o serviço antigo não manda. */
+ ownerLabel?: OwnerLabel | null;
+ ownerNote?: string | null;
};
export type ClipFinal = {
@@ -551,6 +648,26 @@ export const TAG_LABEL: Record = { risada: "risada", sus
export const PROVIDER_LABEL: Record = { codex: "Codex (GPT)", claude: "Claude", gemini: "Gemini", off: "Desligado" };
+/** Equipe de IA: nome e o que cada papel faz (cartões da configuração). */
+export const ROLE_INFO: Record = {
+ scan: { label: "Varredura", does: "Assiste a live por janelas e propõe momentos mesmo sem pico de chat; descreve a tela para a linha do tempo." },
+ analyst: { label: "Analista", does: "Olha tela, fala e chat do trecho e diz o que aconteceu (lag, jogada, treta…). Não decide." },
+ editor: { label: "Editor", does: "Decide se vira corte, escolhe o trecho e escreve título, legenda e hashtags." },
+ judge: { label: "Juiz", does: "Só texto: vê o que vai no corte e confere se quem nunca viu a live entende — começo, desfecho, funciona sozinho." },
+};
+export const ROLE_ORDER: AiRoleId[] = ["scan", "analyst", "editor", "judge"];
+export const CHECK_LABEL: Record = {
+ setup: "começo (setup)", payoff: "desfecho", who_what: "quem/o quê", standalone: "funciona sozinho",
+ intelligible: "fala clara", faithful: "título fiel", strong_open: "abertura forte",
+};
+export const OWNER_LABEL: Record = {
+ good: { label: "Bom", tone: "success" }, bad: { label: "Ruim", tone: "danger" }, no_context: { label: "Sem contexto", tone: "warning" },
+};
+export const CONTEXT_DECISION: Record<"approve" | "adjust" | "discard" | "warn", { label: string; tone: Tone }> = {
+ approve: { label: "aprovou", tone: "success" }, adjust: { label: "ajustou o trecho", tone: "info" },
+ discard: { label: "descartou", tone: "danger" }, warn: { label: "avisou", tone: "warning" },
+};
+
/** Sessões que ainda mudam sozinhas (vale consultar de novo). */
export const ACTIVE_SESSION: SessionStatus[] = ["starting", "recording", "processing"];
/** Cortes que ainda mudam sozinhos (IA ou render). */
diff --git a/panel/src/components/clipper-clip-dialog.tsx b/panel/src/components/clipper-clip-dialog.tsx
index 24a0567..9ccbeec 100644
--- a/panel/src/components/clipper-clip-dialog.tsx
+++ b/panel/src/components/clipper-clip-dialog.tsx
@@ -6,7 +6,8 @@
import { useEffect, useState } from "react";
import { CLIP_STATUS, SOURCE_LABEL, clipperCall, formatClock, formatDuration, languageLabel, useClipperAction, type Clip, type ClipperSession } from "./clipper-client";
import {
- ChatSignals, ClipActions, ClipMedia, ClipVideoState, DeleteControl, FaceSignal, JudgeVerdict, TrimControl, situationLabel, type DeleteClip,
+ ChatSignals, ClipActions, ClipMedia, ClipVideoState, DeleteControl, FaceSignal, JudgeVerdict, OwnerLabelControl, TrimControl, situationLabel,
+ type DeleteClip,
} from "./clipper-clip-parts";
import { isOther, speakerLabel } from "./clip-editor-model";
import { Dialog } from "./dialog";
@@ -119,6 +120,7 @@ function ClipBody({ clip, onChanged, publishJobs }: { clip: Clip; onChanged: ()
+
{clip.status === "error" && clip.error && (
diff --git a/panel/src/components/clipper-clip-parts.tsx b/panel/src/components/clipper-clip-parts.tsx
index 6baf796..d71ad87 100644
--- a/panel/src/components/clipper-clip-parts.tsx
+++ b/panel/src/components/clipper-clip-parts.tsx
@@ -5,9 +5,9 @@
// confirmação curta no lugar. Nada aqui busca dados: tudo vem por props; cada ação chama `run` (useClipperAction).
import { useEffect, useRef, useState, type ReactNode } from "react";
import {
- ACTIVE_CLIP, CLIP_STATUS, DEV_LAYER_LABEL, FACE_LABEL, SITUATION_LABEL, TAG_LABEL, UNDELETABLE_CLIP, aspectOf, clipperCall, formatClock, formatDuration, formatScore,
- reviewHasDevLayers,
- type Clip, type ClipAnalysis, type ClipTags, type Situation, type useClipperAction,
+ ACTIVE_CLIP, CHECK_LABEL, CLIP_STATUS, CONTEXT_DECISION, DEV_LAYER_LABEL, FACE_LABEL, OWNER_LABEL, SITUATION_LABEL, TAG_LABEL, UNDELETABLE_CLIP, aspectOf,
+ clipperCall, formatClock, formatDuration, formatScore, reviewHasDevLayers,
+ type Clip, type ClipAnalysis, type ClipContext, type ClipTags, type ContextCheckId, type OwnerLabel, type Situation, type useClipperAction,
} from "./clipper-client";
import { ClipPublishButton } from "./clip-publish";
import { AlertIcon, CheckIcon, EyeIcon, RefreshIcon, ScissorsIcon, SparkIcon, TrashIcon, UndoIcon, XIcon } from "./icons";
@@ -250,10 +250,107 @@ export function JudgeVerdict({ clip }: { clip: Clip }) {
{(judge.pt?.reason || judge.reason) &&
{judge.pt?.reason || judge.reason}
}
+ {judge.context && }
>
);
}
+/** O JUIZ de contexto (EQUIPE-IA.md): o que um espectador frio entende, as checagens e o que o código decidiu. */
+export function ContextVerdict({ context }: { context: ClipContext }) {
+ if ("error" in context) {
+ return (
+
+
+ O juiz não conseguiu conferir o contexto (ficou a decisão do editor): {context.error}
+