Komunikaty WebSocket: tekst i dźwięk
Na tej stronie
Zaktualizowano 3 listopada 2026 r. na podstawie strony Text to Speech od xAI: delty do 60 000 znaków, anulowanie (
text.clear,audio.clear) oraz tabela wymowy (session.update,session.updated). Źródło: Text to Speech.
Protokół komunikatów TTS
Gdy połączenie WebSocket zostanie nawiązane, komunikacja polega na wymianie komunikatów JSON. Wysyłasz tekst, a serwer odpowiada dźwiękiem zakodowanym w formacie base64. Zrozumienie tego protokołu jest kluczowe dla poprawnej implementacji strumieniowania TTS.
Komunikaty klient-serwer
Twoja aplikacja wysyła do serwera cztery typy komunikatów: text.delta i text.done dla tekstu, text.clear do anulowania oraz session.update do konfiguracji.
text.delta: wysyłanie fragmentu tekstu
Komunikat text.delta przesyła fragment tekstu do konwersji. Możesz wysyłać tekst w kolejnych częściach:
{"type": "text.delta", "delta": "Hello, and welcome to "}
{"type": "text.delta", "delta": "our presentation on speech synthesis."}
Każda delta może zawierać do 60 000 znaków, a całkowity tekst nie ma limitu długości. Serwer zaczyna generować dźwięk natychmiast, gdy zgromadzi wystarczający kontekst, aby uzyskać naturalną wymowę.
text.done: sygnał końca tekstu
Komunikat text.done informuje serwer, że zakończyłeś wysyłanie tekstu dla tej sekwencji:
{"type": "text.done"}
Po otrzymaniu tego komunikatu serwer kończy generowanie dźwięku i wysyła komunikat audio.done. Możesz wtedy rozpocząć wysyłanie nowych delt dla kolejnej sekwencji.
text.clear: anulowanie bieżącej sekwencji
text.clear anuluje bieżącą sekwencję: serwer przestaje generować dźwięk, odrzuca dane z pamięci i odpowiada komunikatem audio.clear. Połączenie jest natychmiast gotowe do obsługi następnej sekwencji bez konieczności nowego handshake WebSocket; xAI szacuje oszczędność czasu na około 600 ms dla zdalnego klienta. Jest to mechanizm przerwania („barge-in“), stosowany, gdy użytkownik wchodzi w słowo.
{"type": "text.clear"}
session.update: korekta wymowy
session.update instaluje lub zastępuje tabelę replace dla połączenia: każda fraza znaleziona w tekście jest zamieniana na swoją formę wymawianą przed syntezą, bez zmiany wysyłanego tekstu ani liczby znaków, za które jesteś obciążany. Wyślij go przed pierwszym text.delta, aby objął całe połączenie; aktualizacja otrzymana w trakcie sekwencji obowiązuje dopiero od następnej sekwencji.
{"type": "session.update", "replace": {"kubectl": "kube cuttle"}}
Komunikaty serwer-klient
Serwer odpowiada pięcioma typami komunikatów: audio.delta, audio.done i error (opisane poniżej), a także audio.clear, który potwierdza anulowanie, oraz session.updated, który zwraca aktywną tabelę replace.
audio.delta: fragment dźwięku
Komunikat audio.delta zawiera fragment dźwięku zakodowany w formacie base64:
{
"type": "audio.delta",
"delta": "SUQzBAAAAAAAI1RTU0UAAAAPAAADTGF2ZjU4Ljc2..."
}
Każda delta jest poprawnym fragmentem dźwięku, który możesz zdekodować i odtworzyć natychmiast. Delty przychodzą w miarę postępu generowania.
audio.done: zakończenie generowania
Komunikat audio.done sygnalizuje, że wygenerowano cały dźwięk dla wysłanej sekwencji tekstu:
{
"type": "audio.done",
"trace_id": "550e8400-e29b-41d4-a716-446655440000"
}
trace_id to unikalny identyfikator sekwencji, przydatny do debugowania i śledzenia.
error: wystąpił błąd
Jeśli coś pójdzie nie tak, serwer wysyła komunikat o błędzie:
{
"type": "error",
"message": "Invalid text encoding"
}
Pełny przepływ komunikacji
Oto jak wygląda typowa sesja:
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 ----------------|
Serwer może zacząć wysyłać komunikaty audio.delta, zanim jeszcze wyślesz text.done. Na tym właśnie polega idea strumieniowania: generowanie zaczyna się tak szybko, jak to możliwe.
Kompletna implementacja w Pythonie
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:
# Wysyłaj tekst w kawałkach po 2000 znaków
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
}))
# Sygnalizuj koniec tekstu
await ws.send(json.dumps({"type": "text.done"}))
# Odbieraj fragmenty dźwięku
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']}")
# Złóż pełny dźwięk
return b"".join(audio_chunks)
Implementacja w JavaScript (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", () => {
// Wyślij 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);
});
}
Obsługa wielu delt
W przypadku tekstu generowanego stopniowo (np. wyjście modelu LLM), wysyłaj każdy token bezpośrednio do 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"}))
Taka architektura „strumieniowanie LLM do strumieniowania TTS“ zapewnia najmniejsze możliwe opóźnienia: użytkownik słyszy odpowiedź, gdy model LLM wciąż ją generuje.
Kluczowe wnioski
- Cztery komunikaty klienta:
text.delta(wyślij tekst),text.done(koniec tekstu),text.clear(anuluj) isession.update(tabelareplace) - Pięć komunikatów serwera:
audio.delta(fragment dźwięku),audio.done(koniec),audio.clear(potwierdzenie anulowania),session.updatedierror - Dźwięk w komunikatach
audio.deltajest zakodowany w formacie base64 - Serwer zaczyna generowanie przed otrzymaniem
text.done - Każda delta tekstu jest ograniczona do 60 000 znaków
- Połączenie strumieniowego LLM ze strumieniowym TTS daje najniższe opóźnienia