Files
CenaForge/doc/PLANO_RASTREIO_REACAO.md
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

10 KiB
Raw Permalink Blame History

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.