Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Implementar Transcrição em Tempo Real em Python

Aula 10 de 16 Atualizada a 3 de novembro de 2026 Programador
Nesta página
  1. O Fluxo Assíncrono Completo em Python
  2. Arquitetura do Programa de Streaming
  3. Implementação Básica
  4. Estruturar o Processamento para Produção
  5. Sobreviver a Interrupções de Rede
  6. Preparar um Ficheiro Existente
  7. Pontos-chave

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 por voxtral-mini-transcribe-3, voxtral-mini-transcribe-realtime-3 e voxtral-mini-tts-3-0. Alterações principais: as marcas temporais são apenas por segmento (word devolve 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 entradas context_bias sã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)