README.md

---
license: apache-2.0
language:
- ar
pipeline_tag: text-to-speech
library_name: kokoro
base_model: oddadmix/Nabra-82M-v0.1
base_model_relation: finetune
tags:
- text-to-speech
- tts
- arabic
- egyptian-arabic
- masri
- dialect
- speech-synthesis
- kokoro
widget:
- text: "أَنَا بَحِبّ الْأَكْل الْمَصْرِي أَوِي، وِمَامْتِي بِتِعْمِل مَحْشِي وِمُلُوخِيَّة كُلّ يُوم جُمْعَة، وِالطَّعْم بِتَاعْهَا مَفِيش زَيُّه فِي الدُّنْيَا، وِكُلّ الْعِيلَة بِتِتْجَمَّع عَلَى السُّفْرَة وِنِفْضَل نِتْكَلِّم وِنِضْحَك لِحَدّ مَا الْأَكْل يِخْلَص، وِبَعْد الْغَدَا بِنِشْرَب شَاي وِنِقْعُد مَع بَعْض شْوَيَّة."
  example_title: Food and family
  output:
    url: samples/voice-notes/voice-note-01-food.wav
- text: "كُلّ يُوم الصُّبْح بِفْتَح الشُّبَّاك عَشَان أَشُوف الدُّنْيَا بَرَّه، وِبَعْد كِدَه بِعْمِل كُوبَايِة شَاي وِآكُل لُقْمَة خَفِيفَة، وِبِقْعُد شْوَيَّة أَفْتَكِر اللِّي وَرَايَا، عَشَان أَبْدَأ يَوْمِي بِهُدُوء وِأَخَلَّص شُغْلِي فِي مِعَادُه، وِبَعْد الْعَصْر بِنْزِل أَلُفّ شْوَيَّة فِي الشَّارِع وِبَرُوح الْبِيت قَبْل الْمَغْرِب، وِبِاللِّيل بِقْعُد مَع أَهْلِي."
  example_title: Morning routine
  output:
    url: samples/voice-notes/voice-note-02-morning.wav
- text: "إِمْبَارِح رُوحْت وَسْط الْبَلَد مَعَ صَاحْبِي، وِاتْفَرَّجْنَا عَلَى الْمَحَلَّات الْقَدِيمَة، وِرِجِعْنَا بِاللِّيل عَلَى الْبِيت تَعْبَانِين خَالِص بَسّ مَبْسُوطِين، وِاتَّفَقْنَا إِنَّنَا نِرْجَع تَانِي الْأُسْبُوع الْجَاي عَشَان نِشُوف بَاقِي الْمَحَلَّات، وِنِقْعُد عَلَى النِّيل وِنِشْرَب حَاجَة بَارْدَة، وِنِرْجَع الْبِيت بِاللِّيل."
  example_title: A day in Cairo
  output:
    url: samples/voice-notes/voice-note-03-cairo.wav
---

<div align="center">
  <img src="assets/logo-card.png" alt="KemeTone" width="460">

  ### Egyptian Arabic that sounds Egyptian.

  **82M parameters · 24 kHz · female voice · runs on a CPU**

  <sub>A fine-tune of <a href="https://huggingface.co/oddadmix/Nabra-82M-v0.1">Nabra-82M</a>, itself built on <a href="https://huggingface.co/hexgrad/Kokoro-82M">Kokoro-82M</a>.</sub>
</div>

---

## Voice samples

**Food and family · 16 seconds**

<audio controls src="https://huggingface.co/Rabe3/kemetone/resolve/main/samples/voice-notes/voice-note-01-food.wav"></audio>

**Morning routine · 17.5 seconds**

<audio controls src="https://huggingface.co/Rabe3/kemetone/resolve/main/samples/voice-notes/voice-note-02-morning.wav"></audio>

**A day in Cairo · 15.8 seconds**

<audio controls src="https://huggingface.co/Rabe3/kemetone/resolve/main/samples/voice-notes/voice-note-03-cairo.wav"></audio>

All three are single-pass 24 kHz generations. Exact diacritized transcripts
and Cohere Transcribe Arabic checks are in
[`samples/voice-notes/metadata.json`](samples/voice-notes/metadata.json).

---

## The problem with Arabic TTS

Almost every Arabic voice you can buy or download speaks **Modern Standard
Arabic** — the language of news broadcasts and textbooks. Roughly no one speaks
it at home.

Point one of those models at Egyptian text and it does not fail loudly. It
fails *politely*: it reads your words with textbook consonants and textbook
vowels, and the result lands somewhere between a newsreader and a foreigner.
`جَمِيل` comes out **/ʤamiːl/** when a hundred million people say **/ɡamiːl/**.
`دِلْوَقْتِي` comes out **/dilwaqti/** when the street says **/dilwaʔti/**.

KemeTone is built for the dialect, not adapted to it.

| | Standard Arabic TTS | **KemeTone** |
|---|---|---|
| ج | /ʤ/ — *gemeel* | **/ɡ/ — *gameel*** |
| ق | /q/ — *dilwaqti* | **/ʔ/ — *dilwa'ti*** |
| ث | /θ/ — *thalatha* | **/t/ — *talata*** |
| ذ | /ð/ — *dhahab* | **/z/ — *zahab*** |
| ظ | /ðˤ/ | **/zˤ/** |
| Register | broadcast | **conversational** |

And it does this without becoming naive about it. Egyptians do not flatten
*every* ق to a glottal stop — `الْقُرْآن` keeps its /q/, `ثَقَافَة` keeps its
/s/, and a model that applies the rule everywhere sounds like a caricature.
KemeTone ships curated exception lexicons for exactly the learned and Qur'anic
vocabulary that resists the shift, so the rules fire where a Cairene speaker
fires them and stay quiet where they don't.

## Listen for

- **A natural female voice**, warm and conversational — not a formal announcer.
- **Long-form in a single pass.** 15–20 seconds of continuous speech with
  coherent phrasing, no chunk-and-stitch seams.
- **Correct dialect consonants**, with the learned-vocabulary exceptions intact.
- **ع and ح that are actually pronounced** — the two pharyngeals that
  general-purpose phonemisers silently drop.

## Quick start

```bash
pip install -r requirements.txt
```

You also need **espeak-ng** available to the phonemiser
(`apt install espeak-ng`, `brew install espeak-ng`, or set
`KEMETONE_ESPEAK_LIB` to a build of `libespeak-ng.so`).

```python
import torch, soundfile as sf
from kokoro import KModel
from kemetone import EgyptianG2P

model = KModel(repo_id="Rabe3/kemetone",
               config="config.json", model="kemetone.pth").eval()
voice = torch.load("voices/kemetone.pt")

ipa = EgyptianG2P()("النَّهَارْدَه الْجَوّ حِلْو أَوِي")
audio = model(ipa, voice[len(ipa) - 1])

sf.write("out.wav", audio.numpy(), 24000)
```

Or straight from the command line:

```bash
python example.py "النَّهَارْدَه الْجَوّ حِلْو أَوِي" out.wav
```

### Give it diacritics

Arabic script does not write short vowels. When they are missing, the
phonemiser has to guess them — and it guesses the **Standard Arabic** way,
which is precisely the accent KemeTone exists to avoid. The consonants will
still be Egyptian; the vowels will not.

```
حلو            →  vowels guessed, MSA-flavoured
حِلْو           →  vowels read from the text  ✓
```

Undiacritized input works and is often acceptable. Diacritized input is
noticeably better. If your text is bare, run it through an Arabic diacritizer
first — the quality gain is larger than anything else you can do at inference
time.

## Specifications

| | |
|---|---|
| Architecture | StyleTTS2 / Kokoro (ISTFTNet decoder) |
| Parameters | 81.8 M |
| Sample rate | 24 kHz mono |
| Voice | single female speaker |
| Language | Egyptian (Cairene) Arabic |
| Input | diacritized Arabic text |
| Weights | `kemetone.pth` (327 MB, fp32) |
| Voice embedding | `voices/kemetone.pt` |
| Hardware | CPU or any CUDA GPU; ~300 MB of VRAM |
| Licence | Apache 2.0 |

### What ships here

```
kemetone.pth          model weights
config.json           architecture + 178-symbol vocabulary
voices/kemetone.pt    the voice embedding
kemetone/             Egyptian G2P front-end and its exception lexicons
example.py            end-to-end synthesis
```

The front-end is part of the model, not a convenience wrapper. The weights were
trained on the phoneme strings this G2P produces; feeding them phonemes from a
generic Arabic phonemiser will degrade output in ways that are subtle enough to
miss and consistent enough to matter.

## Limitations

- **One voice.** No multi-speaker support, no voice cloning, no style prompts.
- **Cairene.** Not Sa'idi, not Alexandrian, and not any other Arabic dialect.
- **Diacritics carry the vowels.** See above.
- **Latin script, digits, and code-switched English** are not handled — convert
  numbers to Arabic words before synthesis.
- **Very long inputs** must be split at sentence boundaries; the context window
  is 510 tokens.
- Emotional range is conversational-neutral. There is no shouting, whispering,
  or singing in this model.

## Responsible use

This voice is modelled on a real person. Please treat it accordingly:

- **Do not** use it to impersonate anyone, to put words in a real person's
  mouth, or to produce audio that a listener could mistake for a genuine
  recording of someone.
- **Do not** use it for fraud, harassment, political disinformation, or to
  defeat voice-based authentication.
- **Do** disclose synthetic speech when the audience might otherwise assume it
  is human — accessibility tools, narration, learning material, and assistants
  are all better with a label on them.

Downstream users are responsible for complying with the laws on synthetic media
and personality rights in their own jurisdiction.

## Licence and credits

Released under **Apache 2.0**, inheriting the licence of the Kokoro
architecture it builds on.

Built on [Kokoro-82M](https://huggingface.co/hexgrad/Kokoro-82M) and
[Nabra-82M](https://huggingface.co/oddadmix/Nabra-82M-v0.1), with
phonemisation by [espeak-ng](https://github.com/espeak-ng/espeak-ng).

---

<div align="center">
  <sub><b>KemeTone</b> — from <i>Kemet</i>, the old name for Egypt: <i>the black land</i>.</sub>
</div>