Hulpprogramma's voor audioconversie in Python
Op deze pagina
Een bibliotheek voor audioutiliteiten
Om een robuuste Voice Agent-app te bouwen, heeft u hulpfuncties nodig die audio tussen formaten converteren. Deze les bundelt de essentiële Python-tools voor realtime audiobewerking.
PCM16 naar base64 en terug
Dit zijn de twee functies die u het meest zult gebruiken: het coderen van opgenomen audio in base64 om deze te verzenden, en het decoderen van ontvangen base64-audio om deze af te spelen.
import base64
import numpy as np
def audio_to_base64(audio_data: np.ndarray) -> str:
"""Converteert een float32 numpy-array in [-1, 1] naar 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:
"""Converteert een base64 PCM16-tekenreeks naar een 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
Gebruik in de Voice Agent-flow
import pyaudio
import json
# Microfoonopname → verzenden
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
}))
# Ontvangen → afspelen
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())
Resamplen
Als uw microfoon opneemt met een andere samplefrequentie dan de API verwacht, moet u resamplen:
from scipy.signal import resample
def resample_audio(
audio: np.ndarray,
original_rate: int,
target_rate: int
) -> np.ndarray:
"""Resamplet audio van de ene samplefrequentie naar de andere."""
if original_rate == target_rate:
return audio
num_samples = int(len(audio) * target_rate / original_rate)
return resample(audio, num_samples)
# Voorbeeld: microfoon op 44100 Hz → API op 24000 Hz
audio_44100 = capture_microphone()
audio_24000 = resample_audio(audio_44100, 44100, 24000)
b64 = audio_to_base64(audio_24000)
Converteren tussen G.711 en PCM
Voor telefonie-integraties moet u converteren tussen G.711 en lineaire PCM. Let op uw Python-versie: audioop is verwijderd uit de standaardbibliotheek in versie 3.13. Installeer op een recente Python-versie het pakket audioop-lts, dat dezelfde interface biedt:
import audioop
def pcm_to_mulaw(pcm_data: bytes) -> bytes:
"""Converteert PCM16 naar G.711 mu-law."""
return audioop.lin2ulaw(pcm_data, 2)
def mulaw_to_pcm(mulaw_data: bytes) -> bytes:
"""Converteert G.711 mu-law naar PCM16."""
return audioop.ulaw2lin(mulaw_data, 2)
def pcm_to_alaw(pcm_data: bytes) -> bytes:
"""Converteert PCM16 naar G.711 A-law."""
return audioop.lin2alaw(pcm_data, 2)
def alaw_to_pcm(alaw_data: bytes) -> bytes:
"""Converteert G.711 A-law naar PCM16."""
return audioop.alaw2lin(alaw_data, 2)
Een complete telefoonrelay
Hier volgt een voorbeeld van een relay tussen een G.711 SIP-stream en de Voice Agent API:
async def relay_sip_to_voice_agent(sip_stream, ws):
"""Relayt audio van een SIP-oproep naar de Voice Agent API."""
async for mulaw_chunk in sip_stream:
# Converteer 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):
"""Relayt de audiorespons van de API naar de 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)
Stilte-detectie aan de clientzijde
Als u push-to-talk zelf afhandelt, of lokale stilte-detectie wilt uitvoeren voordat u verzendt, meet deze functie de energie van het signaal:
def is_silence(
audio: np.ndarray,
threshold: float = 0.01
) -> bool:
"""Detecteert of een audiofragment stilte is."""
rms = np.sqrt(np.mean(audio ** 2))
return rms < threshold
# Gebruik
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-bestanden opslaan en laden
Voor debugging en testen kunt u WAV-bestanden opslaan en laden:
import wave
def save_wav(
filename: str,
audio: np.ndarray,
sample_rate: int = 24000
):
"""Slaat een numpy-array op als een WAV-bestand."""
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]:
"""Laadt een WAV-bestand als een 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
Belangrijkste punten
audio_to_base64enbase64_to_audiozijn de twee essentiële functies voor de Voice Agent-flow- Resamplen is nodig wanneer de samplefrequentie van uw microfoon niet overeenkomt met die van de API
- De module
audioophandelt conversies voor G.711 mu-law en A-law af; deze is verwijderd uit de standaardbibliotheek in Python 3.13, dus installeeraudioop-ltsvia PyPI op recente versies - Stilte-detectie aan de clientzijde bespaart bandbreedte door alleen nuttige audio te verzenden
- WAV-hulpprogramma’s maken debugging eenvoudiger door audiostreams op te slaan en opnieuw af te spelen
Controleer uw begrip
WebSocket, VAD, audio: de voice agent van begin tot eind.
1. Hoe stelt u een Voice Agent-sessie in?
Antwoord: Met een realtime WebSocket-verbinding, geverifieerd met ephemeral tokens (nooit de hoofdsleutel op de client), vervolgens geconfigureerd via session.update en bevestigd door session.created en session.updated.
2. Wat handelt VAD af?
Antwoord: Automatische spraakdetectie: het bepaalt wanneer de gebruiker begint en stopt met spreken, zodat de agent weet wanneer hij moet luisteren en wanneer moet antwoorden, zonder knop.
3. Hoe verloopt de audioflow?
Antwoord: Input gaat eruit via input_audio_buffer.append (met buffer commit en clear), en de respons komt binnen als audio-events om af te spelen, in PCM of G.711 afhankelijk van het kanaal.
4. Wat maken tools en MCP mogelijk in een voice-gesprek?
Antwoord: Function calling en ingebouwde tools (web, X, collections) tijdens de gesproken uitwisseling: de agent zoekt dingen op en onderneemt actie terwijl hij spreekt, inclusief MCP-events.
5. En voor telefonie?
Antwoord: SIP en LiveKit met G.711: de voice agent koppelt aan het telefoonnetwerk, en de Python-hulpprogramma’s voor audioconversie overbruggen de formaten.
Een beveiligde sessie, VAD, goed beheerde buffers, tools in voice: de complete telefoonassistent is binnen handbereik, en deze cursus heeft u elk onderdeel gegeven.