Lähe põhisisu juurde
Eesti— Vali keel
Menüü

WebSocketi sõnumid: tekst ja heli

Õppetund 10 / 14 Värskendatud 3. november 2026 Arendajatele
Sellel lehel
  1. TTSi sõnumiprotokoll
  2. Kliendilt serverile sõnumid
  3. Serverilt kliendile sõnumid
  4. Täielik suhtlusvoog
  5. Täielik rakendus Pythonis
  6. Rakendus JavaScriptis (Node.js)
  7. Mitme delta haldamine
  8. Peamised punktid

Uuendatud 3. novembril 2026, tuginedes xAI Text to Speech lehele: deltad kuni 60 000 tähemärki, tühistamine (text.clear, audio.clear) ja hääldustabel (session.update, session.updated). Allikas: Text to Speech.

TTSi sõnumiprotokoll

Kui WebSocketi ühendus on avatud, toimub suhtlus JSON-sõnumite vahetamise teel. Sa saadad teksti ja server vastab base64-kodeeritud heliga. Selle protokolli mõistmine on hädavajalik TTSi voogedastuse korrektseks rakendamiseks.

Kliendilt serverile sõnumid

Sinu rakendus saadab serverile nelja tüüpi sõnumeid: text.delta ja text.done teksti jaoks, text.clear tühistamiseks ning session.update seadistamiseks.

text.delta: tekstiosa saatmine

Sõnum text.delta saadab serverile teisendamiseks tekstifragmendi. Saad teksti saata järjestikuste tükkidena:

{"type": "text.delta", "delta": "Tere tulemast "}
{"type": "text.delta", "delta": "meie kõnesünteesi esitlusele."}

Iga delta võib sisaldada kuni 60 000 tähemärki ja kogu tekstil pole pikkusepiirangut. Server alustab heli genereerimist niipea, kui tal on loomuliku häälduse jaoks piisavalt konteksti.

text.done: teksti lõpu märkimine

Sõnum text.done annab serverile teada, et oled selle jada jaoks teksti saatmise lõpetanud:

{"type": "text.done"}

Kui server selle sõnumi kätte saab, lõpetab ta heli genereerimise ja saadab sõnumi audio.done. Seejärel saad alustada uute deltade saatmist uue jada jaoks.

text.clear: praeguse jada tühistamine

text.clear tühistab praeguse jada: server lõpetab heli genereerimise, kustutab mälus oleva ja vastab sõnumiga audio.clear. Ühendus on koheselt valmis järgmiseks jadaks, ilma uue WebSocketi käepigistuseta; xAI hinnangul säästab see kaugel asuva kliendi puhul umbes 600 ms. See on katkestusmehhanism („barge-in“) juhuks, kui kasutaja sekeldab vahele.

{"type": "text.clear"}

session.update: häälduse parandamine

session.update paigaldab või asendab ühenduse replace-tabeli: iga tekstist leitud fraas asendatakse enne sünteesi selle kõnevormiga, muutmata sinu saadetud teksti ega arveldatavate tähemärkide arvu. Saada see enne esimest text.delta, et see hõlmaks kogu ühendust; keset jada saabunud värskendus kehtib alles järgmisest jadast alates.

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

Serverilt kliendile sõnumid

Server vastab viie tüüpi sõnumitega: audio.delta, audio.done ja error (kirjeldatud allpool), lisaks audio.clear, mis kinnitab tühistamist, ja session.updated, mis tagastab kehtiva replace-tabeli.

audio.delta: heliosa

Sõnum audio.delta sisaldab base64-kodeeritud helifragmenti:

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

Iga delta on kehtiv helitükk, mille saad kohe dekodeerida ja esitada. Deltad saabuvad genereerimise käigus.

audio.done: genereerimine lõpetatud

Sõnum audio.done annab märku, et kogu sinu saadetud tekstijada jaoks mõeldud heli on genereeritud:

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

trace_id on jada unikaalne ID, mis on kasulik silumiseks ja jälgimiseks.

error: tekkinud viga

Kui midagi läheb valesti, saadab server veateate:

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

Täielik suhtlusvoog

Nii näeb välja tüüpiline seanss:

Klient                          Server
  |                                |
  |-- text.delta ("Tere, ") ----->|
  |-- text.delta ("kuidas läheb ") ---->|
  |-- text.delta ("sul?") -------->|
  |<-- audio.delta (tükk 1) -----|
  |<-- audio.delta (tükk 2) -----|
  |-- text.done ----------------->|
  |<-- audio.delta (tükk 3) -----|
  |<-- audio.done ----------------|

Server võib hakata saatma sõnumeid audio.delta enne, kui oled isegi saatnud text.done. See ongi voogedastuse mõte: genereerimine algab nii kiiresti kui võimalik.

Täielik rakendus Pythonis

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:
        # Saada tekst 2000 tähemärgi kaupa
        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
            }))

        # Märgi teksti lõpp
        await ws.send(json.dumps({"type": "text.done"}))

        # Võta vastu helitükid
        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"Genereerimine lõpetatud (jälg: {data['trace_id']})")
                break

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

    # Koosta täielik helifail
    return b"".join(audio_chunks)

Rakendus JavaScriptis (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", () => {
      // Saada tekst
      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);
  });
}

Mitme delta haldamine

Järk-järgult genereeritava teksti (näiteks LLM-i väljundi) korral saada iga token otse TTSi WebSocketisse:

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

See „voogedastatava LLM-i ühendamine voogedastatava TTSiga“ arhitektuur pakub võimalikult väikest latentsust: kasutaja kuuleb vastust samal ajal, kui LLM seda veel genereerib.

Peamised punktid

  • Neli kliendi sõnumit: text.delta (saada tekst), text.done (teksti lõpp), text.clear (tühistamine) ja session.update (replace-tabel)
  • Viis serveri sõnumit: audio.delta (heliosa), audio.done (lõpp), audio.clear (tühistamine kinnitatud), session.updated ja error
  • Heli on sõnumites audio.delta base64-kodeeritud
  • Server alustab genereerimist enne, kui saab sõnumi text.done
  • Iga tekstidelta on piiratud 60 000 tähemärgiga
  • Voogedastatava LLM-i ühendamine voogedastatava TTSiga annab väikseima latentsuse