Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Ricevi e riproduci l'audio della risposta

Lezione 11 di 16 Aggiornata il 30 luglio 2026 Sviluppatore
In questa pagina
  1. Riproduzione in streaming
  2. Architettura del lettore audio
  3. Collegamento agli eventi WebSocket
  4. Gestione delle interruzioni
  5. Lettore audio in Python
  6. Mostra la trascrizione a fianco
  7. Punti chiave

Riproduzione in streaming

Quando l’agente vocale genera una risposta, l’audio arriva in frammenti (delta) codificati in base64. La tua applicazione deve decodificarli, metterli in coda e riprodurli fluidamente, così l’utente sente una risposta continua senza interruzioni.

Architettura del lettore audio

Il principio è semplice: ogni delta audio ricevuto viene decodificato e aggiunto a una coda. Un processo di riproduzione consuma la coda e invia i dati all’uscita audio del sistema:

class AudioStreamPlayer {
  constructor(sampleRate = 24000) {
    this.audioContext = new AudioContext({ sampleRate });
    this.queue = [];
    this.isPlaying = false;
    this.nextPlayTime = 0;
  }

  enqueue(pcm16ArrayBuffer) {
    // Converti PCM16 in Float32 per le Web Audio API
    const pcm16 = new Int16Array(pcm16ArrayBuffer);
    const float32 = new Float32Array(pcm16.length);
    for (let i = 0; i < pcm16.length; i++) {
      float32[i] = pcm16[i] / 32768.0;
    }

    const buffer = this.audioContext.createBuffer(
      1, float32.length, this.audioContext.sampleRate
    );
    buffer.getChannelData(0).set(float32);

    this.queue.push(buffer);
    if (!this.isPlaying) this.playNext();
  }

  playNext() {
    if (this.queue.length === 0) {
      this.isPlaying = false;
      return;
    }

    this.isPlaying = true;
    const buffer = this.queue.shift();
    const source = this.audioContext.createBufferSource();
    source.buffer = buffer;
    source.connect(this.audioContext.destination);

    const now = this.audioContext.currentTime;
    const startTime = Math.max(now, this.nextPlayTime);
    source.start(startTime);
    this.nextPlayTime = startTime + buffer.duration;

    source.onended = () => this.playNext();
  }

  stop() {
    this.queue = [];
    this.isPlaying = false;
    this.nextPlayTime = 0;
  }
}

Collegamento agli eventi WebSocket

Ecco come collegare il lettore audio agli eventi delle API:

const player = new AudioStreamPlayer(24000);

ws.on("message", (data) => {
  const event = JSON.parse(data);

  switch (event.type) {
    case "response.output_audio.delta":
      const audioBytes = base64ToArrayBuffer(event.delta);
      player.enqueue(audioBytes);
      break;

    case "response.output_audio.done":
      console.log("Risposta audio completata");
      break;

    case "input_audio_buffer.speech_started":
      // L'utente interrompe l'agente
      player.stop();
      ws.send(JSON.stringify({ type: "response.cancel" }));
      break;
  }
});

function base64ToArrayBuffer(base64) {
  const binary = atob(base64);
  const bytes = new Uint8Array(binary.length);
  for (let i = 0; i < binary.length; i++) {
    bytes[i] = binary.charCodeAt(i);
  }
  return bytes.buffer;
}

Gestione delle interruzioni

In una conversazione naturale, l’utente può interrompere l’agente parlando sopra la sua risposta. La tua applicazione deve gestire questo scenario:

  1. Rileva l’interruzione: l’evento speech_started arriva mentre l’audio è in riproduzione.
  2. Ferma la riproduzione: svuota la coda audio e interrompi il suono.
  3. Annulla la risposta: invia response.cancel affinché il server smetta di generare contenuti.
  4. Ascolta: la parola passa all’utente e il ciclo ricomincia.

Questo meccanismo di «barge-in» è essenziale per una conversazione fluida. Senza di esso, gli utenti dovrebbero aspettare che l’agente finisca di parlare prima di poter rispondere.

Lettore audio in Python

Per un’applicazione Python, puoi usare pyaudio per la riproduzione:

import pyaudio
import base64
import asyncio
from collections import deque

class AudioPlayer:
    def __init__(self, rate=24000):
        self.p = pyaudio.PyAudio()
        self.stream = self.p.open(
            format=pyaudio.paInt16,
            channels=1,
            rate=rate,
            output=True
        )
        self.queue = deque()

    def enqueue(self, base64_audio):
        audio_bytes = base64.b64decode(base64_audio)
        self.queue.append(audio_bytes)

    def play_all(self):
        while self.queue:
            chunk = self.queue.popleft()
            self.stream.write(chunk)

    def stop(self):
        self.queue.clear()

Mostra la trascrizione a fianco

Mentre l’audio viene riprodotto, puoi visualizzare la trascrizione della risposta in tempo reale grazie agli eventi response.output_audio_transcript.delta. Gli utenti possono così leggere ciò che l’agente sta dicendo, il che aiuta in ambienti rumorosi e migliora l’accessibilità:

let currentTranscript = "";

case "response.output_audio_transcript.delta":
  currentTranscript += event.delta;
  updateTranscriptDisplay(currentTranscript);
  break;

Punti chiave

  • L’audio della risposta arriva come frammenti base64 tramite response.output_audio.delta
  • Usa una coda audio per garantire una riproduzione continua senza interruzioni
  • Gestisci le interruzioni (barge-in) fermando la riproduzione e annullando la risposta
  • Mostra la trascrizione a fianco dell’audio per migliorare l’accessibilità
  • Le Web Audio API del browser richiedono una conversione da base64 a PCM16 e poi a Float32