Ugrás a főtartalomra
Magyar— Nyelv kiválasztása
Menü

TTS streamelés WebSocketen keresztül

9. lecke 14 közül Frissítve 2026. november 3. Középhaladó
Ezen az oldalon
  1. Miért változtatja meg a streamelés az élményt
  2. Kapcsolat megnyitása
  3. Az üzenetprotokoll
  4. Teljes megvalósítás
  5. Ismerendő korlátok
  6. HTTP vagy WebSocket
  7. Főbb megállapítások

Frissítve: 2026. november 3., az xAI Text to Speech oldala alapján. Forrás: Text to Speech.

Miért változtatja meg a streamelés az élményt

HTTP módban a TTS csak akkor adja vissza az irányítást, ha az összes hanganyag elkészült. Két mondatos értesítésnél senki nem veszi észre a várakozást. Viszont blogbejegyzéseknél, könyvfejezeteknél vagy folyamatosan görgetett hírfolyamoknál ez a várakozás a terméked legnagyobb hibájává válik: a felhasználók kattintanak, majd másodpercekig egy töltőanimációt bámulnak.

A WebSocket mód megszünteti ezt a várakozást azáltal, hogy szintézis közben azonnal továbbítja a hangot. A lejátszás már az első szavaknál elindul, miközben a szöveg végét még fel sem dolgozta a rendszer. Ez a különbség a befagyottnak tűnő oldal és az azonnal megszólaló hanganyag között.

Kapcsolat megnyitása

A kapcsolatot a wss://api.x.ai/v1/tts címen nyitod meg, ahol minden konfigurációt nem egy inicializáló üzenetben, hanem közvetlenül az URL lekérdezési paramétereiben (query string) adsz meg.

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
    }
  }
);

Ezek az elfogadott paraméterek:

  • language (kötelező): egy BCP-47 kód vagy az auto érték
  • voice (opcionális, alapértelmezett: eve): a hang azonosítója
  • codec (opcionális, alapértelmezett: mp3): a kimeneti hangformátum
  • sample_rate (opcionális, alapértelmezett: 24000): a mintavételezési frekvencia Hz-ben
  • bit_rate (opcionális, alapértelmezett: 128000): a bitráta bps-ben (kizárólag MP3 esetén)

Ezek a beállítások a teljes munkamenetre érvényesek: menet közben nem tudod megváltoztatni a hangot vagy a kodeket. Ha az alkalmazásodnak két különböző narrátor között kell váltogatnia, nyiss két külön kapcsolatot.

Az üzenetprotokoll

A küldő oldalon mindössze két üzenettípusra van szükséged a szintézis vezérléséhez. Az első egy szövegrészt küld, a második pedig jelzi, hogy a szöveg véget ért.

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

Annyi text.delta üzenetet küldhetsz, amennyit csak szeretnél, mindegyik maximum 60 000 karakter hosszú lehet. Ennek ellenére érdemes nem kihasználni ezt a limitet: ha néhány mondatos darabokra bontod a szöveget, sokkal hamarabb megérkezik hozzád az első hangrészlet, ami a streamelés lényege. Ha egyetlen deltában több ezer karaktert küldesz, azzal visszakerülsz a HTTP-mód viselkedéséhez.

A fogadó oldalon minden audio.delta üzenet a beállított kodeknek megfelelő, base64-kódolt hangrészletet tartalmaz. Dekódold ezt, és fűzd hozzá a lejátszási pufferhez.

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

Az audio.done esemény jelzi a szintézis végét. A benne lévő trace_id az az azonosító, amit a támogatásnak kell megadnod, vagy amit a naplóidban rögzítened kell, ha valami hiba történik a generálás során. Ha a szöveg érvénytelen, vagy túllépted a kvótádat, hibaüzenetet kapsz helyette.

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

Teljes megvalósítás

Az alábbi példa egy hosszú szöveget bekezdésekre bont, elküldi azokat, majd a kapott hangrészletekből összeállít egy MP3 fájlt.

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();
  }
});

Figyeld meg a para + " " részt: e szóköz nélkül az egyik bekezdés vége összeér a következő elejével, és a motor levegővétel nélkül, egyben olvassa fel a két szót.

Ismerendő korlátok

MetrikaÉrték
Szöveg deltánkéntmax. 60 000 karakter
Összes szövegKorlátlan
Egyidejű munkamenetek50 csapatonként
Munkamenet-engedély600 másodperc
Kapcsolat időtúllépésNincs

Az xAI dokumentációja szerint a kapcsolatnak nincs időtúllépése, de külön említ egy 600 másodperces „munkamenet-engedélyt“ anélkül, hogy tisztázná, mi történik, ha ez lejár. A biztonság kedvéért csak akkor létesíts kapcsolatot, ha van elküldendő szöveged, ne már az oldal betöltésekor, és tervezz újraconnectelést. Ugyanígy tervezd meg az csapatra vonatkozó 50 egyidejű munkamenet korlátját is: egy háttérben katalógust konvertáló hangkönyvtárnak sorba kell állítania a feladatokat, ahelyett, hogy párhuzamosan kétszáz kapcsolatot nyitna meg.

HTTP vagy WebSocket

A HTTP mód továbbra is a helyes választás rövid szövegeknél, egyszeri generálásoknál, és mindenhol, ahol az integráció egyszerűsége a legfontosabb: egy kérés, egy válasz, nincs kezelendő állapot. A WebSocket akkor jön szóba, ha a szöveg hosszú, ha a hangot gyártás közben kell lejátszani, vagy ha maga a tartalom is streamként érkezik – tipikusan egy nyelvi modell kimeneteként, amit generálás közben alakítasz hanggá.

Főbb megállapítások

  • A WebSocket alapú TTS lehetővé teszi a streamelt hangfogadást anélkül, hogy meg kellene várnod a generálás végét
  • A konfigurációs paramétereket a kapcsolati URL lekérdezési karakterláncában kell megadni
  • A protokoll egyszerű: text.delta a szöveg küldéséhez, audio.delta a hang fogadásához
  • A WebSocket munkamenetek száma csapatra vetítve 50 egyidejű kapcsolatra korlátozódik; tervezz újraconnectelést
  • Hosszú szövegeknél és valós idejű hallgatási élményeknél részesítsd előnyben a WebSocketet