This is a fine-tuned Transformers-compatible sequence-to-sequence model for converting Persian (Farsi) text into phoneme sequences based on the International Phonetic Alphabet (IPA; in Persian: الفبای آوانگاری بین‌المللی). It uses a ByT5 tokenizer and T5ForConditionalGeneration architecture.

Source code

Inference and metadata-processing code is available on GitHub: KiaBush/persian-text-to-ipa-byt5.

Authors and contributors

Ali Akbar Kiaei — research, model training, engineering, and release
Mahnaz Bush — data preparation, model training, evaluation, research, and documentation

Intended use

The model is intended as a Persian grapheme-to-phoneme component for speech processing and text-to-speech pipelines. Punctuation handling and text normalization may need to be adapted to the downstream system.

Usage

python

import torch
from transformers import ByT5Tokenizer, T5ForConditionalGeneration

model_id = "KiaBush/persian-text-to-ipa-byt5"
device = torch.device("cuda" if torch.cuda.is_available() else "cpu")

# The explicit mapping keeps checkpoints saved with older tokenizer configs
# compatible with Transformers versions where extra_special_tokens is a map.
tokenizer = ByT5Tokenizer.from_pretrained(
    model_id,
    extra_special_tokens={},
)
model = T5ForConditionalGeneration.from_pretrained(model_id).to(device)
model.eval()

text = "گل رز واقعا زیباست."
inputs = tokenizer(text, return_tensors="pt").to(device)

with torch.inference_mode():
    output_ids = model.generate(**inputs, max_new_tokens=512)

print(tokenizer.decode(output_ids[0], skip_special_tokens=True))

For long inputs, split text into chunks no longer than 256 input tokens and preserve punctuation outside the generated phoneme spans.

Model details

Base model: google/byt5-small
Architecture: encoder-decoder T5 (T5ForConditionalGeneration)
Tokenizer: ByT5Tokenizer
Source language: Persian (fa)
Output: phoneme text based on the International Phonetic Alphabet (IPA)
Maximum input length used by the accompanying inference code: 256 tokens
Maximum generated length used by the accompanying inference code: 512 tokens

Limitations

No public benchmark results are included in this release.
Accuracy may vary for names, loanwords, abbreviations, dialectal spellings, code-switching, numbers, and text outside the training distribution.
Persian pronunciation can depend on context and unwritten ezafe; outputs should be reviewed for high-stakes or production linguistic applications.
This model should not be treated as a forced aligner and does not produce phoneme-level timestamps.

Training data

The fine-tuning dataset is not included in this repository and cannot be redistributed because it does not have official permission for public release. Detailed dataset provenance, preprocessing, and split definitions are not published. Users should take this into account when assessing suitability, bias, licensing, and expected generalization.

Evaluation

No official evaluation results or public benchmark metrics are included in this release.

License

The model artifacts in this repository are released under the Apache License 2.0. The fine-tuning dataset is not distributed under this license and is not included in the repository.