📿 Quran MP3

A beautiful and feature-rich Flutter application for listening to the Holy Quran with multiple reciters, offline support, and a modern Material Design interface.

Listen to the Holy Quran anytime, anywhere with professional-quality audio recitations

---

✨ Features

Core Features

• 🎵 High-quality Quranic audio - Professional Quran recitations from renowned reciters
• 📱 Beautiful UI - Modern Material Design with dynamic colors and smooth animations
• 🌙 Dark mode support - Comfortable viewing in any lighting condition
• 🔖 Bookmarks - Save your favorite Surahs and continue from where you left off
• 📥 Offline listening - Download Surahs and listen without internet
• 👥 Multiple reciters - Choose from various renowned and beautiful Quran reciters

Technical Features

• 🌍 Multi-language support - Available in 18+ languages
• 📊 Data management - Import and export your playlists and bookmarks
• 🆓 Free and open source - No ads, no subscriptions, no premium features
• 🔄 Built-in updater - Stay up-to-date with the latest features
• 🔐 Privacy-focused - All data stored locally on your device
• 🎨 Dynamic Material 3 - Adaptive colors based on system theme

Audio Features

• ⏸️ Full playback controls - Play, pause, skip, previous, repeat modes
• 🔊 Audio session management - Proper handling of audio focus and notifications
• 🎧 Audio quality - Support for high-quality MP3 recitations
• 📍 Resume playback - Remember your listening position

---

📥 Installation

F-Droid (Recommended)

Download from F-Droid

GitHub Releases

Download the latest APK from GitHub Releases

Requirements

• Android 7.0 or higher (API level 24+)
• 100 MB free storage space (more for offline downloads)
• Internet connection for streaming (optional if using offline downloads)

---

🏗️ Tech Stack

Frontend:

• Flutter 3.35.6
• Dart 3.9.2
• Material Design 3

Audio & Backend:

• just_audio - Audio playback
• audio_service - Background audio
• audio_session - Audio session management
• hive - Local database

Other Libraries:

• go_router - Navigation and routing
• sqflite - SQLite database
• file_picker - File selection
• url_launcher - Open external links
• app_links - Deep linking support
• youtube_explode_dart - Video/audio extraction

---

🎯 Permissions

The app requires the following permissions:

• INTERNET - Stream Quran recitations
• WAKE_LOCK - Keep device awake during playback
• FOREGROUND_SERVICE - Background audio playback
• READ_MEDIA_AUDIO - Access local audio files

---

🔧 Build from Source

Prerequisites

• Flutter SDK (3.35.6 or higher)
• Android SDK (API level 36)
• Java JDK 17+
• Git

Steps

1. Clone the repository

   git clone https://github.com/yourusername/quran-mp3.git
   cd quran-mp3

2. Install dependencies

   flutter pub get

3. Build for Android

   # Debug APK
   flutter build apk --debug
   
   # Release APK
   flutter build apk --release

4. Build for F-Droid flavor

   flutter build apk --release -t lib/main_fdroid.dart

---

📁 Project Structure

lib/
├── main.dart              # Application entry point
├── main_fdroid.dart       # F-Droid variant entry point
├── API/                   # API integration
├── DB/                    # Database models
├── models/                # Data models
├── screens/               # UI screens
├── services/              # Business logic
├── style/                 # Theming and styling
├── utilities/             # Helper functions
├── widgets/               # Reusable UI components
└── localization/          # i18n translations (18 languages)

android/
├── app/                   # Android app configuration
└── gradle/                # Build configuration

---

🌍 Localization

Supported languages (18):

• 🇸🇦 Arabic
• 🇬🇧 English
• 🇷🇺 Russian
• 🇩🇪 German
• 🇪🇸 Spanish
• 🇫🇷 French
• 🇮🇹 Italian
• 🇯🇵 Japanese
• 🇵🇱 Polish
• 🇵🇹 Portuguese
• 🇹🇷 Turkish
• 🇺🇦 Ukrainian
• 🇬🇷 Greek
• 🇮🇩 Indonesian
• 🇮🇳 Hindi
• 🇰🇷 Korean
• 🇨🇳 Chinese (Simplified)
• 🇹🇼 Chinese (Traditional)

---

🐛 Bug Reports & Feature Requests

Found a bug or have a feature idea? Please open an issue

Before reporting, please check:

• Android version
• Device information
• Steps to reproduce
• Expected vs actual behavior

---

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

---

📜 License

This project is licensed under the GNU General Public License v3.0 - see the LICENSE file for details.

Key points:

• Free to use and modify
• Must credit original authors
• Must keep source code open
• Can redistribute with same license

---

👏 Acknowledgments

• All Quran reciters for their beautiful recitations
• Flutter and Dart communities
• Open source contributors
• F-Droid team for distribution

---

⚖️ Disclaimer

Quran MP3 is an independent, community-driven application for listening to Quranic audio.

Important:

• All audio content is provided by third-party sources
• We do not own or claim ownership of any Quranic recitations
• This application is for educational and personal use
• All content rights belong to respective copyright holders
• The developers are not affiliated with any religious organization

---

📊 Project Statistics

• Language: Dart/Flutter
• Lines of Code: 10,000+
• Commits: 184+
• Contributors: Open to everyone
• License: GPL v3.0

---

🔗 Links

• GitHub: quran-mp3
• F-Droid: com.null7x.quranmp3
• Package ID: com.null7x.quranmp3
• Minimum API: 24 (Android 7.0)
• Target API: 35 (Android 15)

---

Made with ❤️ by the Quran MP3 community