Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Formati audio: PCM e G.711

Lezione 5 di 16 Aggiornata il 3 novembre 2026 Sviluppatore
In questa pagina
  1. Formati audio supportati
  2. PCM (Pulse Code Modulation)
  3. G.711: mu-law e A-law
  4. Formati di input e output diversi
  5. Opus
  6. Trasporto: JSON o binario
  7. Punti chiave

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