Prejsť na hlavný obsah
Slovenčina— Vyberte jazyk
Menu

Nástroje na konverziu zvuku v Pythone

Lekcia 16 z 16 Aktualizované 30. júla 2026 Vývojár
Na tejto strane
  1. Knižnica zvukových nástrojov
  2. PCM16 na base64 a späť
  3. Prevzorkovanie (Resampling)
  4. Konverzia medzi G.711 a PCM
  5. Detekcia ticha na strane klienta
  6. Ukladanie a načítanie súborov WAV
  7. Kľúčové poznatky
  8. Over si svoje vedomosti

Knižnica zvukových nástrojov

Na vytvorenie robustnej aplikácie Voice Agent potrebuješ pomocné funkcie na konverziu zvuku medzi formátmi. Táto lekcia zhromažďuje základné nástroje Pythonu pre spracovanie zvuku v reálnom čase.

PCM16 na base64 a späť

Toto sú dve funkcie, ktoré budeš používať najčastejšie: kódovanie zachyteného zvuku do formátu base64 na odoslanie a dekódovanie prijatého zvuku base64 na prehratie.

import base64
import numpy as np

def audio_to_base64(audio_data: np.ndarray) -> str:
    """Converts a float32 numpy array in [-1, 1] to 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:
    """Converts a base64 PCM16 string to a float32 numpy array."""
    audio_bytes = base64.b64decode(base64_audio)
    audio_int16 = np.frombuffer(audio_bytes, dtype=np.int16)
    return audio_int16.astype(np.float32) / 32768.0

Použitie v toku Voice Agent

import pyaudio
import json

# Zachytenie mikrofónu → odoslanie
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
    }))

# Prijatie → prehratie
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())

Prevzorkovanie (Resampling)

Ak tvoj mikrofón zachytáva zvuk s inou vzorkovacou frekvenciou, než očakáva API, musíš vykonať prevzorkovanie:

from scipy.signal import resample

def resample_audio(
    audio: np.ndarray,
    original_rate: int,
    target_rate: int
) -> np.ndarray:
    """Resamples audio from one sample rate to another."""
    if original_rate == target_rate:
        return audio
    num_samples = int(len(audio) * target_rate / original_rate)
    return resample(audio, num_samples)

# Príklad: mikrofón 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)

Konverzia medzi G.711 a PCM

Pre integráciu s telefónmi budeš potrebovať konverziu medzi G.711 a lineárnym PCM. Dávaj pozor na verziu Pythonu: modul audioop bol odstránený zo štandardnej knižnice vo verzii 3.13. Na novšom Pythone si nainštaluj balík audioop-lts, ktorý poskytuje rovnaké rozhranie:

import audioop

def pcm_to_mulaw(pcm_data: bytes) -> bytes:
    """Converts PCM16 to G.711 mu-law."""
    return audioop.lin2ulaw(pcm_data, 2)

def mulaw_to_pcm(mulaw_data: bytes) -> bytes:
    """Converts G.711 mu-law to PCM16."""
    return audioop.ulaw2lin(mulaw_data, 2)

def pcm_to_alaw(pcm_data: bytes) -> bytes:
    """Converts PCM16 to G.711 A-law."""
    return audioop.lin2alaw(pcm_data, 2)

def alaw_to_pcm(alaw_data: bytes) -> bytes:
    """Converts G.711 A-law to PCM16."""
    return audioop.alaw2lin(alaw_data, 2)

Kompletný telefónny relé

Tu je príklad relé medzi tokom SIP G.711 a API Voice Agent:

async def relay_sip_to_voice_agent(sip_stream, ws):
    """Relays audio from a SIP call to the Voice Agent API."""
    async for mulaw_chunk in sip_stream:
        # Konverzia 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):
    """Relays the API's audio response to the SIP stream."""
    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)

Detekcia ticha na strane klienta

Ak sám obsluhuješ tlačidlo „stlač a hovoriť“ (push-to-talk) alebo chceš lokálnu detekciu ticha pred odoslaním, táto funkcia meria energiu signálu:

def is_silence(
    audio: np.ndarray,
    threshold: float = 0.01
) -> bool:
    """Detects whether an audio chunk is silence."""
    rms = np.sqrt(np.mean(audio ** 2))
    return rms < threshold

# Použitie
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
    }))

Ukladanie a načítanie súborov WAV

Na ladenie a testovanie môžeš ukladať a načítavať súbory WAV:

import wave

def save_wav(
    filename: str,
    audio: np.ndarray,
    sample_rate: int = 24000
):
    """Saves a numpy array as a WAV file."""
    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]:
    """Loads a WAV file as a float32 numpy array."""
    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

Kľúčové poznatky

  • Funkcie audio_to_base64 a base64_to_audio sú dve kľúčové funkcie pre tok Voice Agent.
  • Prevzorkovanie je potrebné, keď sa vzorkovacia frekvencia tvojho mikrofónu nezhoduje s frekvenciou API.
  • Modul audioop spravuje konverzie G.711 mu-law a A-law; bol odstránený zo štandardnej knižnice v Pythone 3.13, preto si na novších verziách nainštaluj audioop-lts z PyPI.
  • Detekcia ticha na strane klienta šetrí šírku pásma odosielaním iba užitočného zvuku.
  • Nástroje pre WAV uľahčujú ladenie tým, že ti umožňujú ukladať a znovu prehrávať zvukové toky.

Over si svoje vedomosti

WebSocket, VAD, zvuk: hlasový agent od začiatku do konca.

1. Ako nastavíš reláciu Voice Agent?

Odpoveď: Pomocou WebSocket pripojenia v reálnom čase, autentifikovaného jednorazovými tokenmi (nikdy nie hlavným kľúčom na klientovi), následne nakonfigurovaného cez session.update a potvrdeného udalosťami session.created a session.updated.

2. Čo vybavuje VAD?

Odpoveď: Automatickú detekciu reči: zistí, kedy používateľ začne a prestane hovoriť, takže agent vie, kedy počúvať a kedy odpovedať, bez potreby tlačidla.

3. Ako prúdi zvuk?

Odpoveď: Vstup odchádza cez input_audio_buffer.append (s commitom a vyčistením vyrovnávacej pamäte) a odpoveď prichádza ako zvukové udalosti na prehratie, vo formáte PCM alebo G.711 v závislosti od kanála.

4. Čo umožňujú nástroje a MCP v hlasovej konverzácii?

Odpoveď: Volanie funkcií a vstavané nástroje (web, X, kolekcie) počas hovorenej výmeny: agent vyhľadáva informácie a vykonáva akcie počas hovoru, vrátane udalostí MCP.

5. A čo telefónia?

Odpoveď: SIP a LiveKit s G.711: hlasový agent sa pripája do telefónnej siete a Pythonové nástroje na konverziu zvuku mostia formáty.

Bezpečná relácia, VAD, dobre spravované vyrovnávacie pamäte, nástroje v hlase: kompletný telefónny asistent je na dosah a tento kurz ti poskytol každý potrebný dielik.