Whisper Quran v1 — Arabic Quranic Speech Recognition

The first open-source, production-tested Whisper Large-v3 model fine-tuned specifically for Quran recitation.

Fine-tuned on professional recitations from 5 world-renowned Qurʾān reciters, achieving 5.35% WER on held-out evaluation data. Tested across 19 reciters (including 14 completely unseen) with strong generalization. Deployed and validated in a real-time verse-tracking system on smart glasses.

Key Results

What Makes This Model Different

Training Details

Reciters (Phase 1)

This covers Gulf, Saudi Haramain, and Egyptian classical styles — the three dominant recitation traditions worldwide.

Training Configuration

WER Progression

The oscillation between checkpoints is due to the small evaluation set (115 samples). Both 3,500 and 4,500 are strong models.

Cross-Reciter Evaluation (19 Reciters)

Tested on 10 ayahs per reciter spanning short, medium, and long verses. Reciters marked with ✅ were in the training set; all others are completely unseen.

Trained Reciters (5)

Unseen Reciters (14) — Zero-Shot Generalization

Key finding: Ayman Sowaid (who recites like an average person, not a professional) scored near-perfect — this confirms the model works for everyday reciters, not just professionals.

Long ayah drift is expected and is solved in production by chunking audio into 10-second windows.

Live Production Results

This model has been deployed in a real-time Quran verse tracking system running on G2 smart glasses. The pipeline processes 10-second audio chunks through Whisper, then matches output against all 6,236 Quran ayahs using Token F1 + IDF-weighted scoring.

Real-Time Matching Scores (Live Recitation)

Example from live log:

Whisper: "فَبِأَيِّ آلَاءِ رَبِّكُمَا تُكَذِّبَانِ"
Match:   [55:13] score=1.00 F1=1.00 IDF=1.00 coverage=100%

The 10-second chunking eliminates the long-ayah drift problem entirely — every chunk contains 5-15 words, which is the model's sweet spot.

Usage

Hugging Face Inference Endpoint (custom handler, recommended)

This repo now includes a custom handler.py for HF Inference Endpoints that supports:

• micro-batching concurrent requests on one GPU worker
• low-latency queue window (ASR_BATCH_WINDOW_MS)
• bounded batching (ASR_MAX_BATCH_SIZE)
• output shape compatible with clients expecting { text, chunks }

Endpoint configuration

Set your endpoint to use this repository revision and custom handler.

Optional environment variables:

The handler accepts raw audio/wav bytes or JSON payloads with:

• inputs (base64/string/bytes audio), and optional
• parameters (language, task, return_timestamps, chunk_length_s, temperature)

Basic Transcription

from transformers import pipeline

pipe = pipeline(
    "automatic-speech-recognition",
    model="wasimlhr/whisper-quran-v1",
    device=0  # GPU, or -1 for CPU
)

result = pipe(
    "recitation.wav",
    generate_kwargs={"language": "ar", "task": "transcribe"}
)
print(result["text"])

From Audio Array (No ffmpeg Required)

import librosa

audio, sr = librosa.load("recitation.wav", sr=16000)
result = pipe(
    {"array": audio, "sampling_rate": 16000},
    generate_kwargs={"language": "ar", "task": "transcribe"}
)
print(result["text"])

Direct Model Usage (Full Control)

import torch
import librosa
from transformers import WhisperProcessor, WhisperForConditionalGeneration

processor = WhisperProcessor.from_pretrained("wasimlhr/whisper-quran-v1")
model = WhisperForConditionalGeneration.from_pretrained(
    "wasimlhr/whisper-quran-v1",
    torch_dtype=torch.float16
).to("cuda")

audio, sr = librosa.load("recitation.wav", sr=16000)
inputs = processor(audio, sampling_rate=16000, return_tensors="pt")
input_features = inputs.input_features.to("cuda").half()

with torch.no_grad():
    predicted_ids = model.generate(
        input_features,
        language="ar",
        task="transcribe",
    )

text = processor.batch_decode(predicted_ids, skip_special_tokens=True)[0]
print(text)

Production Chunking (Recommended)

For real-time applications, send audio in 5-10 second chunks rather than full recordings. This eliminates long-ayah drift and keeps transcription in the model's optimal accuracy range:

import numpy as np

CHUNK_SECONDS = 10
SAMPLE_RATE = 16000

audio, sr = librosa.load("long_recitation.wav", sr=SAMPLE_RATE)
chunks = [
    audio[i:i + CHUNK_SECONDS * SAMPLE_RATE]
    for i in range(0, len(audio), CHUNK_SECONDS * SAMPLE_RATE)
]

for i, chunk in enumerate(chunks):
    result = pipe(
        {"array": chunk, "sampling_rate": SAMPLE_RATE},
        generate_kwargs={"language": "ar", "task": "transcribe"}
    )
    print(f"Chunk {i}: {result['text']}")

Known Limitations

1. Long ayahs (20+ words): Transcription drifts after ~15 words when processing full-length audio. Solved by chunking in production.

2. Systematic training artifact: The phrase "وَإِيَّاكَ نَسْتَعِينُ" (Fatiha 1:5) consistently outputs as "وَإِنَّيِّيكَنَ اسْتَعِينِ" across all reciters — a known training artifact.

3. Diacritics: The model sometimes produces slightly incorrect tashkeel (vowel marks). The core consonantal text is almost always correct, which is sufficient for verse identification.

4. Non-Quran audio: The model is specialized for Quran recitation. General Arabic speech will produce poor results. Whisper's hallucination tokens ("شكرا", "موسيقى") appear on non-speech audio.

5. Single Qira'a: Trained primarily on Hafs 'an 'Asim readings. Warsh, Qalun, and other qira'at are not specifically covered.

Deployment Options

Citation

@misc{whisper-quran-v1,
  title={Whisper Quran v1: Fine-tuned Whisper Large-v3 for Quranic Arabic Speech Recognition},
  author={Abdul Rahman Nasim},
  year={2026},
  url={https://huggingface.co/wasimlhr/whisper-quran-v1},
  note={Fine-tuned on Buraaq/quran-md-ayahs dataset}
}

@article{radford2022whisper,
  title={Robust speech recognition via large-scale weak supervision},
  author={Radford, Alec and Kim, Jong Wook and Xu, Tao and Brockman, Greg and McLeavey, Christine and Sutskever, Ilya},
  journal={arXiv preprint arXiv:2212.04356},
  year={2022}
}

Acknowledgments

• OpenAI for the Whisper architecture and pre-trained weights
• Buraaq for the comprehensive ayah-level Quran recitation dataset
• The Quran reciter community for preserving and sharing these recordings

License

This project and the fine-tuned Whisper model (wasimlhr/whisper-quran-v1) are free for personal, educational, and non-commercial use only. This includes mosques, madaris, Islamic schools, and non-profit organizations. Commercial use is strictly prohibited without prior written permission. This applies to the model weights, the application code, and any derivative works. For commercial licensing inquiries, contact via GitHub: wasimlhr/taraweeh-companion-g2