Przejdź do głównej treści
Polski— Wybierz język
Menu

Zatwierdzanie i czyszczenie bufora audio

Lekcja 8 z 16 Zaktualizowano 3 listopada 2026 Programista
Na tej stronie
  1. Zarządzanie buforem audio
  2. input_audio_buffer.commit
  3. input_audio_buffer.clear
  4. Tryb VAD a tryb ręczny
  5. Kluczowe wnioski

Zaktualizowano 3 listopada 2026 r. na podstawie dokumentacji referencyjnej xAI Voice API: input_audio_buffer.commit jest dostępne wyłącznie, gdy turn_detection.type ma wartość null; w trybie server_vad serwer sam zatwierdza audio. Źródło: Voice API.

Zarządzanie buforem audio

Gdy wysyłasz dane audio za pomocą input_audio_buffer.append, są one gromadzone w buforze na serwerze. Dwie operacje kontrolują ten bufor: commit (zatwierdź), aby przesłać jego zawartość jako wiadomość użytkownika, oraz clear (wyczyść), aby opróżnić go bez przetwarzania.

input_audio_buffer.commit

To zdarzenie zatwierdza bieżącą zawartość bufora audio jako wiadomość użytkownika. Jest wymagane w trybie ręcznym (push-to-talk) i automatyczne w trybie VAD:

{
  "type": "input_audio_buffer.commit"
}

Gdy serwer otrzyma polecenie zatwierdzenia:

  1. Tworzy nowy element konwersacji z nagromadzonym audio
  2. Wysyła zdarzenie input_audio_buffer.committed jako potwierdzenie
  3. Wysyła zdarzenie conversation.item.added z nowym elementem
  4. Rozpoczyna transkrypcję audio (jeśli jest włączona)

Odpowiedź serwera

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

Pole item_id pozwala odwołać się do tej wiadomości w konwersacji w późniejszym czasie.

Kiedy zatwierdzać ręcznie

  • Push-to-talk: użytkownik przytrzymuje przycisk, aby mówić, i puszcza go, aby wysłać nagranie
  • Ręczna segmentacja: dzielisz strumień audio na logiczne segmenty po stronie klienta
  • Integracja telefoniczna: otrzymujesz fragmenty audio z centrali PBX i zatwierdzasz je na końcu każdej tury rozmowy
// Przykład push-to-talk
talkButton.addEventListener("mousedown", () => {
  isRecording = true;
  startCapture();
});

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

  // Zatwierdź bufor
  ws.send(JSON.stringify({
    type: "input_audio_buffer.commit"
  }));

  // Żądaj odpowiedzi
  ws.send(JSON.stringify({
    type: "response.create"
  }));
});

input_audio_buffer.clear

To zdarzenie opróżnia bufor audio bez tworzenia wiadomości w konwersacji:

{
  "type": "input_audio_buffer.clear"
}

Serwer potwierdza to wysyłając:

{
  "type": "input_audio_buffer.cleared"
}

Kiedy czyścić bufor

  • Anulowanie: użytkownik naciska przycisk „Anuluj“ podczas mówienia
  • Przerwanie: użytkownik zaczyna mówić, ale inne zdarzenie przerywa turę
  • Reset: po błędzie lub upływie czasu wyczyść bufor przed rozpoczęciem od nowa
  • Szum tła: system wykrywa, że bufor zawiera tylko szum, a nie mowę
cancelButton.addEventListener("click", () => {
  stopCapture();
  ws.send(JSON.stringify({
    type: "input_audio_buffer.clear"
  }));
  showMessage("Nagrywanie anulowane");
});

Tryb VAD a tryb ręczny

W trybie VAD (server_vad) serwer obsługuje cały cykl automatycznie:

  1. Wykrywa początek mowy (speech_started)
  2. Gromadzi audio w buforze
  3. Wykrywa koniec mowy (speech_stopped)
  4. Automatycznie zatwierdza bufor
  5. Automatycznie rozpoczyna generowanie odpowiedzi

W trybie ręcznym (gdy turn_detection.type jest ustawione na null) samodzielnie obsługujesz każdy krok; jest to jedyny tryb, w którym dostępne jest input_audio_buffer.commit:

  1. Wysyłasz audio za pomocą append
  2. Decydujesz, kiedy użytkownik skończył mówić
  3. Wysyłasz commit
  4. Wysyłasz response.create

Porównanie

AspektTryb VADTryb ręczny
Wykrywanie mowyAutomatyczneZależy od Ciebie
Zatwierdzanie buforaAutomatyczneRęczne (commit)
Żądanie odpowiedziAutomatyczneRęczne (response.create)
KontrolaMniejsza kontrolaPełna kontrola
ZłożonośćProsteBardziej złożone
Przypadki użyciaSwobodna rozmowaPush-to-talk, IVR

Kluczowe wnioski

  • input_audio_buffer.commit przesyła bufor audio jako wiadomość użytkownika
  • input_audio_buffer.clear opróżnia bufor bez przetwarzania
  • W trybie VAD zatwierdzenie następuje automatycznie po wykryciu końca mowy
  • W trybie ręcznym (gdy turn_detection.type jest ustawione na null) musisz jawnie wysłać commit, a następnie response.create; polecenie commit jest dostępne tylko w tym trybie
  • Tryb ręczny sprawdza się w interfejsach push-to-talk i telefonicznych systemach IVR