Dugsi — Quran Recitation & Tajweed Trainer

Recite the Quran aloud and get instant, word-by-word feedback on your accuracy and tajweed. A free, open alternative to paid recitation apps — built to be honest about what it can and can't yet verify.

Surahs: Al-Fatiha (1, with full per-word tajweed) and Al-Baqarah (2, 286 verses, practised in short sections). Pick a surah and, for long ones, a verse range to recite. More surahs slot in via the same verified-data pipeline.

---

Free for everyone. No API key, no server, no cost, no tracking. All the word-checking is plain JavaScript that runs client-side, so the app is a static site anyone can host for free. Listening is done by Tarteel's open Quran model, on the device, so the voice stays there. Until the model has downloaded the first time (or where it cannot run, or when switched off), the browser's own speech service stands in — in Chrome that sends the audio to Google, and the app says so on screen.

What it does today

1. Recitation accuracy. You recite into the mic; your voice is cut at your pauses and heard by Tarteel's Quran model on the device (see 17), and each word is laid against the verified Uthmani text by a deterministic follower. Every word is marked correct / nearly / wrong / skipped, or faded not heard when there was voice the model could not make out.

2. One engine, chosen for you. The Quran model when it can run here; otherwise the browser's speech service, said plainly on screen.

3. Acoustic madd-timing. From the model's word timestamps Dugsi flags a six-count madd held for less than half its length (⏱) — e.g. in aḍ-ḍāāāllīn. Two-count madds are not judged: the timestamps are too coarse.

4. Tajweed guide. The surah is rendered with colour-coded tajweed rules (madd, sun/moon letters, leen, lām of Allah, tafkhīm, …) to learn as you read.

5. Listen to the whole Quran, in your Sheikh's voice. A reciter library of 40+ qaris, all Hafs ʿan ʿĀṣim, from Alafasy, Al-Husary, Abdul Basit and Al-Minshawi (murattal, mujawwad and teaching recordings) to the imams of the two Holy Mosques, with search, style and country filters, favourites, recently used, a quality badge from the recording bitrate, a "word highlighting" badge, and portraits from Wikipedia where available. Pick one and press play: Dugsi recites the surah verse by verse and flows straight into the next one, so you can listen to the entire Quran hands-free. It hooks into the phone's Media Session, so the lock-screen and headphone controls (play / pause / skip) work too — handy while driving or with the screen off. Audio streams from the public everyayah.com archive at play time, with the next verse always loaded ahead so nothing breaks between verses or between surahs, and a surah can be saved to the device to play with no network at all. Your chosen Sheikh is remembered on the device and used everywhere audio plays. A few beloved qaris — Sudan's Sheikh Al Zain Mohammad Ahmad among them — were never published ayah by ayah; their recordings exist only as one file per surah, so those come from mp3quran.net instead, with the download server looked up in their public catalogue on your device rather than hardcoded here. Such a Sheikh recites a surah at a time: no word highlighting, and a single tapped verse is read in the default voice.

6. Prayer times for Göteborg + adhan. A dedicated page shows today's times (Fajr, Shuruq, Dhuhr, Asr, Maghrib, Isha) with the next prayer and a live countdown, computed on-device with the Muslim World League method and the "one-seventh of the night" high-latitude rule — the same method as salatgbg.se, so it stays accurate through Sweden's bright summer nights, offline and server-free. A built-in adhan player lets you choose a call-to-prayer recording and listen whenever you like.

7. Vowels too. The Quran model writes the short vowels it hears, so a word with the right letters but a wrong fatha, damma or kasra is marked yellow ("wrong vowel: you said مَالِكُ (damma, the text has kasra)").

8. Live following. While you recite, the green flows along the words you are saying; once a piece is judged, words said right stay green, words said as another turn yellow and skipped words grey; added words are counted in a running tally. It is deliberately conservative (a word is only flagged once a later word clearly matched), a re-read word turns green again, and the full alignment at the end has the final say. Can be switched off under Goals & reminders → Reciting for positive-only marking.

9. Memorisation (Hifz) tools. Three hiding levels; hidden words reveal as you recite them correctly. Stuck? Peek next word or Peek verse (peeks are counted per attempt, so the summary stays honest), or tap any hidden word. Transliteration and translation hide with the words so nothing gives them away. Long surahs can be practised a verse range at a time, with ◀ ▶ to step to the next range.

10. Mistake history. Every word you slip on is saved, with what you said instead. Per surah (with You vs Correct playback) and across all surahs on the progress page, most frequent first, each with a one-tap Practise that opens exactly that verse.

11. Your recordings. Every recitation is recorded on the device. The Recordings tab lists them per surah with playback at 0.75× / 1× / 1.25×, download and delete. Audio never leaves the device.

12. Analytics dashboard (/progress). Current and best streak, minutes recited (today / week / all time), verses covered, score trend, minutes per day against your goal, a 16-week activity calendar, all-time word totals, and per-surah mastery with verses mastered.

13. Goals. Minutes per day, recitations per day, verses per week and verses memorised per month, each with a progress bar. Editable with +/−.

14. Study reminders. A daily reminder at your time (and chosen weekdays): a system notification while Dugsi is open or installed to the home screen, plus an .ics calendar file with a repeating alarm for when it is not — a static site has no push server, and we say so instead of pretending.

15. Bookmarks. Mark any verse while reading; the list on the progress page jumps straight back to it.

16. Local-first, cloud-synced. All of the above works signed out, stored in this browser. Sign in and history, goals, settings and bookmarks sync to the account and merge across devices (each session carries a client id so nothing is counted twice). Recordings stay on the device by design.

17. Installable. A web manifest and a tiny service worker let Dugsi be added to the home screen like an app.

18. Tarteel-style live following, on the device. While you recite, your voice is cut at your pauses and each piece is heard by Tarteel's open whisper-tiny-ar-quran (Apache-2.0) in a background worker — on the graphics chip where the browser allows it — and laid against the text by a deterministic follower (lib/follow). Words turn green, yellow or red a second or two after each pause, and when a verse was not caught and you carry on, the follower finds you in the next one. A stretch where there was voice but the model heard nothing is shown faded and never counted as skipped; only a verse nobody said is. The verdict is ready the moment the last piece is decoded. Without the model (switched off, or it cannot run) the browser's speech service listens instead, as before.

19. Hesitation detection + auto-stop. The same pause detector notes a pause longer than 2.5 s mid-recitation with the word you were stuck before, and can stop the recording after 6 s of silence.

20. Word-by-word qari timings. Word-level timestamps from quran-align (CC BY 4.0) for Alafasy, Al-Husary (Muallim), Ash-Shuraim and Al-Minshawi: words light up as the Sheikh recites them on the Listen page (with 0.75× / 1× / 1.25× speed), and in the mistake review Correct plays just that word in the qari's voice next to You.

21. The real mushaf pages. The Quran is shown as the 604 pages of the printed Madinah mushaf, 15 lines each, every word on the line the King Fahd Complex printed it on (layout generated from the Complex's own typeset document by scripts/build-mushaf-layout.py), set in the Complex's own HAFS Uthmanic typeface so every mark reads as in print. Eight-lobed rosette verse markers (tap one to hear the verse), the surah banner and the basmala sit where the mushaf prints them; the page number follows in the header and /quran?page=N opens any page.

22. One simple design. A warm, old-fashioned book look on every page: cream paper, brown ink, one deep green, big type and big buttons, built so children and elders can follow it. The home page is three steps (pick a surah, pick a Sheikh, then Listen or Recite); the Quran page has one Listen/Recite switch, a docked player or mic, and an Options sheet of plain switches. Recitation colours the letters themselves: green said right, yellow nearly, red wrong, grey skipped; while listening, the word the Sheikh is reciting turns green. Hidden verses in memorisation mode become empty ruled lines with only the markers left. Translation, transliteration and tajweed colouring are plain switches in the Options sheet. Light theme by default, dark under Options → Dark screen.

23. Listening without pauses. For 33 Sheikhs a surah plays as ONE recording (mp3quran.net, with the start of every verse from their documented API): nothing loads between verses, so there is no pause between them on any phone; the verse being recited lights up, ⏮ ⏭ step verse by verse, and repeat cycles this verse / this surah. The next surah is loaded in the last 25 s of the current one. Other Sheikhs play verse by verse, with the next verse fetched into memory ahead (iPhone does not load audio ahead itself). The play button never turns into a spinner. Tap a verse marker: while listening the Sheikh carries on from there; while reciting he reads just that verse, in his own voice. Save this surah to listen without internet keeps the recording in the browser's own cache.

24. Sources & licences page (/about) crediting every text, audio, model and library source; THIRD_PARTY.md has the full review.

The areas each live on their own page — Recitera (/), Lyssna (/listen), Framsteg (/progress) and Bönetider (/prayer) — reached from a slide-out side menu, so the flows never get in each other's way.

Deep links open the reader at a place: /?surah=2&verse=255 scrolls to a verse, /?surah=2&from=1&to=5 practises a range.

Quran text integrity

The Al-Fatiha text is verified two ways in CI (test/quran-integrity.test.ts): a word-by-word comparison against an independent canonical reference, and a pinned SHA-256 checksum of the exact diacritic text. The religious text cannot change silently — any edit fails the build until the checksum is reviewed and updated.

Honest limits

• The Quran model is about 93 % word-accurate on recitation, so it can still slip — a word marked wrong may be the recogniser, not the reciter (tap "You" to hear yourself). Dugsi judges words, not vowel marks.
• Madd-timing is a timestamp heuristic, not a phonetic measurement. It flags obviously rushed elongations; it does not judge makharij or ghunnah quality.
• The model downloads once (about 67 MB) and is slower on older phones without a usable graphics chip; the browser's speech service stands in where it cannot run.
• Always learn tajweed with a qualified teacher. This is a practice aid.

---

Architecture

app/
  page.tsx                 Recite: recorder + surah + tajweed legend
  listen/page.tsx          Listen: full-Quran player + read-along
  progress/page.tsx        Analytics dashboard, mistakes, recordings, goals
  prayer/page.tsx          Prayer times (Göteborg) + adhan
components/
  AppNav.tsx               Slide-out side menu across all pages
  AppServices.tsx          Sign-in sync, service worker, reminder timer
  Reciter.tsx              On-device recognition + live marking + results UI
  QuranTrainer.tsx         Surah picker, verse range, deep links
  VerseRange.tsx           Practise a verse range of a long surah
  SurahView.tsx            Ayah rendering with tajweed colours / result overlay
  BookmarkButton.tsx       Per-verse bookmark toggle
  ProgressPanel.tsx        Compact "today" card on the home page
  ProgressDashboard.tsx    The /progress page (tabs)
  GoalsPanel.tsx           Goal bars + editing
  ReminderSettings.tsx     Notification + calendar reminders
  MistakesPanel.tsx        All-time most-missed words
  RecordingsPanel.tsx      Your recordings: play / download / delete
  SurahMasteryList.tsx     Per-surah mastery + mistake review
  charts/                  Streak calendar, score trend, minutes per day
  ReciterPicker.tsx        Choose which Sheikh (qari) to listen to
  ListenPlayer.tsx         Hands-free full-Quran player (auto-advance + MediaSession)
  ListenView.tsx           The /listen page: pickers + player + read-along
  PrayerView.tsx           Prayer times, next-prayer countdown (client, live)
  AdhanPlayer.tsx          Choose and play a call-to-prayer recording
  PlayButton.tsx           Per-verse listen button (uses the chosen Sheikh)
  Legend.tsx               Tajweed colour key
lib/
  listen/segmenter.ts      Cuts the recitation at the reciter's pauses (also hesitations, auto-stop)
  listen/recite-engine.ts  Mic → pieces → Tarteel's Quran model (worker) → follower
  listen/surah-timing.ts   Whole-surah recordings + verse timings (mp3quran ayat_timing)
  follow/                  The deterministic follower and verdict (tested on real model output)
  memory/weak-spots.ts     How each word goes wrong, put right since, due for review
  quran/timings.ts         Word-level qari timings loader (quran-align data)
  quran/timings/<qari>/    Vendored per-surah timing JSON (CC BY 4.0)
  history.ts               Local-first session history + cloud merge/sync
  settings.ts              Goals, reminder and reciting settings (synced)
  bookmarks.ts             Verse bookmarks (synced, with tombstones)
  reminders.ts             Reminder timer, notifications, .ics export
  live.ts                  Live tracking + mistake detection + sticky merge
  recordings.ts            On-device recordings (IndexedDB), bounded
  audio-quran.ts           Reciter catalogue + per-ayah audio URLs (everyayah.com)
  mp3quran.ts              Whole-surah recitations: server lookup, cached on the device
  listen-engine.ts         Gapless recitation: two players, the next verse always ready
  audio-cache.ts           Saving a surah to the device, and playing it from there
  reciter-store.ts         Shared, persisted "current Sheikh" choice
  prayer-times.ts          On-device prayer times (adhan lib, MWL + 1/7-night)
  adhan-audio.ts           Adhan recording catalogue
  quran/fatiha.ts          Verified text + per-word tajweed metadata
  arabic.ts                Normalisation, tokenisation, similarity
  align.ts                 Needleman–Wunsch word alignment (heard vs expected)
  analyze.ts               Orchestrates alignment + timing + scoring (client-side)
  speech/recognizer.ts     Web Speech API wrapper (Fast engine)
  tajweed/rules.ts         Rule colours + descriptions
  tajweed/timing.ts        Madd-timing engine (Whisper word timestamps)

Recognition + analysis both run in the browser, so the deployed app needs no backend and no secrets. transformers.js is loaded from a CDN at runtime only when High-accuracy mode is chosen, so it never bloats the bundle.

---

Run it locally

npm install
npm run dev      # http://localhost:3000  (no API key needed)

Then open the app in Chrome, tap Start reciting, recite Surah Al-Fatiha, and tap stop. A microphone is the only requirement.

Tests

npm test

Covers Arabic normalisation, word alignment (perfect / skipped / wrong word), live mistake detection, history merging, stats aggregation, reminder scheduling and the .ics file, end-to-end scoring, and Quran text integrity (canonical match + checksum).

Database (accounts)

supabase/schema.sql is idempotent — re-run it in the Supabase SQL editor after pulling. It adds the richer session columns (client_id, seconds, verses, from_verse, to_verse, extra, peeks, hifz), the user_settings table and the bookmarks table. Until it is run the app falls back to the old shape automatically (nothing breaks, sessions just carry less detail in the cloud).

---

Roadmap

• Quran-tuned acoustic model + real phonetic tajweed (makharij, ghunnah, qalqalah) beyond the current madd-timing heuristic.
• Listen-then-recite drill loops per verse (play the qari, recite, auto-check, advance on three clean passes).
• Real push reminders if the project ever gets a (free) backend worker.