Βοηθητικά εργαλεία μετατροπής ήχου στην Python
Σε αυτήν τη σελίδα
Μια βιβλιοθήκη βοηθητικών εργαλείων ήχου
Για να δημιουργήσετε μια αξιόπιστη εφαρμογή Voice Agent, χρειάζεστε συναρτήσεις βοηθητικών εργαλείων που μετατρέπουν τον ήχο μεταξύ διαφορετικών μορφών. Αυτό το μάθημα συγκεντρώνει τα απαραίτητα εργαλεία Python για την επεξεργασία ήχου σε πραγματικό χρόνο.
Μετατροπή PCM16 σε base64 και αντίστροφα
Αυτές είναι οι δύο συναρτήσεις που θα χρησιμοποιείτε συχνότερα: κωδικοποίηση του καταγεγραμμένου ήχου σε base64 για αποστολή και αποκωδικοποίηση του ληφθέντος ήχου base64 για αναπαραγωγή.
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
Χρήση τους στη ροή του Voice Agent
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)
Εάν το μικρόφωνό σας καταγράφει με διαφορετική συχνότητα δειγματοληψίας από αυτήν που αναμένει το API, πρέπει να κάνετε 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)
# 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)
Μετατροπή μεταξύ G.711 και PCM
Για ενσωματώσεις τηλεφωνίας, θα χρειαστεί να μετατρέπετε μεταξύ G.711 και γραμμικού PCM. Προσέξτε την έκδοση της Python σας: το audioop αφαιρέθηκε από την τυπική βιβλιοθήκη στην 3.13. Σε μια πρόσφατη Python, εγκαταστήστε το πακέτο audioop-lts, το οποίο παρέχει την ίδια διεπαφή:
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)
Ένας πλήρης αναμεταδότης τηλεφωνίας
Ακολουθεί ένα παράδειγμα αναμετάδοσης μεταξύ μιας ροής SIP G.711 και του Voice Agent API:
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)
Ανίχνευση σιωπής στην πλευρά του πελάτη
Εάν διαχειρίζεστε μόνοι σας τη λειτουργία push-to-talk ή θέλετε τοπική ανίχνευση σιωπής πριν την αποστολή, αυτή η συνάρτηση μετρά την ενέργεια του σήματος:
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
Για αποσφαλμάτωση και δοκιμές, μπορείτε να αποθηκεύσετε και να φορτώσετε αρχεία 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
Βασικά σημεία
- Οι
audio_to_base64καιbase64_to_audioείναι οι δύο βασικές συναρτήσεις για τη ροή του Voice Agent - Το resampling είναι απαραίτητο όταν η συχνότητα δειγματοληψίας του μικροφώνου σας δεν ταιριάζει με αυτήν του API
- Η ενότητα
audioopδιαχειρίζεται τις μετατροπές G.711 mu-law και A-law· αφαιρέθηκε από την τυπική βιβλιοθήκη στην Python 3.13, οπότε εγκαταστήστε τοaudioop-ltsαπό το PyPI σε πρόσφατες εκδόσεις - Η ανίχνευση σιωπής στην πλευρά του πελάτη εξοικονομεί εύρος ζώνης στέλνοντας μόνο χρήσιμο ήχο
- Τα βοηθητικά εργαλεία WAV διευκολύνουν την αποσφαλμάτωση επιτρέποντάς σας να αποθηκεύετε και να αναπαράγετε ροές ήχου
Ελέγξτε την κατανόησή σας
WebSocket, VAD, ήχος: ο φωνητικός πράκτορας από άκρη σε άκρη.
1. Πώς ρυθμίζετε μια συνεδρία Voice Agent;
Απάντηση: Με μια σύνδεση WebSocket σε πραγματικό χρόνο, πιστοποιημένη με εφήμερα διακριτικά (ποτέ το κύριο κλειδί στον πελάτη), και στη συνέχεια διαμορφώνεται μέσω του session.update και επιβεβαιώνεται από τα session.created και session.updated.
2. Τι διαχειρίζεται το VAD;
Απάντηση: Αυτόματη ανίχνευση ομιλίας: εντοπίζει πότε ο χρήστης αρχίζει και σταματά να μιλά, ώστε ο πράκτορας να γνωρίζει πότε να ακούει και πότε να απαντά, χωρίς κανένα κουμπί.
3. Πώς ρέει ο ήχος;
Απάντηση: Η είσοδος εξέρχεται μέσω του input_audio_buffer.append (με επιβεβαίωση και εκκαθάριση buffer), και η απόκριση φτάνει ως γεγονότα ήχου για αναπαραγωγή, σε PCM ή G.711 ανάλογα με το κανάλι.
4. Τι καθιστούν δυνατά τα εργαλεία και το MCP σε μια φωνητική συνομιλία;
Απάντηση: Κλήση συναρτήσεων και ενσωματωμένα εργαλεία (web, X, collections) κατά τη διάρκεια της προφορικής ανταλλαγής: ο πράκτορας αναζητά πληροφορίες και αναλαμβάνει δράση ενώ μιλά, συμπεριλαμβανομένων των γεγονότων MCP.
5. Και για την τηλεφωνία;
Απάντηση: SIP και LiveKit με G.711: ο φωνητικός πράκτορας συνδέεται με το τηλεφωνικό δίκτυο και τα βοηθητικά εργαλεία μετατροπής ήχου Python γεφυρώνουν τις μορφές.
Μια ασφαλής συνεδρία, VAD, καλά διαχειριζόμενα buffers, εργαλεία στη φωνή: ο πλήρης τηλεφωνικός βοηθός είναι πλέον εφικτός και αυτό το μάθημα σας έχει προσφέρει κάθε απαραίτητο κομμάτι.