Preskoči na glavni sadržaj
Hrvatski— Odaberite jezik
Izbornik

Alati za konverziju zvuka u Pythonu

Lekcija 16 od 16 Ažurirano 30. srpnja 2026. Programer
Na ovoj stranici
  1. Knjižnica uslužnih programa za zvuk
  2. PCM16 u base64 i obrnuto
  3. Promjena uzorkovanja (Resampling)
  4. Konverzija između G.711 i PCM formata
  5. Detekcija tišine na strani klijenta
  6. Spremanje i učitavanje WAV datoteka
  7. Ključne točke
  8. Provjeri svoje razumijevanje

Knjižnica uslužnih programa za zvuk

Za izgradnju robustne aplikacije glasovnog agenta trebaju ti uslužne funkcije koje pretvaraju zvuk između različitih formata. Ova lekcija okuplja ključne Python alate za obradu zvuka u stvarnom vremenu.

PCM16 u base64 i obrnuto

Ovo su dvije funkcije koje ćeš najčešće koristiti: kodiranje snimljenog zvuka u base64 za slanje i dekodiranje primljenog base64 zvuka za reprodukciju.

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

Korištenje u tijeku rada glasovnog agenta

import pyaudio
import json

# Snimanje mikrofona → slanje
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
    }))

# Primanje → reprodukcija
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())

Promjena uzorkovanja (Resampling)

Ako tvoj mikrofon snima na drugačijoj frekvenciji uzorkovanja nego što API očekuje, moraš izvršiti promjenu uzorkovanja:

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)

# Primjer: 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)

Konverzija između G.711 i PCM formata

Za integracije s telefonijom trebat ćeš pretvarati podatke između G.711 i linearnog PCM formata. Pazi na svoju verziju Pythona: modul audioop uklonjen je iz standardne knjižnice u verziji 3.13. Na novijim verzijama Pythona instaliraj paket audioop-lts, koji pruža isto sučelje:

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)

Potpuni telefonski relej

Evo primjera releja između G.711 SIP strujanja i Voice Agent API-ja:

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:
        # Konverzija 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 klijenta

Ako samostalno upravljaš funkcijom „pritisni za govor“ (push-to-talk) ili želiš lokalnu detekciju tišine prije slanja, ova funkcija mjeri energiju 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

# Upotreba
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
    }))

Spremanje i učitavanje WAV datoteka

Za otklanjanje pogrešaka i testiranje možeš spremati i učitavati WAV datoteke:

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 točke

  • audio_to_base64 i base64_to_audio dvije su ključne funkcije za tijek rada glasovnog agenta
  • Promjena uzorkovanja potrebna je kada se frekvencija uzorkovanja tvog mikrofona ne podudara s onom koju zahtijeva API
  • Modul audioop rukuje konverzijama G.711 mu-law i A-law formata; uklonjen je iz standardne knjižnice u Pythonu 3.13, stoga na novijim verzijama instaliraj audioop-lts s PyPI-ja
  • Detekcija tišine na strani klijenta širi propusnost slanjem samo korisnog zvuka
  • WAV uslužni programi olakšavaju otklanjanje pogrešaka omogućujući ti spremanje i ponovnu reprodukciju zvučnih strujanja

Provjeri svoje razumijevanje

WebSocket, VAD, zvuk: glasovni agent od početka do kraja.

1. Kako postavljaš sesiju glasovnog agenta?

Odgovor: Putem WebSocket veze u stvarnom vremenu, autentificirane privremenim tokenima (nikada glavnim ključem na klijentu), zatim konfigurirane kroz session.update i potvrđene događajima session.created i session.updated.

2. Što rješava VAD?

Odgovor: Automatsko otkrivanje govora: utvrđuje kada korisnik počinje i prestaje govoriti, tako da agent zna kada slušati, a kada odgovoriti, bez potrebe za gumbom.

3. Kako teče zvuk?

Odgovor: Ulazni zvuk odlazi kroz input_audio_buffer.append (uz commit i clear međuspremnika), a odgovor stiže kao zvučni događaji za reprodukciju, u PCM ili G.711 formatu, ovisno o kanalu.

4. Što alati i MCP omogućuju u glasovnom razgovoru?

Odgovor: Pozivanje funkcija i ugrađeni alati (web, X, kolekcije) tijekom govorne razmjene: agent traži informacije i poduzima radnje dok govori, uključujući i MCP događaje.

5. A što je s telefonijom?

Odgovor: SIP i LiveKit s G.711: glasovni agent spaja se na telefonsku mrežu, a Pythonovi uslužni programi za konverziju zvuka moste različite formate.

Sigurna sesija, VAD, dobro upravljani međuspremnici, alati u glasu: kompletan telefonski asistent je na dohvat ruke, a ovaj tečaj dao ti je svaki potrebni dio.