Preskoči na glavni sadržaj
Hrvatski— Odaberite jezik
Izbornik

Streaming TTS preko WebSocketa

Lekcija 9 od 14 Ažurirano 3. studenoga 2026. Srednja razina
Na ovoj stranici
  1. Zašto streaming mijenja iskustvo
  2. Otvaranje veze
  3. Protokol poruka
  4. Potpuna implementacija
  5. Ograničenja koja trebaš znati
  6. HTTP ili WebSocket
  7. Ključne točke

Ažurirano 3. studenog 2026., na temelju stranice xAI Text to Speech. Izvor: Text to Speech.

Zašto streaming mijenja iskustvo

U HTTP načinu rada, TTS vraća kontrolu tek nakon što se proizvede cijeli audio zapis. Za obavijest od dvije rečenice, nitko ne primijeti čekanje. Za blog post, poglavlje knjige ili neprekidno klizajući feed vijesti, to čekanje postaje najveći nedostatak tvog proizvoda: korisnici kliknu, a zatim nekoliko sekundi zure u vrteći se indikator učitavanja.

Način rada putem WebSocketa uklanja to čekanje gurajući audio podatke čim se sintetiziraju. Reprodukcija počinje s prvim riječima dok kraj teksta još nije ni obrađen. To je razlika između stranice koja djeluje smrznuto i audio zapisa koji se reproducira odmah.

Otvaranje veze

Veza se otvara na wss://api.x.ai/v1/tts, a sva konfiguracija ide u upitni niz (query string) URL-a, a ne u poruku za inicijalizaciju.

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

Ovo su prihvaćeni parametri:

  • language (obavezno): BCP-47 kod ili auto
  • voice (opcionalno, zadano: eve): ID glasa
  • codec (opcionalno, zadano: mp3): izlazni audio format
  • sample_rate (opcionalno, zadano: 24000): frekvencija uzorkovanja u Hz
  • bit_rate (opcionalno, zadano: 128000): brzina prijenosa u bps (samo za MP3)

Ove postavke vrijede za cijelu sesiju: ne možeš mijenjati glas ili codec usred procesa. Ako tvoja aplikacija treba izmjenjivati dva naratora, otvori dvije odvojene veze.

Protokol poruka

Na strani slanja potrebne su ti samo dvije vrste poruka za pokretanje sinteze. Prva šalje dio teksta; druga najavljuje da je tekst završen.

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

Možeš poslati koliko god text.delta poruka trebaš, svaka do 60.000 znakova. Ipak, bolje je ne iscrpljivati to ograničenje: dijeljenje teksta na odlomke od nekoliko rečenica omogućuje da ti prvi audio isječak stigne mnogo brže, što je i sama svrha streaminga. Jedan delta od nekoliko tisuća znakova vraća te na ponašanje karakteristično za HTTP način rada.

Na strani primanja, svaki audio.delta nosi fragment audio zapisa kodiranog u base64, u codec-u koji si postavio pri povezivanju. Dekodiraj ga i dodaj u svoj međuspremnik za reprodukciju.

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

Događaj audio.done označava kraj sinteze. Njegov trace_id je identifikator koji daješ podršci ili bilježiš u svoje logove kada generiranje ne radi kako treba. Ako je tekst neispravan ili si premašio kvotu, umjesto toga dobivaš poruku o pogrešci.

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

Potpuna implementacija

Primjer u nastavku dijeli dugi tekst na odlomke, šalje ih sve, a zatim sastavlja primljene audio fragmente u MP3 datoteku.

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

Obrati pažnju na para + " ": bez tog razmaka, kraj jednog odlomka se stapa s početkom sljedećeg, pa motor čita te dvije riječi zajedno, bez daha.

Ograničenja koja trebaš znati

MetrikaVrijednost
Tekst po delta porucimaks. 60.000 znakova
Ukupno tekstaNeograničeno
Istovremene sesije50 po timu
Dozvola za sesiju600 sekundi
Istek veze (timeout)Nema

Stranica xAI navodi da veza nema vremensko ograničenje (timeout), a zasebno spominje „dozvolu za sesiju“ od 600 sekundi, ne objašnjavajući što se događa kada istekne. Radi sigurnosti, poveži se kada imaš tekst za slanje, a ne pri učitavanju stranice, i planiraj ponovno povezivanje. Na isti se način nosi s ograničenjem od 50 istovremenih sesija po timu: audio biblioteka koja u pozadini konvertira svoj katalog trebala bi stavljati zadatke u red čekanja, umjesto da otvori dvjesto veza paralelno.

HTTP ili WebSocket

HTTP način rada i dalje je pravi izbor za kratke tekstove, jednokratna generiranja i svugdje gdje je jednostavnost integracije najvažnija: jedan zahtjev, jedan odgovor, bez upravljanja stanjem. WebSocket je pravi put kada tekst postane dug, kada se audio mora reproducirati dok se proizvodi ili kada sam sadržaj stiže kao stream, što je tipično izlaz jezičnog modela kojem daješ glas dok generira.

Ključne točke

  • WebSocket TTS omogućuje primanje streamanog audio zapisa bez čekanja da generiranje završi
  • Parametri konfiguracije idu u upitni niz URL-a veze
  • Protokol je jednostavan: text.delta za slanje teksta, audio.delta za primanje audia
  • WebSocket sesije ograničene su na 50 istovremenih po timu; planiraj ponovno povezivanje
  • Preferiraj WebSocket za duge tekstove i iskustva slušanja u stvarnom vremenu