Hangkonverziós segédprogramok Pythonban
Ezen az oldalon
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 abase64_to_audioa 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
audioopmodul 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 azaudioop-ltscsomagot 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á.