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>
138 lines
10 KiB
Markdown
138 lines
10 KiB
Markdown
# 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.
|