persian-text-to-ipa-byt5

Persian Text to International Phonetic Alphabet (IPA) — ByT5

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.

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

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))
# ɡole ɾoz vɒːɣeʔæn ziːbɒːst.

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

Examples of inputs and outputs:

One of the main challenges in Persian pronunciation is that written text often does not uniquely determine pronunciation. Short vowels are generally omitted in Persian orthography, and many words are heteronyms: they have exactly the same written form but different pronunciations depending on their meaning and context.

For example, the Persian word «گل» can mean “flower,” pronounced /ɡol/, or “mud,” pronounced /ɡel/. Correct pronunciation therefore requires more than simple character-to-character transliteration; it requires contextual and semantic disambiguation.

This model was specifically designed to produce IPA representations while taking such contextual ambiguities into account.

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.

Authors and contributors

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