Přejít na hlavní obsah
Čeština— Vyberte jazyk
Menu

Zprávy WebSocket: text a zvuk

Lekce 10 z 14 Aktualizováno 3. listopadu 2026 Vývojář
Na této stránce
  1. Protokol zpráv TTS
  2. Zprávy od klienta k serveru
  3. Zprávy od serveru ke klientovi
  4. Kompletní tok komunikace
  5. Kompletní implementace v Pythonu
  6. Implementace v JavaScriptu (Node.js)
  7. Zpracování mnoha delt
  8. Klíčové poznatky

Aktualizováno 3. listopadu 2026 na základě stránky xAI Text to Speech: delty až do 60 000 znaků, zrušení (text.clear, audio.clear) a tabulka výslovnosti (session.update, session.updated). Zdroj: Text to Speech.

Protokol zpráv TTS

Jakmile je připojení WebSocket otevřené, komunikace probíhá výměnou zpráv ve formátu JSON. Ty posíláš text a server odpovídá zvukem zakódovaným v base64. Pochopení tohoto protokolu je zásadní pro správnou implementaci streamování TTS.

Zprávy od klienta k serveru

Tvoje aplikace odesílá serveru čtyři typy zpráv: text.delta a text.done pro text, text.clear pro zrušení a session.update pro konfiguraci.

text.delta: odeslání části textu

Zpráva text.delta odešle fragment textu ke konverzi. Text můžeš posílat v postupných částech:

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

Každá delta může obsahovat až 60 000 znaků a celkový text nemá žádný limit. Server začne generovat zvuk, jakmile má dostatečný kontext pro vytvoření přirozené výslovnosti.

text.done: signalizace konce textu

Zpráva text.done sděluje serveru, že jsi pro tuto sekvenci dokončil odesílání textu:

{"type": "text.done"}

Jakmile server tuto zprávu obdrží, dokončí generování zvuku a odešle zprávu audio.done. Poté můžeš začít odesílat nové delty pro novou sekvenci.

text.clear: zrušení aktuální sekvence

text.clear zruší aktuální sekvenci: server přestane generovat zvuk, zahodí data v paměti a odpoví zprávou audio.clear. Připojení je okamžitě připraveno pro další sekvenci bez nutnosti nového handshake WebSocket; xAI odhaduje úsporu času na přibližně 600 ms pro vzdálené klienty. Jedná se o mechanismus přerušení („barge-in“) pro situace, kdy uživatel vstoupí do řeči.

{"type": "text.clear"}

session.update: oprava výslovnosti

session.update nainstaluje nebo nahradí tabulku replace pro připojení: každá fráze nalezená v textu je před syntézou nahrazena svou mluvenou formou, aniž by se změnil odesílaný text nebo počet znaků, za které se účtuje. Odešli ji před první zprávou text.delta, aby pokryla celé připojení; aktualizace přijatá uprostřed sekvence se projeví až od další sekvence.

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

Zprávy od serveru ke klientovi

Server odpovídá pěti typy zpráv: audio.delta, audio.done a error, které jsou podrobně popsány níže, dále audio.clear, který potvrzuje zrušení, a session.updated, který vrací aktivní tabulku replace.

audio.delta: část zvuku

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

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

Každá delta je platnou částí zvuku, kterou můžeš okamžitě dekódovat a přehrát. Delty přicházejí v průběhu generování.

audio.done: generování dokončeno

Zpráva audio.done signalizuje, že byl vygenerován veškerý zvuk pro sekvenci textu, kterou jsi odeslal:

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

trace_id je jedinečné ID pro sekvenci, užitečné pro ladění a sledování.

error: došlo k chybě

Pokud se něco pokazí, server odešle chybovou zprávu:

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

Kompletní tok komunikace

Zde je průběh typické relace:

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čít odesílat zprávy audio.delta dříve, než vůbec odešleš text.done. To je celá podstata streamování: generování začíná co nejdříve.

Kompletní implementace 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:
        # Odeslání textu po částech po 2 000 znacích
        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
            }))

        # Signalizace konce textu
        await ws.send(json.dumps({"type": "text.done"}))

        # Příjem částí 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']}")

    # Sestavení kompletního zvuku
    return b"".join(audio_chunks)

Implementace 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", () => {
      // Odeslání 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);
  });
}

Zpracování mnoha delt

Pro text generovaný postupně (například výstup LLM) odešli každý token přímo 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"}))

Tato architektura „streamování LLM do streamovaného TTS“ nabízí nejnižší možnou latenci: uživatel slyší odpověď, zatímco LLM stále generuje.

Klíčové poznatky

  • Čtyři zprávy klienta: text.delta (odeslání textu), text.done (konec textu), text.clear (zrušení) a session.update (tabulka replace)
  • Pět zpráv serveru: audio.delta (část zvuku), audio.done (konec), audio.clear (potvrzení zrušení), session.updated a error
  • Zvuk je ve zprávách audio.delta zakódován v base64
  • Server začne generovat dříve, než obdrží text.done
  • Každá textová delta je omezena na 60 000 znaků
  • Řetězení streamovaného LLM do streamovaného TTS poskytuje nejnižší latenci