Integrazione browser e best practice
In questa pagina
Aggiornato il 3 novembre 2026, basato sulla pagina Text to Speech di xAI: la validazione lato server utilizza l’attuale limite di 60.000 caratteri per richiesta. Fonte: Text to Speech.
Distribuire il TTS in un’app web
Integrare il TTS in un browser presenta sfide specifiche: supporto dei codec, gestione della memoria, particolarità di Safari e prestazioni. Questa lezione finale ti fornisce tutto il necessario per un’integrazione robusta in produzione.
Supporto dei codec nel browser
Non tutti i browser supportano tutti i formati audio. Scegli il codec giusto per il tuo pubblico:
| Codec | Chrome | Firefox | Safari | Edge | Consigliato |
|---|---|---|---|---|---|
| MP3 | Sì | Sì | Sì | Sì | Sì |
| WAV | Sì | Sì | Sì | Sì | Sì |
| Raw PCM | No | No | No | No | No |
| mulaw/alaw | No | No | No | No | No |
La regola semplice: usa MP3 o WAV nel browser. PCM, mulaw e alaw sono pensati per applicazioni server e telefonia, non per la riproduzione web.
// Richiedi MP3 dall'API (tramite il tuo backend)
const response = await fetch("/api/tts", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
text: "Hello from the browser.",
voice_id: "eve",
language: "en"
// Non c'è bisogno di impostare output_format: MP3 è il default
})
});
Il problema di AudioContext su Safari
Safari impone una restrizione di sicurezza: un AudioContext può essere creato solo all’interno di un gestore di eventi utente (clic, pressione di tasto, tap). Se provi a creare un AudioContext al caricamento della pagina, Safari lo blocca silenziosamente.
L’approccio sbagliato
// NON funziona su Safari
const audioContext = new AudioContext(); // Bloccato!
async function playTTS() {
const audio = await fetchTTS("Hello");
// audioContext è sospeso su Safari...
}
L’approccio corretto
let audioContext = null;
// Crea l'AudioContext al primo clic dell'utente
document.getElementById("play-btn").addEventListener("click", async () => {
if (!audioContext) {
audioContext = new AudioContext();
}
// Riprendi se sospeso
if (audioContext.state === "suspended") {
await audioContext.resume();
}
const response = await fetch("/api/tts", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
text: "Hello from Safari.",
voice_id: "eve",
language: "en"
})
});
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);
});
Questo approccio funziona in ogni browser, non solo su Safari. È una buona pratica universale.
URL Blob e perdite di memoria
Quando crei URL Blob per riprodurre audio, ogni URL occupa memoria finché non la rilasci esplicitamente. Senza pulizia, la tua app perderà memoria.
Il problema
// Ogni chiamata crea un URL Blob che non viene mai rilasciato
async function playTTS(text) {
const response = await fetch("/api/tts", { ... });
const blob = await response.blob();
const url = URL.createObjectURL(blob); // Perdita di memoria!
const audio = new Audio(url);
audio.play();
}
La soluzione
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: "en" })
});
const blob = await response.blob();
const url = URL.createObjectURL(blob);
const audio = new Audio(url);
// Libera la memoria al termine della riproduzione
audio.addEventListener("ended", () => {
URL.revokeObjectURL(url);
});
// Liberala anche in caso di errore
audio.addEventListener("error", () => {
URL.revokeObjectURL(url);
});
audio.play();
}
Per le app che generano molto audio, mantieni una lista degli URL attivi e puliscili 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: "en" })
});
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() {
// Rilascia ogni URL attivo
for (const url of this.activeUrls) {
URL.revokeObjectURL(url);
}
this.activeUrls.clear();
}
}
Best practice per la produzione
Limitazione delle richieste (Rate limiting) lato backend
Proteggi il tuo backend dagli abusi limitando le richieste per utente:
const rateLimit = require("express-rate-limit");
const ttsLimiter = rateLimit({
windowMs: 60 * 1000, // 1 minuto
max: 10, // 10 richieste al minuto per IP
message: { error: "Troppe richieste TTS" }
});
app.post("/api/tts", ttsLimiter, async (req, res) => {
// ... proxy verso l'API xAI
});
Validazione del testo
Valida e sanifica il testo prima di inviarlo all’API:
function validateTTSInput(text) {
if (!text || typeof text !== "string") {
throw new Error("Il testo è obbligatorio");
}
if (text.length > 60000) {
throw new Error("Testo troppo lungo (massimo 60.000 caratteri)");
}
// Rimuovi i caratteri di controllo
return text.replace(/[\x00-\x08\x0B\x0C\x0E-\x1F]/g, "");
}
Caching dell’audio
Per testi ripetuti (saluti, istruzioni standard), memorizza nella cache l’audio generato:
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;
}
Pre-generazione
Per contenuti che conosci in anticipo (e-learning, IVR), pre-genera i file audio al momento della build invece che in tempo reale.
Punti chiave
- Usa MP3 o WAV nel browser, mai PCM/mulaw/alaw
- Su Safari, crea l’AudioContext all’interno di un gestore di eventi utente
- Rilascia sempre gli URL Blob con
URL.revokeObjectURL()dopo l’uso - Aggiungi la limitazione delle richieste al tuo proxy backend
- Valida e sanifica il testo prima di inviarlo all’API
- Memorizza nella cache l’audio per i testi ripetuti per risparmiare chiamate API
- Pre-genera l’audio per i contenuti che conosci in anticipo
Verifica la tua comprensione
Sintesi vocale xAI: dalla prima chiamata alla pipeline di streaming.
1. Come funziona la chiamata TTS di base?
Risposta: Una POST su /v1/tts con il testo, la voce scelta (che puoi elencare tramite l’API) e i parametri. La risposta è l’audio, fatturato in base al volume sintetizzato.
2. Cosa ti permettono di fare i tag espressivi?
Risposta: Controllare il parlato direttamente dal testo: tag inline e di avvolgimento per intonazione, pause ed enfasi, che puoi combinare per letture naturali e guidate.
3. Quando dovresti passare al WebSocket TTS?
Risposta: Per il tempo reale: il testo viene inviato come stream e l’audio torna in modo continuo. È la base delle pipeline LLM → TTS, dove la voce inizia prima che la generazione sia terminata.
4. Come si protegge un'integrazione browser?
Risposta: Non inserire mai la chiave API nel client: il browser passa attraverso il tuo server o usa credenziali a breve durata, e gestisci correttamente gli errori HTTP.
5. Com'è fatta una pipeline di produzione completa?
Risposta: Una pipeline streaming LLM → segmenti di testo → WebSocket TTS → riproduzione audio. Ogni collegamento trasmette in streaming, quindi la latenza percepita crolla, e le best practice di questo corso chiudono il cerchio.
Tag per l’espressività, WebSocket per il tempo reale, il tuo server per i segreti: le tue app sono pronte a parlare.