WhisperX: marcação temporal palavra por palavra e locuteurs

#O que Whisper sozinho não resolve

WhisperX é uma camada de software livre, sob licença BSD-2-Clause, que adiciona ao Whisper duas coisas que o modelo sozinho não oferece: marcações de tempo palavra por palavra obtidas por alinhamento forçado com um modelo wav2vec2 e uma identificação de quem fala produzida por um modelo pyannote. Você precisa do WhisperX se estiver criando legendas que precisam aparecer no momento certo ou um relatório de reunião que mostre quem falou. Se você só quer texto, o Whisper sozinho ou o faster-whisper basta. O custo envolve carregar três modelos em vez de um, precisar de um token de acesso do Hugging Face para a separação dos falantes e lidar com limitações documentadas: os números e valores monetários não são alinhados, a fala simultânea é mal processada e a separação dos falantes continua imperfeita. Tudo funciona localmente, seja em GPU, em processador ou em Mac.

Whisper gera um texto excelente. Suas limitações aparecem assim que se quer algo além de texto. De acordo com o repositório WhisperX, as marcações de tempo do Whisper são fornecidas por enunciado, e não por palavra, e podem apresentar desvios de vários segundos: isso passa despercebido em um documento, mas é inaceitável na legendagem, em que uma legenda que aparece um pouco atrasada é pior do que nenhuma legenda. E o Whisper não distingue quem está falando: duas horas de reunião são devolvidas como um monólogo indiferenciado.

O WhisperX atende às duas necessidades adicionando etapas em vez de substituir o modelo. É essa escolha de projeto que preserva a qualidade de transcrição que você conhece. O projeto, publicado sob a licença BSD-2-Clause, tem hoje mais de 24.000 estrelas no GitHub — um sinal de que a necessidade que ele atende, adicionar marcações de tempo à transcrição e atribuí-la aos falantes, vai muito além da legendagem.

#As três etapas

A detecção de voz tem um duplo papel: o repositório indica que ela reduz as alucinações e permite agrupar os segmentos sem piorar a taxa de erro por palavra. A etapa de alinhamento é a que costuma ser subestimada. É ela que torna confiáveis as marcações de tempo de cada palavra, usando um modelo wav2vec2 para alinhar cada palavra à sua posição real no sinal de áudio. Ela depende do idioma: o repositório especifica que é necessário um modelo wav2vec2 específico para o idioma e que existem modelos padrão para inglês, francês, alemão, espanhol e italiano, além de muitos outros idiomas via Hugging Face. Para um idioma ausente da lista, você precisa encontrar por conta própria um modelo fonético e testá-lo. A própria transcrição se beneficia da inferência em lote: o projeto anuncia até 70 vezes a velocidade em tempo real com o modelo large-v2, sem especificar o hardware no README. Considere esse número como um limite máximo a verificar na sua máquina.

#A separação dos falantes, sem ilusão

A identificação de falantes funciona agrupando as características vocais ao longo de toda a gravação, via pyannote-audio. O modelo padrão do WhisperX é hoje speaker-diarization-community-1, publicado sob a licença CC-BY-4.0, que recebe um sinal de áudio mono a 16 kHz (o estéreo é convertido para mono, e as demais frequências são reamostradas). A ficha do modelo afirma que ele tem um desempenho muito melhor que o antigo pipeline 3.1. O repositório do WhisperX é franco sobre as limitações: a sobreposição de falas é tratada de forma insatisfatória, e a separação continua « longe de ser perfeita ». As taxas de erro de diarização publicadas pelo pyannote mostram isso: 11,7 % no AISHELL-4, 17,0 % no AMI (microfones individuais), 19,9 % no AMI (microfone distante), 26,7 % no CALLHOME (parte 2) e 46,8 % no Ego4D, dependendo do corpus. São corpora acadêmicos, não as suas gravações, mas a ordem de grandeza indica que uma revisão continua sendo necessária. A situação piora justamente quando as reuniões ficam mais complicadas: pessoas que interrompem umas às outras, alguém longe do microfone, vozes semelhantes.

Duas observações práticas. É possível indicar um número mínimo e máximo de falantes (opções --min_speakers e --max_speakers), e o repositório recomenda fazer isso quando você conhece esse número: o modelo não precisa mais adivinhá-lo. E os rótulos são anônimos por definição: o sistema informa que havia três vozes e quais turnos de fala pertencem a cada uma, mas não quem são essas pessoas. Associar um rótulo a um nome é uma etapa manual — e é também nesse momento que a transcrição se torna um dado pessoal.

#Precisão real, não a do benchmark

A transcrição em si merece um número, porque o benchmark habitual dá uma imagem excessivamente positiva. De acordo com o VexaScribe, um serviço comercial de transcrição, o Whisper large-v3 atinge uma taxa de erro por palavra de cerca de 2,7% no LibriSpeech test-clean, um conjunto de áudios limpos com um único locutor. Em áudio real em inglês — reuniões, podcasts, chamadas —, o mesmo site situa essa taxa em torno de 8 a 12%. São ordens de grandeza publicadas por uma empresa do setor, válidas para o inglês: elas não dizem nada sobre suas gravações em francês. O WhisperX não melhora a transcrição em si, que continua sendo a do Whisper: o que ele acrescenta é a identificação exata de onde cada palavra se encontra e de quem a pronunciou, duas informações que essa taxa de erro não captura.

#O que isso exige

O tamanho do modelo Whisper determina tudo

Um modelo grande produz o melhor texto e exige mais memória; o repositório indica que um modelo maior melhora a precisão das marcações de tempo ao custo de mais memória da GPU, enquanto um modelo de alinhamento maior não ajuda muito.

São carregados três modelos, não um

A memória atinge o pico quando os modelos de transcrição, alinhamento e separação estão todos na memória. O exemplo Python do repositório libera cada modelo após sua etapa (coleta de memória seguida de torch.cuda.empty_cache()), solução comum em uma placa de vídeo com pouca memória.

Sem GPU, incluindo Mac

O repositório fornece o comando para o processador e para macOS: --compute_type int8 --device cpu. Ele não publica nenhum tempo de processamento no processador: meça em um trecho antes de planejar um lote. Com um GPU NVIDIA, ele exige o kit CUDA 12.8, e o projeto indica menos de 8 GB de memória para large-v2 com beam_size=5.

O processamento em lote ajuda

O processamento em lotes explica a velocidade anunciada: o valor padrão na linha de comando é --batch_size 8. Reduzi-lo (o repositório cita 4) libera memória da GPU.

#Instalar e iniciar a transcrição

A instalação é feita via pip; o pacote exige Python 3.10 a 3.13. A linha de comando grava por padrão todos os formatos disponíveis (srt, vtt, txt, tsv, json, aud), e a opção --highlight_words True sublinha cada palavra no momento em que ela é pronunciada nas legendas SRT e VTT. O JSON inclui os identificadores de locutor quando a separação está ativada.

1. 01
   Instalar o WhisperX

   pip install whisperx instala o pacote; com uma GPU NVIDIA, instale primeiro o kit CUDA 12.8, de acordo com o repositório. O repositório acrescenta que também pode ser necessário instalar o ffmpeg, remetendo às instruções de instalação do Whisper.
2. 02
   Transcrever e alinhar

   Iniciar uma primeira rodada com um modelo Whisper de tamanho médio (o padrão é small), especificando o idioma se ele for conhecido de antemão: sem essa informação, o idioma é detectado automaticamente, e o modelo de alinhamento depende desse idioma.
3. 03
   Ativar a separação, se necessário

   Adicionar --diarize e o token de acesso do Hugging Face obtido após aceitar as condições do modelo pyannote, e indicar o número de falantes se você souber.
4. 04
   Reler o arquivo de saída

   Abrir o arquivo SRT ou JSON gerado e verificar alguns trechos escolhidos ao acaso, especialmente os turnos de fala nos momentos em que várias pessoas falam quase ao mesmo tempo.

pip install whisperx

# Avec GPU : transcription, alignement et séparation des locuteurs
whisperx reunion.mp3 --model medium --language fr \
  --diarize --hf_token VOTRE_JETON --min_speakers 2 --max_speakers 5

# Sur processeur ou sur Mac
whisperx reunion.mp3 --model medium --language fr --compute_type int8 --device cpu

• Whisper local: transcrição básica
• Gerar um relatório de reunião localmente
• Assistente de voz local: a cadeia completa
• Transcrição de consultas com Whisper

#O que o alinhamento não conseguirá marcar com timestamps

O repositório lista limitações que é preciso conhecer antes de prometer legendas perfeitas. A primeira diz respeito aos números: palavras cujos caracteres não estão no dicionário do modelo de alinhamento, por exemplo «2014.» ou «£13.60», não podem ser alinhadas e, portanto, não recebem nenhuma marcação de tempo. Em uma reunião cheia de valores e datas, essas palavras aparecem no SRT sem marcação de tempo própria. A segunda é a fala simultânea, com a qual tanto Whisper quanto WhisperX lidam mal. A terceira é o idioma: é necessário um modelo wav2vec2 específico.

Duas diferenças em relação à versão original do Whisper também explicam diferenças no texto. Para processar cada lote em uma única passagem, a inferência é feita sem as marcações de tempo do Whisper, o que, conforme alerta o repositório, pode gerar divergências em relação à saída padrão. Além disso, a opção condition_on_prev_text está desativada por padrão para reduzir as alucinações. Desde 2026, a opção --interleaved_context restabelece um contexto contínuo entre os segmentos, útil para a pontuação e o vocabulário técnico segundo o projeto, mas ela é recente: teste-a em um trecho antes de adotá-la.

#Casos de uso concretos

Legendar vídeos de treinamento

A marcação de tempo palavra por palavra evita legendas que ficam uma frase inteira atrás da voz, um defeito imediatamente visível e incômodo em conteúdo pedagógico.

Relatório de reunião com vários interlocutores

A separação dos falantes permite reconstruir quem propôs o que, uma informação que um resumo sem atribuição não consegue reproduzir fielmente.

Podcasts e entrevistas longas

A inferência em lote é feita para gravações longas: é o que anuncia o título do artigo dos autores, « Time-Accurate Speech Transcription of Long-Form Audio ».

Arquivos de áudio para indexar

Um texto com marcações de tempo para cada palavra permite direcionar uma pesquisa diretamente para o instante exato da gravação, e não apenas para o documento inteiro.

Trechos para redes sociais

Identificar exatamente onde uma frase marcante é dita, palavra por palavra, facilita a extração de um trecho curto sem precisar ouvir todo o vídeo novamente.

Um ponto em comum nesses casos: nenhum exige transcrição em tempo real. Trata-se de um arquivo já gravado que é processado depois, o que dá tempo para a inferência em lote fazer seu trabalho sem restrições de latência. Quando a necessidade passa a ser legendagem ao vivo — uma conferência transmitida, uma ligação em andamento — o WhisperX deixa de ser a ferramenta adequada, independentemente da potência da máquina disponível.

#A transcrição é uma entrada, não um produto final

Em quase todos os casos reais, a transcrição não é o objetivo: ela alimenta um modelo local que, a partir dela, gera um relatório, um registro de decisões ou um resumo. Isso tem uma consequência para a qualidade esperada: um erro de transcrição em uma palavra rara importa menos do que a estrutura dos turnos de fala, porque é essa estrutura que permite ao modelo atribuir corretamente o que foi dito.

Na prática, um fluxo de produção razoável separa as duas funções: o WhisperX produz um texto com marcações de tempo e identificação dos falantes, depois um modelo de linguagem separado relê esse texto para extrair um resumo estruturado. Misturar as duas funções em uma única chamada — pedir a um modelo para resumir diretamente o áudio — priva o pipeline da precisão das marcações de tempo que o WhisperX tem justamente a função de fornecer e dificulta a verificação posterior de um trecho específico.

Outro benefício: a transcrição é feita apenas uma vez e depois é reutilizada para vários entregáveis — resumo curto, registro de decisões, legendas — sem precisar voltar ao áudio. O texto com marcações de tempo e rótulos torna-se a fonte de verdade.

• Fonte: repositório oficial WhisperX no GitHub
• Fonte: modelo de separação de falantes pyannote community-1
• Fonte: VexaScribe, taxa de erro por palavra do Whisper large-v3 (serviço comercial)
• Fonte: whisperx no PyPI

#FAQ