Munajjam

A Python library and API Server to synchronize Quran ayat with audio recitations.

Munajjam uses AI-powered speech recognition to automatically generate precise timestamps for each ayah in a Quran audio recording.

You can run Munajjam as a standalone API server with asynchronous processing and GPU support.

The easiest way to run the API server is using Docker Compose:

git clone https://github.com/Itqan-community/munajjam.git
cd munajjam

# To run with GPU support (default)
docker compose up --build

# To run with CPU only
docker compose -f docker-compose.yml -f docker-compose.cpu.yml up --build

Once the server is running (default: http://localhost:8000), you can use the following endpoints:

• POST /align/{surah_number}: Upload an audio file for a specific surah. Returns a job_id.
  • Form Data: file (audio file), riwaya (e.g., "hafs")
• GET /align/status/{job_id}: Check the status of the alignment job and get the results when ready.
• GET /health: Health check.

If you want to use Munajjam as a Python library:

Clone the repository:

git clone https://github.com/Itqan-community/munajjam.git
cd munajjam/munajjam

Install the package:

pip install .

For faster transcription with faster-whisper:

pip install ".[faster-whisper]"

For development (editable install):

pip install -e ".[dev]"

Download a sample audio file (Surah Al-Fatiha):

curl -L -o 001.mp3 "https://pub-9ee413c8af4041c6bd5223d08f5d0f0f.r2.dev/media/uploads/assets/11/recitations/001.mp3"

Note: Audio files should be named by surah number (e.g., 001.mp3, 002.mp3). Browse more recitations at cms.itqan.dev

from munajjam.core import align
from munajjam.data import load_surah_ayahs
from munajjam.transcription import WhisperTranscriber

# Transcribe audio
with WhisperTranscriber() as transcriber:
    segments = transcriber.transcribe("001.mp3")

# Align to ayahs (uses auto strategy by default; override with "greedy", "dp", or "hybrid")
ayahs = load_surah_ayahs(1)
results = align("001.mp3", segments, ayahs)

# Get timestamps
for result in results:
    print(
        f"Ayah {result.ayah.ayah_number}: "
        f"{result.start_time:.2f}s - {result.end_time:.2f}s"
    )

Ayah 1: 5.62s - 9.57s
Ayah 2: 10.51s - 14.72s
Ayah 3: 15.45s - 18.53s
Ayah 4: 19.21s - 22.54s
Ayah 5: 23.27s - 28.19s
Ayah 6: 29.00s - 33.07s
Ayah 7: 33.98s - 46.44s

• API Server - Async FastAPI server for handling concurrent alignment jobs
• Whisper Transcription - Uses faster-whisper as default backend with Quran-tuned models
• Four Alignment Strategies - Auto, Hybrid, DP, and Greedy
• Arabic Text Normalization - Handles diacritics, hamzas, and character variations
• Automatic Drift Correction - Multi-pass zone realignment for long recordings
• Quality Metrics - Confidence scores for each aligned ayah
• Phonetic Similarity - Arabic ASR confusion-aware similarity scoring
• Word-level Precision - Uses per-word timestamps (when available) to improve drift recovery

The default auto strategy works best for most cases. You can override it:

from munajjam.core import Aligner

# Auto (recommended) - picks the best strategy, full pipeline by default
aligner = Aligner("001.mp3")

# Hybrid - DP with greedy fallback (legacy)
aligner = Aligner(
    "001.mp3",  # Audio file path (required)
    strategy="auto",  # "greedy", "dp", "hybrid", or "auto" (default)
    quality_threshold=0.85,  # Similarity threshold for high-quality alignment
    fix_drift=True,  # Run zone realignment for long surahs
    fix_overlaps=True,  # Fix overlapping ayah timings
    min_gap=0.3,  # Minimum gap between consecutive ayahs (seconds)
    energy_snap=True,  # Snap boundaries to energy minima (default True)
)

results = aligner.align(segments, ayahs)

See the examples directory for more usage patterns:

• 01_basic_usage.py - Simple transcription and alignment
• 02_comparing_strategies.py - Compare alignment strategies
• 03_advanced_configuration.py - Custom settings and options
• 04_batch_processing.py - Process multiple files

• Python 3.10+
• PyTorch 2.0+
• FFmpeg (for audio processing)
• Docker & Docker Compose (Optional, for running the API server)

• Website
• ITQAN Community

• Tarteel AI for the Quran-specialized Whisper model

MIT License - see LICENSE for details.