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