Valider et vider le buffer audio

Leçon complétée le 3 novembre 2026 d’après la référence de l’API Voice de xAI : input_audio_buffer.commit n’est disponible que lorsque turn_detection.type vaut null ; en mode server_vad, le serveur valide lui-même l’audio. Source : Voice API.

Gestion du buffer audio

Lorsque vous envoyez de l’audio avec input_audio_buffer.append, les données sont accumulées dans un buffer côté serveur. Deux opérations permettent de contrôler ce buffer : commit pour valider le contenu comme un message utilisateur, et clear pour le vider sans traitement.

input_audio_buffer.commit

Cet événement valide le contenu actuel du buffer audio comme un message de l’utilisateur. Il est obligatoire en mode sans VAD (push-to-talk) et automatique en mode VAD :

{
  "type": "input_audio_buffer.commit"
}

Lorsque le serveur reçoit un commit, il :

1. Crée un nouvel élément de conversation avec l’audio accumulé
2. Envoie un événement input_audio_buffer.committed pour confirmer
3. Envoie un événement conversation.item.added avec le nouvel élément
4. Lance la transcription de l’audio (si activée)

Réponse du serveur

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

L’identifiant item_id vous permet de référencer ce message dans la conversation par la suite.

Quand utiliser commit manuellement

• Mode push-to-talk : l’utilisateur appuie sur un bouton pour parler, relâche pour envoyer
• Segmentation manuelle : vous découpez le flux audio en segments logiques côté client
• Intégration téléphonique : vous recevez des chunks audio d’un PBX et les validez à la fin de chaque tour

// Exemple push-to-talk
talkButton.addEventListener("mousedown", () => {
  isRecording = true;
  startCapture();
});

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

  // Valider le buffer
  ws.send(JSON.stringify({
    type: "input_audio_buffer.commit"
  }));

  // Demander une réponse
  ws.send(JSON.stringify({
    type: "response.create"
  }));
});

input_audio_buffer.clear

Cet événement vide le buffer audio sans créer de message dans la conversation :

{
  "type": "input_audio_buffer.clear"
}

Le serveur confirme avec :

{
  "type": "input_audio_buffer.cleared"
}

Cas d’usage du clear

• Annulation : l’utilisateur appuie sur un bouton “Annuler” pendant qu’il parle
• Interruption : l’utilisateur commence à parler puis l’agent est interrompu par un autre événement
• Réinitialisation : après une erreur ou un timeout, vider le buffer avant de recommencer
• Bruit parasite : le système détecte que le buffer ne contient que du bruit (pas de parole)

cancelButton.addEventListener("click", () => {
  stopCapture();
  ws.send(JSON.stringify({
    type: "input_audio_buffer.clear"
  }));
  showMessage("Enregistrement annulé");
});

Différence entre mode VAD et mode manuel

En mode VAD (server_vad), le serveur gère automatiquement le cycle complet :

1. Il détecte le début de la parole (speech_started)
2. Il accumule l’audio dans le buffer
3. Il détecte la fin de la parole (speech_stopped)
4. Il commit automatiquement le buffer
5. Il lance automatiquement la génération de réponse

En mode manuel (turn_detection.type à null), vous devez gérer chaque étape — et c’est le seul mode où input_audio_buffer.commit est disponible :

1. Vous envoyez l’audio avec append
2. Vous décidez quand l’utilisateur a fini
3. Vous envoyez commit
4. Vous envoyez response.create

Comparaison

Points clés à retenir

• input_audio_buffer.commit valide le buffer audio comme un message utilisateur
• input_audio_buffer.clear vide le buffer sans traitement
• En mode VAD, le commit est automatique à la fin de la parole détectée
• En mode manuel (turn_detection.type à null), vous devez envoyer commit puis response.create explicitement ; commit n’est disponible que dans ce mode
• Le mode manuel convient aux interfaces push-to-talk et aux systèmes téléphoniques IVR