Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Implementare la trascrizione in tempo reale in Python

Lezione 10 di 16 Aggiornata il 3 novembre 2026 Sviluppatore
In questa pagina
  1. Il flusso asincrono completo in Python
  2. Architettura del programma in streaming
  3. Implementazione di base
  4. Strutturare l’elaborazione per la produzione
  5. Sopravvivere alle interruzioni di rete
  6. Preparare un file esistente
  7. Punti chiave

Corso aggiornato il 3 novembre 2026 per Voxtral 3, basato sulla guida Migrate from Voxtral 2 di Mistral: i modelli Voxtral 2 (voxtral-mini-2602, voxtral-mini-transcribe-realtime-2602, voxtral-mini-tts-2603, deprecati il 31 ottobre 2026 e ritirati il 30 aprile 2027) sono sostituiti negli esempi da voxtral-mini-transcribe-3, voxtral-mini-transcribe-realtime-3 e voxtral-mini-tts-3-0. Cambiamenti principali: i timestamp sono solo per segmento (word restituisce un errore 400), la diarizzazione è possibile in tempo reale, le impostazioni della sessione in tempo reale vengono bloccate dopo il primo chunk audio e gli input context_bias sono in formato libero (frasi con spazi). Fonti: Migrate from Voxtral 2 · Speech to Text.

Il flusso asincrono completo in Python

Ora scriverai una pipeline completa di trascrizione in tempo reale, dal primo byte audio al file di testo finale. Tutto si basa su asyncio: il programma deve leggere l’audio e ricevere gli eventi del modello simultaneamente, senza che nessuna delle due operazioni blocchi l’altra. Un codice sincrono standard si limiterebbe ad attendere qui, e la latenza che hai configurato con cura svanirebbe nei tempi morti del tuo stesso programma.

Architettura del programma in streaming

Indipendentemente dall’applicazione, la struttura rimane la stessa e si legge da sinistra a destra. A monte, una sorgente audio: un generatore asincrono che produce chunk audio PCM. Oggi potrebbe essere un file, domani un microfono o un flusso di rete. Al centro, il client Voxtral, ovvero l’SDK, che invia questi chunk al modello e ti restituisce gli eventi. A valle, l’elaborazione degli eventi: la tua logica di business, che visualizza il testo, lo accumula, lo salva o lo inoltra a un altro servizio.

Sorgente Audio → [chunk PCM] → Mistral SDK → [eventi] → Il tuo Codice

Questa separazione ha un vantaggio pratico: la sorgente audio è intercambiabile. Il codice di trascrizione che scriverai qui sotto funzionerà in modo identico con il generatore del microfono della prossima lezione, senza cambiare una singola riga.

Implementazione di base

Due dettagli in questo primo programma meritano la tua attenzione. Il generatore source_audio_fichier suddivide il file in blocchi da 32.000 byte, che corrispondono esattamente a un secondo di audio PCM mono a 16 bit a 16 kHz: 16.000 campioni moltiplicati per 2 byte. L’istruzione await asyncio.sleep successiva a ogni yield simula il tempo reale; commenta questa riga ed esegui il programma su un estratto di pochi minuti: vedrai il file consumato in una frazione di secondo, il che non ti insegna nulla sul comportamento dello streaming. Sul lato ricezione, texte_complet accumula i frammenti in modo da avere l’intero testo disponibile alla fine, oltre alla visualizzazione in diretta.

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):
    """Generatore asincrono che legge un file PCM a chunk.

    taille_chunk = 32000 byte = 1 secondo di audio PCM mono a 16 bit a 16kHz
    (16000 campioni × 2 byte = 32000 byte)
    """
    with open(chemin, "rb") as f:
        while True:
            chunk = f.read(taille_chunk)
            if not chunk:
                break
            yield chunk
            # Simula il tempo reale (1 chunk = 1 secondo)
            await asyncio.sleep(len(chunk) / 32000)

async def transcrire_realtime(source_audio):
    """Trascrive un flusso audio in tempo reale con 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--- Trascrizione terminata ---")

    return "".join(texte_complet)

async def main():
    source = source_audio_fichier("audio.pcm")
    texte = await transcrire_realtime(source)

    # Salva il risultato
    with open("transcription_realtime.txt", "w", encoding="utf-8") as f:
        f.write(texte)
    print(f"\nTesto salvato ({len(texte)} caratteri)")

asyncio.run(main())

La visualizzazione in diretta si basa su print(event.text, end="", flush=True). Senza flush=True, Python bufferizza l’output e il testo apparirebbe a blocchi: la tua trascrizione sarebbe tecnicamente in tempo reale, ma visivamente a scatti.

Strutturare l’elaborazione per la produzione

Una volta che la tua applicazione va oltre la demo, il ciclo if/elif diventa ingombrante: vuoi contare i frammenti, misurare la durata, collegare un display o alimentare un database. Incapsulare la logica in una classe risolve il problema una volta per tutte. Ogni tipo di evento ottiene il suo metodo dedicato e puoi aggiungere comportamenti, ad esempio inviare ogni delta a un’interfaccia web, senza toccare il ciclo di ricezione.

class GestionnaireTranscription:
    """Gestisce gli eventi di trascrizione in tempo reale."""

    def __init__(self):
        self.texte_complet = []
        self.nb_deltas = 0
        self.debut = None

    async def traiter(self, source_audio):
        """Avvia la trascrizione ed elabora gli eventi."""
        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):
        """Chiamato per ogni nuovo frammento di testo."""
        self.texte_complet.append(event.text)
        self.nb_deltas += 1
        # Visualizzazione in diretta
        print(event.text, end="", flush=True)

    def _on_done(self, event):
        """Chiamato alla fine della trascrizione."""
        import time
        duree = time.time() - self.debut
        print(f"\n\nTerminato in {duree:.1f}s")
        print(f"Frammenti ricevuti: {self.nb_deltas}")

    def obtenir_resultat(self) -> str:
        """Restituisce l'intero testo trascritto."""
        return "".join(self.texte_complet)

async def main():
    gestionnaire = GestionnaireTranscription()
    source = source_audio_fichier("audio.pcm")
    texte = await gestionnaire.traiter(source)
    print(f"Risultato: {len(texte)} caratteri")

asyncio.run(main())

Il contatore nb_deltas non è un espediente: rispetto alla durata dell’audio, indica la velocità di emissione del modello e ti avvisa se lo streaming si degrada.

Sopravvivere alle interruzioni di rete

Una connessione in streaming rimane aperta per l’intera durata del parlato, esponendola molto più di una richiesta offline di pochi secondi. Un Wi-Fi instabile, un cambio di rete su un dispositivo mobile o un’interruzione dell’operatore possono interrompere il flusso. Il pattern sottostante riavvia la trascrizione fino a tre volte, con un ritardo che aumenta a ogni tentativo per dare tempo alla rete di riprendersi. Oltre questo limite, l’eccezione viene propagata: un fallimento esplicito è meglio di un’applicazione che sembra non ascoltare nulla.

import asyncio
from mistralai.client import Mistral
from mistralai.client.models import (
    AudioFormat,
    TranscriptionStreamTextDelta,
    TranscriptionStreamDone
)

MAX_TENTATIVES = 3
DELAI_RECONNEXION = 2  # secondi

async def transcrire_avec_retry(source_audio, tentative=1):
    """Trascrizione con riconnessione automatica."""
    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[Terminato]")

    except ConnectionError as e:
        if tentative < MAX_TENTATIVES:
            print(f"\nErrore di rete (tentativo {tentative}/{MAX_TENTATIVES})")
            await asyncio.sleep(DELAI_RECONNEXION * tentative)
            await transcrire_avec_retry(source_audio, tentative + 1)
        else:
            print(f"\nFallito dopo {MAX_TENTATIVES} tentativi: {e}")
            raise

Preparare un file esistente

Per testare con un file MP3 o WAV che hai già a disposizione, puoi automatizzare la conversione in PCM da Python invece di eseguirla manualmente. La funzione seguente delega il lavoro a FFmpeg, deduce il nome di output dal nome di input e restituisce il percorso risultante, pronto per essere passato a source_audio_fichier.

import subprocess

def convertir_en_pcm(chemin_entree: str, chemin_sortie: str = None) -> str:
    """Converte un file audio in PCM mono a 16 bit 16kHz tramite 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

# Utilizzo
chemin_pcm = convertir_en_pcm("reunion.mp3")
# Poi usa source_audio_fichier(chemin_pcm)

Due precauzioni con questa funzione. check=True solleva un’eccezione se FFmpeg fallisce, il che è meglio che scoprire un file PCM vuoto più avanti nello stream; e capture_output=True nasconde l’output dello strumento, quindi una conversione lunga farà sembrare il programma bloccato. Per registrazioni di un’ora, prevedi di stampare un messaggio prima e dopo la chiamata.

Punti chiave

  • Lo streaming utilizza generatori asincroni (async for, yield)
  • Un chunk da 32.000 byte = 1 secondo di audio PCM mono a 16 bit a 16 kHz
  • Struttura l’elaborazione degli eventi in una classe per la produzione
  • Implementa un meccanismo di retry per gestire gli errori di rete
  • Usa FFmpeg per convertire i file audio esistenti in PCM
  • La visualizzazione in diretta usa print(text, end="", flush=True)