Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Streaming in tempo reale

Lezione 10 di 14 Aggiornata il 3 novembre 2026 Sviluppatore
In questa pagina
  1. Perché lo streaming cambia tutto
  2. Il protocollo degli eventi
  3. Riprodurre il suono man mano che arriva
  4. Inoltrare lo stream a un browser
  5. L’impostazione che fa la differenza: il buffer
  6. Punti chiave

Corso aggiornato il 3 novembre 2026 per Voxtral TTS 3, basato sulla guida Migrate from Voxtral 2 e sulle pagine Text to Speech di Mistral: voxtral-mini-tts-2603, deprecato il 31 ottobre 2026 e ritirato il 30 aprile 2027, viene sostituito negli esempi da voxtral-mini-tts-3-0. Le voci predefinite di Voxtral 2 (gb_jane_neutral…) rimangono supportate; Voxtral 3 aggiunge i tag [emotion=…] e [pace=…] nel testo, l’impostazione expressiveness, la pronuncia personalizzata (phoneme_hints) e 35 lingue. Mistral consiglia di rimisurare la latenza dopo la migrazione. Fonti: Migrate from Voxtral 2 · Speech generation.

Perché lo streaming cambia tutto

Finora hai lavorato in modalità sincrona: invii il testo, attendi il completamento totale della sintesi e ricevi poi l’intero file audio. Per un saluto pre-generato il giorno prima, questa attesa è irrilevante. Per un assistente vocale che risponde a un cliente al telefono, è inaccettabile: due secondi di silenzio dopo una domanda e l’utente pensa che la chiamata sia caduta.

Lo streaming elimina questa attesa. L’audio viene inviato man mano che viene generato, frammento per frammento, così l’utente sente le prime parole mentre il modello sta ancora producendo la fine della frase. Il tempo totale di generazione non cambia; ciò che crolla è il ritardo prima del primo suono.

Il protocollo degli eventi

Lo stream si basa su Server-Sent Events. Ogni messaggio ricevuto è un evento tipizzato e due tipi ti riguardano:

  • speech.audio.delta: contiene un frammento audio in base64. Questo è l’evento principale che gestirai
  • speech.audio.done: segnale di fine, la generazione è completa

Lato codice, passare allo streaming significa aggiungere stream=True e consumare la risposta in un blocco with. L’esempio seguente accumula i frammenti in memoria per scrivere un file alla fine: non è ancora tempo reale, ma è la struttura del loop su cui si baserà il resto della lezione.

import base64
from pathlib import Path
from mistralai.client import Mistral

client = Mistral(api_key="your-api-key")

audio_chunks = []

with client.audio.speech.complete(
    model="voxtral-mini-tts-3-0",
    input="Streaming makes voice agents responsive and natural.",
    voice_id="your-voice-id",
    response_format="opus",
    stream=True,
) as stream:
    for event in stream:
        if event.event == "speech.audio.delta":
            chunk = base64.b64decode(event.data.audio_data)
            audio_chunks.append(chunk)
            print(f"Chunk received: {len(chunk)} bytes")

# Assemble all chunks
audio_complet = b"".join(audio_chunks)
Path("streaming-output.opus").write_bytes(audio_complet)
print(f"Final audio: {len(audio_complet)} bytes")

Riprodurre il suono man mano che arriva

Per ottenere la reattività promessa, smetti di accumulare e scrivi ogni frammento direttamente sulla scheda audio. Con pyaudio, la modifica richiede una riga: invece di aggiungere il frammento decodificato a una lista, lo invii a uno stream di output aperto in anticipo, configurato per mono Float32 a 24.000 Hz.

import base64
import pyaudio
from mistralai.client import Mistral

client = Mistral(api_key="your-api-key")

# PCM audio configuration (fastest format)
p = pyaudio.PyAudio()
stream_audio = p.open(
    format=pyaudio.paFloat32,
    channels=1,
    rate=24000,
    output=True,
)

with client.audio.speech.complete(
    model="voxtral-mini-tts-3-0",
    input="You're hearing this sentence while I generate it.",
    voice_id="your-voice-id",
    response_format="pcm",
    stream=True,
) as stream:
    for event in stream:
        if event.event == "speech.audio.delta":
            audio_data = base64.b64decode(event.data.audio_data)
            stream_audio.write(audio_data)

stream_audio.stop_stream()
stream_audio.close()
p.terminate()

Il formato richiesto è cambiato da opus a pcm, e questo conta. Il PCM non richiede decodifica: i byte ricevuti sono pronti per essere riprodotti immediatamente, rendendolo il formato consigliato per l’uso in tempo reale.

Inoltrare lo stream a un browser

In un’app web, il server non riproduce il suono: lo inoltra. Lo schema classico utilizza un WebSocket che riceve il testo dal browser, apre lo stream Voxtral e spinge ogni frammento decodificato indietro al client. Lato browser, è la Web Audio API a prendere il sopravvento per riprodurre i frammenti PCM ricevuti.

# Server side (FastAPI example)
from fastapi import FastAPI, WebSocket
import base64
from mistralai.client import Mistral

app = FastAPI()
client = Mistral(api_key="your-api-key")

@app.websocket("/ws/tts")
async def tts_websocket(websocket: WebSocket):
    await websocket.accept()
    texte = await websocket.receive_text()

    with client.audio.speech.complete(
        model="voxtral-mini-tts-3-0",
        input=texte,
        voice_id="your-voice-id",
        response_format="pcm",
        stream=True,
    ) as stream:
        for event in stream:
            if event.event == "speech.audio.delta":
                await websocket.send_bytes(
                    base64.b64decode(event.data.audio_data)
                )

    await websocket.close()

L’impostazione che fa la differenza: il buffer

Le dimensioni dei frammenti variano e rappresentano tipicamente pochi millisecondi di audio ciascuno. Se riproduci il primo frammento non appena arriva, qualsiasi irregolarità di rete causa un micro-interruzione udibile: un singhiozzo nella voce che rivela immediatamente la macchina. La soluzione è mettere in buffer due o tre frammenti prima di avviare la riproduzione, al costo di alcune decine di millisecondi, livellando così il resto dello stream.

C’è poi la scelta del formato, che bilancia latenza e larghezza di banda. Il PCM fornisce il primo suono più velocemente, circa 0,7 secondi nelle misurazioni effettuate con Voxtral 2 (da rifare con Voxtral TTS 3), a scapito di un throughput elevato. Opus perde un po’ sulla latenza ma comprime pesantemente, rendendolo il compromesso giusto quando i tuoi utenti sono su mobile.

Punti chiave

  • Lo streaming invia l’audio frammento per frammento durante la generazione
  • Abilitalo con stream=True nella chiamata audio.speech.complete()
  • Gli eventi speech.audio.delta contengono frammenti audio in base64
  • Il formato PCM offre la latenza più bassa per lo streaming (~0,7s contro ~2s per MP3)
  • Per la riproduzione in tempo reale, usa pyaudio o WebSocket + Web Audio API