Implementace přepisu v reálném čase v Pythonu
Na této stránce
Kurz aktualizován 3. listopadu 2026 pro Voxtral 3 na základě průvodce Mistralu Migrate from Voxtral 2: Modely Voxtral 2 (
voxtral-mini-2602,voxtral-mini-transcribe-realtime-2602,voxtral-mini-tts-2603'), které byly zastaralé k 31. říjnu 2026 a vyřazené k 30. dubnu 2027, jsou v příkladech nahrazeny modelyvoxtral-mini-transcribe-3,voxtral-mini-transcribe-realtime-3avoxtral-mini-tts-3-0. Klíčové změny: časová razítka jsou pouze pro segmenty (wordvrací chybu 400), diarizace je možná v reálném čase, nastavení relace v reálném čase jsou uzamčena po prvním zvukovém bloku a vstupycontext_bias` jsou volného formátu (fráze s mezerami). Zdroje: Migrate from Voxtral 2 · Speech to Text.
Kompletní asynchronní stream v Pythonu
Nyní napíšeš kompletní pipeline pro přepis v reálném čase, od prvního zvukového bajtu až po finální textový soubor. Všechno stojí na asyncio: program musí současně číst zvuk a přijímat události od modelu, aniž by jedna operace blokovalou druhou. Běžný synchronní kód by zde prostě čekal a latence, kterou jsi pečlivě nakonfiguroval, by zmizela v mrtvém čase tvého vlastního programu.
Architektura streamovacího programu
Bez ohledu na aplikaci zůstává struktura stejná a čte se zleva doprava. Nahoře je zdroj zvuku: asynchronní generátor, který produkuje bloky PCM zvuku. Dnes to může být soubor, zítra mikrofon nebo síťový stream. Uprostřed je klient Voxtral, tedy SDK, které tyto bloky posílá modelu a předává ti události. Dole je zpracování událostí: tvá obchodní logika, která zobrazuje text, akumuluje ho, ukládá nebo přeposílá další službě.
Audio Source → [PCM chunks] → Mistral SDK → [events] → Your Code
Toto oddělení má praktický přínos: zdroj zvuku je zaměnitelný. Kód pro přepis, který níže napíšeš, bude fungovat totožně s generátorem mikrofonu z další lekce, aniž bys musel měnit jediný řádek.
Základní implementace
Dva detaily v tomto prvním programu si zaslouží tvou pozornost. Generátor source_audio_fichier krájí soubor na bloky o velikosti 32 000 bajtů, což přesně odpovídá jedné sekundě 16bitového mono PCM zvuku při 16 kHz: 16 000 vzorků vynásobeno 2 bajty. Následující await asyncio.sleep po každém yield simuluje reálný čas; zakomentuj tento řádek a spusť program na několikaminutovém úryvku a uvidíš, že se soubor spotřebuje za zlomek sekundy, což tě nic nenaučí o chování streamu. Na straně příjmu texte_complet akumuluje fragmenty, takže máš na konci k dispozici celý text, navíc k živému zobrazení.
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):
"""Asynchronní generátor, který čte PCM soubor po blocích.
taille_chunk = 32000 bajtů = 1 sekunda 16bitového mono PCM zvuku při 16kHz
(16000 vzorků × 2 bajty = 32000 bajtů)
"""
with open(chemin, "rb") as f:
while True:
chunk = f.read(taille_chunk)
if not chunk:
break
yield chunk
# Simulace reálného času (1 blok = 1 sekunda)
await asyncio.sleep(len(chunk) / 32000)
async def transcrire_realtime(source_audio):
"""Přepisuje zvukový stream v reálném čase s Voxtralem."""
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--- Přepis dokončen ---")
return "".join(texte_complet)
async def main():
source = source_audio_fichier("audio.pcm")
texte = await transcrire_realtime(source)
# Uložení výsledku
with open("transcription_realtime.txt", "w", encoding="utf-8") as f:
f.write(texte)
print(f"\nText uložen ({len(texte)} znaků)")
asyncio.run(main())
Živé zobrazení spoléhá na print(event.text, end="", flush=True). Bez flush=True by Python výstup bufferoval a text by se objevoval v dávkách: tvůj přepis by byl technicky v reálném čase, ale vizuálně trhavý.
Strukturování zpracování pro produkci
Jakmile tvoje aplikace překročí fázi dema, smyčka if/elif se stává nepohodlnou: chceš počítat fragmenty, měřit dobu trvání, napojit displej nebo krmit databázi. Zapouzdření logiky do třídy tento problém řeší jednou provždy. Každý typ události dostane svou vlastní vyhrazenou metodu a můžeš přidávat chování – například odesílání každého delta přírůstku na webové rozhraní – aniž bys musel sahat na smyčku pro příjem.
class GestionnaireTranscription:
"""Zpracovává události přepisu v reálném čase."""
def __init__(self):
self.texte_complet = []
self.nb_deltas = 0
self.debut = None
async def traiter(self, source_audio):
"""Spustí přepis a zpracuje události."""
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):
"""Voláno pro každý nový textový fragment."""
self.texte_complet.append(event.text)
self.nb_deltas += 1
# Živé zobrazení
print(event.text, end="", flush=True)
def _on_done(self, event):
"""Voláno na konci přepisu."""
import time
duree = time.time() - self.debut
print(f"\n\nDokončeno za {duree:.1f}s")
print(f"Přijaté fragmenty: {self.nb_deltas}")
def obtenir_resultat(self) -> str:
"""Vrátí celý přepsaný 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ýsledek: {len(texte)} znaků")
asyncio.run(main())
Počítadlo nb_deltas není jen trik: ve vztahu k délce zvuku indikuje rychlost emise modelu a upozorní tě, pokud se stream degraduje.
Překonání výpadků sítě
Streamovací připojení zůstává otevřené po celou dobu řeči, což ho vystavuje mnohem většímu riziku než několikasekundový offline požadavek. Kolísající Wi-Fi, přepnutí sítě na mobilním zařízení nebo výpadek operátora mohou stream přerušit. Níže uvedený vzor restartuje přepis až třikrát, s prodlevou, která se s každým pokusem zvyšuje, aby se síti dal čas na obnovu. Nad tento limit se výjimka propaguje dál: explicitní selhání je lepší než aplikace, která se tváří, jako by nic neposlouchala.
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):
"""Přepis s automatickým opětovným připojení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čeno]")
except ConnectionError as e:
if tentative < MAX_TENTATIVES:
print(f"\nChyba sítě (pokus {tentative}/{MAX_TENTATIVES})")
await asyncio.sleep(DELAI_RECONNEXION * tentative)
await transcrire_avec_retry(source_audio, tentative + 1)
else:
print(f"\nSelhání po {MAX_TENTATIVES} pokusech: {e}")
raise
Příprava existujícího souboru
Chceš-li testovat s MP3 nebo WAV souborem, který už máš po ruce, můžeš automatizovat převod do PCM přímo z Pythonu, místo abys to dělal ručně. Funkce níže deleguje práci na FFmpeg, odvodí výstupní název ze vstupního názvu a vrátí výslednou cestu, připravenou k předání do source_audio_fichier.
import subprocess
def convertir_en_pcm(chemin_entree: str, chemin_sortie: str = None) -> str:
"""Převede zvukový soubor na 16bitové 16kHz mono PCM pomocí 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žití
chemin_pcm = convertir_en_pcm("reunion.mp3")
# Poté použij source_audio_fichier(chemin_pcm)
S touto funkcí jsou spojeny dvě opatření. check=True vyvolá výjimku, pokud FFmpeg selže, což je lepší, než když později ve streamu objevíš prázdný PCM soubor; a capture_output=True skryje výstup nástroje, takže při dlouhé konverzi se bude zdát, že program zamrzl. U hodinových nahrávek si naplánuj výpis zprávy před voláním a po něm.
Klíčové poznatky
- Streaming využívá asynchronní generátory (
async for,yield) - Blok o velikosti 32 000 bajtů = 1 sekunda 16bitového mono PCM zvuku při 16 kHz
- Pro produkci strukturovej zpracování událostí do třídy
- Implementuj mechanismus opakování pro řešení chyb sítě
- Použij FFmpeg k převodu existujících zvukových souborů do PCM
- Živé zobrazení používá
print(text, end="", flush=True)