Prejsť na hlavný obsah
Slovenčina— Vyberte jazyk
Menu

Správy WebSocket: text a zvuk

Lekcia 10 z 14 Aktualizované 3. novembra 2026 Vývojár
Na tejto strane
  1. Protokol správ TTS
  2. Správy od klienta k serveru
  3. Správy od servera ku klientovi
  4. Úplný tok komunikácie
  5. Kompletná implementácia v Pythone
  6. Implementácia v JavaScripte (Node.js)
  7. Spracovanie viacerých delt
  8. Kľúčové poznatky

Aktualizované 3. novembra 2026 na základe stránky xAI Text to Speech: delty až do 60 000 znakov, zrušenie (text.clear, audio.clear) a tabuľka výslovnosti (session.update, session.updated). Zdroj: Text to Speech.

Protokol správ TTS

Akonáhle je spojenie WebSocket otvorené, komunikácia prebieha výmenou správ vo formáte JSON. Ty posielaš text a server odpovedá zvukom zakódovaným v base64. Pochopenie tohto protokolu je kľúčové pre správnu implementáciu streamovania TTS.

Správy od klienta k serveru

Tvoja aplikácia posiela serveru štyri typy správ: text.delta a text.done pre text, text.clear na zrušenie a session.update na konfiguráciu.

text.delta: odoslanie časti textu

Správa text.delta odosiela fragment textu na konverziu. Text môžeš posielať v postupných častiach:

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

Každá delta môže obsahovať až 60 000 znakov a celkový text nemá žiadny limit. Server začne generovať zvuk hneď, ako má dostatok kontextu na vytvorenie prirodzenej výslovnosti.

text.done: signalizácia konca textu

Správa text.done informuje server, že si dokončil odosielanie textu pre túto sekvenciu:

{"type": "text.done"}

Akonáhle server túto správu prijme, dokončí generovanie zvuku a odošle správu audio.done. Potom môžeš začať posielať nové delty pre novú sekvenciu.

text.clear: zrušenie aktuálnej sekvencie

text.clear zruší aktuálnu sekvenciu: server prestane generovať zvuk, zahodí údaje v pamäti a odpovie správou audio.clear. Spojenie je okamžite pripravené na ďalšiu sekvenciu bez potreby nového handshake WebSocket; xAI odhaduje úsporu času na približne 600 ms pre vzdialeného klienta. Ide o mechanizmus prerušenia („barge-in“) pre situácie, keď používateľ vstúpi do reči.

{"type": "text.clear"}

session.update: oprava výslovnosti

session.update nainštaluje alebo nahradí tabuľku replace pre dané spojenie: každá fráza nájdená v texte sa pred syntézou vymení za jej hovorenú formu, pričom sa nezmení text, ktorý posielaš, ani počet znakov, za ktoré sa účtuje poplatok. Pošli ju pred prvou správou text.delta, aby sa vzťahovala na celé spojenie; aktualizácia prijatá uprostred sekvencie sa aplikuje až od nasledujúcej sekvencie.

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

Správy od servera ku klientovi

Server odpovedá piatimi typmi správ: audio.delta, audio.done a error, ktoré sú podrobne popísané nižšie, plus audio.clear, ktorá potvrdzuje zrušenie, a session.updated, ktorá vracia aktívnu tabuľku replace.

audio.delta: časť zvuku

Správa audio.delta obsahuje fragment zvuku zakódovaný v base64:

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

Každá delta je platný kus zvuku, ktorý môžeš okamžite dekódovať a prehrať. Delty prichádzajú v priebehu generovania.

audio.done: generovanie dokončené

Správa audio.done signalizuje, že bol vygenerovaný celý zvuk pre textovú sekvenciu, ktorú si poslal:

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

trace_id je jedinečné ID pre sekvenciu, užitočné na ladenie a sledovanie.

error: vyskytla sa chyba

Ak sa niečo pokazí, server odošle chybovú správu:

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

Úplný tok komunikácie

Takto vyzerá typická relácia:

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

Server môže začať odosielať správy audio.delta skôr, než vôbec odošleš text.done. To je celá pointa streamovania: generovanie začína čo najskôr.

Kompletná implementácia v Pythone

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:
        # Odoslanie textu v častiach po 2 000 znakoch
        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
            }))

        # Signalizácia konca textu
        await ws.send(json.dumps({"type": "text.done"}))

        # Prijatie častí zvuku
        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']}")

    # Zloženie kompletného zvuku
    return b"".join(audio_chunks)

Implementácia v JavaScripte (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", () => {
      // Odoslanie textu
      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);
  });
}

Spracovanie viacerých delt

Pri texte generovanom postupne (napríklad výstup LLM) pošli každý token priamo do WebSocketu 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"}))

Táto architektúra „streamovanie LLM do streamovania TTS“ ponúka najnižšiu možnú latenciu: používateľ počuje odpoveď zatiaľ čo LLM stále generuje.

Kľúčové poznatky

  • Štyri správy klienta: text.delta (odoslanie textu), text.done (koniec textu), text.clear (zrušenie) a session.update (tabuľka replace)
  • Päť správ servera: audio.delta (časť zvuku), audio.done (koniec), audio.clear (potvrdenie zrušenia), session.updated a error
  • Zvuk je v správach audio.delta zakódovaný v base64
  • Server začne generovať skôr, než prijme text.done
  • Každá textová delta je obmedzená na 60 000 znakov
  • Reťazenie streamovaného LLM do streamovaného TTS poskytuje najnižšiu latenciu