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

Messiġġi WebSocket: test u awdjo

Lezzjoni 10 / 14 Aġġornat 3 ta’ Novembru 2026 Zviluppatur
F'din il-paġna
  1. Il-protokoll tal-messaġġi TTS
  2. Messaġġi mill-klijent għas-server
  3. Messaġġi mis-server għall-klijent
  4. Il-fluss sħiħ tal-komunikazzjoni
  5. Implimentazzjoni sħiħa f’Python
  6. Implimentazzjoni f’JavaScript (Node.js)
  7. Kif timmaniġġja ħafna deltas
  8. Punti Ewlenin

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), u session.update (tabella replace)
  • Ħames messaġġi tas-server: audio.delta (biċċa awdjo), audio.done (tmiem), audio.clear (kanċellazzjoni kkonfermata), session.updated, u error
  • 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