Sporočila WebSocket: besedilo in zvok
Na tej strani
Posodobljeno 3. novembra 2026 na podlagi strani xAI Text to Speech: delte do 60.000 znakov, preklic (
text.clear,audio.clear) in tabela izgovorjave (session.update,session.updated). Vir: Text to Speech.
Protokol sporočil TTS
Ko je povezava WebSocket vzpostavljena, komunikacija poteka z izmenjavo sporočil JSON. Ti pošlješ besedilo, strežnik pa odgovori z zvočnimi podatki, kodiranimi v base64. Razumevanje tega protokola je ključno za pravilno implementacijo pretakanja TTS.
Sporočila od odjemalca do strežnika
Tvoja aplikacija strežniku pošlje štiri vrste sporočil: text.delta in text.done za besedilo, text.clear za preklic ter session.update za konfiguracijo.
text.delta: pošiljanje dela besedila
Sporočilo text.delta pošlje del besedila za pretvorbo. Besedilo lahko pošlješ v zaporednih kosih:
{"type": "text.delta", "delta": "Hello, and welcome to "}
{"type": "text.delta", "delta": "our presentation on speech synthesis."}
Vsaka delta lahko vsebuje do 60.000 znakov, skupna dolžina besedila pa ni omejena. Strežnik začne generirati zvok takoj, ko ima dovolj konteksta za naravno izgovorjavo.
text.done: signalizacija konca besedila
Sporočilo text.done strežniku sporoči, da si končal s pošiljanjem besedila za to zaporedje:
{"type": "text.done"}
Ko strežnik prejme to sporočilo, dokonča generiranje zvoka in pošlje sporočilo audio.done. Nato lahko začneš pošiljati nove delte za novo zaporedje.
text.clear: preklic trenutnega zaporedja
text.clear prekliče trenutno zaporedje: strežnik ustavi generiranje zvoka, zavrže vsebino v pomnilniku in odgovori z audio.clear. Povezava je takoj pripravljena za naslednje zaporedje brez novega rokovanja WebSocket; xAI ocenjuje prihranek na približno 600 ms za oddaljene odjemalce. To je mehanizem za prekinitev („barge-in”), ko uporabnik poseže vmes.
{"type": "text.clear"}
session.update: popravek izgovorjave
session.update namesti ali nadomesti tabelo replace za povezavo: vsak stavek, najden v besedilu, se pred sintezo zamenja z njegovo govorno obliko, ne da bi se spremenilo besedilo, ki ga pošlješ, ali število zaračunanih znakov. Pošlji ga pred prvim text.delta, da zajame celotno povezavo; posodobitev, prejeta sredi zaporedja, velja šele od naslednjega zaporedja.
{"type": "session.update", "replace": {"kubectl": "kube cuttle"}}
Sporočila od strežnika do odjemalca
Strežnik odgovori s petimi vrstami sporočil: audio.delta, audio.done in error, ki so podrobneje opisani spodaj, ter audio.clear, ki potrjuje preklic, in session.updated, ki vrne veljavno tabelo replace.
audio.delta: del zvoka
Sporočilo audio.delta vsebuje del zvoka, kodiran v base64:
{
"type": "audio.delta",
"delta": "SUQzBAAAAAAAI1RTU0UAAAAPAAADTGF2ZjU4Ljc2..."
}
Vsaka delta je veljaven del zvoka, ki ga lahko takoj dekodiraš in predvajaš. Delte prihajajo med potekom generiranja.
audio.done: generiranje končano
Sporočilo audio.done signalizira, da je ves zvok za zaporedje besedila, ki si ga poslal, generiran:
{
"type": "audio.done",
"trace_id": "550e8400-e29b-41d4-a716-446655440000"
}
trace_id je edinstven ID za zaporedje, koristen za razhroščevanje in sledenje.
error: prišlo je do napake
Če kaj gre narobe, strežnik pošlje sporočilo o napaki:
{
"type": "error",
"message": "Invalid text encoding"
}
Celoten potek komunikacije
Tako običajno poteka seja:
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 ----------------|
Strežnik lahko začne pošiljati sporočila audio.delta, še preden pošlješ text.done. To je bistvo pretakanja: generiranje se začne čim prej.
Popolna implementacija 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:
# 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 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", () => {
// 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);
});
}
Obdelava več delt
Pri besedilu, ki nastaja postopoma (npr. izhod LLM), pošlji vsak žeton neposredno na WebSocket 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"}))
Ta arhitektura „pretakanje LLM v pretakanje TTS” ponuja najnižjo možno zakasnitev: uporabnik sliši odgovor, medtem ko LLM še vedno generira.
Ključne ugotovitve
- Štiri sporočila odjemalca:
text.delta(pošlji besedilo),text.done(konec besedila),text.clear(preklic) insession.update(tabelareplace) - Pet sporočil strežnika:
audio.delta(del zvoka),audio.done(konec),audio.clear(potrditev preklica),session.updatedinerror - Zvok je v sporočilih
audio.deltakodiran v base64 - Strežnik začne generirati, preden prejme
text.done - Vsaka delta besedila je omejena na 60.000 znakov
- Veriženje pretakanja LLM v pretakanje TTS zagotavlja najnižjo zakasnitev