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_key embeds 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.