Conflitos resolvidos juntando os dois lados: - db.py: v16 (detecção do jogo) e v17 (Equipe de IA) em sequência. - judge.py: a varredura exige os campos das duas frentes (screen_game_confidence/screen_evidence e lines). - proxy do painel: libera judge/report e sessions/id/game/detect. - skill: detecção do jogo vira a 1.55.0 (gotcha 180 → 186), acima da 1.54.0 das cinco frentes. Suíte do Clipador inteira passa; painel: tsc + 119 testes. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
692 lines
75 KiB
Markdown
692 lines
75 KiB
Markdown
# 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` 17, `SCHEMA` em `clipper/app/db.py`: v1 tabelas, v2 `settings`, v3 jogo/varredura/emotes/configuração do corte — colunas novas em `sessions`, `channels.settings_json`, `chat.emotes`, `clips.learned`, tabelas `games` e `emotes`; v4 `edits` (`clip_id`, `project_json`, `rev`, `cover`, `exported_at`, `created_at`, `updated_at`); v5 `face_track`; v6 `games.notes_json`/`games.edited_at`; v7 `edits.origin` (`ai`/`user`) + `edits.ai_project_json`; v8 `clips.aspect` (`vertical`/`horizontal`, padrão `vertical`, gravado no render); v9 `sessions.capture_json` (o que a captura gravou de fato; sessões antigas `NULL`); v10 tabela `deleted_clips` (marca do corte apagado, `ON DELETE CASCADE` com a sessão); v11 `channels.monitor_paused_at`/`monitor_paused_session`/`language` e `sessions.language`, padrão `''` = `CLIPPER_LANGUAGE`; v12 `games.profile_ai_json` (perfil em inglês), `translated_at`, `aliases_json`; v13 `clips.translation_json`, fala do corte em frases + português; v14 vídeo de revisão × final (`clips.review_dev_json`, `final_status/file/thumb/cover/error/at`); v15 `voice_chunks` (impressão de voz); v16 detecção do jogo (`sessions.game_status`, `game_detect_json`; vem de outra frente, o doc `DETECCAO-JOGO.md` ainda não está nesta branch); v17 `ai_calls`, `scene_notes`, `clips.owner_label/owner_note`). Detalhes de v14–v15 em [clipper-video.md](clipper-video.md), de v17 em [clipper-ai-team.md](clipper-ai-team.md). Migra ao subir o serviço. **Nunca altere uma migração já aplicada** (o banco real estava em v4 quando a v7 nasceu): coluna nova = `ALTER` numa versão nova |
|
||
| Blocos gravados (`.ts` de 30 s + `segments.csv`) e frames | `data/clipper/sessions/<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 |
|
||
| Fonte em outro idioma (inglês): prompts `*_EN`, schemas com bloco `pt`, `lang_key`, `translate_lines`, `translate_clip`, `voice_language`, `phrases`, legenda `Trans` | `clipper/app/judge.py`, `intel.py` (`Intel.lang`), `worker.py`, `subtitles.py`, `scoring.py`, `layout.py`, `editor_render.py`, `editor_api.py` (`translation_for`), `main.py`; painel `clipper-client.ts`, `clipper-clip-dialog.tsx`, `clipper-clip-parts.tsx`, `clipper-clip-table.tsx`, `clipper-session-detail.tsx`, `clipper-cut-settings.tsx` | `clipper/tests/test_english_source.py` (9); seção "Fonte em inglês" abaixo |
|
||
| Vídeo de revisão × final (`dev_flags`, `render_clip_edit(dev=…)`, `review_layers`, `render_final`, `drop_final`, rota `POST /v1/clips/{id}/final`, `publishFile`) | `clipper/app/layout.py`, `editor_api.py`, `worker.py`, `main.py`; painel `panel/src/lib/publishing-rules.ts` (`clipPublishFile`), `publishing.ts` (`sendDue`), `clipper-clip-dialog.tsx`, `clipper-clip-table.tsx` | `clipper/tests/test_final_render.py`, `publishing-rules.test.ts`, `publishing-db.test.ts`; seção em [clipper-video.md](clipper-video.md) |
|
||
| Dublagem em português (`dev.dub*`, TTS, cache, encaixe, `duck`) | `clipper/app/dub.py` + `editor_render.py` (mistura) + serviço de voz `POST /v1/synthesize` | `clipper/tests/test_dub.py`; [clipper-video.md](clipper-video.md) |
|
||
| Falantes (streamer × `otherN`): impressão de voz, boca, legenda em duas linhas, `GET /v1/sessions/{id}/speakers` | `clipper/app/speakers.py`, `voiceprint.py`, `face.py` (`MouthMeter`), `subtitles.py`, `judge.py` (`_transcript`); peso `wespeaker_r34` em `clipper/models.lock.json` | `clipper/tests/test_speakers.py`; [clipper-video.md](clipper-video.md) |
|
||
| Expressões, pose da cabeça e corpo do streamer; mapa de expressões | lógica `clipper/app/reaction.py` (`label`, `body_moments`, `expression_map`, `extra_weights`), E/S `face.py` (`pose_from_matrix`, reserva do YuNet); painel `clipper-face-map.tsx` | `clipper/tests/test_expressions.py`; seção "Expressões" em "Rastreio de reação" abaixo |
|
||
| Equipe de IA: papéis (`judge.roles`), juiz de contexto, linha do tempo JSON + mosaico (`timelineJson`), medição (`ai_calls`, `GET /v1/judge/report`), rótulo do dono | `clipper/app/roles.py`, `context_judge.py`, `timeline.py`, `report.py`, `judge.py`, `worker.py`, `intel.py`; painel `clipper-ai-team.tsx`, `clipper-judge.tsx`, `clipper-clip-parts.tsx` | `clipper/tests/test_roles.py`, `test_context_judge.py`; [clipper-ai-team.md](clipper-ai-team.md) |
|
||
| Chat (IRC anônimo da Twitch com `CAP REQ :twitch.tv/tags` → emotes nativos e `room-id`; Pusher da Kick, emotes `[emote:id:NOME]`) | `clipper/app/chat.py` | — |
|
||
| Heurística: pesos, base de 3 min, mínimo proporcional (`_required_messages`), reações (`min_reactions`), chat fraco (`sparse_rate` 0,5 msg/s), momentos do chat/áudio/rosto (`_chat_moments`/`_audio_moments`/`_face_moments`; `face_*` em `Params`), `pick_peaks`, `fit_window` (duração de todo corte automático) | `Params` e funções em `clipper/app/scoring.py`; alvo `min_target` em `layout.py` | `clipper/tests/test_scoring.py` (regressões de falso positivo, chat fraco e rosto), `test_duration_banner_fonts.py` |
|
||
| Rastreio de reação — E/S: backends (MediaPipe; plano B OpenSeeFace), download sob demanda com sha256, recorte FFmpeg 6 qps, laço `face` | `clipper/app/face.py` (`for_scoring`, `must_wait`, `view`, `reset`); laço `_face_loop` e uso de `must_wait` na decisão do corte em `worker.py`; bancada `clipper/tools/face_bench.py` | `clipper/tests/test_face.py`, `clipper/models.lock.json`, `doc/FACE_BAKEOFF.md` |
|
||
| 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` |
|
||
| Detecção do jogo da live (`check_game` a cada `GAME_CHECK_S` 180, `detect_game`, `detect_game_now`, `note_screen`, `canon`, `gather_evidence`; regra pura `Evidence`/`fuse`/`count_mentions`/`is_generic`; `sessions.game_status`/`game_detect_json`) | `clipper/app/game_detect.py` (regra) + `intel.py` (pistas e aplicação); `judge.py` (`GAME_SYSTEM`/`GAME_SCHEMA`, `Judge.detect_game`); `main.py` (`session_view`: `gameStatus`, `gameDetect`; `PUT …/game`, `POST …/game/detect`); painel `clipper-games.tsx` (`SessionGame`), `clipper-client.ts` (`GameStatus`, `GameDetect`, `GAME_CLUE_LABEL`, `gameNeedsReview`) — seção "Detecção do jogo da live" abaixo | `clipper/tests/test_game_detect.py`; `doc/clipador/DETECCAO-JOGO.md`; `ALLOWED` em `panel/src/lib/clipper.ts` (gotchas, item 180) |
|
||
| Contexto do jogo (`screen_game` da varredura, 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, detecção do jogo pela tela (`SCAN_SCHEMA` exige `screen_game_confidence` high\|medium\|low e `screen_evidence`; `Judge.detect_game(images, live_title)` com 3 frames) | `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`, `timelineJson`, `roles`. Fica na tabela `settings`, sem reiniciar; o `.env` só dá o valor inicial.
|
||
- **Equipe de IA (18/11/2026):** hoje são quatro papéis (varredura, analista, editor e o **juiz de contexto**), cada um com
|
||
provedor + modelo + raciocínio + instruções do administrador (`judge.roles`), e a IA lê a live como linha do tempo JSON
|
||
(`timelineJson`). Tudo em [clipper-ai-team.md](clipper-ai-team.md); o texto acima descreve o fluxo base analista → editor.
|
||
- Codex: cada imagem com seu `-i`, todas antes do `-` final; `--search` é opção **global** (antes de `exec`).
|
||
- Custo fixo: cada chamada é um processo novo (2 por candidato). `codex_lean_overrides(search, config_file=None)` em
|
||
`judge.py` enxuga o Codex; o Claude leva `--setting-sources project,local`. Números e limites em
|
||
[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` confirma o jogo (`game_source = user`; a troca automática vira só
|
||
sugestão) e `POST …/game/detect` roda a detecção ("Detectar agora"); regras em "Detecção do jogo da live". 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).
|
||
- **Expressões, cabeça e corpo** (18/11/2026; `doc/clipador/EXPRESSOES.md`, sem migração: os campos novos vão no
|
||
`data_json` de `face_track`, séries antigas continuam valendo):
|
||
- Rótulos novos só a partir de blendshapes que já vinham: `gargalhada` (risada + cabeça ≥ 20° para trás), `alegria` (só no
|
||
mapa), `medo`, `nojo`, `tristeza`, `espanto`, `tenso`, `bocejo`. Além dos antigos (`risada`, `grito`, `susto`, `choque`,
|
||
`raiva`, `confuso`). Pose (yaw/pitch/roll) vem da matriz de transformação facial do MediaPipe
|
||
(`output_facial_transformation_matrixes=True`, `face.pose_from_matrix`).
|
||
- **Reserva do YuNet:** quando o MediaPipe perde o rosto (streamer de perfil), o YuNet roda **só nesse quadro** (5,3 ms) e dá a
|
||
caixa da cabeça → corpo: `balançando`, `acenando`, `agitado`, `chegou perto`, `saiu do quadro` (`reaction.body_moments`;
|
||
"saiu" só com o campo `head`). Rastreio perdido nunca vira movimento.
|
||
- **Canais novos só dão nome, não criam picos:** `ReactionParams.extra_weights` = 0 (a intensidade alimenta nota e fonte
|
||
`face`; mexer sem conjunto aprovado/rejeitado maior seria chute). Ligar um canal = dar peso lá e medir de novo. Única mudança
|
||
nos picos: bocejo deixou de contar como grito.
|
||
- **Calibração (dados reais, 4 sessões):** bocejos eram os maiores "gritos" (jawOpen ≥ 0,6 por 3 s); `noseSneerLeft/Right`,
|
||
`cheekSquintLeft/Right`, `cheekPuff` são sempre ~0 no MediaPipe (nojo usa o lábio de cima); mão no rosto ainda engana a
|
||
boca (tristeza/espanto/medo/raiva no mapa); cadeira vazia pode gerar "rosto fantasma"; balançar a 6 qps é movimento, não
|
||
"não" literal. Série de 1,7 h: ~1,4 MB/h no banco; análise ~1 s.
|
||
- API: `GET /v1/sessions/{id}/face` ganha `expr`/`body` por segundo e `body: [{startS,endS,peakS,label,value}]`; a linha
|
||
"Rosto do streamer" do analista leva até 2 movimentos do corpo (com rosto de perfil: "sem expressão legível… saiu do quadro").
|
||
Painel: **Mapa de expressões** no modal do corte (`clipper-face-map.tsx`), chip `FaceSignal` com os rótulos novos.
|
||
- **Não verificado:** serviço real rodando o código novo; painel no navegador (só `tsc`); câmera escura/minúscula além da do tfue.
|
||
- **Cortes:** rosto **reforça, não manda.** `reasons.face` + bônus ≤ 0,6 em momentos do chat/áudio; fonte `face` só
|
||
com z ≥ 6 **e** apoio (áudio suavizado ≥ 1,5 ou ≥ 2 mensagens de reação). A decisão do corte espera o rosto do
|
||
trecho (no máximo 2 blocos atrás da transcrição). O analista recebe a linha "Rosto do streamer: …" — exceto
|
||
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 (pela fronteira `voice_language`, ver abaixo); espanhol mantém os prompts em português com a nota de idioma de saída; inglês tem juízes próprios (seção "Fonte em inglês").
|
||
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ão do corte em outro idioma para publicar: **ainda não existe**; a tradução em português guardada é só para a equipe ler.
|
||
- Sem reiniciar o Clipador as rotas novas não valem; o painel trata `language`/pausa como opcionais e não quebra
|
||
(gotchas, item 166).
|
||
|
||
## Fonte em inglês (18/11/2026)
|
||
|
||
Fonte do contrato: `doc/clipador/IDIOMAS.md`; README do Clipador, "Idioma por fonte e por sessão". Decisão do dono: o
|
||
**vídeo sai em inglês** (título, legenda, hashtags, gancho) e **a equipe vê tudo em português** no painel.
|
||
|
||
- **Regra:** `judge.lang_key(language)` = `"en"` para `en-*`, senão `"pt"`; `Intel.lang(session)` resolve. Em inglês, analista,
|
||
editor e varredura usam `ANALYST_SYSTEM_EN`/`JUDGE_SYSTEM_EN`/`SCAN_SYSTEM_EN`, `CLIP_GUIDE_EN`, `CHAT_GLOSSARY_EN` e
|
||
`LABELS` en nos montadores (parâmetro `lang` em `Judge.analyze/judge/scan`). Perfil do jogo no prompt = `profileAi`.
|
||
- **Tradução sem chamada extra:** os schemas `*_EN` exigem o bloco `pt` (analista: `what_happened`, `screen`, `speech`,
|
||
`chat_meaning`, `hook`; editor: `title`, `caption`, `reason`; varredura: `summary_pt` e `pt` por momento). Vai em
|
||
`judge_json.pt`, `memory[].summaryPt`, `reasons.proposalTitlePt/proposalReasonPt`. `analysis_block` tira o `pt` antes do editor.
|
||
Campo novo no schema inglês = pôr o `pt` correspondente e mostrar no painel.
|
||
- **Fala traduzida:** `Engine.translate_clip(clip_id, lo, hi, force)` (chamada quando o corte é mantido) grava
|
||
`clips.translation_json` `{language, startS, endS, model, lines: [{s, e, text, pt}]}`; frases de `subtitles.phrases`
|
||
(pausa > 0,7 s, fim de frase com 4+ palavras, 16 palavras ou 6 s) traduzidas por `Judge.translate_lines`.
|
||
`POST /v1/clips/{id}/translate` refaz (409 em fonte PT); `clip_view.translation`.
|
||
- **Legenda em português no vídeo (só para desenvolver):** `dev.translation` (padrão `false`; `caption.translation` é o legado, ainda lido) → estilo ASS `Trans`
|
||
(metade do tamanho, `&H00FFE79B`) sob a legenda, seguindo o desvio do gancho; só entra no ASS quando ligado **e** há
|
||
tradução (sem isso o ASS é idêntico ao de antes). `editor_api.translation_for` alimenta render e prévia. Entra só no
|
||
**vídeo de revisão**: o final, gerado ao aprovar, sai sem ela ([clipper-video.md](clipper-video.md); dublagem: mesma seção).
|
||
- **Heurística:** `scoring.py` (`REACTION_PATTERNS`, `SPOKEN_REACTION`) reconhece reação em inglês (lmao, lol, 💀, 😭, no
|
||
way, bruh, holy, clutch, goated, clip that…). `judge.output_language_note` agora é vazio também para inglês.
|
||
- **Voz:** `worker.VOICE_LANGUAGES`/`voice_language()` converte `en-US` → `en` e `es-419` → `es` antes do Whisper (gotchas, item 173).
|
||
- **Começar uma fonte gringa:** Fontes → idioma English (US); jogo com perfil em inglês e gírias do público gringo
|
||
(Jogos → "acrescente as gírias…", ou `POST /v1/games/{id}/translate` se o perfil só existe em português); ligar
|
||
"Tradução em português embaixo (teste)" (e, se quiser, "Dublagem em português (teste)") na configuração do corte do
|
||
canal enquanto estiver testando. Fontes em teste (18/11/2026): twitch-tfue (ROB RUN) e twitch-maxylobes (GTA V Chaos
|
||
Mod, en-US, `dev.translation` + `dev.dub` ligados).
|
||
- **Painel:** modal do corte com bloco "Em português" (título, legenda, "O que ele fala" frase a frase, botão "Traduzir a
|
||
fala"); lista com título traduzido (🇧🇷); resumo da sessão em português; switch em `clipper-cut-settings.tsx`; Fontes: a
|
||
coluna "Ao vivo" mostra "gravando #N" da sessão ativa e checagem do monitor com mais de 10 min vira "ao vivo há X"
|
||
apagado (gotchas, item 174).
|
||
- Medido (18/11/2026, sessão 15, twitch.tv/tfue, ROB RUN, 1080p60 h264, informado pelo coordenador): transcrição em
|
||
inglês ok; câmera pela YuNet em 12/12 quadros; corte manual 259 (30–100 s) com título, legenda e hashtags em inglês,
|
||
`judge.pt` em português, 27 frases traduzidas e vídeo 1080×1920 com inglês em cima e português embaixo. Não verificado
|
||
por mim: o render real (só a suíte foi reexecutada); qualidade da tradução fora desse corte; espanhol ponta a ponta.
|
||
|
||
## Detecção do jogo da live (18/11/2026)
|
||
|
||
Fonte do contrato: `doc/clipador/DETECCAO-JOGO.md`; seção "Contexto do jogo" de `clipper/README.md`. Decisão do dono:
|
||
ninguém precisa lembrar de dizer o jogo; o Clipador descobre sozinho e o usuário só confirma ou corrige.
|
||
|
||
- **Quando:** `Intel.check_game` a cada `GAME_CHECK_S` 180 s grava a categoria/título em `sessions.game_detect_json`
|
||
(`platform`) e chama `detect_game`. A varredura e "Detectar agora" gravam a tela com `note_screen` (vale
|
||
`SCREEN_FRESH_S` 900 s). Chat e fala: últimos `CHAT_WINDOW_S` 360 s e 12 blocos (`SPEECH_SEGMENTS`).
|
||
- **Pistas** (`game_detect.Evidence`; peso por fonte `SOURCE_WEIGHT`: categoria 0,55, tela 0,5, chat e fala 0,35,
|
||
título 0,25; tela multiplica pela confiança high 1 / medium 0,7 / low 0,4). Cada fonte conta uma vez por jogo.
|
||
`fuse` junta os pesos por ruído-ou e decide `status`:
|
||
`agreed` (≥ 2 fontes e nota ≥ 0,6), `probable` (nota ≥ 0,34), `conflict` (2º colocado ≥ 0,34, vantagem < 0,25 e com
|
||
fonte forte = categoria ou tela), `unknown`. Chat só conta com ≥ 2 mensagens citando o jogo.
|
||
- **Estados em `sessions.game_status`:** `user` (você confirmou) | `agreed` | `probable` | `conflict` | `unknown` (`''` =
|
||
sessão antiga, ainda não checada).
|
||
- **Regras de troca** (`detect_game`):
|
||
- Jogo confirmado por você (`game_source = user`) **nunca** muda sozinho; se as pistas concordam em outro jogo por 2
|
||
checagens seguidas vira `suggestion` e o painel pergunta.
|
||
- Sem confirmação, trocar de jogo exige a categoria apoiando **ou** a mesma resposta em 2 checagens seguidas
|
||
(`state.pending.n`); "Detectar agora" (`immediate`) pula a espera.
|
||
- Conflito categoria × tela mantém o jogo atual e o painel pergunta (um botão por candidato).
|
||
- Categoria genérica ("Just Chatting", "IRL", "Só Bate-papo"…, `GENERIC_CATEGORIES`) não é jogo: fica registrada, não conta.
|
||
- **Nomes:** `canon(name)` resolve categoria "Grand Theft Auto VI" e tela "GTA 6" para o mesmo id quando o jogo (ou um
|
||
alias) está cadastrado. `count_mentions` casa palavra inteira e confere duas leituras do texto: sem acento (`slug`) e
|
||
como `intel.game_id` gerou o id, que **não** tira acento (`Pokémon` → `pok-mon`).
|
||
- **"Detectar agora"** (`POST /v1/sessions/{id}/game/detect`, `detect_game_now`): a IA vê 3 frames (−120, −60 e −6 s) e
|
||
o título; sem IA ou sem visão (`vision`) responde erro de usuário. Leva de 10 s a 1 min. Resposta `{result, session}`.
|
||
- **API:** `session_view` ganhou `gameStatus` e `gameDetect` `{checkedAt, candidates, suggestion, platform, screen}`.
|
||
`PUT …/game` confirma à mão e roda a detecção (limpa a sugestão).
|
||
- **Painel:** `SessionGame` em `clipper-games.tsx`: selo do estado, botão "Detectar agora", aviso de conflito, aviso de
|
||
sugestão e "Como o jogo foi descoberto"; `gameNeedsReview` (`clipper-client.ts`) é o que `clipper-session-detail.tsx` e
|
||
`clipper-sessions-page.tsx` usam para chamar a atenção (serviço antigo sem `gameStatus`: cai no cálculo por `screenGame`).
|
||
- **Limites:** chat e fala só reconhecem jogos já cadastrados em Jogos (`_mention_forms` lê a tabela `games`); sem IA/visão
|
||
não há pista de tela. Só vale com o serviço reiniciado (migração v16; gotchas, item 180).
|
||
|
||
## 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
|
||
|
||
Detecção do jogo da live (18/11/2026): suíte inteira do Clipador (`cd clipper; .venv\Scripts\python -m pytest`) →
|
||
exit 0, 440 testes (pontos contados na saída; o `pytest.ini` usa `-q` e não imprime a linha final; reexecutado nesta
|
||
manutenção); `tests/test_game_detect.py` tem 15 testes (o lote informou 14); `npx tsc --noEmit -p panel` → exit 0
|
||
(reexecutado). Não verificado: IA real em `Judge.detect_game` e nos prompts com os campos novos; o painel no navegador;
|
||
banco real em v16 (o serviço precisa reiniciar); o botão "Detectar agora" contra o serviço — o proxy do painel não tem
|
||
`game/detect` no `ALLOWED` (gotchas, item 186; já corrigido).
|
||
|
||
Bloco de 18/11/2026 (revisão × final, dublagem, falantes, expressões, Equipe de IA e proxy): **informado pelo coordenador**
|
||
(não reexecutado por mim): suíte inteira do Clipador passa; painel `tsc` + 119 testes. Testes novos: `test_final_render.py`,
|
||
`test_dub.py`, `test_speakers.py`, `test_expressions.py`, `test_roles.py`, `test_context_judge.py`. Medidas citadas (tempo da
|
||
dublagem, custo da voz, estabilidade dos falantes, tokens por hora) vêm dos docs de `doc/clipador/` e estão nas seções
|
||
próprias. Não verificado: serviços reais com o código novo (precisam reiniciar), UI no navegador, juiz/dublagem/voz com IA e
|
||
TTS reais além dos cortes citados, banco real em v17. `onnxruntime` 1.32.0 e `mediapipe` 1.2.3 reconferidos no `clipper/.venv`.
|
||
O proxy do painel liberou `POST clips/{id}/translate` e `GET sessions/{id}/speakers` (sem isso o botão "Traduzir a fala"
|
||
dava 404; regex `ALLOWED` + `METHODS` em `panel/src/lib/clipper.ts`).
|
||
|
||
Fonte em inglês (18/11/2026): `pnpm test:clipper` → **346 passed** (reexecutado nesta manutenção, 101 s); `test_english_source.py`
|
||
novo (9 testes) e ajustes em `test_monitor_pause_and_language.py`, `test_render_and_duplicates.py`, `test_intel.py`. Não
|
||
verificado: IA real com prompts em inglês (só o corte 259 informado), painel no navegador, `pnpm typecheck`, banco real em v13
|
||
(o serviço precisa reiniciar).
|
||
|
||
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.
|