Documentation

Technical reference for QuranBuddy v0.1.0

Overview

QuranBuddy is a cross-platform desktop Quran reader built with Tauri v2 (Rust backend) and Next.js 16 (React 19 frontend). It uses a static site export served inside a Tauri webview with full native integration via IPC commands and events.

The application provides Quran reading with tajweed color coding, audio recitations from 17+ reciters, verse-by-verse and word-by-word audio playback, prayer times with azan notifications, and a distraction-free reading experience.

  • Version: 0.1.0
  • Identifier: com.quran.buddy
  • License: Open Source
  • Window: 1280x800, frameless (custom title bar)

Installation

Download the latest installer for Windows. Choose between the standard setup wizard (.exe) or the package manager format (.msi).

Setup (.exe)

Standard NSIS installer

Windows Installer

Package (.msi)

Microsoft Software Installer

Requirements

  • Windows 10+ (64-bit)
  • ~22 MB free disk space
  • WebView2 Runtime (pre-installed on Windows 11)
  • Internet connection for recitation streaming (optional)

Keyboard Shortcuts

ShortcutActionScope
DToggle dark/light themeGlobal
EscapeClear search / close dropdownSurah reader
Ctrl + KOpen command paletteGlobal

Features

Quran Reader

Full Quran text with Uthmani script, verse-by-verse navigation, tajweed color coding (17 color rules), translations, and word-by-word clickable text for audio playback.

Audio Recitations

17+ reciters including Maher Al Muaiqly, Yasser Al Dossari, Hazza Al-Balushi, and more. Supports verse-by-verse streaming, offline download with progress tracking, word-by-word audio, and play queue with shuffle/repeat.

Prayer Times

Accurate prayer times via Aladhan API (14 calculation methods). Azan notifications, pre-prayer reminders, countdown timer, 3 azan styles (Makkah, Madinah, Egypt), and test notification support.

Customization

Dark/light/system theme, tajweed toggle, translations toggle, configurable reciter, azan style and volume, prayer calculation method, startup on login (Windows), and auto-hiding title bar.

Configuration

Settings are persisted as JSON at %APPDATA%/quranbuddy/config.json on Windows.

FieldTypeDefaultDescription
citystring"Dubai"City for prayer times
countrystring"UAE"Country for prayer times
methodu322Prayer calculation method (ISNA)
themestring"dark"dark / light / system
last_surahu321Last viewed surah
reciter_idu327Default reciter ID
tajweed_enabledboolfalseTajweed color coding
translations_enabledbooltrueVerse translations
prayer_notifications_enabledboolfalsePrayer time alerts
selected_azanstring"Makkah"Azan style
azan_volumef320.5Azan volume (0.0-1.0)
reminders_enabledboolfalsePre-prayer reminders
reminder_minutesu3210Minutes before prayer

Architecture

Rust Backend

The backend is organized into four modules:

  • lib.rsApp setup, 40+ Tauri commands, audio playback via rodio, system tray, and prayer scheduler background task (30-second polling loop).
  • api.rsQuran.com API integration (chapters, verses, audio URLs, search), azan MP3 downloads, and Aladhan prayer times.
  • config.rsJSON-based settings persistence with serde — stored at %APPDATA%/quranbuddy/config.json.
  • main.rsEntry point with Windows console hiding on release builds.

Frontend (Next.js)

  • /Splash page with command palette (cmdk) for quick navigation.
  • /homeChapter grid with download management for each surah.
  • /surah/[id]Full reader with tajweed HTML, word-by-word audio, verse search, and audio player.
  • /settingsAll app settings with persistence via Tauri IPC.
  • /ptimesPrayer times dashboard with live countdown, azan preview, and notification test.

Audio System

A dedicated background thread (rodio) manages azan playback. The frontend uses HTMLAudioElement for verse recitations:

  • Streaming: Direct MP3 URLs from mp3quran.net servers.
  • Offline: Downloaded to $APPDATA/audio/{chapter_id:03d}_{reciter_id}.mp3, served via Tauri's asset:// protocol.
  • Word-by-word: Quran.com API or constructed URLs at https://verses.quran.com/wbw/{chapter:03d}_{verse:03d}_{word:03d}.mp3.
  • Audio output: Supports setSinkId() for device selection when supported.

Prayer Scheduler

The Rust backend runs an async task that checks every 30 seconds for matching prayer times. On match, it sends an OS notification via tauri-plugin-notification and plays the selected azan. Pre-prayer reminders fire at the configured interval. Notifications are deduplicated per prayer per day.

Azan styles: Makkah (Ali Ibn Ahmad Mala), Madinah, Egypt (Abdulbasit Abdusamad).

Tauri Commands

All IPC commands registered in the Rust backend, callable from the frontend via @tauri-apps/api.

Config

  • get_settings — Returns current Config object
  • save_settings(settings) — Persists partial config changes
  • reset_settings — Restores defaults
  • get_config_path — Returns config file path
  • open_config_folder — Opens directory in file manager
  • get_startup_setting / set_startup_setting — Windows auto-start via registry (winreg)

Quran API

  • get_chapters — All 114 surahs from Quran.com API
  • get_recitations — API reciters + 10 custom reciters (IDs 7001-7010)
  • get_chapter_audio(chapter_id, reciter_id) — Audio URL for surah
  • get_verses_by_chapter(chapter_id) — All verses (paginated)
  • get_verses_tajweed(chapter_id) — Tajweed-coded Uthmani text
  • get_verse_words(chapter_id, verse_number) — Word-level audio URLs
  • search_verses(query, page) — Global Quran search

Audio Download

  • download_chapter_audio(chapter_id, reciter_id) — Downloads MP3 with progress events
  • get_chapter_audio_path(chapter_id, reciter_id) — Local file path
  • delete_chapter_audio(chapter_id, reciter_id) — Deletes cached audio
  • get_bulk_chapter_audio_status(reciter_id) — Lists all downloaded chapters

Prayer / Azan

  • get_prayer_times — Fetches from Aladhan API
  • preview_azan(azan_name) — Streams and plays azan preview
  • get_azan_list — Available azan styles
  • trigger_test_notification — Test OS notification + azan

FAQ

Support

QuranBuddy is free and open source. If you encounter issues or have suggestions, reach out:

Enjoying QuranBuddy?

Consider supporting the project to help with development and hosting costs.

Get in touch