Implementar la transcripción en tiempo real en Python
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) se sustituyen 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), la diarización es posible 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 de texto libre (frases con espacios). Fuentes: Migrate from Voxtral 2 · Speech to Text.
El flujo asíncrono completo en Python
Ahora vas a escribir una canalización completa de transcripción en tiempo real, desde el primer byte de audio hasta el archivo de texto final. Todo depende de asyncio: el programa debe leer audio y recibir eventos del modelo simultáneamente, sin que ninguna de las dos operaciones bloquee a la otra. El código síncrono estándar simplemente esperaría aquí, y la latencia que has configurado con cuidado se desvanecería en el tiempo muerto de tu propio programa.
Arquitectura del programa de streaming
Independientemente de la aplicación, la estructura permanece igual y se lee de izquierda a derecha. Aguas arriba, una fuente de audio: un generador asíncrono que produce fragmentos de audio PCM. Hoy puede ser un archivo; mañana, un micrófono o un flujo de red. En el centro, el cliente de Voxtral, es decir, el SDK, que envía estos fragmentos al modelo y te devuelve eventos. Aguas abajo, el procesamiento de eventos: tu lógica de negocio, que muestra el texto, lo acumula, lo guarda o lo reenvía a otro servicio.
Fuente de audio → [fragmentos PCM] → SDK de Mistral → [eventos] → Tu código
Esta separación tiene una ventaja práctica: la fuente de audio es intercambiable. El código de transcripción que escribes a continuación funcionará idénticamente con el generador de micrófono de la siguiente lección, sin cambiar ni una sola línea.
Implementación básica
Dos detalles de este primer programa merecen tu atención. El generador source_audio_fichier divide el archivo en bloques de 32.000 bytes, lo que corresponde exactamente a un segundo de audio PCM mono de 16 bits a 16 kHz: 16.000 muestras multiplicadas por 2 bytes. El await asyncio.sleep que sigue a cada yield simula el tiempo real; comenta esta línea y ejecuta el programa con un extracto de varios minutos, y verás cómo el archivo se consume en una fracción de segundo, sin enseñarte nada sobre el comportamiento del streaming. En el lado de la recepción, texte_complet acumula los fragmentos para que tengas todo el texto disponible al final, además de la visualización en directo.
import asyncio
import os
from mistralai.client import Mistral
from mistralai.client.models import (
AudioFormat,
TranscriptionStreamTextDelta,
TranscriptionStreamDone
)
async def source_audio_fichier(chemin: str, taille_chunk: int = 32000):
"""Generador asíncrono que lee un archivo PCM en fragmentos.
taille_chunk = 32.000 bytes = 1 segundo de audio PCM mono de 16 bits a 16 kHz
(16.000 muestras × 2 bytes = 32.000 bytes)
"""
with open(chemin, "rb") as f:
while True:
chunk = f.read(taille_chunk)
if not chunk:
break
yield chunk
# Simular tiempo real (1 fragmento = 1 segundo)
await asyncio.sleep(len(chunk) / 32000)
async def transcrire_realtime(source_audio):
"""Transcribe un flujo de audio en tiempo real con Voxtral."""
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
audio_format = AudioFormat(
encoding="pcm_s16le",
sample_rate=16000
)
texte_complet = []
async for event in client.audio.realtime.transcribe_stream(
audio_stream=source_audio,
model="voxtral-mini-transcribe-realtime-3",
audio_format=audio_format,
):
if isinstance(event, TranscriptionStreamTextDelta):
print(event.text, end="", flush=True)
texte_complet.append(event.text)
elif isinstance(event, TranscriptionStreamDone):
print("\n\n--- Transcripción finalizada ---")
return "".join(texte_complet)
async def main():
source = source_audio_fichier("audio.pcm")
texte = await transcrire_realtime(source)
# Guardar el resultado
with open("transcription_realtime.txt", "w", encoding="utf-8") as f:
f.write(texte)
print(f"\nTexto guardado ({len(texte)} caracteres)")
asyncio.run(main())
La visualización en directo depende de print(event.text, end="", flush=True). Sin flush=True, Python almacena la salida en búfer y el texto aparecería por lotes: tu transcripción sería técnicamente en tiempo real, pero visualmente entrecortada.
Estructurar el procesamiento para producción
Una vez que tu aplicación va más allá de una demostración, el bucle if/elif se vuelve engorroso: querrás contar fragmentos, medir la duración, conectar una interfaz gráfica o alimentar una base de datos. Encapsular la lógica en una clase resuelve el problema de una vez por todas. Cada tipo de evento obtiene su propio método dedicado, y puedes añadir comportamiento —por ejemplo, enviar cada delta a una interfaz web— sin tocar el bucle de recepción.
class GestionnaireTranscription:
"""Gestiona los eventos de transcripción en tiempo real."""
def __init__(self):
self.texte_complet = []
self.nb_deltas = 0
self.debut = None
async def traiter(self, source_audio):
"""Inicia la transcripción y procesa los eventos."""
import time
self.debut = time.time()
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
audio_format = AudioFormat(encoding="pcm_s16le", sample_rate=16000)
async for event in client.audio.realtime.transcribe_stream(
audio_stream=source_audio,
model="voxtral-mini-transcribe-realtime-3",
audio_format=audio_format,
):
if isinstance(event, TranscriptionStreamTextDelta):
self._on_text_delta(event)
elif isinstance(event, TranscriptionStreamDone):
self._on_done(event)
return self.obtenir_resultat()
def _on_text_delta(self, event):
"""Se llama para cada nuevo fragmento de texto."""
self.texte_complet.append(event.text)
self.nb_deltas += 1
# Visualización en directo
print(event.text, end="", flush=True)
def _on_done(self, event):
"""Se llama al final de la transcripción."""
import time
duree = time.time() - self.debut
print(f"\n\nFinalizado en {duree:.1f} s")
print(f"Fragmentos recibidos: {self.nb_deltas}")
def obtenir_resultat(self) -> str:
"""Devuelve el texto transcrito completo."""
return "".join(self.texte_complet)
async def main():
gestionnaire = GestionnaireTranscription()
source = source_audio_fichier("audio.pcm")
texte = await gestionnaire.traiter(source)
print(f"Resultado: {len(texte)} caracteres")
asyncio.run(main())
El contador nb_deltas no es un adorno: en relación con la duración del audio, indica la tasa de emisión del modelo y te alerta si el flujo se degrada.
Sobrevivir a las interrupciones de red
Una conexión de streaming permanece abierta durante toda la duración del habla, lo que la expone mucho más que una solicitud sin conexión de unos pocos segundos. Una Wi-Fi inestable, un cambio de red en un dispositivo móvil o una caída del operador pueden interrumpir el flujo. El patrón siguiente reinicia la transcripción hasta tres veces, con un retraso que aumenta en cada intento para dar tiempo a que la red se recupere. Más allá de eso, la excepción se propaga: un fallo explícito es mejor que una aplicación que parece no escuchar nada.
import asyncio
from mistralai.client import Mistral
from mistralai.client.models import (
AudioFormat,
TranscriptionStreamTextDelta,
TranscriptionStreamDone
)
MAX_TENTATIVES = 3
DELAI_RECONNEXION = 2 # segundos
async def transcrire_avec_retry(source_audio, tentative=1):
"""Transcripción con reconexión automática."""
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
audio_format = AudioFormat(encoding="pcm_s16le", sample_rate=16000)
try:
async for event in client.audio.realtime.transcribe_stream(
audio_stream=source_audio,
model="voxtral-mini-transcribe-realtime-3",
audio_format=audio_format,
):
if isinstance(event, TranscriptionStreamTextDelta):
print(event.text, end="", flush=True)
elif isinstance(event, TranscriptionStreamDone):
print("\n[Finalizado]")
except ConnectionError as e:
if tentative < MAX_TENTATIVES:
print(f"\nError de red (intento {tentative}/{MAX_TENTATIVES})")
await asyncio.sleep(DELAI_RECONNEXION * tentative)
await transcrire_avec_retry(source_audio, tentative + 1)
else:
print(f"\nFallo tras {MAX_TENTATIVES} intentos: {e}")
raise
Preparar un archivo existente
Para probar con un archivo MP3 o WAV que ya tengas a mano, puedes automatizar la conversión a PCM desde Python en lugar de ejecutarla manualmente. La función siguiente delega el trabajo en FFmpeg, deduce el nombre de salida a partir del nombre de entrada y devuelve la ruta resultante, lista para pasarla a source_audio_fichier.
import subprocess
def convertir_en_pcm(chemin_entree: str, chemin_sortie: str = None) -> str:
"""Convierte un archivo de audio a PCM mono de 16 bits y 16 kHz mediante FFmpeg."""
if chemin_sortie is None:
chemin_sortie = chemin_entree.rsplit(".", 1)[0] + ".pcm"
subprocess.run([
"ffmpeg", "-y",
"-i", chemin_entree,
"-f", "s16le",
"-acodec", "pcm_s16le",
"-ar", "16000",
"-ac", "1",
chemin_sortie
], check=True, capture_output=True)
return chemin_sortie
# Uso
chemin_pcm = convertir_en_pcm("reunion.mp3")
# Luego usar source_audio_fichier(chemin_pcm)
Dos precauciones con esta función. check=True lanza una excepción si FFmpeg falla, lo cual es mejor que descubrir más tarde en el flujo un archivo PCM vacío; y capture_output=True oculta la salida de la herramienta, de modo que una conversión larga hará que el programa parezca congelado. Para grabaciones de una hora de duración, planifica imprimir un mensaje antes y después de la llamada.
Puntos clave
- El streaming utiliza generadores asíncronos (
async for,yield) - Un fragmento de 32.000 bytes = 1 segundo de audio PCM mono de 16 bits a 16 kHz
- Estructura el procesamiento de eventos en una clase para producción
- Implementa un mecanismo de reintento para gestionar errores de red
- Usa FFmpeg para convertir archivos de audio existentes a PCM
- La visualización en directo usa
print(texto, end="", flush=True)