# 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//` (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` | | Arquivos do editor (proxy, TTS) | `output/clipper//edit-/` (narração em `tts-.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 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 -o json --approval-mode plan --skip-trust -m `, 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-`. - 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-.*`/`clip--*` em `output/clipper//`, a pasta `edit-/` e os quadros do juiz `frames/clip-*.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//data`, `CLIPPER_OUTPUT_DIR=output//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/`) 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//(research|refine|translate|notes/n)`; `METHODS` dá GET/POST a `games` e PUT/DELETE a `games/`; 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-/` 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.