Værktøjer til lydkonvertering i Python
På denne side
Et bibliotek til lydværktøjer
For at bygge en robust Voice Agent-app har du brug for hjælpefunktioner, der konverterer lyd mellem forskellige formater. Denne lektion samler de essentielle Python-værktøjer til realtidsbehandling af lyd.
PCM16 til base64 og tilbage igen
Dette er de to funktioner, du vil bruge oftest: kodning af optaget lyd til base64 for at sende den, og afkodning af modtaget base64-lyd for at afspille den.
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
Brug af dem i Voice Agent-flowet
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())
Resampling
Hvis din mikrofon optager med en anden sample rate, end API’et forventer, skal du resample lyden:
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)
Konvertering mellem G.711 og PCM
Ved telefonintegration skal du konvertere mellem G.711 og lineær PCM. Vær opmærksom på din Python-version: audioop blev fjernet fra standardbiblioteket i version 3.13. På nyere Python-versioner skal du installere pakken audioop-lts, som giver den samme grænseflade:
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)
Et komplet telefon-relæ
Her er et eksempel på et relæ mellem en G.711 SIP-strøm og Voice Agent API’et:
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)
Stillethedsgenkendelse på klientsiden
Hvis du selv håndterer push-to-talk, eller ønsker lokal genkendelse af stilhed før afsendelse, måler denne funktion signalets energi:
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
}))
Gemme og indlæse WAV-filer
Til fejlfinding og test kan du gemme og indlæse WAV-filer:
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
Vigtige pointer
audio_to_base64ogbase64_to_audioer de to essentielle funktioner til Voice Agent-flowet- Resampling er nødvendigt, når din mikrofon’s sample rate ikke matcher API’ets
- Modulet
audioophåndterer konvertering af G.711 mu-law og A-law; det blev fjernet fra standardbiblioteket i Python 3.13, så installeraudioop-ltsfra PyPI på nyere versioner - Stillethedsgenkendelse på klientsiden sparer båndbredde ved kun at sende brugbar lyd
- WAV-værktøjer gør fejlfinding lettere ved at lade dig gemme og afspille lydstrømme igen
Tjek din forståelse
WebSocket, VAD, lyd: voice agenten fra ende til ende.
1. Hvordan opsætter du en Voice Agent-session?
Svar: Med en realtids WebSocket-forbindelse, autentificeret med ephemeral tokens (brug aldrig hovednøglen på klienten), derefter konfigureret via session.update og bekræftet af session.created og session.updated.
2. Hvad håndterer VAD?
Svar: Automatisk talegenkendelse: det finder ud af, hvornår brugeren begynder og holder op med at tale, så agenten ved, hvornår den skal lytte, og hvornår den skal svare, uden nogen knap.
3. Hvordan flyder lyden?
Svar: Input sendes ud gennem input_audio_buffer.append (med buffer commit og clear), og svaret ankommer som lyd-events til afspilning, i PCM eller G.711 afhængigt af kanalen.
4. Hvad muliggør tools og MCP i en talesamtale?
Svar: Funktionskald og indbyggede værktøjer (web, X, collections) under den talte udveksling: agenten slår ting op og handler, mens den taler, inklusive MCP-events.
5. Og hvad med telefoni?
Svar: SIP og LiveKit med G.711: voice agenten kobles til telefonnetværket, og Python-værktøjerne til lydkonvertering brobygger mellem formaterne.
En sikker session, VAD, velhåndterede buffers, tools i tale: den komplette telefonassistent er inden for rækkevidde, og dette kursus har givet dig alle brikkerne.