Preskoči na glavni sadržaj
Hrvatski— Odaberite jezik
Izbornik

Poruke WebSocketa: tekst i zvuk

Lekcija 10 od 14 Ažurirano 3. studenoga 2026. Programer
Na ovoj stranici
  1. Protokol poruka za TTS
  2. Poruke od klijenta prema poslužitelju
  3. Poruke od poslužitelja prema klijentu
  4. Potpuni tijek komunikacije
  5. Potpuna implementacija u Pythonu
  6. Implementacija u JavaScriptu (Node.js)
  7. Rukovanje s mnogo delta
  8. Ključne točke

Ažurirano 3. studenoga 2026., na temelju stranice xAI Text to Speech: delte do 60.000 znakova, otkazivanje (text.clear, audio.clear) i tablica izgovora (session.update, session.updated). Izvor: Text to Speech.

Protokol poruka za TTS

Čim se WebSocket veza uspostavi, komunikacija funkcionira razmjenom JSON poruka. Ti šalješ tekst, a poslužitelj odgovara zvukom kodiranim u base64 formatu. Razumijevanje ovog protokola ključno je za ispravnu implementaciju strujanja TTS-a.

Poruke od klijenta prema poslužitelju

Tvoja aplikacija šalje četiri vrste poruka poslužitelju: text.delta i text.done za tekst, text.clear za otkazivanje te session.update za konfiguraciju.

text.delta: slanje dijela teksta

Poruka text.delta šalje fragment teksta na pretvorbu. Tekst možeš slati u uzastopnim dijelovima:

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

Svaka delta može sadržavati do 60.000 znakova, a ukupni tekst nema ograničenje. Poslužitelj počinje generirati zvuk čim ima dovoljno konteksta za prirodan izgovor.

text.done: signaliziranje kraja teksta

Poruka text.done obavještava poslužitelj da si završio slati tekst za ovaj slijed:

{"type": "text.done"}

Čim poslužitelj primi ovu poruku, dovršava generiranje zvuka i šalje poruku audio.done. Nakon toga možeš početi slati nove delte za novi slijed.

text.clear: otkazivanje trenutnog slijeda

text.clear otkazuje trenutni slijed: poslužitelj prestaje generirati zvuk, odbacuje ono što je imao u memoriji i odgovara s audio.clear. Veza je odmah spremna za sljedeći slijed, bez novog WebSocket rukovanja; xAI procjenjuje uštedu na oko 600 ms za udaljene klijente. To je mehanizam prekida („barge-in“) za trenutke kada korisnik upadne u riječ.

{"type": "text.clear"}

session.update: ispravljanje izgovora

session.update instalira ili zamjenjuje tablicu replace za vezu: svaka fraza pronađena u tekstu zamjenjuje se svojim govornim oblikom prije sinteze, bez promjene teksta koji šalješ ili broja znakova za koje se naplaćuje. Pošalji je prije prve text.delta kako bi pokrila cijelu vezu; ažuriranje primljeno usred slijeda vrijedi tek od sljedećeg slijeda.

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

Poruke od poslužitelja prema klijentu

Poslužitelj odgovara s pet vrsta poruka: audio.delta, audio.done i error, koje su detaljno opisane u nastavku, plus audio.clear, koja potvrđuje otkazivanje, te session.updated, koja vraća aktivnu tablicu replace.

audio.delta: dio zvuka

Poruka audio.delta sadrži fragment zvuka kodiran u base64 formatu:

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

Svaka delta je valjani dio zvuka koji možeš odmah dekodirati i reproducirati. Delte pristižu kako generiranje napreduje.

audio.done: generiranje završeno

Poruka audio.done signalizira da je sav zvuk za tekstualni slijed koji si poslao generiran:

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

trace_id je jedinstveni ID za slijed, koristan za otklanjanje pogrešaka i praćenje.

error: dogodila se pogreška

Ako nešto pođe po zlu, poslužitelj šalje poruku o pogrešci:

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

Potpuni tijek komunikacije

Evo kako tipična sesija izgleda:

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

Poslužitelj može početi slati poruke audio.delta prije nego što si uopće poslao text.done. U tome i jest cijela poanta strujanja: generiranje počinje što je ranije moguće.

Potpuna implementacija u 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 u 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);
  });
}

Rukovanje s mnogo delta

Za tekst koji se generira progresivno (npr. izlaz LLM-a), pošalji svaki token izravno na TTS WebSocket:

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

Ova arhitektura „strujanja LLM-a u strujanje TTS-a“ nudi najnižu moguću latenciju: korisnik čuje odgovor dok LLM još uvijek generira sadržaj.

Ključne točke

  • Četiri klijentske poruke: text.delta (slanje teksta), text.done (kraj teksta), text.clear (otkazivanje) i session.update (tablica replace)
  • Pet poslužiteljskih poruka: audio.delta (dio zvuka), audio.done (kraj), audio.clear (potvrda otkazivanja), session.updated i error
  • Zvuk je kodiran u base64 formatu unutar poruka audio.delta
  • Poslužitelj počinje generirati prije nego što primi text.done
  • Svaka tekstualna delta ograničena je na 60.000 znakova
  • Lančano povezivanje strujanja LLM-a sa strujanjem TTS-a daje najnižu latenciju