Implementeer realtime transcriptie in Python
Op deze pagina
Cursus bijgewerkt op 3 november 2026 voor Voxtral 3, gebaseerd op de gids Migrate from Voxtral 2 van Mistral: Voxtral 2-modellen (
voxtral-mini-2602,voxtral-mini-transcribe-realtime-2602,voxtral-mini-tts-2603), verouderd op 31 oktober 2026 en buiten gebruik gesteld op 30 april 2027, worden in de voorbeelden vervangen doorvoxtral-mini-transcribe-3,voxtral-mini-transcribe-realtime-3envoxtral-mini-tts-3-0. Belangrijkste wijzigingen: tijdstempels zijn alleen per segment beschikbaar (wordgeeft een 400-fout), diarization is mogelijk in realtime, instellingen voor realtime-sessies worden vergrendeld na het eerste audioblok, encontext_bias-invoer is vrij vormgegeven (zinnen met spaties). Bronnen: Migrate from Voxtral 2 · Speech to Text.
De volledige Python async-stream
U gaat nu een volledige realtime transcriptiepijplijn schrijven, van de eerste audiobyte tot het uiteindelijke tekstbestand. Alles draait om asyncio: het programma moet audio lezen en modelgebeurtenissen tegelijkertijd ontvangen, zonder dat de ene bewerking de andere blokkeert. Standaard synchrone code zou hier simpelweg wachten, en de latentie die u zorgvuldig hebt geconfigureerd, zou verdwijnen in de dode tijd van uw eigen programma.
Architectuur van het streamingprogramma
Ongeacht de toepassing blijft de structuur hetzelfde en leest deze van links naar rechts. Stroomopwaarts bevindt zich een audiobron: een asynchrone generator die PCM-audioblokken produceert. Vandaag kan dit een bestand zijn, morgen een microfoon of een netwerkstream. In het midden staat de Voxtral-client, oftewel de SDK, die deze blokken naar het model pusht en gebeurtenissen aan u oplevert. Stroomafwaarts volgt de gebeurtenisverwerking: uw bedrijfslogica, die de tekst weergeeft, accumuleert, opslaat of doorstuurt naar een andere service.
Audio Source → [PCM chunks] → Mistral SDK → [events] → Your Code
Deze scheiding heeft een praktisch voordeel: de audiobron is uitwisselbaar. De onderstaande transcriptiecode werkt identiek met de microfoongenerator uit de volgende les, zonder ook maar één regel aan te passen.
Basisimplementatie
Twee details in dit eerste programma verdienen uw aandacht. De generator source_audio_fichier snijdt het bestand in blokken van 32.000 bytes, wat exact overeenkomt met één seconde 16-bit mono PCM-audio bij 16 kHz: 16.000 samples vermenigvuldigd met 2 bytes. De await asyncio.sleep na elke yield simuleert realtime; commentarieer deze regel uit en voer het programma uit op een fragment van enkele minuten, en u zult zien dat het bestand in een fractie van een seconde wordt verwerkt, wat u niets leert over streaminggedrag. Aan de ontvangstkant accumuleert texte_complet fragmenten, zodat u aan het einde over de volledige tekst beschikt, naast de live-weergave.
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):
"""Asynchrone generator die een PCM-bestand in blokken leest.
taille_chunk = 32000 bytes = 1 seconde 16-bit mono PCM-audio bij 16kHz
(16000 samples × 2 bytes = 32000 bytes)
"""
with open(chemin, "rb") as f:
while True:
chunk = f.read(taille_chunk)
if not chunk:
break
yield chunk
# Simuleer realtime (1 blok = 1 seconde)
await asyncio.sleep(len(chunk) / 32000)
async def transcrire_realtime(source_audio):
"""Transcribeert een audiostream in realtime met 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--- Transcriptie voltooid ---")
return "".join(texte_complet)
async def main():
source = source_audio_fichier("audio.pcm")
texte = await transcrire_realtime(source)
# Sla het resultaat op
with open("transcription_realtime.txt", "w", encoding="utf-8") as f:
f.write(texte)
print(f"\nTekst opgeslagen ({len(texte)} tekens)")
asyncio.run(main())
De live-weergave vertrouwt op print(event.text, end="", flush=True). Zonder flush=True bufferd Python de uitvoer en verschijnt tekst in batches: uw transcriptie zou technisch gezien realtime zijn, maar visueel schokkerig.
Verwerking structureren voor productie
Zodra uw applicatie verder gaat dan een demo, wordt de if/elif-lus onhandig: u wilt fragmenten tellen, duur meten, een display koppelen of een database voeden. Het kapselen van de logica in een klasse lost dit probleem eens en voor altijd op. Elk gebeurtenistype krijgt zijn eigen dedicated methode, en u kunt gedrag toevoegen – bijvoorbeeld elk delta naar een webinterface sturen – zonder de ontvangstlus aan te raken.
class GestionnaireTranscription:
"""Verwerkt realtime transcriptiegebeurtenissen."""
def __init__(self):
self.texte_complet = []
self.nb_deltas = 0
self.debut = None
async def traiter(self, source_audio):
"""Start transcriptie en verwerkt gebeurtenissen."""
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):
"""Wordt aangeroepen voor elk nieuw tekstfragment."""
self.texte_complet.append(event.text)
self.nb_deltas += 1
# Live-weergave
print(event.text, end="", flush=True)
def _on_done(self, event):
"""Wordt aangeroepen aan het einde van de transcriptie."""
import time
duree = time.time() - self.debut
print(f"\n\nVoltooid in {duree:.1f}s")
print(f"Ontvangen fragmenten: {self.nb_deltas}")
def obtenir_resultat(self) -> str:
"""Geeft de volledige getranscribeerde tekst terug."""
return "".join(self.texte_complet)
async def main():
gestionnaire = GestionnaireTranscription()
source = source_audio_fichier("audio.pcm")
texte = await gestionnaire.traiter(source)
print(f"Resultaat: {len(texte)} tekens")
asyncio.run(main())
De teller nb_deltas is geen gimmick: relatief tot de audioduur geeft deze de emissiesnelheid van het model aan en waarschuwt u als de stream degradeert.
Omgaan met netwerkonderbrekingen
Een streamingverbinding blijft open gedurende de hele duur van de spraak, waardoor deze veel meer blootstaat dan een offline aanvraag van enkele seconden. Een haperende wifi, een netwerkswitch op een mobiel apparaat of een storing bij de provider kunnen de stream onderbreken. Het onderstaande patroon start de transcriptie maximaal drie keer opnieuw, met een vertraging die bij elke poging toeneemt om het netwerk tijd te geven om te herstellen. Daarbovenop wordt de uitzondering doorgegeven: een expliciete mislukking is beter dan een applicatie die lijkt te luisteren naar niets.
import asyncio
from mistralai.client import Mistral
from mistralai.client.models import (
AudioFormat,
TranscriptionStreamTextDelta,
TranscriptionStreamDone
)
MAX_TENTATIVES = 3
DELAI_RECONNEXION = 2 # seconden
async def transcrire_avec_retry(source_audio, tentative=1):
"""Transcriptie met automatisch opnieuw verbinden."""
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[Voltooid]")
except ConnectionError as e:
if tentative < MAX_TENTATIVES:
print(f"\nNetwerkfout (poging {tentative}/{MAX_TENTATIVES})")
await asyncio.sleep(DELAI_RECONNEXION * tentative)
await transcrire_avec_retry(source_audio, tentative + 1)
else:
print(f"\nMislukt na {MAX_TENTATIVES} pogingen: {e}")
raise
Een bestaand bestand voorbereiden
Om te testen met een MP3- of WAV-bestand dat u al bij de hand hebt, kunt u de conversie naar PCM vanuit Python automatiseren in plaats van dit handmatig uit te voeren. De onderstaande functie delegeert het werk aan FFmpeg, leidt de uitvoernaam af van de invoernaam en geeft het resulterende pad terug, klaar om door te geven aan source_audio_fichier.
import subprocess
def convertir_en_pcm(chemin_entree: str, chemin_sortie: str = None) -> str:
"""Converteert een audiobestand naar 16-bit 16kHz mono PCM 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
# Gebruik
chemin_pcm = convertir_en_pcm("reunion.mp3")
# Gebruik vervolgens source_audio_fichier(chemin_pcm)
Twee voorzorgsmaatregelen bij deze functie. check=True veroorzaakt een uitzondering als FFmpeg faalt, wat beter is dan later in de stream een leeg PCM-bestand ontdekken; en capture_output=True verbergt de uitvoer van de tool, zodat een lange conversie het programma bevroren doet lijken. Voor opnames van een uur is het verstandig om voor en na de aanroep een bericht af te drukken.
Belangrijkste punten
- Streaming maakt gebruik van asynchrone generators (
async for,yield) - Een blok van 32.000 bytes = 1 seconde 16-bit mono PCM-audio bij 16 kHz
- Structureer gebeurtenisverwerking in een klasse voor productie
- Implementeer een retry-mechanisme om netwerkfouten af te handelen
- Gebruik FFmpeg om bestaande audiobestanden naar PCM te converteren
- Live-weergave gebruikt
print(tekst, end="", flush=True)