Hangformátumok: PCM és G.711
Ezen az oldalon
Frissítve: 2026. november 3., az xAI Speech to Speech oldala alapján: az API egy negyedik kodeket, az
audio/opus-t (nyers Opus csomagok, 24 kHz mono), és egy második szállítási módot, abinary-t is támogat, amely az audiot bináris WebSocket keretekben küldi a JSON-on belüli base64 kódolás helyett. Forrás: Speech to Speech, Audio and Audio Transport.
Támogatott hangformátumok
A Voice Agent API négy hangformátumot támogat bemenetként és kimenetként egyaránt: PCM, G.711 μ-law, G.711 A-law és Opus. A választás a felhasználási esetedtől függ: webes alkalmazás, távközlés vagy professzionális hangfeldolgozás.
| Formátum | Kódolás | Mintavételezési ráták | Tipikus felhasználás |
|---|---|---|---|
| audio/pcm | Linear16, little-endian | 8000–48000 Hz | Webes alkalmazások, hangfeldolgozás |
| audio/pcmu | G.711 mu-law | Kizárólag 8000 Hz | Észak-amerikai távközlés |
| audio/pcma | G.711 A-law | Kizárólag 8000 Hz | Európai / nemzetközi távközlés |
| audio/opus | Opus (nyers csomagok) | 24000 Hz mono | Mobil, alacsony sávszélesség |
PCM (Pulse Code Modulation)
A PCM az alapértelmezett és legsokoldalúbb formátum. Tömörítetlen, 16 bites előjeles egész számokként (Linear16) kódolja az audiot little-endian sorrendben.
Elérhető mintavételezési ráták
Az API hét mintavételezési rátát támogat PCM esetén:
- 8000 Hz: minimális telefonminőség
- 16000 Hz: jó kompromisszum beszédhez (szélessávú)
- 22050 Hz: közepes minőség
- 24000 Hz: az alapértelmezett, legtöbb esetben ajánlott
- 32000 Hz: magasabb minőség
- 44100 Hz: CD-minőség
- 48000 Hz: stúdióminőség
Egy szabványos beszédalkalmazáshoz a 24000 Hz nyújtja a legjobb egyensúlyt a minőség és a sávszélesség között. Ennél magasabbra menni nem hoz észrevehető javulást beszéd esetén.
Konfiguráció a session.update-ben
{
"type": "session.update",
"session": {
"audio": {
"input": {
"format": {"type": "audio/pcm", "rate": 24000}
},
"output": {
"format": {"type": "audio/pcm", "rate": 24000}
}
}
}
}
G.711: mu-law és A-law
A G.711 kodekek a hagyományos távközlés szabványai. Logaritmikus tömörítést alkalmaznak az adatmennyiség csökkentésére, miközben megőrzik a beszédminőséget a telefonsávban (300–3400 Hz).
mu-law (audio/pcmu)
Főként Észak-Amerikában és Japánban használják; ez az észak-amerikai telefonhálózatok natív kodekje. Ha a Voice Agent API-t egyesült államokbeli SIP rendszerrel integrálod, az audio/pcmu a természetes választás.
A-law (audio/pcma)
Európában és a világ többi részén alkalmazzák. Európai telefonszolgáltatóval történő integrációhoz válaszd az audio/pcma formátumot.
A G.711 korlátai
Mindkét G.711 kodek 8000 Hz-re korlátozódik, ami csökkentett hangsávszélességet jelent. A hangminőség távközlési célokra megfelelő, de alacsonyabb, mint a 24000 Hz-es PCM-é. Csak akkor használd őket, ha a telefonos infrastruktúrád megköveteli.
Különböző bemeneti és kimeneti formátumok
Az API lehetővé teszi különböző formátumok konfigurálását bemenetre és kimenetre, ami hibrid architektúráknál hasznos:
{
"type": "session.update",
"session": {
"audio": {
"input": {
"format": {"type": "audio/pcmu", "rate": 8000}
},
"output": {
"format": {"type": "audio/pcm", "rate": 24000}
}
}
}
}
Ebben a példában G.711 mu-law jelet fogadsz egy telefonrendszertől, és nagy minőségű PCM-et küldesz vissza egy műsorszóró rendszernek.
Opus
A negyedik kodek, az audio/opus, nyers Opus csomagokat szállít 24 000 Hz-en, monó hanggal, payloadonként egy csomaggal, konténer fejléc nélkül. Ez egy tömörített kodek: drasztikusan csökkenti a sávszélesség-igényt a PCM-hez képest, ami mobilkapcsolaton lényeges, feltéve, hogy a kliensed képes kódolni és dekódolni az Opust.
Szállítás: JSON vagy bináris
A kodek (format) azt határozza meg, hogyan van kódolva az audio; a szállítás (transport) pedig azt, hogyan utaznak ezek a bájtok a WebSocketen. Alapértelmezetten ("json") az audio base64-kódolva érkezik az input_audio_buffer.append és a response.output_audio.delta mezőkben. "binary" esetén bináris WebSocket keretekként távozik, base64 és fejléc nélkül; az életciklus-események (response.created, response.done, átírások) JSON-ban maradnak.
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) # bináris keret: nyers 16 bites PCM, base64 nélkül
async for message in ws:
if isinstance(message, bytes):
player.write(message) # az asszisztens audioja
else:
event = json.loads(message) # JSON esemény
A dokumentáció két szabályt rögzít. Bemenetnél, ha a formátum konfigurálva van, a szerver egyszerre fogadja el mindkét utat: az input.transport csak a preferált utat jelzi. Kimenetnél az audio kizárólag az output.transport útján érkezik, és a munkamenet közbeni változás csak a következő választól érvényesül, így egyetlen megnyilatkozás soha nem keveri a JSON-t és a binárist. A bináris mód elkerüli a base64 többletét, amely körülbelül egyharmaddal növeli az adatmennyiséget.
Főbb megállapítások
- Az alapértelmezett formátum a 24000 Hz-es PCM, amely ideális webes alkalmazásokhoz
- A G.711 mu-law (pcmu) az észak-amerikai távközlési szabvány
- A G.711 A-law (pcma) az európai távközlési szabvány
- A G.711 kodekek 8000 Hz-re korlátozódnak
- Használhatsz különböző formátumokat bemenetre és kimenetre
- Az
audio/opus(24 kHz mono) csökkenti a sávszélességet; atransport: "binary"bináris keretekben küldi az audiot, base64 nélkül - Beszéd esetén a 24000 Hz a legjobb kompromisszum a minőség és a sávszélesség között