Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

Toteuta reaaliaikainen transkriptio Pythonilla

Oppitunti 10 / 16 Päivitetty 3. marraskuuta 2026 Kehittäjä
Tällä sivulla
  1. Täydellinen Pythonin asynkroninen virta
  2. Streamausohjelman arkkitehtuuri
  3. Perustoteutus
  4. Käsittelyn jäsentäminen tuotantokäyttöön
  5. Verkkokatkojen kestämien
  6. Olemassa olevan tiedoston valmistelu
  7. Keskeiset asiat

Kurssi päivitetty 3. marraskuuta 2026 Voxtral 3:lle Mistralin Migrate from Voxtral 2 -oppaan pohjalta: Voxtral 2 -mallit (voxtral-mini-2602, voxtral-mini-transcribe-realtime-2602, voxtral-mini-tts-2603) poistettiin käytöstä 31. lokakuuta 2026 ja ne lopetetaan kokonaan 30. huhtikuuta 2027. Esimerkeissä ne on korvattu malleilla voxtral-mini-transcribe-3, voxtral-mini-transcribe-realtime-3 ja voxtral-mini-tts-3-0. Keskeiset muutokset: aikaleimat ovat vain segmenttitasolla (word palauttaa 400-virheen), puhujantunnistus on mahdollista reaaliajassa, reaaliaikaisen istunnon asetukset lukittuvat ensimmäisen äänipaketin jälkeen, ja context_bias-syötteet ovat vapaamuotoisia (välilyönnillä erotettuja fraaseja). Lähteet: Migrate from Voxtral 2 · Speech to Text.

Täydellinen Pythonin asynkroninen virta

Nyt kirjoitat kokonaisen reaaliaikaisen transkriptioputken ensimmäisestä äänibytistä viimeiseen tekstiedostoon asti. Kaikki perustuu asyncio-kirjastoon: ohjelman on luettava ääntä ja vastaanotettava mallin tapahtumia samanaikaisesti siten, ettei kumpikaan operaatio estä toista. Tavallinen synkroninen koodi vain odottaisi tässä vaiheessa, ja huolellisesti säätämäsi latenssi katoaisi oman ohjelmasi kuolleeseen aikaan.

Streamausohjelman arkkitehtuuri

Sovelluksesta riippumatta rakenne pysyy samana ja etenee vasemmalta oikealle. Ylävirrassa on äänilähde: asynkroninen generaattori, joka tuottaa PCM-äänipaketteja. Tänään se voi olla tiedosto, huomenna mikrofoni tai verkkovirta. Keskellä on Voxtral-asiakas, eli SDK, joka syöttää nämä paketit mallille ja välittää tapahtumat sinulle. Alavirrassa on tapahtumien käsittely: liiketoimintalogiikkasi, joka näyttää tekstin, kerää sitä, tallentaa sen tai välittää eteenpäin toiseen palveluun.

Audio Source → [PCM chunks] → Mistral SDK → [events] → Your Code

Tällä erottelulla on käytännön hyöty: äänilähde on vaihdettavissa. Alla kirjoittamasi transkriptiokoodi toimii täysin identtisesti seuraavan tunnin mikrofonigeneraattorin kanssa ilman, että muutat riviäkään.

Perustoteutus

Tässä ensimmäisessä ohjelmassa kaksi yksityiskohtaa ansaitsevat huomiosi. source_audio_fichier-generaattori pilkkoo tiedoston 32 000 tavun lohkoihin, mikä vastaa täsmälleen yhtä sekuntia 16-bittistä mono-PCM-ääntä taajuudella 16 kHz: 16 000 näytettä kerrottuna kahdella tavulla. Jokaisen yield-lauseen jälkeinen await asyncio.sleep simuloi reaaliaikaa; kommentoi tämä rivi pois ja aja ohjelma muutaman minuutin pätkällä, niin näet tiedoston kuluvan murto-osassa sekuntia, etkä opi mitään streamauksen toiminnasta. Vastaanottopäässä texte_complet kerää fragmentit, jotta koko teksti on käytettävissä lopussa reaaliaikaisen näytön lisäksi.

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):
    """Asynkroninen generaattori, joka lukee PCM-tiedoston paketeissa.

    taille_chunk = 32000 tavua = 1 sekunti 16-bittistä mono-PCM-ääntä 16 kHz:n taajuudella
    (16000 näytettä × 2 tavua = 32000 tavua)
    """
    with open(chemin, "rb") as f:
        while True:
            chunk = f.read(taille_chunk)
            if not chunk:
                break
            yield chunk
            # Simuloi reaaliaikaa (1 paketti = 1 sekunti)
            await asyncio.sleep(len(chunk) / 32000)

async def transcrire_realtime(source_audio):
    """Transkriptoi äänivirran reaaliajassa Voxtralilla."""
    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--- Transkriptio valmis ---")

    return "".join(texte_complet)

async def main():
    source = source_audio_fichier("audio.pcm")
    texte = await transcrire_realtime(source)

    # Tallenna tulos
    with open("transcription_realtime.txt", "w", encoding="utf-8") as f:
        f.write(texte)
    print(f"\nTeksti tallennettu ({len(texte)} merkkiä)")

asyncio.run(main())

Reaaliaikainen näyttö perustuu lauseeseen print(event.text, end="", flush=True). Ilman parametria flush=True Python puskuroi tulosteen, ja teksti ilmestyisi erissä: transkriptiosi olisi teknisesti reaaliaikainen, mutta visuaalisesti nykivä.

Käsittelyn jäsentäminen tuotantokäyttöön

Kun sovelluksesi siirtyy demon vaiheesta eteenpäin, if/elif-silmukasta tulee kömpelö: haluat laskea fragmentteja, mitata kestoa, kytkeä näyttöliittymän tai syöttää tietoa tietokantaan. Logiikan kapseloiminen luokkaan ratkaisee ongelman kerralla. Jokainen tapahtumatyyppi saa oman omistetun metodinsa, ja voit lisätä toiminnallisuutta – esimerkiksi lähettää jokaisen deltan verkkoliittymään – koskematta vastaanottosilmukkaan.

class GestionnaireTranscription:
    """Käsittelee reaaliaikaisia transkriptiotapahtumia."""

    def __init__(self):
        self.texte_complet = []
        self.nb_deltas = 0
        self.debut = None

    async def traiter(self, source_audio):
        """Käynnistää transkription ja käsittelee tapahtumat."""
        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):
        """Kutsutaan jokaisesta uudesta tekstifragmentista."""
        self.texte_complet.append(event.text)
        self.nb_deltas += 1
        # Reaaliaikainen näyttö
        print(event.text, end="", flush=True)

    def _on_done(self, event):
        """Kutsutaan transkription päätyttyä."""
        import time
        duree = time.time() - self.debut
        print(f"\n\nValmis ajassa {duree:.1f}s")
        print(f"Vastaanotetut fragmentit: {self.nb_deltas}")

    def obtenir_resultat(self) -> str:
        """Palauttaa koko transkriptoidun tekstin."""
        return "".join(self.texte_complet)

async def main():
    gestionnaire = GestionnaireTranscription()
    source = source_audio_fichier("audio.pcm")
    texte = await gestionnaire.traiter(source)
    print(f"Tulos: {len(texte)} merkkiä")

asyncio.run(main())

Laskuri nb_deltas ei ole pelkkä koristelu: suhteessa äänen kestoon se kertoo mallin lähetysnopeuden ja varoittaa, jos virran laatu heikkenee.

Verkkokatkojen kestämien

Streamausyhteys pysyy auki koko puheen keston ajan, mikä altistaa sen paljon enemmän kuin muutaman sekunnin offline-pyyntö. Pätkivä Wi-Fi, verkon vaihto mobiililaitteella tai operaattorin katkos voivat keskeyttää virran. Alla oleva malli käynnistää transkription uudelleen enintään kolme kertaa viiveellä, joka kasvaa jokaisella yrityksellä verkon toipumisen mahdollistamiseksi. Tämän jälkeen poikkeus välitetään eteenpäin: selkeä epäonnistuminen on parempi kuin sovellus, joka näyttää kuuntelevan tyhjyyttä.

import asyncio
from mistralai.client import Mistral
from mistralai.client.models import (
    AudioFormat,
    TranscriptionStreamTextDelta,
    TranscriptionStreamDone
)

MAX_TENTATIVES = 3
DELAI_RECONNEXION = 2  # sekuntia

async def transcrire_avec_retry(source_audio, tentative=1):
    """Transkriptio automaattisella uudelleenyhteydenotolla."""
    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[Valmis]")

    except ConnectionError as e:
        if tentative < MAX_TENTATIVES:
            print(f"\nVerkkovirhe (yritys {tentative}/{MAX_TENTATIVES})")
            await asyncio.sleep(DELAI_RECONNEXION * tentative)
            await transcrire_avec_retry(source_audio, tentative + 1)
        else:
            print(f"\nEpäonnistui {MAX_TENTATIVES} yrityksen jälkeen: {e}")
            raise

Olemassa olevan tiedoston valmistelu

Testataksesi MP3- tai WAV-tiedostolla, joka sinulla on jo valmiina, voit automatisoida muunnoksen PCM-muotoon Pythonista käsin manuaalisen suorittamisen sijaan. Alla oleva funktio delegoi työn FFmpegille, päättee tulosteen nimen syötteen nimen perusteella ja palauttaa valmiin polun, jonka voit syöttää funktiolle source_audio_fichier.

import subprocess

def convertir_en_pcm(chemin_entree: str, chemin_sortie: str = None) -> str:
    """Muuntaa äänitiedoston 16-bittiseksi 16 kHz:n mono-PCM:ksi FFmpegillä."""
    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

# Käyttö
chemin_pcm = convertir_en_pcm("reunion.mp3")
# Käytä sitten source_audio_fichier(chemin_pcm)

Tähän funktioon liittyy kaksi varotoimenpidettä. check=True nostaa poikkeuksen, jos FFmpeg epäonnistuu, mikä on parempi kuin huomata myöhemmin virrassa olevan tyhjän PCM-tiedoston; ja capture_output=True piilottaa työkalun tulosteen, jotta pitkä muunnos ei saa ohjelmaa näyttämään jumiutuneelta. Tuntien pituisia nauhoituksia varten suunnittele viestin tulostaminen ennen kutsua ja sen jälkeen.

Keskeiset asiat

  • Streamaus käyttää asynkronisia generaattoreita (async for, yield)
  • 32 000 tavun paketti = 1 sekunti 16-bittistä mono-PCM-ääntä 16 kHz:n taajuudella
  • Jäsennä tapahtumien käsittely luokkaan tuotantokäyttöä varten
  • Toteuta uudelleenyrittämismekanismi verkkovirheiden hallintaan
  • Käytä FFmpegiä olemassa olevien äänitiedostojen muuntamiseen PCM-muotoon
  • Reaaliaikainen näyttö käyttää komentoa print(text, end="", flush=True)