Persian Text to International Phonetic Alphabet (IPA)
Python inference and metadata-processing code for converting Persian (Farsi)
text into phoneme sequences based on the International Phonetic Alphabet
(IPA; Persian: الفبای آوانگاری بینالمللی). The model is a fine-tuned
google/byt5-small checkpoint.
Model weights
The model weights, tokenizer, configuration, and model card are hosted on Hugging Face:
KiaBush/persian-text-to-ipa-byt5
Weights and training data are intentionally not stored in this GitHub repository. The fine-tuning dataset does not have official permission for public redistribution.
Installation
Python 3.10 or newer is recommended.
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
python -m pip install -r requirements.txt
Inference
Run the included examples:
python s3_inference.py
Use the model from Python:
from s3_inference import translate, translate_batch
print(translate("گل رز واقعا زیباست."))
print(translate_batch(["سلام دنیا!", "امروز هوا خوب است."]))
The first run downloads the model from Hugging Face. CUDA is used when
available; otherwise inference runs on CPU. To use a compatible local
checkpoint or another Hub revision, set PERSIAN_G2P_MODEL before importing
s3_inference:
PERSIAN_G2P_MODEL=/path/to/model python s3_inference.py
Limitations
- No official benchmark or evaluation metrics are published for this release.
- Accuracy may vary for names, loanwords, abbreviations, dialectal spellings, numbers, code-switching, and text outside the training distribution.
- Persian pronunciation can depend on context and unwritten ezafe.
- This model is not a forced aligner and does not generate phoneme timestamps.
Authors and contributors
- Ali Akbar Kiaei — research, model training, engineering, and release
- Mahnaz Bush — data preparation, model training, evaluation, research, and documentation
License
The code and model artifacts are released under the Apache License 2.0. The fine-tuning dataset is not included and is not distributed under this license.