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.2

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.2
File Size Uploaded Provenance Actions
oro_g2p-0.1.2.tar.gz 11.9 kB Without provenance Details for oro_g2p-0.1.2.tar.gz

Built distribution (wheel)

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

Total release size: 22.4 kB

Release files / oro_g2p-0.1.2.tar.gz

Download URL oro_g2p-0.1.2.tar.gz
Size 11.9 kB
Tags Source
SHA-256 checksum
How to use checksums
b03fa561a40d2de8036fb666d0ed69b99823742ae53a5b0f1f44ab76c440455b
BLAKE2b-256 checksum
How to use checksums
55f8c461f6416f7d5e452261ca251b767131cebf82f6000f380faebb2a9732a7
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.2-py3-none-any.whl

Download URL oro_g2p-0.1.2-py3-none-any.whl
Size 10.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
5e2a06d36c33b5779f8c19e7709e2ac2fa5cf16337fa7cf7bb9873edd47ec43f
BLAKE2b-256 checksum
How to use checksums
9c9ca9df676b88fd81f85286837399deeb4b5cf03a130e782b243ad0f35789df
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.2

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