Vai al contenuto principale
Italiano— Scegli una lingua
Menu

VAD: rilevamento automatico della voce

Lezione 6 di 16 Aggiornata il 3 novembre 2026 Sviluppatore
In questa pagina
  1. Come funziona il rilevamento del turno
  2. Due modalità, un unico campo
  3. Eventi VAD
  4. Sollecitare un utente silenzioso: idle_timeout_ms
  5. Modalità manuale: turn_detection.type impostato su null
  6. Scegli la tua modalità
  7. Punti chiave

Aggiornato il 3 novembre 2026, sulla base della pagina Speech to Speech di xAI e del riferimento alle API Voice: il rilevamento del turno si configura con turn_detection.type ("server_vad" o null) e, opzionalmente, turn_detection.idle_timeout_ms. Fonti: Speech to Speech · Voice API.

Come funziona il rilevamento del turno

In una conversazione vocale, il sistema deve sapere quando l’utente inizia a parlare e quando smette. Questo è il compito del VAD (rilevamento dell’attività vocale). Le API Voice Agent di xAI offrono un VAD lato server, server_vad: il server analizza il flusso audio, individua la fine di ogni enunciato e attiva autonomamente la risposta.

Due modalità, un unico campo

Scegli la modalità nell’oggetto turn_detection di session.update:

{
  "type": "session.update",
  "session": {
    "turn_detection": { "type": "server_vad" }
  }
}
turn_detection.typeChi decide la fine del turnoCosa invii
"server_vad"Il serverinput_audio_buffer.append, nient’altro
nullTuinput_audio_buffer.append, poi input_audio_buffer.commit e response.create

In modalità server_vad, il server divide i turni, conferma l’audio e avvia la risposta. Anche le interruzioni sono gestite automaticamente: xAI consiglia questa modalità per un’alternanza naturale dei turni, ad esempio quando l’utente interrompe l’agente a metà frase. La documentazione non offre tuttavia impostazioni per la sensibilità o la durata del silenzio: la divisione dei turni spetta esclusivamente al server.

Eventi VAD

Con server_vad, il server segnala ogni transizione:

  • input_audio_buffer.speech_started: il VAD ha rilevato l’inizio del parlato;
  • input_audio_buffer.speech_stopped: ha rilevato la fine;
  • input_audio_buffer.committed: l’audio è stato confermato come messaggio dell’utente.
ws.on("message", (data) => {
  const event = JSON.parse(data);
  switch (event.type) {
    case "input_audio_buffer.speech_started":
      stopPlayback();       // l'utente sta parlando: ferma l'audio dell'agente già ricevuto
      break;
    case "input_audio_buffer.speech_stopped":
      showThinking();       // fine del parlato rilevata: la risposta sta arrivando
      break;
  }
});

Lato server, l’interruzione è automatica; lato client, l’audio già ricevuto continuerebbe a essere riprodotto se non lo fermassi. speech_started è il momento giusto per svuotare la coda di riproduzione.

Sollecitare un utente silenzioso: idle_timeout_ms

L’unica impostazione documentata relativa al VAD, idle_timeout_ms, fa sì che l’agente riprenda la conversazione quando l’utente rimane in silenzio dopo una risposta:

{
  "type": "session.update",
  "session": {
    "turn_detection": { "type": "server_vad", "idle_timeout_ms": 8000 }
  }
}

Se non viene rilevato alcun parlato per quel lasso di tempo dopo la fine di una risposta, il server emette input_audio_buffer.timeout_triggered, conferma un turno utente silenzioso e genera un controllo. Il timer si resetta dopo ogni risposta, quindi scatta nuovamente ogni idle_timeout_ms finché l’utente non parla. È disattivato per impostazione predefinita (null). Su un centralino telefonico, un controllo dopo pochi secondi evita che i silenzi si protraggano troppo a lungo: scrivi nelle istruzioni la frase di follow-up che l’agente dovrà usare.

Modalità manuale: turn_detection.type impostato su null

Per un’interfaccia push-to-talk, o ogni volta che vuoi decidere tu quando finisce un turno, imposta il tipo su null:

{
  "type": "session.update",
  "session": {
    "turn_detection": { "type": null }
  }
}

Invii quindi l’audio con input_audio_buffer.append e, quando l’utente rilascia il pulsante, invii input_audio_buffer.commit per confermare il turno e response.create per richiedere la risposta. input_audio_buffer.commit è disponibile solo in modalità manuale. input_audio_buffer.clear scarta l’audio inviato ma non ancora confermato, mentre response.cancel interrompe una risposta in corso, poiché l’interruzione non è più automatica in modalità manuale.

Scegli la tua modalità

  • Conversazione fluida (assistente, centralino telefonico, chiosco): server_vad, con idle_timeout_ms per sollecitare gli utenti silenziosi se necessario.
  • Walkie-talkie, dettatura, ambienti molto rumorosi: modalità manuale, dove la fine del turno segue la pressione del pulsante e il rumore di fondo non attiva più nulla.

Punti chiave

  • turn_detection.type può essere "server_vad" (il server divide i turni e gestisce le interruzioni) oppure null (modalità manuale)
  • La documentazione di xAI non offre soglie di sensibilità o durate del silenzio da configurare
  • speech_started, speech_stopped e committed segnalano le transizioni del VAD
  • idle_timeout_ms sollecita un utente silenzioso, tramite l’evento input_audio_buffer.timeout_triggered
  • In modalità manuale: append, poi commit e response.create