Captura del micrófono con PyAudio
En esta página
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 porvoxtral-mini-transcribe-3,voxtral-mini-transcribe-realtime-3yvoxtral-mini-tts-3-0. Cambios clave: las marcas temporales son solo por segmento (worddevuelve 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 decontext_biasson 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_microphonecede fragmentos de 480 ms por defecto loop.run_in_executorhace 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