Nástroje pro převod zvuku v Pythonu
Na této stránce
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_base64abase64_to_audiojsou 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
audioopzpracová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 nainstalujaudioop-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.