Helivormingud: PCM ja G.711
Sellel lehel
Uuendatud 3. novembril 2026, tuginedes xAI Speech to Speech lehele: API toob kaasa neljanda koodeki,
audio/opus(toored Opus-paketid, 24 kHz mono), ja teise edastusrežiimi,binary, mis saadab heli binaarsete WebSocketi raamistena JSON-i sees oleva base64 asemel. Allikas: Speech to Speech, Audio and Audio Transport.
Toetatud helivormingud
Voice Agent API toob sisendi ja väljundi jaoks kaasa neli helivormingut: PCM, G.711 μ-law, G.711 A-law ja Opus. Valik sõltub sinu kasutusjuhtumist: veebirakendus, telefonivõrk või professionaalne helitöötlus.
| Formaat | Kodeering | Diskreetimissagedused | Tüüpiline kasutus |
|---|---|---|---|
| audio/pcm | Linear16, väike-endiaan | 8000–48000 Hz | Veebirakendused, helitöötlus |
| audio/pcmu | G.711 mu-law | ainult 8000 Hz | Põhja-Ameerika telefonivõrgud |
| audio/pcma | G.711 A-law | ainult 8000 Hz | Euroopa / rahvusvahelised telefonivõrgud |
| audio/opus | Opus (toored paketid) | 24000 Hz mono | Mobiilside, madal ribalaius |
PCM (Impulsskoodmodulatsioon)
PCM on vaikeformaat ja kõige mitmekülgsem. See kodeerib heli tihendamata 16-bitiste märgiga täisarvudena (Linear16) väike-endiaan järjekorras.
Saadaval olevad diskreetimissagedused
API toetab PCM-i jaoks seitset diskreetimissagedust:
- 8000 Hz: minimaalne telefonikvaliteet
- 16000 Hz: hea kompromiss kõne jaoks (laiaribaline)
- 22050 Hz: keskmine kvaliteet
- 24000 Hz: vaikimisi, soovitatav enamiku juhtude jaoks
- 32000 Hz: kõrgem kvaliteet
- 44100 Hz: CD-kvaliteet
- 48000 Hz: stuudiokvaliteet
Tavalise kõnerakenduse puhul pakub 24000 Hz parimat tasakaalu kvaliteedi ja ribalaiuse vahel. Kõrgemate sageduste kasutamine ei too kõne puhul märgatavat parendust.
Seadistamine session.update-is
{
"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 koodekid on traditsioonilise telefonside standardid. Need kasutavad logaritmilist tihendamist, et vähendada heliandmete mahtu, säilitades samal ajal kõnekvaliteedi telefonisagedusribas (300–3400 Hz).
mu-law (audio/pcmu)
Kasutatakse peamiselt Põhja-Ameerikas ja Jaapanis; see on Põhja-Ameerika telefonivõrkude loomulik koodek. Kui integreerid Voice Agent API USA-põhise SIP-süsteemiga, on audio/pcmu loomulik valik.
A-law (audio/pcma)
Kasutatakse Euroopas ja ülejäänud maailmas. Euroopa telefoniettevõtjaga integreerimisel vali audio/pcma.
G.711 piirangud
Mõlemad G.711 koodekid on piiratud sagedusega 8000 Hz, mis tähendab väiksemat heliribalaiust. Kõnekvaliteet on telefonside jaoks korralik, kuid madalam kui 24000 Hz PCM-i puhul. Kasuta neid ainult siis, kui sinu telefonitaristu seda nõuab.
Erinevad sisendi ja väljundi formaadid
API võimaldab sisendi ja väljundi jaoks seadistada erinevaid formaate, mis on kasulik hübriidarhitektuurides:
{
"type": "session.update",
"session": {
"audio": {
"input": {
"format": {"type": "audio/pcmu", "rate": 8000}
},
"output": {
"format": {"type": "audio/pcm", "rate": 24000}
}
}
}
}
Selles näites võtad vastu G.711 mu-law signaali telefonisüsteemist ja saadad kõrgekvaliteedilist PCM-i tagasi ringhäälingusüsteemi.
Opus
Neljas koodek, audio/opus, edastab tooreid Opus-pakette sagedusel 24 000 Hz monorežiimis, üks pakett koormuse kohta, ilma konteineri päiseta. See on tihendatud koodek: see vähendab ribalaiust oluliselt võrreldes PCM-iga, mis on mobiilsideühenduse puhul oluline, eeldusel et sinu klient suudab Opust kodeerida ja dekodeerida.
Edastus: JSON või binaarne
Koodek (format) määrab, kuidas heli on kodeeritud; edastusviis (transport) määrab, kuidas need bitid WebSocketi kaudu liiguvad. Vaikimisi ("json") on heli base64-kodeeritud väljades input_audio_buffer.append ja response.output_audio.delta. Režiimis "binary" saadetakse see binaarsete WebSocketi raamidena, ilma base64 ja päiseta; elutsükli sündmused (response.created, response.done, transkriptsioonid) jäävad JSON-formaati.
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) # binaarne raam: toores 16-bitine PCM, ilma base64-ta
async for message in ws:
if isinstance(message, bytes):
player.write(message) # assistendi heli
else:
event = json.loads(message) # JSON-sündmus
Dokumentatsioon sätestab kaks reeglit. Sisendi puhul aktsepteerib server pärast formaadi seadistamist mõlemat teed samaaegselt: input.transport määrab ainult sinu eelistatud tee. Väljundi puhul saabub heli ainult kanali output.transport kaudu ja seansi keskel tehtud muudatus jõustub alles järgmisest vastusest, nii et üks kõne lõik ei sega kunagi JSON-i ja binaarset andmemahtu. Binaarne edastus väldib base64 ülekulu, mis suurendab andmemahtu umbes kolmandiku võrra.
Peamised punktid
- Vaikimisi formaat on 24000 Hz PCM, mis sobib ideaalselt veebirakendustele
- G.711 mu-law (pcmu) on Põhja-Ameerika telefonside standard
- G.711 A-law (pcma) on Euroopa telefonside standard
- G.711 koodekid on piiratud sagedusega 8000 Hz
- Sisendi ja väljundi jaoks saad kasutada erinevaid formaate
audio/opus(24 kHz mono) vähendab ribalaiust;transport: "binary"saadab heli binaarsete raamidena ilma base64-ta- Kõne puhul on 24000 Hz parim kompromiss kvaliteedi ja ribalaiuse vahel