Lähe põhisisu juurde
Eesti— Vali keel
Menüü

Heli teisendamise utiliitide kasutamine Pythonis

Õppetund 16 / 16 Värskendatud 30. juuli 2026 Arendajatele
Sellel lehel
  1. Heli utiliitide teek
  2. PCM16 baas64-ks ja tagasi
  3. Diskreetimissageduse muutmine (Resampling)
  4. Teisendamine G.711 ja PCM vahel
  5. Kliendipoolne vaikuse tuvastamine
  6. WAV-failide salvestamine ja laadimine
  7. Peamised punktid
  8. Kontrolli oma arusaamist

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_base64 ja base64_to_audio on kaks põhifunktsiooni Voice Agenti voo jaoks
  • Diskreetimissageduse muutmine on vajalik, kui su mikrofoni sagedus ei ühti API omaga
  • Moodul audioop haldab G.711 mu-law ja A-law teisendusi; see eemaldati Pythoni standardteegist versioonis 3.13, seega installi uuematel versioonidel audioop-lts PyPI-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.