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

Captura del micrófono con PyAudio

Lección 11 de 16 Actualizado el 3 de noviembre de 2026 Desarrollador
En esta página
  1. Del archivo al micrófono
  2. Instalación de PyAudio
  3. El generador del micrófono
  4. Programa completo: del micrófono a la transcripción
  5. Elección del dispositivo adecuado
  6. Puntos clave

Curso actualizado el 3 de noviembre de 2026 para Voxtral 3, basado en la guía Migrate from Voxtral 2 de Mistral: los modelos de Voxtral 2 (voxtral-mini-2602, voxtral-mini-transcribe-realtime-2602, voxtral-mini-tts-2603), obsoletos desde el 31 de octubre de 2026 y retirados el 30 de abril de 2027, han sido sustituidos en los ejemplos por voxtral-mini-transcribe-3, voxtral-mini-transcribe-realtime-3 y voxtral-mini-tts-3-0. Cambios clave: las marcas temporales son solo por segmento (word devuelve un error 400), se admite la diarización en tiempo real, la configuración de la sesión en tiempo real se bloquea tras el primer fragmento de audio y las entradas de context_bias son flexibles (frases con espacios). Fuentes: Migrate from Voxtral 2 · Speech to Text.

Del archivo al micrófono

La lección anterior estableció una arquitectura donde la fuente de audio es un generador asíncrono simple e intercambiable. Aprovecharás esto de inmediato: al sustituir el generador que lee archivos por uno que lee desde tu tarjeta de sonido, tu programa comenzará a transcribir tu voz en directo sin cambiar ni una sola línea del resto del código.

La herramienta para esta lección es PyAudio, la biblioteca estándar de Python para acceder a dispositivos de audio. Depende de PortAudio, una capa nativa que es posible que debas instalar por separado según tu sistema.

Instalación de PyAudio

# Linux (Debian/Ubuntu)
sudo apt-get install portaudio19-dev
pip install pyaudio

# macOS
brew install portaudio
pip install pyaudio

# Windows
pip install pyaudio

El generador del micrófono

El núcleo de esta lección cabe en unas treinta líneas. La función abre un flujo de entrada en el dispositivo predeterminado, entra en un bucle infinito leyendo bloques de tamaño fijo y cede cada uno al motor de transcripción. El bloque finally no es decorativo: garantiza que el flujo se detenga, se cierre y que PyAudio libere el hardware, incluso si el programa se interrumpe bruscamente. Sin él, el micrófono podría quedar bloqueado, impidiendo su uso en otras aplicaciones.

import asyncio
import pyaudio

async def iter_microphone(
    sample_rate: int = 16000,
    chunk_duration_ms: int = 480
):
    """Captura el micrófono y cede fragmentos PCM.

    Args:
        sample_rate: Frecuencia de muestreo (16000 Hz para Voxtral)
        chunk_duration_ms: Duración de cada fragmento en milisegundos

    Yields:
        bytes: Fragmentos de audio PCM mono de 16 bits
    """
    p = pyaudio.PyAudio()

    # Número de muestras por fragmento
    chunk_samples = int(sample_rate * chunk_duration_ms / 1000)

    # Abrir el flujo del micrófono
    stream = p.open(
        format=pyaudio.paInt16,    # PCM de 16 bits
        channels=1,                 # Mono
        rate=sample_rate,           # 16 kHz
        input=True,                 # Modo de captura
        frames_per_buffer=chunk_samples
    )

    loop = asyncio.get_running_loop()

    try:
        print("Micrófono activo — habla...")
        while True:
            # Leer el fragmento sin bloqueo
            data = await loop.run_in_executor(
                None,
                stream.read,
                chunk_samples,
                False  # exception_on_overflow
            )
            yield data
    finally:
        stream.stop_stream()
        stream.close()
        p.terminate()
        print("Micrófono cerrado")

Cada parámetro tiene una razón específica. sample_rate=16000 refleja un requisito del modelo, no una preferencia: Voxtral espera 16 kHz, así que no cambies este valor. pyaudio.paInt16 coincide con el formato PCM con signo de 16 bits, exactamente equivalente al pcm_s16le declarado en la API, y channels=1 fuerza el modo mono, que también es obligatorio. Solo queda chunk_duration_ms=480, el único ajuste realmente debatible: cada fragmento representa 480 milisegundos de audio, un buen compromiso entre capacidad de respuesta y eficiencia de red. Un fragmento más corto, digamos 100 ms, mejora la capacidad de respuesta pero multiplica las solicitudes de red; un fragmento más largo ahorra ancho de banda a costa de añadir latencia antes de que el modelo reciba el audio.

La llamada loop.run_in_executor también merece una explicación. stream.read es una función bloqueante: retiene el hilo hasta que está disponible el número solicitado de muestras. Ejecutarla directamente en una corrutina congelaría todo el bucle asyncio, incluida la recepción de eventos de transcripción. Al delegarla en un ejecutor, haces que la lectura sea compatible con el resto del programa asíncrono.

El cálculo del tamaño del bloque se deriva mecánicamente de los dos ajustes, para sample_rate=16000 y chunk_duration_ms=480:

chunk_samples = 16000 × 480 / 1000 = 7680 muestras
byte_size = 7680 × 2 bytes = 15360 bytes por fragmento

Programa completo: del micrófono a la transcripción

El siguiente script combina la captura y la transcripción en una herramienta de dictado lista para usar. El nuevo elemento respecto al generador anterior es la gestión limpia del cierre: un manejador de señales intercepta Ctrl+C, cambia la bandera running a False, lo que sale del bucle de captura, cierra el flujo y permite que el programa guarde el texto acumulado. Sin este mecanismo, una interrupción de teclado mataría el proceso antes de guardar y perderías el dictado.

import asyncio
import os
import signal
from mistralai.client import Mistral
from mistralai.client.models import (
    AudioFormat,
    TranscriptionStreamTextDelta,
    TranscriptionStreamDone
)
import pyaudio

# Bandera para un cierre limpio
running = True

def signal_handler(sig, frame):
    global running
    print("\n\nApagando...")
    running = False

signal.signal(signal.SIGINT, signal_handler)

async def iter_microphone(sample_rate=16000, chunk_duration_ms=480):
    """Captura el micrófono hasta que se interrumpa (Ctrl+C)."""
    p = pyaudio.PyAudio()
    chunk_samples = int(sample_rate * chunk_duration_ms / 1000)

    stream = p.open(
        format=pyaudio.paInt16,
        channels=1,
        rate=sample_rate,
        input=True,
        frames_per_buffer=chunk_samples
    )

    loop = asyncio.get_running_loop()

    try:
        while running:
            data = await loop.run_in_executor(
                None, stream.read, chunk_samples, False
            )
            yield data
    finally:
        stream.stop_stream()
        stream.close()
        p.terminate()

async def main():
    client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
    audio_format = AudioFormat(encoding="pcm_s16le", sample_rate=16000)

    print("=" * 50)
    print("TRANSCRIPCIÓN EN DIRECTO")
    print("Habla al micrófono (Ctrl+C para detener)")
    print("=" * 50)
    print()

    full_text = []

    async for event in client.audio.realtime.transcribe_stream(
        audio_stream=iter_microphone(),
        model="voxtral-mini-transcribe-realtime-3",
        audio_format=audio_format,
    ):
        if isinstance(event, TranscriptionStreamTextDelta):
            print(event.text, end="", flush=True)
            full_text.append(event.text)

        elif isinstance(event, TranscriptionStreamDone):
            break

    # Guardar
    final_text = "".join(full_text)
    if final_text.strip():
        with open("dictee.txt", "w", encoding="utf-8") as f:
            f.write(final_text)
        print(f"\n\nTranscripción guardada en dictee.txt")
        print(f"Longitud: {len(final_text)} caracteres")
    else:
        print("\n\nNo se ha transcrito ningún texto.")

asyncio.run(main())

Ejecútalo, habla, detén con Ctrl+C: el texto aparece mientras hablas y luego termina en dictee.txt.

python dictee_vocale.py
# Habla a tu micrófono
# El texto aparece en tiempo real
# Ctrl+C para detener

Pruébalo con unos treinta segundos de francés continuo, variando el ritmo, y compara lo que dijiste con lo que contiene el archivo. Es la mejor manera de calibrar tus expectativas antes de ajustar la latencia en la siguiente lección.

Elección del dispositivo adecuado

En un equipo con micrófono integrado, auriculares USB y webcam, el dispositivo predeterminado no siempre es el que crees, y una transcripción vacía suele deberse a este detalle. Primero, lista las entradas disponibles con su índice:

def list_microphones():
    """Lista todos los dispositivos de entrada de audio disponibles."""
    p = pyaudio.PyAudio()
    print("Dispositivos de entrada disponibles:")
    for i in range(p.get_device_count()):
        info = p.get_device_info_by_index(i)
        if info["maxInputChannels"] > 0:
            print(f"  [{i}] {info['name']} "
                  f"(canales: {info['maxInputChannels']}, "
                  f"frecuencia: {int(info['defaultSampleRate'])} Hz)")
    p.terminate()

list_microphones()

Luego, simplemente fuerza el índice elegido al abrir el flujo, mediante el parámetro input_device_index:

stream = p.open(
    format=pyaudio.paInt16,
    channels=1,
    rate=sample_rate,
    input=True,
    input_device_index=2,  # Índice del dispositivo
    frames_per_buffer=chunk_samples
)

Puntos clave

  • PyAudio captura el micrófono en PCM mono de 16 bits a 16 kHz, exactamente lo que espera Voxtral
  • El generador iter_microphone cede fragmentos de 480 ms por defecto
  • loop.run_in_executor hace que la lectura del micrófono no sea bloqueante en asyncio
  • Ctrl+C detiene la captura limpiamente mediante un manejador de señales
  • Lista los dispositivos con get_device_count() para elegir el micrófono correcto