Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Messaggi WebSocket: testo e audio

Lezione 10 di 14 Aggiornata il 3 novembre 2026 Sviluppatore
In questa pagina
  1. Il protocollo dei messaggi TTS
  2. Messaggi da client a server
  3. Messaggi da server a client
  4. Il flusso completo della comunicazione
  5. Implementazione completa in Python
  6. Implementazione in JavaScript (Node.js)
  7. Gestione di molti delta
  8. Punti chiave

Aggiornato il 3 novembre 2026, basato sulla pagina Text to Speech di xAI: delta fino a 60.000 caratteri, cancellazione (text.clear, audio.clear) e tabella di pronuncia (session.update, session.updated). Fonte: Text to Speech.

Il protocollo dei messaggi TTS

Una volta stabilita la connessione WebSocket, la comunicazione avviene tramite lo scambio di messaggi JSON. Tu invii del testo e il server risponde con audio codificato in base64. Comprendere questo protocollo è essenziale per implementare correttamente lo streaming TTS.

Messaggi da client a server

La tua applicazione invia quattro tipi di messaggi al server: text.delta e text.done per il testo, text.clear per annullare e session.update per configurare.

text.delta: invia un frammento di testo

Il messaggio text.delta invia un frammento di testo da convertire. Puoi inviare il testo in pezzi successivi:

{"type": "text.delta", "delta": "Ciao e benvenuti a "}
{"type": "text.delta", "delta": "la nostra presentazione sulla sintesi vocale."}

Ogni delta può contenere fino a 60.000 caratteri e il testo totale non ha limiti. Il server inizia a generare l’audio non appena dispone di contesto sufficiente per produrre una pronuncia naturale.

text.done: segnala la fine del testo

Il messaggio text.done informa il server che hai finito di inviare testo per questa sequenza:

{"type": "text.done"}

Una volta ricevuto questo messaggio, il server termina la generazione dell’audio e invia un messaggio audio.done. A quel punto puoi iniziare a inviare nuovi delta per una nuova sequenza.

text.clear: annulla la sequenza corrente

text.clear annulla la sequenza corrente: il server smette di generare audio, scarta ciò che aveva in memoria e risponde con audio.clear. La connessione è immediatamente pronta per la sequenza successiva, senza bisogno di un nuovo handshake WebSocket; xAI stima un risparmio di circa 600 ms per un client remoto. È il meccanismo di interruzione (“barge-in”) da usare quando l’utente interrompe il flusso.

{"type": "text.clear"}

session.update: correggi la pronuncia

session.update installa o sostituisce la tabella replace della connessione: ogni frase trovata nel testo viene scambiata con la sua forma parlata prima della sintesi, senza modificare il testo che invii né il numero di caratteri fatturati. Invialo prima del primo text.delta in modo che copra l’intera connessione; un aggiornamento ricevuto a metà sequenza si applicherà solo dalla sequenza successiva.

{"type": "session.update", "replace": {"kubectl": "kube cuttle"}}

Messaggi da server a client

Il server risponde con cinque tipi di messaggi: audio.delta, audio.done ed error, dettagliati di seguito, più audio.clear, che conferma una cancellazione, e session.updated, che restituisce la tabella replace in vigore.

audio.delta: un frammento di audio

Il messaggio audio.delta contiene un frammento audio codificato in base64:

{
  "type": "audio.delta",
  "delta": "SUQzBAAAAAAAI1RTU0UAAAAPAAADTGF2ZjU4Ljc2..."
}

Ogni delta è un pezzo di audio valido che puoi decodificare e riprodurre immediatamente. I delta arrivano man mano che la generazione procede.

audio.done: generazione terminata

Il messaggio audio.done segnala che tutto l’audio per la sequenza di testo inviata è stato generato:

{
  "type": "audio.done",
  "trace_id": "550e8400-e29b-41d4-a716-446655440000"
}

Il trace_id è un ID univoco per la sequenza, utile per il debug e il tracciamento.

error: si è verificato un errore

Se qualcosa va storto, il server invia un messaggio di errore:

{
  "type": "error",
  "message": "Codifica testo non valida"
}

Il flusso completo della comunicazione

Ecco come si svolge una sessione tipica:

Client                          Server
  |                                |
  |-- text.delta ("Ciao, ") ----->|
  |-- text.delta ("come stai ") ---->|
  |-- text.delta ("?") -------->|
  |<-- audio.delta (chunk 1) -----|
  |<-- audio.delta (chunk 2) -----|
  |-- text.done ----------------->|
  |<-- audio.delta (chunk 3) -----|
  |<-- audio.done ----------------|

Il server può iniziare a inviare messaggi audio.delta prima ancora che tu abbia inviato text.done. È proprio questa l’idea dello streaming: la generazione inizia il prima possibile.

Implementazione completa in Python

import asyncio
import websockets
import json
import base64

async def stream_tts(api_key, text, voice="eve", language="en"):
    uri = f"wss://api.x.ai/v1/tts?language={language}&voice={voice}&codec=mp3"
    headers = {"Authorization": f"Bearer {api_key}"}

    audio_chunks = []

    async with websockets.connect(uri, additional_headers=headers) as ws:
        # Invia il testo in pezzi da 2.000 caratteri
        chunk_size = 2000
        for i in range(0, len(text), chunk_size):
            chunk = text[i:i + chunk_size]
            await ws.send(json.dumps({
                "type": "text.delta",
                "delta": chunk
            }))

        # Segnala la fine del testo
        await ws.send(json.dumps({"type": "text.done"}))

        # Ricevi i pezzi audio
        async for message in ws:
            data = json.loads(message)

            if data["type"] == "audio.delta":
                audio_bytes = base64.b64decode(data["delta"])
                audio_chunks.append(audio_bytes)

            elif data["type"] == "audio.done":
                print(f"Generazione terminata (trace: {data['trace_id']})")
                break

            elif data["type"] == "error":
                raise Exception(f"Errore TTS: {data['message']}")

    # Assembla l'audio completo
    return b"".join(audio_chunks)

Implementazione in JavaScript (Node.js)

const WebSocket = require("ws");

function streamTTS(apiKey, text, voice = "eve", language = "en") {
  return new Promise((resolve, reject) => {
    const ws = new WebSocket(
      `wss://api.x.ai/v1/tts?language=${language}&voice=${voice}&codec=mp3`,
      { headers: { Authorization: `Bearer ${apiKey}` } }
    );

    const audioChunks = [];

    ws.on("open", () => {
      // Invia il testo
      ws.send(JSON.stringify({ type: "text.delta", delta: text }));
      ws.send(JSON.stringify({ type: "text.done" }));
    });

    ws.on("message", (raw) => {
      const data = JSON.parse(raw);

      if (data.type === "audio.delta") {
        audioChunks.push(Buffer.from(data.delta, "base64"));
      } else if (data.type === "audio.done") {
        ws.close();
        resolve(Buffer.concat(audioChunks));
      } else if (data.type === "error") {
        ws.close();
        reject(new Error(data.message));
      }
    });

    ws.on("error", reject);
  });
}

Gestione di molti delta

Per il testo generato progressivamente (ad esempio l’output di un LLM), invia ogni token direttamente al WebSocket TTS:

async def llm_to_speech(ws_tts, llm_stream):
    async for token in llm_stream:
        await ws_tts.send(json.dumps({
            "type": "text.delta",
            "delta": token
        }))

    await ws_tts.send(json.dumps({"type": "text.done"}))

Questa architettura “streaming LLM in streaming TTS” offre la latenza più bassa possibile: l’utente sente la risposta mentre l’LLM sta ancora generando.

Punti chiave

  • Quattro messaggi client: text.delta (invia testo), text.done (fine testo), text.clear (annulla) e session.update (tabella replace)
  • Cinque messaggi server: audio.delta (un pezzo di audio), audio.done (fine), audio.clear (cancellazione confermata), session.updated ed error
  • L’audio è codificato in base64 nei messaggi audio.delta
  • Il server inizia la generazione prima di ricevere text.done
  • Ogni delta di testo è limitato a 60.000 caratteri
  • Collegare un LLM in streaming a un TTS in streaming garantisce la latenza minima