Utilitare de conversie audio în Python
Pe această pagină
O bibliotecă de utilitare audio
Pentru a construi o aplicație robustă de Agent Vocal, aveți nevoie de funcții utilitare care convertesc audio între diferite formate. Această lecție reunește instrumentele Python esențiale pentru procesarea audio în timp real.
De la PCM16 la base64 și invers
Acestea sunt cele două funcții pe care le veți utiliza cel mai des: codificarea audio capturat în base64 pentru a-l trimite și decodificarea audio base64 primit pentru a-l reda.
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
Utilizarea lor în fluxul Agentului Vocal
import pyaudio
import json
# Captare microfon → trimitere
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
}))
# Recepție → redare
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 (Schimbarea frecvenței de eșantionare)
Dacă microfonul dumneavoastră captează la o frecvență de eșantionare diferită de cea așteptată de API, trebuie să efectuați un resampling:
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)
# Exemplu: microfon la 44100 Hz → API la 24000 Hz
audio_44100 = capture_microphone()
audio_24000 = resample_audio(audio_44100, 44100, 24000)
b64 = audio_to_base64(audio_24000)
Conversia între G.711 și PCM
Pentru integrările telefonice, va trebui să convertiți între G.711 și PCM liniar. Acordați atenție versiunii de Python: modulul audioop a fost eliminat din biblioteca standard în versiunea 3.13. Pe o versiune recentă de Python, instalați pachetul audioop-lts, care oferă aceeași interfață:
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)
Un releu telefonic complet
Iată un exemplu de releu între un flux SIP G.711 și API-ul 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:
# Convertire 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)
Detectarea silențiului lato-client
Dacă gestionați singuri funcția „push-to-talk“ sau doriți o detectare locală a silențiului înainte de trimitere, această funcție măsoară energia semnalului:
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
# Utilizare
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
}))
Salvarea și încărcarea fișierelor WAV
Pentru depanare și testare, puteți salva și încărca fișiere 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
Puncte cheie
audio_to_base64șibase64_to_audiosunt cele două funcții esențiale pentru fluxul Agentului Vocal- Resampling-ul este necesar atunci când frecvența de eșantionare a microfonului nu corespunde cu cea a API-ului
- Modulul
audioopgestionează conversiile G.711 mu-law și A-law; acesta a fost eliminat din biblioteca standard în Python 3.13, așa că instalațiaudioop-ltsdin PyPI pe versiunile recente - Detectarea silențiului lato-client economisește lățimea de bandă prin trimiterea doar a audio-ului util
- Utilitarele WAV facilitează depanarea, permițându-vă să salvați și să redați fluxuri audio
Verificați-vă cunoștințele
WebSocket, VAD, audio: agentul vocal de la un capăt la altul.
1. Cum configurați o sesiune de Agent Vocal?
Răspuns: Printr-o conexiune WebSocket în timp real, autentificată cu tokeni efemeri (niciodată cheia principală pe client), apoi configurată prin session.update și confirmată de session.created și session.updated.
2. Ce gestionează VAD?
Răspuns: Detectarea automată a vorbirii: stabilește când utilizatorul începe și se oprește din vorbit, astfel încât agentul să știe când să asculte și când să răspundă, fără niciun buton.
3. Cum circulă audio-ul?
Răspuns: Intrarea iese prin input_audio_buffer.append (cu commit și clear al buffer-ului), iar răspunsul sosește sub formă de evenimente audio de redat, în PCM sau G.711, în funcție de canal.
4. Ce permit instrumentele și MCP într-o conversație vocală?
Răspuns: Apelarea de funcții și instrumente integrate (web, X, colecții) în timpul schimbului verbal: agentul caută informații și întreprinde acțiuni în timp ce vorbește, inclusiv evenimente MCP.
5. Și pentru telefonie?
Răspuns: SIP și LiveKit cu G.711: agentul vocal se conectează la rețeaua telefonică, iar utilitarele de conversie audio Python fac legătura între formate.
O sesiune securizată, VAD, buffere gestionate corect, instrumente în voce: asistentul telefonic complet este la îndemână, iar acest curs v-a oferit fiecare piesă necesară.