Update README.md

README.md

@@ -1,3 +1,88 @@
----
-license: apache-2.0
----
+---
+license: apache-2.0
+datasets:
+- tarteel-ai/everyayah
+- MohamedRashad/Quran-Recitations
+- ahishamm/QURANICWhisperDataset
+language:
+- ar
+metrics:
+- wer
+base_model:
+- openai/whisper-large-v3-turbo
+pipeline_tag: automatic-speech-recognition
+library_name: transformers
+tags:
+- Quran
+- Tajweed
+- Recitation
+- Islam
+- Arabic
+- whisper
+- turbo
+---
+
+# Whisper Large v3 Turbo Quran (LoRA Fine-Tuned)
+
+This is a specialized **Automatic Speech Recognition (ASR)** model for **Quranic Recitation**. It is a fine-tuned version of [openai/whisper-large-v3-turbo](https://huggingface.co/openai/whisper-large-v3-turbo), optimized to recognize Quranic Arabic with high accuracy while maintaining exceptional inference speed.
+
+## Model Performance
+- **Word Error Rate (WER):** Achieved **12.69%** on the `ahishamm/QURANICWhisperDataset` test set.
+- **Accuracy:** The model demonstrates high precision in capturing Quranic vocabulary and standard Imla'i script nuances.
+
+## Architecture & Trade-offs
+This model utilizes the **Turbo** architecture, which reduces the decoder depth from 32 layers (in the standard Large v3) to **4 layers**. 
+
+- **Pros:** Extremely fast inference speed (significantly lower latency than Medium or Large v3).
+- **Cons:** Due to the reduced decoder depth, the model has less capacity for long-range context retention compared to the full Large model. This makes it slightly more prone to **hallucinations** and **repetition loops** (e.g., repeating a word during silence) if not configured correctly during inference.
+
+**Recommendation:** This model is ideal for **Live Transcription** or applications where low latency is critical. For offline batch processing where speed is not a priority, a full Large-v3 model may offer slightly higher semantic stability on very long verses.
+
+## Training Details
+The model was trained using **LoRA (Low-Rank Adaptation)** in a multi-stage curriculum learning process to ensure stability and precision.
+
+### Datasets
+The training and evaluation process utilized a comprehensive mix of professional recitations:
+1.  **Training & Validation:**
+    - [tarteel-ai/everyayah](https://huggingface.co/datasets/tarteel-ai/everyayah)
+    - [MohamedRashad/Quran-Recitations](https://huggingface.co/datasets/MohamedRashad/Quran-Recitations)
+2.  **Testing:**
+    - [ahishamm/QURANICWhisperDataset](https://huggingface.co/datasets/ahishamm/QURANICWhisperDataset) (Used for final WER calculation).
+
+### Methodology
+- **Curriculum Learning:** The model was trained gradually across these datasets to refine its understanding of Tajweed and Quranic sentence structures.
+- **Data Augmentation:** To ensure the model remains robust against real-world conditions (non-studio microphones, background noise, varying volumes), diverse audio augmentations (gain adjustments, spectral masking and white noise) were applied during the training process.
+
+## Usage
+
+This model is fully compatible with the Hugging Face `transformers` pipeline. 
+
+**CRITICAL NOTE ON INFERENCE:**
+Due to the Turbo architecture's reduced decoder depth, you must carefully control the `stride_length_s` parameter. A long stride (e.g., 4s or more) can cause the model to lose context and enter infinite repetition loops. **It is strongly recommended to keep the stride length to 2 seconds.**
+
+```python
+from transformers import pipeline
+
+# Load the pipeline
+pipe = pipeline(
+    "automatic-speech-recognition",
+    model="YourUsername/whisper-l-v3-turbo-quran-lora", # Replace with your model ID
+    device=0 # for GPU usage, -1 for CPU
+)
+
+# Transcribe audio 
+result = pipe(
+    "path_to_audio.mp3",
+    chunk_length_s=30, 
+    stride_length_s=2, # Keep this at 2s to prevent loops and hallucinations
+    batch_size=8,
+    return_timestamps=True,
+    generate_kwargs={
+        "task": "transcribe",
+        "language": "arabic",
+        "temperature": 0.0,      # Greedy decoding, recommended for stability
+        "num_beams": 1           # 1 is sufficient, adjust as needed
+    }
+)
+
+print(result["text"])