Implementar Transcrição em Tempo Real em Python
Nesta página
Curso atualizado a 3 de novembro de 2026 para o Voxtral 3, com base no guia Migrate from Voxtral 2 da Mistral: os modelos Voxtral 2 (
voxtral-mini-2602,voxtral-mini-transcribe-realtime-2602,voxtral-mini-tts-2603, descontinuados a 31 de outubro de 2026 e retirados a 30 de abril de 2027) são substituídos nos exemplos porvoxtral-mini-transcribe-3,voxtral-mini-transcribe-realtime-3evoxtral-mini-tts-3-0. Alterações principais: as marcas temporais são apenas por segmento (worddevolve um erro 400), a diarização é possível em tempo real, as definições da sessão em tempo real ficam bloqueadas após o primeiro bloco de áudio e as entradascontext_biassão de formato livre (frases com espaços). Fontes: Migrate from Voxtral 2 · Speech to Text.
O Fluxo Assíncrono Completo em Python
Vai agora escrever um pipeline completo de transcrição em tempo real, desde o primeiro byte de áudio até ao ficheiro de texto final. Tudo depende do asyncio: o programa deve ler o áudio e receber os eventos do modelo simultaneamente, sem que nenhuma das operações bloqueie a outra. O código síncrono padrão limitava-se a esperar neste ponto, e a latência que configurou cuidadosamente desapareceria no tempo morto do seu próprio programa.
Arquitetura do Programa de Streaming
Independentemente da aplicação, a estrutura mantém-se igual e lê-se da esquerda para a direita. A montante, uma fonte de áudio: um gerador assíncrono que produz blocos de áudio PCM. Hoje pode ser um ficheiro, amanhã um microfone ou um fluxo de rede. No centro, o cliente Voxtral, ou seja, o SDK, que envia esses blocos para o modelo e lhe devolve eventos. A jusante, o processamento de eventos: a sua lógica de negócio, que exibe o texto, o acumula, o guarda ou o encaminha para outro serviço.
Audio Source → [PCM chunks] → Mistral SDK → [events] → Your Code
Esta separação traz uma vantagem prática: a fonte de áudio é substituível. O código de transcrição que escrever abaixo funcionará identicamente com o gerador de microfone da próxima lição, sem alterar uma única linha.
Implementação Básica
Dois detalhes neste primeiro programa merecem a sua atenção. O gerador source_audio_fichier divide o ficheiro em blocos de 32.000 bytes, o que corresponde exatamente a um segundo de áudio PCM mono de 16 bits a 16 kHz: 16.000 amostras multiplicadas por 2 bytes. O await asyncio.sleep que se segue a cada yield simula o tempo real; comente esta linha e execute o programa num excerto de alguns minutos, e verá o ficheiro consumido numa fração de segundo, não lhe ensinando nada sobre o comportamento do streaming. Do lado da receção, texte_complet acumula os fragmentos para que tenha o texto completo disponível no final, para além da exibição em direto.
import asyncio
import os
from mistralai.client import Mistral
from mistralai.client.models import (
AudioFormat,
TranscriptionStreamTextDelta,
TranscriptionStreamDone
)
async def source_audio_fichier(chemin: str, taille_chunk: int = 32000):
"""Gerador assíncrono que lê um ficheiro PCM em blocos.
taille_chunk = 32000 bytes = 1 segundo de áudio PCM mono de 16 bits a 16kHz
(16000 amostras × 2 bytes = 32000 bytes)
"""
with open(chemin, "rb") as f:
while True:
chunk = f.read(taille_chunk)
if not chunk:
break
yield chunk
# Simular tempo real (1 bloco = 1 segundo)
await asyncio.sleep(len(chunk) / 32000)
async def transcrire_realtime(source_audio):
"""Transcreve um fluxo de áudio em tempo real com o Voxtral."""
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
audio_format = AudioFormat(
encoding="pcm_s16le",
sample_rate=16000
)
texte_complet = []
async for event in client.audio.realtime.transcribe_stream(
audio_stream=source_audio,
model="voxtral-mini-transcribe-realtime-3",
audio_format=audio_format,
):
if isinstance(event, TranscriptionStreamTextDelta):
print(event.text, end="", flush=True)
texte_complet.append(event.text)
elif isinstance(event, TranscriptionStreamDone):
print("\n\n--- Transcrição concluída ---")
return "".join(texte_complet)
async def main():
source = source_audio_fichier("audio.pcm")
texte = await transcrire_realtime(source)
# Guardar o resultado
with open("transcription_realtime.txt", "w", encoding="utf-8") as f:
f.write(texte)
print(f"\nTexto guardado ({len(texte)} caracteres)")
asyncio.run(main())
A exibição em direto depende de print(event.text, end="", flush=True). Sem flush=True, o Python coloca a saída em buffer e o texto apareceria em lotes: a sua transcrição seria tecnicamente em tempo real, mas visualmente aos saltos.
Estruturar o Processamento para Produção
Assim que a sua aplicação ultrapassar a fase de demonstração, o ciclo if/elif torna-se incómodo: quererá contar fragmentos, medir a duração, ligar um ecrã ou alimentar uma base de dados. Encapsular a lógica numa classe resolve o problema de uma vez por todas. Cada tipo de evento obtém o seu próprio método dedicado e pode adicionar comportamento — por exemplo, enviar cada delta para uma interface web — sem tocar no ciclo de receção.
class GestionnaireTranscription:
"""Gere os eventos de transcrição em tempo real."""
def __init__(self):
self.texte_complet = []
self.nb_deltas = 0
self.debut = None
async def traiter(self, source_audio):
"""Inicia a transcrição e processa os eventos."""
import time
self.debut = time.time()
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
audio_format = AudioFormat(encoding="pcm_s16le", sample_rate=16000)
async for event in client.audio.realtime.transcribe_stream(
audio_stream=source_audio,
model="voxtral-mini-transcribe-realtime-3",
audio_format=audio_format,
):
if isinstance(event, TranscriptionStreamTextDelta):
self._on_text_delta(event)
elif isinstance(event, TranscriptionStreamDone):
self._on_done(event)
return self.obtenir_resultat()
def _on_text_delta(self, event):
"""Chamado para cada novo fragmento de texto."""
self.texte_complet.append(event.text)
self.nb_deltas += 1
# Exibição em direto
print(event.text, end="", flush=True)
def _on_done(self, event):
"""Chamado no final da transcrição."""
import time
duree = time.time() - self.debut
print(f"\n\nConcluído em {duree:.1f}s")
print(f"Fragmentos recebidos: {self.nb_deltas}")
def obtenir_resultat(self) -> str:
"""Devolve o texto transcrito completo."""
return "".join(self.texte_complet)
async def main():
gestionnaire = GestionnaireTranscription()
source = source_audio_fichier("audio.pcm")
texte = await gestionnaire.traiter(source)
print(f"Resultado: {len(texte)} caracteres")
asyncio.run(main())
O contador nb_deltas não é um artifício: relativamente à duração do áudio, indica a taxa de emissão do modelo e alerta-o se o fluxo se degradar.
Sobreviver a Interrupções de Rede
Uma ligação de streaming permanece aberta durante toda a duração da fala, expondo-a muito mais do que um pedido offline de alguns segundos. Uma Wi-Fi instável, uma mudança de rede num dispositivo móvel ou uma falha do operador podem interromper o fluxo. O padrão abaixo reinicia a transcrição até três vezes, com um atraso que aumenta a cada tentativa para permitir que a rede recupere. Para além disso, a exceção é propagada: uma falha explícita é preferível a uma aplicação que parece não ouvir nada.
import asyncio
from mistralai.client import Mistral
from mistralai.client.models import (
AudioFormat,
TranscriptionStreamTextDelta,
TranscriptionStreamDone
)
MAX_TENTATIVES = 3
DELAI_RECONNEXION = 2 # segundos
async def transcrire_avec_retry(source_audio, tentative=1):
"""Transcrição com reconexão automática."""
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
audio_format = AudioFormat(encoding="pcm_s16le", sample_rate=16000)
try:
async for event in client.audio.realtime.transcribe_stream(
audio_stream=source_audio,
model="voxtral-mini-transcribe-realtime-3",
audio_format=audio_format,
):
if isinstance(event, TranscriptionStreamTextDelta):
print(event.text, end="", flush=True)
elif isinstance(event, TranscriptionStreamDone):
print("\n[Concluído]")
except ConnectionError as e:
if tentative < MAX_TENTATIVES:
print(f"\nErro de rede (tentativa {tentative}/{MAX_TENTATIVES})")
await asyncio.sleep(DELAI_RECONNEXION * tentative)
await transcrire_avec_retry(source_audio, tentative + 1)
else:
print(f"\nFalha após {MAX_TENTATIVES} tentativas: {e}")
raise
Preparar um Ficheiro Existente
Para testar com um ficheiro MP3 ou WAV que já tenha à mão, pode automatizar a conversão para PCM a partir do Python, em vez de a executar manualmente. A função abaixo delega o trabalho ao FFmpeg, deduz o nome de saída a partir do nome de entrada e devolve o caminho resultante, pronto para passar a source_audio_fichier.
import subprocess
def convertir_en_pcm(chemin_entree: str, chemin_sortie: str = None) -> str:
"""Converte um ficheiro de áudio para PCM mono de 16 bits a 16kHz via FFmpeg."""
if chemin_sortie is None:
chemin_sortie = chemin_entree.rsplit(".", 1)[0] + ".pcm"
subprocess.run([
"ffmpeg", "-y",
"-i", chemin_entree,
"-f", "s16le",
"-acodec", "pcm_s16le",
"-ar", "16000",
"-ac", "1",
chemin_sortie
], check=True, capture_output=True)
return chemin_sortie
# Utilização
chemin_pcm = convertir_en_pcm("reunion.mp3")
# Depois usar source_audio_fichier(chemin_pcm)
Duas precauções com esta função. check=True lança uma exceção se o FFmpeg falhar, o que é melhor do que descobrir mais tarde um ficheiro PCM vazio no fluxo; e capture_output=True oculta a saída da ferramenta, pelo que uma conversão longa fará o programa parecer congelado. Para gravações de uma hora, planeie imprimir uma mensagem antes e depois da chamada.
Pontos-chave
- O streaming utiliza geradores assíncronos (
async for,yield) - Um bloco de 32.000 bytes = 1 segundo de áudio PCM mono de 16 bits a 16 kHz
- Estruture o processamento de eventos numa classe para produção
- Implemente um mecanismo de repetição para lidar com erros de rede
- Utilize o FFmpeg para converter ficheiros de áudio existentes para PCM
- A exibição em direto usa
print(texto, end="", flush=True)