A text-to-speech voice for Persian poetry and prose. The voice is "nobody's voice": a ZipVoice flow-matching model trained from scratch on Ganjoor recitations (used with Ganjoor's consent) and ManaTTS (CC0), prompted with a disguised recording, so that it is close to no corpus reciter. The model itself (weights, voice prompt, token list, lexicon) is described in models/README.md.
| You want to | Use | Download |
|---|---|---|
| read with the best quality, in Python with a GPU | the full model ganj-zip-d4h (64 steps, several takes per line) |
release v1.2.0, or the top level and g2p/ on Hugging Face |
| read on a phone or laptop CPU, as the Ganj app does | the distilled model (4 to 8 steps, ONNX for sherpa-onnx) | release phone-1.2.0, or ganj-zip-distill-1.2.0/ |
Older app downloads stay online unchanged, because installed apps fetch them: release phone-v1 and Hugging Face
ganj-zip-distill/ (voice 1.1.0, used by Ganj 1.6.0), and release v1.1.0 (ganj-zip-distill.zip). Version 1.2.0
brought a better letters-to-phonemes model; the voice itself is unchanged since 1.1.0.
Download the model folder ganj-zip-d4h from Releases or
Hugging Face, install the packages (below) and set up ZipVoice (recipes/README.md), then:
python tools/reading_list.py ganj-zip-d4h/example_in.jsonl lists --voice ganj-zip-d4h
VOICE_DIR=ganj-zip-d4h recipes/zipvoice/synth_voice.sh lists/list.tsv out lists/text.jsonlout/ then holds one WAV file per line of example_in.jsonl. To read your own text, write it in the same format.
Hemistichs that are not Persian (Arabic, Azeri Turkish) are left out of the list unless you add --read-all: the
voice reads them badly.
The model folder ganj-zip-distill (same places) is the same voice made to read in 8 steps instead of 64, as ONNX
files for sherpa-onnx 2.0.1 on a phone's CPU. Its README gives the files, the
settings (phone.json) and the clean-up the app does after sherpa. On a computer, read a list made as above with it
(in an environment with sherpa-onnx 2.0.1):
cp lists/list.tsv lists/phone.tsv
python -m ganj_voice.glue lists/phone.tsv --tokens ganj-zip-distill/tokens.txt # what the model reads
python tools/sherpa_read.py ganj-zip-distill lists/phone.tsv out_raw
python -m ganj_voice.phonepost out_raw out_phone --phone ganj-zip-distill/phone.json --set lists/text.jsonlThe code is split into packages that other projects can use on their own; they live in one repository and depend on each other only in this order: reading → corpus → voice → eval.
| Package | Import | What it does | Needs |
|---|---|---|---|
| ganj-reading | ganj_reading |
Persian poetry reading rules: letters to phonemes (Homo-GE2PE) with ezafe, harakat, tashdid, sukun, tanwin and small-alef rules and a word lexicon; aruz metre scansion; the token set (style, metre and pause tokens); which hemistichs are read (not the non-Persian ones) | – |
| ganj-corpus | ganj_corpus |
Training data from Ganjoor and ManaTTS: selection, download, cutting at aligned pauses, cleaning, labels, pause labels, the rules check every label must pass | ganj-reading |
| ganj-voice | ganj_voice |
Voice disguise and synthesis helpers: prompt disguise (WORLD, Praat, mel domain), mains-hum and noise removal, mel despike before the vocoder, guidance interval, finer sampler finish, regeneration from part-way along the flow, pause trimming, Vocos fine-tune data; the phone voice: distillation settings, the despiking ONNX vocoder, the prompt as sherpa-onnx reads it, the clean-up after sherpa | ganj-reading |
| ganj-eval | ganj_eval |
Evaluation: Whisper WER, UTMOS, distance to every corpus reciter's voice, prosody against a reference reading, CTC label checks, noise measures, a listening page | reading, corpus, voice |
Beside the packages:
- recipes/ – the scripts that build the corpus, train ZipVoice, synthesise and score the voice
(
recipes/zipvoice/), and fine-tune Vocos (recipes/vocos/). See recipes/README.md. - tools/ – command-line tools: voice prompts (
make_prompt.py,melwarp_prompt.py), post-processing (postclean.py,trim_pauses.py), choosing among noise draws (pick_draws.py), checks before synthesis or training (check_rules.py,g2p_gate.py), pause labels (pause_labels.py), metre and lexicon tools (freeze_metres.py,scansion_report.py,validate_lexicon.py), corpus audits (boundary_audit.py,ina_segment.py), measurements (noise_probe.py,prosody_compare.py), reading with the phone model (sherpa_read.py), training the Arabic-hemistich detector (train_arabic_detector.py) and a licence check of the installed packages (check_licenses.py). Each file's docstring says how to run it.
Python 3.10 or newer (developed on 3.11). From the repository root:
pip install -e "packages/ganj-reading[g2p]" -e packages/ganj-corpus -e packages/ganj-voice -e "packages/ganj-eval[models]"A package can also be installed alone, with the ones it needs, e.g. only the reading rules:
pip install -e packages/ganj-reading # tokens and scansion; add [g2p] for the letters-to-phonemes modelfrom ganj_reading.scansion import scans
scans("t/vana bov/d h/r ke dana bov/d", "فعولن فعولن فعولن فعل") # True: the line scans in the metreThe training and synthesis recipes also need a ZipVoice checkout and its environment; see recipes/README.md.
| Variable | Used by | Meaning |
|---|---|---|
GANJ_DATA |
tools, recipes | the data folder: corpus, eval set, model runs, voice packages (not in git) |
ZIPVOICE_DIR |
recipes, tools/pause_labels.py |
a ZipVoice checkout (https://github.com/k2-fsa/ZipVoice) |
GANJ_PY, ZIPVOICE_PY, INA_PY, SHERPA_PY |
recipes | the command that runs Python in each environment (defaults python, python3, python, python) |
A tool or recipe that needs one of these stops with a message naming it when it is not set.
pip install pytest
pytest -q # from the repository root: every package, the tools and the recipes; no GPU, data or networkEach package's tests also run on their own (cd packages/ganj-reading && pytest -q). Tests that need GANJ_DATA and
downloaded audio are marked integration and skip without it.
Code: GNU AGPL-3.0-or-later (LICENSE). Model: CC BY-NC 4.0 (models/LICENSE). For-profit use needs a commercial licence: COMMERCIAL.md. Third-party parts: NOTICE.md. The people and data behind the voice: CREDITS.md. Contributions: CONTRIBUTING.md.
Copyright (c) 2026 Amin Akbari.