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

Kaappaa mikrofoni PyAudion avulla

Oppitunti 11 / 16 Päivitetty 3. marraskuuta 2026 Kehittäjä
Tällä sivulla
  1. Tiedostosta mikrofoniin
  2. PyAudion asentaminen
  3. Mikrofonigeneraattori
  4. Täydellinen ohjelma: Mikrofonista litterointiin
  5. Oikean laitteen valinta
  6. 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, vanhentuneet 31. lokakuuta 2026 ja poistuvat käytöstä 30. huhtikuuta 2027) on korvattu esimerkeissä 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), reaaliaikainen puhujan tunnistus on tuettu, reaaliaikaisen istunnon asetukset lukittuvat ensimmäisen äänipaketin jälkeen, ja context_bias-syötteet ovat joustavia (välilyönnillisiä fraaseja). Lähteet: Migrate from Voxtral 2 · Speech to Text.

Tiedostosta mikrofoniin

Edellinen oppitunti loi arkkitehtuurin, jossa äänilähde on yksinkertainen, helposti vaihdettava asynkroninen generaattori. Hyödynnät tätä heti: kun vaihdat tiedostoa lukevan generaattorin äänikorttia lukevaan, ohjelmasi alkaa litteroida puhettasi reaaliajassa muuttamatta ainoatakaan riviä muussa koodissa.

Tämän oppitunnin työkalu on PyAudio, Pythonin standardikirjasto äänilaitteiden käyttöön. Se nojaa PortAudioon, natiiviin kerrokseen, joka saatat joutua asentamaan erikseen järjestelmästäsi riippuen.

PyAudion asentaminen

# Linux (Debian/Ubuntu)
sudo apt-get install portaudio19-dev
pip install pyaudio

# macOS
brew install portaudio
pip install pyaudio

# Windows
pip install pyaudio

Mikrofonigeneraattori

Tämän oppitunnin ydin mahtuu noin kolmeenkymmeneen riviin. Funktio avaa syötevirran oletuslaitteelle, toistaa loputtomasti kiinteänkokoisia lohkoja ja luovuttaa jokaisen niistä litterointimoottorille. finally-lohko ei ole koriste: se takaa, että virta pysähtyy, sulkeutuu ja PyAudio vapauttaa laitteiston, vaikka ohjelma keskeytyisi äkillisesti. Ilman sitä mikrofoni voi jäädä lukkoon ja estää muiden sovellusten käytön.

import asyncio
import pyaudio

async def iter_microphone(
    sample_rate: int = 16000,
    chunk_duration_ms: int = 480
):
    """Kaappaa mikrofoni ja luovuttaa PCM-lohkoja.

    Args:
        sample_rate: Näytteenottotaajuus (16000 Hz Voxtralille)
        chunk_duration_ms: Kunkin lohkon kesto millisekunteina

    Yields:
        bytes: 16-bittisiä mono-PCM-äänilohkoja
    """
    p = pyaudio.PyAudio()

    # Näytteiden määrä lohkoa kohden
    chunk_samples = int(sample_rate * chunk_duration_ms / 1000)

    # Avaa mikrofonivirta
    stream = p.open(
        format=pyaudio.paInt16,    # 16-bittinen PCM
        channels=1,                 # Mono
        rate=sample_rate,           # 16 kHz
        input=True,                 # Kaappaustila
        frames_per_buffer=chunk_samples
    )

    loop = asyncio.get_running_loop()

    try:
        print("Mikrofoni aktiivinen — puhu...")
        while True:
            # Lue lohko ei-estävänä
            data = await loop.run_in_executor(
                None,
                stream.read,
                chunk_samples,
                False  # exception_on_overflow
            )
            yield data
    finally:
        stream.stop_stream()
        stream.close()
        p.terminate()
        print("Mikrofoni suljettu")

Jokaisella parametrilla on erityinen syy. sample_rate=16000 heijastaa mallin vaatimusta, ei mieltymystä: Voxtral odottaa 16 kHz:n taajuutta, joten älä muuta tätä arvoa. pyaudio.paInt16 vastaa etumerkillistä 16-bittistä PCM-muotoa, joka on täysin vastaava API-puolella määritellyn pcm_s16le:n kanssa, ja channels=1 pakottaa monon, mikä on myös vaatimus. Jäljelle jää chunk_duration_ms=480, ainoa todella keskusteltava asetus: jokainen lohko edustaa 480 millisekuntia ääntä, hyvä kompromissi vasteajan ja verkon tehokkuuden välillä. Lyhyempi lohko, esimerkiksi 100 ms, parantaa vasteaikaa mutta moninkertaistaa verkkopyynnöt; pidempi lohko säästää kaistanleveyttä lisääntyneen viiveen kustannuksella ennen kuin malli näkee äänen.

Myös loop.run_in_executor-kutsu ansaitsee selityksen. stream.read on estävä funktio: se pitää säiettä varattuna, kunnes pyydetty määrä näytteitä on saatavilla. Sen suorittaminen suoraan korutiinissa jäädyttäisi koko asyncio-silmukan, mukaan lukien litterointitapahtumien vastaanoton. Siirtämällä se suorittajalle (executor) teet lukemisesta yhteensopivan muun asynkronisen ohjelman kanssa.

Lohkon koon laskeminen seuraa mekaanisesti kahdesta asetuksesta, kun sample_rate=16000 ja chunk_duration_ms=480:

chunk_samples = 16000 × 480 / 1000 = 7680 näytettä
byte_size = 7680 × 2 tavua = 15360 tavua lohkoa kohden

Täydellinen ohjelma: Mikrofonista litterointiin

Seuraava skripti yhdistää kaappauksen ja litteroinnin käyttövalmiiksi sanelutyökaluksi. Uusi elementti edelliseen generaattoriin verrattuna on siisti sammutuskäsittely: signaalinkäsittelijä sieppaa Ctrl+C:n, kääntää running-lipun arvoksi False, mikä poistuu kaappaussilmukasta, sulkee virran ja mahdollistaa ohjelman tallentaa kertyneen tekstin. Ilman tätä mekanismia näppäimistökeskeytys tappaisi prosessin ennen tallennusta, ja menettäisit sanelun.

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

# Lippu siistiä sammutusta varten
running = True

def signal_handler(sig, frame):
    global running
    print("\n\nSammutetaan...")
    running = False

signal.signal(signal.SIGINT, signal_handler)

async def iter_microphone(sample_rate=16000, chunk_duration_ms=480):
    """Kaappaa mikrofoni kunnes keskeytetään (Ctrl+C)."""
    p = pyaudio.PyAudio()
    chunk_samples = int(sample_rate * chunk_duration_ms / 1000)

    stream = p.open(
        format=pyaudio.paInt16,
        channels=1,
        rate=sample_rate,
        input=True,
        frames_per_buffer=chunk_samples
    )

    loop = asyncio.get_running_loop()

    try:
        while running:
            data = await loop.run_in_executor(
                None, stream.read, chunk_samples, False
            )
            yield data
    finally:
        stream.stop_stream()
        stream.close()
        p.terminate()

async def main():
    client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
    audio_format = AudioFormat(encoding="pcm_s16le", sample_rate=16000)

    print("=" * 50)
    print("REAALIAIKAINEN LITTEROINTI")
    print("Puhu mikrofoniin (lopeta painamalla Ctrl+C)")
    print("=" * 50)
    print()

    full_text = []

    async for event in client.audio.realtime.transcribe_stream(
        audio_stream=iter_microphone(),
        model="voxtral-mini-transcribe-realtime-3",
        audio_format=audio_format,
    ):
        if isinstance(event, TranscriptionStreamTextDelta):
            print(event.text, end="", flush=True)
            full_text.append(event.text)

        elif isinstance(event, TranscriptionStreamDone):
            break

    # Tallenna
    final_text = "".join(full_text)
    if final_text.strip():
        with open("dictee.txt", "w", encoding="utf-8") as f:
            f.write(final_text)
        print(f"\n\nLitterointi tallennettu tiedostoon dictee.txt")
        print(f"Pituus: {len(final_text)} merkkiä")
    else:
        print("\n\nEi litteroitua tekstiä.")

asyncio.run(main())

Suorita se, puhu, pysäytä Ctrl+C:llä: teksti ilmestyy puhuessasi ja päätyy lopulta tiedostoon dictee.txt.

python dictee_vocale.py
# Puhu mikrofoniisi
# Teksti ilmestyy reaaliajassa
# Ctrl+C pysäyttää

Kokeile noin kolmenkymmenen sekunnin yhtenäisellä ranskankielisellä puheella, vaihtele vauhtia ja vertaa sanomaasi tiedoston sisältöön. Se on paras tapa kalibroida odotuksesi ennen viiveen hienosäätöä seuraavassa oppitunnissa.

Oikean laitteen valinta

Koneessa, jossa on sisäänrakennettu mikrofoni, USB-kuulokkeet ja verkkokamera, oletuslaite ei aina ole se, jonka luulet, ja tyhjä litterointi johtuu usein tästä yksityiskohdasta. Listaa ensin saatavilla olevat syötteet niiden indeksin kanssa:

def list_microphones():
    """Listaa kaikki saatavilla olevat äänen syöttölaitteet."""
    p = pyaudio.PyAudio()
    print("Saatavilla olevat syöttölaitteet:")
    for i in range(p.get_device_count()):
        info = p.get_device_info_by_index(i)
        if info["maxInputChannels"] > 0:
            print(f"  [{i}] {info['name']} "
                  f"(kanavat: {info['maxInputChannels']}, "
                  f"taajuus: {int(info['defaultSampleRate'])} Hz)")
    p.terminate()

list_microphones()

Sitten pakota valittu indeksi virran avauksen yhteydessä input_device_index-parametrin avulla:

stream = p.open(
    format=pyaudio.paInt16,
    channels=1,
    rate=sample_rate,
    input=True,
    input_device_index=2,  # Laitteen indeksi
    frames_per_buffer=chunk_samples
)

Keskeiset asiat

  • PyAudio kaappaa mikrofonin 16-bittisenä mono-PCM:nä 16 kHz:n taajuudella, täsmälleen kuten Voxtral odottaa
  • iter_microphone-generaattori luovuttaa oletusarvoisesti 480 ms:n lohkoja
  • loop.run_in_executor tekee mikrofonin lukemisesta ei-estävää asiossa
  • Ctrl+C pysäyttää kaappauksen siististi signaalinkäsittelijän avulla
  • Listaa laitteet get_device_count():lla valitaksesi oikean mikrofonin