Heli teisendamise utiliitide kasutamine Pythonis
Sellel lehel
Heli utiliitide teek
Tugeva Voice Agent rakenduse loomiseks vajad utiliitfunktsioone, mis teisendavad heli vormingute vahel. See õppetund koondab olulisemad Pythoni tööriistad reaalajas helitöötluseks.
PCM16 baas64-ks ja tagasi
Need on kaks funktsiooni, mida kasutad kõige sagedamini: salvestatud heli kodeerimine baas64-vormingusse saatmiseks ja vastuvõetud baas64-heli dekodeerimine esitamiseks.
import base64
import numpy as np
def audio_to_base64(audio_data: np.ndarray) -> str:
"""Teisendab float32 numpy massiivi vahemikus [-1, 1] baas64 PCM16-ks."""
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:
"""Teisendab baas64 PCM16 stringi float32 numpy massiiviks."""
audio_bytes = base64.b64decode(base64_audio)
audio_int16 = np.frombuffer(audio_bytes, dtype=np.int16)
return audio_int16.astype(np.float32) / 32768.0
Kasutamine Voice Agenti voos
import pyaudio
import json
# Mikrofoni salvestus → saatmine
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
}))
# Vastuvõtt → esitamine
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())
Diskreetimissageduse muutmine (Resampling)
Kui su mikrofon salvestab teise diskreetimissagedusega kui API eeldab, pead heli ümber diskreetima:
from scipy.signal import resample
def resample_audio(
audio: np.ndarray,
original_rate: int,
target_rate: int
) -> np.ndarray:
"""Muudab heli diskreetimissagedust ühelt sageduselt teisele."""
if original_rate == target_rate:
return audio
num_samples = int(len(audio) * target_rate / original_rate)
return resample(audio, num_samples)
# Näide: mikrofon 44100 Hz → API 24000 Hz
audio_44100 = capture_microphone()
audio_24000 = resample_audio(audio_44100, 44100, 24000)
b64 = audio_to_base64(audio_24000)
Teisendamine G.711 ja PCM vahel
Telefonilahenduste jaoks pead teisendama G.711 ja lineaarse PCM vahel. Jälgi oma Pythoni versiooni: moodul audioop eemaldati standardteegist versioonis 3.13. Uuemal Pythonil installi pakett audioop-lts, mis pakub sama liidest:
import audioop
def pcm_to_mulaw(pcm_data: bytes) -> bytes:
"""Teisendab PCM16 G.711 mu-law vormingusse."""
return audioop.lin2ulaw(pcm_data, 2)
def mulaw_to_pcm(mulaw_data: bytes) -> bytes:
"""Teisendab G.711 mu-law PCM16-ks."""
return audioop.ulaw2lin(mulaw_data, 2)
def pcm_to_alaw(pcm_data: bytes) -> bytes:
"""Teisendab PCM16 G.711 A-law vormingusse."""
return audioop.lin2alaw(pcm_data, 2)
def alaw_to_pcm(alaw_data: bytes) -> bytes:
"""Teisendab G.711 A-law PCM16-ks."""
return audioop.alaw2lin(alaw_data, 2)
Täielik telefonirelee
Siin on näide releeprotsessist G.711 SIP voogu ja Voice Agent API vahel:
async def relay_sip_to_voice_agent(sip_stream, ws):
"""Suunab heli SIP kõnest Voice Agent API-le."""
async for mulaw_chunk in sip_stream:
# Teisenda 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):
"""Suunab API helivastuse SIP voogu."""
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)
Kliendipoolne vaikuse tuvastamine
Kui haldad ise „vajuta-räägi“ (push-to-talk) funktsiooni või soovid enne saatmist kohalikku vaikuse tuvastamist, mõõdab see funktsioon signaali energiat:
def is_silence(
audio: np.ndarray,
threshold: float = 0.01
) -> bool:
"""Tuvastab, kas helilõik on vaikus."""
rms = np.sqrt(np.mean(audio ** 2))
return rms < threshold
# Kasutamine
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-failide salvestamine ja laadimine
Silumiseks ja testimiseks saad salvestada ja laadida WAV-faile:
import wave
def save_wav(
filename: str,
audio: np.ndarray,
sample_rate: int = 24000
):
"""Salvestab numpy massiivi WAV-failina."""
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]:
"""Laeb WAV-faili float32 numpy massiivina."""
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
Peamised punktid
audio_to_base64jabase64_to_audioon kaks põhifunktsiooni Voice Agenti voo jaoks- Diskreetimissageduse muutmine on vajalik, kui su mikrofoni sagedus ei ühti API omaga
- Moodul
audioophaldab G.711 mu-law ja A-law teisendusi; see eemaldati Pythoni standardteegist versioonis 3.13, seega installi uuematel versioonidelaudioop-ltsPyPI-st - Kliendipoolne vaikuse tuvastamine säästab ribalaiust, saates ainult kasulikku heli
- WAV-utiliidid lihtsustavad silumist, võimaldades helivooge salvestada ja taasesitada
Kontrolli oma arusaamist
WebSocket, VAD, heli: kõneagent algusest lõpuni.
1. Kuidas seadistad Voice Agenti seansi?
Vastus: Reaalajas WebSocketi ühendusega, autentides ajutiste tokenitega (mitte kunagi peavõtit kliendil), seejärel konfigureerides session.update kaudu ja kinnitades session.created ning session.updated sündmustega.
2. Mida VAD haldab?
Vastus: Automaatset kõne tuvastamist: see selgitab välja, millal kasutaja rääkima hakkab ja lõpetab, nii et agent teab, millal kuulata ja millal vastata, ilma nuputa.
3. Kuidas heli liigub?
Vastus: Sisend väljub input_audio_buffer.append kaudu (koet puhvri kinnitamise ja tühjendamisega) ning vastus saabub esitamiseks mõeldud helisündmustena, kas PCM või G.711 vormingus, olenevalt kanalist.
4. Mida võimaldavad tööriistad ja MCP kõnevestluses?
Vastus: Funktsioonide kutsumist ja sisseehitatud tööriistu (veeb, X, kogumikud) suulise vahetuse ajal: agent otsib asju üles ja tegutseb rääkimise ajal, kaasa arvatud MCP sündmused.
5. Ja telefonside puhul?
Vastus: SIP ja LiveKit koos G.711-ga: kõneagent ühendub telefonivõrguga ning Pythoni heliteisendamise utiliitidest saavad sildaks vormingute vahel.
Turvaline seanss, VAD, hästi hallatud puhvrid, tööriistad hääles: täiuslik telefonassistent on käeulatuses ja see kursus on andnud sulle kõik vajalikud osad.