Utilidades de conversión de audio en Python
En esta página
Una biblioteca de utilidades de audio
Para construir una aplicación de Agente de Voz robusta, necesitas funciones auxiliares que conviertan el audio entre distintos formatos. Esta lección recopila las herramientas esenciales de Python para el procesamiento de audio en tiempo real.
De PCM16 a base64 y viceversa
Estas son las dos funciones que usarás con más frecuencia: codificar el audio capturado en base64 para enviarlo y decodificar el audio en base64 recibido para reproducirlo.
import base64
import numpy as np
def audio_to_base64(audio_data: np.ndarray) -> str:
"""Convierte un array numpy float32 en [-1, 1] a PCM16 en base64."""
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:
"""Convierte una cadena base64 PCM16 a un array numpy float32."""
audio_bytes = base64.b64decode(base64_audio)
audio_int16 = np.frombuffer(audio_bytes, dtype=np.int16)
return audio_int16.astype(np.float32) / 32768.0
Uso en el flujo del Agente de Voz
import pyaudio
import json
# Captura del micrófono → envío
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
}))
# Recepción → reproducción
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())
Remuestreo (Resampling)
Si tu micrófono captura a una frecuencia de muestreo diferente a la que espera la API, necesitas remuestrear:
from scipy.signal import resample
def resample_audio(
audio: np.ndarray,
original_rate: int,
target_rate: int
) -> np.ndarray:
"""Remuestrea el audio de una frecuencia de muestreo a otra."""
if original_rate == target_rate:
return audio
num_samples = int(len(audio) * target_rate / original_rate)
return resample(audio, num_samples)
# Ejemplo: micrófono a 44100 Hz → API a 24000 Hz
audio_44100 = capture_microphone()
audio_24000 = resample_audio(audio_44100, 44100, 24000)
b64 = audio_to_base64(audio_24000)
Conversión entre G.711 y PCM
Para integraciones telefónicas, necesitarás convertir entre G.711 y PCM lineal. Presta atención a tu versión de Python: audioop se eliminó de la biblioteca estándar en la versión 3.13. En versiones recientes de Python, instala el paquete audioop-lts, que proporciona la misma interfaz:
import audioop
def pcm_to_mulaw(pcm_data: bytes) -> bytes:
"""Convierte PCM16 a G.711 mu-law."""
return audioop.lin2ulaw(pcm_data, 2)
def mulaw_to_pcm(mulaw_data: bytes) -> bytes:
"""Convierte G.711 mu-law a PCM16."""
return audioop.ulaw2lin(mulaw_data, 2)
def pcm_to_alaw(pcm_data: bytes) -> bytes:
"""Convierte PCM16 a G.711 A-law."""
return audioop.lin2alaw(pcm_data, 2)
def alaw_to_pcm(alaw_data: bytes) -> bytes:
"""Convierte G.711 A-law a PCM16."""
return audioop.alaw2lin(alaw_data, 2)
Un retransmisor telefónico completo
Aquí tienes un ejemplo de un retransmisor entre un flujo SIP G.711 y la API del Agente de Voz:
async def relay_sip_to_voice_agent(sip_stream, ws):
"""Retransmite el audio de una llamada SIP a la API del Agente de Voz."""
async for mulaw_chunk in sip_stream:
# Convertir 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):
"""Retransmite la respuesta de audio de la API al flujo SIP."""
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)
Detección de silencio en el cliente
Si gestionas tú mismo el pulsar-para-hablar (push-to-talk) o quieres detectar el silencio localmente antes de enviar, esta función mide la energía de la señal:
def is_silence(
audio: np.ndarray,
threshold: float = 0.01
) -> bool:
"""Detecta si un fragmento de audio es silencio."""
rms = np.sqrt(np.mean(audio ** 2))
return rms < threshold
# Uso
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
}))
Guardar y cargar archivos WAV
Para depuración y pruebas, puedes guardar y cargar archivos WAV:
import wave
def save_wav(
filename: str,
audio: np.ndarray,
sample_rate: int = 24000
):
"""Guarda un array numpy como un archivo WAV."""
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]:
"""Carga un archivo WAV como un array numpy float32."""
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
Puntos clave
audio_to_base64ybase64_to_audioson las dos funciones esenciales para el flujo del Agente de Voz.- El remuestreo es necesario cuando la frecuencia de muestreo de tu micrófono no coincide con la de la API.
- El módulo
audioopgestiona las conversiones G.711 mu-law y A-law; se eliminó de la biblioteca estándar en Python 3.13, así que instalaaudioop-ltsdesde PyPI en versiones recientes. - La detección de silencio en el cliente ahorra ancho de banda al enviar solo el audio útil.
- Las utilidades WAV facilitan la depuración al permitirte guardar y reproducir flujos de audio.
Comprueba tu comprensión
WebSocket, VAD, audio: el agente de voz de extremo a extremo.
1. ¿Cómo se configura una sesión de Agente de Voz?
Respuesta: Mediante una conexión WebSocket en tiempo real, autenticada con tokens efímeros (nunca la clave principal en el cliente), y configurada a través de session.update, confirmada por session.created y session.updated.
2. ¿Qué gestiona el VAD?
Respuesta: La detección automática de voz: determina cuándo el usuario empieza y deja de hablar, para que el agente sepa cuándo escuchar y cuándo responder, sin necesidad de botones.
3. ¿Cómo fluye el audio?
Respuesta: La entrada sale a través de input_audio_buffer.append (con confirmación y limpieza del búfer), y la respuesta llega como eventos de audio para reproducir, en PCM o G.711 dependiendo del canal.
4. ¿Qué permiten las herramientas y MCP en una conversación de voz?
Respuesta: Llamadas a funciones y herramientas integradas (web, X, colecciones) durante el intercambio hablado: el agente busca información y actúa mientras habla, incluyendo eventos MCP.
5. ¿Y para la telefonía?
Respuesta: SIP y LiveKit con G.711: el agente de voz se conecta a la red telefónica, y las utilidades de conversión de audio de Python hacen de puente entre los formatos.
Una sesión segura, VAD, búferes bien gestionados, herramientas en voz: el asistente telefónico completo está a tu alcance, y este curso te ha proporcionado todas las piezas.