Zum Hauptinhalt springen
Deutsch— Sprache auswählen
Menü

WebSocket-Nachrichten: Text und Audio

Lektion 10 von 14 Aktualisiert am 3. November 2026 Entwickler
Auf dieser Seite
  1. Das TTS-Nachrichtenprotokoll
  2. Client-zu-Server-Nachrichten
  3. Server-zu-Client-Nachrichten
  4. Der vollständige Kommunikationsablauf
  5. Komplexe Implementierung in Python
  6. Implementierung in JavaScript (Node.js)
  7. Umgang mit vielen Deltas
  8. Kernaussagen

Aktualisiert am 3. November 2026, basierend auf der xAI-Seite Text to Speech: Deltas von bis zu 60.000 Zeichen, Abbruch (text.clear, audio.clear) und die Aussprachetabelle (session.update, session.updated). Quelle: Text to Speech.

Das TTS-Nachrichtenprotokoll

Sobald die WebSocket-Verbindung geöffnet ist, erfolgt die Kommunikation durch den Austausch von JSON-Nachrichten. Sie senden Text, und der Server antwortet mit base64-kodiertem Audio. Das Verständnis dieses Protokolls ist unerlässlich, um die TTS-Streaming-Funktion korrekt zu implementieren.

Client-zu-Server-Nachrichten

Ihre Anwendung sendet vier Arten von Nachrichten an den Server: text.delta und text.done für Text, text.clear zum Abbrechen und session.update zur Konfiguration.

text.delta: Senden eines Textfragments

Die Nachricht text.delta sendet ein Textfragment zur Umwandlung. Sie können den Text in aufeinanderfolgenden Stücken senden:

{"type": "text.delta", "delta": "Hello, and welcome to "}
{"type": "text.delta", "delta": "our presentation on speech synthesis."}

Jedes Delta kann bis zu 60.000 Zeichen enthalten, und der gesamte Text hat keine Obergrenze. Der Server beginnt mit der Audioerzeugung, sobald er genügend Kontext für eine natürliche Aussprache hat.

text.done: Signalisieren des Textendes

Die Nachricht text.done informiert den Server, dass Sie das Senden des Textes für diese Sequenz abgeschlossen haben:

{"type": "text.done"}

Sobald dieser empfangen wird, beendet der Server die Audioerzeugung und sendet eine audio.done-Nachricht. Anschließend können Sie neue Deltas für eine neue Sequenz senden.

text.clear: Abbrechen der aktuellen Sequenz

text.clear bricht die aktuelle Sequenz ab: Der Server stoppt die Audioerzeugung, löscht den im Speicher gehaltenen Inhalt und antwortet mit audio.clear. Die Verbindung ist sofort bereit für die nächste Sequenz, ohne dass ein neuer WebSocket-Handshake erforderlich ist; xAI veranschlagt die Ersparnis bei etwa 600 ms für einen entfernten Client. Es handelt sich um den Unterbrechungsmechanismus („Barge-in”), wenn der Nutzer einbricht.

{"type": "text.clear"}

session.update: Aussprache korrigieren

session.update installiert oder ersetzt die replace-Tabelle der Verbindung: Jeder im Text gefundene Ausdruck wird vor der Synthese durch seine gesprochene Form ersetzt, ohne den gesendeten Text oder die Anzahl der abgerechneten Zeichen zu ändern. Senden Sie diese Nachricht vor dem ersten text.delta, damit sie die gesamte Verbindung abdeckt; ein Update, das während einer Sequenz empfangen wird, gilt erst ab der nächsten Sequenz.

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

Server-zu-Client-Nachrichten

Der Server antwortet mit fünf Arten von Nachrichten: audio.delta, audio.done und error, die unten detailliert beschrieben sind, sowie audio.clear, das eine Abbruchbestätigung darstellt, und session.updated, das die gültige replace-Tabelle zurückgibt.

audio.delta: Ein Audiofragment

Die Nachricht audio.delta enthält ein base64-kodiertes Audiofragment:

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

Jedes Delta ist ein gültiges Audiofragment, das sofort decodiert und abgespielt werden kann. Die Deltas eintreffen, während die Erzeugung fortschreitet.

audio.done: Erzeugung abgeschlossen

Die Nachricht audio.done signalisiert, dass das gesamte Audio für die von Ihnen gesendete Textsequenz erzeugt wurde:

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

Die trace_id ist eine eindeutige Kennung für die Sequenz, die für die Fehlerbehebung und Verfolgung nützlich ist.

error: Ein Fehler ist aufgetreten

Wenn etwas schiefgeht, sendet der Server eine Fehlermeldung:

{
  "type": "error",
  "message": "Invalid text encoding"
}

Der vollständige Kommunikationsablauf

So verläuft eine typische Sitzung:

Client                          Server
  |                                |
  |-- text.delta ("Hello, ") ----->|
  |-- text.delta ("how are ") ---->|
  |-- text.delta ("you?") -------->|
  |<-- audio.delta (Chunk 1) -----|
  |<-- audio.delta (Chunk 2) -----|
  |-- text.done ----------------->|
  |<-- audio.delta (Chunk 3) -----|
  |<-- audio.done ----------------|

Der Server kann audio.delta-Nachrichten senden, bevor Sie text.done gesendet haben. Das ist der Kern des Streamings: Die Erzeugung beginnt so früh wie möglich.

Komplexe Implementierung 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:
        # Senden des Textes in Blöcken von 2.000 Zeichen
        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
            }))

        # Signalisieren des Textendes
        await ws.send(json.dumps({"type": "text.done"}))

        # Empfangen der Audiofragmente
        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"Erzeugung abgeschlossen (Trace: {data['trace_id']})")
                break

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

    # Zusammenfügen des vollständigen Audios
    return b"".join(audio_chunks)

Implementierung 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", () => {
      // Senden des Textes
      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);
  });
}

Umgang mit vielen Deltas

Für progressiv generierten Text (z. B. die Ausgabe eines LLM) senden Sie jedes Token direkt an den TTS-WebSocket:

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"}))

Diese Architektur „Streaming-LLM in Streaming-TTS” bietet die geringstmögliche Latenz: Der Nutzer hört die Antwort, während das LLM noch generiert.

Kernaussagen

  • Vier Client-Nachrichten: text.delta (Text senden), text.done (Textende), text.clear (Abbrechen) und session.update (replace-Tabelle)
  • Fünf Server-Nachrichten: audio.delta (ein Audiofragment), audio.done (Ende), audio.clear (Abbruch bestätigt), session.updated und error
  • Audio ist in audio.delta-Nachrichten base64-kodiert
  • Der Server beginnt mit der Erzeugung, bevor er text.done erhält
  • Jedes Text-Delta ist auf 60.000 Zeichen begrenzt
  • Die Verkettung eines Streaming-LLM mit Streaming-TTS ergibt die geringste Latenz