Skip to main content

oro-g2p 🗣️

License: MIT Python: 3.9+

oro-g2p is a zero-dependency, research-grade Yoruba Grapheme-to-Phoneme (G2P) engine and phonetic tokenizer designed for speech synthesis (TTS), automatic speech recognition (ASR), and forced alignment.

It provides out-of-the-box native token mapping for Kokoro-82M and StyleTTS2.


Key Features

  1. Deterministic Linguistic Engine: Pure, rule-based Yoruba phonology — zero hallucinations, reproducible output.
  2. Post-Nasal Harmony: Automatically captures unwritten phonetic nasalization on vowels following nasal consonants m and n (ọmọ → /ɔˉmɔ̃ˉ/, inú → /iˉnũˊ/).
  3. Chameleon Syllabic Nasals: Dynamically applies homorganic place assimilation to ń and ǹ:
    • Labials (b, f): /m/ (Mo ń bọ̀ → moˉ mˊ bɔˋ)
    • Alveolars (d, t, s, ṣ): /n/ (Mo ń ṣe → moˉ nˊ ʃeˉ)
    • Velars & Glides (l, k, g): /ŋ/ (Mo ń lọ → moˉ ŋˊ lɔˉ)
  4. Typo Resilience: Seamlessly normalizes Turkish cedillas (ş), combining vertical lines (\u0329), and out-of-order diacritic keystrokes into canonical Yoruba underdots (ẹ, ọ, ṣ).
  5. Contour Glides: Expands carons (ǎ → àá Low-High) and circumflexes (â → áà High-Low).
  6. Native Kokoro Alignment: Maps 100% of Yoruba phonemes and tones directly into Kokoro-82M's 178-token embedding table with 0 missing tokens.

Installation

pip install oro-g2p

Quickstart

1. Basic G2P Conversion

from oro_g2p import g2p

# Converts Yoruba text to tone-marked IPA
phonemes = g2p("Ẹ kú àárọ̀, ọmọ Yorùbá!")
print(phonemes)
# Output: 'ɛˉ kuˊ aˋaˊɾɔˋ, ɔˉmɔ̃ˉ joˉɾuˋbaˊ!'

2. Kokoro-82M Tokenization

from oro_g2p import yoruba_to_kokoro

text = "Ẹ kú àárọ̀"
ipa_str, token_ids, missing = yoruba_to_kokoro(text)

print(f"IPA:       {ipa_str}")
print(f"Token IDs: {token_ids}")
print(f"Missing:   {missing}")  # [] -> 100% coverage!

Architecture: Kokoro-82M Token Mapping

Kokoro has a fixed embedding matrix size of 178 (0 to 177). While 114 slots were occupied by Western languages, 64 slots were unassigned.

oro-g2p resolves Yoruba without modifying any pre-trained weights or embedding tensor dimensions:

  • High Tone (Mí): Assigned to Vacant Slot 7 (ˊ)
  • Mid Tone (Ré): Assigned to Vacant Slot 8 (ˉ)
  • Low Tone (Dò): Assigned to Vacant Slot 26 (ˋ)
  • Nasal Vowels: Decomposed into (vowel + \u0303), cleanly utilizing Kokoro's native Room 17.

Running Tests

python -m pytest tests/

License

MIT License. Free for academic, personal, and commercial speech technology research.

Metadata

Release files for oro-g2p 0.1.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for oro-g2p 0.1.1
File Size Uploaded Provenance Actions
oro_g2p-0.1.1.tar.gz 11.4 kB Without provenance Details for oro_g2p-0.1.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for oro-g2p 0.1.1
File Interpreter ABI Platform Actions
oro_g2p-0.1.1-py3-none-any.whl Python 3 none any Details for oro_g2p-0.1.1-py3-none-any.whl

Total release size: 21.7 kB

Release files / oro_g2p-0.1.1.tar.gz

Download URL oro_g2p-0.1.1.tar.gz
Size 11.4 kB
Tags Source
SHA-256 checksum
How to use checksums
e5cb4f9f5b30f5af52610392e21148e5d4e5cd2e7245ac32b318c71d5dacc677
BLAKE2b-256 checksum
How to use checksums
d87ee145ee7f3da1c2a9ca50f7cf28dc6bb708f2b05337b4b2659be44d15522a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.14

Release files / oro_g2p-0.1.1-py3-none-any.whl

Download URL oro_g2p-0.1.1-py3-none-any.whl
Size 10.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
aaaee0713b729a33f283963a53574a5d4d6b2c2c722536b9dff49ac6b53630b4
BLAKE2b-256 checksum
How to use checksums
83c023837667e55c5e610eccfda2f532cdd0c0719ede9242def32c05a1992766
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.14

Security for oro-g2p 0.1.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page