Messiġġi WebSocket: test u awdjo
F'din il-paġna
Aġġornat fit-3 ta’ Novembru 2026, ibbażat fuq il-paġna Text to Speech ta’ xAI: deltas sa 60,000 karattru, kanċellazzjoni (
text.clear,audio.clear), u t-tabella tal-pronunzja (session.update,session.updated). Sors: Text to Speech.
Il-protokoll tal-messaġġi TTS
Ladarba l-konnessjoni WebSocket tkun miftuħa, il-komunikazzjoni taħdem billi tiskambja messaġġi JSON. Inti tibgħat it-test, u s-server iwieġeb b’awdjo kodifikat f’base64. Li tifhem dan il-protokoll huwa essenzjali biex timplimenta l-istreaming TTS korrettament.
Messaġġi mill-klijent għas-server
L-app tiegħek tibgħat erba’ tipi ta’ messaġġi lis-server: text.delta u text.done għat-test, text.clear biex tikkanċella, u session.update biex tikkonfigura.
text.delta: ibgħat biċċa test
Il-messaġġ text.delta jibgħat framment ta’ test biex jiġi kkonvertit. Tista’ tibgħat it-test f’biċċiet suċċessivi:
{"type": "text.delta", "delta": "Hello, and welcome to "}
{"type": "text.delta", "delta": "our presentation on speech synthesis."}
Kull delta tista’ żżomm sa 60,000 karattru, u t-test totali m’għandux limitu. Is-server jibda jiġġenera l-awdjo hekk kif ikollu biżżejjed kuntest biex jipproduċi pronunzja naturali.
text.done: issinjala t-tmiem tat-test
Il-messaġġ text.done jgħid lis-server li spiċċajt tibgħat it-test għal din is-sekwenza:
{"type": "text.done"}
Ladarba jirċievi dan il-messaġġ, is-server jitlesta jiġġenera l-awdjo u jibgħat messaġġ audio.done. Imbagħad tista’ tibda tibgħat deltas ġodda għal sekwenza ġdida.
text.clear: ikkanċella s-sekwenza attwali
text.clear jikkanċella s-sekwenza attwali: is-server jieqaf jiġġenera l-awdjo, jarmi dak li kellu fil-memorja, u jwieġeb b’audio.clear. Il-konnessjoni tkun lestja immedjatament għas-sekwenza li jmiss, mingħajr l-ebda handshake ġdid ta’ WebSocket; xAI tistma l-iffrankar f’madwar 600 ms għal klijent ‘il bogħod. Dan huwa l-mekkaniżmu ta’ interruzzjoni (“barge-in”) għal meta l-utent jindaħal.
{"type": "text.clear"}
session.update: issolvi l-pronunzja
session.update jinstalla, jew jissostitwixxi, it-tabella replace tal-konnessjoni: kull frażi misjuba fit-test tiġi skambjata mal-forma mitkellma tagħha qabel is-sinteżi, mingħajr ma tbiddel it-test li tibgħat jew in-numru ta’ karattri li tiġi fatturat għalihom. Ibagħtu qabel l-ewwel text.delta biex ikopri l-konnessjoni kollha; aġġornament li jasal f’nofs sekwenza japplika biss mis-sekwenza li jmiss.
{"type": "session.update", "replace": {"kubectl": "kube cuttle"}}
Messaġġi mis-server għall-klijent
Is-server iwieġeb b’ħames tipi ta’ messaġġi: audio.delta, audio.done, u error, iddettaljati hawn taħt, flimkien ma’ audio.clear, li jikkonferma kanċellazzjoni, u session.updated, li jirritorna t-tabella replace fis-seħħ.
audio.delta: biċċa awdjo
Il-messaġġ audio.delta fih framment ta’ awdjo kodifikat f’base64:
{
"type": "audio.delta",
"delta": "SUQzBAAAAAAAI1RTU0UAAAAPAAADTGF2ZjU4Ljc2..."
}
Kull delta hija biċċa awdjo valida li tista’ tdekodekha u ddawwarha minnufih. Id-deltas jaslu hekk kif il-ġenerazzjoni timxi ‘l quddiem.
audio.done: il-ġenerazzjoni ntemmet
Il-messaġġ audio.done jissinjala li l-awdjo kollu għas-sekwenza tat-test li bgħatt ġie ġġenerat:
{
"type": "audio.done",
"trace_id": "550e8400-e29b-41d4-a716-446655440000"
}
It-trace_id huwa ID uniku għas-sekwenza, utli għad-debugging u t-traċċar.
error: seħħ żball
Jekk xi ħaġa tmur ħażin, is-server jibgħat messaġġ ta’ żball:
{
"type": "error",
"message": "Invalid text encoding"
}
Il-fluss sħiħ tal-komunikazzjoni
Hekk kif tiżvolġi sessjoni tipika:
Client Server
| |
|-- text.delta ("Hello, ") ----->|
|-- text.delta ("how are ") ---->|
|-- text.delta ("you?") -------->|
|<-- audio.delta (chunk 1) -----|
|<-- audio.delta (chunk 2) -----|
|-- text.done ----------------->|
|<-- audio.delta (chunk 3) -----|
|<-- audio.done ----------------|
Is-server jista’ jibda jibgħat messaġġi audio.delta qabel ma tkun bgħatt text.done. Dik hija l-idea kollha tal-istreaming: il-ġenerazzjoni tibda malajr kemm jista’ jkun.
Implimentazzjoni sħiħa f’Python
import asyncio
import websockets
import json
import base64
async def stream_tts(api_key, text, voice="eve", language="en"):
uri = f"wss://api.x.ai/v1/tts?language={language}&voice={voice}&codec=mp3"
headers = {"Authorization": f"Bearer {api_key}"}
audio_chunks = []
async with websockets.connect(uri, additional_headers=headers) as ws:
# Ibghat it-test f'biċċiet ta' 2,000 karattru
chunk_size = 2000
for i in range(0, len(text), chunk_size):
chunk = text[i:i + chunk_size]
await ws.send(json.dumps({
"type": "text.delta",
"delta": chunk
}))
# Issinjala t-tmiem tat-test
await ws.send(json.dumps({"type": "text.done"}))
# Irċievi l-biċċiet tal-awdjo
async for message in ws:
data = json.loads(message)
if data["type"] == "audio.delta":
audio_bytes = base64.b64decode(data["delta"])
audio_chunks.append(audio_bytes)
elif data["type"] == "audio.done":
print(f"Generation finished (trace: {data['trace_id']})")
break
elif data["type"] == "error":
raise Exception(f"TTS error: {data['message']}")
# Assembla l-awdjo sħiħ
return b"".join(audio_chunks)
Implimentazzjoni f’JavaScript (Node.js)
const WebSocket = require("ws");
function streamTTS(apiKey, text, voice = "eve", language = "en") {
return new Promise((resolve, reject) => {
const ws = new WebSocket(
`wss://api.x.ai/v1/tts?language=${language}&voice=${voice}&codec=mp3`,
{ headers: { Authorization: `Bearer ${apiKey}` } }
);
const audioChunks = [];
ws.on("open", () => {
// Ibghat it-test
ws.send(JSON.stringify({ type: "text.delta", delta: text }));
ws.send(JSON.stringify({ type: "text.done" }));
});
ws.on("message", (raw) => {
const data = JSON.parse(raw);
if (data.type === "audio.delta") {
audioChunks.push(Buffer.from(data.delta, "base64"));
} else if (data.type === "audio.done") {
ws.close();
resolve(Buffer.concat(audioChunks));
} else if (data.type === "error") {
ws.close();
reject(new Error(data.message));
}
});
ws.on("error", reject);
});
}
Kif timmaniġġja ħafna deltas
Għal test iġġenerat progressivament (l-output ta’ LLM, pereżempju), ibgħat kull token direttament lejn il-WebSocket TTS:
async def llm_to_speech(ws_tts, llm_stream):
async for token in llm_stream:
await ws_tts.send(json.dumps({
"type": "text.delta",
"delta": token
}))
await ws_tts.send(json.dumps({"type": "text.done"}))
Din l-arkitettura ta’ “streaming LLM f’streaming TTS” toffri l-inqas latenza possibbli: l-utent jisma’ t-tweġiba waqt li l-LLM għadu qed jiġġeneraha.
Punti Ewlenin
- Erba’ messaġġi tal-klijent:
text.delta(ibgħat test),text.done(tmiem it-test),text.clear(ikkanċella), usession.update(tabellareplace) - Ħames messaġġi tas-server:
audio.delta(biċċa awdjo),audio.done(tmiem),audio.clear(kanċellazzjoni kkonfermata),session.updated, uerror - L-awdjo huwa kodifikat f’base64 f’messaġġi
audio.delta - Is-server jibda jiġġenera qabel ma jirċievi
text.done - Kull delta ta’ test huwa limitat għal 60,000 karattru
- Il-katina ta’ LLM li jstreamja f’TTS li jstreamja tagħti l-inqas latenza