Skip to content

About

Persian poetry text-to-speech in nobody's voice: code, recipes and model card. Model on Hugging Face: aminkvh/Ganj_voice

Resources

Contributing

Stars

0 stars

Watchers

0 watching

Forks

 
 

Repository files navigation

Ganj voice (آوای گنج)

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.

Which download do I want?

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.

Use the voice

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.jsonl

out/ 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.

Use the voice on a phone

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.jsonl

Code

The 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.

Install

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 model
from ganj_reading.scansion import scans

scans("t/vana bov/d h/r ke dana bov/d", "فعولن فعولن فعولن فعل")   # True: the line scans in the metre

The training and synthesis recipes also need a ZipVoice checkout and its environment; see recipes/README.md.

Environment

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.

Tests

pip install pytest
pytest -q            # from the repository root: every package, the tools and the recipes; no GPU, data or network

Each 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.

Licence

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.

About

Persian poetry text-to-speech in nobody's voice: code, recipes and model card. Model on Hugging Face: aminkvh/Ganj_voice

Resources

Contributing

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages