Pripomočki za pretvorbo zvoka v Pythonu
Na tej strani
Knjižnica za zvočne pripomočke
Za izgradnjo robustne aplikacije Voice Agent potrebuješ pomožne funkcije, ki pretvarjajo zvok med različnimi formati. Ta lekcija zбира bistvena orodja Python za obdelavo zvoka v realnem času.
PCM16 v base64 in obratno
To sta dve funkciji, ki ju boš uporabljal najpogosteje: kodiranje zajetega zvoka v base64 za pošiljanje in dekodiranje prejetega base64 zvoka za predvajanje.
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
Uporaba v toku Voice Agent
import pyaudio
import json
# Zajem mikrofona → pošiljanje
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
}))
# Sprejem → predvajanje
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())
Vzorčenje (Resampling)
Če tvoj mikrofon zajema zvok pri drugačni frekvenci vzorčenja, kot jo pričakuje API, moraš izvesti ponovno vzorčenje:
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)
# Primer: mikrofon pri 44100 Hz → API pri 24000 Hz
audio_44100 = capture_microphone()
audio_24000 = resample_audio(audio_44100, 44100, 24000)
b64 = audio_to_base64(audio_24000)
Pretvorba med G.711 in PCM
Za integracije s telefonskimi sistemi boš potreboval pretvorbo med G.711 in linearnim PCM. Bodi pozoren na svojo različico Pythona: modul audioop so odstranili iz standardne knjižnice v različici 3.13. Na novejših različicah Pythona namesti paket audioop-lts, ki zagotavlja enak vmesnik:
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)
Popoln telefonski relej
Tukaj je primer releja med tokom SIP G.711 in API-jem 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:
# Pretvorba 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)
Detekcija tišine na strani odjemalca
Če sam upravljaš funkcijo „pritisni za govor” (push-to-talk) ali želiš lokalno detekcijo tišine pred pošiljanjem, ta funkcija meri energijo signala:
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
# Uporaba
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
}))
Shranjevanje in nalaganje datotek WAV
Za razhroščevanje in testiranje lahko shranjuješ in nalagaš datoteke 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
Ključne ugotovitve
audio_to_base64inbase64_to_audiosta dve bistveni funkciji za tok Voice Agent.- Ponovno vzorčenje je potrebno, ko se frekvenca vzorčenja tvojega mikrofona ne ujema s tisto v API-ju.
- Modul
audioopobravnava pretvorbe G.711 mu-law in A-law; odstranili so ga iz standardne knjižnice v Pythonu 3.13, zato na novejših različicah namestiaudioop-ltsiz PyPI. - Detekcija tišine na strani odjemalca prihrani pasovno širino, saj pošilja le uporaben zvok.
- Pripomočki za WAV olajšajo razhroščevanje, saj ti omogočajo shranjevanje in ponovno predvajanje zvočnih tokov.
Preveri svoje razumevanje
WebSocket, VAD, zvok: glasovni agent od začetka do konca.
1. Kako nastaviš sejo Voice Agent?
Odgovor: Z WebSocket povezavo v realnem času, avtenticirano z efemernimi žetoni (nikoli glavnim ključem na odjemalcu), nato konfigurirano prek session.update in potrjeno z dogodkoma session.created in session.updated.
2. Kaj obravnava VAD?
Odgovor: Samodejno zaznavanje govora: ugotovi, kdaj uporabnik začne in neha govoriti, tako da agent ve, kdaj poslušati in kdaj odgovoriti, brez potrebe po gumbu.
3. Kako teče zvok?
Odgovor: Vhod gre ven prek input_audio_buffer.append (s potrditvijo in izbrisom medpomnilnika), odgovor pa prispe kot zvočni dogodki za predvajanje, v formatu PCM ali G.711, odvisno od kanala.
4. Kaj omogočajo orodja in MCP v glasovnem pogovoru?
Odgovor: Klicanje funkcij in vgrajena orodja (splet, X, zbirke) med govorno izmenjavo: agent poišče informacije in ukrepa med govorom, vključno z dogodki MCP.
5. In za telefonijo?
Odgovor: SIP in LiveKit z G.711: glasovni agent se priklopi v telefonsko omrežje, pripomočki za pretvorbo zvoka v Pythonu pa premostijo formate.
Varna seja, VAD, dobro upravljani medpomnilniki, orodja v glasu: popoln telefonski asistent je dosegljiv in ta tečaj ti je dal vse potrebne dele.