Narzędzia do konwersji audio w Pythonie
Na tej stronie
Biblioteka narzędziowa do obsługi audio
Aby zbudować solidną aplikację Voice Agent, potrzebujesz funkcji pomocniczych konwertujących audio między różnymi formatami. Ta lekcja zbiera najważniejsze narzędzia Pythona do przetwarzania audio w czasie rzeczywistym.
PCM16 do base64 i z powrotem
Oto dwie funkcje, których będziesz używać najczęściej: kodowanie przechwyconego audio do base64 w celu wysłania go oraz dekodowanie otrzymanego audio w formacie base64 w celu jego odtworzenia.
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
Wykorzystanie ich w przepływie Voice Agent
import pyaudio
import json
# Przechwytywanie z mikrofonu → wysyłanie
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
}))
# Odbieranie → odtwarzanie
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())
Zmiana częstotliwości próbkowania (Resampling)
Jeśli Twój mikrofon rejestruje dźwięk z inną częstotliwością próbkowania niż oczekuje API, musisz dokonać resamplingu:
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)
# Przykład: mikrofon 44100 Hz → API 24000 Hz
audio_44100 = capture_microphone()
audio_24000 = resample_audio(audio_44100, 44100, 24000)
b64 = audio_to_base64(audio_24000)
Konwersja między G.711 a PCM
W przypadku integracji telefonicznych konieczna będzie konwersja między formatem G.711 a liniowym PCM. Zwróć uwagę na wersję Pythona: moduł audioop został usunięty z biblioteki standardowej w wersji 3.13. Na nowszych wersjach Pythona zainstaluj pakiet audioop-lts, który zapewnia ten sam interfejs:
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)
Kompleksowe przekaźnik telefoniczny
Oto przykład przekaźnika (relay) między strumieniem SIP G.711 a API 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:
# Konwersja 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)
Wykrywanie ciszy po stronie klienta
Jeśli samodzielnie obsługujesz tryb „naciśnij i mów“ (push-to-talk) lub chcesz wykrywać ciszę lokalnie przed wysłaniem danych, ta funkcja mierzy energię sygnału:
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
# Użycie
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
}))
Zapisywanie i wczytywanie plików WAV
Do celów debugowania i testowania możesz zapisywać i wczytywać pliki 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
Kluczowe wnioski
audio_to_base64ibase64_to_audioto dwie kluczowe funkcje niezbędne do działania przepływu Voice Agent.- Zmiana częstotliwości próbkowania (resampling) jest konieczna, gdy częstotliwość Twojego mikrofonu nie zgadza się z wymaganą przez API.
- Moduł
audioopobsługuje konwersje G.711 mu-law i A-law; został on usunięty z biblioteki standardowej w Pythonie 3.13, więc na nowszych wersjach zainstalujaudioop-ltsz PyPI. - Wykrywanie ciszy po stronie klienta oszczędza przepustowość, wysyłając tylko użyteczne fragmenty audio.
- Narzędzia do obsługi WAV ułatwiają debugowanie, pozwalając na zapisywanie i odtwarzanie strumieni audio.
Sprawdź swoją wiedzę
WebSocket, VAD, audio: agent głosowy od początku do końca.
1. Jak skonfigurować sesję Voice Agent?
Odpowiedź: Poprzez połączenie WebSocket w czasie rzeczywistym, uwierzytelnione za pomocą tymczasowych tokenów (nigdy nie używaj głównego klucza po stronie klienta), a następnie skonfigurowane przez session.update i potwierdzone zdarzeniami session.created oraz session.updated.
2. Co obsługuje VAD?
Odpowiedź: Automatyczne wykrywanie mowy: określa, kiedy użytkownik zaczyna i kończy mówić, dzięki czemu agent wie, kiedy słuchać, a kiedy odpowiadać – bez konieczności naciskania żadnych przycisków.
3. Jak przepływa audio?
Odpowiedź: Dane wejściowe są wysyłane przez input_audio_buffer.append (z zatwierdzaniem i czyszczeniem bufora), a odpowiedź przychodzi jako zdarzenia audio do odtworzenia, w formacie PCM lub G.711, w zależności od kanału.
4. Co umożliwiają narzędzia i MCP w rozmowie głosowej?
Odpowiedź: Wywoływanie funkcji i wbudowane narzędzia (sieć, X, kolekcje) podczas wymiany zdań: agent wyszukuje informacje i podejmuje działania w trakcie mówienia, uwzględniając również zdarzenia MCP.
5. A jak to wygląda w telefonii?
Odpowiedź: SIP i LiveKit z G.711: agent głosowy integruje się z siecią telefoniczną, a narzędzia do konwersji audio w Pythonie mostkują różne formaty.
Bezpieczna sesja, VAD, dobrze zarządzane bufory, narzędzia w głosie: kompletny asystent telefoniczny jest w Twoim zasięgu, a ten kurs dostarczył Ci wszystkich niezbędnych elementów.