Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Mensagens WebSocket: texto e áudio

Aula 10 de 14 Atualizada a 3 de novembro de 2026 Programador
Nesta página
  1. O protocolo de mensagens TTS
  2. Mensagens do cliente para o servidor
  3. Mensagens do servidor para o cliente
  4. O fluxo completo de comunicação
  5. Implementação completa em Python
  6. Implementação em JavaScript (Node.js)
  7. Gestão de múltiplos deltas
  8. Pontos-chave

Atualizado a 3 de novembro de 2026, com base na página Text to Speech da xAI: deltas de até 60.000 carateres, cancelamento (text.clear, audio.clear) e tabela de pronúncia (session.update, session.updated). Fonte: Text to Speech.

O protocolo de mensagens TTS

Assim que a ligação WebSocket estiver estabelecida, a comunicação funciona através da troca de mensagens JSON. O seu cliente envia texto e o servidor responde com áudio codificado em base64. Compreender este protocolo é essencial para implementar corretamente o streaming de TTS.

Mensagens do cliente para o servidor

A sua aplicação envia quatro tipos de mensagens para o servidor: text.delta e text.done para o texto, text.clear para cancelar e session.update para configurar.

text.delta: enviar um fragmento de texto

A mensagem text.delta envia um fragmento de texto para conversão. Pode enviar o texto em partes sucessivas:

{"type": "text.delta", "delta": "Hello, and welcome to "}
{"type": "text.delta", "delta": "our presentation on speech synthesis."}

Cada delta pode conter até 60.000 carateres, e o texto total não tem limite. O servidor começa a gerar áudio assim que tiver contexto suficiente para produzir uma pronúncia natural.

text.done: sinalizar o fim do texto

A mensagem text.done informa o servidor de que terminou o envio de texto para esta sequência:

{"type": "text.done"}

Assim que recebe esta mensagem, o servidor conclui a geração do áudio e envia uma mensagem audio.done. Pode então começar a enviar novos deltas para uma nova sequência.

text.clear: cancelar a sequência atual

text.clear cancela a sequência atual: o servidor para de gerar áudio, descarta o que tinha na memória e responde com audio.clear. A ligação fica imediatamente pronta para a próxima sequência, sem necessidade de novo handshake WebSocket; a xAI estima uma poupança de cerca de 600 ms para um cliente remoto. Este é o mecanismo de interrupção («barge-in») para quando o utilizador intervém.

{"type": "text.clear"}

session.update: corrigir a pronúncia

session.update instala ou substitui a tabela replace da ligação: cada frase encontrada no texto é trocada pela sua forma falada antes da síntese, sem alterar o texto que envia nem o número de carateres faturados. Envie-a antes do primeiro text.delta para que cubra toda a ligação; uma atualização recebida a meio de uma sequência só se aplica a partir da sequência seguinte.

{"type": "session.update", "replace": {"kubectl": "kube cuttle"}}

Mensagens do servidor para o cliente

O servidor responde com cinco tipos de mensagens: audio.delta, audio.done e error, detalhados abaixo, além de audio.clear, que confirma um cancelamento, e session.updated, que devolve a tabela replace em vigor.

audio.delta: um fragmento de áudio

A mensagem audio.delta contém um fragmento de áudio codificado em base64:

{
  "type": "audio.delta",
  "delta": "SUQzBAAAAAAAI1RTU0UAAAAPAAADTGF2ZjU4Ljc2..."
}

Cada delta é um pedaço de áudio válido que pode descodificar e reproduzir de imediato. Os deltas chegam à medida que a geração progride.

audio.done: geração concluída

A mensagem audio.done sinaliza que todo o áudio para a sequência de texto que enviou foi gerado:

{
  "type": "audio.done",
  "trace_id": "550e8400-e29b-41d4-a716-446655440000"
}

O trace_id é um ID único para a sequência, útil para depuração e rastreio.

error: ocorreu um erro

Se algo correr mal, o servidor envia uma mensagem de erro:

{
  "type": "error",
  "message": "Invalid text encoding"
}

O fluxo completo de comunicação

Eis como decorre uma sessão típica:

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 ----------------|

O servidor pode começar a enviar mensagens audio.delta antes mesmo de ter recebido text.done. Essa é exatamente a ideia do streaming: a geração começa o mais cedo possível.

Implementação completa em 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:
        # Enviar o texto em pedaços de 2.000 carateres
        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
            }))

        # Sinalizar o fim do texto
        await ws.send(json.dumps({"type": "text.done"}))

        # Receber os pedaços de áudio
        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']}")

    # Montar o áudio completo
    return b"".join(audio_chunks)

Implementação em 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", () => {
      // Enviar o texto
      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);
  });
}

Gestão de múltiplos deltas

Para texto gerado progressivamente (a saída de um LLM, por exemplo), envie cada token diretamente para o WebSocket de 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"}))

Esta arquitetura de «streaming de LLM para streaming de TTS» oferece a latência mais baixa possível: o utilizador ouve a resposta enquanto o LLM ainda está a gerar.

Pontos-chave

  • Quatro mensagens do cliente: text.delta (enviar texto), text.done (fim do texto), text.clear (cancelar) e session.update (tabela replace)
  • Cinco mensagens do servidor: audio.delta (um pedaço de áudio), audio.done (fim), audio.clear (cancelamento confirmado), session.updated e error
  • O áudio é codificado em base64 nas mensagens audio.delta
  • O servidor começa a gerar antes de receber text.done
  • Cada delta de texto está limitado a 60.000 carateres
  • Encadear um LLM em streaming num TTS em streaming proporciona a menor latência