Preskok na glavno vsebino
Slovenščina— Izberite jezik
Meni

Pretakanje TTS prek WebSocket

Lekcija 9 od 14 Posodobljeno 3. november 2026 Srednje napredni
Na tej strani
  1. Zakaj pretakanje spremeni uporabniško izkušnjo
  2. Vzpostavi povezavo
  3. Protokol sporočil
  4. Celotna implementacija
  5. Omejitve, ki jih moraš poznati
  6. HTTP ali WebSocket
  7. Ključne ugotovitve

Posodobljeno 3. novembra 2026 na podlagi strani xAI Text to Speech. Vir: Text to Speech.

Zakaj pretakanje spremeni uporabniško izkušnjo

V načinu HTTP prevzame TTS nadzor šele, ko je ves zvok proizveden. Pri obvestilu, dolgem dva stavka, nihče ne opazi čakanja. Pri blogu, poglavju knjige ali nenehno drsečem novičarskem viru pa čakanje postane največja pomanjkljivost tvojega izdelka: uporabniki kliknejo, nato pa nekaj sekund strmijo v vrteči se indikator nalaganja.

Način WebSocket to čakanje odpravi tako, da zvok potiska ven, ko se sintetizira. Predvajanje se začne ob prvih besedah, medtem ko konec besedila še ni obdelan. To je razlika med stranjo, ki deluje zamrznjeno, in zvokom, ki se predvaja takoj.

Vzpostavi povezavo

Povezava se odpre na naslovu wss://api.x.ai/v1/tts, vsa konfiguracija pa gre v niz poizvedbe URL-ja in ne v sporočilo za inicializacijo.

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

To so sprejeti parametri:

  • language (obvezno): koda BCP-47 ali auto
  • voice (izbirno, privzeto: eve): ID glasu
  • codec (izbirno, privzeto: mp3): izhodna zvočna oblika
  • sample_rate (izbirno, privzeto: 24000): vzorčna frekvenca v Hz
  • bit_rate (izbirno, privzeto: 128000): bitna hitrost v bps (samo za MP3)

Te nastavitve veljajo za celotno sejo: glasu ali kodeka ne moreš spreminjati med delovanjem. Če tvoja aplikacija potrebuje izmenjavo med dvema pripovedovalcema, odpri dve povezavi.

Protokol sporočil

Na strani pošiljanja potrebuješ le dve vrsti sporočil za pogon sinteze. Prvo pošlje del besedila, drugo pa naznani, da je besedilo končano.

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

Pošlješ lahko poljubno število sporočil text.delta, vsako do 60.000 znakov. Vendar je bolje, da te omejitve ne izkoristiš do konca: razdelitev besedila na dele po nekaj stavkov ti much hitreje prinese prvi zvočni del, kar je bistvo pretakanja. En sam delta z več tisoč znaki te vrne k obnašanju v načinu HTTP.

Na strani prejemanja vsak audio.delta nosi del zvoka, kodiranega v base64, v kodeku, ki si ga določil ob povezavi. Dekodiraj ga in dodaj v medpomnilnik za predvajanje.

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

Dogodek audio.done označuje konec sinteze. Njegov trace_id je identifikator, ki ga posreduješ podpori ali zapišeš v dnevnike, ko generiranje ne deluje pravilno. Če je besedilo neveljavno ali si prekoračil kvoto, namesto tega prejmeš sporočilo o napaki.

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

Celotna implementacija

Spodnji primer razdeli dolgo besedilo na odstavke, jih vse pošlje in nato sestavi prejete zvočne dele v datoteko 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();
  }
});

Upoštevaj para + " ": brez tega presledka se konec enega odstavka združi z začetkom naslednjega in pogon prebere obe besedi skupaj, brez diha.

Omejitve, ki jih moraš poznati

MetrikaVrednost
Besedilo na deltaNajveč 60.000 znakov
Skupno besediloNeomejeno
Sočasne seje50 na ekipo
Dovoljenje za sejo600 sekund
Časovna omejitev povezaveNična

Stran xAI navaja, da povezava nima časovne omejitve, ločeno pa omenja „dovoljenje za sejo” v trajanju 600 sekund, ne da bi pojasnila, kaj se zgodi, ko ta poteče. Zaradi varnosti se poveži, ko imaš besedilo za pošiljanje, in ne ob nalaganju strani, ter načrtuj ponovno povezavo. Na podoben način načrtuj tudi glede omejitve 50 sočasnih sej na ekipo: zvočna knjižnica, ki v ozadju pretvarja svoj katalog, naj vrsti opravila v čakalno vrsto, namesto da bi vzporedno odprla dvesto povezav.

HTTP ali WebSocket

Način HTTP je še vedno prava izbira za kratka besedila, enkratna generiranja in povsod tam, kjer je najpomembnejša preprostost integracije: ena zahteva, en odgovor, brez upravljanja stanja. WebSocket je prava pot, ko besedilo postane dolgo, ko se mora zvok predvajati medtem, ko nastaja, ali ko sama vsebina prihaja kot tok, kar je običajno izhod jezikovnega modela, ki ga poglasiš med generiranjem.

Ključne ugotovitve

  • TTS prek WebSocket ti omogoča prejemanje pretakanega zvoka brez čakanja na konec generiranja
  • Konfiguracijski parametri gredo v niz poizvedbe URL-ja povezave
  • Protokol je preprost: text.delta za pošiljanje besedila, audio.delta za prejemanje zvoka
  • Seje WebSocket so omejene na 50 sočasnih na ekipo; načrtuj ponovno povezavo
  • Za dolga besedila in izkušnje poslušanja v realnem času raje uporabi WebSocket