Formaty audio: PCM i G.711
Na tej stronie
Zaktualizowano 3 listopada 2026 r. na podstawie strony xAI Speech to Speech: API obsługuje czwarty kodek,
audio/opus(surowe pakiety Opus, 24 kHz mono), oraz drugi tryb transportu,binary, który przesyła audio jako binarne ramki WebSocket zamiast base64 wewnątrz JSON. Źródło: Speech to Speech, Audio and Audio Transport.
Obsługiwane formaty audio
Voice Agent API obsługuje cztery formaty audio dla danych wejściowych i wyjściowych: PCM, G.711 μ-law, G.711 A-law oraz Opus. Wybór zależy od Twojego przypadku użycia: aplikacji internetowej, telefonii lub profesjonalnego przetwarzania dźwięku.
| Format | Kodowanie | Częstotliwości próbkowania | Typowe zastosowanie |
|---|---|---|---|
| audio/pcm | Linear16, little-endian | 8000–48000 Hz | Aplikacje webowe, przetwarzanie audio |
| audio/pcmu | G.711 mu-law | Tylko 8000 Hz | Telefonia północnoamerykańska |
| audio/pcma | G.711 A-law | Tylko 8000 Hz | Telefonia europejska / międzynarodowa |
| audio/opus | Opus (surowe pakiety) | 24000 Hz mono | Urządzenia mobilne, niskie pasmo |
PCM (Pulse Code Modulation)
PCM to domyślny i najbardziej wszechstronny format. Koduje on dźwięk jako nieskompresowane 16-bitowe liczby całkowite ze znakiem (Linear16) w kolejności little-endian.
Dostępne częstotliwości próbkowania
API obsługuje siedem częstotliwości próbkowania dla PCM:
- 8000 Hz: minimalna jakość telefoniczna
- 16000 Hz: dobry kompromis dla głosu (szerokopasmowe)
- 22050 Hz: jakość pośrednia
- 24000 Hz: wartość domyślna, zalecana w większości przypadków
- 32000 Hz: wyższa jakość
- 44100 Hz: jakość płyt CD
- 48000 Hz: jakość studyjna
W standardowej aplikacji głosowej 24000 Hz oferuje najlepszy balans między jakością a przepustowością. Wyższe wartości nie przynoszą zauważalnej poprawy w przypadku mowy.
Konfiguracja w 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 i A-law
Kodeki G.711 to standardy tradycyjnej telefonii. Wykorzystują one kompresję logarytmiczną do zmniejszenia rozmiaru danych audio, zachowując jednocześnie jakość głosu w paśmie telefonicznym (300–3400 Hz).
mu-law (audio/pcmu)
Stosowany głównie w Ameryce Północnej i Japonii; jest to natywny kodek sieci telefonicznych w Ameryce Północnej. Jeśli integrujesz Voice Agent API z systemem SIP opartym w USA, audio/pcmu jest naturalnym wyborem.
A-law (audio/pcma)
Stosowany w Europie i reszcie świata. Do integracji z europejskim operatorem telefonicznym wybierz audio/pcma.
Ograniczenia G.711
Oba kodeki G.711 są ograniczone do 8000 Hz, co oznacza mniejszą przepustowość audio. Jakość głosu jest wystarczająca do celów telefonicznych, ale niższa niż w przypadku PCM 24000 Hz. Używaj ich tylko wtedy, gdy wymaga tego Twoja infrastruktura telefoniczna.
Różne formaty wejścia i wyjścia
API pozwala skonfigurować różne formaty dla danych wejściowych i wyjściowych, co jest przydatne w architekturach hybrydowych:
{
"type": "session.update",
"session": {
"audio": {
"input": {
"format": {"type": "audio/pcmu", "rate": 8000}
},
"output": {
"format": {"type": "audio/pcm", "rate": 24000}
}
}
}
}
W tym przykładzie otrzymujesz G.711 mu-law z systemu telefonicznego i wysyłasz z powrotem wysokiej jakości PCM do systemu nadawczego.
Opus
Czwarty kodek, audio/opus, przenosi surowe pakiety Opus przy częstotliwości 24 000 Hz w mono, jeden pakiet na ładunek użytkowy, bez nagłówka kontenera. Jest to kodek skompresowany: drastycznie zmniejsza zużycie pasma w porównaniu z PCM, co ma znaczenie przy połączeniach mobilnych, pod warunkiem że Twój klient potrafi kodować i dekodować Opus.
Transport: JSON lub binarny
Kodek (format) określa, jak audio jest zakodowane; transport (transport) definiuje, w jaki sposób te bajty są przesyłane przez WebSocket. Domyślnie ("json") audio jest zakodowane w base64 wewnątrz input_audio_buffer.append oraz response.output_audio.delta. Przy ustawieniu "binary" dane wychodzą jako binarne ramki WebSocket, bez base64 i bez nagłówka; zdarzenia cyklu życia (response.created, response.done, transkrypcje) pozostają w formacie 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) # ramka binarna: surowe 16-bitowe PCM, bez base64
async for message in ws:
if isinstance(message, bytes):
player.write(message) # audio asystenta
else:
event = json.loads(message) # zdarzenie JSON
Dokumentacja określa dwie zasady. Po stronie wejścia, po skonfigurowaniu formatu, serwer akceptuje obie ścieżki jednocześnie: input.transport wskazuje jedynie preferowaną ścieżkę. Po stronie wyjścia audio dociera wyłącznie przez output.transport, a zmiana w trakcie sesji obowiązuje od następnej odpowiedzi, więc pojedyncza wypowiedź nigdy nie miesza JSON-a i danych binarnych. Tryb binarny eliminuje narzut base64, który zwiększa objętość danych o około jedną trzecią.
Kluczowe wnioski
- Domyślnym formatem jest PCM 24000 Hz, idealny do aplikacji webowych
- G.711 mu-law (pcmu) to standard telefonii północnoamerykańskiej
- G.711 A-law (pcma) to standard telefonii europejskiej
- Kodeki G.711 są ograniczone do 8000 Hz
- Możesz używać różnych formatów dla wejścia i wyjścia
audio/opus(24 kHz mono) redukuje zużycie pasma;transport: "binary"wysyła audio jako ramki binarne, bez base64- Dla głosu 24000 Hz to najlepszy kompromis między jakością a przepustowością