README.md

---
language:
- ar
- en
license: apache-2.0
tags:
- text-to-speech
- tts
- audio
- speech
- palestinian-arabic
- arabic
- voice-cloning
- miratts
- sofelia
base_model: YatharthS/MiraTTS
library_name: transformers
pipeline_tag: text-to-speech
---

<div style="text-align: center;">
  <h1>🇵🇸 Sofelia-TTS 🇵🇸</h1>
  <p><strong>Palestinian Arabic Text-to-Speech Model</strong></p>
  <p><em>Palestine will be free</em> 🕊️</p>
  <p><img style="margin: auto; width: 500px" src="https://huggingface.co/hamdallah/Sofelia-TTS/resolve/main/Sofelia.png" /></p>
</div>

---

## 🌟 Model Description

**Sofelia-TTS** is a fine-tuned Text-to-Speech (TTS) model specifically trained for **Palestinian Arabic dialect**. This model brings the beautiful sounds of Palestinian speech to AI, preserving and celebrating the linguistic heritage of Palestine.

Built on top of [YatharthS/MiraTTS](https://huggingface.co/YatharthS/MiraTTS), Sofelia-TTS captures the unique phonetic characteristics, intonation patterns, and prosody of Palestinian Arabic, making it ideal for:

- 🎙️ **Voice cloning** with Palestinian Arabic speech
- 📚 **Audiobook generation** in Palestinian dialect
- 🗣️ **Virtual assistants** that speak authentic Palestinian Arabic
- 🎓 **Educational tools** for learning and preserving the Palestinian dialect
- 🎬 **Content creation** for Palestinian media and storytelling

> **Dedicated to Palestine**: This model is a tribute to the resilience, culture, and spirit of the Palestinian people. May their voices be heard loud and clear across the world. 🇵🇸

---

## 🎯 Key Features

- ✅ **High-quality voice cloning**: Clone any voice with just a few seconds of reference audio
- ✅ **Palestinian Arabic dialect**: Authentic pronunciation and intonation
- ✅ **Fast inference**: Optimized for real-time generation
- ✅ **Flexible context**: Supports variable-length reference audio
- ✅ **Open source**: Free to use and improve

---

## 📊 Model Details

| **Attribute** | **Value** |
|---------------|-----------|
| **Model Type** | Text-to-Speech (TTS) |
| **Base Model** | YatharthS/MiraTTS |
| **Architecture** | Transformer-based Language Model + Audio Codec |
| **Training Language** | Palestinian Arabic (ar-PS) |
| **Dataset** | Private Dataset |
| **Sample Rate** | 16,000 Hz |
| **License** | Apache 2.0 |
| **Model Size** | ~0.6B parameters |
| **Precision** | BF16/FP32 |
| **Framework** | PyTorch + Transformers |

---

## 🚀 Quick Start

### Installation

```bash
# Install required packages
uv pip install git+https://github.com/ysharma3501/MiraTTS.git
```

### Usage (Python)

```python
from mira.model import MiraTTS
from IPython.display import Audio
mira_tts = MiraTTS('hamdallah/Sofelia-TTS') ## downloads model from huggingface

file = "reference_file.wav" ## can be mp3/wav/ogg or anything that librosa supports
text = "مرحبا، كيف الحال؟ هذا نموذج للهجة الفلسطينية."

context_tokens = mira_tts.encode_audio(file)
audio = mira_tts.generate(text, context_tokens)

Audio(audio, rate=48000)
```

---

## 🎤 Example Prompts

Try these Palestinian Arabic phrases:

```python
# Greetings
"مرحبا، كيف حالك؟"  # Hello, how are you?
"أهلا وسهلا فيك"      # Welcome

# Common expressions
"يا سلام، هذا رائع"   # Wow, this is amazing
"ما شاء الله"         # Mashallah
"الله يعطيك العافية"  # God give you wellness

# About Palestine
"فلسطين حرة على طول"  # Palestine is free for ever
"القدس عاصمة فلسطين الأبدية"     # Jerusalem is the eternal capital of Palestine
"سنعود يوماً إلى ديارنا"         # We will return one day to our homes
```

---

## 🎓 Training Details

### Training Data

- **Dataset**: 400 Hours Palestinian Speech
- **Language**: Palestinian Arabic dialect
- **Hours of audio**: High-quality Palestinian speech recordings
- **Preprocessing**: Audio normalized and resampled to 16kHz

### Training Configuration

| **Hyperparameter** | **Value** |
|--------------------|-----------|
| **Learning Rate** | 2e-4 (initial), 1e-5 (refinement) |
| **Batch Size** | 8 (effective: 2 per device × 4 accumulation steps) |
| **Training Steps** | 2000+ |
| **Warmup Steps** | 100 |
| **Max Audio Length** | 20-30 seconds |
| **Optimizer** | AdamW |
| **LR Scheduler** | Cosine with warmup |
| **Gradient Clipping** | 1.0 |
| **Precision** | BF16 (H100) / FP32 |
| **Hardware** | NVIDIA H100 / A100 GPU |

### Training Process

The model was trained using a two-phase approach:

1. **Foundation Phase**: High learning rate (2e-4) for initial adaptation to Palestinian Arabic
2. **Refinement Phase**: Lower learning rate (1e-5) with NEFTune noise for stability and quality

---

## 📈 Model Performance

The model achieves:

- ✅ **Natural prosody** matching Palestinian Arabic speech patterns
- ✅ **Clear pronunciation** of Arabic phonemes
- ✅ **Voice similarity** to reference audio
- ✅ **Stable generation** without artifacts or repetitions
- ✅ **Fast inference** suitable for real-time applications

---

## 🛠️ Advanced Usage

### Running the model using batching

```python
file = "reference_file.wav" ## can be mp3/wav/ogg or anything that librosa supports
text = ["مرحبا، كيف حالك؟", "بتعرف إنه انا بقدر احكي فلسطيني و English مع بعض Without Errors."]

context_tokens = [mira_tts.encode_audio(file)]

audio = mira_tts.batch_generate(text, context_tokens)

Audio(audio, rate=48000)
```

### Adjusting Generation Parameters

```python
# More creative/variable output

mira_tts.set_params(
    top_p=0.95, 
    top_k=20, 
    temperature=0.01, # Higher = more variation
    max_new_tokens=1024, 
    repetition_penalty=2.2, 
    min_p=0.05
)

```

---

## 💡 Tips for Best Results

1. **Reference Audio Quality**:
   - Use clean audio without background noise
   - 3-10 seconds of speech is ideal
   - Ensure audio is 16kHz sample rate

2. **Text Input**:
   - Use proper Arabic script (not Arabizi/transliteration)
   - Palestinian dialect works best
   - Avoid very long sentences (split into shorter segments)

3. **Generation Parameters**:
   - `temperature=0.7`: Good default for natural speech
   - `temperature=0.5`: More stable, less variation
   - `temperature=0.9`: More expressive, more variation

---

## 🌍 About Palestinian Arabic

Palestinian Arabic is a Levantine Arabic dialect spoken by the Palestinian people. It has unique characteristics:

- **Phonology**: Preservation of Classical Arabic /q/ as glottal stop [ʔ]
- **Vocabulary**: Rich in Levantine and unique Palestinian terms
- **Intonation**: Distinctive melodic patterns
- **Regional Variants**: Urban (Jerusalem, Hebron) vs. Rural vs. Bedouin varieties

This model captures these linguistic features, making it authentic and representative of Palestinian speech.

---

## 🇵🇸 Message of Solidarity

This model is dedicated to the Palestinian people and their enduring struggle for freedom, dignity, and justice. Through technology, we preserve and celebrate Palestinian culture, language, and identity.

**Free Palestine** 🇵🇸

> *"We will not be erased. Our voices will echo through time, in every language model, every algorithm, every line of code. Palestine lives, and so does its voice."*

---

## 📜 License

This model is released under the **Apache 2.0 License**, making it free for:
- ✅ Commercial use
- ✅ Modification and distribution
- ✅ Private use
- ✅ Patent use

---

## 🙏 Acknowledgments

- **Base Model**: [YatharthS/MiraTTS](https://huggingface.co/YatharthS/MiraTTS) - Thank you for the excellent foundation
- **Dataset**: Palestinian Arabic speakers who contributed their voices
- **Community**: The open-source AI community for tools and support
- **Palestine**: For being the inspiration and purpose behind this work

---

## 📞 Contact & Support

- **Model Repository**: [hamdallah/Sofelia-TTS](https://huggingface.co/hamdallah/Sofelia-TTS)
- **Issues & Questions**: Use the Community tab or open an issue

---

## 🔗 Related Resources

- [YatharthS/MiraTTS](https://huggingface.co/YatharthS/MiraTTS) - Base model
- [ncodec](https://github.com/YatharthS/ncodec) - Audio codec library

---

## 📚 Citation

If you use this model in your research or projects, please cite:

```bibtex
@misc{sofelia-tts-2026,
  author = {Hamdallah},
  title = {Sofelia-TTS: Palestinian Arabic Text-to-Speech Model},
  year = {2026},
  publisher = {Hugging Face},
  journal = {Hugging Face Model Hub},
  howpublished = {\url{https://huggingface.co/hamdallah/Sofelia-TTS}},
}
```

---

<div style="text-align: center; padding: 20px;">
  <h2>🇵🇸 FREE PALESTINE 🇵🇸</h2>
  <p><strong>تحيا فلسطين حرة أبية</strong></p>
  <p><em>Long Live Free Palestine</em></p>
  <p>🕊️ ✊ 🇵🇸</p>
</div>

---

**Made with ❤️ for Palestine**