Streaming TTS fuq WebSocket
F'din il-paġna
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
| Metrika | Valur |
|---|---|
| Test kull delta | Massimu ta’ 60,000 karattru |
| Test totali | Illimitat |
| Sessjonijiet konkorrenti | 50 kull tim |
| Permess tas-sessjoni | 600 sekonda |
| Timeout tal-konnessjoni | L-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.deltabiex tibgħat it-test,audio.deltabiex 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