Preskok na glavno vsebino
Slovenščina— Izberite jezik
Meni

Pripomočki za pretvorbo zvoka v Pythonu

Lekcija 16 od 16 Posodobljeno 30. julij 2026 Razvijalec
Na tej strani
  1. Knjižnica za zvočne pripomočke
  2. PCM16 v base64 in obratno
  3. Vzorčenje (Resampling)
  4. Pretvorba med G.711 in PCM
  5. Detekcija tišine na strani odjemalca
  6. Shranjevanje in nalaganje datotek WAV
  7. Ključne ugotovitve
  8. Preveri svoje razumevanje

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_base64 in base64_to_audio sta 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 audioop obravnava 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 namesti audioop-lts iz 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.