Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Integrazione browser e best practice

Lezione 14 di 14 Aggiornata il 3 novembre 2026 Sviluppatore
In questa pagina
  1. Distribuire il TTS in un’app web
  2. Supporto dei codec nel browser
  3. Il problema di AudioContext su Safari
  4. URL Blob e perdite di memoria
  5. Best practice per la produzione
  6. Punti chiave
  7. Verifica la tua comprensione

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:

CodecChromeFirefoxSafariEdgeConsigliato
MP3SìSìSìSìSì
WAVSìSìSìSìSì
Raw PCMNoNoNoNoNo
mulaw/alawNoNoNoNoNo

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.