Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Confirmar e limpar o buffer de áudio

Aula 8 de 16 Atualizada a 3 de novembro de 2026 Programador
Nesta página
  1. Gestão do buffer de áudio
  2. input_audio_buffer.commit
  3. input_audio_buffer.clear
  4. Modo VAD versus modo manual
  5. Pontos-chave

Atualizado em 3 de novembro de 2026, com base na referência da API de Voz da xAI: input_audio_buffer.commit só está disponível quando turn_detection.type é null; no modo server_vad, o servidor confirma o áudio automaticamente. Fonte: Voice API.

Gestão do buffer de áudio

Quando envia áudio através de input_audio_buffer.append, os dados acumulam-se num buffer no servidor. Duas operações controlam esse buffer: commit para submeter o seu conteúdo como uma mensagem do utilizador e clear para o esvaziar sem processamento.

input_audio_buffer.commit

Este evento confirma o conteúdo atual do buffer de áudio como uma mensagem do utilizador. É obrigatório no modo manual (push-to-talk) e automático no modo VAD:

{
  "type": "input_audio_buffer.commit"
}

Quando o servidor recebe um commit, ele:

  1. Cria um novo item de conversação com o áudio acumulado
  2. Envia um evento input_audio_buffer.committed para confirmar
  3. Envia um evento conversation.item.added com o novo item
  4. Inicia a transcrição do áudio (se ativada)

A resposta do servidor

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

O item_id permite-lhe referenciar esta mensagem na conversação posteriormente.

Quando confirmar manualmente

  • Push-to-talk: o utilizador mantém um botão premido para falar e solta-o para enviar
  • Segmentação manual: divide o fluxo de áudio em segmentos lógicos no cliente
  • Integração telefónica: recebe blocos de áudio de um PBX e confirma-os no final de cada turno
// Exemplo de push-to-talk
talkButton.addEventListener("mousedown", () => {
  isRecording = true;
  startCapture();
});

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

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

  // Solicitar uma resposta
  ws.send(JSON.stringify({
    type: "response.create"
  }));
});

input_audio_buffer.clear

Este evento esvazia o buffer de áudio sem criar uma mensagem na conversação:

{
  "type": "input_audio_buffer.clear"
}

O servidor confirma com:

{
  "type": "input_audio_buffer.cleared"
}

Quando limpar

  • Cancelamento: o utilizador prime o botão “Cancelar” enquanto fala
  • Interrupção: o utilizador começa a falar, mas outro evento interrompe o turno
  • Reinício: após um erro ou tempo limite, limpe o buffer antes de recomeçar
  • Ruído de fundo: o sistema deteta que o buffer contém apenas ruído, sem fala
cancelButton.addEventListener("click", () => {
  stopCapture();
  ws.send(JSON.stringify({
    type: "input_audio_buffer.clear"
  }));
  showMessage("Gravação cancelada");
});

Modo VAD versus modo manual

No modo VAD (server_vad), o servidor gere todo o ciclo automaticamente:

  1. Deteta o início da fala (speech_started)
  2. Acumula o áudio no buffer
  3. Deteta o fim da fala (speech_stopped)
  4. Confirma o buffer automaticamente
  5. Inicia a geração da resposta automaticamente

No modo manual (turn_detection.type definido como null), gere cada passo manualmente; este é o único modo onde input_audio_buffer.commit está disponível:

  1. Envia áudio com append
  2. Decide quando o utilizador terminou
  3. Envia commit
  4. Envia response.create

Comparação

AspetoModo VADModo manual
Deteção de falaAutomáticaA seu cargo
Confirmação do bufferAutomáticaManual (commit)
Pedido de respostaAutomáticoManual (response.create)
ControloMenos controloControlo total
ComplexidadeSimplesMais complexo
Casos de usoConversação fluidaPush-to-talk, IVR

Pontos-chave

  • input_audio_buffer.commit submete o buffer de áudio como uma mensagem do utilizador
  • input_audio_buffer.clear esvazia o buffer sem processamento
  • No modo VAD, a confirmação ocorre automaticamente quando é detetado o fim da fala
  • No modo manual (turn_detection.type definido como null), deve enviar explicitamente commit e depois response.create; commit só está disponível neste modo
  • O modo manual é adequado para interfaces push-to-talk e sistemas telefónicos IVR