Formatos de áudio: PCM e G.711
Nesta página
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