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

• 📖 Read Anywhere: Access all 114 Surahs with English translation (Simple & Uthmani Arabic scripts).
• 🎧 Listen: Stream audio recitations from various renowned reciters with full playback controls (play/pause/seek).
• 🎬 Subtitle Generation: Create .srt subtitle files (Arabic + English) for Ayah ranges – perfect for video editing!
• 🌐 Subtitle Sharing: Built-in web server to easily share generated subtitle files with other devices (phone, tablet, other PCs) on the same Wi-Fi network.
• 💾 Smart Caching: Works offline by caching Quran text and audio locally.
• 🎨 Intuitive Interface: Colorful, responsive, and easy-to-navigate terminal UI with custom theme command to customize colors.
• 🔄 App Auto-Updates: Notifies you of new app versions available on GitHub.
• 📊 Stats: See total download counts directly in the header.
• 🖥️ Multi Platform: Available on Windows and Linux platforms.
• ⌨️ Command Alias: Launch the app directly from the terminal using the qurancli command.
• 🌐 Translation & Transliteration: Provides Urdu and English translations along with transliteration.

---

🎬 Demo & Screenshots

QuranCLI-theme-command-demo.mp4

Theme command in use

Reading View (Simple & Uthmani Scripts + Translation)

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)

🚀 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

• Full Quran Transliteration: Complete transliteration of the entire.
• Integrated Urdu Translation: Built-in support for Urdu translations.
• New Reciters: Additional reciter options (e.g., Shiekh Mohammad Al Luhaidan and more).
• 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.

• Application Icon: Holy icon created by Atif Arshad - Flaticon.

📄 License

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