Preskok na glavno vsebino
Slovenščina— Izberite jezik
Meni

Sporočila WebSocket: besedilo in zvok

Lekcija 10 od 14 Posodobljeno 3. november 2026 Razvijalec
Na tej strani
  1. Protokol sporočil TTS
  2. Sporočila od odjemalca do strežnika
  3. Sporočila od strežnika do odjemalca
  4. Celoten potek komunikacije
  5. Popolna implementacija v Pythonu
  6. Implementacija v JavaScriptu (Node.js)
  7. Obdelava več delt
  8. Ključne ugotovitve

Posodobljeno 3. novembra 2026 na podlagi strani xAI Text to Speech: delte do 60.000 znakov, preklic (text.clear, audio.clear) in tabela izgovorjave (session.update, session.updated). Vir: Text to Speech.

Protokol sporočil TTS

Ko je povezava WebSocket vzpostavljena, komunikacija poteka z izmenjavo sporočil JSON. Ti pošlješ besedilo, strežnik pa odgovori z zvočnimi podatki, kodiranimi v base64. Razumevanje tega protokola je ključno za pravilno implementacijo pretakanja TTS.

Sporočila od odjemalca do strežnika

Tvoja aplikacija strežniku pošlje štiri vrste sporočil: text.delta in text.done za besedilo, text.clear za preklic ter session.update za konfiguracijo.

text.delta: pošiljanje dela besedila

Sporočilo text.delta pošlje del besedila za pretvorbo. Besedilo lahko pošlješ v zaporednih kosih:

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

Vsaka delta lahko vsebuje do 60.000 znakov, skupna dolžina besedila pa ni omejena. Strežnik začne generirati zvok takoj, ko ima dovolj konteksta za naravno izgovorjavo.

text.done: signalizacija konca besedila

Sporočilo text.done strežniku sporoči, da si končal s pošiljanjem besedila za to zaporedje:

{"type": "text.done"}

Ko strežnik prejme to sporočilo, dokonča generiranje zvoka in pošlje sporočilo audio.done. Nato lahko začneš pošiljati nove delte za novo zaporedje.

text.clear: preklic trenutnega zaporedja

text.clear prekliče trenutno zaporedje: strežnik ustavi generiranje zvoka, zavrže vsebino v pomnilniku in odgovori z audio.clear. Povezava je takoj pripravljena za naslednje zaporedje brez novega rokovanja WebSocket; xAI ocenjuje prihranek na približno 600 ms za oddaljene odjemalce. To je mehanizem za prekinitev („barge-in”), ko uporabnik poseže vmes.

{"type": "text.clear"}

session.update: popravek izgovorjave

session.update namesti ali nadomesti tabelo replace za povezavo: vsak stavek, najden v besedilu, se pred sintezo zamenja z njegovo govorno obliko, ne da bi se spremenilo besedilo, ki ga pošlješ, ali število zaračunanih znakov. Pošlji ga pred prvim text.delta, da zajame celotno povezavo; posodobitev, prejeta sredi zaporedja, velja šele od naslednjega zaporedja.

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

Sporočila od strežnika do odjemalca

Strežnik odgovori s petimi vrstami sporočil: audio.delta, audio.done in error, ki so podrobneje opisani spodaj, ter audio.clear, ki potrjuje preklic, in session.updated, ki vrne veljavno tabelo replace.

audio.delta: del zvoka

Sporočilo audio.delta vsebuje del zvoka, kodiran v base64:

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

Vsaka delta je veljaven del zvoka, ki ga lahko takoj dekodiraš in predvajaš. Delte prihajajo med potekom generiranja.

audio.done: generiranje končano

Sporočilo audio.done signalizira, da je ves zvok za zaporedje besedila, ki si ga poslal, generiran:

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

trace_id je edinstven ID za zaporedje, koristen za razhroščevanje in sledenje.

error: prišlo je do napake

Če kaj gre narobe, strežnik pošlje sporočilo o napaki:

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

Celoten potek komunikacije

Tako običajno poteka seja:

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 ----------------|

Strežnik lahko začne pošiljati sporočila audio.delta, še preden pošlješ text.done. To je bistvo pretakanja: generiranje se začne čim prej.

Popolna implementacija v Pythonu

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:
        # Send the text in pieces of 2,000 characters
        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
            }))

        # Signal the end of the text
        await ws.send(json.dumps({"type": "text.done"}))

        # Receive the audio pieces
        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"Generation finished (trace: {data['trace_id']})")
                break

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

    # Assemble the complete audio
    return b"".join(audio_chunks)

Implementacija v JavaScriptu (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", () => {
      // Send the text
      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);
  });
}

Obdelava več delt

Pri besedilu, ki nastaja postopoma (npr. izhod LLM), pošlji vsak žeton neposredno na 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"}))

Ta arhitektura „pretakanje LLM v pretakanje TTS” ponuja najnižjo možno zakasnitev: uporabnik sliši odgovor, medtem ko LLM še vedno generira.

Ključne ugotovitve

  • Štiri sporočila odjemalca: text.delta (pošlji besedilo), text.done (konec besedila), text.clear (preklic) in session.update (tabela replace)
  • Pet sporočil strežnika: audio.delta (del zvoka), audio.done (konec), audio.clear (potrditev preklica), session.updated in error
  • Zvok je v sporočilih audio.delta kodiran v base64
  • Strežnik začne generirati, preden prejme text.done
  • Vsaka delta besedila je omejena na 60.000 znakov
  • Veriženje pretakanja LLM v pretakanje TTS zagotavlja najnižjo zakasnitev