CenaForge: primeira versão pública

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>
This commit is contained in:
2026-11-17 16:35:09 -03:00
co-authored by Claude Opus 5.5
commit 84f30bbc2d
484 changed files with 74826 additions and 0 deletions
+552
View File
@@ -0,0 +1,552 @@
# Clipador — cortes automáticos de live
Serviço local do CenaForge (`127.0.0.1:4520`, faixa 4500–4599) que assiste lives da **Twitch, YouTube e Kick**,
lê o **chat em tempo real**, transcreve a fala com o **Whisper** (serviço de voz, 4510), pede a uma **IA pela CLI**
(Codex/GPT por padrão, ou Claude) que confirme o momento e gera **cortes com legenda queimada**: verticais 1080×1920
(Shorts/Reels/TikTok, padrão) ou horizontais 1920×1080 (YouTube "tela grande", mostrando o próprio jogo).
O painel (`/clipper`) mostra a fila para aprovar. As contas que recebem os cortes de cada canal são ligadas na
página **Contas**, como as histórias.
> **Publicação nas redes (YouTube, TikTok, Instagram) é a próxima etapa.** Hoje "Aprovar" só marca o corte.
## Como funciona
```
Streamlink ─► bomba (Python) ─► FFmpeg -f segment: blocos .ts de 30 s + segments.csv data/clipper/sessions/<id>/
Chat (IRC anônimo da Twitch · websocket da Kick) ─► tabela chat (hora real de cada mensagem)
Cada bloco novo ─► volume por segundo (RMS) + Whisper com tempo por palavra (POST /v1/transcribe, X-Detail: words)
A cada 15 s ─► pontuação do chat/áudio (app/scoring.py) ─┐
A cada 3 min ─► VARREDURA da IA: frames + fala + chat ──┴► candidato ─► ANALISTA (vê frames) ─► EDITOR ─► render
Contexto (app/intel.py): jogo pela categoria + tela + perfil pesquisado na web · webcam achada pela IA · emotes
output/clipper/<sessão>/clip-<id>.mp4 (layout.py)
```
1. **Chat aponta.** Cada mensagem pesa 1; risada (`KKKK`, `KEKW`, `ICANT`, `PepeLaugh`…), susto (`caralho`,
`HUH`, `monkaW`…), hype (`POG`, `W`, `GG`…) somam peso, e pedido de clipe (`clip`, `clipa`) soma 3.
A empolgação de cada segundo é comparada com o **normal recente da própria live** (mediana dos últimos 3 min):
canal grande tem muita mensagem o tempo todo, o que conta é o pico relativo. O mínimo de mensagens nos 8 s do
pico é **proporcional ao chat** (3× a mediana recente, entre 4 e 12) e exige ≥ 2 mensagens de reação (texto ou
emote) — chat de 0,15 msg/s (skipnho) nunca chegava às 12 fixas. Ignora o 1º minuto da gravação.
**Emotes** (Twitch nativos pela tag do IRC, 7TV/BTTV/FFZ do canal e globais, emojis, Kick) contam como reação e
têm **peso aprendido por canal** (tabela `emotes`): sobe nos cortes que você aprova, desce nos rejeitados (a
decisão da IA também conta, com metade do peso).
2. **O corte começa antes da reação.** O chat reage depois do acontecimento: do pico, o código volta até onde a
reação começou e pega mais 14 s antes; termina 6 s depois do pico. Ajusta início/fim a pausas da fala (não corta
no meio da frase) e limita à duração da configuração do corte (`duration`, padrão **60–90 s**; o candidato já
nasce nessa duração, crescendo para trás a partir do fim da reação).
3. **Chat fraco ou sem chat**: o volume (gritos/risadas) e palavras de reação também propõem momentos.
4. **Varredura da IA** (live pequena, reação que não vira mensagem): a cada `scanIntervalS` (180 s) de gravação a IA
assiste a janela — 7 frames, fala, chat, perfil do jogo, resumos das janelas anteriores — e propõe 0–2 momentos.
Medido: ~7 s por janela com `gpt-6-luna` (~20 chamadas/h). Proposta com nota < 4 nem vai aos juízes.
5. **Dois juízes** para cada candidato (chat, áudio ou varredura):
- **Analista** (vê 6 frames do trecho + fala + chat + glossário de gírias): `situation` (lag_ou_bug, jogada,
falha_engracada, morte, susto, treta, conversa_engracada, historia, informacao_do_jogo, reacao, outro),
o que aconteceu, o que a tela/fala/chat mostram, confiança 0–1, início da AÇÃO e fim da reação.
- **Editor** (só texto + a análise): manter/descartar, nota, início/fim, título e legenda fiéis à situação.
Pode voltar até `duration.backtrackS` (padrão **120 s**) antes do candidato: o comentário vem depois da ação.
O analista recebe 6 quadros (8 quando o trecho passa de 80 s, o normal com cortes de 60–90 s) de 20 s antes do
candidato até 15 s depois; a transcrição vai da volta inteira (até 2 min antes) até 15 s depois.
Medido no corte do lag (skipnho): título antigo "Jogando três jogos ao mesmo tempo…" → "O lag jogou ele em três
lugares ao mesmo tempo" (situation `lag_ou_bug`, confiança 0,93; chat "server chinês?" entendido como lag), início
recuado 35 s até "o jogo voltou a lagar". ~18 s pelos dois juízes.
Abaixo da nota mínima (padrão 6) o corte fica como **descartado pela IA** — visível, e dá para forçar o render.
6. **Ao vivo**, um pico só é fechado quando passaram 18 s depois dele (pico ainda crescendo não vira corte cedo) e a
fala do trecho já foi transcrita.
Tempo: `t` = soma das durações dos blocos. A mensagem do chat é convertida pela hora em que cada bloco terminou de
chegar (`wall_end`), então a pausa do Streamlink ao filtrar anúncio da Twitch não desalinha chat e vídeo.
**Cartão da sessão no painel:** o relógio da gravação corre segundo a segundo a partir do último `durationS`, com
teto de 45 s além dele (passou disso, mostra "aguardando o bloco"); "Agora na live" mostra a contagem para o próximo
resumo da varredura, com o intervalo vindo de `GET /v1/status` → `judge.options.scanIntervalS`.
## Contexto do jogo
- Categoria da plataforma (Streamlink `--json`, `metadata.category`) no início e a cada 10 min (troca registrada em
`games_json`). Sem categoria (YouTube/VOD), o jogo vem da tela (`screen_game` da varredura). A IA também diz o que
vê na tela; divergência (categoria "ROB RUN", tela "GTA V") vai para o contexto dos juízes.
- **Perfil do jogo** pesquisado na web pela CLI (`codex --search`), guardado por jogo (tabela `games`): resumo,
mecânicas, o que rende corte, o que não rende, gírias, novidades, fontes. Medido: ~15–35 s por jogo.
- Correção manual: `PUT /v1/sessions/{id}/game` (trava a troca automática).
## Configuração do corte (layout, câmera, legenda)
Por canal (padrão do streamer), por sessão e por corte (`settings` do projeto de edição) — cada camada sobrescreve
campo a campo (padrão ← canal ← sessão ← projeto) — `app/layout.py`:
- `format.aspect`: `vertical` (padrão, 1080×1920, Shorts/Reels/TikTok) ou `horizontal` (1920×1080, YouTube "tela
grande"). No **horizontal** o vídeo mostra o quadro original inteiro (16:9 preenche; outra proporção ganha faixas
pretas em vez de ser cortada) ou, se `layout.game` estiver marcado, essa região recortada para preencher 1920×1080
sem distorcer; `cam_only` continua valendo (câmera em tela cheia); `auto`, `blur`, `cam_top` e `game_only` viram
"quadro inteiro" (`resolved_mode` = `full`). Textos: o ASS do horizontal usa um quadro lógico de **2560×1440**
(o libass reduz para 1920×1080), então os mesmos tamanhos em px do JSON saem a **75 %**: legenda 84 → 63 px,
gancho 68 → 51 px, crédito 44 → 33 px, chat 34 → 25,5 px. Posições 0–1 continuam relativas ao quadro. Legenda
automática (`caption.y: null`) a 85 % da altura (terço de baixo); crédito no canto direito (em cima ou embaixo).
- `layout.mode`: `auto` (câmera em cima se houver câmera marcada), `blur`, `cam_top` (webcam no terço de cima, jogo
embaixo recortado no centro), `game_only`, `cam_only` (a câmera do streamer ocupa a tela inteira; sem câmera
marcada cai em `blur`); `cam`/`game` = retângulos 0–1 do quadro original; `camHeight`.
- `caption`: fonte, tamanho, cor, cor da palavra falada, contorno, posição (`y`; automático = emenda câmera/jogo),
maiúsculas, palavras por bloco. `credit`: liga/desliga, topo/rodapé (no `cam_top` desce para o pé da câmera).
- `duration`: `minS` (5–120, padrão 60), `maxS` (15–180, padrão 90), `minS` < `maxS`, e `backtrackS` (0–120, padrão
120 = a IA pode voltar até 2 min para pegar o contexto). Para Shorts de terceiros, um canal pode baixar para ≤ 60 s.
**Todo corte automático sai com duração final ≥ `minS` + 1 s** (pedido do dono: "se o mínimo é 60 tem que ser 60;
sempre 1 s a mais"; no código, +0,1 s de folga de quadro: `layout.min_target`) e ≤ `maxS`, medida no arquivo. Vale
para a heurística (candidato), a varredura, os juízes, o projeto da IA (depois de silêncios e aparos) e o "IA
sugere"; faltando material, o corte cresce para trás (contexto) e, no começo da gravação, para a frente
(`scoring.fit_window`). Gravação menor que o mínimo: não inventa vídeo, o projeto registra "curto: só havia X s".
"Cortar agora" e a edição à mão continuam livres.
- `hook`: estilo do gancho que o projeto da IA põe no começo: `style` (`plain` | `banner`), `bg` (cor da tarja),
`color` (texto), `font`, `anim` (`pop` | `fade` | `none` | `slide`) e `seconds` (1–8). Padrão: **tarja** verde-limão
`#00FF00`, texto branco com contorno preto em Luckiest Guy, `slide`, 3 s. A tarja cobre o começo do corte: o
segundo a mais do mínimo é essa abertura (vem da própria gravação, de preferência antes da ação; não há tela parada
nem atraso do conteúdo). Se a legenda automática estiver perto de 20 % da altura, a tarja vai para o outro lado.
- **Fontes**: `caption.font`, `hook.font` e `font` dos textos aceitam as do Windows (Arial Black, Arial, Impact,
Verdana, Segoe UI Black, Trebuchet MS) e as **empacotadas** em `assets/fonts/` (Luckiest Guy — Apache-2.0; Bangers,
Anton, Bebas Neue, Poppins ExtraBold — OFL-1.1), baixadas do google/fonts num commit fixo, com sha256 em
`assets/fonts/fonts.lock.json` e a licença ao lado de cada arquivo. O serviço confere o sha256 ao carregar e, quando
o ASS usa uma delas, passa a pasta ao libass (`ass=…:fontsdir='…'`). Acentos do português conferidos.
- **Webcam achada sem IA** nos 2 primeiros blocos da sessão: YuNet procura o rosto em 12 quadros espalhados e
`reaction.locate_cam` acha a câmera (ver "Rastreio de reação"); salva como padrão do canal (ou da sessão). A IA (3
frames, ~5 s) só entra se o local não achar rosto e a visão estiver ligada, ou com `POST …/detect-cam?ai=true`.
`cam_json.source` diz quem achou: `yunet` | `ai` | `manual`.
- Prévia: `POST /v1/sessions/{id}/preview` gera a imagem no formato efetivo (1080×1920 ou 1920×1080) sem salvar;
`GET …/frame` dá o quadro para desenhar.
## Qualidade de gravação (`capture`)
Pedido do dono (17/11/2026): "pegar a live na melhor resolução; a live tem 2K, e isso é configurável". Antes a
captura pedia `720p60,720p,480p,best` (`CLIPPER_QUALITY`) e nunca passava de 720p. Agora é o grupo `capture` da
configuração do corte (padrão ← canal ← sessão; `app/capture.py`):
- `capture.quality`: `best` (**padrão**: a maior resolução que a live oferece) ou um **teto** — `1440p`, `1080p`,
`720p`, `480p` (a maior variante que não passa dele). Vale na próxima gravação ou retomada: a captura em andamento
não troca de qualidade. `CLIPPER_QUALITY` não é mais lida.
- **Escolha** pelos sinônimos do próprio Streamlink: `best` (ignora `audio_only` e as variantes verticais
`*_portrait`); teto = `--stream-sorting-excludes >{teto}60` + `best,worst-unfiltered` (sem nada abaixo do teto, pega
a menor variante que existe: nunca falha por causa da qualidade). Twitch com `best`/`1440p`:
`--twitch-supported-codecs h264,h265` (o 2K da transmissão aprimorada vem em HEVC; com h265 pedido as variantes
paisagem continuaram H.264). AV1 não é pedido (FFmpeg sem libdav1d).
- **Sem opção de 30/60 qps**: a variante do topo é quase sempre só 60 qps (Twitch: 1080p30 em 0 de 143 lives) e o
corte sai em 30 qps de qualquer jeito; pedir 30 qps custaria resolução.
- **O que foi gravado**: o `ffprobe` do 1º bloco de cada execução (início ou retomada) vai para `sessions.capture_json`
(migração v9) e sai em `GET /v1/sessions/{id}` como `capture`: `quality` (pedida), `width`, `height`, `fps`,
`codec`, `kbps`, `gbPerHour`, `fromIdx`, `runs` (últimas 10 execuções) e `mixed` (blocos em mais de uma
resolução). Sessões de antes ficam `null` (eram ≤ 720p). As rotas de settings devolvem `captureQualities`
(rótulo, teto, GB/h e dica de cada opção).
Nomes de stream medidos com `streamlink --json` (17/11/2026; 143 lives da Twitch, 5 da Kick, 22 do YouTube):
| Plataforma | Nomes | `best` |
|---|---|---|
| Twitch | `1080p60` (138 de 143), `1080p`, `936p60`, `864p60`, `720p60`, `720p60_alt`, `720p30`, `720p`, `480p30`, `360p30`, `160p30`, `audio_only`; em 9 canais `1920p60_portrait`, `1280p60_portrait`, `852p30_portrait`… (a de 1080×1920 em HEVC) | `1080p60` (ou `936p60`/`1080p`) |
| Kick | `1080p60`, `720p60`, `480p`, `360p`, `160p` | `1080p60` |
| YouTube | `1080p60` ou `1080p`, `720p60`/`720p`, `480p`, `360p`, `240p`, `144p` (o HLS do Streamlink para em 1080p, até em live "4K") | `1080p` |
Nenhuma live 2K no ar nas 3 plataformas no dia: o 1440p foi medido com blocos 1440p60 gerados a partir do 1080p60 real.
**Custo medido** (17/11/2026, trecho real do skipnho gravado ao mesmo tempo em 720p60 e 1080p60, no formato do serviço;
2K = 1080p60 ampliado para 2560×1440 a ~10 Mbps, em H.264 e em HEVC; CPU de 32 threads + RTX 2060 SUPER):
| Etapa | 720p60 | 1080p60 | 1440p60 H.264 | 1440p60 HEVC |
|---|---|---|---|---|
| Bloco de 30 s | 12,8 MB | 29,9 MB | 40,9 MB | 39,3 MB |
| Disco por hora | 1,5 GB | 3,6 GB | 4,9 GB | 4,7 GB |
| Render de 60 s, vertical / horizontal (NVENC) | 6,3 / 6,2 s | 6,5 / 6,4 s | 6,5 / 6,4 s | 6,7 / 6,7 s |
| Render de 60 s, vertical / horizontal (libx264) | 4,6 / 3,3 s | — | — | 6,2 / 5,4 s |
| Proxy 480p de 90 s | 2,5 s | 3,1 s | 3,8 s | 5,2 s |
| 8 frames do analista (a varredura usa 7) | 0,9 s | 1,4 s | 1,9 s | 2,3 s |
| Achar a câmera (YuNet, 12 quadros) | 1,5 s | 2,3 s | 3,0 s | 3,5 s |
| Rastreio do rosto, bloco de 30 s (só o FFmpeg) | 1,7 s (0,4 s) | 1,7 s (0,7 s) | 1,9 s (1,0 s) | 2,1 s (1,5 s) |
| Áudio do bloco (volume + Whisper) | 0,06 s | 0,07 s | 0,07 s | 0,08 s |
Disco por hora pelas playlistas mestras da Twitch (`BANDWIDTH`, mediana de 62–69 lives): 1080p60 7,1 Mbps
(4,6–9,1) ≈ **3,2 GB/h** (até 4,1); 720p60 3,4 Mbps ≈ 1,54 GB/h; 480p30 1,4 Mbps ≈ 0,64 GB/h. 2K estimado em
~4,5 GB/h. Com `CLIPPER_KEEP_HOURS` = 6, uma live longa em 1080p60 guarda até ~19–25 GB de blocos (antes ~9 GB);
o padrão continua 6. Nenhuma etapa ficou inviável: tudo que não precisa de 2K já reduz a escala (frames do juiz
768 px, YuNet 1280 px, rastreio ~384 px, proxy 480p); o custo extra é decodificar a fonte maior.
**Nitidez**: a câmera recortada no vertical (`cam_top`) gravada em 1080p60 sai mais nítida que em 720p60, no mesmo
trecho: variância do Laplaciano 130 → 149, energia de alta frequência 3,24 → 3,91 (+21 %). O 2K ampliado não ganha
nada (mesma informação do 1080p), como esperado. Retângulos `cam`/`game` são 0–1 e valem em qualquer resolução;
nenhum filtro do render assume 720p (os `scale=` são para o tamanho de saída; NVENC/x264 por qualidade, sem teto
de bitrate).
## Editor de cortes (`/clipper/edit/<id>`)
**Um caminho só de render:** todo corte é renderizado a partir de um **projeto de edição** (JSON versionado,
tabela `edits`; migrações v4 e v7), seja ele feito pela IA ou por você.
**A IA entrega o corte quase pronto.** Depois dos juízes, o render gera o projeto (`editor.auto_project`) com o que
o pipeline já sabe:
- **trecho:** do início da ação (`action_start_s` − 0,8 s) ao fim da reação (+0,8 s), sem cortar no meio de
palavra e limitado a `duration.maxS`;
- **silêncios:** vãos ≥ 2 s sem fala, quietos (< −38 dBFS) e longe do pico (±3 s) saem do corte;
- **legenda:** palavras do Whisper no estilo da configuração do corte, preset `pop` (tempo saneado no render: ver
"Tempo da legenda");
- **gancho:** o `hook` do analista nos primeiros 2,8 s, só se for curto (≤ 8 palavras e ≤ 48 caracteres) e sem tempo
da gravação (frase como "Aos 5085s, ele…" é recusada; `editor.pick_hook`); senão, o título do editor. Um
"aos/em NNN s" que sobrar é tirado, e texto acima de 60 caracteres é cortado em palavra inteira (nunca no meio);
- **zoom:** punch-in de 1,25× no `peak_s`, no rosto quando a câmera está em cima;
- **capa:** quadro do pico com o gancho;
- **layout e formato:** os da sessão/canal (o projeto pode trocar o formato só deste corte em `settings.format`).
O projeto fica marcado `meta.origin = "ai"` (com data, modelo e passos). O que a IA gerou fica guardado em
`ai_project_json` ("Projeto da IA" no editor volta a ele, e dá para desfazer). Se você salvar no editor, a origem
vira `user`. Nova avaliação dos juízes refaz só o projeto de origem `ai`; o seu nunca é apagado.
O painel abre o editor em **tela cheia**:
- barra superior com fila, título, origem, estado do salvamento, **Salvar projeto** (Ctrl+S; também salva sozinho),
botões para **minimizar** cada painel (camadas, transcrição/chat, propriedades), "IA sugere", atalhos e Exportar;
- **Camadas** à esquerda (textos, legenda, zoom, câmera, vídeo, áudio, narração, música, chat na tela, barra, capa),
transcrição/chat ao lado, **Fonte · Programa** no centro (gravação original e o 9:16) e **Propriedades** à direita;
- timeline na largura toda, com uma trilha por camada: C1 legenda, V3 textos, V2 zoom, **CAM câmera** (layout de
cada trecho), V1 vídeo (miniaturas), A1 áudio (forma de onda, "MUDO"), A2 narração, A3 música, CH chat.
Tudo cabe em 100vh, e cada painel rola sozinho. O desenho segue o padrão dos editores de vídeo (tokens `nle-*` em
`panel/src/app/globals.css`); fluxos secundários (exportar, IA, narração, atalhos) abrem em modal.
**Mexer com a mão:**
| Onde | Gesto | Efeito |
|---|---|---|
| Timeline, palavra da legenda | arrastar o corpo | move a palavra (ou o grupo selecionado) no tempo, sem passar pelas vizinhas |
| Timeline, palavra da legenda | puxar a borda esquerda ou direita | apara: encurta ou estica só aquele lado (o áudio não muda) |
| Timeline, clipe de vídeo/áudio | puxar as bordas · arrastar o corpo | estica/encolhe o trecho · desliza o trecho sobre a gravação |
| Timeline, clipe | lâmina (C) ou **Ctrl+Shift+clique** · S ou **Ctrl+K** | divide onde clicar · divide no playhead |
| Timeline, texto/zoom/narração | arrastar corpo e bordas | move e muda a duração |
| Programa (vídeo 9:16) | arrastar texto, gancho, legenda ou chat | muda a posição na tela (`x`/`y`); com um zoom selecionado, o clique põe o foco |
| Fonte | alternador Câmera / Área do jogo; arrastar o retângulo move, as alças redimensionam, arrastar em área vazia desenha outro, setas e Shift+setas pelo teclado | grava `settings.layout.cam`/`game` só deste corte ("Usar esta câmera nos próximos cortes da sessão" grava na sessão) |
| Transcrição | selecionar palavras → Tirar, Manter, **Editar** (troca o texto e reparte o tempo), **Ocultar** (só da legenda), Ênfase | corte pelo texto e correção da legenda |
O arraste de mover só começa depois de 4 px: um clique simples nunca tira o bloco do lugar.
### Tempo e modelo do projeto
- **Tempo da sessão:** `cuts`, palavras, textos, zoom, narração e capa. Remover um pedaço do meio não desloca o
que está ancorado no conteúdo.
- **Tempo de saída:** só o gancho.
| Campo | O que é |
|---|---|
| `source` | Janela carregada da gravação (`lo`/`hi`, até 10 min). |
| `settings` | Configuração do corte só deste corte (mesma validação de `layout.validate`), por cima de canal/sessão: layout, câmera, legenda, crédito e **`format.aspect`** (o corte pode sair horizontal num canal vertical e vice-versa). Projeto salvo antes do formato (sem `format`) segue o canal/sessão; sem nada, vertical. |
| `cuts` | Trechos mantidos, cada um com `mode` próprio (troca de layout por trecho, inclusive `cam_only`) e `muted` (trecho sem o áudio da live). Trechos encostados só se juntam com o mesmo `mode` e o mesmo `muted`. |
| `captions` | Preset `classic`, `pop`, `karaoke`, `single` ou `minimal`; `style` (mesma validação de `layout.validate`); `emphColor`; palavras editáveis (`emph`, `hidden`). |
| `overlays` | `hook`, `text` (posição `x` e `y`, 0–1; `x` ausente = centro) e `zoom` (escala, foco e rampa). `hook`/`text` têm ainda, opcionais: `style` (`plain` padrão, ou `banner` = tarja na largura toda, centrada em `y`, texto em maiúsculas em até 2 linhas — a fonte diminui em vez de cortar palavra), `bg` (cor da tarja), `color`, `font` (uma de `fonts`) e `anim` `slide` (tarja atravessa a tela em 0,24 s; texto entra deslizando com desfoque de 90 a 430 ms e assenta nítido). Projeto sem esses campos renderiza idêntico ao de antes. |
| `overlays` (`kind: "inset"`) | **Camada inserida** (recorte da tela em destaque): `start`/`end` (tempo da sessão), `src` `{x, y, w, h}` (recorte do quadro ORIGINAL, 0–1), `x`/`y` (centro na tela de saída, 0–1), `size` (largura, 0,1–1 da largura; a altura sai da proporção do `src`), `border` (`#RRGGBB` ou null), `borderW` (px no quadro lógico, 0–40, padrão 6), `radius` (px, 0–200, padrão 18), `shadow` (padrão true), `anim` (`pop` padrão, `fade`, `slide`, `none`) e `keys` opcionais `[{t, x, y, size, ease}]` para andar/crescer (mesma interpolação do reenquadramento). No máximo 12. Ordem no array = empilhamento (a última por cima); ficam acima do vídeo e do zoom e abaixo de legenda, gancho, textos e chat. |
| `reframe` | **Reenquadramento do jogo no tempo** (opcional; ausente = como antes): `{keys: [{t, cx, cy, w, ease}]}`, no máximo 60. `t` = tempo da sessão; `cx`/`cy` = centro da janela e `w` = largura (0,05–1), frações do quadro ORIGINAL. A altura sai da proporção da área do jogo do layout daquele trecho (parte de baixo no `cam_top`; a tela toda no `game_only`, `blur` e horizontal), então nunca distorce; zoom que não cabe encolhe a janela, e a janela é presa dentro do quadro (desloca, não deforma). `ease` = como chega ao key seguinte: `smooth`, `linear` ou `hold` (segura e salta no key seguinte); antes do 1º e depois do último, segura. Com keys, `layout.game` é ignorado (keys absolutos no quadro original). Não vale para `cam_only`. A capa usa a janela parada do instante dela. |
| `chat` | Chat da live na tela: `enabled`, `x`, `y` (base do bloco), `width`, `lines` (1–10), `size`, `showUser`. Cada mensagem fica até chegar a próxima (no máximo 9 s). |
| `progress` | Barra de progresso. |
| `audio` | Volume da live; `narration` (TTS, com a live abaixada por baixo); `music` (só de `assets/`, com ducking por `sidechaincompress`); `sfx`. |
| `cover` | Capa. Com `atStart`, a capa também entra nos 2 primeiros quadros do vídeo (0 s), para a rede usar como miniatura. |
| `meta` | Origem do projeto. |
### Render
`editor_render.py`:
- um `-ss` antes do `-i` para a janela inteira;
- `trim`/`atrim` por trecho e layout por trecho (`layout.layout_chain`);
- `concat`, depois `zoompan` (expressão do tempo), depois `ass` (legenda animada, gancho, textos, barra e
crédito), depois `fps=30` e `yuv420p`;
- áudio com `afade` de 20 ms nas emendas, `adelay`/`amix` para narração e efeitos, música em loop;
- saída MP4 no formato do corte (1080×1920 ou 1920×1080), 30 fps, H.264 + AAC 48 kHz; o `zoompan` e a capa no
início usam o mesmo tamanho. O formato do arquivo fica em `clips.aspect` (migração v8) e sai no JSON do corte.
### Reenquadramento e camadas inseridas (`app/reframe.py`)
Pedido do dono (17/11/2026, corte 61 em câmera-em-cima: o inventário ocupava a tela e saía só o miolo):
- **Reenquadramento**: `perspective` com `eval=frame` — os 4 cantos da janela (expressões do nº do quadro do trecho, `in`, que começa em 1) viram o quadro inteiro com interpolação **subpixel**, depois `scale` para a área do jogo. Os keys estão em tempo da sessão e cada trecho do corte usa o próprio início, então `cuts` não desalinha. Medido: janela a < 4 px do esperado em todos os quadros testados; zoom suave sem passo para trás nem tremida (protótipo: desvio da aceleração 0,12 px). `scale` com `eval=frame` + `crop` fixo falhou no encoder e arredonda a posição a pixel inteiro. Grafo > 20 000 caracteres (muitos keys) vai por arquivo (`-/filter_complex`).
- **Camadas inseridas**: o vídeo original de cada trecho é duplicado e concatenado (`[vraw]`); cada camada faz `crop` → `scale` → `alphamerge` (máscara dos cantos) → por cima de UMA imagem de decoração (sombra borrada + borda, gerada com numpy/OpenCV) → `scale` por quadro só se o tamanho muda (keys, pop) → `fade` de alfa → um `overlay` (expressão por quadro só se a posição muda: keys, slide).
- **Medido** (corte 61, 60 s, NVENC): sem nada 6,1–6,2 s; com reenquadramento 7,1–9,5 s; com reenquadramento + 2 camadas (pop e slide) 15,8–20,5 s (com sombra, borda e recorte postos separados era 28,2 s).
- No 9:16 com câmera em cima, a área do jogo é 1080×1268 (proporção 0,85): um inventário de 16:10 não cabe inteiro sem faixas; a janela mostra no máximo 0,48 da largura (uma coluna grande, ex.: a bolsa). No 16:9 cabe.
- A IA ainda NÃO propõe reenquadramento nem camadas: o analista não devolve região da tela (precisaria de caixa na imagem, que hoje não é confiável).
### Tempo da legenda (fala rápida)
Pedido do dono (16/11/2026): "com fala rápida a legenda sai fora do tempo e fica uma em cima da outra". Causa
medida na cópia do banco (3 projetos, sessão 3 do skipnho): **63 de 286** eventos de legenda começavam antes do fim
do anterior: o fim de cada bloco (fim da última palavra, no mínimo +0,25 s) passava do início do bloco seguinte, e o
libass **empilha** dois eventos ativos ao mesmo tempo. O Whisper também devolve palavras de 0 s (380 de 15 583) e
palavras que começam no mesmo instante. Agora (`app/subtitles.py`, usado pelo render do editor e pelo do worker,
nos dois formatos):
- `clean_words`: ordena, dá 60 ms mínimos por palavra, empurra 40 ms a que começa junto com a anterior e corta o fim
de cada palavra no início da seguinte;
- `group_words`: até `maxWords` e um limite de caracteres; quebra em pausa > 0,6 s ou bloco > 3,2 s; com fala muito
rápida (bloco cheio durando < 0,7 s) aceita **uma** palavra a mais, se couber, para o bloco não piscar;
- `caption_blocks`: o fim de um bloco é cortado no início do seguinte: **nunca dois blocos na tela**. O bloco entra
no início da sua 1ª palavra e a palavra destacada troca no início de cada palavra (sem atraso em relação ao áudio);
- a ênfase marcada no editor é casada nos tempos originais, antes do saneamento.
Medido depois: **0 de 299** eventos sobrepostos; deslocamento máximo do início de uma palavra = 140 ms (só em
sequências de várias palavras que o Whisper pôs no mesmo instante; nas demais, 0); 3–7 blocos de 4 palavras por
corte (fala rápida). O vertical com fala normal sai idêntico ao de antes (MD5 dos quadros conferido).
Validação forte (`editor.validate_project`): limites de duração (3–180 s) e de quantidade, texto escapado no ASS,
áudio só de `assets/` ou dos TTS gerados pelo editor, e nada vira comando de shell.
### Medido (cópia do banco, sessão 3 do skipnho, 16/11/2026)
| Operação | Tempo |
|---|---|
| Proxy 480p de 120 s | 4,3 s |
| Forma de onda | 0,2 s |
| Re-transcrição de 13 s (Whisper) | 0,7 s |
| TTS | 2,4 s |
| IA sugere (`gpt-6-luna`) | 6,0 s |
| Prévia real de 5 s | 0,8–1,3 s |
| Export de 55,6 s | ~9 s |
| Corte 10 pelos juízes até o vídeo pelo projeto da IA | 24 s |
### Limitações
- A prévia do navegador é aproximada (canvas); a exata é "Prévia real".
- A tarja do gancho no layout câmera-em-cima fica sobre o painel da câmera nos primeiros segundos (a legenda fica na
emenda); ajuste `y` no editor se preferir.
- Camadas inseridas não entram na capa (a capa usa só o reenquadramento parado).
- A prévia do editor (canvas) segue o formato do corte (9:16 ou 16:9, quadro lógico de `frames`), mas é aproximada:
a exata é a "Prévia real" ou o export.
- `clips.aspect` é gravado no render: antes do 1º render o corte informa `vertical` (padrão), mesmo num canal
horizontal.
- A varredura da IA limita o fim do momento ao fim da janela varrida: perto do fim da janela, a proposta pode sair
mais curta que `minS` (os juízes ainda podem recuar o início).
- Emoji sai monocromático (libass).
- Sem B-roll e sem segunda trilha de vídeo: um pedaço não pode ser arrastado para outra camada nem tocar fora da
ordem da gravação (a timeline é o tempo da sessão).
- Código novo de render (`cam_only`, `muted`, `chat`, `cover.atStart`, texto com `x`) só vale depois de reiniciar o
serviço; um serviço antigo rejeita o projeto com `cam_only`.
- A forma de onda e o proxy cobrem só a janela carregada ("+30 s antes/depois" gera outra).
- O corte usa os blocos `.ts`: depois de `CLIPPER_KEEP_HOURS` sem trabalho pendente, a edição daquele trecho
deixa de ser possível.
- Nova avaliação dos juízes (rejudge) troca o trecho de um projeto de origem `ai` (ele é refeito), mas não o de
um projeto seu.
## Rastreio de reação (rosto do streamer)
`app/face.py` (E/S) + `app/reaction.py` (lógica pura). Plano: `doc/PLANO_RASTREIO_REACAO.md`; números:
`doc/FACE_BAKEOFF.md`. Opção `faceTrack` (padrão ligada; `PUT /v1/judge`, interruptor no painel) — roda no PC, sem IA.
- **Câmera**: YuNet (`face_detection_yunet_2026may.onnx`) em 12 quadros; `locate_cam` agrupa pelo centro do grupo (1
rosto de tolerância), exige presença em ≥ 50 % dos quadros e confiança média do grupo ≥ 0,7 (webcam real dá
0,92–0,94; objeto parado que engana o YuNet, ~0,63) e expande o rosto (3,2× largura, 3,6× altura, folga na
testa). Câmera em tela cheia (rosto > 40 % da altura) não vira layout. Sem rosto enquanto grava: tenta de novo em 5 min.
- **Rastreio**: thread `face` do motor, um bloco por vez (sessões gravando primeiro; sessões antigas com blocos
ainda no disco também). FFmpeg recorta a câmera +10 %, ~384 px, 6 qps, `rgb24` por pipe → MediaPipe Face
Landmarker (VIDEO, um por bloco) → série por segundo na tabela `face_track` (status `done`/`no_cam`/`error`).
`cx`/`cy`/`size` gravados no **quadro inteiro**. Medido: ~1,5 s de CPU por bloco de 30 s. Sem MediaPipe, cai no
OpenSeeFace (só posição, sem expressões). Câmera trocada (detecção ou layout) → a série da sessão é refeita sozinha.
- **Sinal**: z robusto de cada expressão contra o normal dos últimos 180 s do próprio streamer; rótulos risada,
grito, susto, confuso, choque, raiva. Movimento só rotula (susto) e só com rosto em ≥ 80 % do segundo.
- **Cortes**: momentos do chat/áudio ganham `reasons.face` e até +0,6 na nota; fonte nova `face` só com z ≥ 6 **e**
apoio (áudio suavizado ≥ 1,5 ou ≥ 2 mensagens de reação). Com câmera e rastreio ligado, 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: …".
- **Modelos**: `data/clipper/models/`, conferidos pelo sha256 de `clipper/models.lock.json`; o `setup.ps1` (passo 6b)
baixa; o serviço baixa sob demanda se faltar (fora da thread do chat). Falha de modelo não marca blocos: nova
tentativa em 5 min.
- **API**: `GET /v1/sessions/{id}/face?from=&to=` (série, `signal`, picos, câmera, progresso) e `POST …/face/reset`.
## Juiz de IA (pela CLI, sem chave de API)
Usa as CLIs já logadas no PC — as mesmas da página Agente:
| Provedor | Comando | Modelo padrão | Lista de modelos |
|---|---|---|---|
| `codex` (padrão) | `codex exec --ephemeral --sandbox read-only --output-schema … -o … -` | `gpt-6-luna` (rápido e barato) | `~/.codex/models_cache.json` (só `visibility: list`) |
| `claude` | `claude -p --json-schema … --no-session-persistence` (imagens pela ferramenta Read; web por WebSearch) | `haiku` | `haiku`, `sonnet`, `opus` |
| `off` | — | — | só a heurística |
Codex: imagens com `-i` (uma por flag, antes de `-`), busca na web com `--search` (opção global, antes de `exec`).
Provedor, modelo do editor, **modelo do analista** (`analystModel`, vazio = o mesmo), nota mínima, varredura
(`scanEnabled`, `scanIntervalS`), visão (`vision`), detecção de câmera (`camDetect`) e rastreio de reação (`faceTrack`) se trocam no painel (`PUT /v1/judge`) e ficam na tabela `settings` do banco — sem
reiniciar. O `.env` só dá os valores iniciais. Medido (16/11/2026): `gpt-6-luna` respondeu em ~7 s por candidato.
Falha do juiz não perde o momento: o corte segue pela heurística e o erro fica em `judge.error`.
## Instalação e subida
- `setup.bat` cria `clipper/.venv` (Python 3.12 via uv), instala `requirements.txt` (Streamlink 8.6.3) e gera
`clipper/.env` com chave nova.
- `start.bat` / `pnpm dev` sobem voz + Clipador + painel. Sem `clipper/.venv` ou sem chave, o Clipador é pulado com aviso.
- Só o serviço: `cd clipper && .venv\Scripts\python -m uvicorn app.main:build --factory --host 127.0.0.1 --port 4520`
- Testes: `cd clipper && .venv\Scripts\python -m pytest`
- Mudança de **código** em `clipper/app/` só vale depois de reiniciar o serviço (o `pnpm dev` não usa `--reload`).
Provedor/modelo do juiz não precisam: mudam pelo painel na hora.
Precisa do FFmpeg com `libass` (legenda) — o build `essentials` do gyan.dev tem. NVENC é usado quando existe.
## Configuração (`clipper/.env`)
| Variável | Padrão | O que faz |
|---|---|---|
| `CLIPPER_SERVICE_KEY` | (setup) | chave exigida em toda rota, exceto `GET /health` |
| `CLIPPER_PORT` | 4520 | faixa 4500–4599 |
| ~~`CLIPPER_QUALITY`~~ | — | não é mais lida: a qualidade é `capture.quality` por canal/sessão (padrão `best`) |
| `CLIPPER_SEGMENT_S` | 30 | tamanho do bloco gravado |
| `CLIPPER_POLL_S` | 60 | intervalo para checar se um canal monitorado entrou ao vivo |
| `CLIPPER_KEEP_HOURS` | 6 | apaga blocos mais velhos que isto se nenhum corte pendente precisar (0 = nunca) |
| `CLIPPER_LANGUAGE` | `pt-BR` | idioma da transcrição |
| `CLIPPER_ENCODER` | `auto` | `auto` (NVENC se houver) · `libx264` · `h264_nvenc` |
| `CLIPPER_JUDGE_PROVIDER` / `_MODEL` / `_MIN_SCORE` | `codex` / (padrão) / 6 | valores iniciais do juiz |
| `CLIPPER_DATA_DIR` | `data/clipper` | banco, blocos gravados, modelos do rastreio e arquivos do juiz; para isolar uma instância de teste (relativo ao repo ou absoluto, **dentro** do repo) |
| `CLIPPER_OUTPUT_DIR` | `output/clipper` | cortes prontos, prévias e projetos do editor (mesma regra; fora de `output/` o painel não serve os arquivos) |
Instância de teste isolada (não toca no banco nem nos blocos do serviço do usuário): defina `CLIPPER_PORT=4521`,
`CLIPPER_DATA_DIR=output/<teste>/data` e `CLIPPER_OUTPUT_DIR=output/<teste>/clips` no ambiente (o ambiente vence o
`clipper/.env`) e suba o uvicorn com essa porta. Atenção: o serviço de voz é compartilhado e guarda a transcrição pela
chave `clipper-<sessão>-<bloco>`; num banco novo as sessões recomeçam do 1 e colidiriam com as do banco real — suba o
`sqlite_sequence` de `sessions` (ex.: 90000) antes da primeira sessão.
## API (todas com `X-Service-Key`)
| Rota | O que faz |
|---|---|
| `GET /health` | sem chave |
| `GET /v1/status` | ferramentas, voz, juiz, gravações ativas |
| `GET/PUT /v1/judge` | provedor, modelos (editor/analista), nota mínima, varredura, visão, câmera (+ lista de modelos) |
| `GET/PUT /v1/channels/{id}/settings` · `GET/PUT /v1/sessions/{id}/settings` | configuração do corte: `own`, `effective`, `defaults` (com `format`, `duration` e `hook`), `modes`, `fonts`, `fontFiles` (`{família: "assets/fonts/…ttf"}` das empacotadas, relativo à raiz do repositório), `hookStyles`, `hookAnims`, `aspects`, `frames` (`{vertical, horizontal: {width, height, canvasWidth, canvasHeight}}`, para o painel desenhar a prévia) e `captureQualities` (`[{id, label, maxHeight, gbPerHour, gbPerHourMax, hint}]`) |
| `GET /v1/sessions/{id}/frame?t=` · `POST …/preview` · `POST …/detect-cam[?ai=true]` | quadro para o editor, prévia do layout, achar webcam (local primeiro) |
| `GET /v1/sessions/{id}/face?from=&to=` · `POST …/face/reset` | série por segundo do rosto (cx/cy/size no quadro inteiro, expressões, `signal`) e picos; refazer o rastreio |
| `PUT /v1/sessions/{id}/game` · `GET /v1/games` · `POST /v1/games/{id}/research` · `PUT /v1/games/{id}` · `POST /v1/games/{id}/refine` · `DELETE /v1/games/{id}/notes/{n}` | jogo da sessão, perfis pesquisados, edição à mão e pedidos à IA |
| `GET /v1/emotes?channel=twitch-<login>` | emotes do canal, usos e peso aprendido |
| `GET/POST /v1/channels` · `PATCH/DELETE /v1/channels/{id}` · `POST /v1/channels/{id}/check` | canais (`monitor` grava sozinho ao entrar ao vivo; `authorized` = streamer autorizou) |
| `GET/POST /v1/sessions` · `GET/DELETE /v1/sessions/{id}` · `POST …/stop` | gravar live ou processar VOD pelo link; cada sessão traz `capture` (resolução, qps, codec e taxa gravados de fato; `null` = sessão antiga) |
| `GET /v1/sessions/{id}/timeline` | mensagens/s, razão do chat e volume por segundo |
| `POST /v1/sessions/{id}/clips` | **cortar agora**: `{lastS}` ou `{startS,endS}`; corte manual nunca é descartado pela IA |
| `GET /v1/clips?status=&session=` · `GET/PATCH /v1/clips/{id}` · `POST …/render` · `POST …/rejudge` | fila de cortes; cada corte traz `aspect` (`vertical` ou `horizontal`) = formato em que o arquivo foi renderizado |
| `DELETE /v1/clips/{id}[?confirmPublished=true]` | **apagar um corte**: linha, projeto de edição e arquivos (ver "Apagar cortes"). 200 `{id, sessionId, status, removedFiles, left: [{file, reason}]}`; 404 `not_found`; 409 `busy_candidate` / `busy_rendering` / `published` / `changed` (`{error, code}`) |
| `POST /v1/clips/delete` `{ids: [..≤500]}` ou `{statuses: [...], sessionId?}`, `confirmPublished?` | **apagar em lote** (selecionados ou a aba inteira, até 500 por chamada, do mais novo para o mais velho). 200 `{requested, remaining, deleted: [como acima], failed: [{id, code, reason}]}`; 400 sem `ids` nem `statuses` (ou os dois, ou `sessionId` com `ids`); 422 acima de 500 ids ou estado inválido |
| `GET/PUT/DELETE /v1/clips/{id}/edit` (PUT com `rev`; 409 se outro salvou) · `POST …/proxy` `{lo,hi}` · `GET …/waveform?lo=&hi=` | editor: projeto, prévia 480p e forma de onda |
| `POST /v1/clips/{id}/preview-render` `{fromS,durationS≤10,project?}` · `POST …/export` | prévia real de poucos segundos (no formato do corte; com `cover.atStart` e `fromS` = 0 a capa entra nos 2 primeiros quadros, como no export); exportar (volta para a fila de render → `ready`) |
| `POST /v1/clips/{id}/retranscribe` `{startS,endS≤90 s}` · `POST …/tts` `{text,voice,speed}` · `POST …/suggest` | Whisper de novo; narração (WAV em `edit-<id>/tts-*.wav`); IA sugere gancho, título, início/fim, trechos mortos e zooms |
Origem do corte (`source`): `chat`, `audio`, `ai` (varredura), `face` (reação no rosto com apoio do áudio/chat), `manual`.
Estados do corte: `candidate` (esperando IA) → `pending` (fila de render) → `rendering` → `ready` → `approved`/`rejected`;
`discarded` (IA descartou) e `error`. `published` é só uma marcação manual até existir a etapa de publicação nas redes.
### Apagar cortes (`app/clip_delete.py`)
Pedido do dono (17/11/2026): apagar um corte, vários ou todos de uma aba, inclusive "Descartados pela IA" e "Para
aprovar". No painel, tudo discreto (o dono reprovou uma barra presa no topo): "Apagar" em cada cartão (confirmação no
próprio cartão); no canto da linha das abas, "Selecionar" e o menu "⋯" com "Apagar todos desta aba (N)" (modal com a
contagem; com a fila filtrada por sessão, vale só para aquela sessão e o modal diz isso); a caixa de cada cartão só
aparece no hover/foco ou no modo de seleção; com algo marcado, uma pílula flutuante no canto inferior direito
("N selecionados · Selecionar todos · Apagar · ✕"; Esc sai do modo). O painel manda os **ids que está mostrando** (não `statuses`):
corte que chegar depois da confirmação não é apagado junto.
- **O que some:** a linha em `clips`, o projeto (`edits`) e os arquivos: `clip-<id>.mp4`/`.jpg`/`-cover.jpg` e restos do
render (`clip-<id>.*`, `clip-<id>-*`) em `output/clipper/<sessão>/`, a pasta do editor `edit-<id>/` (proxy, forma de
onda, TTS, prévias) e os quadros do juiz `data/clipper/sessions/<sessão>/frames/clip<id>-*.jpg`. Os blocos gravados
(`.ts`) ficam: são da sessão.
- **Só dentro das pastas do Clipador** (`CLIPPER_OUTPUT_DIR`, `CLIPPER_DATA_DIR`): cada caminho é resolvido antes;
caminho de fora (inclusive `clips.file` apontando para fora, ou pasta da sessão trocada por junção) não é tocado e
volta em `left` com "fora das pastas do Clipador". Link ou junção dentro da pasta do editor: some só o link, o alvo
fica. Arquivo em uso também volta em `left`.
- **Recusa:** `candidate` (a IA está avaliando) e `rendering` (inclusive o `pending` que o motor acabou de pegar:
`Engine.render_clip` confere sob o mesmo trinco que o corte ainda existe). `published` só com `confirmPublished`
(o vídeo já foi postado; hoje ninguém marca `published`, mas a etapa de publicação vai precisar do registro).
- **O momento apagado não volta.** Sem o corte, a regra anti-duplicado (que compara com cortes em qualquer estado,
inclusive descartados) deixaria a IA recriar o mesmo momento na passada seguinte da live ou na passada final da
sessão. Fica uma marca mínima na tabela `deleted_clips` (migração **v10**: id, sessão, pico, trecho final, janela
original do candidato, estado, origem, título, data), que entra na conta como se o corte existisse: no candidato
(`find_new_clips`), na varredura da IA (`mark_spans`) e no trecho final depois do juiz para quem foi apagado num
estado de `VETO_STATUSES` ("Duplicado do corte N (que você apagou)"; descartado pela IA apagado não veta, como
antes). A marca some com a sessão (`ON DELETE CASCADE`).
- **Nada mais quebra:** o peso aprendido dos emotes (`clips.learned`) mora na tabela `emotes` e fica; `judge.duplicateOf`
de outros cortes é só texto (nada lê o id de volta); a memória da varredura (`sessions.memory_json`) não guarda id de
corte; apagar o último pendente deixa a sessão terminar (`finish_if_done`); `prune` deixa de segurar os blocos dele.
- Testes: `tests/test_clip_delete.py`.
## Armadilhas já resolvidas
- **Legenda sumia do vídeo**: com `-ss` depois do `-i`, o filtro `ass` via o tempo do bloco (não do corte) e a legenda
saía deslocada. `-ss` vai antes do `-i` (`app/media.py`).
- **`.upper()` na linha ASS** transformava a tag `\c` em `\C` (inválida). Maiúsculas só no texto.
- **Falsos positivos com chat calmo**: 3 mensagens com um emote `clip5k1hmm` davam razão 2,35. Regras: palavra inteira
para "clip", mínimo de mensagens no pico (hoje proporcional ao chat, entre 4 e 12), 60 s de aquecimento (teste de regressão em `tests/test_scoring.py`).
- **Chat pequeno sem corte nenhum** (skipnho, 0,15 msg/s): mínimo fixo de 12 mensagens → proporcional + varredura.
- **Título preso à transcrição** ("jogando três jogos" num momento de lag): dois juízes, frames e glossário do chat.
- **Crédito em cima do rosto** no layout câmera-em-cima: desce para o pé do painel da câmera.
- `codex.cmd` (lote do npm) não roda bem sem shell: o juiz chama o `codex.js` pelo Node, como o painel.
- Matar o serviço à força não deixou `streamlink`/`ffmpeg` órfãos no teste, mas em queda o banco marca as sessões
em andamento como `interrupted` na próxima subida.
- **Palavra com duração zero do Whisper** (ex.: "queria" 1020,10–1020,10 no skipnho) derrubava a validação do
projeto do editor: agora ganha 50 ms.
- **Capa sem imagem**: o mjpeg do FFmpeg 7.1 recusa yuv420p marcado como faixa "tv" (bloco do libx264); o quadro
intermediário da capa é PNG.
- **Gancho cortado no meio**: o `hook` do analista às vezes é uma frase descritiva ("Aos 5085s, ele solta que…",
corte 25 do skipnho); o projeto da IA só usa se for curto (≤ 8 palavras, ≤ 48 caracteres) e sem tempo da gravação,
senão usa o título do editor; resto de "aos NNN s" é tirado e o texto é cortado em palavra inteira (`pick_hook`).
- **Live no ar foi para "processando" depois de reiniciar o serviço** (16/11/2026, sessão 3): a retomada da subida
fazia UMA checagem; o `streamlink --json` falhou (timeout/erro eram engolidos e pareciam "offline") e a sessão foi
encerrada. Agora `Engine.live_check` separa `live`, `offline` ("No playable streams…") e `unknown` (timeout, erro,
JSON inválido; motivo e fim do stderr vão para o log), e `keep_live` tenta de novo com espera crescente
(0, 10, 20, 40, 60, 90, 120 s ≈ 5,7 min). Enquanto tenta, a sessão fica `interrupted` ("Retomar gravação" no
painel); só processa depois de esgotar as tentativas ou de ver `offline` 2 vezes seguidas. Se você retomar,
processar ou apagar no meio, a thread para sem mexer. O mesmo vale para a **captura que cai no meio da live**
(antes ia direto para `processing`): ela vira `interrupted` e passa pelo mesmo `keep_live`; 3 retomadas seguidas
sem nenhum bloco novo desistem.
- **Cortes presos em "renderizando"** (17/11/2026, sessão 3: 10 cortes, ids 42–58): o serviço subiu com uma versão
intermediária da legenda que dava `KeyError` quando o saneamento mudava alguma palavra (o corte 40, com 0 palavras
mudadas, saiu; os 10 presos tinham de 6 a 20). A exceção não prevista escapava do render, o laço reiniciava e o corte
ficava em `rendering` para sempre. Agora qualquer falha no render vira `error` com a mensagem e a fila segue; um
`rendering` que este processo não está renderizando há mais de 5 min volta para `pending` (na 3ª vez, `error`).
- **O mesmo momento virando vários cortes** (sessão 3: pico 1149 s → cortes 42, 47, 49, 51, 52, em cima do 9, já
pronto): a checagem comparava o candidato (em volta do pico) só com o trecho final dos cortes, mas o juiz recua o
trecho (1012–1100); na passada seguinte o mesmo pico já não sobrepunha e era criado de novo. Agora (`worker.py`):
o candidato guarda a janela original (`reasons.candidateStartS/EndS`) e não nasce se o pico estiver a ≤ 10 s de
outro corte, ou se sobrepuser o trecho final ou a janela original de um corte em qualquer estado (inclusive
descartado). Depois do juiz, o trecho final é conferido contra os cortes mantidos (pendente, renderizando, pronto,
aprovado, publicado): mesmo momento (pico a ≤ 10 s ou ≥ 60 % do mais curto coberto) = descartado como
"Duplicado do corte N" (`judge.duplicateOf`). Vale para chat, áudio, rosto e varredura; "cortar agora" (manual)
só ganha o aviso `judge.warning`. Antes de cada render, pendentes que já são o mesmo momento de um corte pronto,
aprovado, publicado ou rejeitado, de um corte apagado que estava num desses estados, ou de um pendente mais antigo
saem da fila como "Duplicado do corte N (que você rejeitou/apagou)" — o mesmo conjunto do veto depois do juiz;
descartado pela IA não veta (nunca sai um manual ou um que você exportou do editor). Cortes duplicados que JÁ estão
prontos não são mexidos: rejeite à mão.
- **Testes chamavam a CLI de IA de verdade**: o juiz falso dos testes não cobria o analista; agora `FakeJudge.ask`
falha sempre (caminho de "IA fora" que o serviço já trata).
- **Cortes mais curtos que o mínimo** (sessão 3, mínimo 60: cortes 43 = 54,6 s, 44 = 55,0 s, 55 = 46,8 s, 58 = 57,7 s,
61 = 43,8 s): o projeto da IA ADIANTAVA o início para o `action_start_s` do analista quando ele vinha depois do
início do juiz ("início no começo da ação"), e nada reimpunha o mínimo depois. Também: o juiz limitava o fim em
`hi` sem recuar o início, a varredura idem, e `fit_length` podia passar do máximo. Agora todos passam por
`fit_window` com mínimo + 1 s, e o início só adianta se o mínimo continuar.
- **Fonte empacotada ignorada pelo libass**: o `fontsdir` NÃO lê subpastas (medido: `fonts/` não achava nada,
`fonts/bangers/` achava). A pasta é plana. No Windows o caminho vai absoluto, entre aspas, com `:` escapado. A
Poppins ExtraBold só é achada pelo nome de família ID 1 ("Poppins ExtraBold"), não por "Poppins".
- **Corte que atravessa blocos de resoluções ou codecs diferentes** (retomada em outra qualidade, ou a fonte mudou
no meio): o vídeo parava na emenda sem erro (medido em 17/11/2026: corte de 35 s com 20 s de vídeo; 15 s na troca
H.264 → HEVC). Agora `uniform_segments` (`editor_render.py`) converte os blocos do trecho num intermediário
uniforme (maior tamanho do trecho, 30 qps) só nesse caso, no render e no proxy; trecho com blocos iguais segue
pelo caminho de sempre. A qualidade pode ser trocada também numa retomada. O proxy faz `fps` antes do `scale`.
- **"Não está gerando os clipes"** (17/11/2026, sessão 3, 9000–10560 s): diagnóstico numa cópia do banco. A live
esfriou: chat de 0,27–0,39 msg/s e 56–78 reações a cada 500 s (7000–8000 s) caiu para 0,04–0,10 msg/s e 2–10
reações (9000–10000 s); a heurística não achou NENHUM pico entre 8872 e 10350 s, nem com as regras antigas
(15–59 s, só sobreposição); a varredura descreveu cada janela como "sem confronto ou reação marcante"; e o juiz deu
3,2–4,2 aos candidatos 65–67 (mínimo 6). Regras atuais × antigas em 7200–10560 s: 1 × 4 candidatos, mas os 3 a
mais eram rosto fraco (nota 2,5) ou a cena do corte 61, rejeitado; zona proibida 34 % × 24 %. Afrouxar o
anti-duplicado não traria corte novo, então ficou como está. Mudanças: rejeitado também veta o trecho final depois
do juiz ("Duplicado do corte N (que você rejeitou)"); a varredura grava `proposals`/`created` em cada janela da
memória (e no log), porque antes não dava para saber se ela não propôs nada ou se foi barrada.
- **Legenda uma em cima da outra com fala rápida**: o fim de um bloco passava do início do seguinte e o libass
empilhava os dois. Blocos agora nunca se sobrepõem e as palavras são saneadas (ver "Tempo da legenda").
- **Quadro errado ao buscar dentro de um bloco `.ts`** (17/11/2026): o demuxer mpegts do FFmpeg trata todo pacote
como ponto de busca; `-ss` antes do `-i` caía num quadro P. No H.264 saía o próximo quadro-chave (até 2 s depois);
no **HEVC** (2K da Twitch) saía um quadro **cinza** — frames do juiz, capa e YuNet (a câmera não era achada). Um
2º `-ss` depois do `-i` também erra com áudio no bloco (7,5 s virou 6,06 s). Agora `media.seek_args`: busca 4 s
antes, `-copyts -start_at_zero` e `select='gte(t,alvo)'` (usado por `grab_frame` e `face.grab_bgr`). Render e
proxy (concat demuxer) já buscavam certo.
- **Rastreio do rosto com resolução trocada no meio da sessão**: o tamanho do quadro era medido uma vez por sessão;
uma retomada em outra qualidade recortaria a câmera no lugar errado. Agora é medido por bloco.
## Limites conhecidos
- **Direitos autorais**: cortar lives de terceiros sem autorização pode render strike/derrubada da conta. Cada corte
leva o crédito do canal no vídeo e na legenda; marque `authorized` nos canais que autorizaram.
- Chat do **YouTube** ainda não é lido (exige a API do YouTube); a sessão segue pelo áudio e pela transcrição.
- Chat da **Kick** usa o websocket público do site (não oficial; o Cloudflare às vezes bloqueia o id da sala).
- VOD não tem chat (o replay de chat da Twitch não é API pública): só áudio + transcrição.
- A webcam é tratada como retângulo fixo (overlay do streamer); se ele mover a câmera no meio da live, ajuste no editor.
- O analista pode errar a situação quando tela, fala e chat não batem (ex.: corte 10 do skipnho: chat "live
travando", analista concluiu "pegadinha na conversa") — a confiança e o motivo ficam no corte para você conferir.