Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

Äänenmuunnosapuvälineet Pythonissa

Oppitunti 16 / 16 Päivitetty 30. heinäkuuta 2026 Kehittäjä
Tällä sivulla
  1. Äänenkäsittelyn apukirjasto
  2. PCM16:n ja base64:n välinen muunnos
  3. Näytetaajuuden muunnos (Resampling)
  4. Muunnos G.711:n ja PCM:n välillä
  5. Asiakaspään hiljaisuuden tunnistus
  6. WAV-tiedostojen tallennus ja lataus
  7. Keskeiset asiat
  8. Testaa ymmärryksesi

Äänenkäsittelyn apukirjasto

Jotta voit rakentaa toimivan Voice Agent -sovelluksen, tarvitset apufunktioita, jotka muuntavat ääntä eri formaattien välillä. Tämä oppitunti kokoaa yhteen keskeiset Python-työkalut reaaliaikaiseen äänenkäsittelyyn.

PCM16:n ja base64:n välinen muunnos

Nämä ovat kaksi funktiota, joita tulet käyttämään useimmiten: kaapatun äänen koodaaminen base64-muotoon lähetystä varten ja vastaanotetun base64-äänen purkaminen toistamista varten.

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

Käyttö Voice Agent -vuossa

import pyaudio
import json

# Mic capture → send
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
    }))

# Receive → play
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())

Näytetaajuuden muunnos (Resampling)

Jos mikrofonisi tallentaa eri näytetaajuudella kuin mitä API odottaa, sinun on suoritettava näytetaajuuden muunnos:

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)

# Example: mic at 44100 Hz → API at 24000 Hz
audio_44100 = capture_microphone()
audio_24000 = resample_audio(audio_44100, 44100, 24000)
b64 = audio_to_base64(audio_24000)

Muunnos G.711:n ja PCM:n välillä

Puhelinintegraatioita varten sinun on muunnettava G.711:n ja lineaarisen PCM:n välillä. Huomioi Python-versiosi: audioop poistettiin vakiokirjastosta versiossa 3.13. Uudemmassa Pythonissa asenna audioop-lts-paketti, joka tarjoaa saman rajapinnan:

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)

Täydellinen puhelinvälitys

Tässä on esimerkki välityksestä G.711-SIP-virran ja Voice Agent API:n välillä:

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

Asiakaspään hiljaisuuden tunnistus

Jos hallitset puheenvuoron aloitusta itse tai haluat paikallisen hiljaisuuden tunnistuksen ennen lähetystä, tämä funktio mittaa signaalin energiaa:

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

# Usage
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-tiedostojen tallennus ja lataus

Virheenkorjausta ja testausta varten voit tallentaa ja ladata WAV-tiedostoja:

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

Keskeiset asiat

  • audio_to_base64 ja base64_to_audio ovat kaksi keskeistä funktiota Voice Agent -vuolle
  • Näytetaajuuden muunnos on tarpeen, kun mikrofonisi näytetaajuus ei täsmää API:n kanssa
  • audioop-moduuli hoitaa G.711 mu-law- ja A-law-muunnokset; se poistettiin vakiokirjastosta Python 3.13:ssa, joten asenna audioop-lts PyPI:stä uusimmissa versioissa
  • Asiakaspään hiljaisuuden tunnistus säästää kaistanleveyttä lähettämällä vain hyödyllistä ääntä
  • WAV-apuvälineet helpottavat virheenkorjausta mahdollistamalla äänivirtojen tallentamisen ja toistamisen

Testaa ymmärryksesi

WebSocket, VAD, ääni: voice agent alusta loppuun.

1. Miten määrität Voice Agent -istunnon?

Vastaus: Reaaliaikaisella WebSocket-yhteydellä, joka on todennettu väliaikaisilla tunnuksilla (ei koskaan pääavaimella asiakaspäässä), ja joka määritetään session.update-kutsulla sekä vahvistetaan session.created- ja session.updated-tapahtumilla.

2. Mitä VAD hoitaa?

Vastaus: Automaattisen puheen tunnistuksen: se selvittää, milloin käyttäjä alkaa ja lopettaa puhumisen, jotta agentti tietää, milloin kuunnella ja milloin vastata, ilman painikkeita.

3. Miten ääni virtaa?

Vastaus: Syöte lähtee input_audio_buffer.append-komennolla (puskurin commit ja clear), ja vastaus saapuu toistettavina äänitapahtumina PCM- tai G.711-muodossa kanavasta riippuen.

4. Mitä työkalut ja MCP mahdollistavat äänikeskustelussa?

Vastaus: Funktiokutsut ja sisäänrakennetut työkalut (web, X, kokoelmat) puhutun vuorovaikutuksen aikana: agentti hakee tietoja ja ryhtyy toimiin puhuessaan, mukaan lukien MCP-tapahtumat.

5. Entä puhelinkäyttö?

Vastaus: SIP ja LiveKit G.711:n kanssa: voice agent liittyy puhelinverkkoon, ja Pythonin äänenmuunnosapuvälineet siltaavat formaatit.

Turvallinen istunto, VAD, hyvin hallitut puskurit, työkalut äänessä: täydellinen puhelinavustaja on ulottuvillasi, ja tämä kurssi on antanut sinulle kaikki tarvittavat osat.