Ugrás a főtartalomra
Magyar— Nyelv kiválasztása
Menü

WebSocket-üzenetek: szöveg és hang

10. lecke 14 közül Frissítve 2026. november 3. Fejlesztő
Ezen az oldalon
  1. A TTS üzenetprotokoll
  2. Kliensről szerverre irányuló üzenetek
  3. Szerverről kliensre irányuló üzenetek
  4. A teljes kommunikációs folyamat
  5. Teljes megvalósítás Pythonban
  6. Megvalósítás JavaScriptben (Node.js)
  7. Több delta kezelése
  8. Főbb megállapítások

Frissítve: 2026. november 3., az xAI Text to Speech oldala alapján: legfeljebb 60 000 karakteres delták, megszakítás (text.clear, audio.clear) és kiejtési tábla (session.update, session.updated). Forrás: Text to Speech.

A TTS üzenetprotokoll

Miután a WebSocket-kapcsolat létrejött, a kommunikáció JSON-üzenetek cseréjével zajlik. Te küldesz szöveget, a szerver pedig base64-kódolt hanggal válaszol. Ennek a protokollnak a megértése elengedhetetlen a TTS-streamelés helyes megvalósításához.

Kliensről szerverre irányuló üzenetek

Az alkalmazásod négyféle üzenetet küld a szervernek: text.delta és text.done a szöveghez, text.clear a megszakításhoz, valamint session.update a konfiguráláshoz.

text.delta: szövegrész küldése

A text.delta üzenet egy átalakítandó szövegrészletet küld. A szöveget egymást követő darabokban is elküldheted:

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

Minden delta legfeljebb 60 000 karaktert tartalmazhat, míg a teljes szöveg hossza korlátlan. A szerver akkor kezdi el generálni a hangot, amint elegendő kontextusa van a természetes kiejtés biztosításához.

text.done: a szöveg végének jelzése

A text.done üzenet jelzi a szervernek, hogy befejezted a szöveg küldését ehhez a szekvenciához:

{"type": "text.done"}

Amint a szerver megkapja ezt az üzenetet, befejezi a hanggenerálást, és küld egy audio.done üzenetet. Ezt követően új deltákat kezdhetsz küldeni egy új szekvenciához.

text.clear: az aktuális szekvencia megszakítása

A text.clear megszakítja az aktuális szekvenciát: a szerver leállítja a hanggenerálást, eldobja a memóriában lévő adatokat, és audio.clear üzenettel válaszol. A kapcsolat azonnal készen áll a következő szekvenciára, új WebSocket-kézfogás nélkül; az xAI szerint ez távoli kliensek esetén kb. 600 ms megtakarítást jelent. Ez a megszakítási („barge-in“) mechanizmus arra az esetre, amikor a felhasználó közbeszól.

{"type": "text.clear"}

session.update: kiejtés javítása

A session.update telepíti vagy lecseréli a kapcsolat replace táblázatát: minden olyan kifejezést, amely szerepel a szövegben, a rendszer lecserél a beszélt alakjára szintézis előtt, anélkül, hogy megváltoztatná az elküldött szöveget vagy a számlázott karakterek számát. Küldd el az első text.delta előtt, hogy az egész kapcsolatra vonatkozzon; a szekvencia közben érkezett frissítés csak a következő szekvenciától lép életbe.

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

Szerverről kliensre irányuló üzenetek

A szerver ötféle üzenettel válaszol: audio.delta, audio.done és error (ezeket lentebb részletezzük), valamint audio.clear, amely megerősíti a megszakítást, illetve session.updated, amely visszaadja az érvényes replace táblázatot.

audio.delta: hangrészlet

Az audio.delta üzenet egy base64-kódolt hangrészletet tartalmaz:

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

Minden delta egy érvényes hangrészlet, amelyet azonnal dekódolhatsz és lejátszhatsz. A delták a generálás előrehaladtával érkeznek.

audio.done: a generálás befejeződött

Az audio.done üzenet jelzi, hogy az elküldött szövegszekvencia összes hangja elkészült:

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

A trace_id a szekvencia egyedi azonosítója, amely hibakereséshez és nyomon követéshez hasznos.

error: hiba történt

Ha valami hiba történik, a szerver hibaüzenetet küld:

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

A teljes kommunikációs folyamat

Így néz ki egy tipikus munkamenet:

Kliens                          Szerver
  |                                |
  |-- text.delta ("Hello, ") ----->|
  |-- text.delta ("how are ") ---->|
  |-- text.delta ("you?") -------->|
  |<-- audio.delta (1. rész) -----|
  |<-- audio.delta (2. rész) -----|
  |-- text.done ----------------->|
  |<-- audio.delta (3. rész) -----|
  |<-- audio.done ----------------|

A szerver már akkor is elkezdheti az audio.delta üzenetek küldését, mielőtt még elküldenéd a text.done üzenetet. Ez a streamelés lényege: a generálás a lehető legkorábban elindul.

Teljes megvalósítás Pythonban

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:
        # Szöveg küldése 2000 karakteres darabokban
        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
            }))

        # Szöveg végének jelzése
        await ws.send(json.dumps({"type": "text.done"}))

        # Hangrészek fogadása
        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"Generálás befejeződött (trace: {data['trace_id']})")
                break

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

    # Teljes hang összeállítása
    return b"".join(audio_chunks)

Megvalósítás JavaScriptben (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", () => {
      // Szöveg küldése
      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);
  });
}

Több delta kezelése

Folyamatosan generált szöveg (például egy LLM kimenete) esetén minden tokent azonnal küldj el a TTS WebSocketnek:

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

Ez a „streamelt LLM streamelt TTS-be“ architektúra biztosítja a lehető legalacsonyabb késleltetést: a felhasználó már akkor hallja a választ, amikor az LLM még mindig generál.

Főbb megállapítások

  • Négy kliensüzenet: text.delta (szöveg küldése), text.done (szöveg vége), text.clear (megszakítás) és session.update (replace tábla)
  • Öt szerverüzenet: audio.delta (hangrészlet), audio.done (vége), audio.clear (megszakítás megerősítve), session.updated és error
  • A hang base64-kódolva érkezik az audio.delta üzenetekben
  • A szerver a text.done fogadása előtt elkezdi a generálást
  • Minden szövegdelta legfeljebb 60 000 karakter lehet
  • Egy streamelt LLM láncolása egy streamelt TTS-hez adja a legalacsonyabb késleltetést