Zvočni formati: PCM in G.711
Na tej strani
Posodobljeno 3. novembra 2026 na podlagi strani xAI Speech to Speech: API sprejema četrti kodek,
audio/opus(surovi paketi Opus, 24 kHz mono), in drugi način prenosa,binary, ki zvok pošilja kot binarne okvire WebSocket namesto base64 znotraj JSON. Vir: Speech to Speech, Audio and Audio Transport.
Podprti zvočni formati
API Voice Agent podpira štiri zvočne formate za vhod in izhod: PCM, G.711 μ-law, G.711 A-law in Opus. Izbira je odvisna od tvoje uporabe: spletna aplikacija, telefonija ali profesionalna obdelava zvoka.
| Format | Kodiranje | Frekvence vzorčenja | Tipična uporaba |
|---|---|---|---|
| audio/pcm | Linear16, little-endian | 8000–48000 Hz | Spletne aplikacije, obdelava zvoka |
| audio/pcmu | G.711 mu-law | Samo 8000 Hz | Severnoameriška telefonija |
| audio/pcma | G.711 A-law | Samo 8000 Hz | Evropska / mednarodna telefonija |
| audio/opus | Opus (surovi paketi) | 24000 Hz mono | Mobilne naprave, nizka pasovna širina |
PCM (Pulsno-kodna modulacija)
PCM je privzeti in najbolj vsestranski format. Zvok kodira kot nekompresirana 16-bitna predznačena cela števila (Linear16) v vrstnem redu little-endian.
Razpoložljive frekvence vzorčenja
API podpira sedem frekvenc vzorčenja za PCM:
- 8000 Hz: minimalna telefonska kakovost
- 16000 Hz: dobro razmerje za govor (wideband)
- 22050 Hz: vmesna kakovost
- 24000 Hz: privzeto, priporočeno za večino primerov
- 32000 Hz: višja kakovost
- 44100 Hz: kakovost CD
- 48000 Hz: studijska kakovost
Za standardno glasovno aplikacijo 24000 Hz ponuja najboljše ravnovesje med kakovostjo in pasovno širino. Višje frekvence ne prinašajo opaznih izboljšav za govor.
Konfiguracija v 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 in A-law
Kodeka G.711 sta standarda tradicionalne telefonije. Uporabljata logaritemsko kompresijo za zmanjšanje podatkov o zvoku ob ohranjanju kakovosti govora znotraj telefonskega pasu (300–3400 Hz).
mu-law (audio/pcmu)
Uporablja se predvsem v Severni Ameriki in na Japonskem; je domači kodek severnoameriških telefonskih omrežij. Če integriraš API Voice Agent s sistemom SIP s sedežem v ZDA, je audio/pcmu naravna izbira.
A-law (audio/pcma)
Uporablja se v Evropi in preostalem svetu. Za integracijo z evropskim telefonskim operaterjem izberi audio/pcma.
Omejitve G.711
Oba kodeka G.711 sta omejena na 8000 Hz, kar pomeni zmanjšano zvočno pasovno širino. Kakovost govora je za telefonijo ustrezna, a nižja kot pri PCM 24000 Hz. Uporabi ju le, če to zahteva tvoja telefonska infrastruktura.
Različni formati za vhod in izhod
API omogoča konfiguracijo različnih formatov za vhod in izhod, kar je uporabno v hibridnih arhitekturah:
{
"type": "session.update",
"session": {
"audio": {
"input": {
"format": {"type": "audio/pcmu", "rate": 8000}
},
"output": {
"format": {"type": "audio/pcm", "rate": 24000}
}
}
}
}
V tem primeru prejmeš G.711 mu-law iz telefonskega sistema in pošlješ visokokakovosten PCM nazaj v oddajni sistem.
Opus
Četrti kodek, audio/opus, prenaša surove pakete Opus pri 24.000 Hz mono, en paket na vsebino, brez glave zabojnika. Gre za kompresijski kodek: močno zmanjša pasovno širino v primerjavi s PCM, kar je pomembno pri mobilni povezavi, če tvoj odjemalec zna kodirati in dekodirati Opus.
Prenos: JSON ali binarno
Kodek (format) določa, kako je zvok kodiran; prenos (transport) pa, kako ti bajti potujejo prek WebSocket. Privzeto ("json") je zvok kodiran v base64 znotraj input_audio_buffer.append in response.output_audio.delta. Pri "binary" gre ven kot binarni okviri WebSocket, brez base64 in brez glave; dogodki življenjskega cikla (response.created, response.done, prepisi) ostanejo v 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) # 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
Dokumentacija določa dve pravili. Pri vhodu strežnik po konfiguraciji formata hkrati sprejme obe poti: input.transport določa le tvojo želeno pot. Pri izhodu zvok prispe le prek output.transport, sprememba sredi seje pa velja šele od naslednjega odgovora, tako da en sam izrek nikoli ne meša JSON in binarnega prenosa. Binarni prenos se izogne strošku base64, ki poveča volumen podatkov za približno tretjino.
Ključne ugotovitve
- Privzeti format je PCM 24000 Hz, idealen za spletne aplikacije
- G.711 mu-law (pcmu) je standard severnoameriške telefonije
- G.711 A-law (pcma) je standard evropske telefonije
- Kodeka G.711 sta omejena na 8000 Hz
- Za vhod in izhod lahko uporabiš različne formate
audio/opus(24 kHz mono) zmanjša pasovno širino;transport: "binary"pošilja zvok kot binarne okvire, brez base64- Za govor je 24000 Hz najboljše razmerje med kakovostjo in pasovno širino