Prejsť na hlavný obsah
Slovenčina— Vyberte jazyk
Menu

Streamovanie TTS cez WebSocket

Lekcia 9 z 14 Aktualizované 3. novembra 2026 Mierne pokročilý
Na tejto strane
  1. Prečo streamovanie mení zážitok
  2. Otvorenie pripojenia
  3. Protokol správ
  4. Kompletná implementácia
  5. Limity, ktoré treba poznať
  6. HTTP alebo WebSocket
  7. Kľúčové poznatky

Aktualizované 3. novembra 2026 na základe stránky xAI Text to Speech. Zdroj: Text to Speech.

Prečo streamovanie mení zážitok

V režime HTTP ti TTS vráti kontrolu až po vygenerovaní celého zvuku. Pri dvojsvetovej notifikácii si nikto čakanie nevšimne. Pri blogovom príspevku, kapitole knihy alebo neustále sa posúvajúcom spravodajskom feede sa však čakanie stane najväčšou chybou tvojho produktu: používatelia kliknú a potom niekoľko sekúnd hľadia na točiace sa indikátor načítania.

Režim WebSocket toto čakanie odstraňuje tým, že posiela zvuk hneď, ako sa syntetizuje. Prehrávanie začína pri prvých slovách, zatiaľ čo koniec textu ešte nebol spracovaný. To je rozdiel medzi stránkou, ktorá vyzerá zamrznuto, a zvukom, ktorý sa prehráva okamžite.

Otvorenie pripojenia

Pripojenie sa otvára na adrese wss://api.x.ai/v1/tts a celá konfigurácia ide do reťazca dotazu URL namiesto do inicializačnej sprá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
    }
  }
);

Toto sú akceptované parametre:

  • language (povinné): kód BCP-47 alebo auto
  • voice (voliteľné, predvolené: eve): ID hlasu
  • codec (voliteľné, predvolené: mp3): výstupný formát zvuku
  • sample_rate (voliteľné, predvolené: 24000): vzorkovacia frekvencia v Hz
  • bit_rate (voliteľné, predvolené: 128000): bitová rýchlosť v bps (len pre MP3)

Tieto nastavenia platia pre celú reláciu: hlas ani kodek nemôžeš počas nej meniť. Ak tvoja aplikácia potrebuje striedať dvoch rozprávačov, otvor dve pripojenia.

Protokol správ

Na strane odosielania ti na riadenie syntézy stačia dve správy. Prvá odosiela časť textu; druhá oznamuje, že text je kompletný.

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

Môžeš odoslať toľko správ text.delta, koľko potrebuješ, každú až do 60 000 znakov. Stále je však lepšie tento limit nevyčerpávať: rozdelenie textu na časti po niekoľkých vetách ti zabezpečí oveľa rýchlejšie doručenie prvého zvukového úseku, čo je celý zmysel streamovania. Jediná delta s niekoľkými tisíckami znakov ťa vráti späť k správaniu v režime HTTP.

Na strane prijímania každá správa audio.delta nesie fragment zvuku zakódovaného v base64 v kodeku, ktorý si nastavil pri pripojení. Dekóduj ho a pripoj do vyrovnávacej pamäte prehrávania.

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

Udalosť audio.done označuje koniec syntézy. Jej trace_id je identifikátor, ktorý máš uviesť podpore alebo zaznamenať do svojich logov, keď sa generovanie správa nesprávne. Ak je text neplatný alebo si prekročil svoju kvótu, namiesto toho dostaneš chybovú správu.

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

Kompletná implementácia

Príklad nižšie rozdeľuje dlhý text na odseky, všetky ich odošle a následne zostaví prijaté zvukové fragmenty do súboru 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 para + " ": bez tejto medzery by koniec jedného odseku prebehol do začiatku ďalšieho a engine by prečítal obe slová spolu bez nadýchnutia.

Limity, ktoré treba poznať

MetrikaHodnota
Text na deltumax. 60 000 znakov
Celkový textNeobmedzený
Súčasné relácie50 na tím
Povolenie relácie600 sekúnd
Časový limit pripojeniaŽiadny

Stránka xAI uvádza, že pripojenie nemá žiadny časový limit, a samostatne spomína „povolenie relácie“ 600 sekúnd bez vysvetlenia, čo sa stane po jeho vypršaní. Pre istotu sa pripájaj, keď máš text na odoslanie, nie pri načítaní stránky, a plánuj opätovné pripojenie. S limitom 50 súčasných relácií na tím zaobchádzaj rovnako: knižnica zvuku, ktorá konvertuje svoj katalóg na pozadí, by mala frontovať svoje úlohy namiesto otvárania dvoch sto pripojení paralelne.

HTTP alebo WebSocket

Režim HTTP je stále správnou voľbou pre krátke texty, jednorazové generovania a všade tam, kde je najdôležitejšia jednoduchosť integrácie: jedna požiadavka, jedna odpoveď, žiadny stav na správu. WebSocket je cestou vpred, keď je text dlhý, keď sa zvuk musí prehrávať počas jeho tvorby alebo keď samotný obsah prichádza ako stream, typicky ako výstup jazykového modelu, ktorý nahlasuješ počas jeho generovania.

Kľúčové poznatky

  • TTS cez WebSocket ti umožňuje prijímať streamovaný zvuk bez čakania na dokončenie generovania
  • Konfiguračné parametre idú do reťazca dotazu URL pripojenia
  • Protokol je jednoduchý: text.delta na odoslanie textu, audio.delta na prijatie zvuku
  • Relácie WebSocket sú obmedzené na 50 súčasných na tím; plánuj opätovné pripojenie
  • Uprednostni WebSocket pre dlhé texty a zážitky z počúvania v reálnom čase