Hoppa till huvudinnehåll
Svenska— Välj ett språk
Meny

WebSocket-meddelanden: text och ljud

Lektion 10 av 14 Uppdaterad 3 november 2026 Utvecklare
På denna sida
  1. TTS-meddelandeprotokollet
  2. Meddelanden från klient till server
  3. Meddelanden från server till klient
  4. Det fullständiga kommunikationsflödet
  5. Fullständig implementation i Python
  6. Implementation i JavaScript (Node.js)
  7. Hantering av många deltar
  8. Viktiga punkter

Uppdaterat den 3 november 2026, baserat på xAI:s sida Text to Speech: deltar (deltas) på upp till 60 000 tecken, avbrytning (text.clear, audio.clear) och uttalstabellen (session.update, session.updated). Källa: Text to Speech.

TTS-meddelandeprotokollet

När WebSocket-anslutningen är öppen sker kommunikationen genom utbyte av JSON-meddelanden. Du skickar text och servern svarar med ljud kodat i base64. Att förstå detta protokoll är avgörande för att implementera TTS-streaming korrekt.

Meddelanden från klient till server

Din app skickar fyra typer av meddelanden till servern: text.delta och text.done för text, text.clear för att avbryta, samt session.update för konfiguration.

text.delta: skicka en textbit

Meddelandet text.delta skickar en textfragment för konvertering. Du kan skicka texten i successiva bitar:

{"type": "text.delta", "delta": "Hej, och välkommen till "}
{"type": "text.delta", "delta": "vår presentation om talgenerering."}

Varje delta kan innehålla upp till 60 000 tecken, och den totala textmängden har ingen begränsning. Servern börjar generera ljud så snart den har tillräckligt med kontext för att producera ett naturligt uttal.

text.done: signalera slutet på texten

Meddelandet text.done talar om för servern att du har slutat skicka text för denna sekvens:

{"type": "text.done"}

När servern tar emot detta meddelande avslutar den ljudgenereringen och skickar ett meddelande audio.done. Därefter kan du börja skicka nya deltar för en ny sekvens.

text.clear: avbryt den aktuella sekvensen

text.clear avbryter den aktuella sekvensen: servern slutar generera ljud, kasserar det den hade i minnet och svarar med audio.clear. Anslutningen är omedelbart redo för nästa sekvens utan någon ny WebSocket-handskakning; xAI uppskattar besparingen till cirka 600 ms för en klient på avstånd. Det är mekanismen för avbrott (“barge-in”) när användaren avbryter.

{"type": "text.clear"}

session.update: korrigera uttal

session.update installerar eller ersätter anslutningens replace-tabell: varje fras som hittas i texten byts ut mot sitt talade format innan syntes, utan att ändra texten du skickar eller antalet tecken du debiteras för. Skicka det före den första text.delta så att det täcker hela anslutningen; en uppdatering som tas emot mitt i en sekvens gäller först från nästa sekvens.

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

Meddelanden från server till klient

Servern svarar med fem typer av meddelanden: audio.delta, audio.done och error, som beskrivs nedan, plus audio.clear som bekräftar ett avbrott, och session.updated som returnerar den gällande replace-tabellen.

audio.delta: en ljudbit

Meddelandet audio.delta innehåller en ljudfragment kodad i base64:

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

Varje delta är en giltig ljudbit som du kan dekoda och spela upp direkt. Deltar anländer i takt med att genereringen fortskrider.

audio.done: genereringen avslutad

Meddelandet audio.done signalerar att allt ljud för textsekvensen du skickat har genererats:

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

trace_id är ett unikt ID för sekvensen, användbart för felsökning och spårning.

error: ett fel har inträffat

Om något går fel skickar servern ett felmeddelande:

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

Det fullständiga kommunikationsflödet

Så här ser en typisk session ut:

Klient                          Server
  |                                |
  |-- text.delta ("Hej, ") ------->|
  |-- text.delta ("hur mår ") ---->|
  |-- text.delta ("du?") --------->|
  |<-- audio.delta (bit 1) --------|
  |<-- audio.delta (bit 2) --------|
  |-- text.done ------------------>|
  |<-- audio.delta (bit 3) --------|
  |<-- audio.done -----------------|

Servern kan börja skicka audio.delta-meddelanden innan du ens har skickat text.done. Det är hela poängen med streaming: genereringen startar så snart som möjligt.

Fullständig implementation i 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:
        # Skicka texten i bitar om 2 000 tecken
        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
            }))

        # Signalera slutet på texten
        await ws.send(json.dumps({"type": "text.done"}))

        # Ta emot ljudbitarna
        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"Generering avslutad (spårning: {data['trace_id']})")
                break

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

    # Sammanställ det kompletta ljudet
    return b"".join(audio_chunks)

Implementation i 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", () => {
      // Skicka texten
      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);
  });
}

Hantering av många deltar

För text som genereras progressivt (till exempel utdata från en LLM), skickar du varje token direkt till TTS-WebSocketen:

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

Denna arkitektur, “streaming LLM in i streaming TTS”, erbjuder den lägsta möjliga latensen: användaren hör svaret medan LLM:n fortfarande genererar.

Viktiga punkter

  • Fyra klientmeddelanden: text.delta (skicka text), text.done (slut på text), text.clear (avbryt) och session.update (replace-tabell)
  • Fem servermeddelanden: audio.delta (en ljudbit), audio.done (slut), audio.clear (avbrott bekräftat), session.updated och error
  • Ljudet är base64-kodat i audio.delta-meddelanden
  • Servern börjar generera innan den tar emot text.done
  • Varje textdelta är begränsat till 60 000 tecken
  • Att koppla en streaming-LLM till en streaming-TTS ger lägst latens