Implementácia prepisu v reálnom čase v Pythone
Na tejto strane
Kurz aktualizovaný 3. novembra 2026 pre Voxtral 3 na základe príručky Mistral Migrate from Voxtral 2: Modely Voxtral 2 (
voxtral-mini-2602,voxtral-mini-transcribe-realtime-2602,voxtral-mini-tts-2603, vyradené 31. októbra 2026 a úplne odstavené 30. apríla 2027) sú v príkladoch nahradené modelmivoxtral-mini-transcribe-3,voxtral-mini-transcribe-realtime-3avoxtral-mini-tts-3-0. Kľúčové zmeny: časové pečiatky sú dostupné len pre segmenty (wordvráti chybu 400), diarizácia je možná v reálnom čase, nastavenia relácie v reálnom čase sú uzamknuté po prvom zvukovom bloku a vstupycontext_biassú voľného formátu (frázy s medzerami). Zdroje: Migrate from Voxtral 2 · Speech to Text.
Kompletný asynchrónny stream v Pythone
Teraz napíšeš kompletný pipeline prepisu v reálnom čase, od prvého bajtu zvuku až po finálny textový súbor. Všetko stojí na asyncio: program musí súčasne čítať zvuk a prijímať udalosti od modelu, pričom ani jedna operácia nesmie blokovať tú druhú. Štandardný synchronný kód by tu jednoducho čakal a latencia, ktorú si starostlivo nakonfiguroval, by sa stratila v mŕtvom čase tvojho vlastného programu.
Architektúra streamovacieho programu
Bez ohľadu na aplikáciu zostáva štruktúra rovnaká a číta sa zľava doprava. Nahor prúdi zvukový zdroj: asynchrónny generátor, ktorý produkuje bloky PCM zvuku. Dnes to môže byť súbor, zajtra mikrofón alebo sieťový stream. V strede je klient Voxtral, teda SDK, ktoré tlačí tieto bloky modelu a vracia ti udalosti. Nadol nasleduje spracovanie udalostí: tvoja business logika, ktorá zobrazuje text, akumuluje ho, ukladá alebo posiela ďalej inej službe.
Audio Source → [PCM chunks] → Mistral SDK → [events] → Your Code
Toto oddelenie má praktický úžitok: zvukový zdroj je zameniteľný. Kód prepisu, ktorý napíšeš nižšie, bude fungovať identicky s generátorom mikrofónu z ďalšej lekcie, bez zmeny jediného riadku.
Základná implementácia
Dva detaily v tomto prvom programe si zaslúžia tvoju pozornosť. Generátor source_audio_fichier krája súbor na bloky veľké 32 000 bajtov, čo presne zodpovedá jednej sekunde 16-bitového mono PCM zvuku pri 16 kHz: 16 000 vzoriek vynásobených 2 bajtmi. Príkaz await asyncio.sleep nasledujúci po každom yield simuluje reálny čas; ak tento riadok zakomentuješ a spustíš program na niekoľkominútovom úryvku, uvidíš, že súbor sa spotrebuje za zlomok sekundy, čo ťa nič nenaučí o správaní streamovania. Na strane prijímania premenná texte_complet akumuluje fragmenty, takže máš na konci k dispozícii celý text navyše k živému zobrazeniu.
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):
"""Asynchrónny generátor, ktorý číta PCM súbor po blokoch.
taille_chunk = 32 000 bajtov = 1 sekunda 16-bitového mono PCM zvuku pri 16 kHz
(16 000 vzoriek × 2 bajty = 32 000 bajtov)
"""
with open(chemin, "rb") as f:
while True:
chunk = f.read(taille_chunk)
if not chunk:
break
yield chunk
# Simulácia reálneho času (1 blok = 1 sekunda)
await asyncio.sleep(len(chunk) / 32000)
async def transcrire_realtime(source_audio):
"""Prepisuje zvukový stream v reálnom čase pomocou 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--- Prepis dokončený ---")
return "".join(texte_complet)
async def main():
source = source_audio_fichier("audio.pcm")
texte = await transcrire_realtime(source)
# Uloženie výsledku
with open("transcription_realtime.txt", "w", encoding="utf-8") as f:
f.write(texte)
print(f"\nText uložený ({len(texte)} znakov)")
asyncio.run(main())
Živé zobrazenie sa spolieha na print(event.text, end="", flush=True). Bez flush=True by Python vyrovnávaciu pamäť výstupu a text by sa objavoval v dávkach: tvoj prepis by bol technicky v reálnom čase, ale vizuálne by trhal.
Štruktúrovanie spracovania pre produkciu
Akonáhle tvoja aplikácia prerastie fázu dema, cyklus if/elif sa stane nepraktickým: budeš chcieť počítať fragmenty, merať trvanie, pripojiť displej alebo kŕmiť databázu. Zapuzdrenie logiky do triedy tento problém vyrieši raz a navždy. Každý typ udalosti dostane svoju vlastnú vyhradenú metódu a môžeš pridať správanie – napríklad odoslanie každého delta fragmentu na webové rozhranie – bez toho, aby si musel zasahovať do slučky prijímania.
class GestionnaireTranscription:
"""Spracováva udalosti prepisu v reálnom čase."""
def __init__(self):
self.texte_complet = []
self.nb_deltas = 0
self.debut = None
async def traiter(self, source_audio):
"""Spustí prepis a spracuje udalosti."""
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):
"""Volané pre každý nový textový fragment."""
self.texte_complet.append(event.text)
self.nb_deltas += 1
# Živé zobrazenie
print(event.text, end="", flush=True)
def _on_done(self, event):
"""Volané na konci prepisu."""
import time
duree = time.time() - self.debut
print(f"\n\nDokončené za {duree:.1f}s")
print(f"Prijatých fragmentov: {self.nb_deltas}")
def obtenir_resultat(self) -> str:
"""Vráti celý prepísaný text."""
return "".join(self.texte_complet)
async def main():
gestionnaire = GestionnaireTranscription()
source = source_audio_fichier("audio.pcm")
texte = await gestionnaire.traiter(source)
print(f"Výsledok: {len(texte)} znakov")
asyncio.run(main())
Počítadlo nb_deltas nie je len ozdobou: vo vzťahu k trvaniu zvuku indikuje rýchlosť emisie modelu a upozorní ťa, ak sa stream degraduje.
Prežitie výpadkov siete
Streamovacie pripojenie zostáva otvorené počas celého trvania reči, čo ho vystavuje riziku oveľa viac než niekoľkosekundová offline požiadavka. Kolísavá Wi-Fi, prepínanie siete na mobilnom zariadení alebo výpadok operátora môžu stream prerušiť. Nižšie uvedený vzor reštartuje prepis až trikrát, s oneskorením, ktoré sa s každým pokusom zvyšuje, aby sa sieti dal čas na obnovu. Po tomto limite sa výnimka propaguje ďalej: explicitné zlyhanie je lepšie než aplikácia, ktorá sa tvári, akoby nič nepočula.
import asyncio
from mistralai.client import Mistral
from mistralai.client.models import (
AudioFormat,
TranscriptionStreamTextDelta,
TranscriptionStreamDone
)
MAX_TENTATIVES = 3
DELAI_RECONNEXION = 2 # sekundy
async def transcrire_avec_retry(source_audio, tentative=1):
"""Prepis s automatickým opätovným pripojením."""
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[Dokončené]")
except ConnectionError as e:
if tentative < MAX_TENTATIVES:
print(f"\nChyba siete (pokus {tentative}/{MAX_TENTATIVES})")
await asyncio.sleep(DELAI_RECONNEXION * tentative)
await transcrire_avec_retry(source_audio, tentative + 1)
else:
print(f"\nZlyhanie po {MAX_TENTATIVES} pokusoch: {e}")
raise
Príprava existujúceho súboru
Ak chceš testovať s MP3 alebo WAV súborom, ktorý už máš po ruke, môžeš automatizovať konverziu do PCM priamo z Pythonu namiesto manuálneho spúšťania. Funkcia nižšie deleguje prácu na FFmpeg, odvodi názov výstupného súboru zo vstupného názvu a vráti výslednú cestu, pripravenú na odovzdanie funkcii source_audio_fichier.
import subprocess
def convertir_en_pcm(chemin_entree: str, chemin_sortie: str = None) -> str:
"""Konvertuje zvukový súbor na 16-bitové 16kHz mono PCM cez 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
# Použitie
chemin_pcm = convertir_en_pcm("reunion.mp3")
# Potom použite source_audio_fichier(chemin_pcm)
S touto funkciou sú spojené dve opatrenia. check=True vyhodí výnimku, ak FFmpeg zlyhá, čo je lepšie, než neskôr v streame objaviť prázdny PCM súbor; a capture_output=True skryje výstup nástroja, takže pri dlhej konverzii sa bude zdať, že program zamrzol. Pri hodinových nahrávkach si naplánuj vypísanie správy pred a po volaní.
Kľúčové poznatky
- Streamovanie využíva asynchrónne generátory (
async for,yield) - Blok 32 000 bajtov = 1 sekunda 16-bitového mono PCM zvuku pri 16 kHz
- Pre produkciu štruktúruj spracovanie udalostí do triedy
- Implementuj mechanizmus opakovania na ošetrenie chýb siete
- Na konverziu existujúcich zvukových súborov do PCM použi FFmpeg
- Živé zobrazenie používa
print(text, end="", flush=True)