Mezna-TTS-82M

🗣️ Mezna-TTS-82M

Emirati (UAE) Arabic text-to-speech — Kokoro-82M fine-tuned for the Gulf/Emirati dialect, with a single natural female voice: Mezna 🌙

Status: repo scaffold + Emirati frontend complete and tested (18/18 pytest). Native-voice samples below use the ar-AE stand-in voice; Mezna's own fine-tuned weights (kokoro_mezna_82M.pth) land after the training run — see Training.

---

✨ Features

• 🇦🇪 Emirati-first frontend — purpose-built G2P handling for UAE dialect (شو, وايد, عيل, يلس, أبغي, ريوق, مسيد, دياي, فريج, ميلس …)
• 📖 Extensible pronunciation lexicon — 68 seed entries in ar_lexicon.json, add surface_word: diacritized_form to fix new words
• ⚡ CPU real-time — Kokoro-82M (82M params, StyleTTS2 + ISTFTNet), RTF ≈ 0.15–0.34
• 📦 Long-text safe — automatic sentence chunking with phoneme-budget fitting and seamless concat (a 30s paragraph renders without crashes)
• 🔊 Two voice paths — offline Kokoro (inference.py) + native ar-AE voice (speak_edge.py) until fine-tuned weights land
• ✅ Tested — 18 pytest cases pinning frontend, chunking, and wiring
• 🖥️ Gradio demo — app.py with 5 one-click Emirati examples

---

🎧 Samples

Native Emirati female voice (ar-AE-FatimaNeural, 24 kHz mono wav). Click any file to play it on GitHub:

Total: ~25s of Emirati speech covering greetings, questions, shopping, majlis plans, and Bedouin-origin vocabulary (دياي, فريج).

---

🚀 Quickstart

# 1. Environment (system pip is often locked — venv recommended)
python3 -m venv .venv && ./.venv/bin/pip install -r requirements.txt
# NOTE (Python 3.14): install misaki without build deps first:
#   ./.venv/bin/pip install --no-deps misaki && ./.venv/bin/pip install spacy

# 2. Native ar-AE voice (needs network) — works TODAY
./.venv/bin/python speak_edge.py "هلا، شحالج؟ شو مسوية اليوم؟" --out out.wav
./.venv/bin/python speak_edge.py --text "..." --out out.mp3 \
    --voice ar-AE-HamdanNeural   # male voice option

# 3. Offline Kokoro path (needs fine-tuned weights — see Training)
./.venv/bin/python voices/make_voice.py   # placeholder pack pre-training
./.venv/bin/python inference.py "هلا، شحالج؟ اليوم الجو وايد زين؟" --out mezna_out.wav

# 4. Tests + demo
./.venv/bin/python -m pytest tests/ -q   # 18 passed
./.venv/bin/python app.py                # Gradio UI (needs: pip install gradio)

---

💡 Use-cases

---

🧠 How it works

Text → audio in 4 stages:

Arabic text
  │  1. NORMALIZE (mezna_frontend.normalize_text)
  │     • ،؛؟ → ,;?  • lexicon: شو→شُو, أبغي→أَبْغي
  │     • ال-prefix fallback: الدكان→الدُكّان  • OOV ة→ه
  ▼
Normalized text
  │  2. PHONEMIZE (espeak-ng 'ar' via misaki EspeakG2P)
  │     هلا → hˈalaː   (bundled dylib, no system install needed)
  ▼
IPA phonemes
  │  3. REMAP (remap_phonemes — Kokoro's 178-token vocab)
  │     ħ→ʰ  ʕ→ʁ  ˤ→ᵊ  ̪→∅
  ▼
Model phonemes
  │  4. SYNTHESIZE (KModel: StyleTTS2 + ISTFTNet, 24 kHz)
  │     voice [510,1,256] indexed by phoneme length, per KPipeline
  ▼
🔊 mezna_out.wav

---

🦙 Ollama (chat brain + Mezna voice)

Ollama runs text LLMs, not TTS voices — so Mezna on Ollama is a split setup: an Ollama model does the talking (Emirati persona), chat_voice.py voices it.

ollama create mezna -f Modelfile   # Emirati persona over a local Arabic LLM
python chat_voice.py "شحالج؟ شو تنصحيني أسوي اليوم في دبي؟" --out reply.wav
# -> Mezna: <reply text> + reply.wav in the ar-AE female voice

To upgrade the brain, change one line in Modelfile (FROM wamda-3b:latest → e.g. FROM qwen3:8b) and re-run ollama create.

---

📁 Project structure

---

🏋️ Training

1. Base: hexgrad/Kokoro-82M, patched StyleTTS2 recipe.
2. Data: single female Emirati speaker, 16–24 kHz clean audio, ~5–20h. Transcripts in Emirati orthography (keep چ, گ where spoken; spell numbers out).
3. Normalize transcripts with mezna_frontend.normalize_text; extend ar_lexicon.json with surface: diacritized fixes as G2P errors appear.
4. Fine-tune KModel; mean-pool style embeddings → voices/mezna.pt.
5. Validate on greetings, market/majlis sentences, ق→/g/ and ج→/y/ words (دياي, فريج), and ؟ question intonation.

---

⚠️ Limitations

• Numbers/dates/times fall back to espeak MSA expansion — spell numbers out (a dialect number normalizer is planned).
• Single voice (Mezna). Lexicon is seed-size and community-extensible.
• speak_edge.py needs network access to the Edge TTS service.
• Base Kokoro voices have no Arabic training — the offline path only sounds Emirati after fine-tuning.

---

🤝 Contributing

• Add lexicon entries: surface_word: diacritized_form in ar_lexicon.json (e.g. hear a mispronunciation → fix it → add a pytest case in tests/test_frontend.py).
• Run ./.venv/bin/python -m pytest tests/ -q before every PR — keep 18/18 green.

📜 Credits & License

• Fine-tuned from hexgrad/Kokoro-82M (patched StyleTTS2 recipe).
• Native-voice samples via Microsoft Edge TTS ar-AE voices.
• License: Apache-2.0 — commercial use allowed. Replace the stand-in voice with Mezna's fine-tuned pack before shipping a product voice.