VAD: rilevamento automatico della voce
In questa pagina
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"onull) 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.type | Chi decide la fine del turno | Cosa invii |
|---|---|---|
"server_vad" | Il server | input_audio_buffer.append, nient’altro |
null | Tu | input_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, conidle_timeout_msper 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.typepuò essere"server_vad"(il server divide i turni e gestisce le interruzioni) oppurenull(modalità manuale)- La documentazione di xAI non offre soglie di sensibilità o durate del silenzio da configurare
speech_started,speech_stoppedecommittedsegnalano le transizioni del VADidle_timeout_mssollecita un utente silenzioso, tramite l’eventoinput_audio_buffer.timeout_triggered- In modalità manuale:
append, poicommiteresponse.create