Ir al contenido principal
Español— Elegir un idioma
Menú

Utilidades de conversión de audio en Python

Lección 16 de 16 Actualizado el 30 de julio de 2026 Desarrollador
En esta página
  1. Una biblioteca de utilidades de audio
  2. De PCM16 a base64 y viceversa
  3. Remuestreo (Resampling)
  4. Conversión entre G.711 y PCM
  5. Detección de silencio en el cliente
  6. Guardar y cargar archivos WAV
  7. Puntos clave
  8. Comprueba tu comprensión

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_base64 y base64_to_audio son 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 audioop gestiona las conversiones G.711 mu-law y A-law; se eliminó de la biblioteca estándar en Python 3.13, así que instala audioop-lts desde 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.