Files
CenaForge/.claude/skills/cenaforge/references/clipper.md
T
MateuusandClaude Opus 5.5 ed31d52df0 IA: Claude, Codex e Gemini com login, chave de API e IA reserva; Configurações em subpáginas
- Configurações → IA (/settings/ai): um cartão por IA para instalar/atualizar a CLI pelo painel, ligar,
  entrar com a conta (OAuth pela própria CLI, num terminal) ou colar a chave de API, e testar.
  Chaves cifradas com a DPAPI do Windows em data/ai/vault.bin; só vão para a CLI no ambiente da chamada.
- Gemini CLI como terceiro agente do painel (stream-json, edição automática, shell só o liberado).
- IA reserva: execução que cai por indisponibilidade (cota, 429, login, chave, rede) pausa a IA e recomeça
  a mesma tarefa na próxima pronta da ordem; migração v10 (agent_runs.fallback_of).
- Configurações viraram subpáginas (IA, Publicação, Apps das redes, Navegador, Sobre os modos), também no
  menu lateral; links antigos apontam para a subpágina certa.
- Contrato com o Clipador em doc/ia.md; skill do CenaForge atualizada até a 1.51.0.

O login gratuito do Gemini CLI para conta pessoal foi encerrado pelo Google (IneligibleTierError): para
conta pessoal, use a chave do AI Studio.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-18 01:51:12 -03:00

568 lines
60 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Clipador (`clipper/`) — cortes automáticos de live
Fonte completa: **`clipper/README.md`**. Ele cobre a arquitetura, as regras da heurística, o juiz, a API,
o `.env` e os limites. Este arquivo só diz onde mexer e o que não pode quebrar. Não copie o README para cá.
## O que é
Serviço FastAPI local (Python 3.12, `clipper/.venv`) em `127.0.0.1:4520`. Ele grava uma live (Twitch, YouTube
ou Kick) ou um VOD, lê o chat, transcreve pelo serviço de voz e pede o veredito a uma IA pela CLI. Depois
renderiza cortes verticais (1080×1920, padrão) ou horizontais (1920×1080, YouTube). Toda rota, exceto `GET /health`, exige `X-Service-Key` (`CLIPPER_SERVICE_KEY` de
`clipper/.env`; nunca copie a chave).
| O quê | Onde |
|---|---|
| Banco do Clipador | `data/clipper/clipper.db` (`PRAGMA user_version` 12, `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`). Migra ao subir o serviço. **Nunca altere uma migração já aplicada** (o banco real estava em v4 quando a v7 nasceu): coluna nova = `ALTER` numa versão nova |
| Blocos gravados (`.ts` de 30 s + `segments.csv`) e frames | `data/clipper/sessions/<id>/` (frames em `frames/`) |
| Pesos do rastreio de reação (YuNet, MediaPipe, OpenSeeFace) | `data/clipper/models/`, fixados (URL imutável + sha256) em `clipper/models.lock.json` |
| Cortes prontos | `output/clipper/<sessão>/clip-<id>.mp4` + `clip-<id>.jpg` |
| Arquivos do editor (proxy, TTS) | `output/clipper/<sessão>/edit-<id>/` (narração em `tts-<hash12>.wav`) |
| Fontes empacotadas (ASS e prévia do painel) | `assets/fonts/` **plana** (Luckiest Guy Apache-2.0; Bangers, Anton, Bebas Neue, Poppins ExtraBold OFL-1.1; licença ao lado de cada `.ttf`), fixadas em `assets/fonts/fonts.lock.json` (URL presa a commit do google/fonts + sha256 + `family` = nome dentro do arquivo). Fonte nova: arquivo na pasta + entrada no lock (gotchas, item 105) |
| Vínculo canal → conta (painel) | tabela `account_channels` em `data/cenaforge.db` (migração **v3** do painel, `panel/src/lib/db.ts`; sem chave estrangeira para o canal) |
## Onde mexer
| Mudança | Arquivo(s) | Também atualizar |
|---|---|---|
| Captura (Streamlink → bomba Python → `ffmpeg -f segment`), linha do tempo, hora do chat, metadados (`title`/`category`) | `clipper/app/worker.py`, `sources.py` | `clipper/tests/` |
| Qualidade de gravação (`capture.quality`, argumentos do Streamlink, `OPTIONS` com GB/h, `record_run` → `sessions.capture_json`) | `clipper/app/capture.py`; validação `CAPTURE_QUALITIES` em `layout.py`; gravação do 1º bloco em `worker.py` | `clipper/tests/test_capture_quality.py` |
| Busca de quadro dentro de bloco `.ts` (`seek_args`, `grab_frame`) e emenda de resolução/codec (`uniform_segments`) | `clipper/app/media.py`; `clipper/app/editor_render.py`; `face.grab_bgr` e tamanho do quadro por bloco (`_frame_size`) em `face.py` | gotchas, itens 107–108 |
| Retomada de live (`Engine.live_check`, `keep_live`, `RESUME_DELAYS_S`, `resume_interrupted`), render que falha (`recover_orphan_renders`, `ORPHAN_RENDER_S` 300, `MAX_RENDER_ATTEMPTS` 3), cortes duplicados (`SAME_PEAK_S` 10, `SAME_MOMENT_OVERLAP` 0,6, `KEPT_STATUSES`/`VETO_STATUSES`, `discard_pending_duplicates`) | `clipper/app/worker.py` | `clipper/tests/test_resume.py`, `clipper/tests/test_render_and_duplicates.py` |
| Apagar cortes (`delete_clip`, `delete_many`, `select_ids`, `MAX_BATCH` 500, recusas `BUSY`/`PUBLISHED`/`CHANGED`, marca `marks`/`mark_spans`, arquivos só dentro das pastas do Clipador) | `clipper/app/clip_delete.py`; rotas em `main.py` (`ClipsDeleteIn`); marca lida em `worker.py` (veto depois do juiz) e na varredura (`intel.py`) | `clipper/tests/test_clip_delete.py`; `METHODS` em `panel/src/lib/clipper.ts`; seção "Apagar cortes" abaixo |
| 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 |
| Chat (IRC anônimo da Twitch com `CAP REQ :twitch.tv/tags` → emotes nativos e `room-id`; Pusher da Kick, emotes `[emote:id:NOME]`) | `clipper/app/chat.py` | — |
| Heurística: pesos, base de 3 min, mínimo proporcional (`_required_messages`), reações (`min_reactions`), chat fraco (`sparse_rate` 0,5 msg/s), momentos do chat/áudio/rosto (`_chat_moments`/`_audio_moments`/`_face_moments`; `face_*` em `Params`), `pick_peaks`, `fit_window` (duração de todo corte automático) | `Params` e funções em `clipper/app/scoring.py`; alvo `min_target` em `layout.py` | `clipper/tests/test_scoring.py` (regressões de falso positivo, chat fraco e rosto), `test_duration_banner_fonts.py` |
| Rastreio de reação — E/S: backends (MediaPipe; plano B OpenSeeFace), download sob demanda com sha256, recorte FFmpeg 6 qps, laço `face` | `clipper/app/face.py` (`for_scoring`, `must_wait`, `view`, `reset`); laço `_face_loop` e uso de `must_wait` na decisão do corte em `worker.py`; bancada `clipper/tools/face_bench.py` | `clipper/tests/test_face.py`, `clipper/models.lock.json`, `doc/FACE_BAKEOFF.md` |
| Rastreio de reação — lógica pura: sinal por segundo contra o neutro do streamer, rótulos, `reaction_moments`, `summarize` (linha do analista), `locate_cam` (câmera pelo rosto) | `ReactionParams` e funções em `clipper/app/reaction.py` | `clipper/tests/test_reaction.py` |
| Emotes: catálogo 7TV/BTTV/FFZ (canal + global, TTL 1 h, fonte que falha é ignorada), emojis, peso aprendido (`LEARN_UP`/`LEARN_DOWN` 0,3/0,15) | `clipper/app/emotes.py`; ingestão e aprendizado em `clipper/app/intel.py` (`ingest_chat`, `learn_from_clip`) | `clipper/tests/test_intel.py` |
| Contexto do jogo (categoria a cada `GAME_CHECK_S` 600, `screen_game`, perfil pela web; `clean_profile`, `save_profile`, `refine`, `delete_note`; perfis bilíngues, `add_game`, `delete_game`, `translate`, aliases, `import_seeds` de `clipper/app/seeds/games/*.json`; contrato em `doc/clipador/JOGOS.md`), varredura (`SCAN_*`), webcam (`detect_cam`: YuNet local primeiro, IA só se não achar ou `use_ai`; `CAM_RETRY_S` 300), opções `OPTION_DEFAULTS` (inclui `faceTrack`) | `clipper/app/intel.py` | README do Clipador |
| Juízes (analista + editor), prompts, glossário `CHAT_GLOSSARY`, linha "Rosto do streamer: …" do analista, schemas, chamada da CLI, pesquisa e refino do jogo (`PROFILE_SYSTEM`/`research_game`, `REFINE_SYSTEM`/`refine_game`), câmera | `clipper/app/judge.py`; montagem dos 6 frames do analista (8 se o trecho passa de 80 s) em `worker.py` | README do Clipador |
| Hashtags da legenda (`to_tag`, `fold`, `split_hashtags`, `compose`, `build_caption`; `MAX_TAGS` 8, `GAME_TAGS` 3, `MOMENT_TAGS` 4) | `clipper/app/hashtags.py`; uso em `judge_clip` de `worker.py`; campo `hashtags` em `judge.py` (`VERDICT_SCHEMA`, `PROFILE_SCHEMA`, `Verdict.hashtags`) e `PROFILE_LISTS`/`clean_profile`/`Intel.session_game` em `intel.py` — ver "Hashtags da legenda" abaixo | `clipper/tests/test_hashtags.py` |
| Configuração do corte: camadas padrão ← canal ← sessão ← projeto (`DEFAULTS`, `merge`, `validate`), `format.aspect` (`ASPECTS`, `FRAME_SIZES`, `CANVAS_SIZES`, `aspect()`), `MODES` (5 modos, inclui `cam_only`), `resolved_mode` (queda para `blur` sem câmera; `full` no horizontal), retângulos, legenda, crédito, `duration` (`min_target`), `hook` (`HOOK_STYLES`, `HOOK_ANIMS`, `HOOK_FONT`), `capture`; fontes empacotadas (`PACKAGED_FONTS`, `font_files`, `ass_filter` = `ass=` com `fontsdir` só se o ASS usar uma delas); cadeia de layout reutilizável `layout_chain(settings, src, dst, tail, suffix, mode)` (usada por `video_filter` e pelo editor) | `clipper/app/layout.py`; rotas de settings em `main.py` (devolvem `aspects`, `frames`, `fontFiles`, `hookStyles`, `hookAnims` e `captureQualities`) | `clipper/tests/test_format_and_captions.py` (o vertical precisa continuar batendo com `clipper/tests/data/vertical_golden_sha256.json`); modo novo também em `LayoutMode`/`MODE_LABEL` de `panel/src/components/clipper-client.ts` e `resolvedMode` de `clip-editor-model.ts`; grupo novo também em `CutSettings` (`Aspect`, `aspectOf`, `withFormat` para serviço antigo) |
| Projeto de edição: modelo, tempo sessão↔saída, `normalize_cuts`, `validate_project`, `auto_project` (projeto da IA), `pick_hook` (texto do gancho), `CAPTION_PRESETS`, `SUGGEST_SCHEMA`/`clean_suggestion` | `clipper/app/editor.py` | `clipper/tests/test_editor.py`, `clipper/tests/test_editor_layers.py`; tipos espelhados em `panel/src/components/clip-editor-model.ts` |
| Render do corte (ASS animado, gancho e tarja `banner`, textos, barra, chat na tela `chat_events`, filtergraph, trecho mudo, áudio, proxy, forma de onda, capa e capa no início) | `clipper/app/editor_render.py` (`render_project`, `build_filter`, `build_project_ass`); cores ASS via `layout.ass_color`/`ass_inline_color` | [gotchas.md](gotchas.md) itens 57, 71, 74–78, 104–105 |
| Reenquadramento do jogo (`reframe.keys`, `perspective_filter`) e camadas inseridas (`kind: "inset"`, decoração numpy/OpenCV), `EASES`, `MAX_KEYS` 60, `MAX_INSETS` 12 | `clipper/app/reframe.py`; validação em `editor.py`; grafo em `editor_render.py` | `clipper/tests/test_reframe_insets.py`; interpolação espelhada em `clip-editor-model.ts` (`easeAt`, `interpolate`, `reframeAt`) — as duas precisam dar o mesmo valor; gotchas, item 106 |
| Rotas do editor, `ensure_edit`, `render_clip_edit`, `chat_for` (mensagens da sessão para o chat na tela) | `clipper/app/editor_api.py`; chamado por `Engine.render_clip` em `worker.py` | `ALLOWED` e timeout em `panel/src/lib/clipper.ts` |
| Legenda (tempo saneado: `clean_words`, `group_words`, `caption_blocks`; `build_ass`) e crédito — usada pelo render do editor e pelo worker, nos dois formatos | `clipper/app/subtitles.py` (`MIN_WORD_S` 0,06, `MIN_STEP_S` 0,04). `media.render_vertical` ainda existe em `media.py`, mas **não** é mais usado pelo render de cortes | `clipper/tests/test_format_and_captions.py`; [gotchas.md](gotchas.md) itens 57–58, 70, 90 |
| Rotas HTTP | `clipper/app/main.py` (editor: `editor_api.py`) | `ALLOWED` em `panel/src/lib/clipper.ts` (o proxy recusa caminho fora da regex) e o timeout por rota no mesmo arquivo |
| Variáveis do `.env` | `clipper/app/config.py` + `clipper/.env.example` | tabela do README do Clipador |
| Páginas `/clipper/*` (grupo de rotas `panel/src/app/clipper/(studio)/`, layout com `ClipperProvider` + `ClipperShell`) | `clipper-provider.tsx` (dados + consulta periódica, `useClipper()`), `clipper-shell.tsx` (`CLIPPER_SECTIONS`, cabeçalho, bloco "Ao vivo agora · N"), páginas `clipper-clips-page.tsx` (+ `clipper-clip-table.tsx` `ClipTable`, `clipper-clip-dialog.tsx` `ClipDialog`, `clipper-clip-parts.tsx`), `clipper-sessions-page.tsx`, `clipper-session-detail.tsx`, `clipper-channels.tsx` (Fontes), `clipper-games-page.tsx` + `clipper-game-dialog.tsx` + `clipper-game-parts.tsx` + `clipper-games.tsx` (emotes), `clipper-settings-page.tsx`; peças compartilhadas em `clipper-sessions.tsx` (`PlatformIcon`, `CutNow`, `RecordForm`, relógio, `sessionHealth`) e utilitários da lista em `clipper-queue.tsx`; `clipper-cut-settings.tsx` modal do corte em 5 abas; `clipper-judge.tsx`; cliente `clipper-client.ts`. Mapa de rotas e papéis em [panel.md](panel.md#página-clipper-clipador) | [panel.md](panel.md) |
| Página do editor `/clipper/edit/[clipId]` | `panel/src/app/clipper/edit/[clipId]/page.tsx` + `panel/src/components/clip-editor*.ts(x)` (papel de cada arquivo em [panel.md](panel.md#editor-de-cortes)); tokens `--color-nle-*` e bloco `.nle` em `panel/src/app/globals.css` | [panel.md](panel.md#editor-de-cortes) |
| Ponte e proxy do painel | `panel/src/lib/clipper.ts` + `panel/src/app/api/clipper/[...path]/route.ts` | — |
| Fontes (canais de live) nos canais de publicação | `linkChannel`/`endChannel`/`accountsForChannel` em `panel/src/lib/accounts.ts`; rotas `panel/src/app/api/accounts/[id]/channels/`; card "Fontes de corte" em `account-manager.tsx`. Na UI "Canais" virou **"Fontes"**; código e rotas seguem `channels` | [panel.md](panel.md) |
| Publicação dos cortes | despachante do painel lê `GET /v1/clips` com `channel=` (fontes, separadas por vírgula), `status=ready,approved` e `ids=`; aprova (`PATCH status=approved`) e marca `published` | [publishing.md](publishing.md) |
## Como os momentos nascem (resumo; regras completas no README)
- `source` do corte: `chat`, `audio`, `face` (rosto forte com apoio), `ai` (varredura) ou `manual`.
- **Chat:** mínimo nos 8 s do pico = 3× a mediana recente, entre 4 (`min_peak_floor`) e 12 (`min_peak_messages`), e
≥ 2 reações (texto ou emote) — ou o dobro do mínimo em mensagens. Emote soma bônus + peso aprendido do canal.
- **Áudio:** sempre sem chat; também com chat fraco (< `sparse_rate` 0,5 msg/s).
- **Varredura** (`scanEnabled`, `scanIntervalS` 180, 60–900): a IA vê até 7 frames + fala + chat + perfil do jogo e
propõe 0–2 momentos; proposta com nota < 4 (`SCAN_MIN_PROPOSAL`) não vai aos juízes. Cada janela grava em
`sessions.memory_json` `proposals` (quantas a IA propôs) e `created` (quantas viraram candidato) e loga
"varredura <sessão> lo–hi s: N proposta(s), M candidato(s)": é por aí que se sabe se ela não propôs ou se foi barrada.
- **Aprendizado dos emotes:** aprovar/rejeitar no painel = ±0,3/0,15 nos emotes de −10 s a +6 s do pico, uma vez por
corte (`clips.learned`); a decisão da IA conta com `factor=0.5`. Peso limitado a −1…3.
## Juízes (decisão do usuário: pela CLI; chave de API só pelo cofre do painel)
- Provedores `codex` (padrão `gpt-6-luna`; lista de `~/.codex/models_cache.json`), `claude` (`haiku`/`sonnet`/`opus`),
`gemini` (`Judge._gemini`: `gemini -p <instrução curta> -o json --approval-mode plan --skip-trust -m <modelo>`, prompt
completo pelo stdin, schema no prompt e JSON extraído de `response`; frames copiados para pasta temporária **fora do
repo**, porque `@arquivo` respeita o `.gitignore`) ou `off` (só a heurística).
- **IA reserva por chamada** (18/11/2026): `clipper/app/ai_settings.py` lê `data/ai/settings.json` e o cofre
`data/ai/vault.bin` (DPAPI por `ctypes`; **só leitura**, quem escreve é o painel). Falha de indisponibilidade (cota,
429, login, chave, rede, CLI fora) pausa a IA e a mesma chamada segue na próxima pronta da `order`; erro de conteúdo
não troca. Contrato: `doc/ia.md`; visão geral e armadilhas: [ai.md](ai.md). Teste: `clipper/tests/test_ai_fallback.py`.
Só vale depois de reiniciar o Clipador (gotchas, item 144). Gemini com chave real e `@arquivo` de imagem: não testados.
- **ANALISTA** vê 6 frames (8 se o trecho passa de 80 s) + fala + chat + glossário e devolve `situation`, `what_happened`, `screen`, `speech`,
`chat_meaning`, `confidence` (0–1) e início/fim da ação. **EDITOR** vê só texto + a análise e escreve título,
legenda, nota e corte. Os dois podem recuar até `duration.backtrackS` (padrão 120 s) antes do candidato.
- `PUT /v1/judge`: provedor, `model` (editor), `analystModel` (vazio = o mesmo), `minScore`, `scanEnabled`,
`scanIntervalS`, `vision`, `camDetect`, `faceTrack`. Fica na tabela `settings`, sem reiniciar; o `.env` só dá o valor inicial.
- Codex: cada imagem com seu `-i`, todas antes do `-` final; `--search` é opção **global** (antes de `exec`).
- Custo fixo: cada chamada é um processo novo (2 por candidato). `codex_lean_overrides(search, config_file=None)` em
`judge.py` enxuga o Codex; o Claude leva `--setting-sources project,local`. Números e limites em
[token-economy.md](token-economy.md); teste: `test_codex_lean_overrides`. Vale após reiniciar o Clipador (gotcha 136).
- Chave de API do juiz vem só do cofre do painel (`authMode: "apiKey"`, variável só na chamada); não crie outro caminho de chave sem pedido do usuário. Corte manual é renderizado mesmo com nota baixa.
## Hashtags da legenda (`hashtags.py`)
Pedido do dono (17/11/2026): a IA põe as # certas, do jogo e da missão. A legenda do corte = texto + hashtags + crédito,
montada por `build_caption(text, tags, credit)` (partes separadas por linha em branco; o crédito é "🎥 Créditos: link").
- **Quem escolhe o quê:** o sistema fixa o **canal** (nome do streamer) e as do **jogo** (até 3 de `profile.hashtags`;
sem perfil ou sem a seção, o nome do jogo). A IA escolhe só as do **momento** (2–4 no campo `hashtags` do veredito:
missão, atividade, evento, modo, lugar, item ou personagem, de preferência com termos do perfil; sem genéricas e sem
repetir canal ou jogo). `JUDGE_SYSTEM` manda a `caption` sem hashtags; `split_hashtags` tira as que vierem no texto
e as junta às do momento.
- `compose(streamer, game, profile, moment)`: canal → jogo → até 4 do momento, sem repetidas (`fold`: sem #, acento e
maiúscula), até 8. `to_tag`: "ROB RUN" → `#ROBRUN`, "perseguição policial" → `#PerseguiçãoPolicial`; sem letra → `None`.
- `Verdict.hashtags` é tupla (padrão `()`); `_clean` aceita resposta sem `hashtags`. `_MOMENT` (varredura) **não** tem o
campo. Sem juiz ou com o juiz falhando, ainda saem as tags do canal e do jogo.
- Perfil do jogo: `PROFILE_SCHEMA` ganhou `hashtags` (3–6 que o público usa no TikTok, Shorts e Reels BR, a principal
primeiro); `PROFILE_SECTIONS` ganhou "Hashtags"; `clean_profile` normaliza com `to_tag`/`fold`. `game_context` também
passa as `mechanics` como termos para as tags do momento. `Intel.session_game(session)` devolve (nome, perfil) com o
mesmo critério do contexto.
- Painel: seção "Hashtags" (violeta, chips, editável, com chat) em `SECTIONS` e `ProfileView` de `clipper-games.tsx`;
`GameProfile.hashtags?` em `clipper-client.ts`. Armadilha de perfil sem a seção e de cortes antigos: gotchas, item 144.
- API: `GameRefineIn.section` aceita `"hashtags"` (chat da seção) e `GameProfileIn.hashtags` (lista, máx. 20) existe;
sem esse campo, salvar o perfil à mão apagaria as hashtags. Campo novo no perfil = acrescentar nos dois modelos de
`main.py`. Teste: `test_api_accepts_hashtags_in_profile_edit_and_section_chat`.
- Só vale depois de reiniciar o Clipador (gotchas, item 143). Limite: tags do momento dependem da CLI real; não testado
com IA real.
## Configuração do corte
- `GET/PUT /v1/channels/{id}/settings` (padrão do streamer) e `/v1/sessions/{id}/settings` (`settings_json`,
sobrescreve campo a campo). Modos `auto|blur|cam_top|game_only|cam_only`; `cam`/`game` = retângulos 0–1 do quadro
original. `cam_only` = câmera do streamer na tela inteira; `cam_top` e `cam_only` sem câmera marcada caem em `blur`.
- `format.aspect`: `vertical` (padrão, 1080×1920) ou `horizontal` (1920×1080, YouTube). No horizontal: quadro original
inteiro (ou `layout.game` recortado para preencher); `cam_only` continua valendo; `auto`/`blur`/`cam_top`/`game_only`
viram quadro inteiro (`resolved_mode` = `full`). ASS num quadro lógico 2560×1440 → tamanhos em px do JSON saem a
75 %; legenda automática a 85 % da altura; crédito no canto direito. Tabela de tamanhos no README do Clipador.
- `duration`: padrão `{minS: 60, maxS: 90, backtrackS: 120}`; limites `minS` 5–120, `maxS` 15–180, `backtrackS` 0–120 e
`minS` < `maxS` (senão `LayoutError`). Para Shorts de terceiros, baixe o canal para ≤ 60 s. **Todo corte automático
sai com ≥ `minS` + 1 s e ≤ `maxS`** (`layout.min_target` = `minS` + 1,1 s, por `scoring.fit_window`): heurística,
varredura, juízes, `auto_project` (depois de silêncios e aparos), remoção de silêncio e "IA sugere". Faltando
material, o corte cresce para trás (no começo da gravação, para a frente); gravação menor que o mínimo não inventa
vídeo. "Cortar agora" e a edição à mão continuam livres. Não reintroduza ajuste de início/fim fora de `fit_window`
(gotchas, item 103).
- `hook` (estilo do gancho que o projeto da IA põe na abertura): `{style: plain|banner, bg, color, font,
anim: pop|fade|none|slide, seconds 1–8}`; padrão `banner`, `#00FF00`, `#FFFFFF`, Luckiest Guy, `slide`, 3 s. Tudo em
ASS, sem filtro extra (entrada `slide` em duas camadas: gotchas, item 104).
- Fontes (`caption.font`, `hook.font`, `font` dos textos): as do Windows (Arial Black, Arial, Impact, Verdana, Segoe UI
Black, Trebuchet MS) e as empacotadas de `assets/fonts/` (sha256 conferido ao carregar). Nome = família de dentro do
arquivo ("Poppins ExtraBold").
- `capture.quality`: `best` (padrão) | `1440p` | `1080p` | `720p` | `480p` (teto), por canal e por sessão (não por
corte); vale na **próxima** gravação ou retomada. `CLIPPER_QUALITY` não é mais lida. Detalhes em "Qualidade de
gravação" abaixo.
- `GET …/settings` devolve `own`, `effective`, `defaults` (com `format`, `duration` e `hook`), `modes`, `fonts`,
`fontFiles` (`{família: "assets/fonts/…ttf"}`), `hookStyles`, `hookAnims`, `aspects`, `frames`
(`{vertical, horizontal: {width, height, canvasWidth, canvasHeight}}`) e `captureQualities`
(`[{id, label, maxHeight, gbPerHour, gbPerHourMax, hint}]`). O formato do arquivo renderizado fica em `clips.aspect` e
sai no JSON do corte (antes do 1º render, `vertical`).
- Webcam: `POST /v1/sessions/{id}/detect-cam` (YuNet local em 12 quadros, sem IA; a IA olha 3 frames só se o local
não achar rosto e `vision` estiver ligada, ou com `?ai=true`) ou automática nos 2 primeiros blocos, se `camDetect`.
`cam_json.source` = `yunet` | `ai` | `manual`. Prévia sem salvar (no formato efetivo): `POST …/preview`; quadro: `GET …/frame?t=`.
- Jogo da sessão: `PUT /v1/sessions/{id}/game` trava a troca automática. Emotes do canal:
`GET /v1/emotes?channel=twitch-<login>`.
- Timeouts do proxy do painel: 8 min para `games/*/(research|refine)`, 5 min para
`clips/*/(proxy|preview-render|retranscribe|tts|suggest|waveform)`, 3 min para `detect-cam|preview|check`, 30 s para
`sessions/*/face(/reset)`, 2 min o resto.
## Qualidade de gravação (`capture.py`)
Fonte completa (tabelas de nomes de stream e de custo): seção "Qualidade de gravação" de `clipper/README.md`.
- Streamlink: `best` (ignora `audio_only` e `*_portrait`); teto = `--stream-sorting-excludes >{teto}60` com
`best,worst-unfiltered` (sem nada abaixo do teto, pega a menor variante: nunca falha pela qualidade). Twitch com
`best`/`1440p`: `--twitch-supported-codecs h264,h265` (o 2K vem em HEVC). AV1 não é pedido (FFmpeg local sem
libdav1d). Sem opção de 30/60 qps (o topo é quase sempre 60 qps; o corte sai em 30 qps).
- Gravado de fato: `ffprobe` do 1º bloco de cada execução → `sessions.capture_json` → `capture` em
`GET /v1/sessions/{id}` (`quality`, `width`, `height`, `fps`, `codec`, `kbps`, `gbPerHour`, `fromIdx`, `runs`,
`mixed`); `null` = sessão antiga (≤ 720p). Painel: "gravando em L×A · fps" no cartão da sessão.
- Medido (17/11/2026, trecho real do skipnho): disco/hora 720p60 1,5 GB, 1080p60 3,6 GB; 1440p60 4,7–4,9 GB/h só com
blocos **gerados** do 1080p (nenhuma live 2K no ar). Render de 60 s com NVENC 6,2–6,7 s em qualquer resolução. A
câmera recortada no vertical sai mais nítida em 1080p que em 720p; 2K ampliado não ganha nada.
- O que existe nas plataformas (17/11/2026): Twitch quase sempre até `1080p60` (+ `*_portrait` em 9 de 143 canais);
Kick até `1080p60`; YouTube pelo Streamlink para em 1080p, até em live "4K".
- Retomada pode trocar de qualidade: o render e o proxy uniformizam o trecho que atravessa a emenda (gotchas, item 108).
## Retomada, render que falha e cortes duplicados (`worker.py`)
Regras completas em "Armadilhas já resolvidas" do README do Clipador.
- **Retomada:** `Engine.live_check` devolve `live` / `offline` ("No playable streams…") / `unknown` (timeout, erro,
JSON inválido). `keep_live` tenta de novo com esperas `RESUME_DELAYS_S` (0, 10, 20, 40, 60, 90, 120 s ≈ 5,7 min)
antes de processar; enquanto tenta, a sessão fica `interrupted`. Vale na subida e para a captura que cai no meio da
live. Só processa depois de esgotar as tentativas ou de ver `offline` 2 vezes seguidas; 3 retomadas seguidas sem
bloco novo desistem. `POST /v1/sessions/{id}/resume` vale para qualquer live que não esteja gravando.
- **Render:** qualquer exceção no render marca o corte `error` com a mensagem e a fila segue. `rendering` órfão há
mais de 5 min volta para `pending`; na 3ª vez vira `error`.
- **Duplicados:** o candidato guarda a janela original (`reasons.candidateStartS/EndS`) e não nasce se o pico estiver a
≤ 10 s de outro corte ou sobrepuser o trecho final ou a janela original de qualquer corte (inclusive `discarded`).
O corte apagado conta como existente (marca em `deleted_clips`, ver "Apagar cortes").
Depois do juiz, o trecho final é conferido contra `VETO_STATUSES` (= `KEPT_STATUSES` pendente/renderizando/pronto/
aprovado/publicado **+ `rejected`**) e contra os apagados que estavam num desses estados: "mesmo momento" (pico a
≤ 10 s ou ≥ 60 % do trecho mais curto coberto) vira `discarded` com "Duplicado do corte N (mesmo momento | que você
rejeitou | que você apagou)" (`judge.duplicateOf`). O descartado pela IA **não** veta o trecho final. "Cortar agora"
(manual) só ganha `judge.warning`. Antes de cada render, `discard_pending_duplicates` usa o **mesmo veto**: tira da
fila o pendente/renderizando igual a um corte pronto, aprovado, publicado ou rejeitado, a um apagado que estava num
desses estados ou a um pendente mais antigo, com o mesmo motivo "Duplicado do corte N (…)". Descartado pela IA não
veta; manual, exportado do editor e o que está renderizando agora nunca saem. Duplicados já prontos não são
mexidos: rejeite ou apague à mão.
## Apagar cortes (`clip_delete.py`)
Fonte completa: seção "Apagar cortes" e tabela "API" de `clipper/README.md`.
| Rota | Faz |
|---|---|
| `DELETE /v1/clips/{id}[?confirmPublished=true]` | 200 `{id, sessionId, status, removedFiles, left: [{file, reason}]}`; 404 `not_found`; 409 `{error, code}` com `busy_candidate`, `busy_rendering`, `published` ou `changed` |
| `POST /v1/clips/delete` `{ids: [≤ 500]}` **ou** `{statuses, sessionId?}`, `confirmPublished?` | 200 `{requested, remaining, deleted, failed: [{id, code, reason}]}`; 400 sem os dois, com os dois ou `sessionId` com `ids`; 422 acima de 500 ou estado inválido |
- Recusa `candidate`, `rendering` e o `pending` que o motor já pegou (`engine._rendering`, sob o mesmo `engine.lock`
do render). `published` só com `confirmPublished`. Cada corte do lote segue as mesmas regras; recusado vai em `failed`.
- Some: linha em `clips`, `edits`, `clip-<id>.*`/`clip-<id>-*` em `output/clipper/<sessão>/`, a pasta `edit-<id>/` e os
quadros do juiz `frames/clip<id>-*.jpg`. Os blocos `.ts` ficam (são da sessão). Só apaga dentro de
`CLIPPER_OUTPUT_DIR`/`CLIPPER_DATA_DIR`, com caminho resolvido; link ou junção some só o link; o que não pôde vai em
`left` com o motivo.
- **O momento apagado não volta:** a marca em `deleted_clips` (pico, trecho final, janela original, estado) entra no
anti-duplicado do candidato (`find_new_clips`), na varredura (`mark_spans`), no veto depois do juiz e na limpeza da
fila antes do render (`discard_pending_duplicates`), nos dois só se o estado era de `VETO_STATUSES`. Não apague a marca para "liberar" o momento sem pedido.
- Proxy do painel: `METHODS` em `panel/src/lib/clipper.ts` aceita só POST em `clips/delete` e só GET/PATCH/DELETE em
`clips/{id}` (outro método = 405). O painel manda os **ids que está mostrando**, nunca `statuses`: corte que chega
depois da confirmação não é apagado junto. UI em [panel.md](panel.md#página-clipper-clipador).
## Rastreio de reação (rosto do streamer)
Fonte completa: seção "Rastreio de reação" de `clipper/README.md`; plano e licenças em `doc/PLANO_RASTREIO_REACAO.md`;
medições em `doc/FACE_BAKEOFF.md`. Roda no PC, sem IA. Opção `faceTrack` (padrão ligada; `PUT /v1/judge`).
- **Stack (licenças livres para publicar):** YuNet `face_detection_yunet_2026may.onnx` (MIT, `cv2.FaceDetectorYN` do
OpenCV 5) acha a câmera; MediaPipe Face Landmarker (Apache-2.0, 478 pontos + 52 blendshapes) mede expressões;
OpenSeeFace `.onnx` (BSD-2) é o plano B (só posição, sem expressões). **Não use** SCRFD/InsightFace, YOLO-Face,
LibreFace, OpenFace 3.0 nem Py-Feat: licença incompatível com publicação.
- **Fluxo:** `face.py` (E/S) recorta a câmera +10 % pelo FFmpeg (~384 px, 6 qps, `rgb24` por pipe) → MediaPipe em
modo VIDEO, um landmarker por bloco → tabela `face_track` (status `done`/`no_cam`/`error`), `cx`/`cy`/`size` no
**quadro inteiro**. `reaction.py` (lógica pura, sem cv2/mediapipe) faz o resto. Câmera trocada → série refeita.
- **Câmera pelo rosto** (`locate_cam`): grupo de rostos estável em ≥ 50 % dos quadros **e** confiança média do grupo
≥ `ReactionParams.min_cam_score` (0,7). Webcam real dá 0,92–0,94; desenho de rosto em live sem câmera dá 0,61–0,66
(gotchas, item 92). Não baixe esse piso sem medir.
- **Sinal:** z robusto de cada canal contra o neutro dos últimos 180 s do próprio streamer; rótulos `risada`, `grito`,
`susto`, `choque`, `raiva`, `confuso`. Ajuste por `ReactionParams` (pisos por canal, pesos, limiares).
- **Cortes:** rosto **reforça, não manda.** `reasons.face` + bônus ≤ 0,6 em momentos do chat/áudio; fonte `face` só
com z ≥ 6 **e** apoio (áudio suavizado ≥ 1,5 ou ≥ 2 mensagens de reação). A decisão do corte espera o rosto do
trecho (no máximo 2 blocos atrás da transcrição). O analista recebe a linha "Rosto do streamer: …" — exceto
quando a série da sessão é do plano B OpenSeeFace (sem blendshapes): aí `FaceService.summary` não manda linha.
- **Modelos:** `setup.ps1` passo 6b baixa e confere o sha256; o serviço baixa sob demanda se faltar. Falha de modelo
não marca blocos: nova tentativa em 5 min. Modelo novo = entrada em `clipper/models.lock.json` com URL imutável +
sha256 + licença.
- **Dependências** (`clipper/requirements.txt`): `mediapipe`, `opencv-contrib-python`, `numpy`, `onnxruntime` —
versões em [tools.md](tools.md). Nunca instale `opencv-python-headless` junto (gotchas, item 80).
- **Rotas:** `GET /v1/sessions/{id}/face?from=&to=` (série, `signal`, picos, câmera, progresso) e
`POST …/face/reset`. Ambas na regex `ALLOWED` do painel.
- **Bancada** (lê o banco só para leitura, saída em `output/face-bench/`):
`clipper\.venv\Scripts\python.exe clipper\tools\face_bench.py --session 3`. Armadilhas: [gotchas.md](gotchas.md) itens 79–84 e 92–95.
- **Instância de teste isolada** (receita em "Variáveis" de `clipper/README.md`): `CLIPPER_PORT=4521`,
`CLIPPER_DATA_DIR=output/<teste>/data`, `CLIPPER_OUTPUT_DIR=output/<teste>/clips` no ambiente (padrões:
`data/clipper` e `output/clipper`; as duas precisam ficar **dentro** do repo, senão `ConfigError` em
`clipper/app/config.py`), juiz `off`, e o `sqlite_sequence` de `sessions` do banco novo em 90000 antes da 1ª sessão
(gotchas, item 93). Cuidados com cópia do banco real: item 77.
## Editor de cortes (`/clipper/edit/<id>`)
Fonte completa: seção "Editor de cortes" de `clipper/README.md` (campos do projeto, render, medições, limitações).
Pesquisa de referência (OpenCut, effectcraft, Descript, Submagic etc.; nenhum código copiado):
`doc/clip-editor-research.md`.
- **Um caminho só de render:** `Engine.render_clip` (`worker.py`) → `editor_api.ensure_edit` (gera o projeto da IA se
o corte não tem) → `editor_api.render_clip_edit` → `editor_render.render_project` (FFmpeg). Não reintroduza
render que contorne o projeto de edição.
- **Formato:** o projeto pode trocar o formato só daquele corte em `settings.format` (mesma validação de
`layout.validate`); projeto antigo sem `format` segue canal/sessão. Export, `preview-render` e capa saem no formato do
corte (1080×1920 ou 1920×1080). O Programa do painel segue o formato do corte (tamanhos de `frames`; em 16:9 no
horizontal).
- **Projeto da IA** (`editor.auto_project`): trecho `action_start_s − 0,8 s … reaction_end_s + 0,8 s`, encaixado em
palavras e depois em `fit_window` (≥ `minS` + 1 s, ≤ `maxS`; o início só adianta se o mínimo continuar); tira vãos
≥ 2 s sem fala, quietos (< −38 dBFS) e a mais de ±3 s do pico; legenda
Whisper preset `pop` (tempo saneado por `subtitles.py`); gancho por `pick_hook` (regra abaixo) no estilo do grupo
`hook`; zoom 1,25× no `peak_s` (no rosto em `cam_top`); capa no pico; `meta.origin = "ai"` com data, modelo e passos.
**A IA não propõe reenquadramento nem camadas inseridas** (o analista não devolve região da tela).
- **Gancho (`editor.pick_hook`):** o `hook` do analista só vale se tiver ≤ 8 palavras, ≤ 48 caracteres e nenhum tempo
da gravação (3+ dígitos seguidos de "s"); senão vale o título do editor. Em qualquer caso a menção ao tempo
("Aos 5085s, …") é removida, a 1ª letra vira maiúscula e o texto para em palavra inteira até 60 caracteres.
- **Origem:** `edits.ai_project_json` guarda o projeto da IA ("Projeto da IA" no editor volta a ele). PUT do editor
marca `origin = 'user'`. Rejudge (corte volta a `pending`) apaga **só** edit de origem `ai`; o do usuário fica.
- **Tempo:** `cuts`, palavras, textos, zoom, narração e capa em tempo da sessão; só o gancho em tempo de saída.
- **Validação forte** em `validate_project` (3–180 s, limites de quantidade, texto escapado no ASS, áudio só de
`assets/` ou dos TTS do editor, nada vira shell). Campo novo no projeto = validação com valor padrão (projeto
antigo continua abrindo) + teste em `clipper/tests/` + tipo em `clip-editor-model.ts`.
- `clip_view` devolve `edit: {updatedAt, exportedAt, cover, origin}` (o painel decide "Editar"/"Continuar edição").
Campos das camadas (tabela completa do projeto em "Tempo e modelo do projeto" do README):
| Campo | Regra |
|---|---|
| `cuts[].mode` | layout só daquele trecho: um de `MODES` ou `null` (= o do corte) |
| `cuts[].muted` | trecho sem o áudio da live (`volume=0` no trecho; narração e música continuam). `normalize_cuts` só junta trechos encostados com o mesmo `mode` **e** o mesmo `muted` |
| `overlays[].x` (gancho e texto) | posição horizontal 0,05–0,95; ausente = 0,5. `y` 0,04–0,96. No zoom, `x`/`y` (0–1) são o foco |
| `overlays[]` `hook`/`text`: `style`, `bg`, `color`, `font`, `anim` | opcionais. `style` `plain` (padrão) ou `banner` (tarja na largura toda, centrada em `y`, maiúsculas em até 2 linhas; a fonte diminui em vez de cortar palavra); `font` = uma de `fonts`; `anim` ganhou `slide`. Sem esses campos, renderiza idêntico ao de antes |
| `overlays[]` `kind: "inset"` | camada inserida: `start`/`end` (sessão), `src` `{x, y, w, h}` (recorte 0–1 do quadro original), `x`/`y` (centro na saída), `size` 0,1–1 da largura, `border` (`#RRGGBB`/null), `borderW` 0–40 (6), `radius` 0–200 (18), `shadow` (true), `anim` `pop`\|`fade`\|`slide`\|`none`, `keys` opcionais `[{t, x, y, size, ease}]`. Até 12. Ordem do array = empilhamento: acima do vídeo e do zoom, abaixo do ASS (legenda, gancho, textos, chat). **Não entra na capa** |
| `reframe` | `{keys: [{t, cx, cy, w, ease: smooth\|linear\|hold}]}`, até 60, `t` em tempo da sessão, `cx`/`cy`/`w` (0,05–1) absolutos no quadro original; a altura sai da área do jogo do layout do trecho (nunca distorce). Com keys, `layout.game` é ignorado; não vale em `cam_only`; no `blur`, `game_only` e horizontal ocupa a tela toda. A capa usa a janela parada do instante dela |
| `chat` | chat da live na tela: `enabled` (padrão `false`), `x` 0–0,9 (borda esquerda), `y` 0,1–0,98 (base do bloco), `width` 0,25–0,96, `lines` 1–10, `size` 18–64, `showUser`. `chat_events` redesenha o bloco a cada mensagem; ele some 9 s depois da última (`CHAT_HOLD_S`) |
| `cover.atStart` | a capa também cobre os 2 primeiros quadros do MP4 (0 s). Exige `cover.enabled`; `render_clip_edit` gera a capa antes do vídeo e a passa como `cover_file`. `preview-render` também põe a capa quando `fromS` = 0 |
**Editar com a mão** (arrastar e aparar palavra, deslizar e dividir trecho, mover texto/legenda/chat no monitor,
marcar a câmera só daquele corte): tabela "Mexer com a mão" do README; componentes e atalhos em
[panel.md](panel.md#editor-de-cortes).
Limites do editor (lista completa em "Limitações" do README):
- **Uma trilha de vídeo só, sem B-roll.** A timeline é o tempo da sessão: um pedaço não vai para outra camada nem
toca fora da ordem da gravação. Não prometa reordenar trechos.
- A prévia do Programa é um canvas; a exata é `preview-render` (no formato do corte). Legenda e recorte de câmera/jogo
já saem como no render: blocos por `cleanWords`/`groupWords`/`captionBlocks` (porte de `subtitles.py`, constantes em
`CAPTION_TIMING` de `clip-editor-model.ts`) e recorte por `ffmpegCropFill` (arredondamento par do FFmpeg, tamanho da
gravação de `session.capture`). **Mudou constante ou regra em `subtitles.py`, ou a cadeia `layout_chain`, mude o
porte junto.** Tarja a ~2 px do render (informado).
- Reenquadramento no 9:16 com câmera em cima: a área do jogo é 1080×1268 (proporção ~0,85), então um inventário 16:10
não cabe inteiro; a janela mostra no máximo 0,48 da largura. No 16:9 cabe.
- Custo medido (corte 61, 60 s, NVENC): sem nada 6,1–6,2 s; com reenquadramento 7,1–9,5 s; com reenquadramento +
2 camadas 15,8–20,5 s.
- Campo novo (`cam_only`, `muted`, `chat`, `cover.atStart`, texto com `x`, `style`/`font` do gancho, `reframe`, `inset`)
só vale no serviço reiniciado (gotchas, item 73).
Rotas (todas com `X-Service-Key`; todas na regex `ALLOWED`):
| Rota | Faz |
|---|---|
| `GET/PUT/DELETE /v1/clips/{id}/edit` | projeto; PUT manda `rev` e recebe 409 se outro salvou antes |
| `POST …/proxy` `{lo,hi}` · `GET …/waveform?lo=&hi=` | prévia 480p (`-g 15`) e forma de onda (50 picos/s) da janela |
| `POST …/preview-render` `{fromS, durationS ≤ 10, project?}` | prévia real de poucos segundos |
| `POST …/export` | volta para a fila de render → `ready` |
| `POST …/retranscribe` `{startS, endS}` (≤ 90 s) | Whisper de novo no trecho |
| `POST …/tts` `{text, voice, speed}` | narração pelo serviço de voz (4510) |
| `POST …/suggest` | IA (`Judge.ask`) sugere gancho, título, início/fim, trechos mortos e zooms |
Teste local do editor sem tocar no serviço do usuário: instância na faixa 4500–4599 (ex.: 4521) sobre **cópia** do
banco, com as regras do item 77 de [gotchas.md](gotchas.md). Teste de UI no painel do usuário sobre um corte real:
intercepte as escritas (item 86) e ache as camadas do canvas pelo cursor (item 85).
## Parar é parar e idioma (18/11/2026)
Texto completo no README do Clipador ("Parar é parar", "Idioma por fonte e por sessão").
- **Parar à mão pausa o monitor da fonte.** `POST /v1/sessions/{id}/stop` (corpo opcional `{"pauseMonitor": false}`;
padrão `true`) grava `channels.monitor_paused_at` + `monitor_paused_session`; o monitor pula a fonte pausada. Limpam a
pausa: `PATCH /v1/channels/{id}` com `{"monitor": true}`, `POST /v1/sessions` (gravar pelo link) e `resume` pelo painel.
Queda de live (captura cai sozinha) **não** passa pela pausa: continua `keep_live`, na mesma sessão. Na UI: a fonte
mostra "monitor pausado · você parou a sessão #N" com **Religar**; o diálogo de parar tem a opção de voltar a gravar
sozinho (marcada = não pausa).
- **Idioma.** `language` em `channels` e `sessions` (`pt-BR`, `en-US`, `es-419`; `''` = `CLIPPER_LANGUAGE`), aceito em
`POST/PATCH /v1/channels` e `POST /v1/sessions`; as visões de fonte, sessão e corte devolvem o idioma **já resolvido**.
O Whisper usa o idioma da sessão; fora de pt-BR os prompts do editor e da varredura recebem a nota de idioma de saída.
No painel, `accounts.language` (migração v9 do painel, padrão `pt-BR`) e o aviso no diálogo Publicar quando o idioma do
canal difere do idioma do corte. Versões traduzidas de um mesmo corte: **ainda não existem** (próxima etapa).
- Sem reiniciar o Clipador as rotas novas não valem; o painel trata `language`/pausa como opcionais e não quebra
(gotchas, item 166).
## Perfil do jogo (aba Jogos)
Fonte do contrato: `doc/clipador/JOGOS.md`; seção "Contexto do jogo" de `clipper/README.md`. Toda rota abaixo devolve a
lista inteira (mesma forma de `GET /v1/games`), exceto onde dito.
**Dois idiomas.** `profile` = português (o que o painel mostra); `profileAi` = inglês (vai nos prompts; `null` = não
traduzido, a IA usa `profile`); `aiLanguage` `en-US`; `translatedAt`; `aliases` (união dos dois perfis). Campos novos do
perfil: `aliases` (≤ 10), `missions` `[{name, chapter, summary, completion_triggers ≤ 8 de 200 caracteres}]` (até 120;
`[]` quando não há lista pública — a IA nunca inventa) e `end_triggers` (≤ 12, sinais gerais de fim de missão).
`game_context` (`judge.mission_lines`: `MISSIONS_IN_PROMPT` 25, `MISSIONS_PROMPT_CHARS` 1500) manda terminar o corte de
missão logo depois do gatilho de fim. Busca por nome casa `id` **ou** alias (categoria "Grand Theft Auto VI" e tela
"GTA 6" = mesmo jogo).
| Rota | Faz |
|---|---|
| `GET /v1/games` | perfis com `status`, `error`, `model`, `researchedAt`, `editedAt`, `translatedAt`, `notes` (`[{text, at, section?}]`), `aliases`, `profile`, `profileAi` |
| `POST /v1/games` `{name, notes?}` | cadastra (201, `{games, id}`, status `pending`) e pesquisa em segundo plano; 409 se o `id` ou um alias já existe |
| `DELETE /v1/games/{id}` | apaga o jogo (sessões não mudam; volta a ser pesquisado se o jogo reaparecer); 404 se não existe |
| `POST /v1/games/{id}/research` | refaz o perfil do zero pela web **em inglês** e traduz para português (`RESEARCH_TIMEOUT_S` 420); os pedidos guardados entram no prompt |
| `POST /v1/games/{id}/translate` | gera o inglês a partir do português (jogo de antes dos perfis bilíngues) |
| `PUT /v1/games/{id}?lang=pt\|en` | grava a edição à mão no idioma `lang` (padrão `pt`) e traduz para o outro; sem IA, grava e deixa o outro desatualizado. Campos: `name`, `summary`, `genre`, `mechanics`, `clip_worthy`, `avoid`, `jargon`, `news`, `hashtags`, `sources`, `aliases`, `missions`, `end_triggers` |
| `POST /v1/games/{id}/refine` | `{instruction, search, section, history}` → `{games, reply}`. Aplica no inglês e responde em português. `instruction` 3–1500 caracteres; `search` padrão `true` (`false` = sem web, `TIMEOUT_S` 240); `section` `""` \| `summary` \| `clip_worthy` \| `avoid` \| `mechanics` \| `news` \| `jargon` \| `hashtags` \| `sources` \| `missions` \| `end_triggers` \| `aliases` (`Literal` em `GameRefineIn` de `main.py`, inválido dá 422); `history` `[{role: "user"\|"ai", text ≤1500}]`, máx. 20. A IA devolve o perfil inteiro + `reply`; guarda o pedido (com `section`) e marca `edited_at` |
| `DELETE /v1/games/{id}/notes/{index}` | esquece um pedido guardado (o perfil atual fica como está) |
- Tradução que falha (ou IA desligada): a outra versão fica como estava (na pesquisa, as duas em inglês), `error`
explica e `translatedAt` não muda. Tradução nunca mexe em nome, hashtags, fontes e outros nomes, e é recusada se
perder missões.
- **Sementes:** `clipper/app/seeds/games/*.json` (`{name, aliases, researchedAt, sources, profileAi, profile}`) é
importado na subida **só se o jogo não existe**. Hoje: `gta-vi.json` (GTA VI lança 19/11/2026, sem lista oficial de
missões; a semente traz 4 do vídeo "An Extended Look" com nomes descritivos **não oficiais** — pesquisar de novo
depois do lançamento; gotchas, item 167).
- Proxy do painel (`panel/src/lib/clipper.ts`): `ALLOWED` aceita `games/<id>/(research|refine|translate|notes/n)`;
`METHODS` dá GET/POST a `games` e PUT/DELETE a `games/<id>`; timeouts: 8 min `research|refine`, 5 min `translate` e
`PUT`, 30 s `POST games`.
- `clean_profile` (`intel.py`) normaliza tudo que entra: apara, tira vazios e duplicados, no máximo 20 itens por lista.
São guardados os últimos 30 pedidos.
- **Pedido guardado sobrevive a "Pesquisar de novo"** (`research_game(name, title, notes)`; `PROFILE_SYSTEM` manda
priorizar os pedidos sobre a pesquisa). **Edição à mão não sobrevive.** Por isso o painel pede confirmação
quando há `editedAt`. Para algo durar, prefira o pedido à IA.
- Refino (`judge.py`): `refine_game(name, profile, instruction, search, section, history)` usa `REFINE_SCHEMA`
(= `PROFILE_SCHEMA` + `reply`) e `PROFILE_SECTIONS` (chave → título). A IA vê só os últimos 8 turnos do
`history`, 400 caracteres cada. `REFINE_SYSTEM` manda mexer só na seção em foco e transformar pedido genérico
em item concreto ("reação do streamer conta" → "Streamer grita, xinga ou ri alto logo depois de uma morte ou fuga").
`Intel.refine(...)` (`intel.py`) devolve `(profile, reply)`.
- Painel: lista em `/clipper/games` e modal por `?game=ID` (`clipper-game-dialog.tsx`, `clipper-game-parts.tsx`); o chat
`AiChat` tem a chave "Confirmar na web" **desligada** por padrão, embora a API use `search=true`. A conversa só existe
enquanto o chat está aberto; o que fica salvo é o pedido (aba "Pedidos à IA", com X). Tipos `Game`, `GameProfile`,
`GameMission` em `panel/src/components/clipper-client.ts`. Detalhes visuais em [panel.md](panel.md).
## Regras
- **Aprovar publica** nas redes dos canais de publicação ligados à fonte (pelo despachante do painel; aprovar vale
para todas as redes). O painel marca o corte `published` quando todos os jobs dele saíram. Exportar no editor
volta o corte para `pending` e cancela os jobs ainda não enviados (voltam quando o corte fica pronto de novo).
Regras em [publishing.md](publishing.md). Corte aprovado **sem fonte ligada** (ou em outra rede) sai pelo botão
**"Publicar"** do cartão (`clip-publish.tsx`; em `published` vira "Publicar em outra rede"): ver publishing.md.
- **Direitos autorais.** Todo corte leva o crédito do canal. Marque `authorized` nos canais que autorizaram.
- Mudança de código em `clipper/app/` só entra no ar depois de reiniciar o serviço. O `scripts/dev.ts` sobe o
uvicorn sem `--reload` (gotchas, itens 53 e 73). O painel é do usuário, então peça a ele que reinicie — e só com a
suíte verde: reinício no meio de uma edição carrega código intermediário (gotchas, item 87). Agente que edita o
serviço trabalha numa cópia e aplica em `clipper/app/` por **edição pontual**, nunca sobrescrevendo o arquivo
inteiro: vários agentes e outras sessões mexem em `clipper/` ao mesmo tempo.
- Nada de rede (APIs de emotes, CLI) na thread do chat: use `EmoteCatalog.cached()` e baixe em thread à parte
(gotchas, item 72).
- Subprocesso sem shell. A CLI do Codex é chamada pelo `codex.js` (gotchas, item 28).
## Testes e evidência
Perfis de jogo bilíngues, missões, cadastro e semente do GTA VI (18/11/2026): `pnpm test:clipper` → **335 passed**
(reexecutado nesta manutenção, 108 s; bate com o informado); 10 testes em `clipper/tests/test_game_profiles.py`. Não
verificado: IA real na pesquisa, tradução e refino bilíngues; modal e lista no navegador; serviço real em v12 (precisa
reiniciar); `pnpm typecheck` e testes do painel.
IA reserva e Gemini no juiz (18/11/2026): `pnpm test:clipper` → **335 passed** (reexecutado pela skill; `test_ai_fallback.py` novo).
Reformulação da interface e regras de pausa/idioma (18/11/2026): `pnpm test:clipper` → **287 passed** (reexecutado
nesta manutenção; 9 testes novos em `clipper/tests/test_monitor_pause_and_language.py`). Não verificado: as páginas no
navegador e o banco real em v11 (o serviço precisa reiniciar).
Os testes não chamam a CLI de IA: `FakeJudge.ask` (`clipper/tests/test_sources_and_api.py`) sempre falha, e o serviço
segue pelo caminho de "IA fora". Juiz falso novo precisa cobrir `ask` também.
Hashtags da legenda (17/11/2026): `pnpm test:clipper` → **278 passed** (reexecutado nesta manutenção; bate com o
informado). Testes novos em `clipper/tests/test_hashtags.py`. O perfil do ROB RUN no banco ainda não tem `hashtags`
(informado; não conferido no banco).
Apagar cortes, veto do rejeitado, varredura contada e prévia igual ao render (17/11/2026):
- `pnpm test:clipper` → **270 passed** (medido na 1.29.1; o coordenador informou 269 — o disco já tinha outro teste
novo; na 1.29.0 eram 268). Testes novos: `test_clip_delete.py` (14); em `test_render_and_duplicates.py`, veto do
rejeitado, contagem da varredura e `test_queue_cleanup_uses_the_same_veto_as_the_judge` (limpeza da fila).
- `npx tsc --noEmit -p panel` → exit 0, sem erro (medido nesta manutenção; o lote informou erros de outra sessão em
`montage-editor.tsx`/`lib/montage*.ts`, já resolvidos quando rodei).
- Banco real `data/clipper/clipper.db` em `user_version` 10 (lido só para leitura nesta manutenção).
- Informado: diagnóstico "não sai corte" da sessão 3 (README, "Armadilhas já resolvidas"; gotchas, item 114);
legenda do painel em 22 conferências contra o Python; teste de ponta a ponta no corte 61 (projeto montado no editor,
capturado do PUT interceptado, render por `editor_render.render_project`) com enquadramento, inserção e legenda
iguais em 2/3,5/5/6,5/8 s; observador só leitura depois da retomada (01:30–01:46): corte 68 pronto e aprovado,
69 e 70 descartados, 71 pronto em 8 s.
Duração mínima, tarja do gancho, fontes, reenquadramento, camadas e qualidade de gravação (17/11/2026):
- `pnpm test:clipper` → **251 passed** (medido nesta manutenção; bate com o informado). Testes novos:
`test_duration_banner_fonts.py` (19), `test_reframe_insets.py` (10), `test_capture_quality.py` (17).
- `npx tsc --noEmit -p panel` → exit 0 (medido nesta manutenção; uma 1ª rodada deu erro em `confirm-dialog.tsx`,
de outro trabalho que ainda estava sendo escrito, e passou depois que ele terminou).
- Informado: medições de render, disco e nitidez acima e no README; prévia da tarja a ≤ ~2 px do render; interpolação
do painel × `reframe.py` em 41 conferências.
Formato horizontal, legenda com fala rápida, retomada, render que falha e duplicados (17/11/2026):
- `pnpm test:clipper` → **170 passed** e `npx tsc --noEmit -p panel` → exit 0, ambos medidos nesta manutenção (o lote
informou 169; o disco já tinha mudanças de outro lote em andamento). Testes novos: `test_format_and_captions.py`,
`test_resume.py`, `test_render_and_duplicates.py`; o vertical bate com o SHA de referência
(`tests/data/vertical_golden_sha256.json`).
- Informado: render horizontal real 1920×1080 conferido no ffprobe; legenda medida numa cópia do banco (3 projetos,
sessão 3 do skipnho): 63 de 286 eventos sobrepostos antes, 0 de 299 depois (README, "Tempo da legenda").
- Informado: capturas por CDP com as escritas interceptadas — modal "Configuração do corte" em 1920×1080 e 1366×768;
aba Sessões sem mudança de posição/altura entre atualizações automáticas.
Redesenho do editor e camadas novas (16/11/2026):
- `pnpm test:clipper` → 136 passed na época e `npx tsc --noEmit -p panel` → exit 0.
`clipper/tests/test_editor_layers.py` (6 testes): projeto antigo ganha os padrões, `cam_only` enche a tela,
`mode`/`muted` sobrevivem sem juntar, texto com `x` e bloco de chat no ASS, capa no início, e um render real pelo
FFmpeg com as camadas novas.
- Informado pelo coordenador, Chrome sem janela por CDP em `/clipper/edit/25` do painel, com as escritas
interceptadas (nada gravado): palavra aparada pela direita 34→21 px e pela esquerda 21→12 px com a outra borda
parada; mover −6 px com a largura igual; clique simples não move; Ctrl+Shift+clique divide (1→2 trechos) e Ctrl+Z
desfaz; marcar a câmera mudou a área de "21% × 24% em 2%, 43%" para "25% × 35% em 5%, 45%"; câmera inteira e chat
na tela aparecem na prévia.
Rastreio de reação (16–17/11/2026):
- `cd clipper; .venv\Scripts\python -m pytest` → 120 passed na época (2 execuções seguidas);
`npx tsc --noEmit -p panel` limpo (informado). Versões instaladas no `clipper/.venv` conferidas (ver tools.md);
os 4 pesos já estão em `data/clipper/models/`.
- `doc/FACE_BAKEOFF.md` (cópia do banco, sessão 3 do skipnho): MediaPipe achou rosto em 97,8–100 % dos quadros dos 6
trechos, 5–7 ms/quadro; bloco de 30 s em 1,47 s de média (p95 2,05 s); 144/144 blocos `done`, rosto em 85,1 % dos quadros;
após calibração 114 picos, 0 no trecho calmo, 0 cortes novos de fonte `face`, 14 dos 21 momentos do chat com
`reasons.face`. **O rosto não separou aprovados de descartados** nos cortes 10–13 — por isso é só reforço.
Rastreio de reação ao vivo (16–17/11/2026; seção "Testes de 17/11 — ao vivo" de `doc/FACE_BAKEOFF.md`):
- `cd clipper; .venv\Scripts\python -m pytest` → 170 passed e `npx tsc --noEmit -p panel` → exit 0 (conferidos
nesta manutenção).
- Download real dos 4 modelos para pasta vazia (0,28–0,91 s cada), sha256 conferido, nenhum `.part`; sha256 errado e
URL 404 → `FaceUnavailable` com `.part` apagado; arquivo corrompido → baixado de novo.
- Plano B OpenSeeFace com pesos reais × MediaPipe (sessão 3, blocos 54/66/80): rosto 96,7–100 % × 94,4–100 %;
12,3–13,9 × 9,8–13,2 ms/quadro (FFmpeg + modelo ÷ 180); `size` do OSF ~18 % menor; OSF dá sinal 0 (sem picos, sem erro).
- Serviço real, instância 4521, twitch.tv/skipnho (sessão 90001, 722 s, 25 blocos, juiz `off`): câmera `yunet` em
12/12 quadros, confiança 0,864; 25/25 `done`, atraso de 0–1 bloco; 1,71 s/bloco (p95 2,20 s) com gravação +
transcrição + chat juntos; fim do bloco → rosto gravado 1,4–9,4 s; CPU média 16,8 % de um núcleo, pico 90 % na
reconstrução após reset; rosto em 99,8 % dos segundos; `GET …/face` 200; `POST …/face/reset` 200 (ocioso) / 202
(bloco em andamento), refez 19 blocos em ~45 s; 2 cortes do chat, um com `reasons.face` grito z 12,7 (o outro,
decidido durante a reconstrução, sem rosto, como desenhado). Queda do `start.bat` no meio → sessão retomada sozinha.
- twitch.tv/lofigirl (sem câmera, sessão 90002): falso positivo achado e corrigido (gotchas, item 92); refeito →
`hasWebcam: false`, 8 blocos `no_cam`.
- Painel em 127.0.0.1:4500/clipper sem erro de console; selo, interruptor e chip de reação vistos só com respostas GET
alteradas no navegador (o serviço do usuário rodava o código antigo).
Editor de cortes, 1ª versão (16/11/2026):
- `pnpm test:clipper` → 120 passed na época.
- Informado pelo coordenador, instância de teste em 127.0.0.1:4521 sobre cópia do banco (sessão 3 do skipnho, já
derrubada e cópia apagada): tempos na tabela "Medido" do README; export do corte 9 editado (início −20 s, 2 trechos
removidos, legenda `pop` com palavra trocada e ênfase, gancho com caixa, zoom 1,5×, barra) = 55,6 s H.264
1080×1920 30 fps + AAC em ~9 s; corte 10 rejulgado pela IA real → projeto da IA → MP4 33,8 s em 24 s; quadros
inspecionados; editor em tela cheia no Chrome sem janela sem rolagem nem erro de console; `pnpm typecheck` e
`npx tsc --noEmit -p panel` limpos.
Chat por seção do perfil (16/11/2026, informado pelo coordenador, IA simulada em banco temporário): `refine`
com `section=clip_worthy` acrescentou o item, devolveu `reply`, recebeu 2 turnos de histórico e salvou a nota com
`section`; seção inválida recusada pelo pydantic; `tsc --noEmit` do painel limpo; `import app.main` ok; captura
de `localhost:4500/clipper?tab=jogos` com o chat aberto em "O que rende corte". **IA real não testada** (serviço
não reiniciado).
Perfil editável do jogo (informado pelo coordenador, banco temporário): migração até `user_version` 7,
`save_profile` deduplicou lista, `refine` guardou o pedido e marcou `edited_at`, a pesquisa recebeu as notas,
`delete_note` limpou; `tsc --noEmit` do painel limpo; `import app.main` ok. O serviço no ar precisa ser reiniciado
para migrar (o banco real estava em v4).
Fase 2 (17/11/2026):
- `pnpm test:clipper` → 46 passed (sem rede, juiz falso); `pnpm typecheck` e `npx tsc --noEmit -p panel` limpos.
Conferido nesta manutenção.
- Informado pelo coordenador, numa cópia do banco da live do skipnho (chat de ~0,15 msg/s):
- jogo ROB RUN pela categoria e perfil pesquisado (~15–35 s por jogo);
- webcam achada no canto inferior esquerdo (~5 s); render `cam_top` de 59 s inspecionado;
- varredura de 2 janelas sem falso positivo (~7 s por janela com `gpt-6-luna`);
- corte do lag: título "O lag jogou ele em três lugares ao mesmo tempo", `lag_ou_bug`, confiança 0,93, início
recuado 35 s, ~18 s nos dois juízes.
Fase 1 (16/11/2026, `twitch.tv/alanzoka`, sessão 2): 21 blocos (617,97 s), 490 mensagens, 4 cortes do chat aprovados
pelo `codex:gpt-6-luna` (notas 7,4–8,5) e 1 manual (nota 3,0) renderizado; `clip-4.mp4` H.264 1080×1920 + AAC.
Não verificado:
- hashtags: juiz e pesquisa de jogo com a CLI real (o campo `hashtags` do veredito e do perfil); UI da seção "Hashtags"
contra o serviço reiniciado;
- apagar: rota no serviço real do usuário; arquivo em uso no Windows (deve voltar em `left`); pedido do editor em
andamento gravando em `edit-<id>/` depois de apagar; relógio da sessão com movimento reduzido, aba escondida e
larguras de 1024/1280; a faixa do topo (hoje `clipper-shell.tsx`) pode ainda mostrar o `durationS` real (sem o relógio);
- duração, gancho, reenquadramento, camadas e captura: live 2K real e HEVC real da Twitch pela captura; gravação longa
em 1080p ou 2K com o serviço real; juiz e varredura reais com as durações novas; render real de um projeto feito no
editor com reenquadramento e camadas comparado com a prévia (pendente, depois do reinício do serviço); camadas na
capa (não entram por desenho);
- formato e retomada: juízes, varredura e "IA sugere" com a CLI real depois da mudança de prompts; retomada automática
contra live real; horizontal com NVENC e com fonte que não é 16:9; corte horizontal de ponta a ponta numa live;
gravação real do `format` pelo modal (as escritas foram interceptadas);
- editor: música e efeitos com arquivo real (não há áudio em `assets/`; só o filtergraph em teste unitário);
arrastes com mouse humano (só por CDP, e nem todos: deslizar o corpo do clipe, arrastar texto/zoom/narração na
timeline, mover texto/gancho/legenda/chat no Programa, "Editar"/"Ocultar" da transcrição, "Salvar projeto" e
minimizar painéis não têm medição registrada); export real pelo serviço do usuário (4520) de um projeto com
`cam_only`, `muted`, `chat` ou `cover.atStart` — as escritas do teste de UI foram interceptadas, e o serviço
precisa ser reiniciado para o código novo e a migração v7 (gotchas, item 73);
- rastreio de reação: câmera em tela cheia, escura ou minúscula; GPU; live > 15 min (`LIVE_WINDOW_S` 900 s não foi
ultrapassada); a linha "Rosto do streamer" chegando ao juiz analista ao vivo (juiz `off` no teste); interação real
com o interruptor `faceTrack` contra o serviço novo (só com respostas simuladas no navegador); câmera que muda de
lugar no meio da live. O serviço do usuário só pega a correção do `min_cam_score` depois de reiniciar o `start.bat`;
- editar/refinar perfil pela UI contra o serviço reiniciado; `refine` com IA real (com e sem `search`);
- a UI nova (modal do corte, aba Jogos e emotes) contra o serviço novo no ar — o serviço do usuário ainda roda o
código antigo;
- juiz com a CLI do Claude (analista, editor, varredura, câmera e pesquisa);
- chat da Kick e lives do YouTube ponta a ponta; VOD; render com NVENC.