Ugrás a főtartalomra
Magyar— Nyelv kiválasztása
Menü

Hangkonverziós segédprogramok Pythonban

16. lecke 16 közül Frissítve 2026. július 30. Fejlesztő
Ezen az oldalon
  1. Egy hangfeldolgozó könyvtár
  2. PCM16 és base64 közötti konverzió
  3. Újramintavételezés (Resampling)
  4. Konverzió G.711 és PCM között
  5. Kliens oldali csendérzékelés
  6. WAV fájlok mentése és betöltése
  7. Főbb megállapítások
  8. Ellenőrizd a tudásod

Egy hangfeldolgozó könyvtár

Egy robosztus Voice Agent alkalmazás felépítéséhez olyan segédfüggvényekre van szükséged, amelyek különböző formátumok között konvertálják a hangot. Ez a lecke összegyűjti a valós idejű hangfeldolgozáshoz szükséges alapvető Python-eszközöket.

PCM16 és base64 közötti konverzió

Ez a két függvény lesz a leggyakrabban használt: a rögzített hang base64-be kódolása a küldéshez, valamint a fogadott base64 hang dekódolása a lejátszáshoz.

import base64
import numpy as np

def audio_to_base64(audio_data: np.ndarray) -> str:
    """Konvertál egy [-1, 1] tartományú float32 numpy tömböt base64 PCM16-ba."""
    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:
    """Konvertál egy base64 PCM16 karakterláncot float32 numpy tömbbé."""
    audio_bytes = base64.b64decode(base64_audio)
    audio_int16 = np.frombuffer(audio_bytes, dtype=np.int16)
    return audio_int16.astype(np.float32) / 32768.0

Használatuk a Voice Agent folyamatban

import pyaudio
import json

# Mikrofon rögzítés → küldés
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
    }))

# Fogadás → lejátszás
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())

Újramintavételezés (Resampling)

Ha a mikrofonod más mintavételezési rátával rögzít, mint amit az API elvár, újra kell mintavételezned:

from scipy.signal import resample

def resample_audio(
    audio: np.ndarray,
    original_rate: int,
    target_rate: int
) -> np.ndarray:
    """Újramintavételezi a hangot egyik mintavételezési rátáról a másikra."""
    if original_rate == target_rate:
        return audio
    num_samples = int(len(audio) * target_rate / original_rate)
    return resample(audio, num_samples)

# Példa: mikrofon 44100 Hz-en → API 24000 Hz-en
audio_44100 = capture_microphone()
audio_24000 = resample_audio(audio_44100, 44100, 24000)
b64 = audio_to_base64(audio_24000)

Konverzió G.711 és PCM között

Telefonos integrációkhoz konvertálnod kell a G.711 és a lineáris PCM formátumok között. Figyeld a Python verziódat: az audioop modult eltávolították a szabványos könyvtárból a 3.13-as verzióban. Friss Python esetén telepítsd az audioop-lts csomagot, amely ugyanazt a felületet biztosítja:

import audioop

def pcm_to_mulaw(pcm_data: bytes) -> bytes:
    """Konvertálja a PCM16-ot G.711 mu-law formátumba."""
    return audioop.lin2ulaw(pcm_data, 2)

def mulaw_to_pcm(mulaw_data: bytes) -> bytes:
    """Konvertálja a G.711 mu-law-t PCM16-ba."""
    return audioop.ulaw2lin(mulaw_data, 2)

def pcm_to_alaw(pcm_data: bytes) -> bytes:
    """Konvertálja a PCM16-ot G.711 A-law formátumba."""
    return audioop.lin2alaw(pcm_data, 2)

def alaw_to_pcm(alaw_data: bytes) -> bytes:
    """Konvertálja a G.711 A-law-t PCM16-ba."""
    return audioop.alaw2lin(alaw_data, 2)

Egy teljes telefonos relé

Íme egy példa egy relére egy G.711 SIP adatfolyam és a Voice Agent API között:

async def relay_sip_to_voice_agent(sip_stream, ws):
    """Továbbítja a hangot egy SIP hívásból a Voice Agent API felé."""
    async for mulaw_chunk in sip_stream:
        # Konverzió: 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):
    """Továbbítja az API hangválaszát a SIP adatfolyamba."""
    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)

Kliens oldali csendérzékelés

Ha te kezeled a „nyomd a beszéléshez“ funkciót, vagy helyi csendérzékelést szeretnél a küldés előtt, ez a függvény méri a jel energiáját:

def is_silence(
    audio: np.ndarray,
    threshold: float = 0.01
) -> bool:
    """Érzékeli, hogy egy hangrészlet csend-e."""
    rms = np.sqrt(np.mean(audio ** 2))
    return rms < threshold

# Használat
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
    }))

WAV fájlok mentése és betöltése

Hibakereséshez és teszteléshez elmentheted és betöltheted a WAV fájlokat:

import wave

def save_wav(
    filename: str,
    audio: np.ndarray,
    sample_rate: int = 24000
):
    """Elment egy numpy tömböt WAV fájlként."""
    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]:
    """Betölt egy WAV fájlt float32 numpy tömbként."""
    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

Főbb megállapítások

  • Az audio_to_base64 és a base64_to_audio a két alapvető függvény a Voice Agent folyamathoz
  • Újramintavételezésre akkor van szükség, ha a mikrofonod mintavételezési rátája nem egyezik az API-éval
  • Az audioop modul kezeli a G.711 mu-law és A-law konverziókat; ezt eltávolították a szabványos könyvtárból a Python 3.13-ban, ezért friss verziókon telepítsd az audioop-lts csomagot a PyPI-ről
  • A kliens oldali csendérzékelés sávszélességet takarít meg azzal, hogy csak a hasznos hangot küldi el
  • A WAV segédprogramok megkönnyítik a hibakeresést, lehetővé téve hangfolyamok mentését és visszajátszását

Ellenőrizd a tudásod

WebSocket, VAD, hang: a voice agent végig, elejétől a végéig.

1. Hogyan állítasz be egy Voice Agent munkamenetet?

Válasz: Egy valós idejű WebSocket kapcsolattal, amely ideiglenes tokenekkel hitelesített (soha ne a fő kulcsot használd a kliensen), majd a session.update segítségével konfigurálod, és a session.created, illetve session.updated események erősítik meg.

2. Mit kezel a VAD?

Válasz: Az automatikus beszédérzékelést: kideríti, mikor kezd el és mikor fejezi be a beszédet a felhasználó, így az ügynök tudja, mikor figyeljen és mikor válaszoljon, gomb nélkül.

3. Hogyan áramlik a hang?

Válasz: A bemenet az input_audio_buffer.append keresztül távozik (puffer commit és clear műveletekkel), a válasz pedig hangeseményekként érkezik lejátszásra, PCM vagy G.711 formátumban, a csatornától függően.

4. Mit tesznek lehetővé az eszközök és az MCP egy hangalapú beszélgetésben?

Válasz: Függvényhívást és beépített eszközöket (web, X, gyűjtemények) a szóbeli csere során: az ügynök keresgél és intézkedik beszéd közben, beleértve az MCP eseményeket is.

5. És a telefonhálózat esetében?

Válasz: SIP és LiveKit G.711-lel: a voice agent csatlakozik a telefonhálózathoz, a Python hangkonverziós segédprogramok pedig hidat képeznek a formátumok között.

Egy biztonságos munkamenet, VAD, jól kezelt pufferek, eszközök hangalapú környezetben: a teljes telefonos asszisztens elérhető közelségbe került, és ez a tanfolyam minden szükséges elemet megadott hozzá.