Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Esegui il commit e svuota il buffer audio

Lezione 8 di 16 Aggiornata il 3 novembre 2026 Sviluppatore
In questa pagina
  1. Gestione del buffer audio
  2. input_audio_buffer.commit
  3. input_audio_buffer.clear
  4. Modalità VAD rispetto alla modalità manuale
  5. Punti chiave

Aggiornato il 3 novembre 2026, in base al riferimento dell’API Voice di xAI: input_audio_buffer.commit è disponibile solo quando turn_detection.type è null; in modalità server_vad, il server esegue il commit dell’audio automaticamente. Fonte: Voice API.

Gestione del buffer audio

Quando invii audio con input_audio_buffer.append, i dati si accumulano in un buffer sul server. Due operazioni controllano questo buffer: commit per inviare il contenuto come messaggio utente e clear per svuotarlo senza elaborazione.

input_audio_buffer.commit

Questo evento esegue il commit del contenuto corrente del buffer audio come messaggio utente. È obbligatorio in modalità manuale (push-to-talk) e automatico in modalità VAD:

{
  "type": "input_audio_buffer.commit"
}

Quando il server riceve un commit:

  1. Crea un nuovo elemento di conversazione con l’audio accumulato
  2. Invia un evento input_audio_buffer.committed per confermare
  3. Invia un evento conversation.item.added con il nuovo elemento
  4. Avvia la trascrizione dell’audio (se abilitata)

La risposta del server

{
  "type": "input_audio_buffer.committed",
  "item_id": "item_audio_001"
}

L’item_id ti permette di fare riferimento a questo messaggio nella conversazione in un secondo momento.

Quando eseguire il commit manualmente

  • Push-to-talk: l’utente tiene premuto un pulsante per parlare e lo rilascia per inviare
  • Segmentazione manuale: suddividi il flusso audio in segmenti logici lato client
  • Integrazione telefonica: ricevi chunk audio da un PBX ed esegui il commit alla fine di ogni turno
// Esempio push-to-talk
talkButton.addEventListener("mousedown", () => {
  isRecording = true;
  startCapture();
});

talkButton.addEventListener("mouseup", () => {
  isRecording = false;
  stopCapture();

  // Esegui il commit del buffer
  ws.send(JSON.stringify({
    type: "input_audio_buffer.commit"
  }));

  // Richiedi una risposta
  ws.send(JSON.stringify({
    type: "response.create"
  }));
});

input_audio_buffer.clear

Questo evento svuota il buffer audio senza creare un messaggio nella conversazione:

{
  "type": "input_audio_buffer.clear"
}

Il server conferma con:

{
  "type": "input_audio_buffer.cleared"
}

Quando svuotare il buffer

  • Annullamento: l’utente preme un pulsante “Annulla” mentre parla
  • Interruzione: l’utente inizia a parlare, ma un altro evento interrompe il turno
  • Reset: dopo un errore o un timeout, svuota il buffer prima di ricominciare
  • Rumore di fondo: il sistema rileva che il buffer contiene solo rumore, non voce
cancelButton.addEventListener("click", () => {
  stopCapture();
  ws.send(JSON.stringify({
    type: "input_audio_buffer.clear"
  }));
  showMessage("Registrazione annullata");
});

Modalità VAD rispetto alla modalità manuale

In modalità VAD (server_vad), il server gestisce l’intero ciclo automaticamente:

  1. Rileva l’inizio della voce (speech_started)
  2. Accumula l’audio nel buffer
  3. Rileva la fine della voce (speech_stopped)
  4. Esegue il commit del buffer automaticamente
  5. Avvia automaticamente la generazione della risposta

In modalità manuale (turn_detection.type impostato su null), gestisci ogni passo tu stesso; è l’unica modalità in cui input_audio_buffer.commit è disponibile:

  1. Invii l’audio con append
  2. Decidi quando l’utente ha finito
  3. Invii commit
  4. Invii response.create

Confronto

AspettoModalità VADModalità manuale
Rilevamento voceAutomaticoA tua cura
Commit del bufferAutomaticoManuale (commit)
Richiesta rispostaAutomaticaManuale (response.create)
ControlloMinore controlloControllo totale
ComplessitàSemplicePiù complessa
Casi d’usoConversazione fluidaPush-to-talk, IVR

Punti chiave

  • input_audio_buffer.commit invia il buffer audio come messaggio utente
  • input_audio_buffer.clear svuota il buffer senza elaborazione
  • In modalità VAD, il commit avviene automaticamente al rilevamento della fine della voce
  • In modalità manuale (turn_detection.type impostato su null), devi inviare esplicitamente commit e poi response.create; commit è disponibile solo in questa modalità
  • La modalità manuale è adatta alle interfacce push-to-talk e ai sistemi telefonici IVR