LegendaLab
Legendas automáticas em português para pessoas surdas, que avisam onde a IA pode ter errado e apontam os trechos rápidos demais para ler.
Ver a demonstração: um vídeo de exemplo já legendado pelo projeto, com a lista de blocos e os destaques.
A pessoa e a voz do vídeo de exemplo são um avatar gerado por IA (Clipchamp).
O problema
Legenda automática erra, e quem ouve percebe na hora. A pessoa surda não tem como perceber, porque não confere a legenda pelo áudio. Além disso, uma transcrição literal pode passar da velocidade de leitura recomendada.
O que o LegendaLab faz
- Gera a legenda (WebVTT) de um vídeo curto, com um modelo Whisper rodando localmente, sem API paga.
- Marca os trechos duvidosos, em que o próprio modelo estava inseguro, com ⚠ e o motivo.
- Aponta os blocos difíceis de ler, pelos limites do Guia para Produções Audiovisuais Acessíveis (2016): até 2 linhas de 37 caracteres, até 18 caracteres por segundo e de 1 a 6 segundos na tela. Aponta, mas não reescreve o texto.
E mede tudo isso com números.
Resultados
Qual modelo usar?
Comparei dois tamanhos do Whisper nas 427 frases do conjunto de teste do Common Voice pt-BR (36 minutos de áudio), com 2 núcleos de CPU, imitando a máquina da demo.
| Modelo | Erro de palavra (WER) | Velocidade (RTF) |
|---|
| whisper-base | 38,6% | 0,32 |
| whisper-small | 22,9% | 0,86 |
- WER: palavras trocadas, faltando ou sobrando, divididas pelas palavras da frase correta, somando todas as frases.
- RTF: tempo de processamento ÷ duração do áudio. RTF 0,32 = 10 s de áudio transcritos em 3,2 s.
- Regra de escolha: o menor WER entre os modelos com RTF até 1,0, ou seja, mais rápidos que o tempo real. Modelo da demo: whisper-small.
Conclusão: a regra inicial pedia RTF até 0,5, um limite que eu defini antes de medir, e com ela a demo usaria o base. Quando vi os números, percebi que esse limite não tinha um motivo ligado a quem usa a legenda: para quem não ouve, acertar vale mais do que esperar alguns segundos a menos. Mudei a regra para "mais rápido que o tempo real" (RTF até 1,0), e a demo passou a usar o small, que erra 41% menos (22,9% contra 38,6%). Como a regra mudou depois de ver os números, os resultados dos dois modelos ficam aqui, lado a lado.
A marcação de "trecho duvidoso" funciona?
Apliquei às 427 frases a mesma regra que a demo usa para marcar dúvida, com os mesmos cortes nos dois modelos:
| whisper-small (demo) | whisper-base |
|---|
| Frases marcadas como duvidosas | 33% (141) | 60% (258) |
| WER nas marcadas × nas demais | 42,2% × 13,0% | 51,4% × 16,8% |
| Parte dos erros que cai em frases marcadas | 62% | 84% |
| Erros sem aviso | 8,6% (230 palavras) | 6,2% (165 palavras) |
- Erros sem aviso: palavras erradas em frases que não foram marcadas, divididas por todas as palavras. É o erro que a pessoa lê sem nenhum destaque, e por isso é o número que mais importa para quem não ouve.
- A troca: o small erra menos no total, mas marca menos frases, então deixa mais erros passarem sem aviso (8,6% das palavras, contra 6,2% no base). O base avisa mais, mas, com 60% das frases marcadas, o destaque perde o sentido.
- Os cortes foram definidos antes da medição (três deles são os padrões do próprio Whisper) e não foram ajustados olhando o conjunto de teste.
Onde o modelo erra
Nos dois modelos, as frases com mais erros são listas de termos técnicos e nomes próprios ("lotusscript, corelscript", "Gerdau, PagBrasil, Piccadilly"). No base, em duas frases o modelo entrou em repetição ("e o hábita e o hábita e o hábita"); as 10 piores do base estão em errors.md. No small, aparecem também números por extenso transcritos como algarismos ("um, dois, três…" virou "1, 2, 3…"), que a normalização atual conta como erro.
Medido em 24/10/2026 · seed 42 · normalização v1 · dados completos em results/2026-10-24_145853 (resumo, calibração).
Como funciona
flowchart LR
V[Vídeo enviado] --> M[Validação:<br>tamanho, tipo real,<br>duração, áudio]
M --> A[Áudio mono 16 kHz<br>ffmpeg]
A --> T[Transcrição<br>Whisper local]
T --> C[Blocos de legenda<br>limites do Guia]
C --> L[Legibilidade:<br>aponta blocos rápidos]
C --> D[Baixa confiança:<br>marca trechos duvidosos]
L --> R[WebVTT + relatório]
D --> R
R --> P[Página: player<br>e lista de blocos]
- A IA entra só na transcrição. Quebra em blocos, legibilidade, marcação de dúvida e VTT são código comum, coberto por testes com pytest. Os testes usam um transcritor falso, para testar o código sem depender da IA.
- O benchmark e a demo usam o mesmo núcleo (
core/), então o número da tabela descreve o que a demo faz.
- Privacidade: o vídeo é salvo com nome aleatório numa pasta temporária e apagado ao fim de cada pedido, inclusive quando dá erro. O log não guarda o texto transcrito nem o nome do arquivo.
Como rodar
Pré-requisitos: Python 3.12 e ffmpeg instalados.
git clone https://github.com/joaopeorossi/legendalab
cd legendalab
py -3.12 -m venv .venv
.venv\Scripts\python -m pip install -r requirements.txt
.venv\Scripts\python -m uvicorn api.main:app
Depois, abra http://127.0.0.1:8000 (a página) ou http://127.0.0.1:8000/docs (a documentação da API). Os testes rodam com .venv\Scripts\python -m pytest. No Linux ou no macOS, use python3.12 -m venv .venv e .venv/bin/python.
Para refazer o benchmark, baixe o Common Voice pt-BR na Mozilla Data Collective para data/pt-BR/ e rode:
.venv\Scripts\python -m bench.run_benchmark --models base small --n 427 --seed 42
.venv\Scripts\python -m bench.report results/<pasta-da-execução>
.venv\Scripts\python -m bench.calibrate results/<pasta-da-execução>
Limitações
- Fala lida em voz alta (Common Voice), diferente da fala espontânea de um vídeo comum.
- O Whisper pode ter ouvido esses áudios no treino, porque o Common Voice é público. Não há como garantir que não.
- 427 frases bastam para um projeto de estudo, mas são poucas para conclusões gerais. Muitas são listas de termos técnicos e nomes próprios, que puxam o erro para cima.
- O RTF foi medido no meu computador, com 2 núcleos, para imitar a máquina da demo. Na nuvem, o número pode ser outro.
- O WER não conta pontuação e não converte números ("3" e "três" contam como palavras diferentes).
- Erros sem aviso: com o small, 8,6% das palavras saem erradas sem nenhum destaque (no base, 6,2%), porque ele marca menos frases (33% contra 60%).
- Demora: com 2 núcleos, o small leva 0,86 s para cada segundo de áudio, então um vídeo de 60 s leva perto de 1 minuto para ficar pronto.
- A legenda não descreve sons (música, risos) nem identifica quem fala, como uma legenda completa para surdos faria.
- A demo aceita vídeos de até 60 s e 30 MB, só em português.
- A demonstração online usa um vídeo já processado no meu computador: o visitante não envia o próprio vídeo. Para isso, rode o projeto localmente. O vídeo de exemplo tem voz sintética, mais fácil de transcrever que a fala humana; os números do benchmark são de vozes humanas.
Fontes
- Limites de legibilidade: Guia para Produções Audiovisuais Acessíveis, Ministério da Cultura / Secretaria do Audiovisual (MinC/SAv), 2016.
- Dados: Common Voice pt-BR (Mozilla, via Mozilla Data Collective), licença CC0. Os áudios não estão neste repositório, porque os termos proíbem re-hospedar; aqui ficam só as frases e os resultados.
- Modelos: Whisper (OpenAI), via faster-whisper.
Como usei IA no desenvolvimento
Usei o Claude Code como copiloto para escrever o código. As decisões são minhas: para quem é o projeto, que métrica usar, de onde vêm os limites, a regra de escolha do modelo e o corte da marcação de dúvida. A validação dos resultados também é minha. Cada etapa terminou com testes automáticos e um registro do que aprendi no LEARNING_LOG.md.
No produto, a IA aparece só na transcrição. Nenhuma IA reescreve, resume ou "corrige" a legenda.
Licença
MIT.
