Zum Hauptinhalt springen
Deutsch— Sprache auswählen
Menü

Audio-Buffer festlegen und leeren

Lektion 8 von 16 Aktualisiert am 3. November 2026 Entwickler
Auf dieser Seite
  1. Verwaltung des Audio-Buffers
  2. input_audio_buffer.commit
  3. input_audio_buffer.clear
  4. VAD-Modus versus manueller Modus
  5. Kernaussagen

Aktualisiert am 3. November 2026, basierend auf der xAI Voice API-Referenz: input_audio_buffer.commit steht nur zur Verfügung, wenn turn_detection.type auf null gesetzt ist. Im server_vad-Modus übernimmt der Server das Festlegen des Audios selbst. Quelle: Voice API.

Verwaltung des Audio-Buffers

Wenn Sie Audio mit input_audio_buffer.append senden, wird die Datenmenge in einem Puffer auf dem Server angesammelt. Zwei Operationen steuern diesen Puffer: commit, um den Inhalt als Benutzernachricht einzureichen, und clear, um ihn ohne Verarbeitung zu leeren.

input_audio_buffer.commit

Dieses Ereignis legt den aktuellen Inhalt des Audio-Buffers als Benutzernachricht fest. Es ist im manuellen Modus (Push-to-Talk) erforderlich und im VAD-Modus automatisch:

{
  "type": "input_audio_buffer.commit"
}

Wenn der Server ein Commit-Ereignis empfängt, führt er folgende Schritte aus:

  1. Er erstellt einen neuen Gesprächsartikel mit dem angesammelten Audio.
  2. Er sendet ein input_audio_buffer.committed-Ereignis zur Bestätigung.
  3. Er sendet ein conversation.item.added-Ereignis mit dem neuen Artikel.
  4. Er beginnt mit der Transkription des Audios (sofern aktiviert).

Die Antwort des Servers

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

Mit der item_id können Sie diese Nachricht später im Gespräch referenzieren.

Wann man manuell festlegt

  • Push-to-Talk: Der Benutzer hält eine Taste zum Sprechen gedrückt und gibt sie los, um zu senden.
  • Manuelle Segmentierung: Sie teilen den Audio-Stream auf dem Client in logische Segmente auf.
  • Telefonintegration: Sie erhalten Audio-Blöcke von einer PBX und legen sie am Ende jeder Runde fest.
// Beispiel für Push-to-Talk
talkButton.addEventListener("mousedown", () => {
  isRecording = true;
  startCapture();
});

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

  // Den Puffer festlegen
  ws.send(JSON.stringify({
    type: "input_audio_buffer.commit"
  }));

  // Eine Antwort anfordern
  ws.send(JSON.stringify({
    type: "response.create"
  }));
});

input_audio_buffer.clear

Dieses Ereignis leert den Audio-Buffer, ohne eine Nachricht im Gespräch zu erstellen:

{
  "type": "input_audio_buffer.clear"
}

Der Server bestätigt dies mit:

{
  "type": "input_audio_buffer.cleared"
}

Wann man leert

  • Abbruch: Der Benutzer drückt eine „Abbrechen”-Taste, während er spricht.
  • Unterbrechung: Der Benutzer beginnt zu sprechen, und ein anderes Ereignis unterbricht die Runde.
  • Neustart: Nach einem Fehler oder einem Timeout den Puffer leeren, bevor man von vorne beginnt.
  • Hintergrundgeräusche: Das System erkennt, dass der Puffer nur Rauschen und keine Sprache enthält.
cancelButton.addEventListener("click", () => {
  stopCapture();
  ws.send(JSON.stringify({
    type: "input_audio_buffer.clear"
  }));
  showMessage("Aufnahme abgebrochen");
});

VAD-Modus versus manueller Modus

Im VAD-Modus (server_vad) übernimmt der Server den gesamten Zyklus automatisch:

  1. Er erkennt den Beginn der Sprache (speech_started).
  2. Er sammelt das Audio im Puffer.
  3. Er erkennt das Ende der Sprache (speech_stopped).
  4. Er legt den Puffer automatisch fest.
  5. Er beginnt automatisch mit der Generierung der Antwort.

Im manuellen Modus (turn_detection.type auf null gesetzt) führen Sie jeden Schritt selbst aus, und dies ist der einzige Modus, in dem input_audio_buffer.commit verfügbar ist:

  1. Sie senden Audio mit append.
  2. Sie entscheiden, wann der Benutzer fertig ist.
  3. Sie senden commit.
  4. Sie senden response.create.

Vergleich

AspektVAD-ModusManueller Modus
SpracherkennungAutomatischIn Ihrer Verantwortung
Puffer festlegenAutomatischManuell (commit)
AntwortanfrageAutomatischManuell (response.create)
KontrolleWeniger KontrolleVolle Kontrolle
KomplexitätEinfachKomplexer
AnwendungsfälleFreier GesprächsverlaufPush-to-Talk, IVR

Kernaussagen

  • input_audio_buffer.commit reicht den Audio-Buffer als Benutzernachricht ein.
  • input_audio_buffer.clear leert den Puffer ohne Verarbeitung.
  • Im VAD-Modus erfolgt das Festlegen automatisch, wenn das Ende der Sprache erkannt wird.
  • Im manuellen Modus (turn_detection.type auf null gesetzt) müssen Sie commit und anschließend response.create explizit senden; commit steht nur in diesem Modus zur Verfügung.
  • Der manuelle Modus eignet sich für Push-to-Talk-Oberflächen und IVR-Telefonsysteme.