Aqbeż għall-kontenut ewlieni
Malti— Agħżel lingwa
Menu

Streaming TTS fuq WebSocket

Lezzjoni 9 / 14 Aġġornat 3 ta’ Novembru 2026 Livell Medju
F'din il-paġna
  1. Għaliex l-istreaming ibiddel l-esperjenza
  2. Iftaħ il-konnessjoni
  3. Il-protokoll tal-messaġġi
  4. Implimentazzjoni sħiħa
  5. Limiti li għandek tkun taf bihom
  6. HTTP jew WebSocket
  7. Punti Ewlenin

Aġġornat fit-3 ta’ Novembru, 2026, ibbażat fuq il-paġna Text to Speech ta’ xAI. Sors: Text to Speech.

Għaliex l-istreaming ibiddel l-esperjenza

Fil-modalità HTTP, is-sistema TTS tirritorna l-kontroll biss wara li l-awdjo kollu jkun ġie ġġenerat. Għal notifika ta’ żewġ sentenzi, ħadd ma jinnota l-istennija. Iżda għal artiklu ta’ blog, kapitlu ta’ ktieb, jew feed tal-aħbarijiet li jiskrollja kontinwament, dik l-istennija ssir l-akbar difett tal-prodott tiegħek: l-utenti jikklikkjaw, imbagħad jibdew iħarsu lejn spinner tat-tagħbija għal diversi sekondi.

Il-modalità WebSocket telimina dik l-istennija billi tibgħat l-awdjo hekk kif jiġi sintetizzat. Ir-riproduzzjoni tibda mill-ewwel kliem waqt li t-tmiem tat-test għadu ma ġiex ipproċessat. Dik hija d-differenza bejn paġna li tidher iffriżata u awdjo li jibda jdoqq minnufih.

Iftaħ il-konnessjoni

Il-konnessjoni tiftaħ fuq wss://api.x.ai/v1/tts, u l-konfigurazzjoni kollha tmur fil-query string tal-URL minflok f’messaġġ ta’ inizjalizzazzjoni.

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

Dawn huma l-parametri aċċettati:

  • language (meħtieġ): kodiċi BCP-47 jew auto
  • voice (opzjonali, default: eve): l-ID tal-vuċi
  • codec (opzjonali, default: mp3): il-format tal-awdjo tal-output
  • sample_rate (opzjonali, default: 24000): ir-rata tal-kampjun f’Hz
  • bit_rate (opzjonali, default: 128000): ir-rata tal-bit f’bps (MP3 biss)

Dawn l-issettjar japplikaw għas-sessjoni kollha: ma tistax tibdel il-vuċi jew il-codec matul it-triq. Jekk l-app tiegħek jeħtieġ li jalternaw bejn żewġ narraturi, iftaħ żewġ konnessjonijiet.

Il-protokoll tal-messaġġi

Fuq in-naħa tal-bagħat, żewġ messaġġi biss huma biżżejjed biex tmexxi s-sintesi. L-ewwel jibgħat biċċa test; it-tieni jħabbar li t-test intemm.

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

Tista’ tibgħat kemm-il messaġġ text.delta trid, kull wieħed sa 60,000 karattru. Madankollu, huwa aħjar li ma tilħaqx dak il-limitu massimu: li taqsam it-test f’biċċiet ta’ ftit sentenzi jwasslek għall-ewwel biċċa awdjo ferm aktar malajr, li huwa preċiżament l-għan tal-istreaming. Delta waħda ta’ diversi eluf ta’ karattri terġa’ lura għall-imġiba tal-modalità HTTP.

Fuq in-naħa tar-riċeviment, kull audio.delta iġorr framment ta’ awdjo kodifikat f’base64, fil-codec li stabbilejt meta għamilt il-konnessjoni. Iddekodjah u żidh mal-buffer tar-riproduzzjoni tiegħek.

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

L-avveniment audio.done jimmarka t-tmiem tas-sintesi. L-trace_id tiegħu huwa l-identifikatur li għandek tagħti lis-support, jew tirreġistra fil-logs tiegħek, meta ġenerazzjoni ma taħdimx sew. Jekk it-test ikun invalidu jew jekk qbiżt il-kwota tiegħek, tirċievi messaġġ ta’ żball minflok.

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

Implimentazzjoni sħiħa

L-eżempju hawn taħt jaqsam test twil f’paragrafi, jibgħathom kollha, imbagħad jgħaqqad il-frammenti tal-awdjo li jirċievi f’fajl 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();
  }
});

Innota l-para + " ": mingħajr dak l-ispazju, it-tmiem ta’ paragrafu jingħaqad mal-bidu tal-li jmiss, u l-magna taqra ż-żewġ kliem flimkien mingħajr nifs.

Limiti li għandek tkun taf bihom

MetrikaValur
Test kull deltaMassimu ta’ 60,000 karattru
Test totaliIllimitat
Sessjonijiet konkorrenti50 kull tim
Permess tas-sessjoni600 sekonda
Timeout tal-konnessjoniL-ebda

Il-paġna ta’ xAI tgħid li l-konnessjoni m’għandha l-ebda timeout, u separatament issemmi “permess tas-sessjoni” ta’ 600 sekonda mingħajr ma tispjega x’jiġri meta jintemm. Biex tkun sikur, konnettja meta jkollok test x’tibgħat minflok meta titgħabba l-paġna, u ppjana għal konnessjoni mill-ġdid. Ippjana madwar il-limitu ta’ 50 sessjoni konkorrenti kull tim bl-istess mod: librerija tal-awdjo li qed tikkonverti l-katalgu tagħha fl-isfond għandek tqiegħed ix-xogħlijiet fi kju minflok ma tiftaħ mitejn konnessjoni paralleli.

HTTP jew WebSocket

Il-modalità HTTP għadha l-għażla t-tajba għal testi qosra, ġenerazzjonijiet ta’ darba, u kullimkien fejn is-simpliċità tal-integrazzjoni hija l-aktar importanti: talba waħda, tweġiba waħda, l-ebda stat x’timmaniġġja. WebSocket huwa t-triq li għandek tieħu meta t-test isir twil, meta l-awdjo jrid jindaqq waqt li qed jiġi prodott, jew meta l-kontenut innifsu jaslu bħala fluss, tipikament l-output ta’ mudell tal-lingwa li qed tivvokalizza hekk kif jiġġenera.

Punti Ewlenin

  • TTS fuq WebSocket jippermettilek tirċievi awdjo streaming mingħajr ma tistenna li l-ġenerazzjoni tispiċċa
  • Il-parametri tal-konfigurazzjoni jmorru fil-query string tal-URL tal-konnessjoni
  • Il-protokoll huwa sempliċi: text.delta biex tibgħat it-test, audio.delta biex tirċievi l-awdjo
  • Is-sessjonijiet WebSocket huma limitati għal 50 konkorrenti kull tim; ipplana għal konnessjoni mill-ġdid
  • Ippreferixxi WebSocket għal testi twal u esperjenzi ta’ smigħ f’ħin reali