zaibihassan/Quranic-Recitation-Data

<p align="center"> <img src="./banner.png" alt="Quranic Recitation Dataset Banner" width="100%"> </p>

<p align="center"> <img src="https://img.shields.io/badge/Audio%20Format-Opus%20(16kHz,%2032kbps)-emerald?style=for-the-badge&logo=opus" alt="Opus Format"> <img src="https://img.shields.io/badge/Total%20Reciters-135-blue?style=for-the-badge" alt="Total Reciters"> <img src="https://img.shields.io/badge/Timing%20Format-Protocol%20Buffers-violet?style=for-the-badge" alt="Protobuf"> <img src="https://img.shields.io/badge/CDN-Cloudflare%20Edge-orange?style=for-the-badge&logo=cloudflare" alt="Cloudflare CDN"> <img src="https://img.shields.io/badge/License-Apache%202.0-green?style=for-the-badge" alt="License"> </p>

🌟 Overview

Quranic Recitation Dataset (Word-by-Word Sync) is a highly optimized, production-ready dataset containing high-quality audio recitations of the Holy Quran synchronized at the word-by-word level.

This dataset features 135 world-renowned reciters, with every Surah (114 chapters) mapped precisely to millisecond-accurate word timestamps. It is designed for modern Islamic mobile and web applications — served via a Cloudflare Edge CDN with native range-request support for instant audio streaming and seeking.

🚀 Key Features

• —135 Reciters × 114 Surahs — totaling 15,390 audio files with matching timing data.
• —Optimized Audio — Mono-channel, 16kHz, 32kbps .opus format. Exceptional clarity at ultra-low bandwidth.
• —Per-Surah Architecture — Each surah is a single .opus file. Seek to any ayah using the timing data — no need to download individual ayah files.
• —Protocol Buffer Timing — Binary .pb timing files are ~33% smaller than JSON and parse instantly in any language.
• —Cloudflare Edge CDN — Files are served from cdn.mualim.app with edge caching, CORS, and native HTTP 206 Partial Content for mobile audio seeking.
• —Word-Level Accuracy — Timestamps map to standard Uthmani script word indices, enabling karaoke-style highlighting.

📡 CDN Access

This dataset is served via a Cloudflare Worker that proxies HuggingFace with aggressive edge caching. You never need to download the 17GB repository locally.

Base URL

https://cdn.mualim.app

URL Format

{BASE_URL}/{slug}/{surah_number}.{opus|pb}

Quick Examples

# Audio — Mishari Rashid Al-Afasy, Surah Al-Fatihah
curl https://cdn.mualim.app/mishari-rashid-al-afasy-murattal/001.opus

# Timing — Same reciter, same surah (Protocol Buffer)
curl https://cdn.mualim.app/mishari-rashid-al-afasy-murattal/001.pb

# Range Request (for mobile seeking)
curl -H "Range: bytes=0-1024" \
  https://cdn.mualim.app/mishari-rashid-al-afasy-murattal/001.opus
# → 206 Partial Content ✅

CDN Features

Direct HuggingFace Fallback

If the CDN is unavailable, you can fetch directly from HuggingFace:

https://huggingface.co/datasets/zaibihassan/Quranic-Recitation-Data/resolve/main/{Folder Name}/{Surah}/{File}

Note: Folder names on HuggingFace contain spaces and special characters (e.g., Mishari Rashid Al Afasy (Murattal)). The CDN slug mapping handles this automatically.

📂 Dataset Structure

The dataset is organized by Reciter Folder → Surah Number (001–114).

Each surah folder contains two files:

1. 1.{surah}.opus — Per-surah audio file (full surah in one file)
2. 2.{surah}.pb — Protocol Buffer word-by-word timing data

Quranic-Recitation-Data/
├── Abdul Basit Abdul Samad (Mujawwad)/
│   ├── 001/
│   │   ├── 001.opus    (Full Surah Al-Fatihah audio)
│   │   └── 001.pb      (Word timestamps for all ayahs)
│   ├── 002/
│   │   ├── 002.opus
│   │   └── 002.pb
│   └── ...
├── Mishari Rashid Al Afasy (Murattal)/
├── Alijon Qari (Murattal)/
└── ...

⏱️ Timing Data Schema (Protocol Buffers)

The .pb timing files map every verse in a surah to word-level timestamps.

Protocol Buffer Schema (recitation.proto)

syntax = "proto3";
package recitation;

message WordSegment {
  int32 word_index_0_based = 1;
  int32 word_index_1_based = 2;
  int32 timestamp_from = 3;      // milliseconds from start of surah
  int32 timestamp_to = 4;        // milliseconds from start of surah
}

message VerseSegments {
  repeated WordSegment segments = 1;
}

message SurahTimestamps {
  map<string, VerseSegments> verses = 1;  // key = "surah:ayah" (e.g., "1:1")
}

How It Works

Each .pb file contains a SurahTimestamps message with all verses of that surah. The timestamps are relative to the start of the surah audio file, so you can:

1. 1.Load the surah .opus audio
2. 2.Decode the .pb timing data
3. 3.To play a specific ayah, seek the audio to verses["1:3"].segments[0].timestamp_from milliseconds
4. 4.Highlight words in real-time as currentTimeMs falls between each segment's timestamp_from and timestamp_to

🔗 CDN Slug Map

The CDN uses URL-friendly slugs that map to the actual folder names on HuggingFace:

📜 Data License & Usage

License: Apache-2.0

This dataset is completely free and open-source for personal, educational, and commercial projects under the Apache License 2.0. You are encouraged to integrate this directly into mobile apps (Flutter, React Native, iOS, Android) and web platforms.

Attribution: While not strictly required by the license, we appreciate attribution linking back to this dataset to support the ongoing development of open-source Islamic infrastructure.