Äänimuodot: PCM ja G.711
Tällä sivulla
Päivitetty 3. marraskuuta 2026 xAI:n Speech to Speech -sivun perusteella: API hyväksyy neljännen koodekin,
audio/opus(raakat Opus-paketit, 24 kHz mono), ja toisen siirtotilan,binary, joka lähettää äänen binäärisinä WebSocket-kehyksinä JSONiin koodatun base64:n sijaan. Lähde: Speech to Speech, Audio and Audio Transport.
Tuetut äänimuodot
Voice Agent API tukee neljää äänimuotoa sekä syötteelle että tulosteelle: PCM, G.711 μ-law, G.711 A-law ja Opus. Valintasi riippuu käyttötarkoituksestasi: verkkosovellus, puhelinliikenne vai ammattimainen äänenkäsittely.
| Format | Encoding | Sample rates | Typical use |
|---|---|---|---|
| audio/pcm | Linear16, little-endian | 8000–48000 Hz | Web apps, audio processing |
| audio/pcmu | G.711 mu-law | 8000 Hz only | North American telephony |
| audio/pcma | G.711 A-law | 8000 Hz only | European / international telephony |
| audio/opus | Opus (raw packets) | 24000 Hz mono | Mobile, low bandwidth |
PCM (Pulse Code Modulation)
PCM on oletusmuoto ja monipuolisin vaihtoehto. Se koodaa äänen pakkaamattomina 16-bittisinä etumerkillisinä kokonaislukuina (Linear16) little-endian-järjestyksessä.
Käytettävissä olevat näytetaajuudet
API tukee PCM-formaatille seitsemää eri näytetaajuutta:
- 8000 Hz: minimaalinen puhelinklaatu
- 16000 Hz: hyvä kompromissi puheelle (laajakaista)
- 22050 Hz: keskitason laatu
- 24000 Hz: oletus, suositeltu useimpiin tapauksiin
- 32000 Hz: korkeampi laatu
- 44100 Hz: CD-laatu
- 48000 Hz: studiolaatu
Tavallisessa puhesovelluksessa 24000 Hz tarjoaa parhaan tasapainon laadun ja kaistanleveyden välillä. Korkeammat taajuudet eivät tuo havaittavaa parannusta puheen toistoon.
Määritys kohdassa 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 ja A-law
G.711-koodekit ovat perinteisen puhelinliikenteen standardeja. Ne käyttävät logaritmista pakkausta pienentääkseen äänidataa säilyttäen samalla puhelinkaistan (300–3400 Hz) puheenlaadun.
mu-law (audio/pcmu)
Käytetään pääasiassa Pohjois-Amerikassa ja Japanissa; se on Pohjois-Amerikan puhelinverkkojen natiivi koodekki. Jos integroit Voice Agent API:n Yhdysvalloissa toimivaan SIP-järjestelmään, audio/pcmu on luontevin valinta.
A-law (audio/pcma)
Käytössä Euroopassa ja muualla maailmassa. Valitse audio/pcma, jos integroit eurooppalaiseen operaattoriin.
G.711:n rajoitukset
Molemmat G.711-koodekit rajoittuvat 8000 Hz:n näytetaajuuteen, mikä tarkoittaa suppeampaa äänikaistaa. Puheenlaatu riittää puhelinliikenteeseen, mutta se on heikompi kuin 24000 Hz PCM. Käytä niitä vain, jos puhelininfrastruktuurisi sitä vaatii.
Eri muodot syötteelle ja tulosteelle
API antaa sinun määrittää eri muodot syötteelle ja tulosteelle, mikä on hyödyllistä hybridiarkkitehtuureissa:
{
"type": "session.update",
"session": {
"audio": {
"input": {
"format": {"type": "audio/pcmu", "rate": 8000}
},
"output": {
"format": {"type": "audio/pcm", "rate": 24000}
}
}
}
}
Tässä esimerkissä vastaanotat G.711 mu-law -signaalia puhelinjärjestelmästä ja lähetät korkealaatuista PCM-dataa takaisin lähetysjärjestelmään.
Opus
Neljäs koodekki, audio/opus, kuljettaa raakoja Opus-paketteja taajuudella 24 000 Hz monona, yksi paketti kuormaa kohden, ilman säiliön otsikkotietoja. Se on pakattu koodekki: se leikkaa kaistanleveyttä jyrkästi verrattuna PCM:ään, mikä on tärkeää mobiiliyhteyksillä, edellyttäen että asiakasohjelmasi osaa koodata ja purkaa Opusta.
Siirto: JSON tai binääri
Koodekki (format) määrittää, miten ääni koodataan; siirtotapa (transport) määrittää, miten nämä tavut kulkevat WebSocketin yli. Oletuksena ("json") ääni on base64-koodattuna kentissä input_audio_buffer.append ja response.output_audio.delta. Arvolla "binary" se lähetetään binäärisinä WebSocket-kehyksinä ilman base64-koodausta tai otsikoita; elinkaaren tapahtumat (response.created, response.done, transkriptiot) pysyvät JSON-muodossa.
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) # binary frame: raw 16-bit PCM, no base64
async for message in ws:
if isinstance(message, bytes):
player.write(message) # the assistant's audio
else:
event = json.loads(message) # JSON event
Dokumentaatio asettaa kaksi sääntöä. Syötteessä, kun formaatti on määritetty, palvelin hyväksyy molemmat polut samanaikaisesti: input.transport ilmoittaa vain ensisijaisen polkusi. Tulosteessa ääni saapuu ainoastaan output.transport-määrittelyn kautta, ja muutos kesken istunnon vaikuttaa vasta seuraavasta vastauksesta alkaen, joten yksittäinen puhejakso ei koskaan sekoita JSONia ja binääridataa. Binäärimuoto välttää base64:n ylikuorman, joka kasvattaa datamäärää noin kolmanneksella.
Keskeiset asiat
- Oletusmuoto on 24000 Hz PCM, ihanteellinen verkkosovelluksille
- G.711 mu-law (pcmu) on Pohjois-Amerikan puhelinstandardi
- G.711 A-law (pcma) on eurooppalainen puhelinstandardi
- G.711-koodekit rajoittuvat 8000 Hz:n taajuuteen
- Voit käyttää eri muotoja syötteelle ja tulosteelle
audio/opus(24 kHz mono) vähentää kaistanleveyttä;transport: "binary"lähettää äänen binäärikehyksinä ilman base64-koodausta- Puheelle 24000 Hz on paras kompromissi laadun ja kaistanleveyden välillä