VocabReader

Local vocabulary audio generation using Kokoro.

Structure

data/raw/          Source CSV vocabulary files
data/processed/    Generated TXT and combined CSV files
src/               CSV processing and text-to-audio scripts
requirements.txt   Python package requirements

Setup

Use Python 3.10, 3.11, or 3.12. Kokoro 0.9.x does not support Python 3.13.

python3.11 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt

This project was verified with Python 3.11.7.

CSV Requirements

CSV files to be processed should be UTF-8 text files with vocabulary entries in this shape:

word,definition

Input files may also use quoted rows:

"word","definition"

The first column is the vocabulary word. The second column is the definition. If a word appears in multiple input CSVs, the first definition found is kept.

Part-of-speech markers are normalized when converting CSV to TXT:

(n.)   -> noun,
(v.)   -> verb,
(adj.) -> adjective,

Combine CSVs

Combine, deduplicate, remove double quotes, and shuffle the raw CSV files:

python src/combine_and_shuffle.py data/raw/vocab1.csv data/raw/vocab2.csv

This always writes:

data/processed/combined.csv

Use --seed for reproducible shuffle order:

python src/combine_and_shuffle.py data/raw/vocab1.csv data/raw/vocab2.csv --seed 42

Disable shuffling and keep input order after deduplication:

python src/combine_and_shuffle.py data/raw/vocab1.csv data/raw/vocab2.csv --no-shuffle

Convert CSV To TXT

Convert one CSV into TTS-friendly text:

python src/csv_to_txt.py data/raw/vocab1.csv

By default this writes:

data/processed/vocab1.txt

Convert the combined CSV:

python src/csv_to_txt.py data/processed/combined.csv

This writes:

data/processed/combined.txt

Generated TXT entries look like:

abase: verb, to humiliate, cause to feel shame; verb, to hurt the pride of.

Convert TXT To WAV

Generate speech from a TXT file:

python src/txt_to_wav.py --input data/processed/combined.txt

By default, data/processed/combined.txt writes:

data/processed/combined.wav

Override voice, speed, device, or output path:

python src/txt_to_wav.py --input data/processed/combined.txt --voice af_bella --speed 1.1 --device cpu
python src/txt_to_wav.py --input data/processed/combined.txt --voice af_heart,af_bella --output data/processed/blended.wav

Each non-empty TXT line is generated as its own vocabulary chunk. By default, the script inserts 1 second of silence between vocabulary lines. Override that pause if needed:

python src/txt_to_wav.py --input data/processed/combined.txt --line-pause 1.5

List voices:

python src/txt_to_wav.py --list-voices

Supported devices are cpu, cuda, and auto. With --device auto, the script uses CUDA if available; otherwise it uses CPU.

The first TTS run downloads Kokoro model files from Hugging Face and the spaCy English model. After that, speech generation runs locally on your machine.

Model Cache

Kokoro weights are cached outside the repo by Hugging Face, typically under:

~/.cache/huggingface/hub/models--hexgrad--Kokoro-82M