Files
CenaForge/doc/PLANO_RASTREIO_REACAO.md
T
MateuusandClaude Opus 5.5 84f30bbc2d 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>
2026-11-17 16:35:09 -03:00

138 lines
10 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Plano — Rastreio de reação (câmera + rosto do streamer) no Clipador
Data: 16/11/2026. Dono do pedido: usuário. Escopo: **só o Clipador** (`clipper/`); o editor de cortes está com
outro agente — não mexer em `clipper/app/editor*.py` nem nos componentes do editor no painel.
## Objetivo
1. Saber, sem gastar IA, **se a live tem câmera** e **onde ela está** no quadro.
2. **Rastrear o rosto** do streamer dentro da câmera, ao longo da live inteira.
3. Transformar as **expressões** (risada, grito, susto, raiva, choque, movimento da cabeça) num sinal por segundo
que **reforça e cria cortes**, ajuda a achar o início/fim da reação e vai, em texto, para o juiz analista.
4. Deixar a série do rosto (centro, tamanho, reação) disponível na API para o editor reenquadrar a câmera.
## Stack escolhida (pesquisa de 16/11/2026)
| Papel | Ferramenta | Licença | Por quê |
|---|---|---|---|
| Achar a câmera (rosto pequeno no quadro inteiro) | **YuNet** (OpenCV Zoo, `cv2.FaceDetectorYN`) | MIT | leve, CPU, qualquer resolução; OpenCV já vem com o MediaPipe |
| Pontos + expressões | **MediaPipe Face Landmarker** (`mediapipe==1.2.3`) | Apache-2.0 | 478 pontos 3D + **52 blendshapes** prontos (jawOpen, mouthSmile*, eyeWide*, browInnerUp, browDown…); 37,7 mil estrelas, commit diário |
| Plano B (câmera escura/pequena/comprimida) | **OpenSeeFace** — só os `.onnx` no onnxruntime atual | BSD-2 | mais estável em condição ruim, segundo o autor; sem blendshapes; repo preso em Python 3.9 |
| Fase 2 (opcional) | EmotiEffLib (ex-HSEmotion) | Apache-2.0 | rótulo de emoção para o juiz |
Descartados: SCRFD/InsightFace (pesos não comerciais), YOLO-Face (GPL/AGPL), LibreFace (não comercial),
OpenFace 3.0 (só pesquisa, parado desde jun/2025), Py-Feat (licença indefinida). Os cortes serão publicados:
**nada de peso não comercial ou copyleft**.
## Fases e agentes
```
Fase 0 A "bancada" ──┐ (paralelo)
Fase 1 B "sinal" ──┤
└─► Fase 2 C "integração" ─► Fase 3 D revisão (python-reviewer) ─► E skill-updater
```
### Fase 0 — Agente A "bancada" (instalação + teste comparativo)
Dono de: `clipper/requirements.txt`, `clipper/models.lock.json` (novo), `scripts/setup.ps1` (passo 6b),
`clipper/tools/face_bench.py` (novo), `doc/FACE_BAKEOFF.md` (novo).
1. Instalar com `uv pip install --python clipper/.venv/Scripts/python.exe` e **fixar versões** no
`requirements.txt`: `mediapipe==1.2.3`, `onnxruntime==1.32.0` (o MediaPipe traz `opencv-contrib-python` e
`numpy`; **não** instalar `opencv-python-headless` junto — conflito de `cv2`). Conferir `import` e a API
(`mediapipe.tasks.python.vision.FaceLandmarker`, `cv2.FaceDetectorYN`).
2. Baixar os modelos para `data/clipper/models/` e registrar URL imutável + sha256 em `clipper/models.lock.json`:
YuNet (variante compatível com o OpenCV instalado — 5.x pode exigir a `2026may` de entrada dinâmica),
`face_landmarker.task` (float16/1), e os `.onnx` do OpenSeeFace (modelo 3 + detector) do commit fixado.
`setup.ps1` passo 6b baixa e confere o sha256.
3. Bancada com a sessão 3 (skipnho, 2937 s, 99 blocos `.ts` em `data/clipper/sessions/3/`; câmera achada pela IA
em `cam_json`: x 0,014 y 0,532 w 0,183 h 0,395):
- **Achar a câmera:** 12 quadros espalhados; YuNet no quadro inteiro → taxa de rosto, posição estável?
IoU do retângulo estimado com o da IA.
- **Rastreio:** 3 trechos de 30 s (um calmo, um com o lag/mortes que geraram corte, um qualquer) a 6 qps no
recorte da câmera: MediaPipe × OpenSeeFace → % de quadros com rosto, tempo por quadro (CPU), e se os
blendshapes sobem nos momentos de reação (comparar com `clips` existentes da sessão 3).
- Se houver outra sessão/canal disponível, repetir a câmera nela.
4. Escrever `doc/FACE_BAKEOFF.md` com números, quadros de exemplo (salvar em `output/face-bench/`) e a
**decisão**: MediaPipe confirmado ou plano B. Critério: rosto em ≥ 85 % dos quadros com o streamer presente e
≤ 15 ms/quadro na CPU.
### Fase 1 — Agente B "sinal" (lógica pura, sem dependências)
Dono de: `clipper/app/reaction.py` (novo), `clipper/tests/test_reaction.py` (novo). Python puro (como
`scoring.py`), testável sem modelo.
- `FaceSample` (por quadro): `t`, `present`, `cx`, `cy`, `size`, `blend` (dict nome→0..1).
- `per_second(samples, duration)` → lista de `FaceSecond` (`present` 0..1, `cx`, `cy`, `size`, `smile`, `jaw`,
`surprise`, `frown`, `blink`, `motion`), com médias/máximos por segundo; `motion` = deslocamento do centro
normalizado pelo tamanho do rosto.
- `reaction_signal(seconds, baseline_s=180)` → intensidade por segundo **relativa ao neutro do próprio
streamer**: z robusto (mediana + MAD) de cada canal sobre a janela recente só com segundos com rosto; o sinal é o
máximo ponderado dos canais; `None` sem rosto.
- `label(second)` → `risada` (smile+jaw), `grito` (jaw sem smile), `susto` (surprise+motion), `raiva` (frown),
`choque` (surprise sem motion), `neutro`.
- `reaction_moments(...)`/`summarize(window)` → picos com rótulo, início da reação (onset) e texto curto para o
juiz ("risada forte em 12 s, susto em 15 s").
- `locate_cam(detections_per_frame, frame_w, frame_h)` → agrupa rostos por posição; câmera = grupo presente em
≥ 50 % dos quadros e estável; devolve `{hasWebcam, cam, faceRect, confidence, fullFrame}`. Rosto > 40 % da
altura = câmera em tela cheia (`fullFrame`). Retângulo: bordas persistentes da moldura quando dadas (média de
gradiente entre quadros, passada como parâmetro opcional), senão rosto expandido (≈3,2× largura, 3,6× altura,
deslocado para baixo), recortado em 0..1.
- Testes: séries sintéticas (neutro com ruído → sem pico; risada → pico `risada` com onset certo; streamer com
"neutro sorridente" não vira falso positivo; câmera estável × rosto que aparece no jogo/cutscene; tela cheia).
### Fase 2 — Agente C "integração" (depois de A e B)
Arquivos: `clipper/app/face.py` (novo: backends YuNet/MediaPipe/OpenSeeFace atrás de uma interface, download
lazy com sha256), e **ganchos pequenos** em `db.py`, `worker.py`, `intel.py`, `scoring.py`, `judge.py`,
`main.py`, `config.py`; painel só `panel/src/lib/clipper.ts` (`ALLOWED`) + um interruptor nas opções do juiz +
reação no cartão do corte. **Reler cada arquivo logo antes de editar** (o agente do editor mexe neles).
1. **Banco:** próxima migração (ler `user_version` atual; hoje 3) — tabela `face_track(session_id, idx, status,
data_json, error, PRIMARY KEY(session_id, idx))`. `cam_json` ganha `source` (`yunet`|`ai`|`manual`).
2. **Câmera:** `Intel.detect_cam` tenta primeiro o local (YuNet + `reaction.locate_cam` em 8–12 quadros); a IA
só entra se o local não achar rosto ou o usuário pedir. Opção `camDetect` continua valendo; detecção local não
exige `vision`/juiz ligados.
3. **Laço `_face_loop`** (thread própria, não atrasa a transcrição): blocos com câmera conhecida e sem
`face_track` → FFmpeg recorta a câmera (+10 % de margem), escala para ~384 px, 6 qps, `rawvideo rgb24` por
pipe → MediaPipe em modo VIDEO (timestamps crescentes) → `reaction.per_second` → grava. Sem câmera →
`status='no_cam'`. Câmera alterada (detect/PUT de layout) → apaga o `face_track` da sessão e refaz.
Opção nova `faceTrack` (padrão `true`) em `OPTION_DEFAULTS` e no `PUT /v1/judge`.
4. **Pontuação:** `find_moments` recebe `face` opcional:
- momentos de chat/áudio ganham `reasons.face` (pico, rótulo, onset) e bônus limitado na nota;
- fonte nova `face` só com **apoio** (áudio z ≥ 1 ou chat acima do normal no mesmo trecho) e z ≥
`face_threshold` (padrão 3,0) — rosto sozinho não vira corte;
- `find_new_clips` espera o rosto do trecho quando há câmera e `faceTrack` ligado (no máximo 2 blocos de atraso).
- Testes de regressão em `test_scoring.py` (sem rosto = comportamento atual idêntico).
5. **Juiz:** o prompt do analista ganha a linha "Rosto do streamer: …" de `reaction.summarize` na janela do corte.
6. **API:** `GET /v1/sessions/{id}/face?from=&to=` (série por segundo; o editor usa `cx/cy/size` para
reenquadrar) e `POST /v1/sessions/{id}/face/reset`. Atualizar `ALLOWED` e timeout no `panel/src/lib/clipper.ts`.
7. **README do Clipador** (seção nova "Rastreio de reação") e `.env.example` se houver variável nova.
8. **Validação na sessão 3** (cópia do banco em `output/face-bench/`, nunca o banco vivo enquanto o serviço do
usuário roda): câmera local × IA, % de rosto, tempo por bloco (meta ≤ 5 s CPU por bloco de 30 s), 10 maiores
reações com rótulo e tempo, e quais coincidem com cortes existentes. `pnpm test:clipper` e
`npx tsc --noEmit -p panel` verdes.
### Fase 3 — revisão e manutenção
- D: `ecc:python-reviewer` nos arquivos novos/alterados do Clipador; corrigir CRÍTICO/ALTO.
- E: `cenaforge-skill-updater` com o que mudou, arquivos e evidência.
- O serviço do usuário só pega o código novo após reiniciar o `start.bat` — **pedir ao usuário**, não reiniciar.
## Regras para todos os agentes
- Identificadores em inglês; comentários, mensagens e docs em português.
- Portas só na faixa 4500–4599. Não iniciar/encerrar o painel nem o serviço do Clipador do usuário.
- Subprocesso sem shell, argumentos em lista. Nada de rede na thread do chat.
- Nada de peso com licença não comercial/GPL. Modelos com URL imutável + sha256.
- Não publicar nada em rede social.
## Riscos
- OpenCV 5 × modelo YuNet antigo (fixo) → usar a variante dinâmica; a bancada confirma.
- Webcam muito pequena (rosto < 40 px no recorte) → MediaPipe perde; plano B OpenSeeFace ou ampliar o recorte.
- Rosto no jogo (cutscene, outro jogador com câmera) → `locate_cam` exige posição estável em ≥ 50 % dos quadros.
- Streamer sai da câmera → `present` 0, sinal `None`, nunca vira pico.
- Conflito com o agente do editor nos mesmos arquivos → ganchos mínimos, reler antes de editar, migração com o
próximo número livre na hora da edição.