Przejdź do głównej treści
Polski— Wybierz język
Menu

Formaty audio: PCM i G.711

Lekcja 5 z 16 Zaktualizowano 3 listopada 2026 Programista
Na tej stronie
  1. Obsługiwane formaty audio
  2. PCM (Pulse Code Modulation)
  3. G.711: mu-law i A-law
  4. Różne formaty wejścia i wyjścia
  5. Opus
  6. Transport: JSON lub binarny
  7. Kluczowe wnioski

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ą