Text-to-Speech locale per convertire documenti Markdown (.md) in file audio usando Kokoro ONNX.
Kokoro Reader legge i documenti direttamente dal computer e genera gli audio localmente, senza inviare il contenuto dei documenti a servizi TTS cloud.
È pensato in particolare per la lettura di documenti, appunti e vault Obsidian.
- Legge file Markdown (
.md) - Cerca ricorsivamente nelle sottocartelle
- Mantiene la struttura delle cartelle sorgenti
- Esclude automaticamente la cartella
readings/dalla scansione - Genera un audio WAV per ogni documento
- Crea una cartella
-wavdedicata per ogni documento - Salta automaticamente gli audio già generati
- Permette di interrompere e riprendere una conversione
- Usa Kokoro ONNX localmente
- Supporta diverse voci Kokoro
- Permette di scegliere voce e velocità da riga di comando
- Non modifica i documenti Markdown originali
- Può lavorare direttamente su un vault Obsidian
La directory del progetto contiene:
kokoro-reader/
├── .venv/
├── kokoro-v1.0.onnx
├── voices-v1.0.bin
├── leggi.py
├── test_kokoro.py
├── requirements.txt
├── letture-audio/
└── README.md
Il progetto è portable: leggi.py e test_kokoro.py cercano automaticamente i modelli nella directory in cui si trovano.
Non sono necessari percorsi assoluti specifici per l'utente.
- Linux
- Python 3.12
- Ambiente virtuale Python
- Kokoro ONNX
- Alcuni GB di spazio libero per modelli, dipendenze e audio generati
Entrare nella directory del progetto:
cd /percorso/del/progetto/kokoro-reader
Creare l'ambiente virtuale:
python3 -m venv .venv
Attivare l'ambiente:
source .venv/bin/activate
Installare le dipendenze:
pip install -r requirements.txt
Nella directory del progetto devono essere presenti:
kokoro-v1.0.onnx
voices-v1.0.bin
Gli script individuano automaticamente questi file nella propria directory.
Non è quindi necessario modificare il codice quando il progetto viene spostato.
Il programma accetta:
python leggi.py CARTELLA_SORGENTE CARTELLA_OUTPUT
Esempio:
python leggi.py \
"/percorso/al/vault" \
"/percorso/al/vault/readings"
È possibile specificare anche voce e velocità:
python leggi.py \
"/percorso/al/vault" \
"/percorso/al/vault/readings" \
im_nicola \
1.0
I parametri sono:
CARTELLA_SORGENTE
CARTELLA_OUTPUT
VOCE
VELOCITÀ
La voce predefinita è:
if_sara
La velocità predefinita è:
1.0
La scansione dei Markdown è ricorsiva.
La directory:
readings/
viene esclusa automaticamente dalla scansione.
Questo permette di utilizzare direttamente un vault Obsidian come sorgente senza rischiare di rileggere gli audio o eventuali file presenti nella directory di output.
La scansione procede ordinando i file della directory corrente e successivamente entrando nelle sottodirectory in ordine.
Esempio:
vault/
├── 01-introduzione.md
├── 02-metodo.md
├── code-documentations/
│ ├── 01-api.md
│ └── 02-examples.md
└── readings/
L'ordine di elaborazione sarà:
01-introduzione.md
02-metodo.md
code-documentations/01-api.md
code-documentations/02-examples.md
La struttura delle directory sorgenti viene mantenuta all'interno di readings/.
Ogni Markdown genera una propria directory -wav.
Esempio:
vault/
├── 01-introduzione.md
├── 02-metodo.md
├── code-documentations/
│ ├── 01-api.md
│ └── 02-examples.md
└── readings/
├── 01-introduzione-wav/
│ └── 01-introduzione.wav
├── 02-metodo-wav/
│ └── 02-metodo.wav
└── code-documentations/
├── 01-api-wav/
│ └── 01-api.wav
└── 02-examples-wav/
└── 02-examples.wav
In questo modo la struttura dei documenti e quella degli audio rimangono chiaramente separate.
Kokoro Reader controlla se l'audio di un documento è già presente.
Se il file WAV esiste già, viene saltato.
Esempio:
[SKIP] Audio già presente
Questo permette di interrompere una conversione lunga e riprenderla successivamente senza rigenerare gli audio già completati.
Per esempio, con centinaia di documenti è possibile interrompere il programma con:
Ctrl+C
e successivamente rilanciare lo stesso comando.
Gli audio già generati verranno saltati automaticamente.
Kokoro Reader può essere utilizzato direttamente su un vault Obsidian.
Esempio:
/percorso/vault/
vault/
├── documento-01.md
├── documento-02.md
├── progetti/
│ ├── progetto-a.md
│ └── progetto-b.md
└── readings/
Comando:
python leggi.py \
"/percorso/vault" \
"/percorso/vault/readings"
Il programma leggerà tutti i .md del vault, comprese le sottocartelle, ma escluderà readings/.
Il programma effettua una pulizia preliminare del Markdown prima di passarlo al TTS.
Sono gestiti, tra gli altri:
- titoli
- paragrafi
- liste
- grassetto
- corsivo
- link
- citazioni
- codice
- immagini
- wiki link Obsidian
- frontmatter YAML
Il contenuto leggibile viene estratto e passato a Kokoro.
Documenti Markdown particolarmente complessi potrebbero richiedere ulteriori regole di pulizia.
Kokoro Reader è progettato per funzionare localmente.
Il testo dei documenti viene letto dal filesystem ed elaborato localmente.
Il contenuto dei documenti non viene inviato a un servizio TTS online durante la generazione degli audio.
L'installazione iniziale delle dipendenze Python richiede una connessione Internet.
Una volta installati pacchetti e modelli, la generazione degli audio può essere eseguita localmente.
Per verificare l'installazione di Kokoro:
python test_kokoro.py
Il test dovrebbe caricare:
kokoro-v1.0.onnx
voices-v1.0.bin
dalla directory del progetto e generare un breve file audio di prova.
Controllare:
ls -lh kokoro-v1.0.onnx
e:
ls -lh voices-v1.0.bin
I due file devono trovarsi nella stessa directory degli script.
Controllare anche:
pwd
e:
ls
Controllare:
ls -la
Deve essere presente:
.venv/
Se necessario:
python3 -m venv .venv
Poi:
source .venv/bin/activate
e:
pip install -r requirements.txt
python -c "import kokoro_onnx; print('Kokoro OK')"
find "/percorso/al/vault/readings" -type f -name "*.wav"
find "/percorso/al/vault/readings" -type f -name "*.wav" | wc -l
Entrare nel progetto:
cd /percorso/del/progetto/kokoro-reader
Attivare l'ambiente:
source .venv/bin/activate
Testare Kokoro:
python test_kokoro.py
Convertire un vault:
python leggi.py \
"/percorso/al/vault" \
"/percorso/al/vault/readings"
Convertire scegliendo voce e velocità:
python leggi.py \
"/percorso/al/vault" \
"/percorso/al/vault/readings" \
im_nicola \
1.0
Controllare gli audio:
find "/percorso/al/vault/readings" -type f -name "*.wav"
Contare gli audio:
find "/percorso/al/vault/readings" -type f -name "*.wav" | wc -l
Kokoro Reader non modifica i file Markdown originali.
Gli audio sono file derivati e possono essere rigenerati.
È consigliabile mantenere readings/ separata logicamente dai documenti originali.
Kokoro Reader è un progetto locale per la conversione automatica di documenti Markdown in audio tramite Kokoro ONNX.
Possibili sviluppi:
- supporto MP3
- suddivisione automatica dei documenti molto lunghi
- gestione avanzata dei titoli
- playlist degli audio
- rilevamento dei Markdown modificati
- conversione automatica dei nuovi Markdown
- integrazione più stretta con Obsidian
- interfaccia grafica