The Holy Quran

Listen to the Holy Quran anywhere with multiple reciters, offline playback, and Android Auto integration.

❔ About

The Holy Quran is a modern, open-source Android application that brings the Holy Quran to your fingertips. Built with Kotlin and following modern Android development practices, this app provides a seamless experience for listening to Quranic recitations from multiple renowned reciters. Whether you're at home, commuting, or traveling, The Holy Quran ensures you can access the divine words of Allah ﷻ with ease.

The application is designed with simplicity and user experience in mind, supporting both mobile devices and Android Auto, making it perfect for listening while driving. With offline playback capabilities and an intuitive interface, The Holy Quran serves as your digital companion for spiritual enlightenment.

---

✨ Features

• 🎧 Audio Features

  • Multiple Reciters: Choose from a variety of renowned Quran reciters with different recitation styles
  • Full Chapter Playback: Listen to complete Surahs with high-quality audio
  • Offline Playback: Download chapters for listening without an internet connection
  • Playback Controls: Pause, resume, and seek to specific positions within chapters
  • Background Playback: Continue listening while using other apps

• 🚗 Android Auto Support

  • In-Car Experience: Full integration with Android Auto for safe listening while driving
  • Voice Controls: Control playback using voice commands
  • Car-Optimized UI: Simplified interface designed for automotive displays
  • Focus on Safety: Minimal distraction design compliant with Android Auto guidelines

• 🎨 User Interface

  • Modern Material Design: Clean and intuitive interface following Material Design principles
  • Chapter Browser: Easy navigation through all 114 chapters of the Quran
  • Reciter Selection: Quick access to switch between different reciters
  • Smooth Animations: Polished transitions and interactions throughout the app

• 🌏 Localization & Accessibility

  • Multi-Language Support: App interface available in multiple languages via Crowdin
  • Community Translations: Contribute translations through the Crowdin project
  • Accessible Design: Built with accessibility in mind for all users

• 🧑‍💻 Technical Features

  • Kotlin-Based: Built entirely with modern Kotlin code
  • Modular Architecture: Separated mobile and automotive modules for maintainable codebase
  • Automated Asset Generation: Python scripts for generating app assets during build
  • CI/CD Pipeline: Automated builds and releases via GitHub Actions
  • Quality Assured: Code quality monitored with CodeFactor and Codacy

---

📱 Screenshots

---

📥 Download

You can download the most recent version of The Holy Quran from GitHub Releases.

---

🌍 Localization & Translation

The Holy Quran supports multiple languages and welcomes community contributions for translations.

• How to Contribute Translations

  • Visit the AlQuran Crowdin Project
  • Select your language or request a new one
  • Translate app strings and store descriptions
  • Submit your translations for review

The Holy Quran appreciates all translators that help make The Holy Quran accessible to Muslims worldwide!

---

🚀 Getting Started

• Important

  This project uses automated scripts from the helper-scripts during the gradle build process to generate some of the assets used in the app. To get started, follow these steps:

• Project Prerequisites

  • Android Studio latest stable version
  • JDK v21 or later
  • Android SDK API level 33 or higher
  • uv package manager
  • Python v3.13 or higher
  • Git for version control

• Project Set Up

  • Clone the repository:

    git clone https://github.com/abdalmoniem/AlQuran.git
    cd AlQuran

  • Install Python (If not already installed):

    cd helper-scripts
    uv python install

  • Create and activate a virtual environment (Recommended):

    uv venv .venv
    .\venv\Scripts\activate  # On Windows
    # or
    source .venv/bin/activate  # On Unix/macOS

  • Install dependencies:

    uv sync

  • Open in Android Studio

    • Launch Android Studio
    • Select Open an Existing Project
    • Navigate to the cloned AlQuran directory
    • Click OK and wait for Gradle sync to complete

  • Build the Project

    • From the menu: Build > Make Project
    • Or use the command line:

      ./gradlew build

• Build Variants

  The project includes two build variants:

  • debug: Development build with debugging symbols and additional logging
  • release: Production-ready build optimized for performance and size (requires signing configuration)

  To build a specific variant:

  ./gradlew assembleDebug   # build debug variant
  # or
  ./gradlew assembleRelease # build release variant

---

🏗️ Project Structure

AlQuran/
├─.github/                          # GitHub Actions workflows and configurations
├─.idea/                            # Android Studio project settings
├─assets/                           # App icons, screenshots, and promotional materials
├─automotive/                       # Android Auto module
├─fastlane                          # Fastlane configuration for F-Droid
│   └─metadata                      # F-Droid metadata and descriptions
│       └─android
│           ├─ar
│           │ └─images
│           │   └─phoneScreenshots  # App Screenshots for AR Locale on F-Droid
│           ├─en
│           │ ├─changelogs          # App Changelogs for F-Droid
│           │ └─images
│           │   └─phoneScreenshots  # App Screenshots for AR Locale on F-Droid
│           └─<xx>
│             └─images
│               └─phoneScreenshots  # App Screenshots for XX Locale on F-Droid
├─git_hooks/                        # Git hooks for automated checks
├─gradle/                           # Gradle wrapper files
├─helper-scripts/                   # Python scripts for asset generation
├─mobile/                           # Main Android application module
├─pre-build/                        # Pre-build scripts and configurations
├─shared/                           # Shared code between mobile and automotive modules
├─build.gradle.kts                  # Root Gradle build script (Kotlin DSL)
├─settings.gradle.kts               # Gradle settings (Kotlin DSL)
└─crowdin.yml                       # Crowdin localization configuration

---

🛠️ Tech Stack

• Core Technologies

  • Kotlin: Primary programming language
  • Android SDK: Target API 33+
  • Gradle: Build automation with Kotlin DSL

• Architecture & Patterns

  • Modular Architecture: Separate modules for mobile and automotive
  • MVVM Pattern: Model-View-ViewModel architecture
  • Clean Architecture: Separation of concerns and dependency inversion

• Key Libraries & Tools

  • Media3 / ExoPlayer: Audio playback engine
  • Kotlin Coroutines: Asynchronous programming
  • Android Auto: Car integration
  • Material Design Components: UI components
  • Python Scripts: Automated asset generation
  • Shell Scripts: Build automation

• Development Tools

  • GitHub Actions: CI/CD pipeline
  • CodeFactor: Code quality analysis
  • Codacy: Automated code review
  • Crowdin: Localization management
  • Fastlane: F-Droid Deployment automation

---

🤝 Contributing

Contributions are welcome and appreciated! See the CONTRIBUTING.md file for more information about how to contribute to this project.

---

📜 License

This project is licensed under the GNU General Public License v3.0 (GPL-3.0)

You are free to:

• ✅ Use the software for any purpose
• ✅ Study how it works and modify it
• ✅ Distribute copies
• ✅ Distribute modified versions

Under the following terms:

• 📋 Source code must be made available
• 🔄 Modifications must be released under GPL-3.0
• 📝 Changes must be documented
• ⚖️ Original copyright notices must be preserved

See the LICENSE.md file for the complete license text.

---

🙏 Acknowledgments

• Reciters: All the Quran reciters whose recitations are featured
• Contributors: Everyone who has contributed code, translations, or feedback
• Open Source Community: For the amazing libraries and tools
• Users: For using The Holy Quran and spreading the word

🫂 Special Thanks

• mp3quran for the amazing API
• GitHub Actions for CI/CD infrastructure
• Crowdin for localization platform
• CodeFactor and Codacy for code quality tools
• The Android development community

---

✉️ Contact & Support

• Get Help

  • Issues: Report bugs via GitHub Issues
  • Discussions: Join conversations in GitHub Discussions

• Stay Connected

  • GitHub: @abdalmoniem
  • Repository: AlQuran

• Support the Project

  • ⭐ Star the repository
  • 🍴 Fork and contribute
  • 🐛 Report issues
  • 📢 Share with others
  • 🤲 Keep the project in your prayers

---

📊 Project Stats

---

Made with ❤️ for the Muslim Community

May Allah ﷻ accept this effort and make it beneficial for all Muslims. Ameen.

"The best among you are those who learn the Quran and teach it." - Prophet Muhammad ﷺ