QuranCLI ✨

Your Terminal Companion for the Holy Quran: Read, Listen & Generate Subtitles for Video Editing!

Tip

This project is part of the FadSec Lab suite.
Discover our focus on ad-free, privacy-first applications and stay updated on future releases!

---

QuranCLI brings the Quran to your Windows command line with a rich set of features designed for readers, listeners, and video creators.

🌟 Key Features

• 📖 Complete Quran Access: Read all 114 Surahs with English translation (Simple & Uthmani Arabic scripts)
• 🎧 Audio Recitations: Stream high-quality audio from renowned reciters with full playback controls
• 🎬 Subtitle Generation: Create .srt subtitle files (Arabic + English) for video editing workflows
• 🌐 Built-in Web Server: Share generated subtitle files with devices on the same Wi-Fi network
• 💾 Offline Mode: Smart caching for Quran text and audio with local storage
• 🎨 Customizable Interface: Colorful, responsive terminal UI with theme customization
• 🔄 Auto-Updates: Automatic notifications for new app versions from GitHub
• 📊 Download Statistics: Real-time download counts displayed in the app header
• 🖥️ Cross-Platform: Native support for Windows and Linux operating systems
• ⌨️ Command Line Integration: Launch directly from terminal using the qurancli command
• 🌐 Multi-Language Support: Urdu, Turkish, and English translations with transliteration
• 🔖 Advanced Bookmarks: Comprehensive bookmark system with notes and quick Ayatul Kursi access
• 💾 Data Management: Backup and restore capabilities for settings and data
• 🧩 Linux-Style Commands: Short commands like ls for efficient navigation
• 🎵 Focused Audio Player: Dedicated Ayatul Kursi audio player for spiritual listening
• 🔁 Audio Loop Mode: Continuous playback feature for extended listening sessions
• ⏰ Sleep Timer: Auto-stop functionality after specified time duration
• 📖 Bulk Reading: all command for opening complete Surahs from any starting point
• 📥 Audio Manager: Comprehensive audio management system with download, clear, and path commands
• ⚙️ Translation Settings: Toggle Urdu, English, and Turkish translations in reader mode
• 🔔 Smart Notifications: Toast messages for download completion and error handling
• 🗂️ Organized Settings: Categorized configuration commands in dedicated settings screen

---

🎬 Demo & Screenshots

QuranCLI-theme-command-demo.mp4

Theme command in use

Reading View (Transliteration + en, ur & tr Translations)

Audio Player (with Progress Bar & Controls)

Reciter Selection Menu

Full Surah List (`list` command)

Smart Surah Search (Suggestions for "rehman")

Information / Help Page (`info` command)

Subtitle Management & Sharing (`sub` command)

Subtitle Web Server Interface (Accessible on Local Network)

Bookmark Manager

🚀 Installation

Windows Installer (Recommended)

1. Go to the Releases Page.
2. Download the latest QuranCLI-Setup.exe file.
3. Run the installer and follow the on-screen instructions.
4. Launch QuranCLI from your Start Menu or Desktop shortcut.
   Tip: You can also run the tool directly from the terminal by typing qurancli.

Linux (.deb Package Installation)

1. Go to the Releases Page.
2. Download the latest .deb package, for example: qurancli_1.1.0_amd64.deb.
3. Open a terminal and navigate to the download directory.
4. Install the package with:

   sudo dpkg -i qurancli_1.1.0_amd64.deb

5. If any dependency errors appear, run:

   sudo apt-get install -f

6. Once installed, launch QuranCLI directly by typing:

   qurancli

🔧 Dev Only: Build from Source

• Prerequisites: Python 3.9+ and pip.
• Clone:

  git clone https://github.com/anonfaded/QuranCLI.git
  cd QuranCLI

• Install Dependencies: (Using a virtual environment is recommended)

  # Optional: Create and activate venv
  # python -m venv venv
  # .\venv\Scripts\activate  (Windows) or source venv/bin/activate (Linux/macOS)
  
  pip install -r requirements.txt

• Run:

  python Quran-CLI.py

🔧 Dev Only: Step-by-Step on building the .deb package for Linux

Building the .deb Package

1. Copy Codebase from /mnt/c/ (WSL only)
   Due to the WSL /mnt/c/ structure, copy the whole codebase to the root to match the filesystem as linux would expect:

   cp -r /mnt/c/Users/username/Desktop/QuranCLI /

2. Create the Executable:
   Run PyInstaller (WSL) in the project's directory:

   pyinstaller QuranCLI.spec

3. Convert Line Endings:
   Convert the Debian maintainer scripts to Unix format:

   dos2unix debian/postinst debian/prerm debian/postrm

4. Verify Executable Permissions:
   Ensure the generated executable has the correct executable permissions:

   ls -l dist/QuranCLI

   The permissions should show an x (executable) flag.

5. Build the Debian Package:
   Run the Debian build command in the copied codebase directory (the .deb package will be placed one level up):

   dpkg-buildpackage -us -uc -b

---

🎮 Quick Start & Usage

1. Launch: Start QuranCLI (via Installer or python Quran-CLI.py).
2. Select Surah: Enter the Surah number (1-114) or type part of its name (e.g., rahman).
3. Select Ayahs: Enter the starting and ending Ayah numbers.
4. Read: View Arabic text and English translation. Use n / p to navigate pages.
5. Listen: Type a to open the Audio Player. Use keys like p (play/pause), s (stop), r (change reciter), [ / ] (seek 5s), j / k (seek 30s). Press q to return.
6. Subtitles & Share:
   • Type sub in the main menu.
   • Select Surah and the Ayah range you want subtitles for.
   • The .srt file is saved in Documents\QuranCLI Subtitles.
   • A local web server starts automatically. You'll see a URL like http://<Your-IP>:8000.
   • Open this URL on other devices on the same Wi-Fi to browse and download the subtitle files for that Surah.
   • Use the open command in the subtitle menu to view the folder on your PC, or back to return to the main menu (this also stops the server).
7. Help: Type info in the main menu for detailed commands and credits.
8. Quit: Type quit or exit in the main menu.

(Note: Use the reverse command in the reader if Arabic text appears incorrectly displayed on your specific terminal.)

---

🚀 Upcoming Features Roadmap

• New Reciters: Additional reciter options.
• Tafsir Integration: In-depth explanations for each ayah.
• I'm-Feeling Feature: A mood-based recommendation system that suggests ayahs based on the user's current feelings.

---

🤝 Contributing & Feedback

• Bugs & Feature Requests: Found an issue or have an idea? Please Open an Issue.

• Pull Requests: Contributions are welcome!

🫱🏽‍🫲🏽 Credits

• Quran Data & Audio API: Provided by The Quran Project. An API for the Holy Quran with no rate limit.

• Databases used: https://gist.github.com/raz0229/ad8cb85f6a92c08f7acf50d245524a5f, https://github.com/saikothasan/quran-cloud

📄 License

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