Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Cattura il microfono con PyAudio

Lezione 11 di 16 Aggiornata il 3 novembre 2026 Sviluppatore
In questa pagina
  1. Dal file al microfono
  2. Installazione di PyAudio
  3. Il generatore del microfono
  4. Programma completo: dal microfono alla trascrizione
  5. Scelta del dispositivo corretto
  6. Punti chiave

Corso aggiornato il 3 novembre 2026 per Voxtral 3, basato sulla guida Migrate from Voxtral 2 di Mistral: i modelli Voxtral 2 (voxtral-mini-2602, voxtral-mini-transcribe-realtime-2602, voxtral-mini-tts-2603, deprecati il 31 ottobre 2026 e ritirati il 30 aprile 2027) sono sostituiti negli esempi da voxtral-mini-transcribe-3, voxtral-mini-transcribe-realtime-3 e voxtral-mini-tts-3-0. Cambiamenti principali: i timestamp sono solo per segmento (word restituisce un errore 400), la diarizzazione in tempo reale è supportata, le impostazioni della sessione in tempo reale sono bloccate dopo il primo chunk audio e gli input context_bias sono flessibili (frasi con spazi). Fonti: Migrate from Voxtral 2 · Speech to Text.

Dal file al microfono

La lezione precedente ha stabilito un’architettura in cui la sorgente audio è un generatore asincrono semplice e intercambiabile. Sfrutterai subito questo concetto: sostituendo il generatore che legge da file con uno che legge dalla scheda audio, il tuo programma inizierà a trascrivere la tua voce in diretta senza modificare una singola riga del resto del codice.

Lo strumento per questa lezione è PyAudio, la libreria Python standard per accedere ai dispositivi audio. Si appoggia a PortAudio, un livello nativo che potresti dover installare separatamente a seconda del tuo sistema.

Installazione di PyAudio

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

# macOS
brew install portaudio
pip install pyaudio

# Windows
pip install pyaudio

Il generatore del microfono

Il cuore di questa lezione sta in una trentina di righe. La funzione apre un flusso di input sul dispositivo predefinito, entra in un ciclo infinito leggendo blocchi di dimensione fissa e cede ciascuno di essi al motore di trascrizione. Il blocco finally non è decorativo: garantisce che il flusso si arresti, si chiuda e che PyAudio rilasci l’hardware anche se il programma viene interrotto bruscamente. Senza di esso, il microfono potrebbe rimanere bloccato, impedendo l’uso ad altre applicazioni.

import asyncio
import pyaudio

async def iter_microphone(
    sample_rate: int = 16000,
    chunk_duration_ms: int = 480
):
    """Cattura il microfono e cede chunk PCM.

    Args:
        sample_rate: Frequenza di campionamento (16000 Hz per Voxtral)
        chunk_duration_ms: Durata di ogni chunk in millisecondi

    Yields:
        bytes: Chunk audio PCM mono a 16 bit
    """
    p = pyaudio.PyAudio()

    # Numero di campioni per chunk
    chunk_samples = int(sample_rate * chunk_duration_ms / 1000)

    # Apre il flusso del microfono
    stream = p.open(
        format=pyaudio.paInt16,    # PCM a 16 bit
        channels=1,                 # Mono
        rate=sample_rate,           # 16 kHz
        input=True,                 # Modalità cattura
        frames_per_buffer=chunk_samples
    )

    loop = asyncio.get_running_loop()

    try:
        print("Microfono attivo — parla...")
        while True:
            # Legge il chunk in modo non bloccante
            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("Microfono chiuso")

Ogni parametro ha una ragione specifica. sample_rate=16000 riflette un requisito del modello, non una preferenza: Voxtral si aspetta 16 kHz, quindi non cambiare questo valore. pyaudio.paInt16 corrisponde al formato PCM signed a 16 bit, esattamente equivalente al pcm_s16le dichiarato lato API, e channels=1 impone il mono, anch’esso obbligatorio. Resta chunk_duration_ms=480, l’unica impostazione davvero discutibile: ogni chunk rappresenta 480 millisecondi di audio, un buon compromesso tra reattività ed efficienza di rete. Un chunk più breve, diciamo 100 ms, migliora la reattività ma moltiplica le richieste di rete; un chunk più lungo risparmia banda a costo di aggiungere latenza prima che il modello veda l’audio.

Anche la chiamata loop.run_in_executor merita una spiegazione. stream.read è una funzione bloccante: trattiene il thread finché il numero richiesto di campioni non è disponibile. Eseguirla direttamente in una coroutine bloccherebbe l’intero loop asyncio, inclusa la ricezione degli eventi di trascrizione. Delegandola a un executor, rendi la lettura compatibile con il resto del programma asincrono.

Il calcolo della dimensione del blocco deriva meccanicamente dalle due impostazioni, per sample_rate=16000 e chunk_duration_ms=480:

chunk_samples = 16000 × 480 / 1000 = 7680 campioni
byte_size = 7680 × 2 byte = 15360 byte per chunk

Programma completo: dal microfono alla trascrizione

Lo script seguente combina cattura e trascrizione in uno strumento di dettatura pronto all’uso. L’elemento nuovo rispetto al generatore precedente è la gestione pulita dell’arresto: un gestore di segnali intercetta Ctrl+C, imposta il flag running su False, il che esce dal ciclo di cattura, chiude il flusso e permette al programma di salvare il testo accumulato. Senza questo meccanismo, un’interruzione da tastiera ucciderebbe il processo prima del salvataggio e perderesti la dettatura.

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

# Flag per l'arresto pulito
running = True

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

signal.signal(signal.SIGINT, signal_handler)

async def iter_microphone(sample_rate=16000, chunk_duration_ms=480):
    """Cattura il microfono fino all'interruzione (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("TRASCRIZIONE IN DIRETTA")
    print("Parla nel microfono (Ctrl+C per fermare)")
    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

    # Salvataggio
    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\nTrascrizione salvata in dictee.txt")
        print(f"Lunghezza: {len(final_text)} caratteri")
    else:
        print("\n\nNessun testo trascritto.")

asyncio.run(main())

Eseguilo, parla, fermati con Ctrl+C: il testo appare mentre parli, per poi finire in dictee.txt.

python dictee_vocale.py
# Parla nel tuo microfono
# Il testo appare in tempo reale
# Ctrl+C per fermare

Provalo con circa trenta secondi di francese continuo, variando il ritmo, e confronta ciò che hai detto con ciò che il file contiene. È il modo migliore per calibrare le tue aspettative prima di ottimizzare la latenza nella prossima lezione.

Scelta del dispositivo corretto

Su una macchina con microfono integrato, cuffie USB e webcam, il dispositivo predefinito non è sempre quello che pensi, e una trascrizione vuota suele dipendere da questo dettaglio. Prima, elenca gli input disponibili con il loro indice:

def list_microphones():
    """Elenca tutti i dispositivi di input audio disponibili."""
    p = pyaudio.PyAudio()
    print("Dispositivi di input disponibili:")
    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"(canali: {info['maxInputChannels']}, "
                  f"freq: {int(info['defaultSampleRate'])} Hz)")
    p.terminate()

list_microphones()

Poi imposta semplicemente l’indice scelto all’apertura del flusso, tramite il parametro input_device_index:

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

Punti chiave

  • PyAudio cattura il microfono in PCM mono a 16 bit a 16 kHz, esattamente ciò che Voxtral si aspetta
  • Il generatore iter_microphone cede chunk di 480 ms per impostazione predefinita
  • loop.run_in_executor rende la lettura del microfono non bloccante in asyncio
  • Ctrl+C arresta pulitamente la cattura tramite un gestore di segnali
  • Elenca i dispositivi con get_device_count() per scegliere il microfono giusto