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

Receber e reproduzir o áudio da resposta

Aula 11 de 16 Atualizada a 30 de julho de 2026 Programador
Nesta página
  1. Reprodução em streaming
  2. Arquitetura do leitor de áudio
  3. Ligar aos eventos do WebSocket
  4. Gestão de interrupções
  5. Leitor de áudio em Python
  6. Exibir a transcrição em simultâneo
  7. Pontos-chave

Reprodução em streaming

Quando o agente de voz gera uma resposta, o áudio chega em fragmentos codificados em base64 (deltas). A sua aplicação tem de os descodificar, colocá-los numa fila e reproduzi-los de forma fluida, para que o utilizador ouça uma resposta contínua, sem interrupções.

Arquitetura do leitor de áudio

O princípio é simples: cada delta de áudio recebido é descodificado e adicionado a uma fila. Um processo de reprodução consome essa fila e envia os dados para a saída de áudio do sistema:

class AudioStreamPlayer {
  constructor(sampleRate = 24000) {
    this.audioContext = new AudioContext({ sampleRate });
    this.queue = [];
    this.isPlaying = false;
    this.nextPlayTime = 0;
  }

  enqueue(pcm16ArrayBuffer) {
    // Convert PCM16 to Float32 for the Web Audio API
    const pcm16 = new Int16Array(pcm16ArrayBuffer);
    const float32 = new Float32Array(pcm16.length);
    for (let i = 0; i < pcm16.length; i++) {
      float32[i] = pcm16[i] / 32768.0;
    }

    const buffer = this.audioContext.createBuffer(
      1, float32.length, this.audioContext.sampleRate
    );
    buffer.getChannelData(0).set(float32);

    this.queue.push(buffer);
    if (!this.isPlaying) this.playNext();
  }

  playNext() {
    if (this.queue.length === 0) {
      this.isPlaying = false;
      return;
    }

    this.isPlaying = true;
    const buffer = this.queue.shift();
    const source = this.audioContext.createBufferSource();
    source.buffer = buffer;
    source.connect(this.audioContext.destination);

    const now = this.audioContext.currentTime;
    const startTime = Math.max(now, this.nextPlayTime);
    source.start(startTime);
    this.nextPlayTime = startTime + buffer.duration;

    source.onended = () => this.playNext();
  }

  stop() {
    this.queue = [];
    this.isPlaying = false;
    this.nextPlayTime = 0;
  }
}

Ligar aos eventos do WebSocket

Eis como conectar o leitor de áudio aos eventos da API:

const player = new AudioStreamPlayer(24000);

ws.on("message", (data) => {
  const event = JSON.parse(data);

  switch (event.type) {
    case "response.output_audio.delta":
      const audioBytes = base64ToArrayBuffer(event.delta);
      player.enqueue(audioBytes);
      break;

    case "response.output_audio.done":
      console.log("Audio response complete");
      break;

    case "input_audio_buffer.speech_started":
      // The user interrupts the agent
      player.stop();
      ws.send(JSON.stringify({ type: "response.cancel" }));
      break;
  }
});

function base64ToArrayBuffer(base64) {
  const binary = atob(base64);
  const bytes = new Uint8Array(binary.length);
  for (let i = 0; i < binary.length; i++) {
    bytes[i] = binary.charCodeAt(i);
  }
  return bytes.buffer;
}

Gestão de interrupções

Numa conversa natural, o utilizador pode interromper o agente falando por cima da resposta. A sua aplicação tem de gerir essa situação:

  1. Detetar a interrupção: o evento speech_started chega enquanto o áudio está a ser reproduzido.
  2. Parar a reprodução: esvaziar a fila de áudio e interromper o som.
  3. Cancelar a resposta: enviar response.cancel para que o servidor pare de gerar conteúdo.
  4. Ouvir: o utilizador tem a palavra e o ciclo recomeça.

Este mecanismo de «barge-in» (interrupção) é essencial para uma conversa fluida. Sem ele, os utilizadores teriam de esperar que o agente terminasse de falar antes de poderem responder.

Leitor de áudio em Python

Para uma aplicação em Python, pode utilizar a biblioteca pyaudio para a reprodução:

import pyaudio
import base64
import asyncio
from collections import deque

class AudioPlayer:
    def __init__(self, rate=24000):
        self.p = pyaudio.PyAudio()
        self.stream = self.p.open(
            format=pyaudio.paInt16,
            channels=1,
            rate=rate,
            output=True
        )
        self.queue = deque()

    def enqueue(self, base64_audio):
        audio_bytes = base64.b64decode(base64_audio)
        self.queue.append(audio_bytes)

    def play_all(self):
        while self.queue:
            chunk = self.queue.popleft()
            self.stream.write(chunk)

    def stop(self):
        self.queue.clear()

Exibir a transcrição em simultâneo

Enquanto o áudio é reproduzido, pode apresentar a transcrição da resposta em tempo real através dos eventos response.output_audio_transcript.delta. Desta forma, os utilizadores podem ler o que o agente está a dizer, o que é útil em ambientes ruidosos e para fins de acessibilidade:

let currentTranscript = "";

case "response.output_audio_transcript.delta":
  currentTranscript += event.delta;
  updateTranscriptDisplay(currentTranscript);
  break;

Pontos-chave

  • O áudio da resposta chega em fragmentos base64 através de response.output_audio.delta
  • Utilize uma fila de áudio para garantir uma reprodução contínua, sem falhas
  • Gestione as interrupções (barge-in) parando a reprodução e cancelando a resposta
  • Apresente a transcrição juntamente com o áudio para melhorar a acessibilidade
  • A Web Audio API do navegador requer uma conversão de base64 para PCM16 e depois para Float32