README.md

---
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:

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

## Setup

```powershell
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.

```powershell
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

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

## Train

```powershell
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

```powershell
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:

```powershell
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.