Formati tal-awdjo: PCM u G.711
F'din il-paġna
Aġġornat fit-3 ta’ Novembru 2026, abbażi tal-paġna Speech to Speech ta’ xAI: l-API taċċetta r-raba’ codec,
audio/opus(pakketti Opus raw, 24 kHz mono), u t-tieni modalità ta’ trasport,binary, li tibgħat l-awdjo bħala frames binary ta’ WebSocket minflok base64 ġewwa JSON. Sors: Speech to Speech, Audio and Audio Transport.
Formati tal-awdjo appoġġjati
L-API tal-Aġent Vokali tappoġġja erba’ formati tal-awdjo għall-input u l-output: PCM, G.711 μ-law, G.711 A-law, u Opus. Liema wieħed tagħżel jiddependi mill-każ ta’ użu tiegħek: applikazzjoni web, telefonija, jew ipproċessar professjonali tal-awdjo.
| 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 huwa l-format default u l-aktar wieħed versatili. Jikkodifika l-awdjo bħala integers iffirmati ta’ 16-bit mhux ikkumpressati (Linear16) f’ordni little-endian.
Rati ta’ kampjunar disponibbli
L-API tappoġġja seba’ rati ta’ kampjunar għal PCM:
- 8000 Hz: kwalità telefonika minima
- 16000 Hz: kompromess tajjeb għall-vuċi (wideband)
- 22050 Hz: kwalità intermedja
- 24000 Hz: id-default, rakkomandat għall-biċċa l-kbira tal-każijiet
- 32000 Hz: kwalità ogħla
- 44100 Hz: kwalità CD
- 48000 Hz: kwalità ta’ studjo
Għal applikazzjoni vokali standard, 24000 Hz joffri l-aħjar bilanċ bejn il-kwalità u l-banda. It-tlugħ ogħla ma jġib l-ebda titjib notevoli għad-diskors.
Konfigurazzjoni f’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 u A-law
Il-codecs G.711 huma l-istandards tat-telefonija tradizzjonali. jużaw kompressjoni logaritmika biex iċekknu d-dejta tal-awdjo filwaqt li jippreservaw il-kwalità tal-vuċi fil-banda telefonika (300–3400 Hz).
mu-law (audio/pcmu)
Użat prinċipalment fl-Amerika ta’ Fuq u l-Ġappun, huwa l-codec nattiv tan-netwerks tat-telefown tal-Amerika ta’ Fuq. Jekk qed tintegra l-API tal-Aġent Vokali ma’ sistema SIP ibbażata fl-Istati Uniti, audio/pcmu hija l-għażla naturali.
A-law (audio/pcma)
Użat fl-Ewropa u l-bqija tad-dinja. Għal integrazzjoni ma’ operatur tat-telefonija Ewropew, mur ma’ audio/pcma.
Limitazzjonijiet tal-G.711
Iż-żewġ codecs G.711 huma limitati għal 8000 Hz biss, li jfisser banda tal-awdjo mnaqqsa. Il-kwalità tal-vuċi hija tajba għat-telefonija iżda aktar baxxa milli PCM ta’ 24000 Hz. Użahom biss meta l-infrastruttura tat-telefonija tiegħek teħtieġ dan.
Formati differenti għall-input u l-output
L-API tippermettilek tikkonfigura formati differenti għall-input u l-output, li huwa utli f’arkitetturi ibridi:
{
"type": "session.update",
"session": {
"audio": {
"input": {
"format": {"type": "audio/pcmu", "rate": 8000}
},
"output": {
"format": {"type": "audio/pcm", "rate": 24000}
}
}
}
}
F’dan l-eżempju, tirċievi G.711 mu-law minn sistema tat-telefonija u tibgħat PCM ta’ kwalità għolja lura lejn sistema ta’ xandir.
Opus
Ir-raba’ codec, audio/opus, iġorr pakketti Opus raw f’24,000 Hz mono, pakkett wieħed kull payload, mingħajr l-ebda header ta’ kontenitur. Huwa codec ikkumpressat: inaqqas il-banda b’mod qawwi meta mqabbel ma’ PCM, li huwa importanti fuq konnessjoni mobbli, sakemm il-klijent tiegħek ikun jista’ jikkodifika u jiddekodifika l-Opus.
Trasport: JSON jew binary
Il-codec (format) jgħid kif l-awdjo huwa kkodifikat; it-trasport (transport) jgħid kif dawk il-bytes jivvjaġġaw fuq il-WebSocket. B’mod default ("json"), l-awdjo huwa encoded f’base64 ġewwa input_audio_buffer.append u response.output_audio.delta. Ma’ "binary", joħroġ bħala frames binary ta’ WebSocket, mingħajr base64 u mingħajr header; l-avvenimenti taċ-ċiklu tal-ħajja (response.created, response.done, trascrizjonijiet) jibqgħu f’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
Id-dokumentazzjoni tistabbilixxi żewġ regoli. Fuq l-input, ladarba l-format ikun ikkonfigurat, is-server jaċċetta ż-żewġ mogħdijiet fl-istess ħin: input.transport jiddikjara biss il-mogħdija preferuta tiegħek. Fuq l-output, l-awdjo jasla biss permezz ta’ output.transport, u bidla f’nofs is-sessjoni tapplika biss mir-risposta li jmiss, għalhekk dikjazzjoni waħda qatt ma tħallat JSON u binary. Il-binary jevita l-overhead tal-base64, li jżid madwar terz mal-volum tad-dejta.
Punti Ewlenin
- Il-format default huwa PCM ta’ 24000 Hz, ideali għal applikazzjonijiet web
- G.711 mu-law (pcmu) huwa l-istandard tat-telefonija tal-Amerika ta’ Fuq
- G.711 A-law (pcma) huwa l-istandard tat-telefonija Ewropea
- Il-codecs G.711 huma limitati għal 8000 Hz
- Tista’ tuża formati differenti għall-input u l-output
audio/opus(24 kHz mono) inaqqas il-banda;transport: "binary"jibgħat l-awdjo bħala frames binary, mingħajr base64- Għall-vuċi, 24000 Hz huwa l-aħjar kompromess bejn il-kwalità u l-banda