Утилити за аудио конвертиране в 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
Използване във потока на гласовия агент
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, трябва да извършите прем дискретизация:
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)
Пълно телефонно реле
Ето пример за реле между G.711 SIP поток и 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са двете основни функции за потока на гласовия агент.- Прем дискретизацията е необходима, когато честотата на дискретизация на микрофона Ви не съвпада с тази на API.
- Модулът
audioopобработва конвертирането на G.711 mu-law и A-law; той беше премахнат от стандартната библиотека в Python 3.13, затова инсталирайтеaudioop-ltsот PyPI при по-нови версии. - Откриването на тишина от страна на клиента спестява честотна лента, като изпраща само полезно аудио.
- WAV утилитите улесняват дебъгването, като Ви позволяват да запазвате и възпроизвеждате аудио потоци.
Проверете знанията си
WebSocket, VAD, аудио: гласовият агент от край до край.
1. Как се настройва сесия на гласов агент?
Отговор: Чрез връзка в реално време през WebSocket, удостоверявана с ефемерни токени (никога основния ключ на клиента), след което се конфигурира чрез session.update и се потвърждава от събитията session.created и session.updated.
2. Какво обработва VAD?
Отговор: Автоматично откриване на реч: то определя кога потребителят започва и спира да говори, така че агентът да знае кога да слуша и кога да отговори, без нужда от бутон.
3. Как протича аудио потокът?
Отговор: Входът се изпраща чрез input_audio_buffer.append (със commit и clear на буфера), а отговорът пристига като аудио събития за възпроизвеждане, във формат PCM или G.711 в зависимост от канала.
4. Какво правят възможни инструментите и MCP в гласов разговор?
Отговор: Извикване на функции и вградени инструменти (уеб, X, колекции) по време на spoken обмена: агентът търси информация и предприема действия, докато говори, включително събития от MCP.
5. А за телефонията?
Отговор: SIP и LiveKit с G.711: гласовият агент се включва в телефонната мрежа, а утилитите за аудио конвертиране на Python осъществяват моста между форматите.
Сигурна сесия, VAD, добре управлявани буфери, инструменти в гласа: пълният телефонен асистент е постижим, а този курс Ви даде всяка необходима част.