Files
CenaForge/doc/clipador/FALANTES.md
T

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.
# Clipador — quem fala cada palavra (streamer × outra pessoa)
Pedido do dono (18/11/2026):
> Está atribuindo ao streamer a fala de outro jogador. A gente vai separar: a legenda do streamer em cima e a de
> outra pessoa abaixo, com outra cor, como se fossem duas pessoas conversando.
O áudio da live é um canal só: microfone do streamer, colegas no Discord e outros jogadores no chat de voz do jogo
saem misturados, e o Whisper devolve as palavras sem dizer de quem são. Na câmera só aparece o streamer: as outras
vozes **não estão no vídeo**.
## Como funciona
| Etapa | Onde | Quando | Custo medido |
| --- | --- | --- | --- |
| Trechos de fala → impressão de voz (256 números) + volume (dBFS) | `speakers.index_block` + `voiceprint.py` | análise de cada bloco, logo depois do Whisper (thread da análise) | **0,19 s de CPU por bloco de 30 s** (máx. 0,67 s) |
| Movimento da boca do streamer, quadro a quadro | `face.MouthMeter` (YuNet) | rastreio do rosto de cada bloco (thread `face`), nos mesmos quadros já decodificados | **+0,5 s de CPU por bloco** |
| Vozes da sessão, qual é o streamer, rótulo de cada trecho | `speakers.build_model` | sob demanda (`load_timeline`, editor), em cache até chegar bloco novo | **0,05 s** (1 061 trechos, 72 min); 0,07 s com 6 400 trechos (~7 h) |
Por que assim: a parte cara (rede de voz) roda uma vez por bloco, em segundo plano, junto com o áudio que a análise já
decodificou; o agrupamento precisa da sessão inteira (as vozes só se separam com muitos trechos) e custa centésimos,
então é refeito na leitura — e o rótulo melhora sozinho conforme a live avança, sem reescrever nada no banco.
1. **Trechos**: palavras seguidas (vão ≤ 0,25 s), até 3 s, e fecha no fim de frase (`. ? !`) — numa conversa a vez
troca quase sempre ali, mesmo sem pausa. Trecho ≥ 0,5 s vira impressão de voz (com 0,1 s de folga de áudio).
2. **Vozes**: os trechos ≥ 1 s são agrupados pela voz (aglomerativo, cosseno ≥ 0,5 entre os centros; até 600
trechos espalhados na sessão). Grupo com ≥ 15 s de fala é uma voz. Funciona com qualquer número de colegas.
3. **Qual voz é o streamer** — duas provas:
- **boca**: a voz cujos trechos coincidem com mais movimento da boca dele na webcam (média de muitos trechos;
t de Welch ≥ 3 contra a segunda voz);
- **volume**: o microfone dele vem mais forte que o Discord/jogo (mediana ≥ 3 dB acima da segunda voz).
Concordam ou só uma decide → ela. **Discordam ou nenhuma decide → ninguém vira "outro"** (tudo como do
streamer, o comportamento de antes). Uma voz só (streamer sozinho) → nada muda.
4. **Cada trecho** vai para a voz mais parecida. Só vira `otherN` com folga: cosseno com a outra voz ≥ 0,30 e ≥ 0,10
acima do cosseno com o streamer (+0,05 nos dois para trecho < 1 s). Senão, streamer. Trecho curto sem impressão
herda o rótulo do trecho vizinho (até 1 s); longe de tudo, streamer.
`GET /v1/sessions/{id}/speakers` mostra as vozes, qual é o streamer e por quê. Opção `speakers` (`intel.opts`,
padrão ligada) desliga tudo.
## Dados
- `scoring.Word` ganhou `speaker: str = ""` (no fim, opcional): `""`/`"streamer"` = streamer; `"other1"`,
`"other2"`… = outra pessoa (numeradas pela quantidade de fala na sessão; a numeração pode mudar com a live).
- `segments.words_json` aceita o 4º elemento `[início, fim, texto, falante]`; o formato antigo (3) continua valendo e é
o que se grava hoje (`speakers.dump_words`). Falante gravado no 4º elemento tem prioridade sobre a atribuição.
- Tabela `voice_chunks (session_id, idx, data_json, updated_at)` — `{model, chunks: [{s, e, db, v}]}`, `v` = vetor em
float16/base64 (~5 KB por bloco, ~0,6 MB por hora). Criada pela migração **v15** (`db.py`).
- `face_track.data_json.mouth`: série por quadro (6 qps) do movimento da boca; blocos antigos não têm (a prova da boca
só vale para blocos rastreados depois desta versão).
- Projeto do editor: cada palavra ganha `sp` (só quando atribuída). Projetos antigos, sem `sp`, saem iguais.
- Tradução (`clips.translation_json`): cada linha tem `speaker`; as frases nunca misturam falantes. Tradução antiga,
sem `speaker`, é refeita na próxima chamada.
## Legenda
- Duas faixas: a do streamer na posição normal; a de outra pessoa **logo abaixo** (`caption.otherColor`, padrão
`#5CE1FF`; `caption.otherSize`, padrão vazio = 85 % de `size`). A palavra falada continua com `highlight`.
- Um bloco nunca mistura falantes; "nunca dois blocos ao mesmo tempo" vale dentro de cada faixa. Os dois falando
juntos = as duas linhas na tela, cada uma com `\pos` próprio (o libass não empilha).
- Sem espaço embaixo (horizontal, legenda a 85 % da altura), a linha do streamer **sobe** o necessário: a ordem nunca
inverte. O gancho (`hook_dodges`) desvia as duas linhas juntas.
- Tradução de desenvolvimento (`dev.translation`): o português de cada um fica embaixo da linha de quem fala (a do
streamer entre as duas linhas).
- Estilos `CaptionOther`/`KaraokeOther` só entram no ASS quando o corte tem outra pessoa: corte só com o streamer sai
byte a byte igual (conferido pelo teste dourado do vertical).
- Painel: a configuração do corte tem "Fala de outra pessoa" (cor e tamanho); o editor marca o falante de cada
parágrafo da transcrição e o botão **Outra pessoa / É o streamer** corrige as palavras selecionadas; a prévia
(canvas) desenha as duas linhas; o modal mostra quem fala em "O que falam".
## Juízes
`judge._transcript`: com outra pessoa no trecho, cada linha diz quem fala (`[Tfue] …` / `[other1] …`) e vem a nota
"Never attribute to Tfue what someone else said" (em português nos prompts em português). Sem outra pessoa, a
transcrição sai igual à de antes.
## Licenças (conferidas em 18/11/2026)
| Peça | Licença | Onde conferi |
| --- | --- | --- |
| **WeSpeaker ResNet34-LM** (`voxceleb_resnet34_LM.onnx`, commit `f0c48c2…` do Hugging Face) — os PESOS | **CC-BY-4.0** (uso comercial permitido, pede atribuição: "WeSpeaker, wenet-e2e") | cartão do modelo `Wespeaker/wespeaker-voxceleb-resnet34-LM` (`license: cc-by-4.0`) e `docs/pretrained.md` do WeSpeaker ("o modelo segue a licença do conjunto de treino"; VoxCeleb = CC BY 4.0) |
| Código de fbank | nosso (reimplementação em numpy; conferida contra o `torchaudio.compliance.kaldi.fbank`: diferença máx. 0,00016) | — |
| YuNet (boca) | MIT (já no projeto) | `models.lock.json` |
Não usados: **pyannote**, **SpeechBrain ECAPA**, **NeMo TitaNet**, **Resemblyzer** — todos pedem PyTorch, que não está
no venv do Clipador (o modelo escolhido roda no `onnxruntime` que já existe). **3D-Speaker CAM++** (código
Apache-2.0): a página do modelo no ModelScope não abriu para conferir a licença dos pesos, então ficou de fora.
Nenhum pacote novo foi instalado; o modelo (26,5 MB) entra no `models.lock.json` com sha256 e é baixado pelo
`setup.ps1` ou sob demanda (`ModelStore`).
## Qualidade medida — sessão 15 (twitch.tv/tfue, inglês, dois colegas no Discord)
Medido só lendo o banco e os blocos da pasta principal (cópia em memória), 144 blocos (~72 min), com o código desta
versão.
**A boca sozinha não resolve nesta live.** Webcam pequena (rosto ~45×66 px no 1080p) e streamer de PERFIL olhando o
monitor:
- MediaPipe Face Landmarker (o rastreio atual): rosto em ~4 % dos quadros na maioria dos blocos (0 a 58 %), e
`jawOpen` = 0,00 mesmo nos quadros com rosto e falando. Recorte justo no rosto: 26–69 % de presença, `jawOpen`
ainda ~0,01. Inútil para falante.
- YuNet + recorte da boca (`MouthMeter`): rosto em **99 %** dos quadros. Mas por trecho o sinal separa pouco: AUC
**0,55–0,64** (boca do streamer × boca nos trechos dos colegas). Somando muitos trechos aponta a voz certa
(média 0,188 × 0,167 × 0,159), com t = 2,3 contra a 2ª voz — abaixo do limiar 3: aqui quem decide é o volume.
Em câmera de frente e maior a boca deve pesar mais; não foi medido.
**A voz separa bem**:
- 3 vozes (358 s, 313 s e 244 s de fala em trechos ≥ 1 s); cosseno entre os centros 0,26–0,33 (vozes bem distintas).
- Volume: streamer −27,3 dBFS × −34,8 e −37,6 dBFS dos colegas → **+7,5 dB**; o streamer é achado pelo volume desde os
primeiros 5 minutos.
- 1 061 trechos: 916 com impressão; **514 viraram outra pessoa**, 73 ficaram como do streamer por dúvida (a voz mais
parecida era a de um colega, mas sem a folga exigida); 145 curtos herdam o vizinho.
- **Conferência visual às cegas** (30 trechos ≥ 1,2 s sorteados, 10 de cada voz, embaralhados; olhei 8 quadros da boca
de cada um sem saber a voz): 20 casos claros.
- boca parada o trecho todo (não é ele): **9 de 9** rotulados como outra pessoa;
- boca mexendo (seria ele): **7 de 11** rotulados streamer; os 4 restantes são todos da mesma voz de colega
(`other2`) e, revistos a 24 qps, mostram lábios entreabertos sem articular — duvidosos. Outros 2 trechos dessa
mesma voz mostram a boca dele fechada enquanto ela fala, e ela é 10 dB mais baixa que o microfone dele: tratei
como colega. Esta conferência é fraca (rosto de perfil, 45 px); não há gabarito de áudio.
- **Estabilidade** (streamer × outra pessoa, comparando com o modelo da sessão inteira): com 5 min de live, 52/62
trechos iguais (84 %); 10 min, 129/132 (98 %); 20 min, 287/292 (98 %); 40 min, 555/563 (99 %).
- Exemplo real (5:30–5:50): "How many drills is the gallery?" → streamer; "Gallery is three." → `other1`;
"I think we need five. I have three so I think you should bring two." → `other1`; "I got one code tablet
completed." → streamer (antes do corte por fim de frase, "I got one code" ia junto com o colega).
## Limites conhecidos
- Troca de falante no meio de um trecho sem pausa nem pontuação fica com um rótulo só.
- Nos primeiros minutos (menos de 15 s de fala por voz) não há atribuição: tudo como do streamer.
- Vozes do jogo (NPC, anúncio) também viram "outra pessoa" — o que é verdade (não é o streamer).
- Projeto do editor guarda o `sp` de quando foi criado; projeto antigo (sem `sp`) sai como antes. Nova avaliação dos
juízes refaz o projeto da IA já com falantes.
- A série da boca só existe em blocos rastreados por esta versão; a do volume vale para qualquer bloco com fala.
- Modelo de voz indisponível (sem rede no 1º uso, arquivo corrompido): os blocos analisados nesse tempo ficam sem
impressão de voz (não são refeitos depois) e o serviço tenta carregar de novo a cada 5 min.
- Tudo isso só vale depois de reiniciar o serviço (o código novo não roda no Clipador que está no ar).