# Output atteso: Python 3.8.x o superiore

Se la versione è più vecchia, aggiorna il sistema o installa una versione più recente di Python.

Installazione di Piper TTS

Per mantenere l’ambiente pulito e evitare conflitti con le librerie di sistema, è consigliato utilizzare un virtual environment (venv).

Creazione e attivazione del virtual environment

python3 -m venv .venvsource .venv/bin/activate

Dopo l’attivazione, il prompt della shell dovrebbe mostrare il prefisso (.venv). Da questo punto in poi tutti i pacchetti verranno installati all’interno dell’ambiente isolato.

Installazione del pacchetto Piper

pip install --upgrade pippip install piper-tts

Il comando pip install piper-tts scarica l’ultima versione stabile disponibile su PyPI, includendo le dipendenze necessarie come onnxruntime.

Verifica dell’installazione

piper --help

Se il comando restituisce l’elenco delle opzioni disponibili, l’installazione è avvenuta correttamente.

Gestione dei modelli vocali ONNX

Piper utilizza modelli .onnx accompagnati da un file di configurazione .json. Il file JSON contiene parametri di velocità, rumore e mappature fonetiche.

Scaricare un modello di esempio

Per questa guida utilizziamo la voce inglese “Amy”. Il procedimento è identico per qualsiasi altra voce disponibile.

wget -O en_US-amy-medium.onnx "wget -O en_US-amy-medium.onnx.json "

Assicurati che entrambi i file siano nella stessa directory di lavoro.

Struttura del file di configurazione JSON

Modificando questi valori è possibile personalizzare la voce per adattarla a scenari specifici (es. robotica, assistenti vocali, installazioni artistiche).

Test iniziale: generare un file WAV

Una volta scaricati i file, è possibile verificare il funzionamento con un semplice comando:

echo "Hello from your Raspberry Pi!" | piper -m en_US-amy-medium.onnx --output_file hello.wavaplay hello.wav

Il comando aplay è l’utilità di default per la riproduzione di file audio su Linux. Se l’audio è udibile e privo di distorsioni evidenti, il motore è correttamente configurato.

Streaming diretto verso ALSA

Per applicazioni in tempo reale (es. assistenti vocali) è più efficiente inviare il flusso audio direttamente a aplay senza creare un file intermedio:

echo "This is a streaming test." | piper -m en_US-amy-medium.onnx --output-raw | aplay -r 22050 -f S16_LE -t raw -

Assicurati che i parametri di aplay (-r 22050, -f S16_LE) corrispondano a quelli specificati dal modello ONNX. La maggior parte dei modelli forniti da Piper utilizza una frequenza di campionamento di 22 050 Hz e 16 bit PCM.

Ottimizzazione della catena audio su Raspberry Pi

La qualità percepita dipende non solo dal modello vocale, ma anche da come il segnale audio viene gestito dal sistema operativo. Di seguito trovi le principali aree di intervento.

Impostazioni ALSA

ALSA (Advanced Linux Sound Architecture) è il sottosistema audio predefinito su Raspberry Pi. Modificando il file /etc/asound.conf o creando un file ~/.asoundrc è possibile:

• Ridurre la latenza impostando un buffer più piccolo.
• Forzare il formato a 16 bit PCM per evitare conversioni costose.
• Abilitare il mixing hardware se la scheda audio lo supporta.

Esempio di configurazione a bassa latenza:

pcm.!default {type plug slave {pcm "hw:0,0" format S16_LE rate 22050 period_time 10000 # 10 ms di buffer buffer_size 64000 # 64 KB di buffer totale}}

Questa configurazione riduce il ritardo di riproduzione a circa 10 ms, ideale per interazioni vocali in tempo reale.

Utilizzo di PulseAudio (opzionale)

Se il progetto richiede la gestione di più flussi audio simultanei, è possibile installare pulseaudio e configurare un modulo di latenza ridotta. Tuttavia, su Raspberry Pi è consigliato mantenere ALSA per la massima efficienza.

Ottimizzazione del driver audio

Alcune schede audio USB offrono impostazioni di “sample rate conversion” (SRC) hardware. Verifica la documentazione del produttore e, se disponibile, abilita l’SRC a 22 050 Hz per evitare la conversione software.

Parametri di inferenza e fine‑tuning

Piper espone diversi parametri che influenzano la qualità della voce. Questi possono essere modificati direttamente nel file .json o passati come opzioni da riga di comando.

Parametri di velocità e durata

• phoneme_duration_scale: valore >1 allunga i fonemi, rendendo la voce più lenta e più chiara.
• length_scale (all’interno di "inference"): controlla la durata complessiva della frase.

Esempio di modifica per una voce più lenta:

{"phoneme_duration_scale": 1.3, "inference": {"length_scale": 1.4, "noise_scale": 0.45, "noise_w": 0.55}}

Parametri di rumore

Il rumore sintetico è utile per rendere la voce più naturale, ma un valore troppo alto può introdurre fruscii udibili.

• noise_scale: riducendo questo valore si ottiene un suono più pulito.
• noise_w: regola il peso del rumore nella generazione del segnale.

Passare i parametri da riga di comando

Se non si desidera modificare il file JSON, è possibile sovrascrivere i valori al volo:

echo "Testing custom parameters." | piper -m en_US-amy-medium.onnx \ --phoneme_duration_scale 1.2 \ --length_scale 1.3 \ --noise_scale 0.4 \ --output-raw | aplay -r 22050 -f S16_LE -t raw -

Questa flessibilità è particolarmente utile in script che devono adattare la voce a contesti diversi (es. annunci rapidi vs. narrazioni lente).

Uso della GPU (opzionale)

Le versioni più recenti di Raspberry Pi (es. Raspberry Pi 4 con GPU VideoCore VI) non supportano ancora CUDA, ma è possibile sfruttare la GPU di una scheda NVIDIA collegata via USB o un acceleratore Edge TPU. In questi casi, Piper può essere eseguito con onnxruntime‑gpu.

Installazione del runtime GPU

.venv/bin/pip install onnxruntime-gpu

Dopo l’installazione, aggiungi il flag --cuda al comando Piper:

echo "Running on GPU." | piper -m en_US-amy-medium.onnx --cuda --output-raw | aplay -r 22050 -f S16_LE -t raw -

Nota: è necessario un ambiente CUDA funzionante, tipicamente fornito da container NVIDIA o da driver proprietari installati sul sistema host.

Benefici dell’uso della GPU

• Riduzione del tempo di inferenza da circa 300 ms a meno di 100 ms per frase media.
• Possibilità di gestire più richieste simultanee senza saturare la CPU.
• Maggiore scalabilità per progetti che prevedono voci multiple o effetti audio aggiuntivi.

Se il progetto non prevede una GPU dedicata, la configurazione CPU descritta nei paragrafi precedenti è più che sufficiente.

Migliorare le prestazioni e ridurre la latenza

Oltre alle impostazioni audio, ci sono diverse tecniche per ottimizzare le prestazioni di Piper su Raspberry Pi.

Utilizzo di thread multipli

Il runtime ONNX può sfruttare più core della CPU. Imposta la variabile d’ambiente OMP_NUM_THREADS al numero di core disponibili (es. 4 su Raspberry Pi 4).

export OMP_NUM_THREADS=4

Questa impostazione deve essere definita prima di avviare lo script Python o il comando Piper.

Cache dei modelli in RAM

Caricare il modello ONNX in memoria una sola volta riduce il tempo di avvio. Se utilizzi Piper da Python, è possibile mantenere l’oggetto modello in una variabile globale.

from piper import Piperpiper = Piper(model_path="en_US-amy-medium.onnx")def speak(text): audio = piper.synthesize(text) # invia audio a ALSA o salva su file

In questo modo il modello non viene ricaricato ad ogni chiamata.

Riduzione della frequenza di campionamento

Alcuni progetti non richiedono la qualità a 22 050 Hz. Se la destinazione è un altoparlante a bassa fedeltà, è possibile forzare una frequenza di 16 000 Hz, riducendo il carico di elaborazione.

piper -m en_US-amy-medium.onnx --output_raw --sample_rate 16000 | aplay -r 16000 -f S16_LE -t raw -

Attenzione: la modifica della frequenza richiede che il modello supporti il nuovo sample rate; altrimenti la voce può risultare distorta.

Profilazione con perf

Per identificare colli di bottiglia, utilizza lo strumento perf incluso in Debian:

sudo perf record -g -- piper -m en_US-amy-medium.onnx --output_raw | aplay -r 22050 -f S16_LE -t raw -sudo perf report

Il report evidenzierà le funzioni più costose (tipicamente onnxruntime o numpy).

Risoluzione dei problemi più comuni

Log di debug di Piper

Per ottenere informazioni più dettagliate, aggiungi il flag --log_level debug:

piper -m en_US-amy-medium.onnx --log_level debug --output-raw | aplay -r 22050 -f S16_LE -t raw -

Il log mostrerà i tempi di caricamento del modello, la configurazione audio e eventuali errori di runtime.

Casi d'uso tipici nei progetti maker

Di seguito sono elencati alcuni esempi pratici in cui Piper TTS può essere integrato in progetti basati su Raspberry Pi.

Assistente vocale domestico

• Utilizza piper per generare risposte a comandi vocali riconosciuti da Snowboy o Porcupine.
• Imposta una latenza inferiore a 100 ms per una conversazione fluida.
• Salva le risposte in cache per ridurre il carico di inferenza su richieste ripetute.

Robotica educativa

Un robot basato su Raspberry Pi può annunciare lo stato dei sensori (es. “Temperatura ambiente 23 gradi”) usando Piper. Grazie al modello offline, il robot può operare anche in ambienti senza connessione internet.

Installazioni artistiche interattive

Artisti possono sincronizzare la voce sintetizzata con luci LED o proiezioni. La capacità di regolare length_scale e noise_scale permette di creare atmosfere “spettrali” o “robotiche” a seconda del contesto.

Dispositivi di accessibilità

Per persone con disabilità visive, Piper può trasformare testi da file PDF o da schermate di terminale in audio chiaro, senza dipendere da servizi cloud che potrebbero violare la privacy.

Monitoraggio remoto di impianti IoT

Un Raspberry Pi installato in una serra può inviare avvisi vocali (“Umidità bassa, attivazione irrigazione”) direttamente sul posto, evitando la necessità di app mobile.

Conclusioni e prossimi passi

Ottimizzare la qualità audio di Piper TTS su Raspberry Pi richiede un approccio a più livelli: dalla corretta installazione del motore, alla scelta di modelli vocali adeguati, fino alla configurazione fine della catena audio e dei parametri di inferenza. Seguendo i consigli di questa guida, è possibile ottenere una sintesi vocale fluida, a bassa latenza e con un suono pulito, adatta a una vasta gamma di progetti maker.

Per approfondire, considera i seguenti prossimi passi:

1. Creare uno script Python che gestisca la cache dei modelli e offra un’interfaccia semplice per la sintesi.
2. Sperimentare con la modifica dei parametri length_scale e noise_scale per personalizzare la voce in base al contesto.
3. Integrare Piper con un riconoscitore di parole chiave offline per realizzare un assistente vocale completamente locale.
4. Valutare l’uso di un acceleratore hardware (es. NVIDIA Jetson Nano) se il progetto richiede più voci simultanee.
5. Documentare le impostazioni di latenza e qualità in un file README per condividere il risultato con la community maker.