README.md

metadata

title: Quran Reciter Identification
emoji: 🎙️
colorFrom: green
colorTo: blue
sdk: gradio
sdk_version: 5.49.1
app_file: app.py
python_version: '3.11'
suggested_hardware: cpu-basic

Quran Reciter Identification

Identify Quran reciters from short unknown audio clips using a strong pretrained speaker-recognition backbone.

Approach

This project uses speechbrain/spkrec-ecapa-voxceleb as the default embedding model. ECAPA-TDNN is a proven speaker-recognition architecture, and the SpeechBrain checkpoint is trained on VoxCeleb1+VoxCeleb2. The local classifier is trained on Quran reciter embeddings, so training is fast enough for a moderate laptop dataset while still using a deep speaker model.

Recommended dataset:

• Buraaq/quran-md-ayahs on Hugging Face: 187,080 verse-level clips, 30 reciters, complete Quran coverage, about 450+ hours.

The code also supports any folder dataset shaped like:

data/raw/
  alafasy/
    clip001.mp3
    clip002.wav
  abdul_basit/
    clip001.mp3

Setup

python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
pip install -e .

Install FFmpeg if your audio files are MP3 and torchaudio cannot decode them on your machine.

Build a Moderate Quran-MD Dataset

This exports a balanced subset from Hugging Face into local WAV clips and a manifest. The default keeps all 30 reciters and about 500 ayahs per reciter, spread across train/validation/test surah ranges.

python -m quran_reciter_id.export_quran_md `
  --output-dir data/quran_md `
  --max-samples-per-reciter 500

For a larger run, increase --max-samples-per-reciter; use 0 for the full dataset.

Build a Manifest from Local Folders

python -m quran_reciter_id.build_manifest `
  --audio-root data/raw `
  --output data/manifests/local.jsonl

Train

python -m quran_reciter_id.train `
  --manifest data/quran_md/manifest.jsonl `
  --output-dir runs/ecapa_quran_md

Training saves:

• model.pt: classifier head and normalization stats
• labels.json: reciter labels
• metrics.json: validation/test metrics
• embeddings/*.npz: cached ECAPA embeddings

Predict an Unknown Reciter

python -m quran_reciter_id.predict `
  --run-dir runs/ecapa_quran_md `
  --audio-file path\to\unknown_recitation.mp3 `
  --top-k 5

The predictor returns top candidates, probabilities, and a centroid similarity score. If confidence is below --unknown-threshold, it reports the clip as unknown/out-of-distribution.

Test in the Browser

Launch the Gradio interface to upload audio or record from a microphone:

python gradio_app.py

Choose the checkpoint directory and device in the interface. Browser microphone access requires localhost or an HTTPS connection.

Notes

• Split by surah when possible. That prevents the model from memorizing a specific verse recording pattern instead of the reciter voice.
• A 30-reciter Quran-MD subset is the best practical starting point today. If a directly downloadable Tadabur release becomes available, use build_manifest.py after arranging audio by reciter folder.
• For production, use longer clips when possible. A 10-30 second recitation generally gives more stable speaker embeddings than a very short ayah.