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

Integração com o navegador e boas práticas

Aula 14 de 14 Atualizada a 3 de novembro de 2026 Programador
Nesta página
  1. Implementar TTS numa aplicação web
  2. Suporte de codecs no navegador
  3. O problema do AudioContext no Safari
  4. URLs de Blob e fugas de memória
  5. Boas práticas de produção
  6. Pontos-chave
  7. Verifique a sua compreensão

Atualizado em 3 de novembro de 2026, com base na página Text to Speech da xAI: a validação no lado do servidor utiliza o limite atual de 60.000 caracteres por pedido. Fonte: Text to Speech.

Implementar TTS numa aplicação web

Integrar TTS num navegador apresenta desafios específicos: suporte de codecs, gestão de memória, particularidades do Safari e desempenho. Esta última lição fornece-lhe tudo o que precisa para uma integração robusta em produção.

Suporte de codecs no navegador

Nem todos os navegadores suportam todos os formatos de áudio. Escolha o codec adequado ao seu público:

CodecChromeFirefoxSafariEdgeRecomendado
MP3SimSimSimSimSim
WAVSimSimSimSimSim
PCM brutoNãoNãoNãoNãoNão
mulaw/alawNãoNãoNãoNãoNão

A regra simples: utilize MP3 ou WAV no navegador. PCM, mulaw e alaw destinam-se a aplicações de servidor e telefonia, não à reprodução web.

// Solicitar MP3 à API (através do seu backend)
const response = await fetch("/api/tts", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    text: "Olá a partir do navegador.",
    voice_id: "eve",
    language: "pt"
    // Não é necessário definir output_format: MP3 é o padrão
  })
});

O problema do AudioContext no Safari

O Safari impõe uma restrição de segurança: um AudioContext só pode ser criado dentro de um manipulador de eventos do utilizador (clique, pressão de tecla, toque). Se tentar criar um AudioContext quando a página carrega, o Safari bloqueia-o silenciosamente.

A abordagem errada

// NÃO funciona no Safari
const audioContext = new AudioContext(); // Bloqueado!

async function playTTS() {
  const audio = await fetchTTS("Olá");
  // audioContext está suspenso no Safari...
}

A abordagem correta

let audioContext = null;

// Criar o AudioContext no primeiro clique do utilizador
document.getElementById("play-btn").addEventListener("click", async () => {
  if (!audioContext) {
    audioContext = new AudioContext();
  }

  // Retomar se estiver suspenso
  if (audioContext.state === "suspended") {
    await audioContext.resume();
  }

  const response = await fetch("/api/tts", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      text: "Olá a partir do Safari.",
      voice_id: "eve",
      language: "pt"
    })
  });

  const arrayBuffer = await response.arrayBuffer();
  const audioBuffer = await audioContext.decodeAudioData(arrayBuffer);

  const source = audioContext.createBufferSource();
  source.buffer = audioBuffer;
  source.connect(audioContext.destination);
  source.start(0);
});

Esta abordagem funciona em todos os navegadores, não apenas no Safari. É uma boa prática universal.

URLs de Blob e fugas de memória

Quando cria URLs de Blob para reproduzir áudio, cada URL consome memória até que a libere explicitamente. Sem limpeza, a sua aplicação sofrerá fugas de memória.

O problema

// Cada chamada cria uma URL de Blob que nunca é libertada
async function playTTS(text) {
  const response = await fetch("/api/tts", { ... });
  const blob = await response.blob();
  const url = URL.createObjectURL(blob); // Fuga de memória!
  const audio = new Audio(url);
  audio.play();
}

A solução

async function playTTS(text) {
  const response = await fetch("/api/tts", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ text, voice_id: "eve", language: "pt" })
  });

  const blob = await response.blob();
  const url = URL.createObjectURL(blob);
  const audio = new Audio(url);

  // Libertar a memória quando a reprodução terminar
  audio.addEventListener("ended", () => {
    URL.revokeObjectURL(url);
  });

  // Libertar também em caso de erro
  audio.addEventListener("error", () => {
    URL.revokeObjectURL(url);
  });

  audio.play();
}

Para aplicações que geram muito áudio, mantenha uma lista de URLs ativas e limpe-as periodicamente:

class AudioManager {
  constructor() {
    this.activeUrls = new Set();
  }

  async play(text) {
    const response = await fetch("/api/tts", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ text, voice_id: "eve", language: "pt" })
    });

    const blob = await response.blob();
    const url = URL.createObjectURL(blob);
    this.activeUrls.add(url);

    const audio = new Audio(url);
    audio.addEventListener("ended", () => this.release(url));
    audio.addEventListener("error", () => this.release(url));
    audio.play();
    return audio;
  }

  release(url) {
    URL.revokeObjectURL(url);
    this.activeUrls.delete(url);
  }

  cleanup() {
    // Libertar todas as URLs ativas
    for (const url of this.activeUrls) {
      URL.revokeObjectURL(url);
    }
    this.activeUrls.clear();
  }
}

Boas práticas de produção

Limitação de taxa no backend

Proteja o seu backend contra abusos limitando os pedidos por utilizador:

const rateLimit = require("express-rate-limit");

const ttsLimiter = rateLimit({
  windowMs: 60 * 1000, // 1 minuto
  max: 10, // 10 pedidos por minuto por IP
  message: { error: "Demasiados pedidos de TTS" }
});

app.post("/api/tts", ttsLimiter, async (req, res) => {
  // ... proxy para a API da xAI
});

Validação de texto

Valide e sanitize o texto antes de o enviar para a API:

function validateTTSInput(text) {
  if (!text || typeof text !== "string") {
    throw new Error("O texto é obrigatório");
  }
  if (text.length > 60000) {
    throw new Error("Texto demasiado longo (máximo de 60.000 caracteres)");
  }
  // Remover caracteres de controlo
  return text.replace(/[\x00-\x08\x0B\x0C\x0E-\x1F]/g, "");
}

Cache de áudio

Para textos repetidos (saudações, instruções padrão), coloque em cache o áudio gerado:

const audioCache = new Map();

async function getTTS(text, voice, language) {
  const cacheKey = `${text}:${voice}:${language}`;

  if (audioCache.has(cacheKey)) {
    return audioCache.get(cacheKey);
  }

  const audio = await fetchTTSFromAPI(text, voice, language);
  audioCache.set(cacheKey, audio);
  return audio;
}

Pré-geração

Para conteúdo que conhece antecipadamente (e-learning, IVR), pré-gerar os ficheiros de áudio no momento da compilação, em vez de o fazer em tempo real.

Pontos-chave

  • Utilize MP3 ou WAV no navegador, nunca PCM/mulaw/alaw
  • No Safari, crie o AudioContext dentro de um manipulador de eventos do utilizador
  • Liberte sempre as URLs de Blob com URL.revokeObjectURL() após a utilização
  • Adicione limitação de taxa ao seu proxy de backend
  • Valide e sanitize o texto antes de o enviar para a API
  • Coloque em cache o áudio para textos repetidos para poupar chamadas à API
  • Pré-gerar áudio para conteúdo que conhece antecipadamente

Verifique a sua compreensão

Síntese de fala da xAI: desde a primeira chamada até ao pipeline de streaming.

1. Como funciona a chamada básica de TTS?

Resposta: Um POST para /v1/tts com o texto, a voz escolhida (que pode listar através da API) e os parâmetros. A resposta é o áudio, faturado pelo volume sintetizado.

2. O que permitem fazer as tags expressivas?

Resposta: Controlar a fala diretamente no texto: tags inline e de envelopamento para entonação, pausas e ênfase, que pode combinar para leituras naturais e direcionadas.

3. Quando deve mudar para o WebSocket de TTS?

Resposta: Para tempo real: o texto sai como um fluxo e o áudio retorna continuamente. É a base dos pipelines LLM → TTS, onde a voz começa antes de a geração terminar.

4. Como secured uma integração no navegador?

Resposta: Nunca coloque a chave da API no cliente: o navegador passa pelo seu servidor ou utiliza credenciais de curta duração, e gere os erros HTTP corretamente.

5. Qual é o aspeto do pipeline de produção completo?

Resposta: Um streaming LLM → segmentos de texto → WebSocket de TTS → reprodução de áudio. Cada ligação faz streaming, pelo que a latência percebida colapsa, e as boas práticas deste curso fecham o ciclo.

Tags para expressividade, WebSocket para tempo real, o seu servidor para segredos: as suas aplicações estão prontas para falar.