Mathani-Ayat/qalon-reciter

Qaloon Quran Reciter — two Whisper Base variants

Recommended: models/full-finetuning. It is a complete Whisper Base model. Runner-up: models/base-lora-v2. It is a LoRA adapter and needs openai/whisper-base; it is not a standalone full model.

Repository visibility: private (unchanged). This is a Qālūn ʿan Nāfiʿ research model for al-Fātiḥah and surahs 78–114, not a trained full-Quran or tajweed assessment model.

Current saved metrics

Recomputed from each run's saved reference/prediction files and verified against its own metrics.json. These are not new evaluations and not model probabilities. WER/CER below are percentages; JSON files store fractions (0–1). Lower is better.

Variant	Test WER	Test CER	Validation WER	Validation CER
Full fine-tuning (gpu_base_full)	26.39%	7.96%	28.74%	7.20%
Base LoRA v2 (gpu_base_v2, rank 32)	31.15%	9.05%	33.02%	10.10%

Both models share the exact same saved 232 test and 188 validation examples: Dokali, Husary, Huthaify, and Waleed, 58 test / 47 validation clips per reciter. The dataset split used seed 42, with 1,851 training clips; four Husary clips over 30 seconds were excluded. Fātiḥah is grouped across reciters into one partition. Scores use the project's unvowelled Qālūn normalization and greedy Arabic transcription; extra hamza-folded diagnostics are not substituted for these primary scores. See each folder's metrics.json for per-reciter results.

The second-best comparable earlier Base adapter (gpu_base) had test WER 33.23%, CER 9.56%; gpu_base_v2 is the selected runner-up by saved WER. This selection used existing test results for this release, not an untouched future deployment benchmark.

Quick start — one command per model

Install Python dependencies (use a CUDA-compatible Torch/Torchaudio pair for GPU):

pip install torch torchaudio "transformers==4.57.6" "peft==0.21.1" "huggingface_hub>=0.36,<1" soundfile numpy

If this private repository requires login:

python -c "from huggingface_hub import login; login()"

Download the small inference script:

python -c "from huggingface_hub import hf_hub_download; import shutil; shutil.copyfile(hf_hub_download('BadrSh/qalon-reciter', 'examples/transcribe.py'), 'transcribe.py')"

Run either model; needed files are downloaded and cached automatically:

python transcribe.py clip.wav --variant full-finetuning
python transcribe.py clip.wav --variant base-lora-v2

Use a WAV clip of at most 30 seconds. Stereo and other sample rates are converted to mono 16 kHz automatically. GPU is used when available; add --device cpu to force CPU. Longer recordings must be segmented first, not silently truncated. No expected ayah is injected into the decoder.

For reproducibility, add --revision <COMMIT_HASH> (the commit for this release is visible in the Hub commit history); main may change later.

Download only the model you want

from pathlib import Path
from huggingface_hub import snapshot_download

repo = "BadrSh/qalon-reciter"
variant = "full-finetuning"  # or "base-lora-v2"
snapshot = snapshot_download(repo, allow_patterns=[f"models/{variant}/*"])
model_folder = Path(snapshot) / "models" / variant
print(model_folder)

Load the full model in your own application

from transformers import WhisperProcessor, WhisperForConditionalGeneration

processor = WhisperProcessor.from_pretrained(str(model_folder))
model = WhisperForConditionalGeneration.from_pretrained(str(model_folder)).eval()

Load the second-best Base adapter

Use variant = "base-lora-v2" in the download block above, then:

from transformers import WhisperProcessor, WhisperForConditionalGeneration
from peft import PeftModel

processor = WhisperProcessor.from_pretrained(str(model_folder))
base = WhisperForConditionalGeneration.from_pretrained("openai/whisper-base")
model = PeftModel.from_pretrained(base, str(model_folder)).eval()

The ready-to-run script handles audio loading, feature extraction and generation for either format. Tokenizer/processor assets are included in each model folder.

Existing model preserved

The old root Whisper Tiny LoRA adapter was preserved, not deleted, in legacy/whisper-tiny-lora/, including its original README, metrics and provenance LICENSE. The pre-reorganization revision is 024d875a683d7d10736e79f44570ad179ec50f56 and still loads using the old root layout if pinned to that commit.

Its saved test WER/CER is 64.37% / 22.73%, validation 73.08% / 25.32%, on a different three-reciter, 180-test / 141-validation split. Do not compare those figures directly to the four-reciter Base results or attach the full model's metrics to this adapter. Load the archived adapter with:

python transcribe.py clip.wav --variant legacy-tiny-lora

Layout

models/full-finetuning/       # Complete weights + processor + original metrics
models/base-lora-v2/          # Base adapter + processor + original metrics
legacy/whisper-tiny-lora/     # Previously published model, preserved
examples/transcribe.py       # One quick inference command for all variants
metrics.json                 # Verified overall metrics for the new variants
release.json                 # File SHA256s, split hashes and source revision
LICENSE                      # Existing provenance terms, unchanged

Limits and provenance

• These metrics measure transcription on held-out ayah clips from known reciter voices, not generalization to unseen speakers or live student omission accuracy.
• False omission alerts, repetitions and substitutions are possible. This is a recognition aid, not a pronunciation/tajweed judgment or teacher replacement.
• Whisper's upstream base weights have their published Apache-2.0 terms. Existing repository LICENSE provenance restrictions remain unchanged; source-recording permissions and new derived-weight redistribution need their own review. No blanket public redistribution permission is inferred from this private release.
• No recordings, dataset rows, prediction transcripts, optimizer state, training checkpoints, tokens, signed URLs or credentials are included in this upload.

Project: https://github.com/BADR-DEEV/Ai-Reciter