Formati audio: PCM e G.711
In questa pagina
Aggiornato il 3 novembre 2026, sulla base della pagina Speech to Speech di xAI: l’API accetta un quarto codec,
audio/opus(pacchetti Opus grezzi, 24 kHz mono), e una seconda modalità di trasporto,binary, che invia l’audio come frame WebSocket binari invece che in base64 all’interno di JSON. Fonte: Speech to Speech, Audio and Audio Transport.
Formati audio supportati
L’API Voice Agent supporta quattro formati audio per l’input e l’output: PCM, G.711 μ-law, G.711 A-law e Opus. La scelta dipende dal tuo caso d’uso: un’app web, la telefonia o l’elaborazione audio professionale.
| Formato | Codifica | Frequenze di campionamento | Uso tipico |
|---|---|---|---|
| audio/pcm | Linear16, little-endian | 8000–48000 Hz | App web, elaborazione audio |
| audio/pcmu | G.711 mu-law | Solo 8000 Hz | Telefonia nordamericana |
| audio/pcma | G.711 A-law | Solo 8000 Hz | Telefonia europea / internazionale |
| audio/opus | Opus (pacchetti grezzi) | 24000 Hz mono | Mobile, bassa larghezza di banda |
PCM (Pulse Code Modulation)
Il PCM è il formato predefinito e più versatile. Codifica l’audio come interi con segno a 16 bit non compressi (Linear16) in ordine little-endian.
Frequenze di campionamento disponibili
L’API supporta sette frequenze di campionamento per il PCM:
- 8000 Hz: qualità telefonica minima
- 16000 Hz: un buon compromesso per la voce (wideband)
- 22050 Hz: qualità intermedia
- 24000 Hz: il predefinito, raccomandato per la maggior parte dei casi
- 32000 Hz: qualità superiore
- 44100 Hz: qualità CD
- 48000 Hz: qualità da studio
Per un’app vocale standard, 24000 Hz offre il miglior equilibrio tra qualità e larghezza di banda. Andare oltre non porta miglioramenti percettibili per la voce.
Configurazione in 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
I codec G.711 sono gli standard della telefonia tradizionale. Utilizzano una compressione logaritmica per ridurre i dati audio mantenendo la qualità vocale nella banda telefonica (300–3400 Hz).
mu-law (audio/pcmu)
Utilizzato principalmente in Nord America e Giappone, è il codec nativo delle reti telefoniche nordamericane. Se integri l’API Voice Agent con un sistema SIP basato negli USA, audio/pcmu è la scelta naturale.
A-law (audio/pcma)
Utilizzato in Europa e nel resto del mondo. Per un’integrazione con un operatore telefonico europeo, scegli audio/pcma.
Limitazioni del G.711
Entrambi i codec G.711 sono limitati a 8000 Hz, il che significa una larghezza di banda audio ridotta. La qualità vocale è adeguata per la telefonia ma inferiore al PCM a 24000 Hz. Usali solo se la tua infrastruttura telefonica lo richiede.
Formati di input e output diversi
L’API ti consente di configurare formati diversi per input e output, utile nelle architetture ibride:
{
"type": "session.update",
"session": {
"audio": {
"input": {
"format": {"type": "audio/pcmu", "rate": 8000}
},
"output": {
"format": {"type": "audio/pcm", "rate": 24000}
}
}
}
}
In questo esempio, ricevi G.711 mu-law da un sistema telefonico e invii PCM ad alta qualità a un sistema di diffusione.
Opus
Il quarto codec, audio/opus, trasporta pacchetti Opus grezzi a 24.000 Hz mono, un pacchetto per payload, senza header di contenitore. È un codec compresso: riduce drasticamente la larghezza di banda rispetto al PCM, cosa fondamentale su una connessione mobile, purché il tuo client possa codificare e decodificare Opus.
Trasporto: JSON o binario
Il codec (format) definisce come l’audio è codificato; il trasporto (transport) definisce come questi byte viaggiano sul WebSocket. Per impostazione predefinita ("json"), l’audio è codificato in base64 all’interno di input_audio_buffer.append e response.output_audio.delta. Con "binary", viene inviato come frame WebSocket binari, senza base64 e senza header; gli eventi del ciclo di vita (response.created, response.done, trascrizioni) rimangono in 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 binario: PCM grezzo a 16 bit, nessun base64
async for message in ws:
if isinstance(message, bytes):
player.write(message) # audio dell'assistente
else:
event = json.loads(message) # evento JSON
La documentazione stabilisce due regole. In input, una volta configurato il formato, il server accetta entrambi i percorsi contemporaneamente: input.transport indica solo il tuo percorso preferito. In output, l’audio arriva solo tramite output.transport e una modifica a metà sessione si applica solo dalla risposta successiva, quindi un singolo enunciato non mescola mai JSON e binario. Il binario evita l’overhead del base64, che aggiunge circa un terzo al volume dei dati.
Punti chiave
- Il formato predefinito è PCM a 24000 Hz, ideale per le app web
- G.711 mu-law (pcmu) è lo standard telefonico nordamericano
- G.711 A-law (pcma) è lo standard telefonico europeo
- I codec G.711 sono limitati a 8000 Hz
- Puoi usare formati diversi per input e output
audio/opus(24 kHz mono) riduce la larghezza di banda;transport: "binary"invia l’audio come frame binari, senza base64- Per la voce, 24000 Hz è il miglior compromesso tra qualità e larghezza di banda