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

Formatos de áudio: PCM e G.711

Aula 5 de 16 Atualizada a 3 de novembro de 2026 Programador
Nesta página
  1. Formatos de áudio suportados
  2. PCM (Modulação por Código de Pulso)
  3. G.711: mu-law e A-law
  4. Formatos de entrada e saída diferentes
  5. Opus
  6. Transporte: JSON ou binário
  7. Pontos-chave

Atualizado a 3 de novembro de 2026, com base na página Speech to Speech da xAI: a API aceita um quarto codec, audio/opus (pacotes Opus brutos, mono a 24 kHz), e um segundo modo de transporte, binary, que envia áudio como frames binários de WebSocket em vez de base64 dentro de JSON. Fonte: Speech to Speech, Audio and Audio Transport.

Formatos de áudio suportados

A API do Voice Agent suporta quatro formatos de áudio para entrada e saída: PCM, G.711 μ-law, G.711 A-law e Opus. A escolha depende do seu caso de uso: uma aplicação web, telefonia ou processamento de áudio profissional.

Formato Codificação Taxas de amostragem Uso típico
audio/pcm Linear16, little-endian 8000–48000 Hz Aplicações web, processamento de áudio
audio/pcmu G.711 mu-law Apenas 8000 Hz Telefonia norte-americana
audio/pcma G.711 A-law Apenas 8000 Hz Telefonia europeia / internacional
audio/opus Opus (pacotes brutos) 24000 Hz mono Telemóveis, largura de banda reduzida

PCM (Modulação por Código de Pulso)

O PCM é o formato padrão e o mais versátil. Codifica o áudio como inteiros com sinal de 16 bits não comprimidos (Linear16) em ordem little-endian.

Taxas de amostragem disponíveis

A API suporta sete taxas de amostragem para PCM:

  • 8000 Hz: qualidade telefónica mínima
  • 16000 Hz: um bom compromisso para voz (banda larga)
  • 22050 Hz: qualidade intermédia
  • 24000 Hz: o padrão, recomendado para a maioria dos casos
  • 32000 Hz: qualidade superior
  • 44100 Hz: qualidade de CD
  • 48000 Hz: qualidade de estúdio

Para uma aplicação de voz standard, 24000 Hz oferece o melhor equilíbrio entre qualidade e largura de banda. Aumentar mais não traz melhorias perceptíveis para a fala.

Configuração em session.update

{
  "type": "session.update",
  "session": {
    "audio": {
      "input": {
        "format": {"type": "audio/pcm", "rate": 24000}
      },
      "output": {
        "format": {"type": "audio/pcm", "rate": 24000}
      }
    }
  }
}

G.711: mu-law e A-law

Os codecs G.711 são os padrões da telefonia tradicional. Utilizam compressão logarítmica para reduzir os dados de áudio, preservando a qualidade da voz dentro da banda telefónica (300–3400 Hz).

mu-law (audio/pcmu)

Utilizado principalmente na América do Norte e no Japão, é o codec nativo das redes telefónicas norte-americanas. Se estiver a integrar a API do Voice Agent com um sistema SIP baseado nos EUA, audio/pcmu é a escolha natural.

A-law (audio/pcma)

Utilizado na Europa e no resto do mundo. Para uma integração com um operador telefónico europeu, opte por audio/pcma.

Limitações do G.711

Ambos os codecs G.711 estão limitados a 8000 Hz, o que significa uma largura de banda de áudio reduzida. A qualidade de voz é adequada para telefonia, mas inferior ao PCM a 24000 Hz. Utilize-os apenas quando a sua infraestrutura telefónica o exigir.

Formatos de entrada e saída diferentes

A API permite configurar formatos diferentes para entrada e saída, o que é útil em arquiteturas híbridas:

{
  "type": "session.update",
  "session": {
    "audio": {
      "input": {
        "format": {"type": "audio/pcmu", "rate": 8000}
      },
      "output": {
        "format": {"type": "audio/pcm", "rate": 24000}
      }
    }
  }
}

Neste exemplo, recebe G.711 mu-law de um sistema telefónico e envia PCM de alta qualidade de volta para um sistema de difusão.

Opus

O quarto codec, audio/opus, transporta pacotes Opus brutos a 24.000 Hz mono, um pacote por carga útil, sem cabeçalho de contentor. É um codec comprimido: reduz drasticamente a largura de banda em comparação com o PCM, o que é crucial numa ligação móvel, desde que o seu cliente consiga codificar e descodificar Opus.

Transporte: JSON ou binário

O codec (format) define como o áudio é codificado; o transporte (transport) define como esses bytes viajam através do WebSocket. Por padrão ("json"), o áudio é codificado em base64 dentro de input_audio_buffer.append e response.output_audio.delta. Com "binary", sai como frames de WebSocket binários, sem base64 nem cabeçalho; os eventos do ciclo de vida (response.created, response.done, transcrições) permanecem em JSON.

await ws.send(json.dumps({
    "type": "session.update",
    "session": {
        "audio": {
            "input": {"format": {"type": "audio/pcm", "rate": 24000}, "transport": "binary"},
            "output": {"format": {"type": "audio/pcm", "rate": 24000}, "transport": "binary"},
        }
    },
}))

await ws.send(pcm16_bytes)  # frame binário: PCM de 16 bits bruto, sem base64

async for message in ws:
    if isinstance(message, bytes):
        player.write(message)           # áudio do assistente
    else:
        event = json.loads(message)     # evento JSON

A documentação estabelece duas regras. Na entrada, uma vez configurado o formato, o servidor aceita ambos os caminhos simultaneamente: input.transport apenas indica o seu caminho preferencial. Na saída, o áudio chega apenas através de output.transport, e uma alteração a meio da sessão só se aplica a partir da próxima resposta, pelo que uma única enunciação nunca mistura JSON e binário. O modo binário evita a sobrecarga do base64, que adiciona cerca de um terço ao volume de dados.

Pontos-chave

  • O formato padrão é PCM a 24000 Hz, ideal para aplicações web
  • G.711 mu-law (pcmu) é o padrão de telefonia norte-americano
  • G.711 A-law (pcma) é o padrão de telefonia europeu
  • Os codecs G.711 estão limitados a 8000 Hz
  • Pode utilizar formatos diferentes para entrada e saída
  • audio/opus (24 kHz mono) reduz a largura de banda; transport: "binary" envia áudio como frames binários, sem base64
  • Para voz, 24000 Hz é o melhor compromisso entre qualidade e largura de banda