Central Kurdish G2P (Graph2Phon)

A modern, high-performance, and linguistically accurate Grapheme-to-Phoneme (G2P) converter and Syllabifier for Central Kurdish (Sorani).

Designed specifically for training modern Text-to-Speech (TTS) models (VITS, FastSpeech2, Glow-TTS) by providing robust phonetization, stress marking, and syllable boundaries.

(کوردی) دەربارەی پڕۆژە

ئەم پڕۆژەیە ئامرازێکی پێشکەوتووە بۆ گۆڕینی دەقی کوردی (سۆرانی) بۆ فۆنێم و بڕگە. بەتایبەت دیزاین کراوە بۆ سیستەمەکانی دروستکردنی دەنگ و ڕاهێنانی مۆدێلەکانی زیرەکی دەستکرد.

خێراییەکی زۆر بەرزی هەیە و هەموو یاسا دەنگییەکانی زمانی کوردی (وەک پاڵاتەڵایزەیشن، بزرۆکە، و فۆکەس) لەخۆدەگرێت.

🔗 Live Demos

• G2P Playground: ckb-g2p.streamlit.app
• Text Normalizer: ckb-textify.streamlit.app

🌟 Why Graph2Phon?

Generic G2P tools often fail on Kurdish phonology. ckb-g2p (v3) combines architectural speed with linguistic depth to solve these challenges:

🚀 Installation

From PyPI

pip install ckb-g2p

From Source

git clone [https://github.com/RazwanSiktany/ckb_g2p.git](https://github.com/RazwanSiktany/ckb_g2p.git)
cd ckb_g2p
pip install -e .

💻 Usage

Command Line Interface (CLI)

You can use the tool directly from your terminal:

# Basic usage (Syllabified)
ckb-g2p "سڵاو کوردستان"
# Output: sɪ.ˈɫäw kuɾ.dɪs.ˈtän

# Raw IPA (No stress, no syllable markers)
ckb-g2p "سڵاو" --format ipa --no-stress
# Output: sɪɫäw

# Batch Processing (Great for datasets)
ckb-g2p -i input.txt -o output.txt

Python API

from ckb_g2p.converter import Converter

# Initialize (loads cache by default)
converter = Converter()

# 1. Basic Syllabification
text = "من کوردم"
ipa = converter.convert(text, output_format="syllables")
print(ipa) 
# Output: ['mɪn', 'kuɾ.ˈdɪm']

# 2. TTS-Ready Output (with Pauses)
# Note: Punctuation is automatically converted to pauses (| and ||)
text = "سڵاو، ناوت چییە؟"
ipa_list = converter.convert(text, output_format="syllables")
print(" ".join(ipa_list))
# Output: sɪ.ˈɫäw | näwt ˈt͡ʃiː.ja ||

🗣️ Phoneme Inventory

We use a precise IPA set to capture allophonic variations critical for natural speech synthesis.

Consonants (Key Distinctions)

⚡ Performance & Caching

Graph2Phon uses a local SQLite database (lexicon.db) to store processed words.

• First Run: Calculates phonemes (~1-5ms per word).
• Second Run: Fetches from cache (<0.1ms per word).

To disable caching:

converter = Converter(use_cache=False)

🛠️ Configuration & Exceptions

The engine is driven by a YAML configuration file located at src/ckb_g2p/data/phonology.yaml.

Manual Overrides: If the rule-based engine fails on a specific word (e.g., a foreign name), add it to src/ckb_g2p/resources/exceptions.csv

🤝 Contributing

Contributions are welcome! Please run the test suite before submitting a PR:

pip install pytest
pytest

📜 License

MIT License. See LICENSE for details.

👨‍💻 Author

Developed by Razwan M. Haji.