Přejít na hlavní obsah
Čeština— Vyberte jazyk
Menu

Implementace přepisu v reálném čase v Pythonu

Lekce 10 z 16 Aktualizováno 3. listopadu 2026 Vývojář
Na této stránce
  1. Kompletní asynchronní stream v Pythonu
  2. Architektura streamovacího programu
  3. Základní implementace
  4. Strukturování zpracování pro produkci
  5. Překonání výpadků sítě
  6. Příprava existujícího souboru
  7. Klíčové poznatky

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 modely voxtral-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)