Implementacija transkripcije u stvarnom vremenu u Pythonu
Na ovoj stranici
Tečaj ažuriran 3. studenoga 2026. za Voxtral 3, na temelju Mistralovog vodiča Migrate from Voxtral 2: modeli Voxtral 2 (
voxtral-mini-2602,voxtral-mini-transcribe-realtime-2602,voxtral-mini-tts-2603), zastarjeli 31. listopada 2026. i povučeni 30. travnja 2027., zamijenjeni su u primjerima svoxtral-mini-transcribe-3,voxtral-mini-transcribe-realtime-3ivoxtral-mini-tts-3-0. Ključne promjene: vremenske oznake su samo po segmentima (wordvraća grešku 400), diarizacija je moguća u stvarnom vremenu, postavke sesije u stvarnom vremenu zaključane su nakon prvog audio isječka, a unosicontext_biassu slobodnog oblika (fraze s razmacima). Izvori: Migrate from Voxtral 2 · Speech to Text.
Potpuni asinkroni stream u Pythonu
Sada ćeš napisati kompletan pipeline za transkripciju u stvarnom vremenu, od prvog audio bajta do konačne tekstualne datoteke. Sve se oslanja na asyncio: program mora istovremeno čitati audio i primati događaje modela, bez da jedna operacija blokira drugu. Standardni sinkroni kod bi ovdje jednostavno čekao, a latencija koju si pažljivo konfigurirao nestala bi u mrtvom vremenu tvog vlastitog programa.
Arhitektura streaming programa
Bez obzira na aplikaciju, struktura ostaje ista i čita se slijeva nadesno. Uzvodno se nalazi izvor zvuka: asinkroni generator koji proizvodi PCM audio isječke. Danas to može biti datoteka, sutra mikrofon ili mrežni stream. U sredini je Voxtral klijent, odnosno SDK, koji gura te isječke modelu i vraća događaje tebi. Nizvodno slijedi obrada događaja: tvoja poslovna logika koja prikazuje tekst, akumulira ga, sprema ili prosljeđuje drugoj usluzi.
Audio Source → [PCM chunks] → Mistral SDK → [events] → Your Code
Ova separacija ima praktičnu prednost: izvor zvuka je zamjenjiv. Kod za transkripciju koji napišeš u nastavku radit će identično s generatorom mikrofona iz sljedeće lekcije, bez mijenjanja ijednog retka.
Osnovna implementacija
Dva detalja u ovom prvom programu zaslužuju tvoju pozornost. Generator source_audio_fichier reže datoteku na blokove od 32.000 bajtova, što točno odgovara jednoj sekundi 16-bitnog mono PCM zvuka pri 16 kHz: 16.000 uzoraka pomnoženo s 2 bajta. Naredba await asyncio.sleep koja slijedi nakon svakog yield simulira stvarno vrijeme; komentiraj ovaj redak i pokreni program na isječku od nekoliko minuta te ćeš vidjeti kako se datoteka troši u djeliću sekunde, što te neće naučiti ništa o ponašanju streamanja. Na strani prijema, texte_complet akumulira fragmente tako da imaš cijeli tekst dostupan na kraju, uz prikaz uživo.
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):
"""Asinkroni generator koji čita PCM datoteku u isječcima.
taille_chunk = 32000 bajtova = 1 sekunda 16-bitnog mono PCM zvuka pri 16kHz
(16000 uzoraka × 2 bajta = 32000 bajtova)
"""
with open(chemin, "rb") as f:
while True:
chunk = f.read(taille_chunk)
if not chunk:
break
yield chunk
# Simulacija stvarnog vremena (1 isječak = 1 sekunda)
await asyncio.sleep(len(chunk) / 32000)
async def transcrire_realtime(source_audio):
"""Transkribira audio stream u stvarnom vremenu s Voxtralom."""
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--- Transkripcija završena ---")
return "".join(texte_complet)
async def main():
source = source_audio_fichier("audio.pcm")
texte = await transcrire_realtime(source)
# Spremi rezultat
with open("transcription_realtime.txt", "w", encoding="utf-8") as f:
f.write(texte)
print(f"\nTekst spremljen ({len(texte)} znakova)")
asyncio.run(main())
Prikaz uživo oslanja se na print(event.text, end="", flush=True). Bez flush=True, Python međusprema izlaz i tekst bi se pojavljivao u serijama: tvoja bi transkripcija tehnički bila u stvarnom vremenu, ali vizualno isprekidana.
Strukturiranje obrade za produkciju
Kada tvoja aplikacija prijeđe razinu demo verzije, petlja if/elif postaje nezgrapna: želiš brojati fragmente, mjeriti trajanje, spojiti zaslon ili napajati bazu podataka. Inkapsulacija logike u klasu rješava problem jednom zauvijek. Svaka vrsta događaja dobiva svoju vlastitu metodu, a možeš dodati ponašanje – na primjer, slanje svakog delta zapisa na web sučelje – bez diranja petlje za prihvat.
class GestionnaireTranscription:
"""Upravlja događajima transkripcije u stvarnom vremenu."""
def __init__(self):
self.texte_complet = []
self.nb_deltas = 0
self.debut = None
async def traiter(self, source_audio):
"""Pokreće transkripciju i obrađuje događaje."""
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):
"""Poziva se za svaki novi tekstualni fragment."""
self.texte_complet.append(event.text)
self.nb_deltas += 1
# Prikaz uživo
print(event.text, end="", flush=True)
def _on_done(self, event):
"""Poziva se na kraju transkripcije."""
import time
duree = time.time() - self.debut
print(f"\n\nZavršeno za {duree:.1f}s")
print(f"Primljeni fragmenti: {self.nb_deltas}")
def obtenir_resultat(self) -> str:
"""Vraća cijeli transkribirani tekst."""
return "".join(self.texte_complet)
async def main():
gestionnaire = GestionnaireTranscription()
source = source_audio_fichier("audio.pcm")
texte = await gestionnaire.traiter(source)
print(f"Rezultat: {len(texte)} znakova")
asyncio.run(main())
Brojač nb_deltas nije trik: u odnosu na trajanje zvuka, indicira brzinu emitiranja modela i upozorava te ako se stream degradira.
Preživljavanje prekida mreže
Streaming veza ostaje otvorena tijekom cijelog trajanja govora, što je izlaže mnogo većem riziku nego nekoliko sekundi trajanja offline zahtjeva. Nestabilan Wi-Fi, promjena mreže na mobilnom uređaju ili ispad operatera mogu prekinuti stream. Donji obrazac ponovno pokreće transkripciju do tri puta, s kašnjenjem koje se povećava sa svakim pokušajem kako bi se mreži dalo vremena za oporavak. Nakon toga, iznimka se prosljeđuje dalje: eksplicitni neuspjeh bolji je od aplikacije koja se čini kao da ništa ne sluša.
import asyncio
from mistralai.client import Mistral
from mistralai.client.models import (
AudioFormat,
TranscriptionStreamTextDelta,
TranscriptionStreamDone
)
MAX_TENTATIVES = 3
DELAI_RECONNEXION = 2 # sekunde
async def transcrire_avec_retry(source_audio, tentative=1):
"""Transkripcija s automatskim ponovnim spajanjem."""
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[Završeno]")
except ConnectionError as e:
if tentative < MAX_TENTATIVES:
print(f"\nMrežna pogreška (pokušaj {tentative}/{MAX_TENTATIVES})")
await asyncio.sleep(DELAI_RECONNEXION * tentative)
await transcrire_avec_retry(source_audio, tentative + 1)
else:
print(f"\nNeuspjeh nakon {MAX_TENTATIVES} pokušaja: {e}")
raise
Priprema postojeće datoteke
Za testiranje s MP3 ili WAV datotekom koju već imaš pri ruci, možeš automatizirati konverziju u PCM iz Pythona umjesto da to radiš ručno. Donja funkcija delegira posao FFmpegu, izvodi ime izlazne datoteke iz ulaznog imena i vraća rezultirajuću putanju, spremnu za proslijeđivanje funkciji source_audio_fichier.
import subprocess
def convertir_en_pcm(chemin_entree: str, chemin_sortie: str = None) -> str:
"""Konvertira audio datoteku u 16-bitni 16kHz mono PCM putem FFmprega."""
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
# Upotreba
chemin_pcm = convertir_en_pcm("reunion.mp3")
# Zatim koristi source_audio_fichier(chemin_pcm)
Dva opreza s ovom funkcijom. check=True podiže iznimku ako FFmpeg ne uspije, što je bolje nego kasnije u streamu otkriti praznu PCM datoteku; a capture_output=True skriva izlaz alata, pa će duga konverzija učiniti da program izgleda kao da je zamrznuo. Za snimke od sat vremena, planiraj ispisati poruku prije i nakon poziva.
Ključne točke
- Streamanje koristi asinkrone generatore (
async for,yield) - Isječak od 32.000 bajtova = 1 sekunda 16-bitnog mono PCM zvuka pri 16 kHz
- Strukturiraj obradu događaja u klasu za produkciju
- Implementiraj mehanizam ponovnog pokušaja za rukovanje mrežnim pogreškama
- Koristi FFmpeg za konverziju postojećih audio datoteka u PCM
- Prikaz uživo koristi
print(text, end="", flush=True)