# 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.