Správy WebSocket: text a zvuk
Na tejto strane
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) asession.update(tabuľkareplace) - Päť správ servera:
audio.delta(časť zvuku),audio.done(koniec),audio.clear(potvrdenie zrušenia),session.updatedaerror - Zvuk je v správach
audio.deltazakó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