Quran Memorization Tool: Juz Amma Ayah-by-Ayah Muraja'ah

Try it live — The app is hosted on GitHub Pages and the source code is on GitHub. Bismillah!

---

Live Demo

You can try HafalanQuran right here — it’s fully functional embedded below:

---

Why I Built This

Memorizing the Qur’an (hifz) is a journey, but the real challenge is retention — muraja’ah (review). I needed a tool that:

1. Plays one ayah at a time — not the whole surah, just the specific ayah I’m reviewing
2. Supports range repeat — play ayah 1–5 on repeat until I nail them
3. Adjustable speed — 0.5x for difficult passages, 2.0x for quick review
4. Works offline-ready — no login, no account, no server. Open and start.

Most Qur’an apps play full surahs. For muraja’ah, you need granular ayah-level control. That’s exactly what this does.

---

Tech Stack (or Lack Thereof)

This project is deliberately minimal:

Layer	Choice	Why
UI	Vanilla HTML + CSS + JS	Zero dependencies, instant load
Data	Static JSON (juz_amma_arab_id.json)	No API calls at runtime
Audio	Qur’an Foundation CDN (Minshawi Murattal)	Free, high-quality recitation
Storage	localStorage	Persist theme + speed preference
Build	None	Just serve the folder

The entire app lives in a single index.html file (~60KB including inline CSS and JS). The JSON data file contains all 37 surahs of Juz Amma with Arabic text and Indonesian translation.

---

Features

Per-Ayah Playback

Select any surah, choose an ayah range, and hit play. Each ayah highlights as it plays — so you can follow along visually while listening.

Configurable Repeat

Set how many times each ayah repeats before moving to the next. Perfect for drilling difficult passages.

Adjustable Speed

0.5x to 2.0x in 0.25 increments. Start slow, then speed up as your memorization strengthens.

Day/Night Mode

Dark mode by default (easy on the eyes during night muraja’ah sessions), with a warm light mode toggle. Your preference is saved in localStorage.

---

How It Works

The audio pipeline is straightforward:

1. User selects a surah and ayah range
2. App constructs audio URLs pointing to the Qur’an Foundation CDN: verses.quran.foundation/Minshawi/Murattal/mp3/{surah}{ayah}.mp3
3. Audio plays sequentially with configurable repeat per ayah
4. Currently playing ayah gets a visual highlight
5. User can pause/resume at any point

The data flow:

juz_amma_arab_id.json
    ↓
index.html loads JSON
    ↓
Renders surah list + ayah display
    ↓
User picks range → audio plays from CDN
    ↓
Visual highlight syncs with playback

---

What I Learned

Building something with zero frameworks is refreshing. No build step, no bundle size worries, no dependency updates. Just HTML, CSS, and JavaScript working together.

Key takeaways:

• Simplicity wins — For a focused tool like this, vanilla JS is more than enough
• Audio API quirks — HTMLAudioElement doesn’t have a clean “onended” queue, so I built a simple sequential playback manager
• CORS considerations — Remote audio CDN needs to allow cross-origin requests; the Qur’an Foundation CDN handles this well
• localStorage for UX — Persisting theme and speed makes repeated use frictionless

---

Source Code

The project is open source:

• Live App: ab2rahman.github.io/HafalanQur-an
• Source Code: github.com/ab2rahman/HafalanQur-an

Only 4 files in the repo:

HafalanQur-an/
├── index.html                          # The entire app
├── juz_amma_arab_id.json               # Surah data
├── generate_juz_amma_arab_id.js        # Data generator script
└── README.md                           # Documentation

Clone it, serve it with any static file server, and you’re good to go.

---

Possible Improvements

Some ideas for future enhancement:

• Offline support — Cache audio files with Service Worker for true offline muraja’ah
• Progress tracking — Mark surahs/ayahs as mastered and track review history
• More reciters — Support different qari (Husary, Abdul Basit, etc.)
• Full Qur’an — Expand beyond Juz Amma to all 30 juz
• PWA — Make it installable on mobile home screen

---

Check out more of my projects or read about how I built a Flutter AI voice assistant and an interactive Flutter developer roadmap. For more on building with minimal infrastructure, see my community management PWA that runs on Firebase free tier.

Barakallahu feekum — may Allah bless your Qur’an memorization journey. 🤲