Preskoči na glavni sadržaj
Hrvatski— Odaberite jezik
Izbornik

Implementacija transkripcije u stvarnom vremenu u Pythonu

Lekcija 10 od 16 Ažurirano 3. studenoga 2026. Programer
Na ovoj stranici
  1. Potpuni asinkroni stream u Pythonu
  2. Arhitektura streaming programa
  3. Osnovna implementacija
  4. Strukturiranje obrade za produkciju
  5. Preživljavanje prekida mreže
  6. Priprema postojeće datoteke
  7. Ključne točke

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 s voxtral-mini-transcribe-3, voxtral-mini-transcribe-realtime-3 i voxtral-mini-tts-3-0. Ključne promjene: vremenske oznake su samo po segmentima (word vrać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 unosi context_bias su 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)