Przejdź do głównej treści
Polski— Wybierz język
Menu

Komunikaty WebSocket: tekst i dźwięk

Lekcja 10 z 14 Zaktualizowano 3 listopada 2026 Programista
Na tej stronie
  1. Protokół komunikatów TTS
  2. Komunikaty klient-serwer
  3. Komunikaty serwer-klient
  4. Pełny przepływ komunikacji
  5. Kompletna implementacja w Pythonie
  6. Implementacja w JavaScript (Node.js)
  7. Obsługa wielu delt
  8. Kluczowe wnioski

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) i session.update (tabela replace)
  • Pięć komunikatów serwera: audio.delta (fragment dźwięku), audio.done (koniec), audio.clear (potwierdzenie anulowania), session.updated i error
  • Dźwięk w komunikatach audio.delta jest 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