hifzguide-muaalem-mini
A size-distilled, teacher-initialised student of the Muaalem Quran phoneme-recognition model, built for real-time, on-device Quran recitation-checking applications, as part of HifzGuide.
| Architecture | Student | Teacher: obadx/muaalem-model-v3_2 |
|---|---|---|
| Backbone | Wav2Vec2-BERT | Wav2Vec2-BERT |
| Parameters | 116,318,635 | ~605,754,251 |
| Encoder layers | 24 | 24 |
hidden_size | 448 | 1024 |
| CTC heads | phonemes only | Phoneme identity + 10 sifat attributes |
| Positional encoding | Rotary | relative_key |
The student reduces width only: intermediate_size=1792,
num_attention_heads=7. It decodes only phonemes:
43 CTC classes, with id 0 as blank/pad. The teacher's one-layer,
stride-2 adapter topology preserves the frame-rate contract
(250, 160) -> (125, 43);
adapter weights necessarily differ with hidden size.
Loading
The custom Wav2Vec2BertForMultilevelCTC architecture is vendored verbatim from
MIT-licensed obadx/quran-muaalem.
Load with trust_remote_code=True; phoneme_vocab.json maps ids to characters.
Greedy decoding collapses repeats and drops blank/pad:
import json
import torch
from huggingface_hub import hf_hub_download
from transformers import AutoModel, AutoFeatureExtractor
repo_id = "sysofwan/hifzguide-muaalem-mini"
model = AutoModel.from_pretrained(repo_id, trust_remote_code=True).eval()
feature_extractor = AutoFeatureExtractor.from_pretrained(repo_id)
waveform = ... # 16 kHz mono float32 numpy array of real audio
inputs = feature_extractor(waveform, sampling_rate=16000, return_tensors="pt")
with torch.no_grad():
logits = model(**inputs).logits["phonemes"] # (1, num_frames, 43)
vocab_path = hf_hub_download(repo_id, "phoneme_vocab.json")
id_to_char = json.load(open(vocab_path))["id_to_char"]
ids, prev, decoded = logits.argmax(dim=-1)[0].tolist(), None, []
for i in ids:
if i != prev and i != 0: # collapse repeats, drop the CTC blank
decoded.append(id_to_char[i])
prev = i
print("".join(decoded))
SeamlessM4TFeatureExtractor produces slightly fewer than 250 frames
from 5 s of audio; the fixed (250, 160)
training/evaluation window comes from HifzGuide's own mel front-end
(mel_filters.bin/window.bin), not raw feature-extractor output.
CoreML export was numerically verified (bit-exact trace); the single-chunk Apple Neural Engine load path was confirmed working on-device at deployment.
Accuracy: teacher decode agreement
Teacher/student greedy CTC decodes are compared character-by-character, reporting pooled accuracy with reciter-clustered 95% CIs (not scored against an independent reference transcript).
| Split | Accuracy | 95% CI | Clips | Reciters |
|---|---|---|---|---|
| dev | 94.87% | [94.47, 95.20] | 970 | 146 |
| test | 94.97% | [94.63, 95.27] | 1,030 | 140 |
License
Weights, configuration and this README are AGPL-3.0 (LICENSE), matching HifzGuide.
The vendored architecture and model lineage from obadx/muaalem-model-v3_2 and
facebook/w2v-bert-2.0 retain their original MIT terms, which permit relicensing
the combined work.
Training audio: FaisaI/tadabur,
CC BY-NC 4.0 (research/educational use; attribution required). AGPL-3.0 governs this
repository's own contents, not the corpus. Before commercial use of these weights,
independently assess how the corpus's non-commercial term applies.
Training
- Objective: frame-weighted KL divergence between student/teacher phoneme posteriors, up-weighting non-blank and confirmed-region frames. No CTC loss, hard-label/decode targets or transcripts: only teacher soft outputs.
- Recipe: teacher-initialised (
teacher_init --qk damp); 40,000 streamed optimizer steps; batch 32; WSD schedule (1,000-step warmup / hold / 4,000-step cooldown); peak lr 1e-4; EMA decay 0.999. ~11.5 h on one RTX 5060 Ti (16 GB). - Architecture choices: training-free depth reduction destroyed the backbone, so
all 24 layers remain. Rotary is deliberate: students are trained from random init
and need not copy the teacher's positional scheme;
relative_keyembeds a large per-layer position constant in traced graphs, mainly costing on-device export, not accuracy.
Limitations
- Trained to imitate the teacher, not independent ground-truth transcription; evaluated only against teacher decodes. Output approximates the teacher, not a validated standalone phoneme-recognition result.
- Evaluation covers only
FaisaI/tadabur-distribution audio; other recording conditions, reciting styles and dialects are untested. - Phoneme identity only: no sifat/tajweed-attribute heads or suitability for tajweed-attribute judgments.
- Evaluation uses one fixed window position. Teacher self-agreement varies by tens of points across positions: headline accuracy compares checkpoints, not a bound on real-world transcription accuracy.
- Inherits teacher errors/biases; the teacher's model card documents no bias evaluation.
Notices and citations
See NOTICE.md for full upstream notices and the Muaalem paper and Tadabur dataset citations.