Files
CenaForge/doc/clipador/EXPRESSOES.md
T
MateuusandClaude Opus 5.5 44f78bd483 Clipador: mapa de expressões do streamer (expressões novas, pose e corpo)
- Expressões novas dos blendshapes que já vinham do MediaPipe: gargalhada, alegria
  (no mapa), medo, espanto, nojo, tristeza, tensão e bocejo (que deixou de contar
  como grito); raiva também por olhos semicerrados + lábios apertados. Canais novos
  opcionais na série (brow_inner, mouth_frown, squint, press, stretch, upper_lip,
  pucker), z relativo ao neutro do próprio streamer só com os segundos que têm o campo.
- Pose da cabeça pela matriz de transformação facial (yaw/pitch/roll) e balanço/aceno
  por zigue-zague; YuNet nos quadros sem rosto dá a caixa da cabeça (streamer de perfil).
- Corpo mesmo sem expressão: balançando, acenando, agitado, chegou perto e saiu do
  quadro, sem contar rastreio perdido como movimento.
- API /face com expr/body por segundo e lista do corpo; linha do juiz com o corpo;
  painel com os rótulos novos e o "Mapa de expressões" no modal do corte.
- Calibrado nas sessões 7, 8, 11 e 15 (doc/clipador/EXPRESSOES.md); intensidade dos
  picos inalterada (canais novos só rotulam). Testes em tests/test_expressions.py.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-18 04:16:25 -03:00

211 lines
16 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.
# Mapa de expressões do streamer (Clipador)
Data: 18/11/2026. Código: `clipper/app/reaction.py` (lógica pura) e `clipper/app/face.py` (MediaPipe/YuNet, API);
painel: `panel/src/components/clipper-face-map.tsx`. Testes: `clipper/tests/test_expressions.py`. Base anterior:
[`doc/FACE_BAKEOFF.md`](../FACE_BAKEOFF.md) e a seção "Rastreio de reação" do `clipper/README.md`.
Pedido do dono: "Está muito pouco, tem que colocar mais expressões. Às vezes ele não tem expressão facial, mas a
gente pega ele balançando… raiva, medo, alegria — está faltando para deixar mais completo o mapa de expressões."
Antes: 8 dos 52 blendshapes do MediaPipe viravam 5 canais (`smile`, `jaw`, `surprise`, `frown`, `brow`) + `motion`,
e 6 rótulos (risada, grito, susto, choque, confuso, raiva). Sem pose da cabeça e sem nada quando o rosto some.
## O que mudou
1. **Expressões novas** a partir dos blendshapes que já vinham (custo zero).
2. **Pose da cabeça**: o Face Landmarker agora devolve a matriz de transformação facial
(`output_facial_transformation_matrixes=True`) → yaw/pitch/roll por quadro (`face.pose_from_matrix`).
3. **Cabeça sem rosto**: quando o MediaPipe não acha o rosto (streamer de perfil), o YuNet (já usado para achar a
câmera; mesma licença MIT) roda **só nesse quadro** e dá a caixa da cabeça → posição/tamanho para o corpo.
4. **Corpo**: balançando, acenando, agitado, chegou perto, saiu do quadro (`reaction.body_moments`).
5. **Mapa**: expressão dominante + corpo por segundo (`reaction.expression_map`), na API e no modal do corte.
Nada disso mexe na **intensidade** do rosto (o sinal que vira pico, bônus na nota e corte de fonte `face`): os
canais novos só **rotulam** (pesos `extra_weights` = 0; ver "Por que os canais novos não viram pico"). A única
mudança nos picos é o **bocejo**, que deixou de contar como grito.
## Canais por segundo (campos novos da série, todos opcionais)
Série antiga (gravada antes) não tem estes campos: tudo continua funcionando (canal ausente = parado). Sem
migração de banco — os campos vão no `data_json` de `face_track` que já existia.
| Campo | De onde vem | Agregação no segundo |
|---|---|---|
| `brow_inner` | `browInnerUp` | máximo |
| `mouth_frown` | média `mouthFrownLeft/Right` (cantos da boca para baixo) | máximo |
| `squint` | média `eyeSquintLeft/Right` (olhos semicerrados) | máximo |
| `press` | média `mouthPressLeft/Right` (lábios apertados) | máximo |
| `stretch` | média `mouthStretchLeft/Right` (boca esticada para os lados) | máximo |
| `upper_lip` | média `mouthUpperUpLeft/Right` (lábio de cima levantado) | máximo |
| `pucker` | maior entre `mouthPucker` e `mouthFunnel` (boca em "O") | máximo |
| `yaw`, `pitch`, `roll` | matriz de transformação facial, graus (1 casa) | média |
| `shake`, `nod` | pernas de zigue-zague do yaw/pitch (histerese 8°/6°) na janela [t−0,5; t+1,5) s | contagem |
| `head` | fração dos quadros com a cabeça visível (rosto com pontos **ou** caixa do YuNet) | fração |
| `head_motion` | caminho da cabeça em tamanhos de cabeça, só entre quadros vizinhos (≤ 0,4 s) da mesma fonte, passo limitado a 1 | soma |
| `hsize` | altura da caixa do YuNet nos quadros sem pontos (fração do quadro inteiro) | média |
Blendshapes **mortos** no modelo do MediaPipe (medido: máximo ≤ 0,001 em 4 sessões, ~45 mil segundos):
`noseSneerLeft/Right`, `cheekSquintLeft/Right`, `cheekPuff`. Por isso nojo e raiva **não** usam o nariz: o lábio de
cima (`upper_lip`) faz o papel.
O z de cada canal novo é o mesmo esquema do `channel_z` (mediana + 1,4826 × MAD dos últimos 180 s do próprio
streamer, sem os últimos 10 s), mas o neutro usa **só os segundos que têm o campo**: numa sessão em que o serviço
foi atualizado no meio, os segundos antigos não viram um "neutro de zeros" (teste
`test_service_updated_mid_session_does_not_fake_new_expressions`). Menos de 30 segundos com o campo → z 0. Pisos
do desvio (`extra_floors`): `brow_inner` 0,10, `mouth_frown` 0,05, `squint` 0,06, `press` 0,08, `stretch` 0,06,
`upper_lip` 0,10, `pucker` 0,12, `head_motion` 0,15.
## Rótulos de expressão (`label`, `yawn_seconds`, `expression_map`)
"Ligado" = z ≥ 2 (`label_z`); "meio" = z ≥ 1. Ordem de decisão:
| Rótulo | Regra | Observação |
|---|---|---|
| **bocejo** | jawOpen ≥ 0,5 por ≥ 2 s seguidos e `squint` z ≥ 1 em algum deles | contexto (`yawn_seconds`); **não é reação**: o pico sai |
| **risada** | sorriso ligado; ou sorriso ≥ 0,5 com boca, franzido, sobrancelha **ou lábio de cima** ligado | lábio de cima: novo |
| **gargalhada** | risada com a cabeça ≥ 20° para trás do neutro dele (`head_back_deg`) | novo |
| **alegria** | (só no mapa) risada sem pico (sinal < 3), sem boca abrindo e sem dentes à mostra | novo |
| **susto** | sobrancelha ou olho arregalado + movimento | igual |
| **medo** | `brow_inner` ligado + `stretch` ligado (ou olho arregalado com a sobrancelha descendo) | novo; FACS AU1+AU20 |
| **grito** | boca ligada; ou franzido com a boca ≥ 0,2 | igual |
| **raiva** | franzido de boca fechada; **ou** `squint` + `press` ligados com o franzido "meio" | 2ª forma: nova |
| **nojo** | `upper_lip` ligado, boca abaixo de "meio" e sorriso < 0,3 | novo |
| **tristeza** | `mouth_frown` ligado + `brow_inner` "meio", sem `pucker` nem `stretch` ligados | novo |
| **espanto** | `pucker` ligado + sobrancelha ligada ou boca "meio" | novo |
| **choque** | olho arregalado parado | igual |
| **confuso** | sobrancelha levantada parada | igual |
| **tenso** | `press` + `squint` ligados (sem franzido) | novo (painel: "tensão") |
## Corpo/cabeça (`body_moments`)
Só contam segundos com a cabeça em ≥ 80 % dos quadros (`head_min`; série antiga: o rosto). Rastreio perdido
nunca vira movimento (achado do FACE_BAKEOFF: os maiores "picos" de movimento eram o rosto sumindo e voltando): o
passo entre quadros é limitado, quadros com buraco > 0,4 s entre eles não somam, pontos e caixa do YuNet não se
misturam, e a agitação exige a janela inteira com a cabeça visível (teste `test_lost_face_is_not_agitation…`).
| Rótulo | Regra |
|---|---|
| **balançando** | `shake` ≥ 3 pernas (vai-volta-vai de ≥ 8° no yaw em 2 s). Olhar para o lado e voltar = 2: não conta |
| **acenando** | `nod` ≥ 3 pernas (≥ 6° no pitch) sem balanço lateral |
| **agitado** | `head_motion` com z ≥ 2,5 em ≥ 3 de 5 s seguidos, todos com a cabeça visível |
| **chegou perto** | cabeça ≥ 18 % maior que o tamanho normal dele (rosto e caixa do YuNet, cada um contra o próprio neutro) |
| **saiu do quadro** | cabeça visível ≥ 3 s, até 2 s de transição parcial, depois ≤ 10 % por ≥ 3 s. **Só com o campo `head`** (série antiga não diz "saiu": lá o MediaPipe perdendo o rosto pareceria saída) |
## Onde aparece
- **API** `GET /v1/sessions/{id}/face`: cada segundo ganha `expr` (expressão do mapa) e `body` (movimento), além
dos campos novos; a resposta ganha `body: [{startS, endS, peakS, label, value}]`. Os picos (`moments`) podem vir
com os rótulos novos.
- **Juiz (analista)**: a linha "Rosto do streamer" traz até 2 movimentos do corpo no fim ("…; balançando a cabeça
em 1628s"). Com o rosto de perfil o tempo todo, antes não ia linha nenhuma; agora vai "rosto sem expressão legível
(de perfil ou longe; cabeça visível em 95% do trecho); saiu do quadro em 187s".
- **Painel**: `FaceSignal` (chip do corte) mostra os rótulos novos em português; o modal do corte ganhou o **Mapa de
expressões** (`clipper-face-map.tsx`): faixa com uma célula por segundo, cor por família (verde alegria/risada,
amarelo susto/espanto/medo, vermelho raiva/grito/nojo, azul tristeza/tensão, violeta confuso), faixa laranja do
corpo embaixo, legenda com segundos por expressão e os movimentos. Busca o trecho do corte; sem câmera ou serviço
antigo, não aparece.
## Calibração (dados reais, só leitura)
Banco copiado por `sqlite3.backup` (`mode=ro`); blocos `.ts` só lidos; MediaPipe rodado num script à parte com as
classes do `face.py` (matriz de pose ligada), quadros salvos fora do repositório. Cada regra foi conferida **olhando
os quadros** (folhas de contato de 8 quadros em volta de cada caso).
| Sessão | Canal | O que tem | Segundos com rosto (MediaPipe) |
|---|---|---|---|
| 8 | skipnho (PT), 1,7 h | 206 blocos, 14 cortes | 6009 de 6162 |
| 11 | skipnho (PT), 30 min | 59 blocos, 3 cortes | 1763 de 1770 |
| 7 | skipnho (PT), fim da live | 79 blocos ainda no disco (2217 s), 6 cortes | — |
| 15 | tfue (EN), gravando | 125 blocos, 27 cortes (13 descartados pela IA) | **486 de 3750** |
Achados que mudaram as regras:
- **Bocejo era o maior "grito"**: na sessão 8 os 5 trechos com jawOpen ≥ 0,6 por 3 s (1420, 3335, 3437, 3483 e
3659 s) eram todos bocejos (olhos fechados, braços esticando), com z 12–16. Gritos e exclamações abriram a boca
assim por 1 s (908, 2331 s). O bocejo ainda levanta o "sorriso" (cantos esticados): z 4–8. Regra de contexto
(≥ 2 s + olhos apertando) pegou os 5 (+1 em 5662 s) e nenhum grito de 1 s; o piscar não serve (o normal deste
streamer já é 0,5).
- **Nojo × risada**: a 1ª regra (lábio de cima sem boca aberta) deu 82 trechos na sessão 8; todos eram risada de
dentes à mostra (sorriso 0,91–0,97, que para ele já é quase o normal: z ~1). Com o sorriso < 0,3 exigido e o lábio
de cima contando para a risada: 5 trechos.
- **Mão no rosto engana a boca**: queixo apoiado, mão na boca e coçar o nariz (tique frequente do skipnho) fazem
`mouth_frown`, `stretch` e `pucker` subirem (911, 3984–3987, 4060, 5077, 5222 s). Não há sinal de oclusão no
MediaPipe (comparei os 52 blendshapes nesses segundos com o resto: nenhum separa). Tristeza passou a excluir bico
e boca esticada; o resto fica como limitação documentada (ver "Por que os canais novos não viram pico").
- **Cabeça para trás**: a 12° deu 16 "gargalhadas" na sessão 8, quase todas falsas (pose errada com a mão no rosto,
falando). A 20° fica a gargalhada real de 1566 s (24°, cabeça para trás com as mãos no rosto) e cai o resto, menos
uma: em 2572 s a cadeira estava **vazia** e o MediaPipe inventou um rosto no encosto (28°). Bebendo de lata também
vai a −25° (pitch), por isso "cabeça para trás" sozinha não vira rótulo — só com risada.
- **Balanço a 6 qps**: 28 eventos (δ 8°, ≥ 3 pernas) na sessão 8; nos quadros, eram cabeça indo e voltando
rindo, falando ou gesticulando — não dá para afirmar "não" literal a 6 qps (uma perna dura 1–2 quadros). Por isso o
rótulo é "balançando a cabeça", não "disse não". Olhar para o lado e voltar (1225, 2832 s) dá 2 pernas e fica fora.
- **Agitado**: 64 trechos na sessão 8; conferidos 6 — todos movimento de verdade (se inclinando para fora e
voltando, gesticulando, se espreguiçando).
- **Chegou perto**: razão tamanho/normal p99 1,15 e p99,9 1,21 (sessão 8); o 1,25 inicial não pegava nada. Com 1,18:
13 trechos na 8 (ex.: 2066 s, rosto colado na câmera), 1 na 15.
- **tfue de perfil (sessão 15)**: o MediaPipe acha rosto em **10 %** dos quadros (yaw mediano −44°: olha o monitor
ao lado da webcam); o YuNet acha a cabeça em **100 %** (180/180 em 4 blocos, score 0,89). Com a caixa do YuNet:
cabeça visível em 85 % dos segundos e **4 saídas do quadro**, que batem com os cortes: 187 s (corte 261 "Tfue Takes
a Bathroom Break Mid-Stream", 175–244), 577 s (corte 268 "…Waiting on a Bathroom Break", 518–581; tirou o fone e
levantou), 1236–1333 s (tela de "volto já" cobrindo a câmera) e 3572 s (corte 285). Sem a tolerância de 2 s de
transição (ele levanta em 1–2 s) só a 3ª aparecia. Raiva forte em 977/1011 s cai nos cortes 265/272 ("Base Is
Under Attack by Suspected Stream Snipers").
Resultado final (picos = `reaction_moments`; mapa = % dos segundos com rosto):
| Sessão | Picos antes → depois | Trocas de rótulo nos picos | Mapa (fora o neutro) | Corpo (eventos) |
|---|---|---|---|---|
| 8 | 251 → 254 (8 bocejos saíram, a seleção gulosa reescolheu vizinhos) | confuso→espanto 3, confuso→tristeza 1, risada→gargalhada 1 | risada 14,8 %, confuso 6,5, alegria 5,1, grito 1,5, susto 1,1, espanto 0,9, raiva 0,7, tristeza 0,3, bocejo 0,3, medo 0,2, nojo 0,1, tenso 0,1 | agitado 64, balançando 42, acenando 36, chegou perto 13 |
| 11 | 107 → 107 | confuso→tristeza 1, confuso→espanto 1, risada→gargalhada 1 | risada 19,0 %, confuso 6,0, alegria 5,3, susto 1,9, grito 0,9, espanto 0,7 | agitado 18, acenando 10, balançando 5 |
| 7 | 144 → 144 | confuso→espanto 3, grito→medo 1 | risada 12,9 %, alegria 8,3, confuso 6,9, grito 3,5, raiva 2,1, espanto 2,1 | acenando 10, balançando 7, agitado 4 |
| 15 | 22 → 22 | risada→gargalhada 1 | raiva 10,5 %, risada 4,7, confuso 2,9, grito 2,3 | agitado 9, saiu do quadro 4, balançando 3, acenando 3 |
(Sessões 7, 8 e 11 sem a caixa do YuNet na calibração — lá o rosto aparece em 97–99 % dos segundos; o "saiu do
quadro" delas vem do rosto sumindo e não entra na tabela.)
## Por que os canais novos não viram pico
Com peso na intensidade, cada canal novo criaria picos sozinho — e os falsos mais comuns (mão no rosto) caem
justamente nos canais da boca. A intensidade alimenta a nota dos cortes e a fonte `face`; mexer nela sem um conjunto
aprovado/rejeitado maior seria chute (nas sessões 7, 8 e 11 quase todos os cortes estão "ready", sem decisão do
dono). Então: `extra_weights` = 0 e os canais novos só **rotulam** o pico que as expressões antigas já acharam, e
pintam o mapa. Para ligar um canal na intensidade, é só dar peso em `ReactionParams.extra_weights` (testado no
código: `_signal_from_z`), depois de medir de novo.
## Custo (medido, mesma máquina: 32 threads, CPU; 6 blocos de 30 s por caso, rodados em sequência)
| Caso | Bloco antes | Bloco depois | `per_second` | JSON da série |
|---|---|---|---|---|
| skipnho (rosto em 100 % dos quadros) | 1775 ms (máx 2124) | 1773 ms (máx 2047) | 0,7 → 1,5 ms | 177 → 400 B/s |
| tfue de perfil (rosto em 1 %, só cabeça em 73 %) | 1238 ms (máx 1573) | 1721 ms (máx 2236) | 0,2 → 0,3 ms | 36 → 85 B/s |
- A matriz de pose não custa nada mensurável. O YuNet custa **5,3 ms por quadro sem rosto** (média de 20 255 quadros
da sessão 15) e só roda nesses quadros: streamer de frente não paga nada; de perfil, +0,5 s por bloco de 30 s
(ainda ~17× mais rápido que o tempo real).
- Banco: ~1,4 MB por hora de live em `face_track` (antes ~0,6 MB).
- Análise (`reaction_moments` + `body_moments` + `expression_map`) numa série de 1,7 h: ~1 s.
## Limitações conhecidas (não verificadas ou fora do alcance)
- **Mão no rosto** ainda pode virar tristeza/espanto/medo/raiva no mapa (ver calibração).
- **Rosto fantasma**: com a cadeira vazia o MediaPipe às vezes acha um rosto no encosto (sessão 8, 2567–2575 s,
presença 0,3–1,0 em segundos soltos); aparece no mapa como expressão. O "saiu do quadro" ainda pega a saída quando
há ≥ 3 s seguidos sem rosto.
- **Sim/não literal** não é medido (6 qps); "balançando/acenando" é o movimento, não a intenção.
- Serviço real rodando o código novo **não** foi testado (o serviço é do dono; só scripts com as classes e a suíte).
A caixa do YuNet dentro do `FaceService` foi coberta por teste com detector falso e medida por script com o real.
- Painel: só `tsc`; não abri no navegador.
- Nenhuma sessão com câmera escura/minúscula além da do tfue (rosto ~66 px de altura na fonte 1080p).
## Integração com o agente de Falantes (atividade da boca)
- Nada foi renomeado nem removido: `SECOND_FIELDS`, `FaceSample.blend`, `per_second`, `FaceSecond`,
`seconds_to_json/from_json` continuam iguais para quem já usa. Os campos novos estão em `EXTRA_SECOND_FIELDS`
(`to_json`/`from_json` percorrem `SECOND_FIELDS + EXTRA_SECOND_FIELDS`).
- `FaceSample` ganhou `pose` e `head` com padrão (`None`/`False`); quadro com `head=True` tem `present=False` e
**não tem blendshapes** — quem medir a boca deve continuar filtrando por `present`.
- `per_second` ganhou o parâmetro opcional `params` (só para os limiares do balanço). A atividade da boca para fala
pode usar `jaw`, `pucker` (bico/funil), `press`, `stretch`, `upper_lip` por segundo, que agora vêm na série.
- Ponto provável de conflito de merge: os dois agentes acrescentam campos ao fim de `FaceSecond` e uma tupla de
campos opcionais; manter as duas listas.