Integração com o navegador e boas práticas
Nesta página
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:
| Codec | Chrome | Firefox | Safari | Edge | Recomendado |
|---|---|---|---|---|---|
| MP3 | Sim | Sim | Sim | Sim | Sim |
| WAV | Sim | Sim | Sim | Sim | Sim |
| PCM bruto | Não | Não | Não | Não | Não |
| mulaw/alaw | Não | Não | Não | Não | Nã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.