TTS en Streaming avec WebSocket

Pourquoi le streaming TTS

Le mode HTTP du TTS vous oblige a attendre que l’integralite de l’audio soit generee avant de le recevoir. Pour un texte court, c’est acceptable. Mais pour un article de blog, un chapitre de livre ou un fil d’actualites en continu, la latence devient prohibitive.

Le mode WebSocket resout ce probleme en envoyant l’audio au fur et a mesure de sa generation. L’utilisateur commence a ecouter presque immediatement, pendant que le reste du texte est encore en cours de synthese.

Etablir la connexion

La connexion WebSocket TTS utilise l’endpoint wss://api.x.ai/v1/tts avec les parametres de configuration dans la query string :

const ws = new WebSocket(
  "wss://api.x.ai/v1/tts?language=fr&voice=ara&codec=mp3&sample_rate=24000",
  {
    headers: {
      "Authorization": "Bearer " + XAI_API_KEY
    }
  }
);

Parametres de connexion

• language (obligatoire) : code BCP-47 ou auto
• voice (optionnel, defaut : eve) : identifiant de la voix
• codec (optionnel, defaut : mp3) : format audio de sortie
• sample_rate (optionnel, defaut : 24000) : frequence d’echantillonnage en Hz
• bit_rate (optionnel, defaut : 128000) : debit binaire en bps (MP3 uniquement)

Le protocole de messages

Messages que vous envoyez

Deux types de messages suffisent pour piloter le TTS en streaming :

Envoyer un morceau de texte :

{ "type": "text.delta", "delta": "Bonjour et bienvenue " }

Signaler la fin du texte :

{ "type": "text.done" }

Vous pouvez envoyer autant de text.delta que necessaire. Chaque delta peut contenir jusqu’a 15 000 caracteres, mais il est recommande d’envoyer des morceaux plus petits (quelques phrases) pour que l’audio commence a arriver rapidement.

Messages que vous recevez

{ "type": "audio.delta", "delta": "<base64 audio>" }

Chaque audio.delta contient un chunk d’audio encode en base64 dans le codec que vous avez specifie. Decodez-le et ajoutez-le a votre buffer de lecture.

{ "type": "audio.done", "trace_id": "uuid-de-trace" }

L’evenement audio.done signale que toute la synthese est terminee. Le trace_id peut servir au debugging.

{ "type": "error", "message": "description de l'erreur" }

En cas de probleme (texte invalide, quota depasse), un message d’erreur est envoye.

Implementation complete

Voici un exemple complet en JavaScript pour generer de l’audio a partir d’un long texte :

const WebSocket = require("ws");
const fs = require("fs");

const ws = new WebSocket(
  "wss://api.x.ai/v1/tts?language=fr&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();
  }
});

Limites du mode WebSocket

La limite de 600 secondes de TTL signifie que votre session WebSocket se ferme automatiquement apres 10 minutes d’inactivite. Envoyez des messages regulierement pour maintenir la connexion active.

Quand utiliser HTTP vs WebSocket

• HTTP : textes courts (< 5 000 caracteres), generation ponctuelle, simplicite d’integration
• WebSocket : textes longs, generation en temps reel, lecture immediate pendant la generation, flux continu de contenu

Points cles a retenir

• Le mode WebSocket TTS permet de recevoir l’audio en streaming sans attendre la fin de la generation
• Les parametres de configuration se passent dans la query string de l’URL de connexion
• Le protocole est simple : text.delta pour envoyer du texte, audio.delta pour recevoir l’audio
• Les sessions WebSocket ont une limite de 50 simultanees par equipe et un TTL de 600 secondes
• Privilegiez le WebSocket pour les textes longs et les experiences de lecture en temps reel