Teaching ByT5 to Sound Out Persian Text

What it does This repository provides Python inference code for a fine-tuned google/byt5-small model that converts Persian (Farsi) text into International Phonetic Alphabet phoneme sequences. It is essentially a lightweight client: the weights, tokenizer, and model card live on Hugging Face, while this repo handles translation and batch inference. The output is meant for TTS pipelines or linguistic analysis.

The interesting bit Persian G2P is tricky because the script omits many vowels and relies on an unwritten ezafe construction to link words, yet the model attempts to infer these missing phonetic cues from context alone. That makes it a learned alternative to hand-crafted pronunciation rules, though the README admits the results are uneven.

Key highlights

• Built on the google/byt5-small transformer checkpoint.
• Supports single and batch inference with automatic fallback from GPU to CPU.
• Weights are fetched from Hugging Face on first run; a PERSIAN_G2P_MODEL environment variable lets you redirect to a local checkpoint.
• Apache 2.0 license covers the code and model artifacts, though the training dataset is withheld from public redistribution.

Caveats

• No official benchmarks or evaluation metrics are published, so accuracy is essentially anecdotal.
• Expect trouble with names, loanwords, abbreviations, numbers, code-switching, and the unwritten ezafe constructions that link Persian words.
• The model outputs phoneme strings but no timestamps or forced-alignment data.

Verdict Worth a look if you are building Persian TTS or phonetic dictionaries; skip it if you need benchmarked, production-hardened G2P or phoneme-level alignment.