Přejít na hlavní obsah
Čeština— Vyberte jazyk
Menu

Streamování TTS přes WebSocket

Lekce 9 z 14 Aktualizováno 3. listopadu 2026 Mírně pokročilý
Na této stránce
  1. Proč streamování mění zážitek
  2. Otevření připojení
  3. Protokol zpráv
  4. Kompletní implementace
  5. Limity, které musíš znát
  6. HTTP nebo WebSocket
  7. Klíčové poznatky

Aktualizováno 3. listopadu 2026 na základě stránky xAI Text to Speech. Zdroj: Text to Speech.

Proč streamování mění zážitek

V režimu HTTP předá TTS řízení zpět až poté, co je vygenerováno celé audio. U dvouvěté notifikace si nikdo čekání nevšimne. U blogového příspěvku, kapitoly knihy nebo neustále se scrolujícího zpravodajského feedu se však čekání stane největší slabinou tvého produktu: uživatelé kliknou a pak několik sekund zírají na točící se indikátor načítání.

Režim WebSocket toto čekání odstraňuje tím, že audio odesílá průběžně, jakmile je syntetizováno. Přehrávání začíná u prvních slov, zatímco konec textu ještě nebyl zpracován. To je rozdíl mezi stránkou, která vypadá, že zamrzla, a audiem, které se přehraje okamžitě.

Otevření připojení

Připojení se otevírá na adrese wss://api.x.ai/v1/tts a veškerá konfigurace patří do řetězce dotazů (query string) v URL, nikoliv do inicializační zprávy.

const ws = new WebSocket(
  "wss://api.x.ai/v1/tts?language=en&voice=ara&codec=mp3&sample_rate=24000",
  {
    headers: {
      "Authorization": "Bearer " + XAI_API_KEY
    }
  }
);

Zde jsou přijímané parametry:

  • language (povinné): kód BCP-47 nebo auto
  • voice (volitelné, výchozí: eve): ID hlasu
  • codec (volitelné, výchozí: mp3): výstupní audio formát
  • sample_rate (volitelné, výchozí: 24000): vzorkovací frekvence v Hz
  • bit_rate (volitelné, výchozí: 128000): datový tok v bps (pouze MP3)

Tato nastavení platí pro celou relaci: hlas ani codec nemůžeš během běhu měnit. Pokud tvoje aplikace potřebuje střídat dva vypravěče, otevři dvě samostatná připojení.

Protokol zpráv

Na straně odesílatele stačí k řízení syntézy pouze dva typy zpráv. První odešle část textu, druhá oznámí, že text je kompletní.

{ "type": "text.delta", "delta": "Hello and welcome " }
{ "type": "text.done" }

Můžeš odeslat libovolný počet zpráv text.delta, každá až o délce 60 000 znaků. Přesto je lepší tento limit nevyčerpávat: rozdělení textu na úseky o několika větách zajistí, že první část audia dorazí mnohem dříve, což je celý smysl streamování. Jediná delta o několika tisících znacích tě vrátí zpět k chování režimu HTTP.

Na straně příjemce každá zpráva audio.delta nese fragment audia zakódovaného v base64 ve formátu codec, který jsi nastavil při připojení. Dekóduj jej a připoj do své vyrovnávací paměti pro přehrávání.

{ "type": "audio.delta", "delta": "<base64 audio>" }
{ "type": "audio.done", "trace_id": "trace-uuid" }

Událost audio.done označuje konec syntézy. Její trace_id je identifikátor, který poskytneš podpoře nebo zaznamenáš do svých logů, pokud generování nefunguje správně. Pokud je text neplatný nebo jsi překročil svou kvótu, obdržíš místo toho chybovou zprávu.

{ "type": "error", "message": "description of the error" }

Kompletní implementace

Níže uvedený příklad rozdělí dlouhý text na odstavce, všechny je odešle a následně sestaví přijaté fragmenty audia do souboru MP3.

const WebSocket = require("ws");
const fs = require("fs");

const ws = new WebSocket(
  "wss://api.x.ai/v1/tts?language=en&voice=rex&codec=mp3",
  { headers: { "Authorization": "Bearer " + process.env.XAI_API_KEY } }
);

const audioChunks = [];

ws.on("open", () => {
  const paragraphs = longText.split("\n\n");
  for (const para of paragraphs) {
    ws.send(JSON.stringify({
      type: "text.delta",
      delta: para + " "
    }));
  }
  ws.send(JSON.stringify({ type: "text.done" }));
});

ws.on("message", (data) => {
  const msg = JSON.parse(data);
  if (msg.type === "audio.delta") {
    audioChunks.push(Buffer.from(msg.delta, "base64"));
  } else if (msg.type === "audio.done") {
    fs.writeFileSync("output.mp3", Buffer.concat(audioChunks));
    ws.close();
  }
});

Všimni si části para + " ": bez této mezery by konec jednoho odstavce naběhl přímo na začátek dalšího a engine by přečetl obě slova dohromady bez nadechnutí.

Limity, které musíš znát

MetrikaHodnota
Text na deltumax. 60 000 znaků
Celkový textNeomezený
Souběžné relace50 na tým
Povolení relace600 sekund
Časový limit připojeníŽádný

Stránka xAI uvádí, že připojení nemá žádný časový limit, a samostatně zmiňuje „povolení relace“ (session permit) v délce 600 sekund, aniž by vysvětlovala, co se stane po jeho vypršení. Pro jistotu se připojuj až ve chvíli, kdy máš text k odeslání, nikoliv při načtení stránky, a počítej s opětovným připojením. Stejným způsobem plánuj i kolem limitu 50 souběžných relací na tým: audio knihovna, která na pozadí převádí svůj katalog, by měla frontovat své úlohy, místo aby otevírala dvě stě připojení paralelně.

HTTP nebo WebSocket

Režim HTTP je stále tou správnou volbou pro krátké texty, jednorázová generování a všude tam, kde záleží především na jednoduchosti integrace: jeden požadavek, jedna odpověď, žádný stav k udržování. WebSocket je cestou, kterou se vydat, jakmile je text dlouhý, když se musí audio přehrávat během jeho tvorby, nebo když samotný obsah přichází jako stream – typicky jako výstup jazykového modelu, který dabuješ během generování.

Klíčové poznatky

  • TTS přes WebSocket ti umožňuje přijímat streamované audio bez čekání na dokončení generování
  • Konfigurační parametry patří do řetězce dotazů v URL připojení
  • Protokol je jednoduchý: text.delta pro odeslání textu, audio.delta pro přijetí audia
  • Relace WebSocket jsou omezeny na 50 souběžných na tým; počítej s opětovným připojením
  • Pro dlouhé texty a zážitky z poslechu v reálném čase upřednostni WebSocket