Implémenter la transcription en temps réel en Python
Šajā lapā
Cours mis à jour le 3 novembre 2026 pour Voxtral 3, basé sur le guide Migrate from Voxtral 2 de Mistral : les modèles Voxtral 2 (
voxtral-mini-2602,voxtral-mini-transcribe-realtime-2602,voxtral-mini-tts-2603), dépréciés le 31 octobre 2026 et retirés le 30 avril 2027, sont remplacés dans les exemples parvoxtral-mini-transcribe-3,voxtral-mini-transcribe-realtime-3etvoxtral-mini-tts-3-0. Changements clés : les horodatages sont uniquement par segment (wordrenvoie une erreur 400), la diarisation est possible en temps réel, les paramètres de session en temps réel sont verrouillés après le premier bloc audio, et les entréescontext_biassont en texte libre (phrases avec espaces). Sources : Migrate from Voxtral 2 · Speech to Text.
Le flux asynchrone Python complet
Tu vas maintenant écrire un pipeline complet de transcription en temps réel, du premier octet audio jusqu’au fichier texte final. Tout repose sur asyncio : le programme doit lire l’audio et recevoir les événements du modèle simultanément, sans qu’aucune opération ne bloque l’autre. Un code synchrone classique se contenterait d’attendre ici, et la latence que tu as soigneusement configurée disparaîtrait dans les temps morts de ton propre programme.
Architecture du programme de streaming
Quelle que soit l’application, la structure reste identique et se lit de gauche à droite. En amont, une source audio : un générateur asynchrone qui produit des blocs audio PCM. Aujourd’hui, il peut s’agir d’un fichier, demain d’un microphone ou d’un flux réseau. Au centre, le client Voxtral, c’est-à-dire le SDK, qui pousse ces blocs vers le modèle et te renvoie des événements. En aval, le traitement des événements : ta logique métier, qui affiche le texte, l’accumule, le sauvegarde ou le transmet à un autre service.
Source Audio → [blocs PCM] → SDK Mistral → [événements] → Ton Code
Cette séparation offre un avantage pratique : la source audio est interchangeable. Le code de transcription que tu écris ci-dessous fonctionnera à l’identique avec le générateur de microphone de la prochaine leçon, sans changer une seule ligne.
Implémentation de base
Deux détails dans ce premier programme méritent ton attention. Le générateur source_audio_fichier découpe le fichier en blocs de 32 000 octets, ce qui correspond exactement à une seconde d’audio PCM mono 16 bits à 16 kHz : 16 000 échantillons multipliés par 2 octets. Le await asyncio.sleep suivant chaque yield simule le temps réel ; commente cette ligne et lance le programme sur un extrait de quelques minutes, et tu verras le fichier consommé en une fraction de seconde, ce qui ne t’apprendra rien sur le comportement du streaming. Côté réception, texte_complet accumule les fragments pour que tu aies le texte intégral disponible à la fin, en plus de l’affichage en direct.
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):
"""Générateur asynchrone qui lit un fichier PCM par blocs.
taille_chunk = 32000 octets = 1 seconde d'audio PCM mono 16 bits à 16kHz
(16000 échantillons × 2 octets = 32000 octets)
"""
with open(chemin, "rb") as f:
while True:
chunk = f.read(taille_chunk)
if not chunk:
break
yield chunk
# Simuler le temps réel (1 bloc = 1 seconde)
await asyncio.sleep(len(chunk) / 32000)
async def transcrire_realtime(source_audio):
"""Transcrit un flux audio en temps réel avec 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--- Transcription terminée ---")
return "".join(texte_complet)
async def main():
source = source_audio_fichier("audio.pcm")
texte = await transcrire_realtime(source)
# Sauvegarder le résultat
with open("transcription_realtime.txt", "w", encoding="utf-8") as f:
f.write(texte)
print(f"\nTexte sauvegardé ({len(texte)} caractères)")
asyncio.run(main())
L’affichage en direct repose sur print(event.text, end="", flush=True). Sans flush=True, Python met en tampon la sortie et le texte apparaîtrait par lots : ta transcription serait techniquement en temps réel, mais visuellement saccadée.
Structurer le traitement pour la production
Une fois ton application sortie du stade de démo, la boucle if/elif devient encombrante : tu veux compter les fragments, mesurer la durée, brancher un affichage ou alimenter une base de données. Encapsuler la logique dans une classe résout le problème une fois pour toutes. Chaque type d’événement obtient sa propre méthode dédiée, et tu peux ajouter des comportements — par exemple, envoyer chaque delta à une interface web — sans toucher à la boucle de réception.
class GestionnaireTranscription:
"""Gère les événements de transcription en temps réel."""
def __init__(self):
self.texte_complet = []
self.nb_deltas = 0
self.debut = None
async def traiter(self, source_audio):
"""Démarre la transcription et traite les événements."""
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):
"""Appelé pour chaque nouveau fragment de texte."""
self.texte_complet.append(event.text)
self.nb_deltas += 1
# Affichage en direct
print(event.text, end="", flush=True)
def _on_done(self, event):
"""Appelé à la fin de la transcription."""
import time
duree = time.time() - self.debut
print(f"\n\nTerminé en {duree:.1f}s")
print(f"Fragments reçus : {self.nb_deltas}")
def obtenir_resultat(self) -> str:
"""Retourne le texte transcrit complet."""
return "".join(self.texte_complet)
async def main():
gestionnaire = GestionnaireTranscription()
source = source_audio_fichier("audio.pcm")
texte = await gestionnaire.traiter(source)
print(f"Résultat : {len(texte)} caractères")
asyncio.run(main())
Le compteur nb_deltas n’est pas un gadget : par rapport à la durée audio, il indique le taux d’émission du modèle et t’alerte si le flux se dégrade.
Survivre aux interruptions réseau
Une connexion de streaming reste ouverte pendant toute la durée de la parole, l’exposant bien plus qu’une requête hors ligne de quelques secondes. Un Wi-Fi capricieux, un changement de réseau sur un appareil mobile ou une panne opérateur peuvent interrompre le flux. Le motif ci-dessous redémarre la transcription jusqu’à trois fois, avec un délai qui augmente à chaque tentative pour laisser le temps au réseau de se rétablir. Au-delà, l’exception est propagée : un échec explicite vaut mieux qu’une application qui semble ne rien écouter.
import asyncio
from mistralai.client import Mistral
from mistralai.client.models import (
AudioFormat,
TranscriptionStreamTextDelta,
TranscriptionStreamDone
)
MAX_TENTATIVES = 3
DELAI_RECONNEXION = 2 # secondes
async def transcrire_avec_retry(source_audio, tentative=1):
"""Transcription avec reconnexion automatique."""
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[Terminé]")
except ConnectionError as e:
if tentative < MAX_TENTATIVES:
print(f"\nErreur réseau (tentative {tentative}/{MAX_TENTATIVES})")
await asyncio.sleep(DELAI_RECONNEXION * tentative)
await transcrire_avec_retry(source_audio, tentative + 1)
else:
print(f"\nÉchec après {MAX_TENTATIVES} tentatives : {e}")
raise
Préparer un fichier existant
Pour tester avec un fichier MP3 ou WAV que tu as déjà sous la main, tu peux automatiser la conversion en PCM depuis Python plutôt que de l’exécuter manuellement. La fonction ci-dessous délègue le travail à FFmpeg, déduit le nom de sortie du nom d’entrée et renvoie le chemin résultant, prêt à être passé à source_audio_fichier.
import subprocess
def convertir_en_pcm(chemin_entree: str, chemin_sortie: str = None) -> str:
"""Convertit un fichier audio en PCM mono 16 bits 16kHz via 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
# Utilisation
chemin_pcm = convertir_en_pcm("reunion.mp3")
# Puis utiliser source_audio_fichier(chemin_pcm)
Deux précautions avec cette fonction. check=True lève une exception si FFmpeg échoue, ce qui vaut mieux que de découvrir plus tard dans le flux un fichier PCM vide ; et capture_output=True masque la sortie de l’outil, sinon une longue conversion donnerait l’impression que le programme est figé. Pour des enregistrements d’une heure, prévois d’afficher un message avant et après l’appel.
Galvenās atziņas
- Le streaming utilise des générateurs asynchrones (
async for,yield) - Un bloc de 32 000 octets = 1 seconde d’audio PCM mono 16 bits à 16 kHz
- Structure le traitement des événements dans une classe pour la production
- Implémente un mécanisme de nouvelle tentative pour gérer les erreurs réseau
- Utilise FFmpeg pour convertir les fichiers audio existants en PCM
- L’affichage en direct utilise
print(texte, end="", flush=True)