Přejít na hlavní obsah
Čeština— Vyberte jazyk
Menu

Nástroje pro převod zvuku v Pythonu

Lekce 16 z 16 Aktualizováno 30. července 2026 Vývojář
Na této stránce
  1. Knihovna zvukových utilit
  2. Převod PCM16 na base64 a zpět
  3. Převzorkování (Resampling)
  4. Převod mezi G.711 a PCM
  5. Detekce ticha na straně klienta
  6. Ukládání a načítání souborů WAV
  7. Klíčové poznatky
  8. Ověř si své znalosti

Knihovna zvukových utilit

Pro vytvoření robustní aplikace Voice Agent potřebuješ pomocné funkce, které převádějí zvuk mezi různými formáty. Tato lekce shromažďuje základní nástroje Pythonu pro zpracování zvuku v reálném čase.

Převod PCM16 na base64 a zpět

Jedná se o dvě funkce, které budeš používat nejčastěji: kódování zachyceného zvuku do formátu base64 pro odeslání a dekódování přijatého zvuku v base64 pro přehrání.

import base64
import numpy as np

def audio_to_base64(audio_data: np.ndarray) -> str:
    """Převede pole numpy float32 v rozsahu [-1, 1] na base64 PCM16."""
    audio_int16 = (audio_data * 32767).astype(np.int16)
    return base64.b64encode(audio_int16.tobytes()).decode("utf-8")

def base64_to_audio(base64_audio: str) -> np.ndarray:
    """Převede řetězec base64 PCM16 na pole numpy float32."""
    audio_bytes = base64.b64decode(base64_audio)
    audio_int16 = np.frombuffer(audio_bytes, dtype=np.int16)
    return audio_int16.astype(np.float32) / 32768.0

Použití v toku Voice Agent

import pyaudio
import json

# Zachytání z mikrofonu → odeslání
def capture_and_send(ws, stream, chunk_size=4096):
    raw_data = stream.read(chunk_size, exception_on_overflow=False)
    audio_array = np.frombuffer(raw_data, dtype=np.int16)
    audio_float = audio_array.astype(np.float32) / 32768.0
    b64 = audio_to_base64(audio_float)

    ws.send(json.dumps({
        "type": "input_audio_buffer.append",
        "audio": b64
    }))

# Přijetí → přehrání
def play_received(player_stream, base64_audio):
    audio_float = base64_to_audio(base64_audio)
    audio_int16 = (audio_float * 32767).astype(np.int16)
    player_stream.write(audio_int16.tobytes())

Převzorkování (Resampling)

Pokud tvůj mikrofon zachytává zvuk s jinou vzorkovací frekvencí, než jakou očekává API, musíš provést převzorkování:

from scipy.signal import resample

def resample_audio(
    audio: np.ndarray,
    original_rate: int,
    target_rate: int
) -> np.ndarray:
    """Převezorkuje zvuk z jedné vzorkovací frekvence na jinou."""
    if original_rate == target_rate:
        return audio
    num_samples = int(len(audio) * target_rate / original_rate)
    return resample(audio, num_samples)

# Příklad: mikrofon na 44100 Hz → API na 24000 Hz
audio_44100 = capture_microphone()
audio_24000 = resample_audio(audio_44100, 44100, 24000)
b64 = audio_to_base64(audio_24000)

Převod mezi G.711 a PCM

Pro integraci s telefonními systémy budeš potřebovat převádět mezi formáty G.711 a lineárním PCM. Dej si pozor na verzi Pythonu: modul audioop byl odstraněn ze standardní knihovny ve verzi 3.13. Na novějších verzích Pythonu si nainstaluj balíček audioop-lts, který poskytuje stejné rozhraní:

import audioop

def pcm_to_mulaw(pcm_data: bytes) -> bytes:
    """Převede PCM16 na G.711 mu-law."""
    return audioop.lin2ulaw(pcm_data, 2)

def mulaw_to_pcm(mulaw_data: bytes) -> bytes:
    """Převede G.711 mu-law na PCM16."""
    return audioop.ulaw2lin(mulaw_data, 2)

def pcm_to_alaw(pcm_data: bytes) -> bytes:
    """Převede PCM16 na G.711 A-law."""
    return audioop.lin2alaw(pcm_data, 2)

def alaw_to_pcm(alaw_data: bytes) -> bytes:
    """Převede G.711 A-law na PCM16."""
    return audioop.alaw2lin(alaw_data, 2)

Kompletní telefonní relay

Zde je příklad relay mezi streamem SIP G.711 a API Voice Agent:

async def relay_sip_to_voice_agent(sip_stream, ws):
    """Přenáší zvuk z hovoru SIP do API Voice Agent."""
    async for mulaw_chunk in sip_stream:
        # Převod mu-law → PCM → base64
        pcm_data = mulaw_to_pcm(mulaw_chunk)
        b64 = base64.b64encode(pcm_data).decode("utf-8")

        await ws.send(json.dumps({
            "type": "input_audio_buffer.append",
            "audio": b64
        }))

async def relay_voice_agent_to_sip(ws, sip_stream):
    """Přenáší zvukovou odpověď z API do streamu SIP."""
    async for message in ws:
        event = json.loads(message)
        if event["type"] == "response.output_audio.delta":
            pcm_data = base64.b64decode(event["delta"])
            mulaw_data = pcm_to_mulaw(pcm_data)
            await sip_stream.send(mulaw_data)

Detekce ticha na straně klienta

Pokud sám obsluhuješ funkci push-to-talk, nebo chceš detekovat ticho lokálně před odesláním, tato funkce měří energii signálu:

def is_silence(
    audio: np.ndarray,
    threshold: float = 0.01
) -> bool:
    """Detekuje, zda je zvukový úsek ticho."""
    rms = np.sqrt(np.mean(audio ** 2))
    return rms < threshold

# Použití
audio_chunk = capture_microphone()
if not is_silence(audio_chunk, threshold=0.02):
    b64 = audio_to_base64(audio_chunk)
    ws.send(json.dumps({
        "type": "input_audio_buffer.append",
        "audio": b64
    }))

Ukládání a načítání souborů WAV

Pro ladění a testování můžeš ukládat a načítat soubory WAV:

import wave

def save_wav(
    filename: str,
    audio: np.ndarray,
    sample_rate: int = 24000
):
    """Uloží pole numpy jako soubor WAV."""
    audio_int16 = (audio * 32767).astype(np.int16)
    with wave.open(filename, "wb") as wf:
        wf.setnchannels(1)
        wf.setsampwidth(2)
        wf.setframerate(sample_rate)
        wf.writeframes(audio_int16.tobytes())

def load_wav(filename: str) -> tuple[np.ndarray, int]:
    """Načte soubor WAV jako pole numpy float32."""
    with wave.open(filename, "rb") as wf:
        sample_rate = wf.getframerate()
        frames = wf.readframes(wf.getnframes())
        audio_int16 = np.frombuffer(frames, dtype=np.int16)
        return audio_int16.astype(np.float32) / 32768.0, sample_rate

Klíčové poznatky

  • Funkce audio_to_base64 a base64_to_audio jsou dvěma zásadními funkcemi pro tok Voice Agent.
  • Převzorkování je nutné, když se vzorkovací frekvence tvého mikrofonu neshoduje s frekvencí API.
  • Modul audioop zpracovává převody G.711 mu-law a A-law; byl odstraněn ze standardní knihovny v Pythonu 3.13, takže na novějších verzích si z PyPI nainstaluj audioop-lts.
  • Detekce ticha na straně klienta šetří šířku pásma tím, že odesílá pouze užitečný zvuk.
  • Utility pro WAV usnadňují ladění tím, že ti umožní ukládat a přehrávat zvukové streamy.

Ověř si své znalosti

WebSocket, VAD, zvuk: hlasový agent od začátku do konce.

1. Jak nastavíš relaci Voice Agent?

Odpověď: Pomocí WebSocket připojení v reálném čase, ověřeného pomocí jednorázových tokenů (nikdy hlavního klíče na klientovi), nakonfigurovaného prostřednictvím session.update a potvrzeného událostmi session.created a session.updated.

2. Co zpracovává VAD?

Odpověď: Automatickou detekci řeči: zjistí, kdy uživatel začne a přestane mluvit, takže agent ví, kdy má poslouchat a kdy odpovědět, bez nutnosti mačkat tlačítko.

3. Jak probíhá tok zvuku?

Odpověď: Vstup odchází přes input_audio_buffer.append (s potvrzením a vyčištěním vyrovnávací paměti) a odpověď přichází jako zvukové události k přehrání, ve formátu PCM nebo G.711 v závislosti na kanálu.

4. Co umožňují nástroje a MCP v hlasové konverzaci?

Odpověď: Volání funkcí a vestavěné nástroje (web, X, kolekce) během mluvené výměny: agent vyhledává informace a podniká kroky, zatímco mluví, včetně událostí MCP.

5. A co telefonie?

Odpověď: SIP a LiveKit s G.711: hlasový agent se zapojí do telefonní sítě a utility pro převod zvuku v Pythonu přemostí formáty.

Bezpečná relace, VAD, dobře spravované vyrovnávací paměti, nástroje v hlasu: kompletní telefonní asistent je na dosah a tento kurz ti poskytl všechny potřebné díly.